@spree/docs 0.1.237 → 0.1.238

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

@@ -89,7 +89,7 @@ Add a Rails validation while you're here (`validates :lead_time_days, numericali
 
 ```tsx
 // src/plugins.ts (or a plugin's entry module)
-import { defineDashboardPlugin, i18n } from '@spree/dashboard-core'
+import { defineDashboardPlugin, i18n } from '@spree/dashboard'
 import { LeadTimeCard } from './fields/lead-time-card'
 
 i18n.addResourceBundle('en', 'translation', en, true, true)
@@ -124,8 +124,7 @@ The form widget binds to the host form — no `<form>` of its own, no save butto
 
 ```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 { Card, CardContent, CardHeader, CardTitle, Field, FieldError, FieldLabel, Input, useHostForm } from '@spree/dashboard'
 import { useTranslation } from 'react-i18next'
 
 export function LeadTimeCard() {

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

@@ -31,7 +31,7 @@ When the default widget isn't right — a color, a rating, a structured pair —
 
 ```tsx
 // src/plugins.ts (or a plugin's entry module)
-import { type CustomFieldComponentProps, defineDashboardPlugin } from '@spree/dashboard-core'
+import { type CustomFieldComponentProps, defineDashboardPlugin } from '@spree/dashboard'
 
 function ColorPicker({ id, value, onChange, ariaLabel }: CustomFieldComponentProps) {
   return (
@@ -76,7 +76,7 @@ Tell the product form about the field: where its value comes from on load. Every
 
 ```tsx
 // src/plugins.ts (or a plugin's entry module)
-import { defineDashboardPlugin } from '@spree/dashboard-core'
+import { defineDashboardPlugin } from '@spree/dashboard'
 
 defineDashboardPlugin({
   formFields: {
@@ -94,11 +94,17 @@ The `product.form_sidebar` slot renders inside the product form. Bind your input
 
 ```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'
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  Field,
+  FieldError,
+  FieldLabel,
+  Textarea,
+  useHostForm,
+} from '@spree/dashboard'
 import { useTranslation } from 'react-i18next'
 
 export function TechSpecsCard() {

package/dist/developer/dashboard/recipes/page-action-button.md

@@ -17,8 +17,7 @@ This recipe shows both — and how to gate them by permission + resource state.
 
 ```tsx
 // src/actions/send-invoice-button.tsx
-import { adminClient, usePermissions, useResourceMutation } from '@spree/dashboard-core'
-import { Button } from '@spree/dashboard-ui'
+import { Button, adminClient, usePermissions, useResourceMutation } from '@spree/dashboard'
 import { Send } from 'lucide-react'
 
 interface Props {
@@ -55,7 +54,7 @@ Register it:
 
 ```ts
 // src/plugins.ts (in your dashboard app)
-import { defineDashboardPlugin } from '@spree/dashboard-core'
+import { defineDashboardPlugin } from '@spree/dashboard'
 import { SendInvoiceButton } from './actions/send-invoice-button'
 
 defineDashboardPlugin({
@@ -82,8 +81,7 @@ For secondary actions, use `page.actions_dropdown` and render `<DropdownMenuItem
 
 ```tsx
 // src/actions/sync-to-erp-item.tsx
-import { adminClient, usePermissions, useResourceMutation } from '@spree/dashboard-core'
-import { DropdownMenuItem } from '@spree/dashboard-ui'
+import { DropdownMenuItem, adminClient, usePermissions, useResourceMutation } from '@spree/dashboard'
 import { RefreshCw } from 'lucide-react'
 
 interface Props {
@@ -135,9 +133,12 @@ For destructive or expensive actions, wrap the click in a `<Dialog>`:
 ```tsx
 import { useState } from 'react'
 import {
-  Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter,
-  DropdownMenuItem, Button,
-} from '@spree/dashboard-ui'
+  adminClient,
+  Button,
+  Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle,
+  DropdownMenuItem,
+  useResourceMutation,
+} from '@spree/dashboard'
 
 export function ResetCartItem({ resource }: { resource: { id: string } }) {
   const [open, setOpen] = useState(false)

package/dist/developer/dashboard/recipes/sidebar-widget.md

@@ -13,13 +13,19 @@ This recipe builds a "Loyalty status" card for the customer detail page: read-on
 ```tsx
 // src/widgets/loyalty-status-card.tsx
 import { useQuery } from '@tanstack/react-query'
-import { adminClient, usePermissions, useStore } from '@spree/dashboard-core'
 import {
+  adminClient,
   Badge,
-  Card, CardContent, CardHeader, CardTitle,
-  Empty, EmptyDescription,
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  Empty,
+  EmptyDescription,
   Skeleton,
-} from '@spree/dashboard-ui'
+  usePermissions,
+  useStore,
+} from '@spree/dashboard'
 import { Trophy } from 'lucide-react'
 
 interface LoyaltyRecord {
@@ -94,7 +100,7 @@ Worth noting:
 
 ```ts
 // src/plugins.ts (in your dashboard app)
-import { defineDashboardPlugin } from '@spree/dashboard-core'
+import { defineDashboardPlugin } from '@spree/dashboard'
 import { LoyaltyStatusCard } from './widgets/loyalty-status-card'
 
 defineDashboardPlugin({

package/dist/developer/dashboard/slots-catalog.md

@@ -13,7 +13,7 @@ If you need a new injection point in a built-in page, open a PR adding `<Slot na
 Ambient context (`permissions`, `store`, `user` merged into every slot's props) is planned but **not wired up yet** — today slot components receive only the slot-specific context listed below. Until it lands, read those values with the hooks instead:
 
 ```tsx
-import { usePermissions, useStore } from '@spree/dashboard-core'
+import { usePermissions, useStore } from '@spree/dashboard'
 
 function MyWidget({ product }: { product: Product }) {
   const { permissions } = usePermissions()

package/dist/developer/how-to/build-a-marketplace.md

@@ -1,11 +1,11 @@
 ---
 title: Build a Multi-Vendor Marketplace
-description: Marketplace capabilities are part of Spree 6 core — sellers, order splitting, commissions and payouts, without a separate extension.
+description: Marketplace capabilities are part of Spree core — sellers, order splitting, commissions and payouts, without a separate extension.
 ---
 
-> **NOTE:** Marketplace features are a headline capability of the Spree 6.0 release and are documented here as they land. This guide covers the open-source core.
+This guide covers the open-source core.
 
-Spree 6 brings multi-vendor marketplace support into the open-source core: sellers as first-class records, orders split per seller at completion, a commission engine, and a payout ledger with pluggable payout providers.
+Spree brings multi-vendor marketplace support into the open-source core: sellers as first-class records, orders split per seller at completion, a commission engine, and a payout ledger with pluggable payout providers.
 
 ## What you will build
 

package/dist/developer/how-to/custom-digital-asset-provider.md

@@ -131,6 +131,6 @@ Spree::DigitalDelivery.new(inline_value: 'ABCD-1234-EFGH', content_type: 'text/p
 
 ## Related documentation
 
-- [Digital products](/use-case/digital-products/capabilities) — what the feature does for merchants
+- [Digital products](sell-digital-products.md) — what the feature does for merchants
 - [Products](../core-concepts/products.md#digital-products) — how digital assets, links, and downloads fit together
 - [Build a Custom Delivery Rate Provider](custom-delivery-rate-provider.md) — a provider strategy that *does* use an integration, for contrast

package/dist/developer/how-to/custom-document-numbers.md

@@ -22,7 +22,7 @@ There are two ways to change it. Merchants can reshape **order numbers** from th
 | Suffix | Ends each order number. Empty by default. |
 | Start numbering at | The first order number. Defaults to `1001`. |
 
-Sequential numbering counts up: `R1001`, `R1002`, `R1003`. Random numbering produces nine unpredictable digits, which is what Spree did before 6.0. The trade-off is worth stating to merchants: sequential numbers are far easier to read back over the phone, but a customer who orders twice can see how many orders you took in between. Random numbers give that away nothing, at the cost of legibility.
+Sequential numbering counts up: `R1001`, `R1002`, `R1003`. Random numbering produces nine unpredictable digits. The trade-off is worth stating to merchants: sequential numbers are far easier to read back over the phone, but a customer who orders twice can see how many orders you took in between. Random numbers reveal nothing about that, at the cost of legibility.
 
 Two rules apply to every change:
 
@@ -139,9 +139,9 @@ This is not configurable and there is no generator to register. If you need a di
 
 Two changes matter.
 
-**Numbers are sequential by default.** Stores upgrading from 5.x keep every existing number untouched, but new documents get sequential numbers starting at 1001. To keep the old behavior, set the store's numbering format to **Random** in Settings → Store → Order numbers.
+**Numbers are sequential by default.** Existing numbers are never rewritten, and new documents get sequential numbers starting at 1001. To keep the old behavior, set the store's numbering format to **Random** in Settings → Store → Order numbers.
 
-**`Spree::Core::NumberGenerator` is deprecated.** Models using it still work through Spree 6.0 and log a deprecation warning. Replace it with the concern:
+**`Spree::Core::NumberGenerator` is deprecated.** Models using it still work and log a deprecation warning, but will stop working in a future release. Replace it with the concern:
 
 ```ruby
 # before

package/dist/developer/how-to/custom-promotion.md

@@ -61,7 +61,7 @@ end
 
 The `options` hash passed to `eligible?` can include `:user`, `:email`, and other context from the checkout flow.
 
-> **WARNING:** Accept **both** `Spree::Cart` and `Spree::Order` in `applicable?`. Promotions are evaluated on every cart change, long before the cart becomes an order, and in Spree 6 a cart is its own model rather than an unfinished order. A rule guarding on `Spree::Order` alone silently never applies during checkout — the promotion just appears not to work. Every built-in rule accepts both.
+> **WARNING:** Accept **both** `Spree::Cart` and `Spree::Order` in `applicable?`. Promotions are evaluated on every cart change, long before the cart becomes an order, and a cart is its own model rather than an unfinished order. A rule guarding on `Spree::Order` alone silently never applies during checkout — the promotion just appears not to work. Every built-in rule accepts both.
 
 #### Using Preferences
 

package/dist/developer/how-to/sell-digital-products.md

@@ -3,7 +3,7 @@ title: Sell Digital Products
 description: Digital goods in Spree — a digital delivery profile, instant fulfillment without a shipping address, and delivering files or entitlements after payment.
 ---
 
-Digital products skip the warehouse: no stock to reserve, no address to collect, no carrier to call. In Spree 6 that behavior comes from the product's delivery profile — assign a digital profile and checkout, fulfillment and the customer experience adapt. This guide walks through selling an uploaded file end to end.
+Digital products skip the warehouse: no stock to reserve, no address to collect, no carrier to call. That behavior comes from the product's delivery profile — assign a digital profile and checkout, fulfillment and the customer experience adapt. This guide walks through selling an uploaded file end to end.
 
 For the concepts behind each piece — assets, links, allowances, providers — see [Products → Digital products](../core-concepts/products.md#digital-products). This page is the practical walkthrough.
 

package/dist/developer/providers/dam.md

@@ -3,7 +3,9 @@ title: Product Media & DAM
 description: Media hosted in your DAM stays in your DAM — Spree stores the address, not a copy of the bytes, and renders it through the same pipeline as uploaded media.
 ---
 
-> **NOTE:** This page documents functionality landing in an upcoming Spree 6.0 release. The interfaces described here may change before final release.
+## Coming soon
+
+> **NOTE:** The following features are on the open-source roadmap. The interfaces described here may change before release.
 
 If your media lives in a digital asset management system or a CDN you already operate, importing copies into Spree doubles your storage and guarantees drift. Externally hosted media makes the address the record: Spree stores a URL, renders it wherever uploaded media renders, and your DAM remains the source of truth for the asset itself.
 

package/dist/developer/providers/erp.md

@@ -3,7 +3,9 @@ title: Connect Your ERP
 description: Keep your ERP as the source of truth for stock. Spree syncs inventory in, answers availability from its own snapshot, and asks your ERP live only at the moments that matter.
 ---
 
-> **NOTE:** This page documents functionality landing in an upcoming Spree 6.0 release. The interfaces described here may change before final release.
+## Coming soon
+
+> **NOTE:** The following features are on the open-source roadmap. The interfaces described here may change before release.
 
 Your ERP owns inventory truth. Spree's job is to sell against it without keeping a copy that drifts — and without making every product page wait on an ERP round trip.
 

package/dist/developer/providers/pim.md

@@ -3,7 +3,9 @@ title: Connect Your PIM
 description: Keep product data and pricing in your PIM. Spree syncs content in, renders from its own copy, and can price live from an external source at cart decision moments.
 ---
 
-> **NOTE:** This page documents functionality landing in an upcoming Spree 6.0 release. The interfaces described here may change before final release.
+## Coming soon
+
+> **NOTE:** The following features are on the open-source roadmap. The interfaces described here may change before release.
 
 Your PIM owns product content — names, descriptions, attributes, associations, prices. Spree renders the shopper-facing copy and asks your systems live only where a stale answer would cost money.
 

package/dist/developer/providers/sso.md

@@ -3,7 +3,7 @@ title: Identity & SSO
 description: Single sign-on with OpenID Connect is built into Spree — connect your existing identity provider for staff and customer authentication without custom code.
 ---
 
-Enterprises already have an identity provider. Staff accounts live in it, security policy is enforced through it, and a commerce platform that demands its own password database is a liability. Spree 6 ships OpenID Connect support in core.
+Enterprises already have an identity provider. Staff accounts live in it, security policy is enforced through it, and a commerce platform that demands its own password database is a liability. Spree ships OpenID Connect support in core.
 
 ## Staff single sign-on
 

package/dist/developer/tutorial/dashboard.md

@@ -0,0 +1,307 @@
+---
+title: Dashboard
+description: Add Brands management to the dashboard of a create-spree-app project — a list page, navigation, a typed Admin API client and a card on the product page.
+---
+
+Staff need a place to manage brands. The back office is a React app that lives in your project at `apps/dashboard/`, and you add screens to it by editing that app's own code.
+
+The dashboard talks to the Admin API you generated in step 1. That is the only data source — it never reaches into the Server app’s models or renders server HTML.
+
+## Where this code goes
+
+A project created with `create-spree-app` has this shape:
+
+```
+my-store/
+├── apps/
+│   ├── dashboard/          # the admin SPA — you edit this
+│   │   ├── src/
+│   │   │   ├── main.tsx
+│   │   │   ├── plugins.ts  # ← your customizations start here
+│   │   │   └── routeTree.gen.ts
+│   │   ├── package.json
+│   │   └── vite.config.ts
+│   ├── seller-dashboard/
+│   └── storefront/
+└── server/                  # the Server app from step 1
+```
+
+`apps/dashboard/src/plugins.ts` ships empty, imported once by `main.tsx` before the dashboard renders. Everything in this step goes there or in files next to it.
+
+The file and the `defineDashboardPlugin` function are named for the registries they talk to, not for how the code ships. A distributed package and your own app call the same function with the same options — the only difference is where the file lives.
+
+> **NOTE:** Everything here is an ordinary file in your dashboard app, committed and deployed with the rest of your project. Publishing a package is only worth it when you want to reuse the same screens across several stores — the registrations are identical either way, so moving one into a package later is a copy, not a rewrite. See [dashboard plugins](../dashboard/plugins/overview.md).
+
+`@spree/dashboard-core` (registries, providers and hooks) and `@spree/dashboard-ui` (the design system) come installed with the dashboard, so you can import from them straight away.
+
+## Step 1: A typed client for the endpoint
+
+Wrap the Admin API calls in one file so pages never call `request` directly. `adminClient` carries authentication, retries and error handling for you — see [talking to the backend](../dashboard/customization/backend.md) for custom endpoints, React-Query hooks and error handling:
+
+```ts apps/dashboard/src/brands/client.ts
+import type { PaginatedResponse } from '@spree/admin-sdk'
+import { adminClient } from '@spree/dashboard'
+
+export interface Brand {
+  id: string
+  name: string
+  slug: string | null
+  active: boolean
+  created_at: string
+  updated_at: string
+}
+
+export interface BrandCreateParams {
+  name: string
+  slug?: string
+  active?: boolean
+}
+
+type ListParams = Record<string, string | number | boolean | undefined>
+
+export const BrandsClient = {
+  list: (params?: ListParams) =>
+    adminClient.request<PaginatedResponse<Brand>>('GET', '/brands', { params }),
+
+  get: (id: string) => adminClient.request<Brand>('GET', `/brands/${id}`),
+
+  create: (body: BrandCreateParams) =>
+    adminClient.request<Brand>('POST', '/brands', { body }),
+
+  update: (id: string, body: Partial<BrandCreateParams>) =>
+    adminClient.request<Brand>('PATCH', `/brands/${id}`, { body }),
+
+  delete: (id: string) => adminClient.request<void>('DELETE', `/brands/${id}`),
+}
+```
+
+Paths are relative to `/api/v3/admin`, so `'/brands'` reaches the controller from step 1. The `Brand` interface matches what your Admin serializer returns, timestamps included.
+
+## Step 2: Describe the table
+
+`defineTable` declares the columns, sorting, search and empty state. The dashboard renders it with the same table chrome as Products and Orders:
+
+```tsx apps/dashboard/src/plugins.ts
+import { RelativeTime, defineTable, i18n } from '@spree/dashboard'
+import type { Brand } from './brands/client'
+
+defineTable<Brand>('brands', {
+  title: i18n.t('admin.brands.table.title'),
+  searchParam: 'search',
+  defaultSort: { field: 'name', direction: 'asc' },
+  emptyMessage: i18n.t('admin.brands.table.empty'),
+  columns: [
+    {
+      key: 'name',
+      label: i18n.t('admin.brands.fields.name'),
+      sortable: true,
+      filterable: true,
+      default: true,
+      render: (record) => <span className="font-medium text-foreground">{record.name}</span>,
+    },
+    {
+      key: 'created_at',
+      label: i18n.t('admin.brands.fields.created_at'),
+      sortable: true,
+      default: true,
+      render: (record) => <RelativeTime iso={record.created_at} />,
+    },
+  ],
+})
+```
+
+`name` is `sortable` and `filterable` because the model allowlisted it in step 1. A column that sorts by an attribute the backend does not permit fails at request time, so the two lists have to agree.
+
+This is the short version. [Tables](../dashboard/customization/tables.md) documents every field of a [column definition](../dashboard/customization/tables.md#column-definition), plus [bulk actions, row actions and drag reordering](../dashboard/customization/tables.md#bulk-actions-row-actions-reordering) — and how to [add or remove columns on a built-in table](../dashboard/customization/tables.md#add-a-column-to-a-built-in-table) such as products or orders.
+
+> **WARNING:** Every visible string goes through i18next — column labels, titles, buttons, empty states. Never hardcode English into a table definition or into JSX, and add each new key to every locale file your project ships. See [translations](../dashboard/customization/translations.md) for the field-key convention and how server-side validation messages are resolved.
+
+## Step 3: Build the list page
+
+`ResourceTable` supplies filtering, sorting and pagination against the table you just declared:
+
+```tsx apps/dashboard/src/brands/list-page.tsx
+import { Button, PageHeader, ResourceLayout, ResourceTable, type ResourceSearch } from '@spree/dashboard'
+import { PlusIcon } from 'lucide-react'
+import { useTranslation } from 'react-i18next'
+import { type Brand, BrandsClient } from './client'
+
+export function BrandsListPage({ searchParams }: { searchParams: Record<string, unknown> }) {
+  const { t } = useTranslation()
+
+  return (
+    <ResourceLayout
+      header={
+        <PageHeader
+          title={t('admin.brands.page.title')}
+          // A create form is the natural next step — see the recipes below.
+          actions={
+            <Button size="sm" disabled>
+              <PlusIcon className="size-4" />
+              {t('admin.brands.page.new_cta')}
+            </Button>
+          }
+        />
+      }
+      main={
+        <ResourceTable<Brand>
+          tableKey="brands"
+          queryKey="brands"
+          queryFn={(params) => BrandsClient.list(params as Record<string, never>)}
+          searchParams={searchParams as ResourceSearch}
+        />
+      }
+    />
+  )
+}
+```
+
+## Step 4: Register navigation, the route and a product card
+
+Back in `plugins.ts`, `defineDashboardPlugin` wires the page into the app:
+
+```tsx apps/dashboard/src/plugins.ts
+import { defineDashboardPlugin, i18n } from '@spree/dashboard'
+import { PackageIcon } from 'lucide-react'
+import { BrandsListPage } from './brands/list-page'
+import { BrandCard } from './brands/product-card'
+
+defineDashboardPlugin({
+  nav: [
+    {
+      key: 'brands',
+      label: i18n.t('admin.brands.nav'),
+      path: '/brands',
+      icon: PackageIcon,
+      position: 50,
+    },
+  ],
+  routes: [{ key: 'brands', path: '/brands', component: BrandsListPage }],
+  slots: {
+    'product.form_sidebar': [
+      { id: 'brand-card', component: BrandCard as never, position: 250 },
+    ],
+  },
+})
+```
+
+Three extension points are doing the work, each with its own reference page:
+
+| Option | What it does | Full documentation |
+|---|---|---|
+| `nav` | Adds the sidebar entry; `position` places it among the built-in items | [Navigation](../dashboard/customization/navigation.md) — settings sub-nav, removing and patching built-in entries |
+| `routes` | Mounts the page under the authenticated store layout, so it becomes `/:storeId/brands` | [Routes](../dashboard/customization/routes.md#runtime-route-registry-in-app-dynamic) — path params, layout and permission gating |
+| `slots` | Injects a component where the dashboard already renders one | [Slots](../dashboard/customization/slots.md) and the [slots catalog](../dashboard/slots-catalog.md) — every slot and the context it passes |
+
+`product.form_sidebar` is what makes brands useful to the person editing a product: the product page knows nothing about brands, and the slot registry is what puts your card there.
+
+> **TIP:** Hiding a nav entry or a column behind a permission is [one option away](../dashboard/customization/permissions.md) — but hiding is never authorising. The Admin API still has to refuse the request, which is why step 1 left authorization to you.
+
+Showing the current brand is not much use on its own — the point is to change
+it. The product page is one big form with a single Save button, and
+`product.form_sidebar` renders **inside** that form, so the card can own an
+input without owning any save logic.
+
+Two pieces make that work. First, tell the form the field exists and where its
+value comes from on load:
+
+```tsx apps/dashboard/src/plugins.ts
+defineDashboardPlugin({
+  formFields: {
+    // `from` receives the fetched product, or null on the create form.
+    product: [{ name: 'brand_id', from: (product) => product?.brand_id ?? null }],
+  },
+})
+```
+
+Then render the input, binding it to the host form with `useHostForm()`. No
+`<form>` of your own, no Save button, no mutation — dirty tracking, the PATCH
+payload and re-baselining after save all stay with the page:
+
+```tsx apps/dashboard/src/brands/product-card.tsx
+import {
+  Card, CardContent, CardHeader, CardTitle,
+  Field, FieldLabel,
+  ResourceCombobox,
+  useHostForm,
+} from '@spree/dashboard'
+import { Controller } from 'react-hook-form'
+import { useTranslation } from 'react-i18next'
+import { BrandsClient } from './client'
+
+export function BrandCard() {
+  const { t } = useTranslation()
+  const form = useHostForm<{ brand_id: string | null }>()
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{t('admin.brands.product_card.title')}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Field>
+          <FieldLabel className="sr-only" htmlFor="brand_id">
+            {t('admin.brands.product_card.title')}
+          </FieldLabel>
+          <Controller
+            control={form.control}
+            name="brand_id"
+            render={({ field }) => (
+              <ResourceCombobox
+                id="brand_id"
+                queryKey="product-brand-picker"
+                value={field.value ?? ''}
+                onChange={(id) => field.onChange(id ?? null)}
+                getOptionLabel={(brand) => brand.name}
+                placeholder={t('admin.brands.product_card.placeholder')}
+                emptyText={t('admin.brands.product_card.none')}
+                search={(query) => BrandsClient.list({ name_cont: query })}
+                hydrate={(ids) => BrandsClient.list({ id_in: ids })}
+              />
+            )}
+          />
+        </Field>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+`ResourceCombobox` searches the API as the merchant types rather than loading
+every brand up front, which is what keeps the picker usable on a catalogue
+with thousands of them. `hydrate` resolves the saved ID back to a name so the
+trigger reads correctly on first render.
+
+For this to persist, the Admin API has to accept `brand_id` on the product —
+the `resource_permitted_attributes` half of the association you set up in
+step 1.
+
+> **NOTE:** A field that merchants should be able to define themselves, rather than one
+>   your code adds as a column, is usually better as a [custom field](../core-concepts/metafields.md) — no code at all. See [adding a custom form field](../dashboard/recipes/custom-form-field.md) for both paths.
+
+## Step 5: Run it
+
+`spree dev` runs the Server app and the dashboard together:
+
+```bash
+spree dev
+```
+
+Open the dashboard at `http://localhost:5173`. **Brands** appears in the sidebar, the list reads your Admin API endpoint from step 1, and the product edit page shows the card.
+
+> **TIP:** Adding a create or edit form next? Wrap `handleSubmit` in a try/catch that calls `mapSpreeErrorsToForm` so 422 responses land on the right fields, and gate any delete that fires straight from a click behind `useConfirm()` with `variant: 'destructive'`.
+
+## Going further
+
+This step used a handful of the dashboard's extension points. The reference documentation covers the rest:
+
+
+  - [Customization quickstart](../dashboard/customization/quickstart.md) — The same ground in five minutes, without the Brands feature around it
+  - [Public API](../dashboard/public-api.md) — Every component, hook, registry and provider you can safely import
+  - [Concepts](../dashboard/concepts.md) — The mental model — what each layer does and where your code fits
+  - [Recipes](../dashboard/recipes/attribute-end-to-end.md) — Worked examples: a custom form field, a page action, a sidebar widget
+
+
+## Next step
+
+Staff can manage brands. Now show them to customers: [Storefront](storefront.md).

package/dist/developer/tutorial/events.md

@@ -1,12 +1,72 @@
 ---
 title: Events
-description: Publish lifecycle events for FAQs and react to them — subscribers inside the app, webhooks for systems outside it.
+description: Publish lifecycle events for Brands and react to them — subscribers inside your Spree app, outbound webhooks for systems you do not deploy code into.
 ---
 
-Features rarely live alone — something usually needs to know when data changes. This chapter publishes lifecycle events for FAQs and consumes them both ways.
+Features rarely live alone. A search index needs to know when a brand is renamed; a PIM wants to hear about new ones. In Spree the integration surface is the **events system**: models publish events as things happen, and you react without touching core code.
 
-## What this chapter covers
+There are two ways to consume an event, and they serve different audiences:
 
-- Publishing lifecycle events from the model
-- A subscriber reacting inside the application
-- Delivering the event to an external system as a webhook
+| Mechanism | Code lives | Best for |
+|---|---|---|
+| **Subscriber** | In your Spree app | Calling external APIs with your own client code, internal side effects, anything needing app context |
+| **Webhook** | In the external system | Letting a third party receive HTTP callbacks — no backend code in your app, endpoints managed from the dashboard |
+
+## Step 1: Publish lifecycle events
+
+Core models publish `*.created`, `*.updated` and `*.deleted` automatically. Your models do too, with one line:
+
+```ruby server/app/models/spree/brand.rb
+publishes_lifecycle_events
+```
+
+Now `brand.created`, `brand.updated` and `brand.deleted` fire after the matching transaction commits. The payload is the record serialized with the v3 serializer you generated in step 1 — the events system resolves it by naming convention. Every consumer sees the same JSON shape your API serves, which is the point: one contract, not two.
+
+## Step 2: React inside the app
+
+Generate a subscriber:
+
+```bash
+spree generate subscriber BrandSync brand.created brand.updated
+```
+
+This creates the subscriber, a spec stub, and — crucially — **registers it** in `config/initializers/spree.rb`. Subscribers are not auto-discovered: one that never gets appended to `Spree.subscribers` is a silent no-op, which is why the generator owns that step. Re-runs are idempotent.
+
+Fill in the handler:
+
+```ruby server/app/subscribers/brand_sync_subscriber.rb
+def handle(event)
+  SearchIndexer.upsert_brand(id: event.payload['id'], name: event.payload['name'])
+end
+```
+
+Two things worth understanding:
+
+- **The payload is the record, already serialized.** It is the same JSON your API returns, so `event.payload['name']` is there without a database query. IDs in it are public ones (`brand_k5nR8xLq`); when you do need the full record, look it up with `Spree::Brand.find_by_prefix_id(event.payload['id'])` rather than treating the id as a row number.
+- **Subscribers run asynchronously by default.** Each `handle` call is an ActiveJob, so a slow third-party API never blocks the request that triggered it. Pass `subscribes_to 'brand.created', async: false` only when you genuinely need it synchronous.
+
+Restart the server, rename a brand in the dashboard, and watch the job run.
+
+## Step 3: Publish a custom event
+
+Lifecycle events cover persistence. Custom events express *domain* moments — something meaningful happened, not just a row changed:
+
+```ruby
+brand.publish_event('brand.featured')
+```
+
+The payload defaults to the serializer output; pass your own hash as a second argument when the event needs different data. Subscribers consume it exactly like any built-in event.
+
+## Step 4: Deliver to external systems with webhooks
+
+When the consumer is a system you do not deploy your own code into, use a webhook instead. In the dashboard go to **Settings → Webhooks**, add an endpoint URL, and select the events to deliver — `brand.created` and anything else publishing in your store.
+
+Each delivery is an HTTP POST carrying the event name and the same serialized payload. The endpoint's **signing secret is shown once when you create it**: store it in the receiving system and verify every request against it, so the receiver can prove the call came from your store.
+
+Deliveries are retried with exponential backoff, and the dashboard shows the attempt history per endpoint, which is where to look when a third party says they never received something.
+
+> **TIP:** Webhooks need no code in your app at all. Reach for a subscriber only when the reaction needs application context or credentials you would rather not hand to a third party. See [events](../core-concepts/events.md) and [webhooks](../core-concepts/webhooks.md).
+
+## Next step
+
+The feature is complete across every layer. Now prove it works: [Testing](testing.md).