@spree/dashboard-ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vendo Connect Inc., Vendo Sp. z o.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @spree/dashboard-ui
+
+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).
+
+## What's inside
+
+- `src/ui/` — shadcn primitives (Button, Input, Dialog, Sheet, Table, …). Copy-paste owned: fork into your own project as needed.
+- `src/spree/` — composed components built on the primitives (PageHeader, ResourceTable, AppSidebar, …). **All headless: data and callbacks come in via props.** No provider imports, no hook calls, no SDK access.
+- `src/styles.css` — design tokens + Tailwind theme. Import once from your Vite app.
+- `src/lib/` — generic helpers (`cn`, formatters, …).
+
+The headless rule is what makes the components composable from outside `@spree/dashboard` — a plugin author, an app developer building a vendor panel, or a third-party using just `@spree/dashboard-ui` can all instantiate the same components with their own data sources.
+
+## Source-only package
+
+This package ships **TypeScript source**, not a compiled bundle. Consumers compile it through their own Vite + Tailwind setup. This is required because Tailwind v4 scans source files in the consuming app for utility classes; a pre-compiled CSS bundle would miss classes only used by source-imported components. The `spreeDashboardPlugin` from `@spree/dashboard-core/vite` wires the scanning up for you.
+
+## Peer dependencies
+
+The consuming app provides `react`, `react-dom`, `@tanstack/react-router`, `@tanstack/react-hotkeys`, `react-hook-form`, `i18next`, and `react-i18next` — see `peerDependencies` in `package.json` for the exact ranges.
+
+## What's NOT here
+
+Anything that needs a provider (auth, store, theme), a TanStack Query hook, or the Admin SDK lives in `@spree/dashboard-core`. The split is: **dashboard-ui is the design system, dashboard-core is the framework**.

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@spree/dashboard-ui",
+  "license": "MIT",
+  "version": "0.1.0",
+  "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.",
+  "author": "Vendo Connect Inc.",
+  "homepage": "https://spreecommerce.org",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/spree/spree.git",
+    "directory": "packages/dashboard-ui"
+  },
+  "keywords": [
+    "spree",
+    "commerce",
+    "ecommerce",
+    "admin",
+    "dashboard",
+    "react"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./styles.css": "./src/styles.css",
+    "./ui/*": "./src/ui/*.tsx",
+    "./spree/*": "./src/spree/*.tsx",
+    "./lib/*": "./src/lib/*.ts",
+    "./hooks/*": "./src/hooks/*.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@tanstack/react-hotkeys": "^0.10.0",
+    "@tanstack/react-router": "^1.169.2",
+    "i18next": "^26.2.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "react-hook-form": "^7.75.0",
+    "react-i18next": "^17.0.8"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.4.1",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@fontsource-variable/geist": "^5.2.8",
+    "@fontsource-variable/geist-mono": "^5.2.7",
+    "@tanstack/react-table": "^8.21.3",
+    "@tiptap/extension-link": "^3.22.5",
+    "@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",
+    "cmdk": "^1.1.1",
+    "date-fns": "^4.1.0",
+    "date-fns-tz": "^3.2.0",
+    "flag-icons": "^7.5.0",
+    "lucide-react": "^1.14.0",
+    "react-colorful": "^5.7.0",
+    "react-day-picker": "^9.14.0",
+    "recharts": "^3.8.1",
+    "shadcn": "^4.7.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.5.0",
+    "tw-animate-css": "^1.4.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "~6.0.3"
+  },
+  "scripts": {
+    "lint": "biome check src",
+    "lint:fix": "biome check --fix src",
+    "format": "biome format --write src",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/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 }
+}

package/src/hooks/use-mobile.ts

@@ -0,0 +1,19 @@
+import * as React from 'react'
+
+const MOBILE_BREAKPOINT = 768
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    }
+    mql.addEventListener('change', onChange)
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    return () => mql.removeEventListener('change', onChange)
+  }, [])
+
+  return !!isMobile
+}

package/src/hooks/use-scrolled.ts

