@spree/docs 0.1.239 → 0.1.240

package/dist/developer/dashboard/concepts.md

@@ -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](overview.md) 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](overview.md) 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.

package/dist/developer/dashboard/customization/backend.md

@@ -52,13 +52,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,

package/dist/developer/dashboard/customization/navigation.md

@@ -26,7 +26,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`
 

package/dist/developer/dashboard/customization/quickstart.md

@@ -80,7 +80,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.
+> **WARNING:** 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.
 
 ## What just happened
 

package/dist/developer/dashboard/overview.md

@@ -6,7 +6,7 @@ description: Learn about the Spree React Dashboard architecture and how to custo
 
 > **INFO:** The React Dashboard is currently a **Developer Preview** — APIs may still change between releases. It is becoming the default Admin interface.
 
-The React Dashboard is a React single-page application (SPA) that talks to the [Spree Admin API](../../api-reference/admin-api.md). 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.md). 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 |
 |---|---|
@@ -35,7 +35,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
 

package/dist/developer/dashboard/plugins/distributing.md

@@ -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
 

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

@@ -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

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

@@ -14,7 +14,7 @@ It's the full version of the [custom form field recipe](custom-form-field.md)
 
 ## First: should this be a custom field instead?
 
-**Default to a [custom field definition](custom-form-field.md#path-a-custom-field-definition--no-code).** It needs zero code — declare the field, and the product form renders and saves it. That covers most plugin data and everything merchants define themselves.
+**Default to a [custom field definition](custom-form-field.md#path-a-custom-field-definition-no-code).** It needs zero code — declare the field, and the product form renders and saves it. That covers most plugin data and everything merchants define themselves.
 
 Graduate to a real database column only when the attribute needs **list operations or database guarantees**:
 
@@ -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'
 
 i18n.addResourceBundle('en', 'translation', en, true, true)
 
@@ -123,7 +123,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'
 

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

@@ -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,

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

@@ -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

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

@@ -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: {

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

@@ -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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.239",
+  "version": "0.1.240",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",