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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Added JSON preview option to Admin SPA (#13979)
Damian Legawiec5d3e461f3198
diff --git a/packages/admin/package.json b/packages/admin/package.jsonindex 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.tsxindex 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.tsxindex 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.tsxnew file mode 100644index 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.tsxindex 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?: ReactNodeonDelete?: () => 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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.lengthconst 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.tsxindex 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.tsxindex 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.yamlindex 5a49554a5d..eb330d0fd9 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -54,6 +54,9 @@ importers:'@tiptap/starter-kit':specifier: ^3.22.5version: 3.22.5+ '@uiw/react-json-view':+ specifier: ^1.12+ version: 1.12.2(@babel/[email protected])([email protected]([email protected]))([email protected])class-variance-authority:specifier: ^0.7.1version: 0.7.1@@ -1573,6 +1576,13 @@ packages:'@types/[email protected]':resolution: {integrity: sha512-lrpDziQipxCEeK5kWxvljWYhUvOiB2A9izZd9B2AFarYAkqZshb4lPbRs7zKEic6eGtH8V/2qJW+dPp9OtF6bw==}+ '@uiw/[email protected]':+ 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]': {}+ '@uiw/[email protected](@babel/[email protected])([email protected]([email protected]))([email protected])':+ dependencies:+ '@babel/runtime': 7.29.2+ react: 19.2.5+ react-dom: 19.2.5([email protected])+'@vitejs/[email protected]([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]))':dependencies:'@rolldown/pluginutils': 1.0.0-rc.7