@@ -0,0 +1,30 @@
+import * as React from 'react'
+
+/**
+ * Returns true once the document has been scrolled past `threshold` pixels
+ * from the top, false at rest. Used to fade in subtle elevation on sticky
+ * headers, top bars, etc. so they don't look heavy when nothing is scrolled
+ * behind them.
+ *
+ * Listens passively to `window` scroll. Default threshold is 4px to avoid
+ * flickering at the boundary on devices that report fractional scroll
+ * positions. Initial value is computed synchronously on mount so the first
+ * paint matches the actual scroll position (e.g., after browser scroll
+ * restoration on navigation).
+ */
+export function useScrolled(threshold = 4) {
+  // Always start `false` so a future SSR render and the first client paint
+  // agree (no hydration mismatch). The effect below resyncs against the
+  // actual scroll position on mount, so any restored scroll position is
+  // reflected as soon as the effect runs.
+  const [scrolled, setScrolled] = React.useState(false)
+
+  React.useEffect(() => {
+    const onScroll = () => setScrolled(window.scrollY > threshold)
+    onScroll()
+    window.addEventListener('scroll', onScroll, { passive: true })
+    return () => window.removeEventListener('scroll', onScroll)
+  }, [threshold])
+
+  return scrolled
+}

package/src/index.ts

@@ -0,0 +1,99 @@
+// @spree/dashboard-ui — Spree Dashboard design system.
+//
+// Shadcn primitives + headless composed components + design tokens.
+// Consumers import flat from this barrel:
+//
+//     import { Button, Card, PageHeader } from '@spree/dashboard-ui'
+//
+// Or import a specific file (for forking, lazy-loading, or to skip the barrel):
+//
+//     import { Button } from '@spree/dashboard-ui/ui/button'
+//
+// CSS lives at `@spree/dashboard-ui/styles.css` — import once from your Vite app.
+
+export * from './hooks/use-copy-to-clipboard'
+export { useIsMobile } from './hooks/use-mobile'
+export * from './hooks/use-scrolled'
+// ---------------------------------------------------------------------------
+// Helpers + hooks
+// ---------------------------------------------------------------------------
+export { cn } from './lib/utils'
+export { requiredMessage } from './lib/validation-messages'
+// ---------------------------------------------------------------------------
+// Spree composed components — headless, accept data via props
+// ---------------------------------------------------------------------------
+export * from './spree/address-block'
+export * from './spree/back-button'
+export * from './spree/bulk-dialog'
+export * from './spree/bulk-price-table'
+export * from './spree/calculator-summary'
+export * from './spree/color-picker'
+export * from './spree/confirm-dialog'
+export * from './spree/copy-to-clipboard-button'
+export * from './spree/country-flag'
+export * from './spree/data-grid'
+export * from './spree/drag-handle'
+export * from './spree/form-actions'
+
+// JsonPreviewDrawer and JsonValueView are intentionally NOT re-exported from
+// this barrel: they pull in `@uiw/react-json-view` (~30KB gzip), and
+// code-splitting only works when consumers can deep-import via
+// `@spree/dashboard-ui/spree/json-preview-drawer` and
+// `@spree/dashboard-ui/spree/json-value-view`. Types are available the same
+// way — `import { type JsonPreviewDrawerProps } from '@spree/dashboard-ui/spree/json-preview-drawer'`.
+
+export * from './spree/language-menu-items'
+export * from './spree/metadata/metadata-card'
+export * from './spree/relative-time'
+export * from './spree/resource-combobox'
+export * from './spree/resource-layout'
+export * from './spree/resource-multi-autocomplete'
+export * from './spree/resource-name-cell'
+export * from './spree/route-error-boundary'
+export * from './spree/row-actions'
+export * from './spree/row-click-bridge'
+export * from './spree/secret-input'
+export * from './spree/storefront-visible-switch'
+export * from './spree/tag-list'
+export * from './spree/theme-provider'
+export * from './spree/theme-toggle'
+// ---------------------------------------------------------------------------
+// UI primitives (shadcn) — see ./ui/*
+// ---------------------------------------------------------------------------
+export * from './ui/attachment'
+export * from './ui/avatar'
+export * from './ui/badge'
+export * from './ui/breadcrumb'
+export * from './ui/button'
+export * from './ui/calendar'
+export * from './ui/card'
+export * from './ui/chart'
+export * from './ui/checkbox'
+export * from './ui/collapsible'
+export * from './ui/combobox'
+export * from './ui/command'
+export * from './ui/data-table'
+export * from './ui/date-picker'
+export * from './ui/date-range-picker'
+export * from './ui/dialog'
+export * from './ui/dropdown-menu'
+export * from './ui/empty'
+export * from './ui/field'
+export * from './ui/input'
+export * from './ui/input-group'
+export * from './ui/label'
+export * from './ui/pagination'
+export * from './ui/popover'
+export * from './ui/progress'
+export * from './ui/radio-group'
+export * from './ui/rich-text-editor'
+export * from './ui/select'
+export * from './ui/separator'
+export * from './ui/sheet'
+export * from './ui/sidebar'
+export * from './ui/skeleton'
+export * from './ui/slot'
+export * from './ui/sonner'
+export * from './ui/switch'
+export * from './ui/textarea'
+export * from './ui/tooltip'

