@spree/dashboard-core 0.13.0 → 0.13.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spree/dashboard-core",
   "license": "MIT",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Spree Dashboard framework — registries (table, nav, slot, settings-nav), providers (auth, permission, store), admin SDK client, generic infra hooks, and the defineDashboardPlugin extension API. Developer Preview.",
   "author": "Vendo Connect Inc.",
   "homepage": "https://spreecommerce.org",
@@ -79,8 +79,8 @@
     "typescript": "~6.0.3",
     "vite": "^8.0.16",
     "vitest": "^4.1.5",
-    "@spree/admin-sdk": "^0.8.0",
-    "@spree/dashboard-ui": "^0.13.0"
+    "@spree/admin-sdk": "^0.8.1",
+    "@spree/dashboard-ui": "^0.13.1"
   },
   "scripts": {
     "lint": "biome check src",

package/src/components/import-button.tsx

@@ -19,8 +19,13 @@ import { DownloadIcon, FileSpreadsheetIcon, UploadIcon } from 'lucide-react'
 import { useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import { toast } from 'sonner'
-import { useCreateImport, useDownloadImportTemplate } from '../hooks/use-import'
+import {
+  useCreateImport,
+  useDownloadImportExample,
+  useDownloadImportTemplate,
+} from '../hooks/use-import'
 import type { SubjectName } from '../lib/permissions'
+import { hasSampleCsv } from '../lib/sample-csv'
 import { Can } from './can'
 import { EMPTY_FILE_UPLOAD_VALUE, FileUploadField, type FileUploadValue } from './file-upload-field'
 
@@ -65,6 +70,8 @@ export function ImportButton({ type, subject, onCreated, label }: ImportButtonPr
   const [delimiter, setDelimiter] = useState<Delimiter>(',')
   const createImport = useCreateImport()
   const downloadTemplate = useDownloadImportTemplate()
+  const downloadExample = useDownloadImportExample()
+  const hasExample = hasSampleCsv(type)
 
   const delimiterOptions = DELIMITERS.map(({ value, labelKey }) => ({
     value,
@@ -109,6 +116,18 @@ export function ImportButton({ type, subject, onCreated, label }: ImportButtonPr
     })
   }
 
+  function handleExampleDownload() {
+    downloadExample.mutate(type, {
+      onError: (err) => {
+        toast.error(
+          t('admin.components.import_button.example_failed', {
+            message: err instanceof Error ? err.message : String(err),
+          }),
+        )
+      },
+    })
+  }
+
   return (
     <Can I="create" a={subject}>
       <Button
@@ -162,17 +181,34 @@ export function ImportButton({ type, subject, onCreated, label }: ImportButtonPr
               </Select>
             </Field>
 
-            <Button
-              type="button"
-              variant="ghost"
-              size="sm"
-              className="self-start"
-              onClick={handleTemplateDownload}
-              disabled={downloadTemplate.isPending}
-            >
-              <DownloadIcon className="size-4" />
-              {t('admin.components.import_button.download_template')}
-            </Button>
+            <div className="flex flex-col items-start gap-1">
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                onClick={handleTemplateDownload}
+                disabled={downloadTemplate.isPending}
+              >
+                <DownloadIcon className="size-4" />
+                {t('admin.components.import_button.download_template')}
+              </Button>
+
+              {/* The populated counterpart to the headers-only template above.
+                  Fetched through the API so the file matches the installed
+                  Spree version's schema. */}
+              {hasExample && (
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="sm"
+                  onClick={handleExampleDownload}
+                  disabled={downloadExample.isPending}
+                >
+                  <FileSpreadsheetIcon className="size-4" />
+                  {t('admin.components.import_button.download_example')}
+                </Button>
+              )}
+            </div>
           </div>
 
           <SheetFooter>

package/src/components/resource-table.tsx

@@ -57,7 +57,6 @@ import {
   type ColumnDef,
   type FilterRule,
   getDefaultColumnKeys,
-  getDisplayableColumns,
   getTable,
   type SortOption,
 } from '../lib/table-registry'
@@ -174,6 +173,14 @@ interface ResourceTableProps<T> {
    * menu on the trailing edge.
    */
   rowActions?: (row: T) => ReactNode
+  /**
+   * Dynamic per-store columns derived from custom field definitions,
+   * merged into the registry columns for display (column selector +
+   * cells), sorting, and filtering. Keys are the definitions'
+   * `filter_key` (`cf_*`), which the backend accepts as sort and
+   * filter attributes.
+   */
+  metafieldColumns?: ColumnDef<T>[]
 }
 
 export interface ReorderConfig<T> {
@@ -197,6 +204,7 @@ export function ResourceTable<T extends Record<string, any>>({
   reorder,
   bulkActions,
   rowActions,
+  metafieldColumns,
 }: ResourceTableProps<T>) {
   const table = getTable<T>(tableKey)
   const { t } = useTranslation()
@@ -236,11 +244,31 @@ export function ResourceTable<T extends Record<string, any>>({
   const [searchInput, setSearchInput] = useState(search ?? '')
   const deferredSearch = useDeferredValue(searchInput)
 
-  const displayableColumns = getDisplayableColumns(table)
+  // Registry columns + dynamic metafield columns. Memoized so the toolbar's
+  // internal memos (FilterPanel `items` stability) keep stable deps.
+  const allColumns = useMemo(
+    () => [...table.columns, ...(metafieldColumns ?? [])],
+    [table, metafieldColumns],
+  )
+  const displayableColumns = useMemo(
+    () => allColumns.filter((c) => c.displayable !== false),
+    [allColumns],
+  )
   const defaultColumnKeys = getDefaultColumnKeys(table)
   const visibleColumnKeys = urlColumns ?? defaultColumnKeys
 
-  const visibleColumns = displayableColumns.filter((c) => visibleColumnKeys.includes(c.key))
+  const visibleColumns = useMemo(
+    () => displayableColumns.filter((c) => visibleColumnKeys.includes(c.key)),
+    [displayableColumns, visibleColumnKeys],
+  )
+
+  // Expands requested by currently-visible columns (e.g. custom field
+  // columns need `expand=custom_fields` to render their values). Sorted so
+  // the query key stays stable regardless of column order.
+  const columnExpand = useMemo(
+    () => [...new Set(visibleColumns.flatMap((c) => (c.expand ? [c.expand] : [])))].sort(),
+    [visibleColumns],
+  )
 
   // Build API params
   const sortString = dir === 'desc' ? `-${sort}` : sort
@@ -256,7 +284,7 @@ export function ResourceTable<T extends Record<string, any>>({
   const { data, isLoading } = useQuery({
     queryKey: [
       ...queryKeyPrefix,
-      { page, limit, sort: sortString, search: deferredSearch, filters },
+      { page, limit, sort: sortString, search: deferredSearch, filters, expand: columnExpand },
     ],
     queryFn: () => {
       const params: Record<string, unknown> = {
@@ -269,12 +297,22 @@ export function ResourceTable<T extends Record<string, any>>({
         params.limit = limit
       }
 
+      if (columnExpand.length) {
+        const base = defaultParams?.expand
+        const baseList = Array.isArray(base)
+          ? base
+          : typeof base === 'string'
+            ? base.split(',')
+            : []
+        params.expand = [...new Set([...baseList, ...columnExpand])]
+      }
+
       if (deferredSearch) {
         const searchParam = table.searchParam ?? 'name_cont'
         params[searchParam] = deferredSearch
       }
 
-      Object.assign(params, filtersToRansack(filters as FilterRule[], table.columns))
+      Object.assign(params, filtersToRansack(filters as FilterRule[], allColumns))
 
       return queryFn(params)
     },
@@ -409,7 +447,7 @@ export function ResourceTable<T extends Record<string, any>>({
           filters: filters as FilterRule[],
           search: deferredSearch,
           searchParam: table.searchParam ?? 'name_cont',
-          columns: table.columns,
+          columns: allColumns,
           totalCount: meta?.count,
         })
       : actions
@@ -427,7 +465,7 @@ export function ResourceTable<T extends Record<string, any>>({
         onSortChange={handleSortChange}
         filters={filters as FilterRule[]}
         onFiltersChange={handleFiltersChange}
-        allColumns={table.columns}
+        allColumns={allColumns}
         title={title ?? table.title}
         actions={resolvedActions}
         hideSort={reorderActive}

package/src/components/store-switcher.tsx

@@ -11,24 +11,59 @@ import {
   Skeleton,
   useSidebar,
 } from '@spree/dashboard-ui'
-import { ChevronsUpDownIcon, ExternalLinkIcon } from 'lucide-react'
+import { Link } from '@tanstack/react-router'
+import { CheckIcon, ChevronsUpDownIcon } from 'lucide-react'
 import { useTranslation } from 'react-i18next'
+import { useAuth } from '../hooks/use-auth'
 import { useStore } from '../providers/store-provider'
 
+/**
+ * Sidebar store header. Renders a plain, non-interactive block when the
+ * signed-in admin only has access to one store; becomes a dropdown listing
+ * every store they hold a role on (from `user.stores`) once there are two
+ * or more to switch between.
+ */
 export function StoreSwitcher() {
   const { t } = useTranslation()
   const { isMobile, state } = useSidebar()
   const isCollapsed = state === 'collapsed'
 
   const { store, isLoading } = useStore()
+  const { user } = useAuth()
 
   if (isLoading) return <Skeleton className="h-header-height w-full rounded-xl" />
 
+  const stores = user?.stores ?? []
+
   const storeInitials = store?.name
     .split(' ')
     .map((name) => name[0])
     .join('')
 
+  const header = (
+    <>
+      <Avatar>
+        {store?.logo_url && <AvatarImage src={store.logo_url} />}
+        <AvatarFallback>{storeInitials}</AvatarFallback>
+      </Avatar>
+      {!isCollapsed && (
+        <div className="grid flex-1 text-left text-sm leading-tight">
+          <span className="truncate font-medium text-foreground">{store?.name}</span>
+        </div>
+      )}
+    </>
+  )
+
+  if (stores.length < 2) {
+    return (
+      <SidebarMenu>
+        <SidebarMenuItem className="h-header-height flex items-center">
+          <div className="flex w-full items-center gap-2 p-1.5">{header}</div>
+        </SidebarMenuItem>
+      </SidebarMenu>
+    )
+  }
+
   return (
     <SidebarMenu>
       <SidebarMenuItem className="h-header-height flex items-center">
@@ -36,19 +71,12 @@ export function StoreSwitcher() {
           <DropdownMenuTrigger asChild className="flex w-full items-center">
             <button
               type="button"
+              aria-label={t('admin.a11y.store_switcher')}
               className="rounded-xl outline-hidden transition-colors duration-100 hover:bg-sidebar-accent data-[state=open]:bg-sidebar-accent gap-2 p-1.5"
             >
-              <Avatar>
-                {store?.logo_url && <AvatarImage src={store.logo_url} />}
-                <AvatarFallback>{storeInitials}</AvatarFallback>
-              </Avatar>
+              {header}
               {!isCollapsed && (
-                <>
-                  <div className="grid flex-1 text-left text-sm leading-tight">
-                    <span className="truncate font-medium text-foreground">{store?.name}</span>
-                  </div>
-                  <ChevronsUpDownIcon className="ml-auto size-4 text-muted-foreground" />
-                </>
+                <ChevronsUpDownIcon className="ml-auto size-4 text-muted-foreground" />
               )}
             </button>
           </DropdownMenuTrigger>
@@ -58,10 +86,18 @@ export function StoreSwitcher() {
             align="start"
             sideOffset={8}
           >
-            <DropdownMenuItem>
-              <ExternalLinkIcon className="size-4" />
-              {t('admin.account.view_store')}
-            </DropdownMenuItem>
+            {stores.map((availableStore) => (
+              <DropdownMenuItem key={availableStore.id} asChild>
+                <Link
+                  to="/$storeId"
+                  params={{ storeId: availableStore.id }}
+                  className="no-underline"
+                >
+                  <span className="flex-1 truncate">{availableStore.name}</span>
+                  {availableStore.id === store?.id && <CheckIcon className="size-4" />}
+                </Link>
+              </DropdownMenuItem>
+            ))}
           </DropdownMenuContent>
         </DropdownMenu>
       </SidebarMenuItem>

package/src/components/table-toolbar.tsx

@@ -75,7 +75,9 @@ interface TableToolbarProps {
 // and resolved with `t()` at render time so they follow the active language.
 const operatorsByType: Record<string, { value: string; labelKey: string }[]> = {
   string: [
-    { value: 'cont', labelKey: 'admin.components.table_toolbar.operators.contains' },
+    // `i_cont` (case-insensitive) rather than `cont` — an admin typing
+    // "2 years" expects to match "2 Years".
+    { value: 'i_cont', labelKey: 'admin.components.table_toolbar.operators.contains' },
     { value: 'eq', labelKey: 'admin.components.table_toolbar.operators.equals' },
     { value: 'not_eq', labelKey: 'admin.components.table_toolbar.operators.does_not_equal' },
     { value: 'start', labelKey: 'admin.components.table_toolbar.operators.starts_with' },
@@ -128,6 +130,19 @@ function getOperators(type: string) {
   return operatorsByType[type] || operatorsByType.string
 }
 
+// Operators no longer offered in the picker but still resolvable for display,
+// so filters saved in older URLs keep a readable chip label.
+const legacyOperatorLabelKeys: Record<string, string> = {
+  cont: 'admin.components.table_toolbar.operators.contains',
+}
+
+function getOperatorLabelKey(type: string, operator: string) {
+  return (
+    getOperators(type).find((o) => o.value === operator)?.labelKey ??
+    legacyOperatorLabelKeys[operator]
+  )
+}
+
 const noValueOperators = ['present', 'blank']
 
 // ============================================================================
@@ -283,8 +298,7 @@ function FilterChip({
   onRemove: () => void
 }) {
   const { t } = useTranslation()
-  const ops = getOperators(col?.filterType ?? 'string')
-  const opLabelKey = ops.find((o) => o.value === filter.operator)?.labelKey
+  const opLabelKey = getOperatorLabelKey(col?.filterType ?? 'string', filter.operator)
   const opLabel = opLabelKey ? t(opLabelKey) : filter.operator
   const showValue = !noValueOperators.includes(filter.operator)
 

package/src/components/top-bar.tsx

@@ -28,6 +28,7 @@ import { useCommandPalette } from '../hooks/use-command-palette'
 import { useSwitchAdminLocale } from '../hooks/use-switch-admin-locale'
 import { getInitials } from '../lib/formatters'
 import { i18n } from '../lib/i18n'
+import { storefrontHref } from '../lib/storefront'
 import { useStore } from '../providers/store-provider'
 
 const IS_MAC = typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform ?? '')
@@ -96,10 +97,8 @@ function SearchTrigger() {
 function ViewStoreLink() {
   const { t } = useTranslation()
   const { store } = useStore()
-  if (!store?.url) return null
-
-  // Best-effort: prefix with https if the URL is just a hostname.
-  const href = /^https?:\/\//.test(store.url) ? store.url : `https://${store.url}`
+  const href = storefrontHref(store)
+  if (!href) return null
 
   return (
     <Button asChild variant="ghost" size="sm">

package/src/hooks/use-import.ts

@@ -47,6 +47,28 @@ export function useDownloadImportTemplate() {
   })
 }
 
+/**
+ * Downloads the populated example CSV for an import type.
+ *
+ * Goes through the API rather than linking the file directly: the URL is pinned
+ * to the installed Spree version so a released install never links to a newer,
+ * incompatible schema — and that version is deliberately not exposed over the
+ * API, since it would fingerprint the deployment. Returns 404 for a type that
+ * ships no example file.
+ */
+export function useDownloadImportExample() {
+  const { token } = useAuth()
+
+  return useMutation({
+    mutationFn: (type: ImportType) =>
+      downloadFromApi(
+        token,
+        `/api/v3/admin/imports/example?type=${encodeURIComponent(type)}`,
+        `${type}.csv`,
+      ),
+  })
+}
+
 /** Downloads the originally uploaded CSV of an import — the audit trail. */
 export function useDownloadImportOriginal() {
   const { token } = useAuth()

package/src/lib/sample-csv.ts

@@ -0,0 +1,18 @@
+import type { ImportType } from '@spree/admin-sdk'
+
+/**
+ * Import types that ship a populated example CSV in Spree's
+ * `core/db/sample_data`. Keyed by the API's type shorthand (`"products"`),
+ * which is also the CSV's filename stem.
+ *
+ * Only used to decide whether to render the download link — the file itself is
+ * served by `GET /api/v3/admin/imports/example`, which pins the URL to the
+ * installed Spree version. A type missing from this list simply hides the link;
+ * the endpoint is the authority and 404s for anything it has no example for.
+ */
+const TYPES_WITH_SAMPLE_CSV = new Set(['products', 'customers', 'product_translations'])
+
+/** Whether an import type has an example CSV to offer. */
+export function hasSampleCsv(type: ImportType): boolean {
+  return TYPES_WITH_SAMPLE_CSV.has(type)
+}

package/src/lib/storefront.ts

@@ -0,0 +1,19 @@
+import type { Store } from '@spree/admin-sdk'
+
+/**
+ * Resolves the storefront URL to link to from admin "View store" affordances,
+ * or `null` when no storefront URL is configured.
+ *
+ * The serialized `store.url` always resolves — the backend falls back to the
+ * store's formatted URL — so gate on the explicit `preferred_storefront_url`
+ * preference: only return a link once a real storefront has been set.
+ *
+ * @param store the current store, or null/undefined while it loads
+ * @returns an absolute URL, or null when the store has no configured storefront
+ */
+export function storefrontHref(store: Store | null | undefined): string | null {
+  if (!store?.preferred_storefront_url) return null
+
+  // Best-effort: prefix with https if the URL is just a hostname.
+  return /^https?:\/\//.test(store.url) ? store.url : `https://${store.url}`
+}

package/src/lib/table-registry.ts

@@ -16,6 +16,12 @@ interface ColumnDefBase<T = any> {
   ransackAttribute?: string
   /** Custom cell renderer. If omitted, renders `row[key]` as text. */
   render?: (row: T) => ReactNode
+  /**
+   * `expand` value the list request needs while this column is visible
+   * (e.g. `'custom_fields'`). ResourceTable unions the values across
+   * visible columns into the `expand` query param.
+   */
+  expand?: string
   /** Cell className */
   className?: string
   /** Whether this column is displayable in the table. Set to false for filter-only columns. */

package/src/locales/ar.json

@@ -76,7 +76,8 @@
       "remove_value": "إزالة القيمة",
       "breadcrumb_more": "المزيد",
       "sidebar": "الشريط الجانبي",
-      "sidebar_description": "يعرض الشريط الجانبي للجوال."
+      "sidebar_description": "يعرض الشريط الجانبي للجوال.",
+      "store_switcher": "تبديل المتجر"
     },
     "common": {
       "loading": "جارٍ التحميل…",

package/src/locales/de.json

@@ -76,7 +76,8 @@
       "remove_value": "Wert entfernen",
       "breadcrumb_more": "Mehr",
       "sidebar": "Seitenleiste",
-      "sidebar_description": "Zeigt die mobile Seitenleiste an."
+      "sidebar_description": "Zeigt die mobile Seitenleiste an.",
+      "store_switcher": "Store wechseln"
     },
     "common": {
       "loading": "Wird geladen…",

package/src/locales/en.json

@@ -76,7 +76,8 @@
       "remove_value": "Remove value",
       "breadcrumb_more": "More",
       "sidebar": "Sidebar",
-      "sidebar_description": "Displays the mobile sidebar."
+      "sidebar_description": "Displays the mobile sidebar.",
+      "store_switcher": "Switch store"
     },
     "common": {
       "loading": "Loading…",
@@ -490,7 +491,9 @@
           "tab": "Tab"
         },
         "download_template": "Download CSV template",
+        "download_example": "Download an example CSV",
         "template_failed": "Template download failed: {{message}}",
+        "example_failed": "Example download failed: {{message}}",
         "submit": "Continue",
         "failed": "Import failed: {{message}}"
       },

package/src/locales/fr.json

@@ -76,7 +76,8 @@
       "remove_value": "Retirer la valeur",
       "breadcrumb_more": "Plus",
       "sidebar": "Barre latérale",
-      "sidebar_description": "Affiche la barre latérale mobile."
+      "sidebar_description": "Affiche la barre latérale mobile.",
+      "store_switcher": "Changer de boutique"
     },
     "common": {
       "loading": "Chargement…",

package/src/locales/pl.json

@@ -76,7 +76,8 @@
       "remove_value": "Usuń wartość",
       "breadcrumb_more": "Więcej",
       "sidebar": "Panel boczny",
-      "sidebar_description": "Wyświetla mobilny panel boczny."
+      "sidebar_description": "Wyświetla mobilny panel boczny.",
+      "store_switcher": "Przełącz sklep"
     },
     "common": {
       "loading": "Ładowanie…",

package/src/locales/zh-CN.json

@@ -76,7 +76,8 @@
       "remove_value": "移除值",
       "breadcrumb_more": "更多",
       "sidebar": "侧边栏",
-      "sidebar_description": "显示移动端侧边栏。"
+      "sidebar_description": "显示移动端侧边栏。",
+      "store_switcher": "切换店铺"
     },
     "common": {
       "loading": "加载中…",