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.

Align the dashboard docs with the facade and the starter layout (#14668)

Damian Legawieca40e2a6c0c63
diff --git a/docs/developer/dashboard/concepts.mdx b/docs/developer/dashboard/concepts.mdx
index ade8b6b765..2b74f3d4ec 100644
--- a/docs/developer/dashboard/concepts.mdx
+++ b/docs/developer/dashboard/concepts.mdx
@@ -30,7 +30,9 @@ The dashboard is a **Single Page Application**: one HTML page, all routing clien
@spree/dashboard ─ app shell: routes, resource hooks, locales, vite config
```
-[Overview](/developer/dashboard/overview) covers the split in more detail. The short version: **`-ui`** has no providers or hooks (data comes via props); **`-core`** is the extension API and runtime services; **`-dashboard`** is the deployable app shell. Plugins and customizations consume `-core` and `-ui`, never the app shell.
+[Overview](/developer/dashboard/overview) covers the split in more detail. The short version: **`-ui`** has no providers or hooks (data comes via props); **`-core`** is the extension API and runtime services; **`-dashboard`** is the deployable app shell.
+
+The split matters when you publish a plugin: it consumes `-core` and `-ui` and never the app shell, which it plugs into rather than ships. In your own dashboard app the distinction is noise, so `@spree/dashboard` re-exports both — one import, and you never have to work out which package a given export lives in.
## How customization plugs in
@@ -53,7 +55,7 @@ The facade `defineDashboardPlugin({ nav, routes, slots, … })` groups all five
The signed-in admin's identity and abilities are exposed via three providers wrapping the app:
- `<AuthProvider>` — the current admin user; `useAuth()` returns `{ user, signIn, signOut, … }`
-- `<PermissionProvider>` — CanCanCan abilities; `usePermissions()` returns `{ can, cannot }`
+- `<PermissionProvider>` — CanCanCan abilities; `usePermissions()` returns `{ permissions, rules, isLoading }`, and the checks live on `permissions.can(...)`
- `<StoreProvider>` — current store + timezone + currency; `useStore()` returns `{ storeId, store, … }`
When you write a custom page or hook, pull from these. **Never reach into local state for identity** — it changes on store switch or session refresh, and the providers wire all that for you.
diff --git a/docs/developer/dashboard/customization/backend.mdx b/docs/developer/dashboard/customization/backend.mdx
index 99a72c70b9..17ac74c539 100644
--- a/docs/developer/dashboard/customization/backend.mdx
+++ b/docs/developer/dashboard/customization/backend.mdx
@@ -54,13 +54,16 @@ Resource methods are just `request<T>()` calls with the right path + types pre-b
The dashboard's data layer is React-Query — every `useFoo` hook is `useQuery({ queryKey, queryFn })` over an SDK call. Follow the same pattern for your own data:
```ts
-import { adminClient } from '@spree/dashboard'
+import { adminClient, useResourceKey } from '@spree/dashboard'
import { useQuery } from '@tanstack/react-query'
import type { AdminBrand } from './types'
export function useBrands(params?: { search?: string }) {
return useQuery({
- queryKey: ['brands', params],
+ // `useResourceKey` scopes the key to the current store. A bare
+ // `['brands', params]` key would serve one store's rows to another
+ // after a store switch.
+ queryKey: useResourceKey('brands', params),
queryFn: () =>
adminClient.request<{ data: AdminBrand[] }>('GET', '/brands', { params }),
staleTime: 30_000,
diff --git a/docs/developer/dashboard/customization/navigation.mdx b/docs/developer/dashboard/customization/navigation.mdx
index e6cee92cbc..4287d9269b 100644
--- a/docs/developer/dashboard/customization/navigation.mdx
+++ b/docs/developer/dashboard/customization/navigation.mdx
@@ -28,7 +28,7 @@ nav.add({
})
```
-`position` controls ordering — built-ins use 100–600 (Home 100, Orders 200, Products 300, Customers 400, Promotions 500, Reports 600; a conditional Getting Started entry sits at 50), leaving gaps to slot into. The default is 100. Keys must be unique, including against the built-in keys (`getting-started`, `home`, `orders`, `products`, `customers`, `promotions`, `reports`, `settings`) — duplicates throw at boot.
+`position` controls ordering — built-ins run 50–600 (Getting Started 50 when shown, Home 100, Orders 200, Products 300, Inventory 350, Customers 400, Sellers 450, Loyalty 475, Promotions 500, Reports 600), leaving gaps to slot into. The default is 100. Keys must be unique, including against the built-in keys (`getting-started`, `home`, `orders`, `products`, `inventory`, `customers`, `sellers`, `loyalty`, `promotions`, `reports`, `settings`) — duplicates throw at boot.
### Add via `defineDashboardPlugin`
diff --git a/docs/developer/dashboard/customization/quickstart.mdx b/docs/developer/dashboard/customization/quickstart.mdx
index 7774a8f33d..e103389ea5 100644
--- a/docs/developer/dashboard/customization/quickstart.mdx
+++ b/docs/developer/dashboard/customization/quickstart.mdx
@@ -81,7 +81,7 @@ defineDashboardPlugin({
Save. Click "Analytics" — your page renders inside the dashboard chrome, at `/<store id>/analytics`.
<Warning>
-Every `key` must be unique, including against the built-ins (`getting-started`, `home`, `orders`, `products`, `customers`, `promotions`, `reports`, `settings`). Registering a duplicate key throws at boot with a message naming the conflict.
+Every `key` must be unique, including against the built-ins (`getting-started`, `home`, `orders`, `products`, `inventory`, `customers`, `sellers`, `loyalty`, `promotions`, `reports`, `settings`). Registering a duplicate key throws at boot with a message naming the conflict.
</Warning>
## What just happened
diff --git a/docs/developer/dashboard/overview.mdx b/docs/developer/dashboard/overview.mdx
index defbebfb80..d292be0f54 100644
--- a/docs/developer/dashboard/overview.mdx
+++ b/docs/developer/dashboard/overview.mdx
@@ -8,7 +8,7 @@ description: Learn about the Spree React Dashboard architecture and how to custo
The React Dashboard is currently a **Developer Preview** — APIs may still change between releases. It is becoming the default Admin interface.
</Info>
-The React Dashboard is a React single-page application (SPA) that talks to the [Spree Admin API](/api-reference/admin-api). It can be distributed with the Spree API or as a standalone npm package, and it can be extended with plugins. The dashboard is built with modern React libraries and patterns, including:
+The React Dashboard is a React single-page application (SPA) that talks to the [Spree Admin API](/api-reference/admin-api/introduction). It can be distributed with the Spree API or as a standalone npm package, and it can be extended with plugins. The dashboard is built with modern React libraries and patterns, including:
| Layer | Choice |
|---|---|
@@ -37,7 +37,7 @@ Most customization uses the registries in `@spree/dashboard-core` to add nav ent
**In your own dashboard app, import from `@spree/dashboard`.** It re-exports both packages, so you never have to work out which one an export lives in. A distributed plugin is the exception: it imports `@spree/dashboard-core` and `@spree/dashboard-ui` directly, because it plugs into the shell rather than shipping it.
-You can also built your own dashboard using `@spree/dashboard-ui` primitives and `@spree/dashboard-core` registries, if you want to replace the default dashboard entirely. This is rare — most teams just add a few pages or cards to the existing dashboard.
+You can also build your own dashboard using `@spree/dashboard-ui` primitives and `@spree/dashboard-core` registries, if you want to replace the default dashboard entirely. This is rare — most teams just add a few pages or cards to the existing dashboard.
## Get the dashboard
diff --git a/docs/developer/dashboard/plugins/distributing.mdx b/docs/developer/dashboard/plugins/distributing.mdx
index 8e7e6a6ab8..e555976fa2 100644
--- a/docs/developer/dashboard/plugins/distributing.mdx
+++ b/docs/developer/dashboard/plugins/distributing.mdx
@@ -120,7 +120,7 @@ The registries are global singletons, so a key collision is the consumer's probl
- **Namespace locale keys** — `admin.acme_brands.title` not `admin.brands.title`.
- **Namespace API paths** — your Rails engine should mount under `/api/v3/admin/acme/...`, not `/api/v3/admin/brands` (which collides with core Brands if it ever ships).
-The dashboard logs a warning in dev mode when two registry entries share a key. That's the consumer's signal that two plugins are stepping on each other — and it falls back to "last-registered wins", which is rarely what either plugin wanted.
+Registering a key that already exists throws at boot, with a message naming the conflict. That is deliberate: a silently shadowed entry would leave the consumer with a plugin that half works, where a failure at startup points straight at the two plugins stepping on each other.
## Distribution channels
diff --git a/docs/developer/dashboard/public-api.mdx b/docs/developer/dashboard/public-api.mdx
index ef23abf156..40bef5eb01 100644
--- a/docs/developer/dashboard/public-api.mdx
+++ b/docs/developer/dashboard/public-api.mdx
@@ -4,7 +4,7 @@ sidebarTitle: Public API
description: Every importable symbol the dashboard exposes — components, hooks, registries, providers, and the SDK client. Treat this as the surface you can safely depend on.
---
-The dashboard is structured as three packages, each with a documented public surface. **Anything not listed here is internal** — don't import it via `@spree/dashboard-core/src/internal/...`, because we'll move or rename it without a deprecation cycle.
+The dashboard is structured as three packages. This page lists the symbols we commit to keeping — **treat anything not listed as internal**, liable to move or be renamed without a deprecation cycle, even where the barrel happens to export it today. Never reach past a package entry point into `@spree/dashboard-core/src/...`.
## `@spree/dashboard-core`
@@ -51,7 +51,7 @@ import {
// Page chrome
PageHeader,
PageTabs,
- TopBar,
+ MobileTopBar,
AppSidebar,
SettingsSidebar,
Slot,
@@ -92,6 +92,7 @@ import {
useCustomFields,
useDirectUpload, // ActiveStorage direct uploads
useExport, // CSV export job lifecycle
+ useResourceKey, // store-scoped query key — use it for every custom query
useResourceMutation, // useMutation wrapper with 422 handling
useHostForm, // the built-in form a slot widget renders inside (throws when absent)
useOptionalHostForm, // same, but null when the page has no host form
diff --git a/docs/developer/dashboard/recipes/attribute-end-to-end.mdx b/docs/developer/dashboard/recipes/attribute-end-to-end.mdx
index 34707b6fed..34da924779 100644
--- a/docs/developer/dashboard/recipes/attribute-end-to-end.mdx
+++ b/docs/developer/dashboard/recipes/attribute-end-to-end.mdx
@@ -14,7 +14,7 @@ It's the full version of the [custom form field recipe](/developer/dashboard/rec
## First: should this be a custom field instead?
-**Default to a [custom field definition](/developer/dashboard/recipes/custom-form-field#path-a-custom-field-definition--no-code).** It needs zero code — declare the field, and the product form renders and saves it. That covers most plugin data and everything merchants define themselves.
+**Default to a [custom field definition](/developer/dashboard/recipes/custom-form-field#path-a-custom-field-definition-no-code).** It needs zero code — declare the field, and the product form renders and saves it. That covers most plugin data and everything merchants define themselves.
Graduate to a real database column only when the attribute needs **list operations or database guarantees**:
@@ -90,7 +90,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'
-import { LeadTimeCard } from './fields/lead-time-card'
+import { LeadTimeCard } from './slots/lead-time-card'
import en from './locales/en.json'
i18n.addResourceBundle('en', 'translation', en, true, true)
@@ -124,7 +124,7 @@ defineDashboardPlugin({
The form widget binds to the host form — no `<form>` of its own, no save button:
```tsx
-// src/fields/lead-time-card.tsx
+// src/slots/lead-time-card.tsx
import { Card, CardContent, CardHeader, CardTitle, Field, FieldError, FieldLabel, Input, useHostForm } from '@spree/dashboard'
import { useTranslation } from 'react-i18next'
diff --git a/docs/developer/dashboard/recipes/custom-form-field.mdx b/docs/developer/dashboard/recipes/custom-form-field.mdx
index 6859e6e1fd..fd4bab8c6f 100644
--- a/docs/developer/dashboard/recipes/custom-form-field.mdx
+++ b/docs/developer/dashboard/recipes/custom-form-field.mdx
@@ -93,7 +93,7 @@ defineDashboardPlugin({
The `product.form_sidebar` slot renders inside the product form. Bind your input to the host form with `useHostForm()` — no `<form>` of your own, no save button:
```tsx
-// src/fields/tech-specs-card.tsx
+// src/slots/tech-specs-card.tsx
import {
Card,
CardContent,
diff --git a/docs/developer/dashboard/recipes/page-action-button.mdx b/docs/developer/dashboard/recipes/page-action-button.mdx
index 53fc6289b3..665c16b95d 100644
--- a/docs/developer/dashboard/recipes/page-action-button.mdx
+++ b/docs/developer/dashboard/recipes/page-action-button.mdx
@@ -21,7 +21,7 @@ import { Button, adminClient, usePermissions, useResourceMutation } from '@spree
import { Send } from 'lucide-react'
interface Props {
- resource: { id: string; state: string } // Order
+ resource: { id: string; status: string } // Order
}
export function SendInvoiceButton({ resource }: Props) {
@@ -34,7 +34,7 @@ export function SendInvoiceButton({ resource }: Props) {
// Only show to users who can act, and only on completed orders.
if (!permissions.can('update', 'Spree::Order')) return null
- if (resource.state !== 'complete') return null
+ if (resource.status !== 'placed') return null
return (
<Button
diff --git a/docs/developer/dashboard/recipes/sidebar-widget.mdx b/docs/developer/dashboard/recipes/sidebar-widget.mdx
index 40764dba89..8533b3b5fa 100644
--- a/docs/developer/dashboard/recipes/sidebar-widget.mdx
+++ b/docs/developer/dashboard/recipes/sidebar-widget.mdx
@@ -11,7 +11,7 @@ This recipe builds a "Loyalty status" card for the customer detail page: read-on
## The component
```tsx
-// src/widgets/loyalty-status-card.tsx
+// src/slots/loyalty-status-card.tsx
import { useQuery } from '@tanstack/react-query'
import {
adminClient,
@@ -101,7 +101,7 @@ Worth noting:
```ts
// src/plugins.ts (in your dashboard app)
import { defineDashboardPlugin } from '@spree/dashboard'
-import { LoyaltyStatusCard } from './widgets/loyalty-status-card'
+import { LoyaltyStatusCard } from './slots/loyalty-status-card'
defineDashboardPlugin({
slots: {
diff --git a/docs/developer/dashboard/slots-catalog.mdx b/docs/developer/dashboard/slots-catalog.mdx
index e0b098d578..8f1d33da32 100644
--- a/docs/developer/dashboard/slots-catalog.mdx
+++ b/docs/developer/dashboard/slots-catalog.mdx
@@ -89,6 +89,66 @@ 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`
+
+| Where | Company detail page, 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`
+
+| Where | Company detail page, end of the sidebar column |
+|---|---|
+| Use | Narrow company-scoped cards alongside the main form |
+| Context | `{ company, kind, canEdit }` |
+| Host form | No |
+
+## Seller panel slots
+
+Rendered by the marketplace seller panel (`@spree/seller-dashboard`) rather than the admin dashboard, and registered the same way.
+
+### `seller.form_main`
+
+| Where | Seller detail page, end of the main column |
+|---|---|
+| Use | Seller-scoped cards — payout configuration, onboarding state, compliance records |
+| Context | `{ seller, canEdit }` |
+| Host form | No |
+
+### `seller.form_sidebar`
+
+| Where | Seller detail page, end of the sidebar column |
+|---|---|
+| Use | Narrow seller-scoped cards |
+| Context | `{ seller, canEdit }` |
+| Host form | No |
+
+### `seller.team.actions`
+
+| Where | Seller team screen, in the header's action area |
+|---|---|
+| Use | Team-level actions — bulk invite, export, an external directory sync |
+| Context | `{ sellerId }` |
+| Host form | No |
+
+### `seller.team.after`
+
+| Where | Seller team screen, below the member list |
+|---|---|
+| Use | Anything that belongs under the team — audit log, role explainer, seat usage |
+| Context | `{ sellerId }` |
+| Host form | No |
+
## Page tabs slot
### `page.tabs` (default)
diff --git a/packages/dashboard-starter/AGENTS.md b/packages/dashboard-starter/AGENTS.md
index ebef571468..c87ada08e4 100644
--- a/packages/dashboard-starter/AGENTS.md
+++ b/packages/dashboard-starter/AGENTS.md
@@ -31,6 +31,7 @@ uses internally.
| `src/hooks/` | Admin API wrappers | `use-brands.ts` |
| `src/tables/` | `defineTable` calls | `brands.tsx` |
| `src/schemas/` | Zod schema + `FormValues` | `brand.ts` |
+| `src/slots/` | Widgets injected into built-in pages | `product-brand-card.tsx` |
| `src/locales/` | Your `admin.*` translation keys | `en.json` |
Adding a resource touches one file in each directory. Keep `plugins.ts` a map
diff --git a/packages/dashboard-starter/README.md b/packages/dashboard-starter/README.md
index 24cba918bf..ebdcf56df0 100644
--- a/packages/dashboard-starter/README.md
+++ b/packages/dashboard-starter/README.md
@@ -51,6 +51,8 @@ src/
├── hooks/ one file per resource use-brands.ts
├── tables/ one file per resource brands.tsx
├── schemas/ one file per resource brand.ts
+├── slots/ widgets injected into product-brand-card.tsx
+│ built-in pages
└── locales/ your translations en.json
```
@@ -101,6 +103,11 @@ type (`Product`, `Order`) in a form-values type — React Hook Form walks every
nested key and the SDK's object graph overflows the TypeScript compiler.
Inline a short single-file schema instead.
+**`slots/`** — components you inject into pages the dashboard already
+renders, one file per widget. A slot widget takes its data from the slot's
+context and, on a page with a host form, binds its inputs to that form with
+`useHostForm()` rather than saving anything itself.
+
**`locales/`** — every visible string goes through i18next, including column
labels and button text. Keys live under a top-level `admin` object. Load the
bundle once at the top of `plugins.ts`:
diff --git a/packages/dashboard-starter/src/slots/.gitkeep b/packages/dashboard-starter/src/slots/.gitkeep
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/packages/seller-dashboard-starter/AGENTS.md b/packages/seller-dashboard-starter/AGENTS.md
index 22a707169b..1007d8b671 100644
--- a/packages/seller-dashboard-starter/AGENTS.md
+++ b/packages/seller-dashboard-starter/AGENTS.md
@@ -34,6 +34,7 @@ uses internally.
| `src/hooks/` | Admin API wrappers | `use-brands.ts` |
| `src/tables/` | `defineTable` calls | `brands.tsx` |
| `src/schemas/` | Zod schema + `FormValues` | `brand.ts` |
+| `src/slots/` | Widgets injected into built-in pages | `seller-payout-card.tsx` |
| `src/locales/` | Your `admin.*` translation keys | `en.json` |
Adding a resource touches one file in each directory. Keep `plugins.ts` a map
diff --git a/packages/seller-dashboard-starter/src/slots/.gitkeep b/packages/seller-dashboard-starter/src/slots/.gitkeep
new file mode 100644
index 0000000000..e69de29bb2