package/src/lib/date-locale.ts

@@ -0,0 +1,29 @@
+import * as dateFnsLocales from 'date-fns/locale'
+import i18n from 'i18next'
+import type { Locale } from 'react-day-picker'
+
+// date-fns ships ~96 locales; we resolve one by the active i18n language code
+// instead of maintaining a hand-kept map (which silently drifted to English
+// whenever a new UI bundle shipped without a matching entry here). The whole
+// locale set is imported, so any language a translation bundle adds is covered
+// with no edit to this file.
+const LOCALES = dateFnsLocales as unknown as Record<string, Locale>
+
+// i18next codes are BCP-47-ish (`en`, `pt-BR`, `zh-CN`); date-fns export names
+// are camelCase (`enUS`, `ptBR`, `zhCN`). Convert `-x` → `X` to match.
+function dateFnsKey(code: string): string {
+  return code.replace(/-(\w)/g, (_, c: string) => c.toUpperCase())
+}
+
+// Resolve a date-fns Locale for an i18n language code. Tries the exact code,
+// then the base language (`pt-BR` → `pt`), and finally falls back to `enUS`.
+// `en` has no bare date-fns export, so it resolves through the fallback.
+function resolveDateLocale(code: string): Locale {
+  const base = code.split('-')[0]
+  return LOCALES[dateFnsKey(code)] ?? LOCALES[base] ?? LOCALES.enUS
+}
+
+/** date-fns locale for the active admin UI language (falls back to English). */
+export function activeDateLocale(): Locale {
+  return resolveDateLocale(i18n.language ?? 'en')
+}

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/src/lib/validation-messages.ts

@@ -0,0 +1,19 @@
+import i18n from 'i18next'
+
+/**
+ * Lazy "<Field> is required" message for Zod v4 schemas. Wrap in `{ error: ... }`
+ * so the message is resolved per validation (not at module load) — keeps the
+ * literal out of the schema and lets locale changes pick up.
+ *
+ * ```ts
+ * z.string().min(1, { error: requiredMessage('name') })
+ * z.string().min(1, { error: requiredMessage('payment_method.type') })
+ * ```
+ *
+ * `field` is a dot-path under `admin.fields.*` resolving to a `.label` key —
+ * `'name'` → `admin.fields.name.label`, `'payment_method.type'` →
+ * `admin.fields.payment_method.type.label`.
+ */
+export function requiredMessage(field: string): () => string {
+  return () => i18n.t('admin.validation.required', { field: i18n.t(`admin.fields.${field}.label`) })
+}

package/src/spree/address-block.tsx

@@ -0,0 +1,74 @@
+import { useTranslation } from 'react-i18next'
+
+/**
+ * Structural shape of the fields `<AddressBlock>` renders. Lets the design
+ * system stay decoupled from `@spree/admin-sdk`'s `Address` type — any
+ * object carrying these fields renders fine.
+ */
+export interface AddressBlockValue {
+  full_name?: string | null
+  company?: string | null
+  address1?: string | null
+  address2?: string | null
+  city?: string | null
+  state_text?: string | null
+  postal_code?: string | null
+  country_iso?: string | null
+  country_name?: string | null
+  phone?: string | null
+}
+
+/**
+ * Resolves a country name localized to the admin UI language via
+ * `Intl.DisplayNames`, falling back to the API-provided name (then the ISO
+ * code) when the ISO is missing or the runtime lacks coverage.
+ */
+function localizedCountryName(
+  locale: string,
+  iso?: string | null,
+  name?: string | null,
+): string | null {
+  if (iso) {
+    try {
+      const localized = new Intl.DisplayNames([locale, 'en'], { type: 'region' }).of(iso)
+      if (localized) return localized
+    } catch {
+      // Runtime without Intl.DisplayNames coverage — fall back below.
+    }
+  }
+  return name ?? iso ?? null
+}
+
+export function AddressBlock({
+  title,
+  address,
+}: {
+  title: string
+  address: AddressBlockValue | null | undefined
+}) {
+  const { t, i18n } = useTranslation()
+  return (
+    <div>
+      <h6 className="font-semibold text-sm mb-1.5">{title}</h6>
+      {address ? (
+        <div className="text-sm text-muted-foreground flex flex-col gap-0.5">
+          <div>{address.full_name}</div>
+          {address.company && <div>{address.company}</div>}
+          <div>{address.address1}</div>
+          {address.address2 && <div>{address.address2}</div>}
+          <div>
+            {[address.city, address.state_text, address.postal_code].filter(Boolean).join(', ')}
+          </div>
+          <div>
+            {localizedCountryName(i18n.language, address.country_iso, address.country_name)}
+          </div>
+          {address.phone && <div>{address.phone}</div>}
+        </div>
+      ) : (
+        <span className="text-sm text-muted-foreground">
+          {t('admin.components.address_block.not_provided')}
+        </span>
+      )}
+    </div>
+  )
+}

