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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Render form_sidebar slots on product, order, and customer detail pages
Damian Legawiec1ec8deb07d87
diff --git a/docs/developer/dashboard/recipes/sidebar-widget.mdx b/docs/developer/dashboard/recipes/sidebar-widget.mdxindex 6c28690392..ef81080264 100644--- a/docs/developer/dashboard/recipes/sidebar-widget.mdx+++ b/docs/developer/dashboard/recipes/sidebar-widget.mdx@@ -13,7 +13,7 @@ This recipe builds a "Loyalty status" card for the customer detail page: read-on```tsx// packages/dashboard/src/widgets/loyalty-status-card.tsximport { useQuery } from '@tanstack/react-query'-import { adminClient, useStore } from '@spree/dashboard-core'+import { adminClient, usePermissions, useStore } from '@spree/dashboard-core'import {Card, CardContent, CardHeader, CardTitle,Skeleton, Badge, EmptyState,@@ -27,21 +27,29 @@ interface LoyaltyRecord {}interface Props {- resource: { id: string }+ // The customer detail page's slot context — see the slots catalog.+ customer: { id: string }}-export function LoyaltyStatusCard({ resource }: Props) {+export function LoyaltyStatusCard({ customer }: Props) {const { storeId } = useStore()+ const { permissions } = usePermissions()+ const canRead = permissions.can('read', 'MyApp::LoyaltyRecord')const { data, isLoading } = useQuery({- queryKey: ['loyalty', storeId, resource.id],+ queryKey: ['loyalty', storeId, customer.id],queryFn: () =>adminClient.request<{ data: LoyaltyRecord | null }>('GET',- `/customers/${resource.id}/loyalty`,+ `/customers/${customer.id}/loyalty`,),staleTime: 30_000,+ enabled: canRead,})+ // Hide entirely for staff without the permission — same behavior as+ // core's permission-gated cards.+ if (!canRead) return null+return (<Card><CardHeader>@@ -90,10 +98,11 @@ defineDashboardPlugin({id: 'loyalty-status',component: LoyaltyStatusCard as never,position: 50,- if: ({ permissions }) => permissions.can('read', 'MyApp::LoyaltyRecord'),}],},})++The permission gate lives *inside* the component (`usePermissions`) rather than in an `if` predicate on the entry — the predicate only receives the slot context today, not ambient permissions (see the [slots catalog](/developer/dashboard/slots-catalog#ambient-context)).````position: 50` puts the card near the top of the sidebar (built-in cards typically use 100/200/300). Pick a number based on whether your widget is more or less important than the others — for a "status" card, near the top is right.@@ -103,8 +112,8 @@ defineDashboardPlugin({The pattern above fetches its own data. The alternative is to read it from the resource the host passes:```tsx-function MyCard({ resource }: { resource: AdminCustomer }) {- return <div>{resource.loyalty_points}</div> // host already loaded it+function MyCard({ customer }: { customer: AdminCustomer }) {+ return <div>{customer.loyalty_points}</div> // host already loaded it}```@@ -112,7 +121,7 @@ Choose based on **whether the data is hot path for the rest of the page**:| Data | Approach ||---|---|-| Already on the host's serializer (e.g., `customer.tags`) | Read from `resource` — no extra HTTP |+| Already on the host's serializer (e.g., `customer.tags`) | Read from the slot context — no extra HTTP || Conditional, expensive, or owned by your plugin | Fetch in the widget || Sometimes-needed (e.g., gated by feature flag) | Fetch in the widget |@@ -120,20 +129,12 @@ A widget that always fetches is wasteful when the host already has the data. A w## Loading states for the host page-The host page renders the sidebar slot before its own data is ready — your widget receives `resource: undefined` briefly during initial load. Either:+The built-in detail pages render their sidebar only after the record has loaded, so the context record is always set when your widget mounts. If you register into a slot where that's not guaranteed (check the slots catalog entry), guard defensively:```tsx-if (!resource) return <Skeleton className="h-24" />+if (!customer) return null // or a <Skeleton> to reserve layout space```-…or skip rendering altogether and let the slot register no DOM at all:--```tsx-if (!resource) return null-```--Skeleton when you want to reserve layout space; null when the widget is small enough that pop-in is acceptable.-## Reference- [Slots catalog → form sidebars](/developer/dashboard/slots-catalog) — every page-level sidebar slotdiff --git a/docs/developer/dashboard/slots-catalog.mdx b/docs/developer/dashboard/slots-catalog.mdxindex 5afc04e7a5..187e83bd91 100644--- a/docs/developer/dashboard/slots-catalog.mdx+++ b/docs/developer/dashboard/slots-catalog.mdx@@ -10,24 +10,21 @@ If you need a new injection point in a built-in page, open a PR adding `<Slot na## Ambient context-Every slot component receives this in addition to the slot-specific context (merged into the same props object):--```ts-interface SlotAmbientContext {- permissions: Permissions // CanCanCan abilities- store: Store // the current store- user: AdminUser // the signed-in admin-}-```--Pull them from the merged props bag:+Ambient context (`permissions`, `store`, `user` merged into every slot's props) is planned but **not wired up yet** — today slot components receive only the slot-specific context listed below. Until it lands, read those values with the hooks instead:```tsx-function MyWidget({ permissions, store, resource }: { permissions: Permissions; store: Store; resource: any }) {+import { usePermissions, useStore } from '@spree/dashboard-core'++function MyWidget({ product }: { product: Product }) {+ const { permissions } = usePermissions()+ const { store } = useStore()+ if (!permissions.can('read', 'MyApp::LoyaltyRecord')) return null// ...}```+The same applies to an entry's `if` predicate: it receives the slot context, but not `permissions` — gate inside the component for now.+## Page header slotsRendered by `<PageHeader>` (`@spree/dashboard-core/components/page-header.tsx`) at the top of every detail and list page that uses the shared chrome.@@ -46,6 +43,31 @@ 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 sidebar slots++The product, order, and customer detail pages each render a slot at the bottom of their right-hand sidebar, below the built-in cards. The context key matches the resource name.++### `product.form_sidebar`++| Where | Product detail page (`products/$productId`), end of the sidebar column |+|---|---|+| Use | Add a card scoped to the product being edited (e.g., a "Brand" picker, wishlist stats, sync status from an external system) |+| Context | `{ product }` — the full `Product` record from the Admin API |++### `order.form_sidebar`++| Where | Order detail page (`orders/$orderId`), end of the sidebar column |+|---|---|+| Use | Fraud-check status, shipping-integration state, loyalty points earned |+| Context | `{ order }` — the full `Order` record |++### `customer.form_sidebar`++| Where | Customer detail page (`customers/$customerId`), end of the sidebar column |+|---|---|+| Use | Loyalty status, support-ticket summary, external CRM links |+| Context | `{ customer }` — the full `Customer` record |+## Page tabs slot### `page.tabs` (default)diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/customers/$customerId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/customers/$customerId.tsxindex 5bb97e28c9..d360016976 100644--- a/packages/dashboard/src/routes/_authenticated/$storeId/customers/$customerId.tsx+++ b/packages/dashboard/src/routes/_authenticated/$storeId/customers/$customerId.tsx@@ -7,6 +7,7 @@ import {mapSpreeErrorsToForm,PageHeader,ResourceMultiAutocomplete,+ Slot,Subject,TagCombobox,useCountries,@@ -210,6 +211,7 @@ function CustomerBody({ customer }: { customer: Customer }) {{/* Key on `updated_at` so the textarea's local state resets after arefetch (e.g. another mutation invalidates the customer). */}<InternalNoteCard key={customer.updated_at} customer={customer} />+ <Slot name="customer.form_sidebar" context={{ customer }} /></>}/>diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/orders/$orderId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/orders/$orderId.tsxindex 72cdeaecaf..94c7719823 100644--- a/packages/dashboard/src/routes/_authenticated/$storeId/orders/$orderId.tsx+++ b/packages/dashboard/src/routes/_authenticated/$storeId/orders/$orderId.tsx@@ -7,6 +7,7 @@ import {getInitials,LocaleLabel,PageHeader,+ Slot,TagCombobox,useResourceMutation,} from '@spree/dashboard-core'@@ -161,6 +162,7 @@ function OrderDetailPage() {<DiscountsCard order={order} /><SpecialInstructionsCard order={order} /><InternalNoteCard order={order} />+ <Slot name="order.form_sidebar" context={{ order }} /></>}/>diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsxindex ab35e6b4a3..f9b2140238 100644--- a/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx+++ b/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx@@ -1,6 +1,6 @@import { zodResolver } from '@hookform/resolvers/zod'import { type Product, SpreeError, type Variant } from '@spree/admin-sdk'-import { adminClient, mapSpreeErrorsToForm, PageHeader } from '@spree/dashboard-core'+import { adminClient, mapSpreeErrorsToForm, PageHeader, Slot } from '@spree/dashboard-core'import {ErrorState,FormActions,@@ -425,6 +425,7 @@ function ProductForm({ product }: { product: Product }) {<CategorizationCard form={form} /><TaxCard form={form} /><SEOCard form={form} product={product} />+ <Slot name="product.form_sidebar" context={{ product }} /></>}/>