Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Added JSON preview option to Admin SPA (#13979)

Damian Legawiec5d3e461f3198
diff --git a/packages/admin/package.json b/packages/admin/package.json
index c6883795d8..0b577221ee 100644
--- a/packages/admin/package.json
+++ b/packages/admin/package.json
@@ -24,6 +24,7 @@
"@tiptap/extension-placeholder": "^3.22.5",
"@tiptap/react": "^3.22.5",
"@tiptap/starter-kit": "^3.22.5",
+ "@uiw/react-json-view": "^1.12",
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
"date-fns": "^4.1.0",
diff --git a/packages/admin/src/components/app-sidebar.tsx b/packages/admin/src/components/app-sidebar.tsx
index 536cb8f5bb..301c42e05a 100644
--- a/packages/admin/src/components/app-sidebar.tsx
+++ b/packages/admin/src/components/app-sidebar.tsx
@@ -1,93 +1,31 @@
import { useParams } from '@tanstack/react-router'
-import {
- BarChart3Icon,
- HomeIcon,
- InboxIcon,
- type LucideIcon,
- PackageIcon,
- SettingsIcon,
- TagIcon,
- UsersIcon,
-} from 'lucide-react'
+import { PackageIcon } from 'lucide-react'
import type { ComponentProps } from 'react'
-import { NavMain } from '@/components/nav-main'
+import { type NavItem, NavMain } from '@/components/nav-main'
import { NavUser } from '@/components/nav-user'
import { StoreSwitcher } from '@/components/store-switcher'
import { Sidebar, SidebarContent, SidebarFooter, SidebarHeader } from '@/components/ui/sidebar'
-import { Subject, type SubjectName } from '@/lib/permissions'
+import { type NavEntry, useNavEntries } from '@/lib/nav-registry'
import { type Permissions, usePermissions } from '@/providers/permission-provider'
-export type NavItem = {
- title: string
- url: string
- icon: LucideIcon
- /** CanCanCan subject required to see this item. If omitted, item is always visible. */
- subject?: SubjectName
- items?: { title: string; url: string; subject?: SubjectName }[]
-}
-
-function buildNavigation(storeId: string): NavItem[] {
- const p = `/${storeId}`
- return [
- {
- title: 'Home',
- url: p,
- icon: HomeIcon,
- },
- {
- title: 'Orders',
- url: `${p}/orders`,
- icon: InboxIcon,
- subject: Subject.Order,
- items: [{ title: 'Draft Orders', url: `${p}/orders/drafts`, subject: Subject.Order }],
- },
- {
- title: 'Products',
- url: `${p}/products`,
- icon: PackageIcon,
- subject: Subject.Product,
- items: [
- { title: 'Price Lists', url: `${p}/products/price-lists`, subject: Subject.Product },
- { title: 'Stock', url: `${p}/products/stock`, subject: Subject.StockLocation },
- { title: 'Categories', url: `${p}/products/categories`, subject: Subject.Taxon },
- { title: 'Options', url: `${p}/products/options`, subject: Subject.OptionType },
- ],
- },
- {
- title: 'Customers',
- url: `${p}/customers`,
- icon: UsersIcon,
- subject: Subject.Customer,
- },
- {
- title: 'Promotions',
- url: `${p}/promotions`,
- icon: TagIcon,
- subject: Subject.Promotion,
- items: [
- { title: 'Gift Cards', url: `${p}/promotions/gift-cards`, subject: Subject.Promotion },
- ],
- },
- {
- title: 'Reports',
- url: `${p}/reports`,
- icon: BarChart3Icon,
- },
- ]
-}
+import '@/nav/default'
-function buildBottomNavigation(storeId: string): NavItem[] {
- return [
- {
- title: 'Settings',
- url: `/${storeId}/settings`,
- icon: SettingsIcon,
- subject: Subject.Store,
- },
- ]
+function entryToNavItem(entry: NavEntry, storeId: string): NavItem {
+ const pathFor = (path: string) => (path === '/' ? `/${storeId}` : `/${storeId}${path}`)
+ return {
+ title: entry.label,
+ url: pathFor(entry.path),
+ icon: entry.icon ?? PackageIcon,
+ subject: entry.subject,
+ items: entry.children?.map((child) => ({
+ title: child.label,
+ url: pathFor(child.path),
+ subject: child.subject,
+ })),
+ }
}
-/** Filter nav items by permission: hide items the user can't `read`. */
+/** Hide items the user can't `read`. */
function filterByPermissions(items: NavItem[], permissions: Permissions): NavItem[] {
return items
.filter((item) => !item.subject || permissions.can('read', item.subject))
@@ -101,9 +39,16 @@ export function AppSidebar(props: ComponentProps<typeof Sidebar>) {
const { storeId } = useParams({ strict: false }) as { storeId?: string }
const { permissions } = usePermissions()
const id = storeId || 'default'
+ const { main, bottom } = useNavEntries()
- const navItems = filterByPermissions(buildNavigation(id), permissions)
- const bottomItems = filterByPermissions(buildBottomNavigation(id), permissions)
+ const navItems = filterByPermissions(
+ main.map((e) => entryToNavItem(e, id)),
+ permissions,
+ )
+ const bottomItems = filterByPermissions(
+ bottom.map((e) => entryToNavItem(e, id)),
+ permissions,
+ )
return (
<Sidebar collapsible="icon" {...props}>
diff --git a/packages/admin/src/components/nav-main.tsx b/packages/admin/src/components/nav-main.tsx
index 7ea01bed14..d50035f3cf 100644
--- a/packages/admin/src/components/nav-main.tsx
+++ b/packages/admin/src/components/nav-main.tsx
@@ -1,6 +1,6 @@
import { Link, useRouterState } from '@tanstack/react-router'
+import type { LucideIcon } from 'lucide-react'
import { useState } from 'react'
-import type { NavItem } from '@/components/app-sidebar'
import {
DropdownMenu,
DropdownMenuContent,
@@ -17,6 +17,16 @@ import {
SidebarMenuSubItem,
useSidebar,
} from '@/components/ui/sidebar'
+import type { SubjectName } from '@/lib/permissions'
+
+export type NavItem = {
+ title: string
+ url: string
+ icon: LucideIcon
+ /** CanCanCan subject required to see this item. If omitted, item is always visible. */
+ subject?: SubjectName
+ items?: { title: string; url: string; subject?: SubjectName }[]
+}
function NavIcon({ icon: Icon, isActive }: { icon: NavItem['icon']; isActive?: boolean }) {
return (
diff --git a/packages/admin/src/components/spree/json-preview-drawer.tsx b/packages/admin/src/components/spree/json-preview-drawer.tsx
new file mode 100644
index 0000000000..5e9debd0ee
--- /dev/null
+++ b/packages/admin/src/components/spree/json-preview-drawer.tsx
@@ -0,0 +1,286 @@
+import { useQuery } from '@tanstack/react-query'
+import { Link } from '@tanstack/react-router'
+import JsonView from '@uiw/react-json-view'
+import { vscodeTheme } from '@uiw/react-json-view/vscode'
+import {
+ CheckIcon,
+ ChevronDownIcon,
+ ChevronRightIcon,
+ CopyIcon,
+ ExternalLinkIcon,
+ Loader2Icon,
+ RotateCcwIcon,
+ XIcon,
+} from 'lucide-react'
+import type { ComponentProps } from 'react'
+import { useMemo, useState } from 'react'
+import { Button } from '@/components/ui/button'
+import {
+ Sheet,
+ SheetContent,
+ SheetDescription,
+ SheetHeader,
+ SheetTitle,
+} from '@/components/ui/sheet'
+import { useCopyToClipboard } from '@/hooks/use-copy-to-clipboard'
+import { cn } from '@/lib/utils'
+
+const PREFIX_DESTINATIONS: Record<string, { route: string; param: string }> = {
+ or: { route: '/$storeId/orders/$orderId', param: 'orderId' },
+ prod: { route: '/$storeId/products/$productId', param: 'productId' },
+ cus: { route: '/$storeId/customers/$customerId', param: 'customerId' },
+}
+
+const PREFIXED_ID_RE = /^([a-z]+(?:_[a-z]+)*)_([A-Za-z0-9]{6,})$/
+
+function parsePrefixedId(value: unknown): { route: string; param: string } | null {
+ if (typeof value !== 'string') return null
+ const match = PREFIXED_ID_RE.exec(value)
+ return match ? (PREFIX_DESTINATIONS[match[1]] ?? null) : null
+}
+
+const VALUE_TYPE_STYLES: Record<string, { color: string; format: (v: unknown) => string }> = {
+ string: { color: 'text-emerald-300', format: (v) => `"${v}"` },
+ number: { color: 'text-amber-300', format: String },
+ bigint: { color: 'text-amber-300', format: String },
+ boolean: { color: 'text-purple-300', format: String },
+}
+
+export interface JsonPreviewDrawerProps {
+ open: boolean
+ onOpenChange: (open: boolean) => void
+ /** Display title shown in the drawer header. Default "JSON". */
+ title?: string
+ /**
+ * React-Query key for the fetch. Each open refetches (`staleTime: 0`) — the
+ * drawer is a debug tool, so it always shows the latest server state.
+ */
+ queryKey: readonly unknown[]
+ /** Fetcher that returns the resource JSON. Called inside `useQuery`. */
+ queryFn: () => Promise<unknown>
+ /**
+ * Resource path the JSON came from, e.g. `'/api/v3/admin/orders/or_xyz'`.
+ * Shown in the toolbar and used as the "Open raw" target.
+ */
+ endpoint?: string
+ /** Store ID for prefixed-ID links to other admin pages. */
+ storeId: string
+}
+
+export function JsonPreviewDrawer({
+ open,
+ onOpenChange,
+ title = 'JSON',
+ queryKey,
+ queryFn,
+ endpoint,
+ storeId,
+}: JsonPreviewDrawerProps) {
+ const { data, isLoading, isFetching, error, refetch } = useQuery({
+ queryKey,
+ queryFn,
+ enabled: open,
+ staleTime: 0,
+ })
+
+ const [collapsed, setCollapsed] = useState<boolean | number>(2)
+ const { copied: copiedAll, copy } = useCopyToClipboard()
+
+ const formatted = useMemo(() => (data ? JSON.stringify(data, null, 2) : ''), [data])
+
+ return (
+ <Sheet open={open} onOpenChange={onOpenChange}>
+ <SheetContent
+ side="right"
+ showCloseButton={false}
+ className="w-full sm:max-w-2xl bg-zinc-950 text-zinc-100 border-zinc-800 overflow-hidden"
+ >
+ <SheetHeader className="border-b border-zinc-800 bg-zinc-950 text-zinc-100 rounded-t-xl">
+ <SheetTitle className="text-zinc-100 font-mono text-base">{title}</SheetTitle>
+ {endpoint && (
+ <SheetDescription className="text-zinc-400 font-mono text-xs">
+ GET {endpoint}
+ </SheetDescription>
+ )}
+ <ToolbarButton
+ size="icon-xs"
+ className="absolute top-3 right-3"
+ onClick={() => onOpenChange(false)}
+ aria-label="Close"
+ >
+ <XIcon className="size-4" />
+ </ToolbarButton>
+ </SheetHeader>
+
+ <div className="flex items-center gap-1 border-b border-zinc-800 px-3 py-2 text-xs">
+ <ToolbarButton
+ size="icon-xs"
+ onClick={() => setCollapsed(false)}
+ aria-label="Expand all"
+ title="Expand all"
+ >
+ <ChevronDownIcon className="size-4" />
+ </ToolbarButton>
+ <ToolbarButton
+ size="icon-xs"
+ onClick={() => setCollapsed(true)}
+ aria-label="Collapse all"
+ title="Collapse all"
+ >
+ <ChevronRightIcon className="size-4" />
+ </ToolbarButton>
+ <DepthControl value={collapsed} onChange={setCollapsed} />
+
+ <span className="ml-auto inline-flex items-center gap-1">
+ <ToolbarButton size="xs" onClick={() => formatted && copy(formatted)} disabled={!data}>
+ {copiedAll ? <CheckIcon className="size-3.5" /> : <CopyIcon className="size-3.5" />}
+ {copiedAll ? 'Copied' : 'Copy all'}
+ </ToolbarButton>
+ <ToolbarButton
+ size="icon-xs"
+ onClick={() => refetch()}
+ aria-label="Refetch"
+ title="Refetch"
+ disabled={isFetching}
+ >
+ {isFetching ? (
+ <Loader2Icon className="size-3.5 animate-spin" />
+ ) : (
+ <RotateCcwIcon className="size-3.5" />
+ )}
+ </ToolbarButton>
+ {endpoint && (
+ <a
+ href={endpoint}
+ target="_blank"
+ rel="noreferrer noopener"
+ className="inline-flex items-center gap-1 rounded-md px-2 py-1 text-zinc-400 hover:bg-zinc-800 hover:text-zinc-100 transition-colors"
+ title="Open raw response"
+ >
+ <ExternalLinkIcon className="size-3.5" />
+ Raw
+ </a>
+ )}
+ </span>
+ </div>
+
+ <div className="flex-1 overflow-auto p-4 font-mono text-sm">
+ {isLoading ? (
+ <p className="text-zinc-500">Loading…</p>
+ ) : error ? (
+ <p className="text-red-400">
+ Failed to load: {error instanceof Error ? error.message : String(error)}
+ </p>
+ ) : data ? (
+ <JsonView
+ value={data as object}
+ style={vscodeTheme}
+ collapsed={collapsed}
+ displayDataTypes={false}
+ displayObjectSize
+ enableClipboard
+ shortenTextAfterLength={60}
+ components={{
+ value: ({ value, type, ...rest }) => (
+ <ValueRenderer value={value} type={type} storeId={storeId} {...rest} />
+ ),
+ }}
+ />
+ ) : null}
+ </div>
+ </SheetContent>
+ </Sheet>
+ )
+}
+
+function ToolbarButton({ className, ...props }: ComponentProps<typeof Button>) {
+ return (
+ <Button
+ type="button"
+ variant="ghost"
+ className={cn('text-zinc-400 hover:bg-zinc-800 hover:text-zinc-100', className)}
+ {...props}
+ />
+ )
+}
+
+function DepthControl({
+ value,
+ onChange,
+}: {
+ value: boolean | number
+ onChange: (next: boolean | number) => void
+}) {
+ const current = typeof value === 'number' ? `${value}` : value === true ? 'all' : 'open'
+ return (
+ <select
+ value={current}
+ onChange={(e) => {
+ const v = e.target.value
+ if (v === 'all') onChange(true)
+ else if (v === 'open') onChange(false)
+ else onChange(Number(v))
+ }}
+ className="ml-1 bg-zinc-900 border border-zinc-700 rounded px-1.5 py-1 text-xs text-zinc-300 hover:bg-zinc-800 focus:outline-none focus:ring-1 focus:ring-zinc-600"
+ title="Collapse depth"
+ >
+ <option value="open">Expand all</option>
+ <option value="1">Depth 1</option>
+ <option value="2">Depth 2</option>
+ <option value="3">Depth 3</option>
+ <option value="all">Collapse all</option>
+ </select>
+ )
+}
+
+interface ValueRendererProps {
+ value: unknown
+ type: string
+ storeId: string
+}
+
+function ValueRenderer({
+ value,
+ type,
+ storeId,
+ ...rest
+}: ValueRendererProps & React.HTMLAttributes<HTMLSpanElement>) {
+ if (type === 'string') {
+ const parsed = parsePrefixedId(value)
+ if (parsed) {
+ return (
+ <span {...rest} className="text-emerald-300">
+ "
+ <Link
+ to={parsed.route}
+ params={{ storeId, [parsed.param]: value as string }}
+ className="text-emerald-300 underline decoration-emerald-700 hover:decoration-emerald-300 transition-colors"
+ onClick={(e) => e.stopPropagation()}
+ >
+ {String(value)}
+ </Link>
+ "
+ </span>
+ )
+ }
+ }
+ return <JsonValueSpan value={value} type={type} {...rest} />
+}
+
+function JsonValueSpan({
+ value,
+ type,
+ ...rest
+}: {
+ value: unknown
+ type: string
+} & React.HTMLAttributes<HTMLSpanElement>) {
+ const style = value === null ? null : VALUE_TYPE_STYLES[type]
+ const color = value === null ? 'text-zinc-500' : (style?.color ?? 'text-zinc-300')
+ const display = value === null ? 'null' : style ? style.format(value) : String(value)
+ return (
+ <span {...rest} className={color}>
+ {display}
+ </span>
+ )
+}
diff --git a/packages/admin/src/components/spree/page-header.tsx b/packages/admin/src/components/spree/page-header.tsx
index 019a194fd1..a1eac3dee0 100644
--- a/packages/admin/src/components/spree/page-header.tsx
+++ b/packages/admin/src/components/spree/page-header.tsx
@@ -1,7 +1,9 @@
-import { CheckIcon, CopyIcon, EllipsisVerticalIcon, TrashIcon } from 'lucide-react'
-import { type ReactNode, useState } from 'react'
+import { useParams } from '@tanstack/react-router'
+import { BracesIcon, CheckIcon, CopyIcon, EllipsisVerticalIcon, TrashIcon } from 'lucide-react'
+import { lazy, type ReactNode, Suspense, useState } from 'react'
import { BackButton } from '@/components/back-button'
import { useConfirm } from '@/components/confirm-dialog'
+import type { JsonPreviewDrawerProps } from '@/components/spree/json-preview-drawer'
import { Slot } from '@/components/spree/slot'
import { Button } from '@/components/ui/button'
import {
@@ -11,6 +13,20 @@ import {
DropdownMenuSeparator,
DropdownMenuTrigger,
} from '@/components/ui/dropdown-menu'
+import { useCopyToClipboard } from '@/hooks/use-copy-to-clipboard'
+
+// JSON drawer is a developer-only feature; pulling its tree (which includes
+// @uiw/react-json-view at ~30KB gzip) into the route bundle is wasteful.
+// Lazy-load on first open so the chunk only ships to admins who use it.
+const JsonPreviewDrawer = lazy(() =>
+ import('@/components/spree/json-preview-drawer').then((m) => ({ default: m.JsonPreviewDrawer })),
+)
+
+/** Subset of `JsonPreviewDrawerProps` callers supply; PageHeader provides storeId + open state. */
+export type PageHeaderJsonPreview = Pick<
+ JsonPreviewDrawerProps,
+ 'title' | 'queryKey' | 'queryFn' | 'endpoint'
+>
/**
* Resource-shaped value PageHeader inspects to wire the more-actions dropdown.
@@ -56,6 +72,11 @@ interface PageHeaderProps {
onDelete?: () => void | Promise<void>
/** Override the destructive label ("Delete order", "Delete product", etc.). */
deleteLabel?: string
+ /**
+ * When supplied, the more-actions dropdown gains a "View as JSON" item that
+ * opens a developer-style drawer with the resource payload.
+ */
+ jsonPreview?: PageHeaderJsonPreview
}
/**
@@ -78,9 +99,20 @@ export function PageHeader({
slotContext,
onDelete,
deleteLabel = 'Delete',
+ jsonPreview,
}: PageHeaderProps) {
const slotCtx = { ...slotContext, resource }
- const showDropdown = Boolean(resource || onDelete || dropdownItems)
+ const showDropdown = Boolean(resource || onDelete || dropdownItems || jsonPreview)
+ const [jsonOpen, setJsonOpen] = useState(false)
+ // Latches true on first open so the drawer (and its lazy JsonView chunk)
+ // doesn't mount until the user actually invokes it, but stays mounted
+ // afterwards so the close animation plays.
+ const [jsonEverOpened, setJsonEverOpened] = useState(false)
+ const openJson = () => {
+ setJsonEverOpened(true)
+ setJsonOpen(true)
+ }
+ const { storeId } = useParams({ strict: false }) as { storeId?: string }
return (
<header className="flex items-start gap-3">
@@ -102,9 +134,21 @@ export function PageHeader({
dropdownItems={dropdownItems}
onDelete={onDelete}
deleteLabel={deleteLabel}
+ onOpenJson={jsonPreview && storeId ? openJson : undefined}
/>
)}
</div>
+
+ {jsonPreview && storeId && jsonEverOpened && (
+ <Suspense fallback={null}>
+ <JsonPreviewDrawer
+ open={jsonOpen}
+ onOpenChange={setJsonOpen}
+ storeId={storeId}
+ {...jsonPreview}
+ />
+ </Suspense>
+ )}
</header>
)
}
@@ -119,6 +163,7 @@ interface PageActionsDropdownProps {
dropdownItems?: ReactNode
onDelete?: () => void | Promise<void>
deleteLabel: string
+ onOpenJson?: () => void
}
function PageActionsDropdown({
@@ -127,6 +172,7 @@ function PageActionsDropdown({
dropdownItems,
onDelete,
deleteLabel,
+ onOpenJson,
}: PageActionsDropdownProps) {
const confirm = useConfirm()
@@ -141,6 +187,12 @@ function PageActionsDropdown({
{dropdownItems}
<Slot name="page.actions_dropdown" context={slotContext} />
+ {onOpenJson && (
+ <DropdownMenuItem onClick={onOpenJson}>
+ <BracesIcon className="size-4" />
+ View as JSON
+ </DropdownMenuItem>
+ )}
{resource?.number && <CopyToClipboardItem label="Copy number" value={resource.number} />}
{resource && <CopyToClipboardItem label="Copy ID" value={resource.id} />}
@@ -176,21 +228,15 @@ function PageActionsDropdown({
// ---------------------------------------------------------------------------
function CopyToClipboardItem({ label, value }: { label: string; value: string }) {
- const [copied, setCopied] = useState(false)
+ const { copied, copy } = useCopyToClipboard()
return (
<DropdownMenuItem
// Keep the menu open after click so the user sees the confirmation flash.
closeOnClick={false}
- onClick={async (e) => {
+ onClick={(e) => {
e.preventDefault()
- try {
- await navigator.clipboard.writeText(value)
- setCopied(true)
- setTimeout(() => setCopied(false), 1200)
- } catch {
- // Clipboard API can fail in insecure contexts; ignore silently.
- }
+ copy(value)
}}
>
{copied ? <CheckIcon className="size-4" /> : <CopyIcon className="size-4" />}
diff --git a/packages/admin/src/hooks/use-copy-to-clipboard.ts b/packages/admin/src/hooks/use-copy-to-clipboard.ts
new file mode 100644
index 0000000000..1102fdc7ea
--- /dev/null
+++ b/packages/admin/src/hooks/use-copy-to-clipboard.ts
@@ -0,0 +1,44 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+interface UseCopyToClipboardOptions {
+ /** Reset `copied` back to false after this many ms. Default 1200. */
+ resetMs?: number
+}
+
+/**
+ * Wraps `navigator.clipboard.writeText` with a `copied` flag that flashes true
+ * for `resetMs` after a successful copy. Failure (insecure context, denied
+ * permissions) is swallowed; the flag stays false.
+ *
+ * The reset timer is cleared on unmount so the component doesn't try to
+ * `setState` after it's gone.
+ */
+export function useCopyToClipboard({ resetMs = 1200 }: UseCopyToClipboardOptions = {}) {
+ const [copied, setCopied] = useState(false)
+ const timerRef = useRef<number | null>(null)
+
+ useEffect(() => {
+ return () => {
+ if (timerRef.current !== null) clearTimeout(timerRef.current)
+ }
+ }, [])
+
+ const copy = useCallback(
+ async (value: string) => {
+ try {
+ await navigator.clipboard.writeText(value)
+ setCopied(true)
+ if (timerRef.current !== null) clearTimeout(timerRef.current)
+ timerRef.current = window.setTimeout(() => {
+ setCopied(false)
+ timerRef.current = null
+ }, resetMs)
+ } catch {
+ // Clipboard API can fail in insecure contexts; ignore silently.
+ }
+ },
+ [resetMs],
+ )
+
+ return { copied, copy }
+}
diff --git a/packages/admin/src/lib/nav-registry.ts b/packages/admin/src/lib/nav-registry.ts
new file mode 100644
index 0000000000..371a19ec18
--- /dev/null
+++ b/packages/admin/src/lib/nav-registry.ts
@@ -0,0 +1,152 @@
+import type { LucideIcon } from 'lucide-react'
+import { useSyncExternalStore } from 'react'
+import type { SubjectName } from '@/lib/permissions'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type NavSection = 'main' | 'bottom'
+
+export interface NavEntry {
+ /** Stable identifier — used for register/remove/update and as the React key. */
+ key: string
+ /** Visible label. */
+ label: string
+ /**
+ * Path template, prefixed with `/$storeId` at render time. Pass paths like
+ * `'/orders'`, NOT `/store_abc/orders`. The leading slash is required.
+ */
+ path: string
+ /** Sidebar icon (top-level entries only — subitems don't render icons). */
+ icon?: LucideIcon
+ /** Section. Defaults to `'main'`. `'bottom'` pins to the sidebar footer. */
+ section?: NavSection
+ /** Lower numbers render first. Built-ins use 100/200/300… so plugins can slot in between. */
+ position?: number
+ /** CanCanCan subject required to see this item. Omit for always-visible. */
+ subject?: SubjectName
+ /** Nested children. Children inherit nothing — they declare their own subject + position. */
+ children?: NavEntry[]
+}
+
+interface NavMutator {
+ add(entry: NavEntry): void
+ remove(key: string): void
+ update(key: string, patch: Partial<Omit<NavEntry, 'key'>>): void
+ /** Insert a new entry immediately before `targetKey`. Throws if the target is missing. */
+ insertBefore(targetKey: string, entry: NavEntry): void
+ /** Insert a new entry immediately after `targetKey`. Throws if the target is missing. */
+ insertAfter(targetKey: string, entry: NavEntry): void
+}
+
+// ============================================================================
+// Registry — module-singleton
+// ============================================================================
+
+const entries: NavEntry[] = []
+const listeners = new Set<() => void>()
+let snapshotCache: { main: NavEntry[]; bottom: NavEntry[] } | null = null
+
+function notify() {
+ snapshotCache = null
+ for (const l of listeners) l()
+}
+
+function findIndex(key: string): number {
+ return entries.findIndex((e) => e.key === key)
+}
+
+function ensureUniqueKey(key: string) {
+ if (entries.some((e) => e.key === key)) {
+ throw new Error(`Nav entry "${key}" already registered. Use nav.update() instead.`)
+ }
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export const nav: NavMutator = {
+ add(entry) {
+ ensureUniqueKey(entry.key)
+ entries.push(entry)
+ notify()
+ },
+ remove(key) {
+ const i = findIndex(key)
+ if (i === -1) return
+ entries.splice(i, 1)
+ notify()
+ },
+ update(key, patch) {
+ const e = entries.find((x) => x.key === key)
+ if (!e) throw new Error(`Nav entry "${key}" not found.`)
+ Object.assign(e, patch)
+ notify()
+ },
+ insertBefore(targetKey, entry) {
+ const i = findIndex(targetKey)
+ if (i === -1) throw new Error(`Nav entry "${targetKey}" not found.`)
+ ensureUniqueKey(entry.key)
+ // Inherit target's position so the relative order survives `getNavEntries`'s sort.
+ const target = entries[i]
+ const adjusted: NavEntry = {
+ ...entry,
+ position: entry.position ?? (target.position ?? 100) - 1,
+ }
+ entries.splice(i, 0, adjusted)
+ notify()
+ },
+ insertAfter(targetKey, entry) {
+ const i = findIndex(targetKey)
+ if (i === -1) throw new Error(`Nav entry "${targetKey}" not found.`)
+ ensureUniqueKey(entry.key)
+ const target = entries[i]
+ const adjusted: NavEntry = {
+ ...entry,
+ position: entry.position ?? (target.position ?? 100) + 1,
+ }
+ entries.splice(i + 1, 0, adjusted)
+ notify()
+ },
+}
+
+function subscribe(listener: () => void): () => void {
+ listeners.add(listener)
+ return () => {
+ listeners.delete(listener)
+ }
+}
+
+function buildSnapshot(): { main: NavEntry[]; bottom: NavEntry[] } {
+ const sortRecursively = (list: NavEntry[]): NavEntry[] =>
+ [...list]
+ .sort((a, b) => (a.position ?? 100) - (b.position ?? 100))
+ .map((e) => (e.children ? { ...e, children: sortRecursively(e.children) } : e))
+
+ return {
+ main: sortRecursively(entries.filter((e) => (e.section ?? 'main') === 'main')),
+ bottom: sortRecursively(entries.filter((e) => e.section === 'bottom')),
+ }
+}
+
+function getSnapshot() {
+ if (!snapshotCache) snapshotCache = buildSnapshot()
+ return snapshotCache
+}
+
+/**
+ * Subscribe to nav-registry updates and read the sorted entries. Mirrors
+ * `useSlotEntries` from slot-registry.ts. Re-renders only when the registry
+ * is mutated; navigations don't trigger updates.
+ */
+export function useNavEntries() {
+ return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}
+
+/** Test-only: clear the registry. Not exported from the package index. */
+export function __resetNavRegistry(): void {
+ entries.length = 0
+ notify()
+}
diff --git a/packages/admin/src/nav/default.ts b/packages/admin/src/nav/default.ts
new file mode 100644
index 0000000000..d3564728a3
--- /dev/null
+++ b/packages/admin/src/nav/default.ts
@@ -0,0 +1,121 @@
+import {
+ BarChart3Icon,
+ HomeIcon,
+ InboxIcon,
+ PackageIcon,
+ SettingsIcon,
+ TagIcon,
+ UsersIcon,
+} from 'lucide-react'
+import { nav } from '@/lib/nav-registry'
+import { Subject } from '@/lib/permissions'
+
+nav.add({
+ key: 'home',
+ label: 'Home',
+ path: '/',
+ icon: HomeIcon,
+ position: 100,
+})
+
+nav.add({
+ key: 'orders',
+ label: 'Orders',
+ path: '/orders',
+ icon: InboxIcon,
+ subject: Subject.Order,
+ position: 200,
+ children: [
+ {
+ key: 'orders.drafts',
+ label: 'Draft Orders',
+ path: '/orders/drafts',
+ subject: Subject.Order,
+ position: 100,
+ },
+ ],
+})
+
+nav.add({
+ key: 'products',
+ label: 'Products',
+ path: '/products',
+ icon: PackageIcon,
+ subject: Subject.Product,
+ position: 300,
+ children: [
+ {
+ key: 'products.price-lists',
+ label: 'Price Lists',
+ path: '/products/price-lists',
+ subject: Subject.Product,
+ position: 100,
+ },
+ {
+ key: 'products.stock',
+ label: 'Stock',
+ path: '/products/stock',
+ subject: Subject.StockLocation,
+ position: 200,
+ },
+ {
+ key: 'products.categories',
+ label: 'Categories',
+ path: '/products/categories',
+ subject: Subject.Taxon,
+ position: 300,
+ },
+ {
+ key: 'products.options',
+ label: 'Options',
+ path: '/products/options',
+ subject: Subject.OptionType,
+ position: 400,
+ },
+ ],
+})
+
+nav.add({
+ key: 'customers',
+ label: 'Customers',
+ path: '/customers',
+ icon: UsersIcon,
+ subject: Subject.Customer,
+ position: 400,
+})
+
+nav.add({
+ key: 'promotions',
+ label: 'Promotions',
+ path: '/promotions',
+ icon: TagIcon,
+ subject: Subject.Promotion,
+ position: 500,
+ children: [
+ {
+ key: 'promotions.gift-cards',
+ label: 'Gift Cards',
+ path: '/promotions/gift-cards',
+ subject: Subject.Promotion,
+ position: 100,
+ },
+ ],
+})
+
+nav.add({
+ key: 'reports',
+ label: 'Reports',
+ path: '/reports',
+ icon: BarChart3Icon,
+ position: 600,
+})
+
+nav.add({
+ key: 'settings',
+ label: 'Settings',
+ path: '/settings',
+ icon: SettingsIcon,
+ subject: Subject.Store,
+ section: 'bottom',
+ position: 100,
+})
diff --git a/packages/admin/src/routes/_authenticated/$storeId/customers/$customerId.tsx b/packages/admin/src/routes/_authenticated/$storeId/customers/$customerId.tsx
index b1130ebf69..acf17afaaf 100644
--- a/packages/admin/src/routes/_authenticated/$storeId/customers/$customerId.tsx
+++ b/packages/admin/src/routes/_authenticated/$storeId/customers/$customerId.tsx
@@ -13,8 +13,9 @@ import {
import { type FormEvent, useState } from 'react'
import { adminClient } from '@/client'
import { AddressFormDialog, type AddressParams } from '@/components/address-form-dialog'
-import { BackButton } from '@/components/back-button'
import { useConfirm } from '@/components/confirm-dialog'
+import { PageHeader } from '@/components/spree/page-header'
+import { ResourceLayout } from '@/components/spree/resource-layout'
import { ErrorState } from '@/components/spree/route-error-boundary'
import { TagCombobox } from '@/components/tag-combobox'
import { Badge, StatusBadge } from '@/components/ui/badge'
@@ -82,27 +83,7 @@ function CustomerDetailPage() {
)
}
- const defaultShipping = customer.addresses?.find((a) => a.is_default_shipping)
- const location = [defaultShipping?.city, defaultShipping?.country_iso].filter(Boolean).join(', ')
-
- return (
- <div className="flex flex-col gap-6">
- <div className="flex items-center gap-3">
- <BackButton fallback="customers" />
- <h1 className="text-2xl font-medium">{customer.full_name}</h1>
- {location && (
- <span className="text-base font-normal text-muted-foreground">{location}</span>
- )}
- {customer.tags?.map((tag) => (
- <Badge key={tag}>{tag}</Badge>
- ))}
- </div>
-
- <LifetimeStatsCard customer={customer} />
-
- <CustomerBody customer={customer} />
- </div>
- )
+ return <CustomerBody customer={customer} />
}
function CustomerBody({ customer }: { customer: Customer }) {
@@ -111,25 +92,49 @@ function CustomerBody({ customer }: { customer: Customer }) {
const totalCount = data?.meta?.count ?? orders.length
const lastCompletedOrder = orders.find((o) => o.status === 'complete')
+ const defaultShipping = customer.addresses?.find((a) => a.is_default_shipping)
+ const location = [defaultShipping?.city, defaultShipping?.country_iso].filter(Boolean).join(', ')
+
return (
- <div className="grid grid-cols-12 gap-6">
- <div className="col-span-12 lg:col-span-8 flex flex-col gap-6">
- {lastCompletedOrder && <LastOrderCard order={lastCompletedOrder} />}
- <OrdersCard
- customer={customer}
- orders={orders}
- totalCount={totalCount}
- isLoading={isLoading}
- />
- <StoreCreditsCard customer={customer} />
- </div>
-
- <div className="col-span-12 lg:col-span-4 flex flex-col gap-6">
- <ProfileCard customer={customer} />
- <AddressesCard customer={customer} />
- <InternalNoteCard customer={customer} />
- </div>
- </div>
+ <ResourceLayout
+ header={
+ <>
+ <PageHeader
+ title={customer.full_name ?? customer.email}
+ subtitle={location || undefined}
+ backTo="customers"
+ badges={customer.tags?.map((tag) => <Badge key={tag}>{tag}</Badge>)}
+ resource={{ id: customer.id }}
+ jsonPreview={{
+ title: `Customer ${customer.email}`,
+ queryKey: ['json', 'customer', customer.id],
+ queryFn: () => adminClient.customers.get(customer.id),
+ endpoint: `/api/v3/admin/customers/${customer.id}`,
+ }}
+ />
+ <LifetimeStatsCard customer={customer} />
+ </>
+ }
+ main={
+ <>
+ {lastCompletedOrder && <LastOrderCard order={lastCompletedOrder} />}
+ <OrdersCard
+ customer={customer}
+ orders={orders}
+ totalCount={totalCount}
+ isLoading={isLoading}
+ />
+ <StoreCreditsCard customer={customer} />
+ </>
+ }
+ sidebar={
+ <>
+ <ProfileCard customer={customer} />
+ <AddressesCard customer={customer} />
+ <InternalNoteCard customer={customer} />
+ </>
+ }
+ />
)
}
diff --git a/packages/admin/src/routes/_authenticated/$storeId/orders/$orderId.tsx b/packages/admin/src/routes/_authenticated/$storeId/orders/$orderId.tsx
index 98524d9500..daa5a61ccc 100644
--- a/packages/admin/src/routes/_authenticated/$storeId/orders/$orderId.tsx
+++ b/packages/admin/src/routes/_authenticated/$storeId/orders/$orderId.tsx
@@ -284,6 +284,12 @@ function OrderHeader({ order }: { order: Order }) {
badges={badges}
dropdownItems={dropdownItems}
resource={{ id: order.id, number: order.number }}
+ jsonPreview={{
+ title: `Order ${order.number}`,
+ queryKey: ['json', 'order', orderId],
+ queryFn: () => adminClient.orders.get(orderId),
+ endpoint: `/api/v3/admin/orders/${orderId}`,
+ }}
/>
)
}
diff --git a/packages/admin/src/routes/_authenticated/$storeId/products/$productId.tsx b/packages/admin/src/routes/_authenticated/$storeId/products/$productId.tsx
index d5284d7675..82b3b39619 100644
--- a/packages/admin/src/routes/_authenticated/$storeId/products/$productId.tsx
+++ b/packages/admin/src/routes/_authenticated/$storeId/products/$productId.tsx
@@ -19,6 +19,7 @@ import { ImagePlusIcon, Loader2Icon, SaveIcon, XIcon } from 'lucide-react'
import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
import { Controller, type UseFormReturn, useForm } from 'react-hook-form'
import { toast } from 'sonner'
+import { adminClient } from '@/client'
import { useConfirm } from '@/components/confirm-dialog'
import { PageHeader } from '@/components/spree/page-header'
import { ResourceLayout } from '@/components/spree/resource-layout'
@@ -212,6 +213,12 @@ function ProductForm({ product }: { product: Product }) {
resource={{ id: product.id }}
onDelete={handleDelete}
deleteLabel="Delete product"
+ jsonPreview={{
+ title: `Product ${product.name}`,
+ queryKey: ['json', 'product', productId],
+ queryFn: () => adminClient.products.get(productId),
+ endpoint: `/api/v3/admin/products/${productId}`,
+ }}
/>
}
main={
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5a49554a5d..eb330d0fd9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -54,6 +54,9 @@ importers:
'@tiptap/starter-kit':
specifier: ^3.22.5
version: 3.22.5
+ '@uiw/react-json-view':
+ specifier: ^1.12
class-variance-authority:
specifier: ^0.7.1
version: 0.7.1
@@ -1573,6 +1576,13 @@ packages:
resolution: {integrity: sha512-lrpDziQipxCEeK5kWxvljWYhUvOiB2A9izZd9B2AFarYAkqZshb4lPbRs7zKEic6eGtH8V/2qJW+dPp9OtF6bw==}
+ resolution: {integrity: sha512-IrL7tqPMgPMgdpjsgfArUepVE37DHlgcmkNgUQ92uNcRbO2+iUHXWysNc9nNsJB6ctb+wIinI5JNRqsqwHER5g==}
+ peerDependencies:
+ '@babel/runtime': '>=7.10.0'
+ react: '>=18.0.0'
+ react-dom: '>=18.0.0'
+
'@vitejs/[email protected]':
resolution: {integrity: sha512-l9X/E3cDb+xY3SWzlG1MOGt2usfEHGMNIaegaUGFsLkb3RCn/k8/TOXBcab+OndDI4TBtktT8/9BwwW8Vi9KUQ==}
engines: {node: ^20.19.0 || >=22.12.0}
@@ -4912,6 +4922,12 @@ snapshots:
'@types/[email protected]': {}
+ dependencies:
+ '@babel/runtime': 7.29.2
+ react: 19.2.5
+ react-dom: 19.2.5([email protected])
+
dependencies:
'@rolldown/pluginutils': 1.0.0-rc.7