@spree/docs 0.1.122 → 0.1.124

package/dist/developer/dashboard/public-api.md

@@ -0,0 +1,241 @@
+---
+title: Public API
+sidebarTitle: Public API
+description: Every importable symbol the dashboard exposes — components, hooks, registries, providers, and the SDK client. Treat this as the surface you can safely depend on.
+---
+
+The dashboard is structured as three packages, each with a documented public surface. **Anything not listed here is internal** — don't import it via `@spree/dashboard-core/src/internal/...`, because we'll move or rename it without a deprecation cycle.
+
+## `@spree/dashboard-core`
+
+Default-import surface for plugins and customizations.
+
+### Plugin facade
+
+```ts
+import { defineDashboardPlugin } from '@spree/dashboard-core'
+```
+
+Single declarative entry-point for every registry. See [Customization Quickstart](customization/quickstart.md) for the full shape.
+
+### Registries
+
+```ts
+import {
+  nav,
+  settingsNav,
+  // route registry
+  pluginRoutes,
+  matchPluginRoute,
+  usePluginRoutes,
+  // slot registry
+  registerSlot,
+  removeSlot,
+  updateSlot,
+  useSlotEntries,
+  // table registry
+  tables,
+  // extension fields on built-in forms (hydrate + save with the host form)
+  formFields,
+  // input components for specific custom field definitions
+  customFieldComponents,
+} from '@spree/dashboard-core'
+```
+
+Each registry exposes `add`/`remove`/`update`-style mutators. See the per-feature pages for examples — form fields and custom field components are covered in the [custom form field recipe](recipes/custom-form-field.md).
+
+### Components
+
+```ts
+import {
+  // Page chrome
+  PageHeader,
+  PageTabs,
+  TopBar,
+  AppSidebar,
+  SettingsSidebar,
+  Slot,
+  StoreSwitcher,
+  // Tables
+  ResourceTable,
+  TableToolbar,
+  BulkActionBar,
+  // Form widgets
+  StoreDatePicker,
+  CountryCombobox,
+  CountryStateFields,
+  CurrencySelect,
+  LocaleSelect,
+  MarketCombobox,
+  ResourceCombobox,
+  ResourceMultiAutocomplete,
+  TagCombobox,
+  PreferencesForm,
+  AddressFormDialog,
+  // Permission
+  Can,
+  // Export
+  ExportButton,
+} from '@spree/dashboard-core'
+```
+
+### Hooks
+
+```ts
+import {
+  useAuth,            // current admin user
+  usePermissions,     // CanCanCan abilities
+  useStore,           // current store
+  useCommandPalette,  // ⌘K palette open/close state
+  useGlobalSearch,    // global search query state
+  useCountries,
+  useCustomFields,
+  useDirectUpload,    // ActiveStorage direct uploads
+  useExport,          // CSV export job lifecycle
+  useResourceMutation, // useMutation wrapper with 422 handling
+  useHostForm,        // the built-in form a slot widget renders inside (throws when absent)
+  useOptionalHostForm, // same, but null when the page has no host form
+} from '@spree/dashboard-core'
+```
+
+### Helpers
+
+```ts
+import {
+  filtersToRansack,     // converts table filter state → Ransack params
+  mapSpreeErrorsToForm, // 422 response → form.setError
+  // formatters
+  formatPrice,          // Price object → display string
+  formatStoreDateTime,  // ISO string → wall-clock in the store's timezone
+  getInitials,          // full name → avatar initials
+  // i18n
+  i18n,                 // configured instance
+  // form mappers — normalize optional text inputs before submitting
+  blankToNull,
+  blankToUndefined,
+} from '@spree/dashboard-core'
+```
+
+### SDK client
+
+```ts
+import { adminClient } from '@spree/dashboard-core'
+```
+
+The shared `@spree/admin-sdk` instance configured for the host's API URL. Use this everywhere instead of constructing your own.
+
+### Providers
+
+```ts
+import {
+  AuthProvider,
+  PermissionProvider,
+  StoreProvider,
+} from '@spree/dashboard-core'
+```
+
+Mount these at the root of your app shell. The shipped app shell does this for you — re-export only if you're composing a custom shell (vendor panel, etc.).
+
+### Vite plugin
+
+```ts
+import { spreeDashboardPlugin } from '@spree/dashboard-core/vite'
+```
+
+Vite plugin that resolves third-party dashboard plugins and injects Tailwind `@source` directives for their CSS. See [Distributing](plugins/distributing.md) for the host wiring.
+
+## `@spree/dashboard-ui`
+
+Design system primitives. Headless — accept data via props, never reach for providers or hooks.
+
+### shadcn-style primitives
+
+```ts
+import {
+  Button,
+  Card, CardContent, CardHeader, CardTitle, CardDescription, CardFooter,
+  Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter,
+  Sheet, SheetContent, SheetHeader, SheetTitle, SheetFooter,
+  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem,
+  Input, Textarea, Checkbox, RadioGroup, Switch,
+  Select, SelectTrigger, SelectContent, SelectItem, SelectValue,
+  Combobox,
+  Field, FieldLabel, FieldError, FieldDescription,
+  Table, TableHeader, TableBody, TableRow, TableCell,
+  Badge,
+  Avatar,
+  Skeleton,
+  Tooltip, TooltipTrigger, TooltipContent,
+  Toaster,
+} from '@spree/dashboard-ui'
+```
+
+Toast *notifications* come from [sonner](https://sonner.emilkowal.ski/) directly — `import { toast } from 'sonner'` — while `<Toaster>` (the mount point, already rendered by the app shell) is the only part re-exported here.
+
+### Composed components
+
+Higher-level pieces that bundle multiple primitives but still take data via props:
+
+```ts
+import {
+  ResourceLayout,     // header + main + sidebar grid
+  Empty, EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent,
+  ColorPicker,
+  // …more land here as we extract from @spree/dashboard
+} from '@spree/dashboard-ui'
+```
+
+`Empty*` composes via children (icon in `<EmptyMedia>`, actions in `<EmptyContent>`) rather than taking `title`/`description` props.
+
+### Utilities
+
+```ts
+import { cn } from '@spree/dashboard-ui'  // clsx + tailwind-merge
+```
+
+## `@spree/dashboard`
+
+The app shell. **Plugins don't import from here** — a plugin extends the dashboard through `@spree/dashboard-core` and never renders the shell. The host (the `dashboard-starter` project, or a create-spree-app project) is what imports it, to mount the admin:
+
+```ts
+import { createDashboardRouter, Dashboard } from '@spree/dashboard'
+```
+
+- **`Dashboard`** — the app shell component (provider stack + router). Render it with a router: `<Dashboard router={router} />`.
+- **`createDashboardRouter(routeTree)`** — builds the router from the host's generated `routeTree.gen.ts` (the shell's routes composed with every installed plugin's file routes). The starter's `main.tsx` wires these together; you rarely write this by hand.
+
+Two subpath entries complete the surface:
+
+```ts
+import { spreeDashboardPlugin } from '@spree/dashboard/vite'  // Vite plugin: Tailwind, discovery, route composition
+import '@spree/dashboard/styles.css'                          // the app's CSS entry
+```
+
+Importing from `@spree/dashboard` pins your code to the deployable app's version. Plugins and custom UI should prefer `@spree/dashboard-core` + `@spree/dashboard-ui`.
+
+## What about `@spree/admin-sdk`?
+
+The Admin API client is a separate package and a public dependency. Import types and `SpreeError` from it directly:
+
+```ts
+import {
+  type Product,
+  type Order,
+  type Customer,
+  SpreeError,
+} from '@spree/admin-sdk'
+```
+
+The `adminClient` instance, by contrast, comes from `@spree/dashboard-core` so the host owns the configured singleton.
+
+## Stability
+
+Anything on this page is covered by semver from `@spree/dashboard-core` 1.0.0 onward. Pre-1.0 we may rename, but we'll call breaking moves out in the changelog.
+
+Anything not listed here is internal. If you find yourself wanting it, open a discussion — it's a sign we should promote it to the public surface.
+
+## Reference
+
+- [`packages/dashboard-core/src/index.ts`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/index.ts) — canonical export list
+- [`packages/dashboard-ui/src/index.ts`](https://github.com/spree/spree/blob/main/packages/dashboard-ui/src/index.ts)
+- [`packages/admin-sdk/src/index.ts`](https://github.com/spree/spree/blob/main/packages/admin-sdk/src/index.ts)

package/dist/developer/dashboard/recipes/attribute-end-to-end.md

@@ -0,0 +1,212 @@
+---
+title: "A product attribute, end to end: form, table, filters, sort"
+sidebarTitle: Attribute end-to-end
+description: Take one custom product attribute all the way — editable on the product form, visible as a table column, filterable and sortable in the products list.
+---
+
+This recipe adds a **supplier lead time** (`lead_time_days`, an integer) to products and wires it through every surface the dashboard has:
+
+- edited on the product form, saved by the form's own Save button
+- a column in the products table
+- a filter ("lead time > 7 days") and a sort ("slowest first") in the list toolbar
+
+It's the full version of the [custom form field recipe](custom-form-field.md) — read that one first if you only need the form.
+
+## First: should this be a custom field instead?
+
+**Default to a [custom field definition](custom-form-field.md#path-a-custom-field-definition--no-code).** It needs zero code — declare the field, and the product form renders and saves it. That covers most plugin data and everything merchants define themselves.
+
+Graduate to a real database column only when the attribute needs **list operations or database guarantees**:
+
+| You need… | Custom field | Real column |
+|---|---|---|
+| Editing on the product form | ✅ zero code | ✅ this recipe |
+| Filtering / sorting the products list in Admin | ❌ | ✅ via Ransack |
+| Merchants defining the field themselves at runtime | ✅ | ❌ |
+
+Lead time is a column because its whole point is the query: *"show me everything that ships slow, slowest first."*
+
+## 1. Backend
+
+Four small pieces — each one unlocks a specific frontend capability. In a host app these live in `backend/` (or `api/`); in a distributed plugin, in the Rails engine half.
+
+**The column** (with an index — you're adding it *because* it will be queried):
+
+```ruby
+class AddLeadTimeDaysToSpreeProducts < ActiveRecord::Migration[7.2]
+  def change
+    add_column :spree_products, :lead_time_days, :integer
+    add_index :spree_products, :lead_time_days
+  end
+end
+```
+
+**The serializer** — makes the attribute *readable* (hydrates the form, renders the table cell):
+
+```ruby
+# app/serializers/admin/product_serializer.rb
+module Admin
+  class ProductSerializer < Spree::Api::V3::Admin::ProductSerializer
+    attributes :lead_time_days
+  end
+end
+
+# config/initializers/spree.rb
+Spree.api.admin_product_serializer = 'Admin::ProductSerializer'
+```
+
+**The permitted param** — makes it *writable* (the form's Save ships it in the same PATCH as core fields). The read and write names must match:
+
+```ruby
+# app/controllers/spree/api/v3/admin/products_controller_decorator.rb
+module Spree
+  module Api
+    module V3
+      module Admin
+        module ProductsControllerDecorator
+          def permitted_params
+            super.merge(params.permit(:lead_time_days))
+          end
+        end
+
+        ProductsController.prepend(ProductsControllerDecorator)
+      end
+    end
+  end
+end
+```
+
+**The Ransack allowlist** — makes it *filterable and sortable*. Both the list's sort param and every filter predicate go through Ransack, and Ransack refuses attributes that aren't allowlisted:
+
+```ruby
+# config/initializers/spree.rb
+Spree::Product.whitelisted_ransackable_attributes |= %w[lead_time_days]
+```
+
+Add a Rails validation while you're here (`validates :lead_time_days, numericality: { greater_than_or_equal_to: 0, allow_nil: true }`) — it's the authoritative validation, and the dashboard renders its 422 message inline on the field automatically.
+
+## 2. Frontend — one declaration
+
+```tsx
+// src/plugins.ts (or a plugin's entry module)
+import { defineDashboardPlugin, i18n } from '@spree/dashboard-core'
+import { LeadTimeCard } from './fields/lead-time-card'
+
+i18n.addResourceBundle('en', 'translation', en, true, true)
+
+defineDashboardPlugin({
+  // Form: hydrate from the fetched product, save with the form's own Save.
+  formFields: {
+    product: [{ name: 'lead_time_days', from: (p) => p?.lead_time_days ?? null }],
+  },
+  slots: {
+    'product.form_sidebar': [{ id: 'lead-time', component: LeadTimeCard as never, position: 60 }],
+  },
+
+  // Table: column + filter + sort in one ColumnDef.
+  tables: {
+    products: {
+      add: [{
+        key: 'lead_time_days',
+        label: i18n.t('admin.fields.product.lead_time_days.label'),
+        sortable: true,       // header click → server-side sort via Ransack
+        filterable: true,     // appears in the filter panel
+        filterType: 'number', // numeric operator set: =, ≠, >, <, ranges
+        default: true,        // visible out of the box (false = opt-in via column picker)
+        render: (product) => (product.lead_time_days != null ? `${product.lead_time_days} d` : '—'),
+      }],
+    },
+  },
+})
+```
+
+The form widget binds to the host form — no `<form>` of its own, no save button:
+
+```tsx
+// src/fields/lead-time-card.tsx
+import { useHostForm } from '@spree/dashboard-core'
+import { Card, CardContent, CardHeader, CardTitle, Field, FieldError, FieldLabel, Input } from '@spree/dashboard-ui'
+import { useTranslation } from 'react-i18next'
+
+export function LeadTimeCard() {
+  const { t } = useTranslation()
+  const form = useHostForm<{ lead_time_days: number | null }>()
+  const error = form.formState.errors.lead_time_days?.message
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{t('admin.fields.product.lead_time_days.label')}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Field>
+          <FieldLabel className="sr-only" htmlFor="lead_time_days">
+            {t('admin.fields.product.lead_time_days.label')}
+          </FieldLabel>
+          <Input
+            id="lead_time_days"
+            type="number"
+            min={0}
+            placeholder={t('admin.fields.product.lead_time_days.placeholder')}
+            aria-invalid={Boolean(error)}
+            {...form.register('lead_time_days', {
+              // Empty input → null (not NaN, not "") so the API gets a clean value.
+              setValueAs: (v) => (v === '' || v == null ? null : Number(v)),
+            })}
+          />
+          {error && <FieldError>{error as string}</FieldError>}
+        </Field>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+```json
+// src/locales/en.json — note the top-level "admin" wrapper
+{
+  "admin": {
+    "fields": {
+      "product": {
+        "lead_time_days": {
+          "label": "Lead time (days)",
+          "placeholder": "e.g. 14"
+        }
+      }
+    }
+  }
+}
+```
+
+## 3. Verify it
+
+API first — the fastest way to confirm the backend pieces:
+
+```bash
+# write (permitted param + validation)
+npx spree api patch products/prod_xxx --data '{"lead_time_days": 14}'
+
+# filter + sort (Ransack allowlist)
+npx spree api get "products?q[lead_time_days_gt]=7&sort=-lead_time_days"
+```
+
+Then the UI: open a product — the Lead time card sits in the sidebar; edit it and the page's Save button arms; save and reload. On the products list the column renders, the header sorts, and the filter panel offers the numeric operators. Filters and sort round-trip through the URL — a filtered view is shareable — and a CSV export of the filtered list respects your filter, because the export stores the same Ransack predicate hash.
+
+## How the pieces map
+
+| Frontend behavior | Made possible by |
+|---|---|
+| Form input hydrates + saves with the page | serializer attribute + permitted param + `formFields`/`useHostForm` |
+| Table cell renders | serializer attribute + `ColumnDef.render` |
+| Header sort works | `sortable: true` + Ransack allowlist |
+| Filter panel entry works | `filterable: true` + `filterType` + Ransack allowlist |
+| Inline validation message | the Rails validation (422 → mapped onto the field) |
+
+Two `ColumnDef` extras worth knowing: `ransackAttribute` points the predicate somewhere other than the column key (the built-in `sku` column filters through `master_sku`), and `displayable: false` makes a filter-only field that never renders as a column.
+
+## Reference
+
+- [Custom form field recipe](custom-form-field.md) — the form layer in isolation, and the custom-field-definition path
+- [Tables](../customization/tables.md) — the full `ColumnDef` and table registry API
+- [Backend integration](../customization/backend.md) — serializers, permitted params, error mapping
+- [Decorators](../../customization/decorators.md) — the `prepend` pattern used for the controller

package/dist/developer/dashboard/recipes/custom-form-field.md

@@ -0,0 +1,174 @@
+---
+title: Add a custom field to the product form
+sidebarTitle: Custom form field
+description: Add a field to the built-in product form that hydrates from the API and saves with the form's own Save button — no save logic of your own.
+---
+
+Two ways to get a custom field onto the product form, both saved by the page's single Save button:
+
+- **Custom field definition (no code)** — declare the field as data; the dashboard renders it. Right for merchant-managed attributes and most plugin data.
+- **Extension form field (code)** — for a real database column your plugin added to `spree_products`. You register the field and render its input; hydration and saving stay with the host form.
+
+## Path A: custom field definition — no code
+
+Create a definition for products (Settings → Custom fields, the in-place "Set up" button on the Custom Fields card, or the API):
+
+```bash
+npx spree api post custom_field_definitions --data '{
+  "resource_type": "Spree::Product",
+  "namespace": "specs",
+  "key": "tech_specs",
+  "label": "Technical specifications",
+  "field_type": "long_text"
+}'
+```
+
+That's the whole feature. The **Custom Fields card** on the product form now renders a textarea for it; the value rides the form's `custom_fields[]` and persists when the merchant hits **Save**. Field types: `short_text`, `long_text`, `rich_text`, `number`, `boolean`, `json`.
+
+### Optional: replace the input widget
+
+When the default widget isn't right — a color, a rating, a structured pair — register a component for that specific definition, keyed by its `namespace.key`:
+
+```tsx
+// src/plugins.ts (or a plugin's entry module)
+import { type CustomFieldComponentProps, defineDashboardPlugin } from '@spree/dashboard-core'
+
+function ColorPicker({ id, value, onChange, ariaLabel }: CustomFieldComponentProps) {
+  return (
+    <input
+      id={id}
+      type="color"
+      aria-label={ariaLabel}
+      value={(value as string) || '#000000'}
+      onChange={(e) => onChange(e.target.value)}
+    />
+  )
+}
+
+defineDashboardPlugin({
+  customFieldComponents: {
+    'specs.color': ColorPicker,
+  },
+})
+```
+
+The component is a controlled input — render `value`, call `onChange`. Persistence stays with the card (the form's Save on products and categories; the card's own Save on orders and customers). When no component is registered, the default widget for the definition's `field_type` renders.
+
+## Path B: extension form field — a real column
+
+Use this when your plugin adds an actual column and API attribute.
+
+### 1. Backend
+
+```ruby
+class AddTechSpecsToSpreeProducts < ActiveRecord::Migration[7.2]
+  def change
+    add_column :spree_products, :tech_specs, :text, null: false, default: ''
+  end
+end
+```
+
+Expose it on the Admin API — the serializer returns `tech_specs`, and the products controller permits it on write (see [Backend integration](../customization/backend.md)). Read and write names must match.
+
+### 2. Register the field
+
+Tell the product form about the field: where its value comes from on load. Everything else — dirty tracking, the PATCH payload, re-baselining after save — is the host form's job.
+
+```tsx
+// src/plugins.ts (or a plugin's entry module)
+import { defineDashboardPlugin } from '@spree/dashboard-core'
+
+defineDashboardPlugin({
+  formFields: {
+    product: [
+      // `from` receives the fetched product — or null on the create form.
+      { name: 'tech_specs', from: (product) => product?.tech_specs ?? '' },
+    ],
+  },
+})
+```
+
+### 3. Render the input from a slot
+
+The `product.form_sidebar` slot renders inside the product form. Bind your input to the host form with `useHostForm()` — no `<form>` of your own, no save button:
+
+```tsx
+// src/fields/tech-specs-card.tsx
+import { useHostForm } from '@spree/dashboard-core'
+import {
+  Card, CardContent, CardHeader, CardTitle,
+  Field, FieldError, FieldLabel, Textarea,
+} from '@spree/dashboard-ui'
+import { useTranslation } from 'react-i18next'
+
+export function TechSpecsCard() {
+  const { t } = useTranslation()
+  const form = useHostForm<{ tech_specs: string }>()
+  const error = form.formState.errors.tech_specs?.message
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{t('admin.fields.product.tech_specs.label')}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Field>
+          <FieldLabel className="sr-only" htmlFor="tech_specs">
+            {t('admin.fields.product.tech_specs.label')}
+          </FieldLabel>
+          <Textarea
+            id="tech_specs"
+            rows={6}
+            placeholder={t('admin.fields.product.tech_specs.placeholder')}
+            aria-invalid={Boolean(error)}
+            {...form.register('tech_specs')}
+          />
+          {error && <FieldError>{error as string}</FieldError>}
+        </Field>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+```tsx
+// src/plugins.ts — alongside the formFields registration
+defineDashboardPlugin({
+  formFields: {
+    product: [{ name: 'tech_specs', from: (product) => product?.tech_specs ?? '' }],
+  },
+  slots: {
+    'product.form_sidebar': [{ id: 'tech-specs', component: TechSpecsCard as never, position: 80 }],
+  },
+})
+```
+
+Done. The field hydrates when the page loads, participates in the form's dirty state (Save enables when it changes), ships in the same PATCH as every core field, and re-baselines after save.
+
+### Validation
+
+Extension fields are validated by the **server** — a Rails validation failing returns a 422, and the host form's error mapping puts the message inline on your field (that's the `errors.tech_specs` read in the component). This mirrors how Vendure and Saleor treat extension-field validation: the backend is authoritative; the client renders what it says.
+
+### Which forms support this
+
+`useHostForm()` works wherever a built-in form exposes its form context — currently the **product** (edit + new), **category** (edit + new), and **store settings** forms, with matching slots (`product.form_sidebar`, `category.form_sidebar`, `store.form_main`) and form keys (`product`, `category`, `store`). Orders and customers have no page-wide form — their sheets own their edits — so slot widgets there manage their own persistence; use `useOptionalHostForm()` to write a widget that adapts to both contexts.
+
+## Which path should I pick?
+
+| Situation | Path |
+|---|---|
+| Merchant-defined attributes, plugin data without schema migrations | **A** — definition, zero code |
+| Default widget is fine | **A** |
+| A real column with Rails validations, queries, or indexes | **B** |
+| The field belongs visually inside your own card with other UI | **B** |
+
+## Going further
+
+To also surface the attribute as a **table column with filtering and sorting**, continue with [A product attribute, end to end](attribute-end-to-end.md).
+
+## Reference
+
+- [Custom fields](../../customization/metadata.md) — definitions, types, the API
+- [Slots](../customization/slots.md) — the injection mechanism
+- [`useHostForm`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/hooks/use-host-form.ts)
+- [`formFields` registry](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/lib/form-fields-registry.ts)