Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Added extension slots to detail pages and form-saved plugin fields (#14784)

Damian Legawieca4baf4900f24
diff --git a/.changeset/dashboard-detail-page-slots.md b/.changeset/dashboard-detail-page-slots.md
new file mode 100644
index 0000000000..5473a544ad
--- /dev/null
+++ b/.changeset/dashboard-detail-page-slots.md
@@ -0,0 +1,6 @@
+---
+"@spree/dashboard": minor
+"@spree/seller-dashboard": minor
+---
+
+Plugins can now add cards to more detail pages. The admin dashboard has new slots on the seller payout, catalog, price list, promotion, purchase order, stock transfer and webhook endpoint pages, and the catalog, price list and promotion pages now save extension fields bound with `useHostForm()` with the page's own Save button. The seller panel has new slots on its product, order, payout and profile pages, and its product page saves extension fields the same way, under the form key `seller.product`. The slots catalog lists every slot and the context it receives.
diff --git a/CLAUDE.md b/CLAUDE.md
index f81223907d..d20b2de758 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -602,6 +602,8 @@ The starter is the canonical host — the same app `spree add dashboard` scaffol
2. **Follow `docs/plans/6.0-admin-spa.md`** for the three extension points (table registry, navigation registry, component injection) and the shadcn copy-paste ownership model.
3. **Wrap SDK calls in custom hooks** under `src/hooks/` (e.g. `useOrders`, `useProduct`) — never call `adminClient` directly from components.
+**Every detail page exposes slots.** A new or reworked resource detail page (admin dashboard and seller panel alike) renders `<Slot name="<resource>.form_sidebar">` at the end of its sidebar column — plus `<resource>.form_main` when the main column is where plugin cards belong — with the record in the context (`{ <resource> }`), and gets an entry in `docs/developer/dashboard/slots-catalog.mdx` in the same change. Seller panel slots are named `seller.<page>.<area>`. **A slot inside a page's form must be a host form:** wrap the form in `<FormProvider>`, seed `extensionFormValues('<resource>', record)` into its defaults and hydration reset, and merge `extensionSubmitValues('<resource>', form)` into the save payload (and the post-save reset), so fields a plugin binds with `useHostForm()` save with the page's Save button. The matching API controller must accept extension attributes — use `resource_permitted_attributes`, or splat `*model_additional_permitted_attributes` into a hand-written `permitted_params`. Seller API controllers splat `*model_class.additional_seller_permitted_attributes` instead, so an attribute opened to operators never becomes seller-writable by accident. Reference: `routes/_authenticated/$storeId/products/collections/$collectionId.tsx`.
+
**Translations.** Every user-visible string in `@spree/dashboard` goes through i18next — page titles, headings, table column labels, button labels, empty states, toast messages, confirm dialog copy, select option labels, badges, status text, tooltips, helper text. Never hardcode English (or any language) into JSX, into table column definitions, or into dropdown option arrays. Keys live in `packages/dashboard/src/locales/en.json` (app-specific copy) or `packages/dashboard-core/src/locales/en.json` (cross-cutting: `admin.common.*`, `admin.fields.<attribute>.<facet>`). Reach for `i18n.t(...)` at module load (table definitions) and `useTranslation().t(...)` inside components. **Schemas in `src/schemas/` hold canonical values only — never label strings.** Build `{ value, label }` pairs at render time inside the component by mapping the canonical value list against translation keys. When adding a new translation key, ALWAYS add it to the all languages files in `packages/dashboard/src/locales/` and `packages/dashboard-core/src/locales/`.
**Destructive actions need a confirm — unless a sheet already gates them.** Any action that destroys or detaches data and fires **straight from a click** must go through `useConfirm()` with `variant: 'destructive'` first: row-level delete/remove buttons, and every bulk action that runs immediately. Bulk actions that open a picker sheet or dialog (`BulkAction.form`, `ResourcePickerSheet`) already require an explicit submit — that IS the confirmation, so don't stack a second dialog on top. `BulkAction` takes a `confirm` option (`{n}` interpolates the count) for the immediate case.
diff --git a/docs/developer/customization/api.mdx b/docs/developer/customization/api.mdx
index 0c4851bbc8..17dc389761 100644
--- a/docs/developer/customization/api.mdx
+++ b/docs/developer/customization/api.mdx
@@ -213,6 +213,19 @@ already permits replaces its filter rather than widening it.
that add real database columns.
</Note>
+### Writable by sellers
+
+The Seller API accepts a narrower set of attributes than the Admin API, so the
+list above does not apply to it — an attribute you open to operators stays
+operator-only. To let sellers write it too, for example from a field on the
+seller panel's product page, declare it again on the seller list:
+
+```ruby config/initializers/spree.rb
+Spree::Product.additional_seller_permitted_attributes += [:brand_id]
+```
+
+Only declare attributes a seller may safely set on their own records.
+
Two endpoints deliberately ignore this hook because their parameters are
authorization data rather than resource data: API keys and invitations.
diff --git a/docs/developer/dashboard/customization/slots.mdx b/docs/developer/dashboard/customization/slots.mdx
index f2796645a8..cda7e7d7c8 100644
--- a/docs/developer/dashboard/customization/slots.mdx
+++ b/docs/developer/dashboard/customization/slots.mdx
@@ -79,7 +79,7 @@ The entry-level `if` predicate also exists, but it only receives the slot's own
## Binding to the host form
-Slots on form pages (product, category, store settings — see the [slots catalog](/developer/dashboard/slots-catalog#detail-page-form-slots) for which) render **inside the page's `<form>`** and expose its react-hook-form instance. A widget can register inputs against it with `useHostForm()` — they hydrate from the API, flip the Save button on change, and persist in the page's own save, with no save logic in the widget:
+Slots on form pages (product, category, collection, catalog, price list, promotion, store settings — see the [slots catalog](/developer/dashboard/slots-catalog#detail-page-slots) for which) render **inside the page's `<form>`** and expose its react-hook-form instance. A widget can register inputs against it with `useHostForm()` — they hydrate from the API, flip the Save button on change, and persist in the page's own save, with no save logic in the widget:
```tsx
import { useHostForm } from '@spree/dashboard'
diff --git a/docs/developer/dashboard/recipes/custom-form-field.mdx b/docs/developer/dashboard/recipes/custom-form-field.mdx
index fd4bab8c6f..759af696c3 100644
--- a/docs/developer/dashboard/recipes/custom-form-field.mdx
+++ b/docs/developer/dashboard/recipes/custom-form-field.mdx
@@ -157,7 +157,7 @@ Extension fields are validated by the **server** — a Rails validation failing
### 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.
+`useHostForm()` works wherever a built-in form exposes its form context — currently the **product** (edit + new), **category** (edit + new), **collection**, **catalog**, **price list** (edit + new), **promotion** (edit + new), and **store settings** forms, with matching slots (`product.form_sidebar`, `category.form_sidebar`, `collection.form_sidebar`, `catalog.form_sidebar`, `price_list.form_sidebar`, `promotion.form_sidebar`, `store.form_main`) and form keys (`product`, `category`, `collection`, `catalog`, `price_list`, `promotion`, `store`). The [slots catalog](/developer/dashboard/slots-catalog#detail-page-slots) marks which pages have a host form. 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?
diff --git a/docs/developer/dashboard/slots-catalog.mdx b/docs/developer/dashboard/slots-catalog.mdx
index 8f1d33da32..c914053b65 100644
--- a/docs/developer/dashboard/slots-catalog.mdx
+++ b/docs/developer/dashboard/slots-catalog.mdx
@@ -4,10 +4,36 @@ sidebarTitle: Slots catalog
description: Every named slot the dashboard renders today. Each entry lists the host page, the slot name, and the context the slot's components receive.
---
-This is the canonical list of slots the dashboard currently exposes. The source of truth is the `<Slot name="…">` call sites in the dashboard source (linked under Reference below); each entry here records the host page, the slot name, and the context your component receives.
+This is the canonical list of slots the admin dashboard and the seller panel currently expose. The source of truth is the `<Slot name="…">` call sites in the dashboard source (linked under Reference below); each entry here records the host page, the slot name, and the context your component receives.
If you need a new injection point in a built-in page, open a PR adding `<Slot name="..." context={...} />` and a documentation entry here — that's the contract for new slots.
+## At a glance
+
+| Area | Page | Slots |
+|---|---|---|
+| Every page | Page header | `page.actions`, `page.actions_dropdown` |
+| Every page | Tabbed sub-navigation | `page.tabs` |
+| Products | Product | `product.form_sidebar` |
+| Products | Category | `category.form_sidebar` |
+| Products | Collection | `collection.form_sidebar` |
+| Products | Catalog | `catalog.form_sidebar` |
+| Products | Price list | `price_list.form_sidebar`, `price_list.rule_form.<type>` |
+| Orders | Order | `order.form_sidebar` |
+| Customers | Customer | `customer.form_sidebar` |
+| Customers | Company | `company.form_main`, `company.form_sidebar`, `company_membership.*` |
+| Promotions | Promotion | `promotion.form_sidebar`, `promotion.rule_form.<type>`, `promotion.action_form.<type>` |
+| Inventory | Purchase order | `purchase_order.form_sidebar` |
+| Inventory | Stock transfer | `stock_transfer.form_sidebar` |
+| Sellers | Seller | `seller.form_main`, `seller.form_sidebar` |
+| Sellers | Seller payout | `seller_payout.form_main`, `seller_payout.form_sidebar` |
+| Settings | Store | `store.form_main` |
+| Settings | Payment method | `payment_method.*.<provider>` |
+| Settings | Webhook endpoint | `webhook_endpoint.form_sidebar` |
+| Onboarding | Getting started | `getting-started.task.<name>` |
+| Sign-in | No store access | `no_store_access` |
+| Seller panel | Product, order, payout, profile, team | `seller.product.*`, `seller.order.*`, `seller.payout.*`, `seller.profile.*`, `seller.team.*` |
+
## Ambient context
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:
@@ -43,13 +69,32 @@ Rendered by `<PageHeader>` (`@spree/dashboard-core/components/page-header.tsx`)
| Use | Add menu items (`<DropdownMenuItem>`) for secondary actions |
| Context | `{ resource, ...slotContext }` — same as `page.actions` |
-## Detail-page form slots
+## Page tabs slot
+
+### `page.tabs` (default)
+
+Rendered by `<PageTabs>` at the right edge of any tabbed sub-nav.
+
+| Where | After the built-in tab strip |
+|---|---|
+| Use | Append your own tab(s) to a sub-route — typically for plugin-owned views inside an existing resource (e.g., "Returns" tab on the order detail) |
+| Context | `{ tabs, ...slotContext }` — `tabs` is the array of built-in tabs (so you can inspect or filter by them) |
+
+Some pages override `slotName` to scope tabs to a single resource (e.g., `slotName="order.tabs"`). The catalog will grow these as we wire them up; today only the default `page.tabs` name is in production use.
+
+## Detail-page slots
+
+Every resource detail page renders a slot at the end of its sidebar column, and some also at the end of the main column. The slot name starts with the resource name, and the context key matches it.
-The resource detail pages each render a slot below their built-in cards. The context key matches the resource name.
+**Host form.** On pages marked *host form: yes*, the slot renders inside the page's own `<form>` and exposes it — widgets can bind inputs via [`useHostForm()`](/developer/dashboard/recipes/custom-form-field) that hydrate, dirty-track, and save with the page's Save button. The form key is what you register extension fields under in `formFields`. On every other page, widgets own their persistence; use `useOptionalHostForm()` to write a widget that adapts to both.
-**Host form:** on pages marked *host form: yes*, the slot renders inside the page's own `<form>` and the form context is exposed — widgets can bind inputs via [`useHostForm()`](/developer/dashboard/recipes/custom-form-field) that hydrate, dirty-track, and save with the page's Save button. On pages without one, widgets own their persistence (use `useOptionalHostForm()` to adapt).
+<Note>
+On host-form pages your widget renders inside the page's `<form>` element, so a `<Button>` in it submits the page unless you give it `type="button"`.
+</Note>
-### `product.form_sidebar`
+### Products
+
+#### `product.form_sidebar`
| Where | Product detail page (`products/$productId`), end of the sidebar column |
|---|---|
@@ -57,7 +102,7 @@ The resource detail pages each render a slot below their built-in cards. The con
| Context | `{ product }` — the full `Product` record from the Admin API |
| Host form | **Yes** — form key `product` |
-### `category.form_sidebar`
+#### `category.form_sidebar`
| Where | Category detail page (`products/categories/$categoryId`), end of the sidebar column |
|---|---|
@@ -65,15 +110,33 @@ The resource detail pages each render a slot below their built-in cards. The con
| Context | `{ category }` — the `Category` record (may be briefly `undefined` while refetching) |
| Host form | **Yes** — form key `category` |
-### `store.form_main`
+#### `collection.form_sidebar`
-| Where | Store settings page (`settings/store`), end of the main column |
+| Where | Collection detail page (`products/collections/$collectionId`), end of the sidebar column |
|---|---|
-| Use | Store-level settings a plugin owns — integration toggles, account linking |
-| Context | `{ store }` — the full `Store` record |
-| Host form | **Yes** — form key `store` |
+| Use | Collection-scoped cards — merchandising rules, feed settings, external sync state |
+| Context | `{ collection }` — the `Collection` record |
+| Host form | **Yes** — form key `collection` |
-### `order.form_sidebar`
+#### `catalog.form_sidebar`
+
+| Where | Catalog detail page (`products/catalogs/$catalogId`), end of the sidebar column |
+|---|---|
+| Use | B2B catalog cards — ERP contract references, approval state, export settings |
+| Context | `{ catalog, canEdit }` — the `Catalog` record; `canEdit` is whether the viewer may update it |
+| Host form | **Yes** — form key `catalog` |
+
+#### `price_list.form_sidebar`
+
+| Where | Price list create and detail pages (`products/price-lists/new`, `products/price-lists/$priceListId`), end of the sidebar column |
+|---|---|
+| Use | Price-list cards — sync state with an external pricing engine, audit notes |
+| Context | `{ priceList, mode }` — `mode` is `'create'` or `'edit'`; `priceList` is `undefined` in create mode |
+| Host form | **Yes** — form key `price_list` |
+
+### Orders and customers
+
+#### `order.form_sidebar`
| Where | Order detail page (`orders/$orderId`), end of the sidebar column |
|---|---|
@@ -81,7 +144,7 @@ The resource detail pages each render a slot below their built-in cards. The con
| Context | `{ order }` — the full `Order` record |
| Host form | No — widgets save via their own API calls |
-### `customer.form_sidebar`
+#### `customer.form_sidebar`
| Where | Customer detail page (`customers/$customerId`), end of the sidebar column |
|---|---|
@@ -89,23 +152,15 @@ The resource detail pages each render a slot below their built-in cards. The con
| Context | `{ customer }` — the full `Customer` record |
| Host form | No — the page edits through sheets; widgets save via their own API calls |
-### `collection.form_sidebar`
-
-| Where | Collection detail page (`products/collections/$collectionId`), end of the sidebar column |
-|---|---|
-| Use | Collection-scoped cards — merchandising rules, feed settings, external sync state |
-| Context | `{ collection }` — the `Collection` record |
-| Host form | **Yes** — form key `collection` |
-
-### `company.form_main`
+#### `company.form_main`
-| Where | Company detail page, end of the main column |
+| Where | Company detail page (`companies/$companyId`), end of the main column |
|---|---|
| Use | B2B account cards — credit terms, approval settings, external account references |
| Context | `{ company, kind, canEdit }` — `kind` is the company's own `kind`, `canEdit` whether the viewer may write |
| Host form | No — the widget owns its persistence |
-### `company.form_sidebar`
+#### `company.form_sidebar`
| Where | Company detail page, end of the sidebar column |
|---|---|
@@ -113,81 +168,187 @@ The resource detail pages each render a slot below their built-in cards. The con
| Context | `{ company, kind, canEdit }` |
| Host form | No |
-## Seller panel slots
+#### Company membership slots
+
+The company's member list and its "Add member" sheet carry three smaller slots, built for an extension that gives members roles.
+
+| Slot | Where | Context |
+|---|---|---|
+| `company_membership.row_meta` | Under each member's email in the member list | `{ membership, companyId, canEdit }` |
+| `company_membership.row_actions` | Each member's actions menu, above "Remove member" — render `<DropdownMenuItem>`s | `{ membership, companyId }` |
+| `company_membership.form_fields` | The "Add member" sheet, below the email field. **Replaces** a built-in note about roles | `{ companyId, onChange }` — call `onChange(params)` and those params are merged into the request that adds the member |
+
+### Promotions
-Rendered by the marketplace seller panel (`@spree/seller-dashboard`) rather than the admin dashboard, and registered the same way.
+#### `promotion.form_sidebar`
-### `seller.form_main`
+| Where | Promotion create and detail pages (`promotions/new`, `promotions/$promotionId`), end of the sidebar column |
+|---|---|
+| Use | Campaign attribution, budget tracking, external coupon-system sync |
+| Context | `{ promotion, mode }` — `mode` is `'create'` or `'edit'`; `promotion` is `undefined` in create mode |
+| Host form | **Yes** — form key `promotion` |
+
+### Inventory
+
+#### `purchase_order.form_sidebar`
-| Where | Seller detail page, end of the main column |
+| Where | Purchase order detail page (`purchase-orders/$purchaseOrderId`), end of the sidebar column |
+|---|---|
+| Use | Supplier portal links, ERP sync status, landed-cost notes |
+| Context | `{ purchaseOrder }` — the full `PurchaseOrder` record |
+| Host form | No |
+
+#### `stock_transfer.form_sidebar`
+
+| Where | Stock transfer detail page (`transfers/$transferId`), end of the sidebar column |
+|---|---|
+| Use | Carrier tracking, warehouse-system sync status |
+| Context | `{ transfer }` — the full `StockTransfer` record |
+| Host form | No |
+
+### Sellers (marketplace)
+
+These slots are on the store owner's seller management pages in the admin dashboard. For the seller's own view, see the seller panel slots below.
+
+#### `seller.form_main`
+
+| Where | Seller detail page (`sellers/$sellerId`), end of the main column |
|---|---|
| Use | Seller-scoped cards — payout configuration, onboarding state, compliance records |
-| Context | `{ seller, canEdit }` |
+| Context | `{ seller, canEdit }` — the full `Seller` record; `canEdit` is whether the viewer may update it |
| Host form | No |
-### `seller.form_sidebar`
+#### `seller.form_sidebar`
| Where | Seller detail page, end of the sidebar column |
|---|---|
-| Use | Narrow seller-scoped cards |
+| Use | Narrow seller-scoped cards — risk score, verification status, external account links |
| Context | `{ seller, canEdit }` |
| Host form | No |
-### `seller.team.actions`
+#### `seller_payout.form_main`
-| Where | Seller team screen, in the header's action area |
+| Where | Seller payout detail page (`sellers/payouts/$payoutId`), end of the main column |
|---|---|
-| Use | Team-level actions — bulk invite, export, an external directory sync |
-| Context | `{ sellerId }` |
+| Use | Payout-scoped cards — remittance advice, the transfer as seen by the payment provider |
+| Context | `{ payout }` — the full `SellerPayout` record |
| Host form | No |
-### `seller.team.after`
+#### `seller_payout.form_sidebar`
-| Where | Seller team screen, below the member list |
+| Where | Seller payout detail page, end of the sidebar column |
|---|---|
-| Use | Anything that belongs under the team — audit log, role explainer, seat usage |
-| Context | `{ sellerId }` |
+| Use | Accounting-system sync status, links to the provider's dashboard |
+| Context | `{ payout }` |
| Host form | No |
-## Page tabs slot
+### Settings
-### `page.tabs` (default)
+#### `store.form_main`
-Rendered by `<PageTabs>` at the right edge of any tabbed sub-nav.
+| Where | Store settings page (`settings/store`), end of the main column |
+|---|---|
+| Use | Store-level settings a plugin owns — integration toggles, account linking |
+| Context | `{ store }` — the full `Store` record |
+| Host form | **Yes** — form key `store` |
-| Where | After the built-in tab strip |
+#### `webhook_endpoint.form_sidebar`
+
+| Where | Webhook endpoint detail page (`settings/webhooks/$webhookEndpointId`), end of the sidebar column |
|---|---|
-| Use | Append your own tab(s) to a sub-route — typically for plugin-owned views inside an existing resource (e.g., "Returns" tab on the order detail) |
-| Context | `{ tabs, ...slotContext }` — `tabs` is the array of built-in tabs (so you can inspect or filter by them) |
+| Use | Notes on the receiving system, links to its logs, a "send test event" action |
+| Context | `{ endpoint }` — the full `WebhookEndpoint` record |
+| Host form | No |
-Some pages override `slotName` to scope tabs to a single resource (e.g., `slotName="order.tabs"`). The catalog will grow these as we wire them up; today only the default `page.tabs` name is in production use.
+## Seller panel slots
+
+Rendered by the marketplace seller panel (`@spree/seller-dashboard`) rather than the admin dashboard, and registered the same way, in the seller panel's own plugins. Their names start with `seller.` followed by the page — `seller.form_main` and `seller.form_sidebar` above belong to the admin dashboard instead.
+
+The product page is a host form with the form key `seller.product`: fields a widget binds with `useHostForm()` save with the product. The Seller API accepts only the attributes your extension declares in `additional_seller_permitted_attributes` — see [Writable by sellers](/developer/customization/api#writable-by-sellers). The other seller panel pages have no page-wide form, so widgets there save via their own Seller API calls.
+
+| Slot | Where | Context |
+|---|---|---|
+| `seller.product.form_sidebar` | Product create and edit pages, end of the sidebar column | `{ product, mode }` — `mode` is `'new'` or `'edit'`; `product` is `undefined` while creating |
+| `seller.order.form_sidebar` | Order detail page, end of the sidebar column | `{ order }` |
+| `seller.payout.form_sidebar` | Payout detail page, end of the sidebar column | `{ payout }` |
+| `seller.profile.form_main` | Profile page, end of the main column | `{ profile }` |
+| `seller.profile.form_sidebar` | Profile page, end of the sidebar column | `{ profile }` |
+| `seller.team.actions` | Team page, in the header's action area — bulk invite, export, an external directory sync | `{ sellerId }` |
+| `seller.team.after` | Team page, below the member list — audit log, role explainer, seat usage | `{ sellerId }` |
+
+## Replaceable slots
+
+These slots render built-in content when nothing is registered. Registering a component **replaces** that content rather than adding to it.
+
+### `no_store_access`
+
+| Where | The screen shown to a signed-in admin who has a role on no store |
+|---|---|
+| Use | Replace the built-in "no access" message — for example, with a request-access form or a link to your own onboarding |
+| Context | `{ user, signOut }` — `user` is the signed-in admin; `signOut()` ends the session |
+
+Import the name as `NO_STORE_ACCESS_SLOT` from `@spree/dashboard-core` rather than typing it.
+
+### `getting-started.task.<name>`
+
+| Where | The body of one step on the Getting Started checklist (`getting-started`) |
+|---|---|
+| Use | Replace a step's description and link with your own flow — or give a setup task your extension added on the backend its own UI |
+| Context | `{ task, store, storeId }` — `task` is the `SetupTask` record (`name`, `done`, …) |
+
+`<name>` is the task's `name` as the API returns it.
+
+## Editor slots (dynamic)
+
+Promotions, price lists, and payment methods each pick their editor by type. The slot names are computed from the type's `api_type` shorthand, so registering against the right name is what hooks your editor in. The promotion and price list editor slots **replace** the built-in editor, which is generated from the type's preference schema.
+
+### `promotion.rule_form.<type>`
+
+| Where | The sheet that edits one promotion rule (e.g. `promotion.rule_form.product`) |
+|---|---|
+| Use | A custom editor for a rule whose settings don't fit the generated form |
+| Context | `{ draft, onSave, onClose }` — edit `draft` locally and call `onSave(next)`; the promotion saves everything when the merchant clicks Save |
+
+### `promotion.action_form.<type>`
+
+| Where | The sheet that edits one promotion action (e.g. `promotion.action_form.free_shipping`) |
+|---|---|
+| Use | A custom editor for an action — calculators, line-item pickers |
+| Context | `{ draft, onSave, onClose }` — same as rules |
+
+### `price_list.rule_form.<type>`
+
+| Where | The sheet that edits one price list rule (e.g. `price_list.rule_form.volume_rule`) |
+|---|---|
+| Use | A custom editor for a price rule |
+| Context | `{ draft, onSave, onClose }` — same as promotion rules |
-## Payment method editor slots (dynamic)
+### Payment method editor slots
Used by `<PaymentMethodForm>` to let payment-provider plugins replace pieces of the editor sheet. The slot names are computed per provider type (`stripe`, `bogus`, …), so registering against the right name is what hooks your editor in.
-### `payment_method.guide.<providerType>`
+#### `payment_method.guide.<providerType>`
| Where | Above the preferences form |
|---|---|
| Use | Banner explaining what the integration does, what credentials to use, links to provider docs |
| Context | `PaymentMethodEditorContext` (see below) |
-### `payment_method.form.<providerType>`
+#### `payment_method.form.<providerType>`
| Where | In place of the auto-generated preferences form |
|---|---|
| Use | Render a custom React form when the provider's preferences are too complex for the generated UI (multi-step OAuth, environment switchers, …) |
| Context | `PaymentMethodEditorContext` |
-### `payment_method.actions.<providerType>`
+#### `payment_method.actions.<providerType>`
| Where | Sheet footer, before Save/Cancel |
|---|---|
| Use | Provider-specific action buttons — "Test connection", "Rotate keys", "Open dashboard in provider" |
| Context | `PaymentMethodEditorContext` |
-### `PaymentMethodEditorContext`
+#### `PaymentMethodEditorContext`
```ts
interface PaymentMethodEditorContext {
@@ -219,10 +380,11 @@ Use these instead of constructing the string yourself, so a rename in one place
If a built-in page should expose a new injection point:
-1. Pick a name (`<resource>.<area>`, e.g., `order.timeline`)
+1. Pick a name (`<resource>.<area>`, e.g., `order.timeline`; `seller.<page>.<area>` in the seller panel)
2. Add `<Slot name="..." context={{ resource: order, /* ... */ }} />` at the call site
-3. Document the slot here — host, intent, context shape
-4. Open the PR
+3. If the slot sits inside the page's form, make it a host form: wrap the form in `<FormProvider>`, hydrate with `extensionFormValues('<resource>', record)`, and merge `extensionSubmitValues('<resource>', form)` into the save payload — the collection page is the reference
+4. Document the slot here — host, intent, context shape, and form key
+5. Open the PR
The slot is not "live" until the docs land — without an entry here, no plugin author knows it exists.
diff --git a/docs/developer/how-to/build-a-marketplace.mdx b/docs/developer/how-to/build-a-marketplace.mdx
index eadaacd074..ae335c9cda 100644
--- a/docs/developer/how-to/build-a-marketplace.mdx
+++ b/docs/developer/how-to/build-a-marketplace.mdx
@@ -726,7 +726,7 @@ Import everything from `@spree/seller-dashboard` — it re-exports both the fram
| Change wording | [Translations](/developer/dashboard/customization/translations) merged with `i18n.addResourceBundle` |
| Install a third-party plugin | `npm add <plugin>` and restart — the Vite plugin picks it up from your dependencies |
-The seller panel currently exposes just two slots, both on its team page: `seller.team.actions` and `seller.team.after`. (`seller.form_main` and `seller.form_sidebar` sound related but belong to the *admin* dashboard's seller detail page — they are for the operator's view of a seller, not the seller's own.) See the [slots catalog](/developer/dashboard/slots-catalog) for their contexts. To put a widget anywhere else in the panel, add a route rather than looking for a slot that is not there yet.
+The seller panel exposes slots on its product, order, payout, profile, and team pages — `seller.product.form_sidebar`, `seller.order.form_sidebar`, `seller.payout.form_sidebar`, `seller.profile.form_main` and `seller.profile.form_sidebar`, plus `seller.team.actions` and `seller.team.after`. The operator's side has its own: `seller.form_main` and `seller.form_sidebar` on the admin dashboard's seller page, and `seller_payout.form_main` and `seller_payout.form_sidebar` on its payout page. See the [slots catalog](/developer/dashboard/slots-catalog#seller-panel-slots) for each one's context. To put a widget anywhere else in the panel, add a route.
<Note>
**White-labelling is theming and copy, not a branding config object.** There is no logo or brand-name setting to fill in. You restyle by owning the Tailwind layer in your host app, and you re-word by overriding translation keys. Both are real customization paths — there is simply no shortcut that skips them.
diff --git a/packages/dashboard/src/components/spree/price-list-editors/price-list-form.tsx b/packages/dashboard/src/components/spree/price-list-editors/price-list-form.tsx
index 1bedd63982..a83fdc48a4 100644
--- a/packages/dashboard/src/components/spree/price-list-editors/price-list-form.tsx
+++ b/packages/dashboard/src/components/spree/price-list-editors/price-list-form.tsx
@@ -29,7 +29,13 @@ import {
} from '@spree/dashboard-ui/icons'
import { useQueryClient } from '@tanstack/react-query'
import { useEffect, useState } from 'react'
-import { Controller, type UseFormReturn, useFieldArray, useForm } from 'react-hook-form'
+import {
+ Controller,
+ FormProvider,
+ type UseFormReturn,
+ useFieldArray,
+ useForm,
+} from 'react-hook-form'
import { useTranslation } from 'react-i18next'
import { spreeJsonLinkResolver } from '../../../lib/json-link-resolver'
import { BulkPriceEditorDialog } from '../bulk-price-editor/bulk-price-editor-dialog'
@@ -47,6 +53,8 @@ import { PriceListStatusBadge } from './status-badge'
// mounts.
import './register'
import {
+ extensionFormValues,
+ extensionSubmitValues,
mapSpreeErrorsToForm,
Slot,
StoreDatePicker,
@@ -148,7 +156,7 @@ export function PriceListForm({
const form = useForm<PriceListFormValues>({
// eslint-disable-next-line @typescript-eslint/no-explicit-any
resolver: zodResolver(priceListFormSchema) as any,
- defaultValues: PRICE_LIST_DEFAULTS,
+ defaultValues: { ...PRICE_LIST_DEFAULTS, ...extensionFormValues('price_list', null) },
})
const rulesArray = useFieldArray<PriceListFormValues, 'rules', '_key'>({
@@ -177,12 +185,16 @@ export function PriceListForm({
match_policy: (priceList.match_policy as 'all' | 'any') ?? 'all',
rules: initialRules.map(ruleDraftFromRule),
staged_products: { adds: [], removes: [] },
+ ...extensionFormValues('price_list', priceList),
})
}, [mode, priceList, initialRules])
async function handleSubmit(values: PriceListFormValues) {
+ // Read before any reset — extension values live in raw form state (the
+ // Zod parse behind `values` strips keys the schema doesn't know).
+ const extensionValues = extensionSubmitValues('price_list', form)
try {
- await onSubmit(priceListValuesToParams(values))
+ await onSubmit({ ...priceListValuesToParams(values), ...extensionValues })
// Membership flushes after the list itself saves, so a validation
// failure aborts before any membership write.
if (priceList) {
@@ -193,7 +205,7 @@ export function PriceListForm({
queryClient,
productsKey,
})
- form.reset({ ...values, staged_products: { adds: [], removes: [] } })
+ form.reset({ ...values, ...extensionValues, staged_products: { adds: [], removes: [] } })
}
} catch (err) {
if (!mapSpreeErrorsToForm(err, form.setError)) throw err
@@ -212,131 +224,136 @@ export function PriceListForm({
return (
<ProductMembershipStagingProvider form={form} name="staged_products">
- <form onSubmit={form.handleSubmit(handleSubmit)}>
- <ResourceLayout
- header={
- <PageHeader
- title={
- mode === 'create'
- ? t('admin.pages.products.price_lists.sheet_title_create')
- : (priceList?.name ?? '')
- }
- backTo="products/price-lists"
- badges={priceList && <PriceListStatusBadge priceList={priceList} />}
- // `destructiveItems` rather than `onDelete`: the caller already runs
- // its own confirm, naming the price list being deleted, and
- // `onDelete` would stack the header's generic prompt in front of it.
- destructiveItems={
- mode === 'edit' && onDelete && canDelete ? (
- <DropdownMenuItem
- variant="destructive"
- disabled={deletePending}
- onClick={onDelete}
+ {/* FormProvider exposes the form to `price_list.form_sidebar` widgets,
+ so inputs bound via `useHostForm()` save with this page. */}
+ <FormProvider {...form}>
+ <form onSubmit={form.handleSubmit(handleSubmit)}>
+ <ResourceLayout
+ header={
+ <PageHeader
+ title={
+ mode === 'create'
+ ? t('admin.pages.products.price_lists.sheet_title_create')
+ : (priceList?.name ?? '')
+ }
+ backTo="products/price-lists"
+ badges={priceList && <PriceListStatusBadge priceList={priceList} />}
+ // `destructiveItems` rather than `onDelete`: the caller already runs
+ // its own confirm, naming the price list being deleted, and
+ // `onDelete` would stack the header's generic prompt in front of it.
+ destructiveItems={
+ mode === 'edit' && onDelete && canDelete ? (
+ <DropdownMenuItem
+ variant="destructive"
+ disabled={deletePending}
+ onClick={onDelete}
+ >
+ {t('admin.actions.delete')}
+ </DropdownMenuItem>
+ ) : undefined
+ }
+ jsonPreview={
+ mode === 'edit' && priceList
+ ? {
+ title: `Price list ${priceList.name}`,
+ fetch: () => adminClient.priceLists.get(priceList.id),
+ endpoint: `/api/v3/admin/price_lists/${priceList.id}`,
+ resolveLink: spreeJsonLinkResolver(storeId),
+ }
+ : undefined
+ }
+ actions={
+ <div className="flex gap-2">
+ {mode === 'edit' && priceList && canEdit && (
+ <EditPricesButton priceList={priceList} />
+ )}
+ {/* Export needs only read access; the import button gates
+ itself on create. */}
+ {mode === 'edit' && priceList && onImportCreated && (
+ <PriceListCsvButtons
+ priceList={priceList}
+ onImportCreated={onImportCreated}
+ size="default"
+ />
+ )}
+ {mode === 'edit' && priceList && <ActivationButtons priceList={priceList} />}
+ <Button
+ type="submit"
+ disabled={
+ form.formState.isSubmitting || (mode === 'edit' && !form.formState.isDirty)
+ }
+ >
+ {form.formState.isSubmitting
+ ? mode === 'create'
+ ? t('admin.actions.creating')
+ : t('admin.actions.saving')
+ : mode === 'create'
+ ? t('admin.actions.create')
+ : t('admin.actions.save')}
+ </Button>
+ </div>
+ }
+ />
+ }
+ main={
+ <>
+ {form.formState.errors.root?.message && (
+ <p
+ className="rounded-md bg-destructive/10 px-3 py-2 text-sm text-destructive"
+ role="alert"
>
- {t('admin.actions.delete')}
- </DropdownMenuItem>
- ) : undefined
- }
- jsonPreview={
- mode === 'edit' && priceList
- ? {
- title: `Price list ${priceList.name}`,
- fetch: () => adminClient.priceLists.get(priceList.id),
- endpoint: `/api/v3/admin/price_lists/${priceList.id}`,
- resolveLink: spreeJsonLinkResolver(storeId),
+ {form.formState.errors.root.message}
+ </p>
+ )}
+ <RulesCard form={form} rulesArray={rulesArray} />
+ {mode === 'edit' && priceList && (
+ <DeferredProductMembershipCard
+ parentId={priceList.id}
+ storeId={storeId}
+ canEdit={canEdit}
+ useProducts={usePriceListProducts}
+ listMembersPage={listPriceListProductsPage}
+ translationNamespace="admin.pages.products.price_lists"
+ description={
+ (priceList.prices_count ?? 0) > 0
+ ? t('admin.pages.products.price_lists.products_help_with_prices', {
+ count: priceList.prices_count ?? 0,
+ })
+ : t('admin.pages.products.price_lists.products_help')
}
- : undefined
- }
- actions={
- <div className="flex gap-2">
- {mode === 'edit' && priceList && canEdit && (
- <EditPricesButton priceList={priceList} />
- )}
- {/* Export needs only read access; the import button gates
- itself on create. */}
- {mode === 'edit' && priceList && onImportCreated && (
- <PriceListCsvButtons
- priceList={priceList}
- onImportCreated={onImportCreated}
- size="default"
- />
- )}
- {mode === 'edit' && priceList && <ActivationButtons priceList={priceList} />}
- <Button
- type="submit"
- disabled={
- form.formState.isSubmitting || (mode === 'edit' && !form.formState.isDirty)
+ // Each variant priced on its own row with its ladder — the
+ // catalog's reading, on the page where the ladder is edited
+ // (docs/plans/6.0-volume-pricing.md).
+ renderSubRows={(products) =>
+ catalogVariantRows<PriceListProduct>({
+ products,
+ variantsOf: (product) => product.price_list_variants,
+ namespace: PRICE_LIST_PRICES_NAMESPACE,
+ })
}
- >
- {form.formState.isSubmitting
- ? mode === 'create'
- ? t('admin.actions.creating')
- : t('admin.actions.saving')
- : mode === 'create'
- ? t('admin.actions.create')
- : t('admin.actions.save')}
- </Button>
- </div>
- }
- />
- }
- main={
- <>
- {form.formState.errors.root?.message && (
- <p
- className="rounded-md bg-destructive/10 px-3 py-2 text-sm text-destructive"
- role="alert"
- >
- {form.formState.errors.root.message}
- </p>
- )}
- <RulesCard form={form} rulesArray={rulesArray} />
- {mode === 'edit' && priceList && (
- <DeferredProductMembershipCard
- parentId={priceList.id}
- storeId={storeId}
- canEdit={canEdit}
- useProducts={usePriceListProducts}
- listMembersPage={listPriceListProductsPage}
- translationNamespace="admin.pages.products.price_lists"
- description={
- (priceList.prices_count ?? 0) > 0
- ? t('admin.pages.products.price_lists.products_help_with_prices', {
- count: priceList.prices_count ?? 0,
- })
- : t('admin.pages.products.price_lists.products_help')
- }
- // Each variant priced on its own row with its ladder — the
- // catalog's reading, on the page where the ladder is edited
- // (docs/plans/6.0-volume-pricing.md).
- renderSubRows={(products) =>
- catalogVariantRows<PriceListProduct>({
- products,
- variantsOf: (product) => product.price_list_variants,
- namespace: PRICE_LIST_PRICES_NAMESPACE,
- })
- }
- extraColumns={() =>
- catalogPriceColumns({
- headers: {
- price: t(`${PRICE_LIST_PRICES_NAMESPACE}.column_price`),
- source: t(`${PRICE_LIST_PRICES_NAMESPACE}.column_source`),
- },
- namespace: PRICE_LIST_PRICES_NAMESPACE,
- })
- }
- />
- )}
- </>
- }
- sidebar={
- <>
- <BasicsCard form={form} />
- <ScheduleCard form={form} />
- </>
- }
- />
- </form>
+ extraColumns={() =>
+ catalogPriceColumns({
+ headers: {
+ price: t(`${PRICE_LIST_PRICES_NAMESPACE}.column_price`),
+ source: t(`${PRICE_LIST_PRICES_NAMESPACE}.column_source`),
+ },
+ namespace: PRICE_LIST_PRICES_NAMESPACE,
+ })
+ }
+ />
+ )}
+ </>
+ }
+ sidebar={
+ <>
+ <BasicsCard form={form} />
+ <ScheduleCard form={form} />
+ <Slot name="price_list.form_sidebar" context={{ priceList, mode }} />
+ </>
+ }
+ />
+ </form>
+ </FormProvider>
</ProductMembershipStagingProvider>
)
}
diff --git a/packages/dashboard/src/components/spree/promotion-editors/promotion-form.tsx b/packages/dashboard/src/components/spree/promotion-editors/promotion-form.tsx
index 052f8ff005..a25f5d6e17 100644
--- a/packages/dashboard/src/components/spree/promotion-editors/promotion-form.tsx
+++ b/packages/dashboard/src/components/spree/promotion-editors/promotion-form.tsx
@@ -13,7 +13,13 @@ import { DropdownMenuItem, formatCalculatorSummary, useConfirm } from '@spree/da
import { PlusIcon, SparklesIcon, TrashIcon } from '@spree/dashboard-ui/icons'
import i18n from 'i18next'
import { useEffect, useState } from 'react'
-import { Controller, type UseFormReturn, useFieldArray, useForm } from 'react-hook-form'
+import {
+ Controller,
+ FormProvider,
+ type UseFormReturn,
+ useFieldArray,
+ useForm,
+} from 'react-hook-form'
import { useTranslation } from 'react-i18next'
import { spreeJsonLinkResolver } from '../../../lib/json-link-resolver'
import { EditorShell } from './editor-shell'
@@ -21,6 +27,8 @@ import './register'
import {
adminClient,
ExportRecordButton,
+ extensionFormValues,
+ extensionSubmitValues,
mapSpreeErrorsToForm,
Slot,
Subject,
@@ -175,7 +183,7 @@ export function PromotionForm({
const form = useForm<PromotionFormValues>({
// eslint-disable-next-line @typescript-eslint/no-explicit-any
resolver: zodResolver(promotionFormSchema) as any,
- defaultValues: PROMOTION_DEFAULTS,
+ defaultValues: { ...PROMOTION_DEFAULTS, ...extensionFormValues('promotion', null) },
})
const rulesArray = useFieldArray({ control: form.control, name: 'rules', keyName: '_key' })
@@ -201,11 +209,15 @@ export function PromotionForm({
match_policy: promotion.match_policy,
rules: initialRules.map(ruleDraftFromRule),
actions: initialActions.map(actionDraftFromAction),
+ ...extensionFormValues('promotion', promotion),
})
}, [mode, promotion, initialRules, initialActions])
async function handleSubmit(values: PromotionFormValues) {
const payload: PromotionFormPayload = {
+ // Raw form state, not `values`: the Zod parse strips keys the schema
+ // doesn't know, which is every field a slot widget registered.
+ ...extensionSubmitValues('promotion', form),
name: values.name,
description: values.description?.length ? values.description : null,
starts_at: values.starts_at || null,
@@ -238,84 +250,93 @@ export function PromotionForm({
}
return (
- <form onSubmit={form.handleSubmit(handleSubmit)}>
- <ResourceLayout
- header={
- <PageHeader
- title={
- mode === 'create' ? t('admin.pages.promotions.new_title') : (promotion?.name ?? '')
- }
- backTo="promotions"
- // Delete lives in the more-actions menu, not beside Save: a
- // destructive action next to the primary one is easy to hit by
- // mistake, and the menu is where every other record page puts it.
- // `destructiveItems` rather than `onDelete`: the caller already runs
- // its own confirm, naming the promotion being deleted, and
- // `onDelete` would stack the header's generic prompt in front of it.
- destructiveItems={
- mode === 'edit' && onDelete && canDelete ? (
- <DropdownMenuItem variant="destructive" disabled={deletePending} onClick={onDelete}>
- {t('admin.actions.delete')}
- </DropdownMenuItem>
- ) : undefined
- }
- jsonPreview={
- mode === 'edit' && promotion
- ? {
- title: `Promotion ${promotion.name}`,
- fetch: () => adminClient.promotions.get(promotion.id),
- endpoint: `/api/v3/admin/promotions/${promotion.id}`,
- resolveLink: spreeJsonLinkResolver(storeId),
- }
- : undefined
- }
- actions={
- <div className="flex gap-2">
- <Button
- type="submit"
- disabled={
- form.formState.isSubmitting || (mode === 'edit' && !form.formState.isDirty)
- }
- >
- {form.formState.isSubmitting
- ? mode === 'create'
- ? t('admin.actions.creating')
- : t('admin.actions.saving')
- : mode === 'create'
- ? t('admin.pages.promotions.create_cta')
- : t('admin.actions.save')}
- </Button>
- </div>
- }
- />
- }
- main={
- <>
- {form.formState.errors.root?.message && (
- <p
- className="rounded-md bg-destructive/10 px-3 py-2 text-sm text-destructive"
- role="alert"
- >
- {form.formState.errors.root.message}
- </p>
- )}
- <RulesCard
- form={form}
- rulesArray={rulesArray}
- matchPolicy={form.watch('match_policy')}
+ // FormProvider exposes the form to `promotion.form_sidebar` widgets, so
+ // inputs bound via `useHostForm()` save with this page.
+ <FormProvider {...form}>
+ <form onSubmit={form.handleSubmit(handleSubmit)}>
+ <ResourceLayout
+ header={
+ <PageHeader
+ title={
+ mode === 'create' ? t('admin.pages.promotions.new_title') : (promotion?.name ?? '')
+ }
+ backTo="promotions"
+ // Delete lives in the more-actions menu, not beside Save: a
+ // destructive action next to the primary one is easy to hit by
+ // mistake, and the menu is where every other record page puts it.
+ // `destructiveItems` rather than `onDelete`: the caller already runs
+ // its own confirm, naming the promotion being deleted, and
+ // `onDelete` would stack the header's generic prompt in front of it.
+ destructiveItems={
+ mode === 'edit' && onDelete && canDelete ? (
+ <DropdownMenuItem
+ variant="destructive"
+ disabled={deletePending}
+ onClick={onDelete}
+ >
+ {t('admin.actions.delete')}
+ </DropdownMenuItem>
+ ) : undefined
+ }
+ jsonPreview={
+ mode === 'edit' && promotion
+ ? {
+ title: `Promotion ${promotion.name}`,
+ fetch: () => adminClient.promotions.get(promotion.id),
+ endpoint: `/api/v3/admin/promotions/${promotion.id}`,
+ resolveLink: spreeJsonLinkResolver(storeId),
+ }
+ : undefined
+ }
+ actions={
+ <div className="flex gap-2">
+ <Button
+ type="submit"
+ disabled={
+ form.formState.isSubmitting || (mode === 'edit' && !form.formState.isDirty)
+ }
+ >
+ {form.formState.isSubmitting
+ ? mode === 'create'
+ ? t('admin.actions.creating')
+ : t('admin.actions.saving')
+ : mode === 'create'
+ ? t('admin.pages.promotions.create_cta')
+ : t('admin.actions.save')}
+ </Button>
+ </div>
+ }
/>
- <ActionsCard form={form} actionsArray={actionsArray} />
- </>
- }
- sidebar={
- <>
- <BasicsCard form={form} />
- <TriggerCard mode={mode} form={form} promotion={promotion} />
- <ScheduleCard form={form} />
- </>
- }
- />
- </form>
+ }
+ main={
+ <>
+ {form.formState.errors.root?.message && (
+ <p
+ className="rounded-md bg-destructive/10 px-3 py-2 text-sm text-destructive"
+ role="alert"
+ >
+ {form.formState.errors.root.message}
+ </p>
+ )}
+ <RulesCard
+ form={form}
+ rulesArray={rulesArray}
+ matchPolicy={form.watch('match_policy')}
+ />
+ <ActionsCard form={form} actionsArray={actionsArray} />
+ </>
+ }
+ sidebar={
+ <>
+ <BasicsCard form={form} />
+ <TriggerCard mode={mode} form={form} promotion={promotion} />
+ <ScheduleCard form={form} />
+ <Slot name="promotion.form_sidebar" context={{ promotion, mode }} />
+ </>
+ }
+ />
+ </form>
+ </FormProvider>
)
}
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/catalogs/$catalogId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/catalogs/$catalogId.tsx
index c007f8557a..b449447904 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/products/catalogs/$catalogId.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/products/catalogs/$catalogId.tsx
@@ -3,8 +3,11 @@ import type { Catalog, CatalogProduct } from '@spree/admin-sdk'
import type { PanelImport } from '@spree/dashboard-core'
import {
adminClient,
+ extensionFormValues,
+ extensionSubmitValues,
mapSpreeErrorsToForm,
PageHeader,
+ Slot,
Subject,
usePermissions,
} from '@spree/dashboard-core'
@@ -30,7 +33,7 @@ import {
import { PauseIcon, PlayIcon, TableIcon } from '@spree/dashboard-ui/icons'
import { createFileRoute, useNavigate } from '@tanstack/react-router'
import { useEffect, useState } from 'react'
-import { type UseFormReturn, useForm } from 'react-hook-form'
+import { FormProvider, type UseFormReturn, useForm } from 'react-hook-form'
import { useTranslation } from 'react-i18next'
import { CatalogAudienceCard } from '../../../../../components/spree/catalog-audience'
import {
@@ -131,7 +134,7 @@ function CatalogBody({ catalog }: { catalog: Catalog }) {
const form = useForm<CatalogFormValues>({
// eslint-disable-next-line @typescript-eslint/no-explicit-any
resolver: zodResolver(catalogFormSchema) as any,
- defaultValues: CATALOG_DEFAULTS,
+ defaultValues: { ...CATALOG_DEFAULTS, ...extensionFormValues('catalog', null) },
})
const pricingMode = form.watch('pricing_mode')
@@ -165,6 +168,7 @@ function CatalogBody({ catalog }: { catalog: Catalog }) {
// form seeded per page would send one page's terms as the whole set
// and clear every other page's (docs/plans/6.0-volume-pricing.md).
staged_terms: {},
+ ...extensionFormValues('catalog', catalog),
})
}, [catalog, form])
@@ -207,6 +211,10 @@ function CatalogBody({ catalog }: { catalog: Catalog }) {
return
}
+ // Read before any reset — extension values live in raw form state (the
+ // Zod parse behind `values` strips keys the schema doesn't know).
+ const extensionValues = extensionSubmitValues('catalog', form)
+
try {
// A product on its way out takes its terms with it, so its cells are
// dropped rather than sent — the save would otherwise re-create rows
@@ -217,12 +225,12 @@ function CatalogBody({ catalog }: { catalog: Catalog }) {
)
await saveMutation.mutateAsync({
- attributes: catalogValuesToParams(values, savedPricingMode),
+ attributes: { ...catalogValuesToParams(values, savedPricingMode), ...extensionValues },
addProductIds: values.staged_products.adds.map((product) => product.id),
removeProductIds: values.staged_products.removes,
quantityRules: stagedTermsToParams(terms),
})
- form.reset({ ...values, staged_products: { adds: [], removes: [] } })
+ form.reset({ ...values, ...extensionValues, staged_products: { adds: [], removes: [] } })
} catch (err) {
if (!mapSpreeErrorsToForm(err, form.setError)) throw err
}
@@ -230,165 +238,170 @@ function CatalogBody({ catalog }: { catalog: Catalog }) {
return (
<ProductMembershipStagingProvider form={form} name="staged_products">
- <form onSubmit={form.handleSubmit(handleSave)}>
- <ResourceLayout
- header={
- <PageHeader
- title={catalog.name}
- badges={
- <ActiveBadge
- active={catalog.active}
- activeLabel={t('admin.common.active')}
- inactiveLabel={t('admin.common.inactive')}
- />
- }
- backTo="products/catalogs"
- resource={{ id: catalog.id }}
- jsonPreview={{
- title: `Catalog ${catalog.name}`,
- fetch: () =>
- adminClient.catalogs.get(catalog.id, {
- expand: ['assignments', 'price_list', 'price_list.price_rules'],
- }),
- endpoint: `/api/v3/admin/catalogs/${catalog.id}`,
- resolveLink: spreeJsonLinkResolver(storeId),
- }}
- onDelete={permissions.can('destroy', Subject.Catalog) ? handleDelete : undefined}
- deleteLabel={t('admin.catalogs.detail.delete_label')}
- deleteConfirmTitle={t('admin.catalogs.delete_confirm.title')}
- deleteConfirmMessage={t('admin.catalogs.delete_confirm.message', {
- name: catalog.name,
- })}
- actions={
- canEdit ? (
- <>
- {/* Going live sits beside Save rather than in the form:
+ {/* FormProvider exposes the form to `catalog.form_sidebar` widgets, so
+ inputs bound via `useHostForm()` save with this page. */}
+ <FormProvider {...form}>
+ <form onSubmit={form.handleSubmit(handleSave)}>
+ <ResourceLayout
+ header={
+ <PageHeader
+ title={catalog.name}
+ badges={
+ <ActiveBadge
+ active={catalog.active}
+ activeLabel={t('admin.common.active')}
+ inactiveLabel={t('admin.common.inactive')}
+ />
+ }
+ backTo="products/catalogs"
+ resource={{ id: catalog.id }}
+ jsonPreview={{
+ title: `Catalog ${catalog.name}`,
+ fetch: () =>
+ adminClient.catalogs.get(catalog.id, {
+ expand: ['assignments', 'price_list', 'price_list.price_rules'],
+ }),
+ endpoint: `/api/v3/admin/catalogs/${catalog.id}`,
+ resolveLink: spreeJsonLinkResolver(storeId),
+ }}
+ onDelete={permissions.can('destroy', Subject.Catalog) ? handleDelete : undefined}
+ deleteLabel={t('admin.catalogs.detail.delete_label')}
+ deleteConfirmTitle={t('admin.catalogs.delete_confirm.title')}
+ deleteConfirmMessage={t('admin.catalogs.delete_confirm.message', {
+ name: catalog.name,
+ })}
+ actions={
+ canEdit ? (
+ <>
+ {/* Going live sits beside Save rather than in the form:
it is an act on the catalog, not a field of it, so it
neither waits for a Save nor is undone by a Discard.
Pricing is offered on the assortment rows instead —
that is where the products being priced are. */}
- <Button
- type="button"
- variant="outline"
- disabled={activate.isPending || deactivate.isPending}
- onClick={handleActivation}
- >
- {catalog.active ? (
- <PauseIcon className="size-4" />
- ) : (
- <PlayIcon className="size-4" />
- )}
- {catalog.active
- ? t('admin.catalogs.actions.deactivate')
- : t('admin.catalogs.actions.activate')}
- </Button>
- <Button
- type="submit"
- disabled={form.formState.isSubmitting || !form.formState.isDirty}
- >
- {form.formState.isSubmitting
- ? t('admin.actions.saving')
- : t('admin.actions.save')}
- </Button>
- </>
- ) : undefined
- }
- />
- }
- main={
- <>
- {form.formState.errors.root?.message && (
- <p
- className="rounded-md bg-destructive/10 px-3 py-2 text-sm text-destructive"
- role="alert"
- >
- {form.formState.errors.root.message}
- </p>
- )}
- <DeferredProductMembershipCard
- parentId={catalog.id}
- storeId={storeId}
- canEdit={canEdit}
- useProducts={useCatalogProducts}
- listMembersPage={listCatalogProductsPage}
- translationNamespace="admin.catalogs"
- // What the agreement charges and what it demands, on the rows
- // the merchant already curates. A product this catalog lists
- // but does not price is only visible if the two sit together
- // (docs/plans/6.0-catalog-agreement-rework.md).
- // Pricing belongs on the rows being priced, not only in the
- // card that names the mode.
- headerActions={
- canEdit && catalog.price_list && pricingMode === 'fixed' ? (
- <Button
- type="button"
- size="sm"
- variant="outline"
- onClick={() => setPriceEditorOpen(true)}
- >
- <TableIcon className="size-4" />
- {t('admin.catalogs.edit_prices_cta')}
- </Button>
+ <Button
+ type="button"
+ variant="outline"
+ disabled={activate.isPending || deactivate.isPending}
+ onClick={handleActivation}
+ >
+ {catalog.active ? (
+ <PauseIcon className="size-4" />
+ ) : (
+ <PlayIcon className="size-4" />
+ )}
+ {catalog.active
+ ? t('admin.catalogs.actions.deactivate')
+ : t('admin.catalogs.actions.activate')}
+ </Button>
+ <Button
+ type="submit"
+ disabled={form.formState.isSubmitting || !form.formState.isDirty}
+ >
+ {form.formState.isSubmitting
+ ? t('admin.actions.saving')
+ : t('admin.actions.save')}
+ </Button>
+ </>
) : undefined
}
- // Each variant priced on its own row: a product's variants can
- // be priced differently and carry different ladders
- // (docs/plans/6.0-volume-pricing.md).
- renderSubRows={(products) =>
- catalogVariantRows<CatalogProduct>({
- products,
- variantsOf: (product) => product.catalog_variants,
- })
- }
- extraColumns={(products) =>
- mergeExtraColumns(
- catalogPriceColumns({
- headers: {
- price: t('admin.catalogs.prices.column_price'),
- source: t('admin.catalogs.prices.column_source'),
- },
- }),
- catalogTermColumns({
- form,
- canEdit,
- savedTermFor: savedTermLookup(products),
- headers: {
- // Short column headers — the card's own title already
- // says these are quantity terms. The full names stay as
- // the inputs' accessible labels.
- minimum: t('admin.catalogs.terms.column_minimum'),
- multiple: t('admin.catalogs.terms.column_multiple'),
- minimumLabel: t('admin.fields.minimum_order_quantity.label'),
- multipleLabel: t('admin.fields.order_multiple.label'),
- minimumHelp: t('admin.catalogs.terms.help.minimum'),
- multipleHelp: t('admin.catalogs.terms.help.multiple'),
- invalid: t('admin.catalogs.terms.validation.positive_integer'),
- mixed: t('admin.catalogs.terms.mixed'),
- defaultHint: t('admin.catalogs.terms.inherits'),
- },
- }),
- )
- }
- />
- </>
- }
- sidebar={
- <>
- <CatalogSettingsCard form={form} canEdit={canEdit} />
- <CatalogPricingCard
- catalog={catalog}
- form={form}
- canEdit={canEdit}
- priceEditorOpen={priceEditorOpen}
- onPriceEditorOpenChange={setPriceEditorOpen}
- onImportCreated={(imp) => wizard.open(imp.id)}
/>
- <CatalogTermsCard form={form} canEdit={canEdit} />
- <CatalogAudienceCard form={form} canEdit={canEdit} />
- </>
- }
- />
- </form>
+ }
+ main={
+ <>
+ {form.formState.errors.root?.message && (
+ <p
+ className="rounded-md bg-destructive/10 px-3 py-2 text-sm text-destructive"
+ role="alert"
+ >
+ {form.formState.errors.root.message}
+ </p>
+ )}
+ <DeferredProductMembershipCard
+ parentId={catalog.id}
+ storeId={storeId}
+ canEdit={canEdit}
+ useProducts={useCatalogProducts}
+ listMembersPage={listCatalogProductsPage}
+ translationNamespace="admin.catalogs"
+ // What the agreement charges and what it demands, on the rows
+ // the merchant already curates. A product this catalog lists
+ // but does not price is only visible if the two sit together
+ // (docs/plans/6.0-catalog-agreement-rework.md).
+ // Pricing belongs on the rows being priced, not only in the
+ // card that names the mode.
+ headerActions={
+ canEdit && catalog.price_list && pricingMode === 'fixed' ? (
+ <Button
+ type="button"
+ size="sm"
+ variant="outline"
+ onClick={() => setPriceEditorOpen(true)}
+ >
+ <TableIcon className="size-4" />
+ {t('admin.catalogs.edit_prices_cta')}
+ </Button>
+ ) : undefined
+ }
+ // Each variant priced on its own row: a product's variants can
+ // be priced differently and carry different ladders
+ // (docs/plans/6.0-volume-pricing.md).
+ renderSubRows={(products) =>
+ catalogVariantRows<CatalogProduct>({
+ products,
+ variantsOf: (product) => product.catalog_variants,
+ })
+ }
+ extraColumns={(products) =>
+ mergeExtraColumns(
+ catalogPriceColumns({
+ headers: {
+ price: t('admin.catalogs.prices.column_price'),
+ source: t('admin.catalogs.prices.column_source'),
+ },
+ }),
+ catalogTermColumns({
+ form,
+ canEdit,
+ savedTermFor: savedTermLookup(products),
+ headers: {
+ // Short column headers — the card's own title already
+ // says these are quantity terms. The full names stay as
+ // the inputs' accessible labels.
+ minimum: t('admin.catalogs.terms.column_minimum'),
+ multiple: t('admin.catalogs.terms.column_multiple'),
+ minimumLabel: t('admin.fields.minimum_order_quantity.label'),
+ multipleLabel: t('admin.fields.order_multiple.label'),
+ minimumHelp: t('admin.catalogs.terms.help.minimum'),
+ multipleHelp: t('admin.catalogs.terms.help.multiple'),
+ invalid: t('admin.catalogs.terms.validation.positive_integer'),
+ mixed: t('admin.catalogs.terms.mixed'),
+ defaultHint: t('admin.catalogs.terms.inherits'),
+ },
+ }),
+ )
+ }
+ />
+ </>
+ }
+ sidebar={
+ <>
+ <CatalogSettingsCard form={form} canEdit={canEdit} />
+ <CatalogPricingCard
+ catalog={catalog}
+ form={form}
+ canEdit={canEdit}
+ priceEditorOpen={priceEditorOpen}
+ onPriceEditorOpenChange={setPriceEditorOpen}
+ onImportCreated={(imp) => wizard.open(imp.id)}
+ />
+ <CatalogTermsCard form={form} canEdit={canEdit} />
+ <CatalogAudienceCard form={form} canEdit={canEdit} />
+ <Slot name="catalog.form_sidebar" context={{ catalog, canEdit }} />
+ </>
+ }
+ />
+ </form>
+ </FormProvider>
<ImportWizardDialog importId={wizard.importId} onClose={wizard.close} />
</ProductMembershipStagingProvider>
)
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/purchase-orders/$purchaseOrderId/index.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/purchase-orders/$purchaseOrderId/index.tsx
index 550d6823f6..03040ae3ad 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/purchase-orders/$purchaseOrderId/index.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/purchase-orders/$purchaseOrderId/index.tsx
@@ -3,6 +3,7 @@ import {
adminClient,
Can,
PageHeader,
+ Slot,
Subject,
useResourceKey,
useStore,
@@ -96,7 +97,12 @@ function PurchaseOrderDetailPage() {
/>
</>
}
- sidebar={<SummaryCard purchaseOrder={purchaseOrder} />}
+ sidebar={
+ <>
+ <SummaryCard purchaseOrder={purchaseOrder} />
+ <Slot name="purchase_order.form_sidebar" context={{ purchaseOrder }} />
+ </>
+ }
/>
)
}
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/sellers/payouts/$payoutId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/sellers/payouts/$payoutId.tsx
index 4f9afb0a1d..2cfd7927c1 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/sellers/payouts/$payoutId.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/sellers/payouts/$payoutId.tsx
@@ -2,6 +2,7 @@ import {
adminClient,
formatStoreDateTime,
PageHeader,
+ Slot,
Subject,
usePermissions,
useStore,
@@ -107,91 +108,97 @@ function PayoutDetailPage() {
/>
}
main={
- <Card>
- <CardHeader>
- <CardTitle>
- <HandCoinsIcon className="size-4" />
- {/* The settlement's own count, not the rows this page
+ <>
+ <Card>
+ <CardHeader>
+ <CardTitle>
+ <HandCoinsIcon className="size-4" />
+ {/* The settlement's own count, not the rows this page
happened to load — the list is paged. */}
- {t('admin.payouts.detail.covers', { count: payout.transfers_count })}
- </CardTitle>
- </CardHeader>
+ {t('admin.payouts.detail.covers', { count: payout.transfers_count })}
+ </CardTitle>
+ </CardHeader>
- {/* Only true once the earnings loaded: a pending or failed query
+ {/* Only true once the earnings loaded: a pending or failed query
says nothing about what this settlement covers. */}
- {transfersPending ? (
- <div className="px-6 pb-6">
- <Skeleton className="h-16 w-full" />
- </div>
- ) : transfersFailed ? (
- <p className="px-6 pb-6 text-sm text-destructive">
- {t('admin.payouts.detail.covers_error')}
- </p>
- ) : rows.length === 0 ? (
- <p className="px-6 pb-6 text-sm text-muted-foreground">
- {t('admin.payouts.detail.covers_empty')}
- </p>
- ) : (
- <Table>
- <TableHeader>
- <TableRow>
- <TableHead>{t('admin.payouts.columns.date')}</TableHead>
- <TableHead>{t('admin.payouts.columns.order')}</TableHead>
- <TableHead>{t('admin.payouts.columns.kind')}</TableHead>
- <TableHead className="text-right">{t('admin.fields.amount.label')}</TableHead>
- </TableRow>
- </TableHeader>
- <TableBody>
- {rows.map((transfer) => (
- <TableRow key={transfer.id}>
- <TableCell>{formatStoreDateTime(transfer.created_at, timezone)}</TableCell>
- <TableCell>
- {transfer.order_id ? (
- <Link
- to={'/$storeId/orders/$orderId' as string}
- params={{ orderId: transfer.order_id }}
- className="no-underline"
- >
- {transfer.order_number ?? transfer.order_id}
- </Link>
- ) : (
- '—'
- )}
- </TableCell>
- <TableCell className="text-muted-foreground">
- {t(`admin.payouts.kinds.${transfer.kind}`, {
- defaultValue: transfer.kind,
- })}
- </TableCell>
- <TableCell className="text-right tabular-nums">
- {transfer.display_amount}
- </TableCell>
+ {transfersPending ? (
+ <div className="px-6 pb-6">
+ <Skeleton className="h-16 w-full" />
+ </div>
+ ) : transfersFailed ? (
+ <p className="px-6 pb-6 text-sm text-destructive">
+ {t('admin.payouts.detail.covers_error')}
+ </p>
+ ) : rows.length === 0 ? (
+ <p className="px-6 pb-6 text-sm text-muted-foreground">
+ {t('admin.payouts.detail.covers_empty')}
+ </p>
+ ) : (
+ <Table>
+ <TableHeader>
+ <TableRow>
+ <TableHead>{t('admin.payouts.columns.date')}</TableHead>
+ <TableHead>{t('admin.payouts.columns.order')}</TableHead>
+ <TableHead>{t('admin.payouts.columns.kind')}</TableHead>
+ <TableHead className="text-right">{t('admin.fields.amount.label')}</TableHead>
</TableRow>
- ))}
- </TableBody>
- </Table>
- )}
- {transfers?.meta && transfers.meta.pages > 1 && (
- <Pagination meta={transfers.meta} onPageChange={setPage} />
- )}
- </Card>
+ </TableHeader>
+ <TableBody>
+ {rows.map((transfer) => (
+ <TableRow key={transfer.id}>
+ <TableCell>{formatStoreDateTime(transfer.created_at, timezone)}</TableCell>
+ <TableCell>
+ {transfer.order_id ? (
+ <Link
+ to={'/$storeId/orders/$orderId' as string}
+ params={{ orderId: transfer.order_id }}
+ className="no-underline"
+ >
+ {transfer.order_number ?? transfer.order_id}
+ </Link>
+ ) : (
+ '—'
+ )}
+ </TableCell>
+ <TableCell className="text-muted-foreground">
+ {t(`admin.payouts.kinds.${transfer.kind}`, {
+ defaultValue: transfer.kind,
+ })}
+ </TableCell>
+ <TableCell className="text-right tabular-nums">
+ {transfer.display_amount}
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ )}
+ {transfers?.meta && transfers.meta.pages > 1 && (
+ <Pagination meta={transfers.meta} onPageChange={setPage} />
+ )}
+ </Card>
+ <Slot name="seller_payout.form_main" context={{ payout }} />
+ </>
}
sidebar={
- <Card>
- <CardHeader>
- <CardTitle>{t('admin.payouts.detail.settlement')}</CardTitle>
- </CardHeader>
- <div className="flex flex-col gap-3 px-6 pb-6">
- <ReadRow label={t('admin.fields.amount.label')}>{payout.display_amount}</ReadRow>
- <ReadRow label={t('admin.payouts.columns.reference')}>{payout.reference}</ReadRow>
- <ReadRow label={t('admin.payouts.columns.provider')}>{payout.provider}</ReadRow>
- <ReadRow label={t('admin.payouts.detail.period')}>
- {payout.period_start && payout.period_end
- ? `${formatStoreDateTime(payout.period_start, timezone)} – ${formatStoreDateTime(payout.period_end, timezone)}`
- : null}
- </ReadRow>
- </div>
- </Card>
+ <>
+ <Card>
+ <CardHeader>
+ <CardTitle>{t('admin.payouts.detail.settlement')}</CardTitle>
+ </CardHeader>
+ <div className="flex flex-col gap-3 px-6 pb-6">
+ <ReadRow label={t('admin.fields.amount.label')}>{payout.display_amount}</ReadRow>
+ <ReadRow label={t('admin.payouts.columns.reference')}>{payout.reference}</ReadRow>
+ <ReadRow label={t('admin.payouts.columns.provider')}>{payout.provider}</ReadRow>
+ <ReadRow label={t('admin.payouts.detail.period')}>
+ {payout.period_start && payout.period_end
+ ? `${formatStoreDateTime(payout.period_start, timezone)} – ${formatStoreDateTime(payout.period_end, timezone)}`
+ : null}
+ </ReadRow>
+ </div>
+ </Card>
+ <Slot name="seller_payout.form_sidebar" context={{ payout }} />
+ </>
}
/>
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/webhooks/$webhookEndpointId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/webhooks/$webhookEndpointId.tsx
index 74fe6b08a8..dc7b086368 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/webhooks/$webhookEndpointId.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/webhooks/$webhookEndpointId.tsx
@@ -12,6 +12,7 @@ import {
type ResourceSearch,
ResourceTable,
resourceSearchSchema,
+ Slot,
Subject,
} from '@spree/dashboard-core'
import {
@@ -272,7 +273,12 @@ function WebhookEndpointDetailBody({ endpoint }: { endpoint: WebhookEndpoint })
/>
</>
}
- sidebar={<DetailsCard endpoint={endpoint} />}
+ sidebar={
+ <>
+ <DetailsCard endpoint={endpoint} />
+ <Slot name="webhook_endpoint.form_sidebar" context={{ endpoint }} />
+ </>
+ }
/>
<EditEndpointSheet
endpoint={endpoint}
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/transfers/$transferId/index.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/transfers/$transferId/index.tsx
index 23693a0824..12cf3f7d02 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/transfers/$transferId/index.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/transfers/$transferId/index.tsx
@@ -3,6 +3,7 @@ import {
adminClient,
Can,
PageHeader,
+ Slot,
Subject,
useResourceKey,
useStockLocations,
@@ -105,7 +106,12 @@ function StockTransferDetailPage() {
/>
</>
}
- sidebar={<SummaryCard transfer={transfer} />}
+ sidebar={
+ <>
+ <SummaryCard transfer={transfer} />
+ <Slot name="stock_transfer.form_sidebar" context={{ transfer }} />
+ </>
+ }
/>
)
}
diff --git a/packages/seller-dashboard/src/pages/order.tsx b/packages/seller-dashboard/src/pages/order.tsx
index 6db53f623e..bed1359bf8 100644
--- a/packages/seller-dashboard/src/pages/order.tsx
+++ b/packages/seller-dashboard/src/pages/order.tsx
@@ -1,4 +1,4 @@
-import { formatStoreDateTime, PageHeader } from '@spree/dashboard-core'
+import { formatStoreDateTime, PageHeader, Slot } from '@spree/dashboard-core'
import { DropdownMenuItem, ResourceLayout, StatusBadge } from '@spree/dashboard-ui'
import { XCircleIcon } from '@spree/dashboard-ui/icons'
import { useParams } from '@tanstack/react-router'
@@ -113,6 +113,7 @@ export function OrderPage() {
<OrderCustomerCard order={order} />
<SpecialInstructionsCard order={order} />
<InternalNoteCard order={order} />
+ <Slot name="seller.order.form_sidebar" context={{ order }} />
</>
}
/>
diff --git a/packages/seller-dashboard/src/pages/payout.tsx b/packages/seller-dashboard/src/pages/payout.tsx
index 3f77fdd639..3e188c6751 100644
--- a/packages/seller-dashboard/src/pages/payout.tsx
+++ b/packages/seller-dashboard/src/pages/payout.tsx
@@ -1,4 +1,4 @@
-import { formatStoreDateTime, PageHeader } from '@spree/dashboard-core'
+import { formatStoreDateTime, PageHeader, Slot } from '@spree/dashboard-core'
import {
Card,
CardHeader,
@@ -134,20 +134,23 @@ export function PayoutPage() {
</Card>
}
sidebar={
- <Card>
- <CardHeader>
- <CardTitle>{t('payouts.detail.settlement')}</CardTitle>
- </CardHeader>
- <div className="flex flex-col gap-3 px-6 pb-6">
- <ReadRow label={t('payouts.columns.amount')}>{payout.display_amount}</ReadRow>
- <ReadRow label={t('payouts.columns.reference')}>{payout.reference}</ReadRow>
- <ReadRow label={t('payouts.detail.period')}>
- {payout.period_start && payout.period_end
- ? `${formatStoreDateTime(payout.period_start, timezone)} – ${formatStoreDateTime(payout.period_end, timezone)}`
- : null}
- </ReadRow>
- </div>
- </Card>
+ <>
+ <Card>
+ <CardHeader>
+ <CardTitle>{t('payouts.detail.settlement')}</CardTitle>
+ </CardHeader>
+ <div className="flex flex-col gap-3 px-6 pb-6">
+ <ReadRow label={t('payouts.columns.amount')}>{payout.display_amount}</ReadRow>
+ <ReadRow label={t('payouts.columns.reference')}>{payout.reference}</ReadRow>
+ <ReadRow label={t('payouts.detail.period')}>
+ {payout.period_start && payout.period_end
+ ? `${formatStoreDateTime(payout.period_start, timezone)} – ${formatStoreDateTime(payout.period_end, timezone)}`
+ : null}
+ </ReadRow>
+ </div>
+ </Card>
+ <Slot name="seller.payout.form_sidebar" context={{ payout }} />
+ </>
}
/>
)
diff --git a/packages/seller-dashboard/src/pages/product.tsx b/packages/seller-dashboard/src/pages/product.tsx
index fec67a362c..229ab0f5ff 100644
--- a/packages/seller-dashboard/src/pages/product.tsx
+++ b/packages/seller-dashboard/src/pages/product.tsx
@@ -1,6 +1,8 @@
import { zodResolver } from '@hookform/resolvers/zod'
import {
CategorizationCard,
+ extensionFormValues,
+ extensionSubmitValues,
GeneralCard,
InventoryCard,
MediaCard,
@@ -12,6 +14,7 @@ import {
type ProductFormValues,
productFormSchema,
productToFormValues,
+ Slot,
VariantsCard,
variantToWirePayload,
} from '@spree/dashboard-core'
@@ -88,7 +91,7 @@ export function ProductPage({ mode }: { mode: 'new' | 'edit' }) {
// The operator's defaults, which seed one placeholder variant — without
// it the Prices and Inventory cards render no row, so a seller could not
// price or stock a new listing at all.
- defaultValues: newProductFormDefaults(),
+ defaultValues: { ...newProductFormDefaults(), ...extensionFormValues('seller.product', null) },
})
// Reset once the record arrives, so the inputs show what was last saved
@@ -102,12 +105,22 @@ export function ProductPage({ mode }: { mode: 'new' | 'edit' }) {
if (!product) return
if (form.formState.isDirty) return
- form.reset(productToFormValues(product as PanelProduct, product.media))
+ form.reset({
+ ...productToFormValues(product as PanelProduct, product.media),
+ ...extensionFormValues('seller.product', product),
+ })
}, [product, form])
const save = useMutation({
- mutationFn: (values: ProductFormValues) => {
+ mutationFn: ({
+ values,
+ extensionValues,
+ }: {
+ values: ProductFormValues
+ extensionValues: Record<string, unknown>
+ }) => {
const payload: ProductParams = {
+ ...extensionValues,
name: values.name,
description: values.description,
slug: values.slug || undefined,
@@ -165,7 +178,12 @@ export function ProductPage({ mode }: { mode: 'new' | 'edit' }) {
async function onSubmit(values: ProductFormValues) {
try {
- await save.mutateAsync(values)
+ // Raw form state, not `values`: the Zod parse strips keys the schema
+ // doesn't know, which is every field a slot widget registered.
+ await save.mutateAsync({
+ values,
+ extensionValues: extensionSubmitValues('seller.product', form),
+ })
} catch (err) {
if (!mapSpreeErrorsToForm(err, form.setError)) {
toastManager.add({
@@ -241,6 +259,7 @@ export function ProductPage({ mode }: { mode: 'new' | 'edit' }) {
/>
)}
<CategorizationCard form={form} />
+ <Slot name="seller.product.form_sidebar" context={{ product, mode }} />
</>
}
/>
diff --git a/packages/seller-dashboard/src/pages/profile.tsx b/packages/seller-dashboard/src/pages/profile.tsx
index 9280c69a4a..143a1ffeae 100644
--- a/packages/seller-dashboard/src/pages/profile.tsx
+++ b/packages/seller-dashboard/src/pages/profile.tsx
@@ -1,4 +1,4 @@
-import { PageHeader } from '@spree/dashboard-core'
+import { PageHeader, Slot } from '@spree/dashboard-core'
import {
Button,
Card,
@@ -84,7 +84,12 @@ export function ProfilePage() {
<>
<ResourceLayout
header={<PageHeader title={profile.name} subtitle={t('profile.subtitle')} />}
- main={<BrandCard profile={profile} onEdit={() => setEditing(true)} />}
+ main={
+ <>
+ <BrandCard profile={profile} onEdit={() => setEditing(true)} />
+ <Slot name="seller.profile.form_main" context={{ profile }} />
+ </>
+ }
sidebar={
<>
<StandingCard profile={profile} />
@@ -95,6 +100,7 @@ export function ProfilePage() {
<SellerAddressCard profile={profile} />
<SellerReturnsLocationCard />
<SettlementCard profile={profile} />
+ <Slot name="seller.profile.form_sidebar" context={{ profile }} />
</>
}
/>
diff --git a/spree/api/app/controllers/spree/api/v3/admin/price_lists_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/price_lists_controller.rb
index ef1c4784cc..aa1b61ae7a 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/price_lists_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/price_lists_controller.rb
@@ -124,6 +124,7 @@ module Spree
def permitted_params
normalize_params(
params.permit(
+ *model_additional_permitted_attributes,
:name, :description, :position,
:starts_at, :ends_at, :match_policy,
:price_adjustment_percentage, :adjust_compare_at,
diff --git a/spree/api/app/controllers/spree/api/v3/seller/products_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/products_controller.rb
index ce3a0613e5..b8c118a90c 100644
--- a/spree/api/app/controllers/spree/api/v3/seller/products_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/seller/products_controller.rb
@@ -166,6 +166,7 @@ module Spree
def permitted_params
attrs = params.permit(
+ *model_class.additional_seller_permitted_attributes,
:name, :description, :slug,
:meta_title, :meta_description, :meta_keywords,
:product_type_id, :delivery_profile_id,
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/price_lists_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/price_lists_controller_spec.rb
index 29d45e7c6d..86eaa2443c 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/price_lists_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/price_lists_controller_spec.rb
@@ -466,6 +466,28 @@ RSpec.describe Spree::Api::V3::Admin::PriceListsController, type: :controller do
end
end
+ describe 'extension-contributed attributes' do
+ around do |example|
+ original = Spree::PriceList.additional_permitted_attributes
+ example.run
+ Spree::PriceList.additional_permitted_attributes = original
+ end
+
+ it 'permits an attribute the model declares' do
+ Spree::PriceList.additional_permitted_attributes += [:erp_reference]
+
+ expect_any_instance_of(described_class).to receive(:permitted_params).at_least(:once).and_wrap_original do |original|
+ result = original.call
+ expect(result.keys).to include('erp_reference')
+ result.except('erp_reference')
+ end
+
+ patch :update, params: { id: price_list.prefixed_id, erp_reference: 'PL-42' }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ end
+ end
+
describe 'PATCH #update — prices nullability contract' do
let(:product) { create(:product) }
let(:variant) { product.default_variant }
diff --git a/spree/api/spec/controllers/spree/api/v3/seller/products_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/products_controller_spec.rb
index 6642278abd..37c0fdd157 100644
--- a/spree/api/spec/controllers/spree/api/v3/seller/products_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/seller/products_controller_spec.rb
@@ -467,6 +467,41 @@ RSpec.describe Spree::Api::V3::Seller::ProductsController, type: :controller do
expect(mine.reload.tax_category).not_to eq(other_tax)
end
+
+ context 'with extension-contributed attributes' do
+ around do |example|
+ admin_attributes = Spree::Product.additional_permitted_attributes
+ seller_attributes = Spree::Product.additional_seller_permitted_attributes
+ example.run
+ Spree::Product.additional_permitted_attributes = admin_attributes
+ Spree::Product.additional_seller_permitted_attributes = seller_attributes
+ end
+
+ def permitted_keys_for(params)
+ keys = nil
+ expect_any_instance_of(described_class).to receive(:permitted_params).at_least(:once).and_wrap_original do |original|
+ result = original.call
+ keys = result.keys
+ result.except('brand_id')
+ end
+ patch :update, params: { id: mine.prefixed_id, **params }, as: :json
+ keys
+ end
+
+ it 'permits an attribute declared for sellers' do
+ Spree::Product.additional_seller_permitted_attributes += [:brand_id]
+
+ expect(permitted_keys_for(brand_id: 'acme')).to include('brand_id')
+ end
+
+ # An extension field made writable for operators must not become
+ # writable by every seller as a side effect.
+ it 'drops an attribute declared only for operators' do
+ Spree::Product.additional_permitted_attributes += [:brand_id]
+
+ expect(permitted_keys_for(brand_id: 'acme')).not_to include('brand_id')
+ end
+ end
end
describe 'DELETE #destroy' do
diff --git a/spree/core/app/models/spree/base.rb b/spree/core/app/models/spree/base.rb
index 0a031e7624..e3806d8a21 100644
--- a/spree/core/app/models/spree/base.rb
+++ b/spree/core/app/models/spree/base.rb
@@ -23,6 +23,13 @@ class Spree::Base < ApplicationRecord
# rather than assigning, so extensions don't clobber each other.
class_attribute :additional_permitted_attributes, instance_writer: false, default: [].freeze
+ # The Seller API's counterpart, kept separate because sellers write a
+ # narrower set than operators: an attribute an extension makes writable for
+ # admins stays admin-only unless it is also declared here.
+ #
+ # Spree::Product.additional_seller_permitted_attributes += [:brand_id]
+ class_attribute :additional_seller_permitted_attributes, instance_writer: false, default: [].freeze
+
# Backfills preferences added to the class after this row was last saved, so
# a reader never sees nil for a newly defined preference. Assigning
# unconditionally would dirty every record on load: `preferences` is a