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.

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.mdx
index 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.tsx
import { 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 slot
diff --git a/docs/developer/dashboard/slots-catalog.mdx b/docs/developer/dashboard/slots-catalog.mdx
index 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 slots
Rendered 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.tsx
index 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 a
refetch (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.tsx
index 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.tsx
index 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 }} />
</>
}
/>