package/src/spree/back-button.tsx

@@ -0,0 +1,48 @@
+import { useParams, useRouter } from '@tanstack/react-router'
+import { ArrowLeftIcon } from 'lucide-react'
+import { useTranslation } from 'react-i18next'
+
+interface BackButtonProps {
+  /**
+   * Fallback path segment under the current store when there is no history to go back to.
+   * Example: "products" → navigates to `/$storeId/products`
+   */
+  fallback: string
+  className?: string
+}
+
+/**
+ * Back button that goes to the previous page in history (preserving that page's
+ * state — filters, column selection, etc.), falling back to `/$storeId/{fallback}`
+ * when there's nothing to go back to (e.g. deep-link, new tab).
+ */
+export function BackButton({ fallback, className }: BackButtonProps) {
+  const { t } = useTranslation()
+  const router = useRouter()
+  const { storeId } = useParams({ strict: false }) as { storeId?: string }
+
+  const handleClick = (e: React.MouseEvent) => {
+    e.preventDefault()
+    // If there's history within the app, go back to preserve previous state
+    if (window.history.length > 1 && document.referrer.includes(window.location.host)) {
+      router.history.back()
+    } else {
+      // Fallback to the list page
+      router.navigate({ to: `/${storeId}/${fallback}` as string })
+    }
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      className={
+        className ??
+        'inline-flex items-center justify-center rounded-lg p-1.5 text-muted-foreground hover:bg-accent hover:text-foreground transition-colors'
+      }
+      aria-label={t('admin.actions.back')}
+    >
+      <ArrowLeftIcon className="size-5" />
+    </button>
+  )
+}

package/src/spree/bulk-dialog.tsx

@@ -0,0 +1,71 @@
+import type { ReactNode } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Button } from '../ui/button'
+import {
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '../ui/dialog'
+import { FieldGroup } from '../ui/field'
+
+interface BulkDialogProps {
+  title: string
+  description?: string
+  submitLabel: string
+  submitDisabled?: boolean
+  onCancel: () => void
+  onSubmit: () => void
+  children: ReactNode
+}
+
+/**
+ * Modal dialog used by `BulkActionBar` form actions — title/description header,
+ * scrollable body wrapping a single `<FieldGroup>`, footer with Cancel/Submit.
+ * The standard shape for "pick a value and apply to N selected rows" flows;
+ * use a Sheet only when the form needs more space than a centered modal.
+ */
+export function BulkDialog({
+  title,
+  description,
+  submitLabel,
+  submitDisabled,
+  onCancel,
+  onSubmit,
+  children,
+}: BulkDialogProps) {
+  const { t } = useTranslation()
+
+  return (
+    <Dialog open onOpenChange={(o) => !o && onCancel()}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+          {description && <DialogDescription>{description}</DialogDescription>}
+        </DialogHeader>
+        <form
+          onSubmit={(event) => {
+            event.preventDefault()
+            if (!submitDisabled) onSubmit()
+          }}
+          className="flex min-h-0 flex-1 flex-col"
+        >
+          <DialogBody>
+            <FieldGroup>{children}</FieldGroup>
+          </DialogBody>
+          <DialogFooter>
+            <Button type="button" variant="outline" size="sm" onClick={onCancel}>
+              {t('admin.actions.cancel')}
+            </Button>
+            <Button type="submit" size="sm" disabled={submitDisabled}>
+              {submitLabel}
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  )
+}