@spree/dashboard-ui 6.0.0-rc.7 → 6.0.1

package/README.md

@@ -2,7 +2,7 @@
 
 Spree Dashboard design system. Shadcn primitives + headless composed components + design tokens.
 
-> **Developer Preview.** APIs may change between 0.x releases. Docs: [React Dashboard](https://spreecommerce.org/docs/developer/dashboard/overview).
+Docs: [React Dashboard](https://spreecommerce.org/docs/developer/dashboard/overview).
 
 ## What's inside
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@spree/dashboard-ui",
   "license": "MIT",
-  "version": "6.0.0-rc.7",
-  "description": "Spree Dashboard design system — shadcn primitives, headless composed components, and design tokens. Source-only package; consumers compile via their own Vite/Tailwind setup. Developer Preview.",
+  "version": "6.0.1",
+  "description": "Spree Dashboard design system — shadcn primitives, headless composed components, and design tokens. Source-only package; consumers compile via their own Vite/Tailwind setup.",
   "author": "Vendo Connect Inc.",
   "homepage": "https://spreecommerce.org",
   "repository": {
@@ -86,11 +86,17 @@
     "shadcn": "4.22.1",
     "tailwind-merge": "3.7.0",
     "tw-animate-css": "1.4.0",
-    "@spree/core": "^6.0.0-rc.7"
+    "@spree/core": "^6.0.1"
   },
   "devDependencies": {
+    "@tanstack/react-router": "^1.170.45",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "i18next": "^26.5.3",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "react-hook-form": "^7.90.0",
+    "react-i18next": "^17.1.0",
     "tailwindcss": "^4.2.4",
     "typescript": "~7.0.2",
     "vite": "^8.3.4"

package/src/index.ts

@@ -39,6 +39,7 @@ export * from './spree/bulk-price-table'
 export * from './spree/bulk-variants-table'
 export * from './spree/calculator-summary'
 export * from './spree/claim-resolve-dialog'
+export * from './spree/collapsible-card'
 export * from './spree/color-picker'
 export * from './spree/confirm-dialog'
 export * from './spree/copy-to-clipboard-button'
@@ -85,6 +86,7 @@ export * from './spree/row-actions'
 export * from './spree/row-click-bridge'
 export * from './spree/search-input'
 export * from './spree/secret-input'
+export * from './spree/step-icon'
 export * from './spree/storefront-visible-switch'
 export * from './spree/tag-list'
 export * from './spree/tax-identifiers-card'

package/src/spree/collapsible-card.tsx

@@ -0,0 +1,66 @@
+import { type ReactNode, useState } from 'react'
+import { cn } from '../lib/utils'
+import { Badge } from '../ui/badge'
+import { Card, CardContent, CardHeader } from '../ui/card'
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '../ui/collapsible'
+import { ChevronRightIcon } from './icons'
+
+interface CollapsibleCardProps {
+  title: ReactNode
+  icon?: ReactNode
+  /** Shown as a badge beside the title when above zero, so a closed card still says whether it holds anything. */
+  count?: number
+  /** Header controls kept outside the toggle, e.g. an Edit button. */
+  actions?: ReactNode
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  children: ReactNode
+}
+
+/** A secondary card that starts folded to its header, for content most visits don't need. */
+export function CollapsibleCard({
+  title,
+  icon,
+  count = 0,
+  actions,
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  children,
+}: CollapsibleCardProps) {
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen)
+  const isOpen = open ?? uncontrolledOpen
+
+  function setOpen(next: boolean) {
+    if (open === undefined) setUncontrolledOpen(next)
+    onOpenChange?.(next)
+  }
+
+  return (
+    <Card>
+      <Collapsible open={isOpen} onOpenChange={setOpen}>
+        <CardHeader
+          className={cn('flex flex-row items-center gap-2 py-1.5', !isOpen && 'border-b-0')}
+        >
+          <CollapsibleTrigger className="group -mx-1 flex min-w-0 flex-1 cursor-pointer items-center gap-2 rounded-md px-1 py-1 text-left hover:bg-accent/50">
+            <ChevronRightIcon className="size-4 shrink-0 text-muted-foreground transition-transform group-data-[panel-open]:rotate-90 motion-reduce:transition-none" />
+            {/* CardTitle's styling on a span: a button may only hold phrasing content. */}
+            <span
+              data-slot="card-title"
+              className="flex items-center gap-2 text-base font-semibold"
+            >
+              {icon}
+              {title}
+            </span>
+            {count > 0 && <Badge variant="secondary">{count}</Badge>}
+          </CollapsibleTrigger>
+          {actions}
+        </CardHeader>
+        <CollapsibleContent>
+          <CardContent>{children}</CardContent>
+        </CollapsibleContent>
+      </Collapsible>
+    </Card>
+  )
+}

package/src/spree/form-actions.tsx

@@ -39,9 +39,11 @@ export function FormSaveButton<TFieldValues extends FieldValues>({
   return (
     <Button type="submit" disabled={!(isDirty || dirty) || isSubmitting}>
       {isSubmitting && <Loader2Icon className="animate-spin" />}
-      {isSubmitting
-        ? (savingLabel ?? t('admin.actions.saving'))
-        : (label ?? t('admin.actions.save'))}
+      <span>
+        {isSubmitting
+          ? (savingLabel ?? t('admin.actions.saving'))
+          : (label ?? t('admin.actions.save'))}
+      </span>
     </Button>
   )
 }

package/src/spree/icons.ts

@@ -169,6 +169,7 @@ export {
   UsersRoundIcon,
   WarehouseIcon,
   WebhookIcon,
+  WrenchIcon,
   X,
   XCircleIcon,
   XIcon,

package/src/spree/metadata/metadata-card.tsx

@@ -1,46 +1,101 @@
 import { Fragment } from 'react'
-import { Card, CardContent, CardHeader, CardTitle } from '../../ui/card'
 import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from '../../ui/empty'
+import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle } from '../../ui/sheet'
+import { CollapsibleCard } from '../collapsible-card'
+import { CopyToClipboardButton } from '../copy-to-clipboard-button'
 import { BracesIcon } from '../icons'
 
-interface MetadataCardProps {
-  /**
-   * Free-form metadata stored on the record. Read-only — apps and integrations
-   * write to this; admins just see what's there. Always an object (possibly
-   * empty); the API never returns `null`.
-   */
-  metadata: Record<string, unknown>
-  /** Translated copy (passed by the app — this component stays headless). */
-  title: string
+/**
+ * Free-form metadata stored on a record. Read-only — apps and integrations
+ * write to it; admins just see what's there.
+ */
+type Metadata = Record<string, unknown> | null | undefined
+
+/** The keys external systems (ERP, PIM, CRM) know a record by, as `{ system => key }`. */
+type ExternalReferences = Record<string, string> | null | undefined
+
+interface MetadataListProps {
+  metadata: Metadata
+  externalReferences?: ExternalReferences
+  /** Translated copy (passed by the app — these components stay headless). */
   emptyTitle: string
   emptyDescription: string
+  /** Section headings, shown only when the record has both kinds of data. */
+  metadataTitle?: string
+  externalReferencesTitle?: string
+  /** Accessible label for the copy button next to a system's key. */
+  copyLabel?: (system: string) => string
+}
+
+export function hasMetadata(metadata: Metadata): metadata is Record<string, unknown> {
+  return !!metadata && Object.keys(metadata).length > 0
+}
+
+export function hasExternalReferences(
+  externalReferences: ExternalReferences,
+): externalReferences is Record<string, string> {
+  return !!externalReferences && Object.keys(externalReferences).length > 0
 }
 
-export function MetadataCard({ metadata, title, emptyTitle, emptyDescription }: MetadataCardProps) {
-  const entries = Object.entries(metadata)
+export function MetadataList({
+  metadata,
+  externalReferences,
+  emptyTitle,
+  emptyDescription,
+  metadataTitle,
+  externalReferencesTitle,
+  copyLabel,
+}: MetadataListProps) {
+  const showMetadata = hasMetadata(metadata)
+  const showReferences = hasExternalReferences(externalReferences)
+
+  if (!showMetadata && !showReferences) {
+    return (
+      <Empty className="border-0 p-0">
+        <EmptyHeader>
+          <EmptyMedia variant="icon">
+            <BracesIcon />
+          </EmptyMedia>
+          <EmptyTitle>{emptyTitle}</EmptyTitle>
+          <EmptyDescription>{emptyDescription}</EmptyDescription>
+        </EmptyHeader>
+      </Empty>
+    )
+  }
+
+  const both = showMetadata && showReferences
 
   return (
-    <Card>
-      <CardHeader>
-        <CardTitle>
-          <BracesIcon className="size-4" />
-          {title}
-        </CardTitle>
-      </CardHeader>
-      <CardContent>
-        {entries.length === 0 ? (
-          <Empty className="border-0 p-0">
-            <EmptyHeader>
-              <EmptyMedia variant="icon">
-                <BracesIcon />
-              </EmptyMedia>
-              <EmptyTitle>{emptyTitle}</EmptyTitle>
-              <EmptyDescription>{emptyDescription}</EmptyDescription>
-            </EmptyHeader>
-          </Empty>
-        ) : (
+    <div className="flex flex-col gap-4">
+      {showReferences && (
+        <section className="flex flex-col gap-2">
+          {externalReferencesTitle && (
+            <h4 className="text-xs font-medium text-muted-foreground">{externalReferencesTitle}</h4>
+          )}
+          <dl className="grid grid-cols-[minmax(160px,1fr)_2fr] items-center gap-x-4 gap-y-1 text-sm">
+            {Object.entries(externalReferences).map(([system, key]) => (
+              <Fragment key={system}>
+                <dt>
+                  <code className="text-xs text-muted-foreground">{system}</code>
+                </dt>
+                <dd className="flex min-w-0 items-center gap-1 font-mono text-xs text-foreground/90">
+                  <span className="break-all">{key}</span>
+                  {copyLabel && (
+                    <CopyToClipboardButton value={key} aria-label={copyLabel(system)} />
+                  )}
+                </dd>
+              </Fragment>
+            ))}
+          </dl>
+        </section>
+      )}
+      {showMetadata && (
+        <section className="flex flex-col gap-2">
+          {both && metadataTitle && (
+            <h4 className="text-xs font-medium text-muted-foreground">{metadataTitle}</h4>
+          )}
           <dl className="grid grid-cols-[minmax(160px,1fr)_2fr] gap-x-4 gap-y-2 text-sm">
-            {entries.map(([key, value]) => (
+            {Object.entries(metadata).map(([key, value]) => (
               <Fragment key={key}>
                 <dt>
                   <code className="text-xs text-muted-foreground">{key}</code>
@@ -51,9 +106,59 @@ export function MetadataCard({ metadata, title, emptyTitle, emptyDescription }:
               </Fragment>
             ))}
           </dl>
-        )}
-      </CardContent>
-    </Card>
+        </section>
+      )}
+    </div>
+  )
+}
+
+interface MetadataCardProps extends MetadataListProps {
+  title: string
+}
+
+/** Folded by default: metadata is for integrations, and the entry count says whether there is any. */
+export function MetadataCard({ title, ...listProps }: MetadataCardProps) {
+  return (
+    <CollapsibleCard
+      title={title}
+      icon={<BracesIcon className="size-4" />}
+      count={
+        Object.keys(listProps.metadata ?? {}).length +
+        Object.keys(listProps.externalReferences ?? {}).length
+      }
+    >
+      <MetadataList {...listProps} />
+    </CollapsibleCard>
+  )
+}
+
+interface MetadataSheetProps extends MetadataListProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  title: string
+  description?: string
+}
+
+/** Metadata of a record listed inside another page, opened from its row menu. */
+export function MetadataSheet({
+  open,
+  onOpenChange,
+  title,
+  description,
+  ...listProps
+}: MetadataSheetProps) {
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent>
+        <SheetHeader>
+          <SheetTitle>{title}</SheetTitle>
+          {description && <SheetDescription>{description}</SheetDescription>}
+        </SheetHeader>
+        <div className="flex-1 overflow-y-auto p-4">
+          <MetadataList {...listProps} />
+        </div>
+      </SheetContent>
+    </Sheet>
   )
 }
 

package/src/spree/step-icon.tsx

@@ -0,0 +1,74 @@
+import { cn } from '../lib/utils'
+
+const R = 6.5
+const CIRCUMFERENCE = 2 * Math.PI * R
+
+/** Progress through a checklist as a ring that fills green. */
+export function StepProgressRing({
+  value,
+  max,
+  className,
+}: {
+  value: number
+  max: number
+  className?: string
+}) {
+  return (
+    <svg viewBox="0 0 16 16" className={cn('size-4 shrink-0 -rotate-90', className)} aria-hidden>
+      <circle cx="8" cy="8" r={R} fill="none" strokeWidth="1.5" className="stroke-border" />
+      <circle
+        cx="8"
+        cy="8"
+        r={R}
+        fill="none"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeDasharray={CIRCUMFERENCE}
+        strokeDashoffset={CIRCUMFERENCE * (1 - value / (max || 1))}
+        className="stroke-success"
+      />
+    </svg>
+  )
+}
+
+export type StepStatus = 'done' | 'in_progress' | 'todo'
+
+/**
+ * A checklist step's state: a green check once done, a dashed blue ring while
+ * it is started but waiting on someone else (such as a review), and a plain
+ * ring before it is started.
+ */
+export function StepIcon({ status, className }: { status: StepStatus; className?: string }) {
+  const classes = cn('size-4 shrink-0', className)
+
+  if (status === 'done') {
+    return (
+      <svg viewBox="0 0 16 16" className={classes} aria-hidden>
+        <circle cx="8" cy="8" r="7.5" className="fill-success" />
+        <path
+          d="M5 8.2 7 10.2 11 6"
+          fill="none"
+          stroke="white"
+          strokeWidth="1.75"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+      </svg>
+    )
+  }
+
+  return (
+    <svg viewBox="0 0 16 16" className={classes} aria-hidden>
+      <circle
+        cx="8"
+        cy="8"
+        r={R}
+        fill="none"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeDasharray={status === 'in_progress' ? '2.5 2.6' : undefined}
+        className={status === 'in_progress' ? 'stroke-blue-500' : 'stroke-border'}
+      />
+    </svg>
+  )
+}

package/src/styles.css

@@ -450,8 +450,8 @@
   --radius-sm: 0.4rem;
   --radius-md: 0.5rem;
   --radius-lg: 0.625rem;
-  --radius-xl: 0.875rem;
-  --radius-2xl: 1.125rem;
+  --radius-xl: 0.75rem;
+  --radius-2xl: 1rem;
 
   /* Sidebar + header tokens */
   --spacing-sidebar-width: 240px;

package/src/ui/badge.tsx

@@ -188,6 +188,15 @@ const statusToneMap: Record<string, StatusTone> = {
   // same green/red the rest of the app uses saves them parsing the word.
   true: 'success',
   false: 'destructive',
+  // Maintenance task runs: amber while a worker holds or is about to release
+  // the run, blue while it waits for one.
+  enqueued: 'info',
+  running: 'warning',
+  interrupted: 'info',
+  cancelling: 'warning',
+  cancelled: 'destructive',
+  succeeded: 'success',
+  errored: 'destructive',
 } satisfies Record<BuiltInStatus, StatusTone> & Record<string, StatusTone>
 
 // Dot fills, by tone. These read the same `--status-*` ramps the tinted Badge

package/src/ui/dropdown-menu.tsx

@@ -160,19 +160,23 @@ function DropdownMenuCheckboxItem({
       data-slot="dropdown-menu-checkbox-item"
       data-inset={inset}
       className={cn(
-        "relative flex cursor-pointer items-center gap-3 rounded-lg py-1.5 pr-8 pl-2.5 text-sm outline-hidden select-none transition-colors duration-75 focus:bg-accent focus:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "group/checkbox-item relative flex cursor-pointer items-center gap-2.5 rounded-lg py-1.5 pr-2.5 pl-2.5 text-sm outline-hidden select-none transition-colors duration-75 focus:bg-accent focus:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
         className,
       )}
       checked={checked}
       onCheckedChange={onCheckedChange ? (checked) => onCheckedChange(checked) : undefined}
       {...props}
     >
+      {/* Drawn rather than a <Checkbox>: the item is already the checkbox to
+          assistive technology, and a second control inside it would be read
+          twice. Styled to match <Checkbox> so a menu and a table agree. */}
       <span
-        className="pointer-events-none absolute right-2 flex items-center justify-center"
+        aria-hidden
         data-slot="dropdown-menu-checkbox-item-indicator"
+        className="pointer-events-none flex size-4 shrink-0 items-center justify-center rounded-[4px] border border-border bg-card text-white shadow-xs transition-colors duration-100 group-data-[checked]/checkbox-item:border-blue-500 group-data-[checked]/checkbox-item:bg-blue-500"
       >
         <MenuPrimitive.CheckboxItemIndicator keepMounted={false}>
-          <CheckIcon />
+          <CheckIcon className="size-3.5" />
         </MenuPrimitive.CheckboxItemIndicator>
       </span>
       {children}

package/src/ui/field.tsx

@@ -94,7 +94,7 @@ function FieldLabel({ className, ...props }: React.ComponentProps<typeof Label>)
     <Label
       data-slot="field-label"
       className={cn(
-        'group/field-label peer/field-label flex w-fit gap-2 leading-snug group-data-[disabled=true]/field:opacity-50 has-data-checked:border-blue-500/30 has-data-checked:bg-blue-500/5 has-[>[data-slot=field]]:rounded-lg has-[>[data-slot=field]]:border *:data-[slot=field]:p-2.5 dark:has-data-checked:border-blue-500/20 dark:has-data-checked:bg-blue-500/10',
+        'group/field-label peer/field-label flex w-fit gap-2 leading-snug group-data-[disabled=true]/field:opacity-50 has-data-checked:border-blue-100 has-data-checked:bg-blue-50 has-[>[data-slot=field]]:rounded-lg has-[>[data-slot=field]]:border *:data-[slot=field]:p-2.5 dark:has-data-checked:border-blue-500/20 dark:has-data-checked:bg-blue-500/10',
         // Card-shaped labels (the ones wrapping a whole `Field`) are clickable
         // targets, so they need the affordance a bare text label doesn't:
         // a pointer and a hover tint. Scoped by `has-[>[data-slot=field]]` so

package/src/ui/tabs.tsx

@@ -41,7 +41,17 @@ function TabsList({
   )
 }
 
-function TabsTrigger({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.Tab>) {
+/**
+ * A tab. Pass `count` to append a tally — the number of steps outstanding, or
+ * of records in the panel — which is what tells an operator whether a tab is
+ * worth opening before they open it.
+ */
+function TabsTrigger({
+  className,
+  children,
+  count,
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.Tab> & { count?: number }) {
   return (
     <TabsPrimitive.Tab
       data-slot="tabs-trigger"
@@ -67,7 +77,12 @@ function TabsTrigger({ className, ...props }: React.ComponentProps<typeof TabsPr
         className,
       )}
       {...props}
-    />
+    >
+      {children}
+      {count !== undefined && (
+        <span className="rounded-full bg-muted px-1.5 py-0.5 text-xs tabular-nums">{count}</span>
+      )}
+    </TabsPrimitive.Tab>
   )
 }