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
Make the seller panel customisable the way the dashboard is
Damian Legawiec8649207a7b20
diff --git a/docs/plans/6.0-multi-vendor-marketplace.md b/docs/plans/6.0-multi-vendor-marketplace.mdindex c3e4bbb6ca..745e48121c 100644--- a/docs/plans/6.0-multi-vendor-marketplace.md+++ b/docs/plans/6.0-multi-vendor-marketplace.md@@ -738,6 +738,7 @@ Even before this lands, work touching adjacent areas should:- **Seller lifecycle → four workflows, never a writable `status`** (RESOLVED 2026-08-16, shipped). `Spree::Sellers::Invite` / `Approve` / `Suspend` / `Reject` (seams `seller_invite_workflow` and siblings), each with `validate` + `after_*` hooks and its own `seller.*` event. The Admin API exposes them as member actions (`POST invite`, `PATCH approve|suspend|reject`) and deliberately omits `status` from `permitted_params` — a PATCH that moved a seller would skip the mail, the payout provisioning and the extension hooks, which is exactly what `6.0-service-workflows.md` keeps out of a column write. Guards admit more than the linear path: `Approve` also lifts a suspension (clearing holiday mode with it) and revives a rejected applicant; `Suspend` is for a seller already on the marketplace while `Reject` is for one that never traded, so rejecting an approved seller is refused. Suspension and rejection reasons live in `metadata` rather than columns — each is a note about one event, and the next one has its own. Creation stays plain CRUD (it is not a lifecycle transition), so the default status is applied in an `after_initialize` on the model, as on `Spree::Fulfillment`.- **Lifecycle emails are seller-facing, event-driven, and skip the invitation** (RESOLVED 2026-08-16, shipped). `Spree::SellerMailer` (approved/suspended/rejected) in `spree_emails`, fired by `Spree::SellerEmailSubscriber` off the `seller.*` events the workflows already publish — nothing mails from a workflow step, so mail is one listener among several rather than something a transition waits on. Three departures from the legacy module: **no `seller.invited` email** (inviting creates an `Invitation`, which already mails the invitee — a second message would be the same news to the same address), **no marketplace-staff copies** (the legacy module mailed every store admin on approval and onboarding; staff read status in the dashboard, and per-admin fan-out across many sellers is the kind of noise merchants switch off — staff notifications ride the event/webhook surface), and **suspension/rejection reasons never appear in the email** (the operator's note is an internal record; the seller is asked to get in touch). Gated on a new `send_seller_transactional_emails` Store preference rather than the consumer one — sellers are a different audience, and silencing customer receipts must not silence seller mail. Onboarding started/completed emails wait for the onboarding task registry.- **The seller panel is a path, not a subdomain** (RESOLVED 2026-08-18). Served at `/sellers` by `spree_dashboard`, exactly as the operator's dashboard is served at `/dashboard` — same engine, same SPA controller (generalised to `Spree::Dashboard::SpaController`, which a subclass points at a bundle), `SPREE_SELLER_PANEL_DIST_PATH` beside `SPREE_DASHBOARD_DIST_PATH`. Nothing forced a second hostname: the two panels' refresh cookies are already isolated by name and path (`/api/v3/admin/auth` vs `/api/v3/seller/auth`), so sharing an origin costs nothing in isolation and saves every deployment a hostname, a certificate and a CORS allowlist entry. `SPREE_SELLER_PANEL_URL` remains for marketplaces that do want sellers on their own domain, and `Sellers::PanelUrl` now resolves the `/sellers` mount before falling back to the dashboard. The dev-time `sellers.<branch>` host stays — two Vite servers cannot share an origin root, which is why `admin.<branch>` exists too. **Constraint:** a link the panel builds from a path must resolve against `BASE_URL`, never `window.location.origin` alone, or it misses the mount.+- **The seller panel is customisable the way the dashboard is — same registries, same facade** (RESOLVED 2026-08-18). Reversing the first cut's "reference/throwaway, no extension points": the seller panel is the part of a marketplace most often shaped to fit, and shaping it should mean adding and removing, not rewriting. `@spree/seller-dashboard` re-exports `@spree/dashboard-core/plugin`, so one `defineDashboardPlugin({ nav, slots, tables })` extends either panel; the built-in sidebar entries register into the shared nav registry (a marketplace `nav.remove('team')`s the built-in), and the built-in screens expose named slots (`seller.team.actions`, `seller.team.after`). Two core changes made this a reuse rather than a fork: `useNavItems(tenantId)` lifts the sidebar's registry composition (tenant prefixing + `if` gates + permission filtering) out of `AppSidebar` so a panel scoped by seller id composes the same registry, and `useOptionalStore()` lets shared code run in a panel that mounts no `StoreProvider`. The chrome moved onto the real `Sidebar`/`NavMain` primitives with it. **Two more things a second consumer surfaced:** the seller `/me` sent only permission keys, so `<Can>` — which reads CanCanCan rules — answered false for everything on the panel, silently (fixed: `PermissionSerialization` concern shared by both `/me`s); and `Seller::ResourceController` had no subclass and no spec — `Seller::ProductsController` is now its first consumer, with the tenancy proofs (another seller's id 404s on show/update/destroy, `seller_id` in a create payload is ignored, a member without `write_products` gets 403). The seller product serializer extends the **store** one, not admin's, so nested variants/media inherit no operator data; the seller SDK writer emits the store-level types a seller serializer nests rather than an empty twin per type.- **Team management mirrors the operator's staff page** (RESOLVED 2026-08-18). Members in a table, pending offers in their own card, one invite dialog — the same layout, components and row actions as Settings → Staff, because it is the same job seen from the other side. Pending invitations were the gap that made the first cut feel broken: inviting someone changed nothing visible, since `team#index` lists accepted members only. A seller now gets `/seller/invitations` (index/destroy + `PATCH resend`), matching the admin surface, and the seller invitation serializer carries `acceptance_url` so a colleague who never got the email can be handed the link. Deliberately a separate controller from `team`: sending an invitation is hiring, chasing or withdrawing one is bookkeeping on the offer. **Roles stay single** — everyone holds the seller's seeded role, so inviting asks only for an address; narrower seller roles need seller-scoped role management first and are a design of their own. One framework lesson: the panel must extend `@spree/dashboard-core/lib/i18n` rather than call `init()` itself, or shared components render raw keys (`admin.row_actions.menu_label`) — a second `init()` wins the race and drops the framework's own copy.- **An invitation opens the app it is an invitation to** (RESOLVED 2026-08-17). The `admin_invitation_acceptance` route branches on `invitation.resource`: onto a `Spree::Seller` it resolves `Spree::Sellers::PanelUrl` (the `seller_panel_url` preference / SPREE_SELLER_PANEL_URL), everything else keeps the dashboard origin. Not cosmetic — the dashboard's acceptance page authenticates through the Admin API, which no seller may call, so a seller sent there could read the invitation and never accept it. The panel gets its own acceptance page and the seller API its own `auth/invitations/:id/{lookup,accept}`, parallel to the admin pair rather than subclassing it: what differs is the audience issued and the invitations it will touch, and both are the point — accepting a *staff* invitation here is refused as `not_found`, since it carries no seller membership and would mint a seller token for someone who runs no seller. With no panel deployed the link falls back to the dashboard; a marketplace that never onboards sellers by email need configure nothing.- **The seller panel is its own app and its own SDK** (RESOLVED 2026-08-17). `@spree/seller-sdk` beside `@spree/sdk` and `@spree/admin-sdk`, and `packages/seller-dashboard` (shell) + `packages/seller-dashboard-starter` (host) beside their dashboard counterparts — not a mode of the admin app. The credentials differ in kind, not degree: a seller JWT only (no secret-key equivalent exists), `X-Spree-Seller-Id` rather than `X-Spree-Store-Id` (the store is derived from the seller), and a refresh cookie whose name and path are deliberately not shared. Typing those as optional-but-meaningless on one client is how a panel ends up able to call the wrong API.diff --git a/packages/dashboard-core/src/components/app-sidebar.tsx b/packages/dashboard-core/src/components/app-sidebar.tsxindex 76172917c9..bb1885a817 100644--- a/packages/dashboard-core/src/components/app-sidebar.tsx+++ b/packages/dashboard-core/src/components/app-sidebar.tsx@@ -6,7 +6,7 @@ import { useAuth } from '../hooks/use-auth'import { primarySidebarSide, useTranslation } from '../lib/i18n'import { type NavEntry, resolveNavLabel, useNavEntries } from '../lib/nav-registry'import { type Permissions, usePermissions } from '../providers/permission-provider'-import { useStore } from '../providers/store-provider'+import { useOptionalStore } from '../providers/store-provider'import { type NavItem, NavMain } from './nav-main'import { StoreSwitcher } from './store-switcher'@@ -14,8 +14,8 @@ import { StoreSwitcher } from './store-switcher'* `labelKey` is resolved here rather than at registration so labels follow a* language change — a literal `label` is frozen at import time.*/-function entryToNavItem(entry: NavEntry, storeId: string, t: (key: string) => string): NavItem {- const pathFor = (path: string) => (path === '/' ? `/${storeId}` : `/${storeId}${path}`)+function entryToNavItem(entry: NavEntry, tenantId: string, t: (key: string) => string): NavItem {+ const pathFor = (path: string) => (path === '/' ? `/${tenantId}` : `/${tenantId}${path}`)return {title: resolveNavLabel(entry, t),url: pathFor(entry.path),@@ -45,27 +45,42 @@ function filterByPermissions(items: NavItem[], permissions: Permissions): NavIte}))}-export function AppSidebar(props: ComponentProps<typeof Sidebar>) {- const { t, i18n } = useTranslation()- const { storeId } = useParams({ strict: false }) as { storeId?: string }+/**+ * The nav registry resolved for one tenant: entries prefixed with the tenant+ * segment, `if` gates evaluated, and items the user cannot act on removed.+ *+ * Exported so a panel scoped by something other than a store composes the+ * same registry — the seller panel prefixes with a seller id instead — rather+ * than re-deriving the prefixing and permission filtering, which is what a+ * second sidebar would otherwise copy.+ */+export function useNavItems(tenantId: string): { navItems: NavItem[]; bottomItems: NavItem[] } {+ const { t } = useTranslation()const { permissions } = usePermissions()- const { store } = useStore()+ const store = useOptionalStore()?.store ?? nullconst { user } = useAuth()- const id = storeId || 'default'const { main, bottom } = useNavEntries()const visibilityContext = { permissions, store, user }const visible = (entry: NavEntry) => !entry.if || entry.if(visibilityContext)const navItems = filterByPermissions(- main.filter(visible).map((e) => entryToNavItem(e, id, t)),+ main.filter(visible).map((e) => entryToNavItem(e, tenantId, t)),permissions,)const bottomItems = filterByPermissions(- bottom.filter(visible).map((e) => entryToNavItem(e, id, t)),+ bottom.filter(visible).map((e) => entryToNavItem(e, tenantId, t)),permissions,)+ return { navItems, bottomItems }+}++export function AppSidebar(props: ComponentProps<typeof Sidebar>) {+ const { i18n } = useTranslation()+ const { storeId } = useParams({ strict: false }) as { storeId?: string }+ const { navItems, bottomItems } = useNavItems(storeId || 'default')+return (<Sidebar collapsible="icon" side={primarySidebarSide(i18n.language)} {...props}><SidebarHeader>diff --git a/packages/dashboard-core/src/providers/store-provider.tsx b/packages/dashboard-core/src/providers/store-provider.tsxindex 5284f8de37..2f56080879 100644--- a/packages/dashboard-core/src/providers/store-provider.tsx+++ b/packages/dashboard-core/src/providers/store-provider.tsx@@ -109,3 +109,16 @@ export function useStore(): StoreContextValue {}return context}++/**+ * The store context if a `StoreProvider` is mounted, else `null`.+ *+ * For code that runs in more than one panel. The operator's dashboard always+ * has a store; the seller panel has none — its tenant is a seller, and the+ * store is derived server-side. Shared pieces (the nav visibility context)+ * take the store when it is there and carry on when it is not, rather than+ * forcing every panel to mount a provider for a concept it does not have.+ */+export function useOptionalStore(): StoreContextValue | null {+ return useContext(StoreContext)+}diff --git a/packages/seller-dashboard-starter/src/main.tsx b/packages/seller-dashboard-starter/src/main.tsxindex 22558f6013..86021dad6a 100644--- a/packages/seller-dashboard-starter/src/main.tsx+++ b/packages/seller-dashboard-starter/src/main.tsx@@ -3,6 +3,12 @@ import { createRoot } from 'react-dom/client'import './styles.css'// Generated by @spree/seller-dashboard/vite on every dev start and build.// Commit it — its diff on upgrades shows exactly which pages changed.+// Activate installed seller-panel plugins — synthesized by the Vite plugin+// from your package.json deps. `pnpm add <plugin>` + dev-server restart is+// the whole install; this line never changes.+import 'virtual:spree-dashboard-plugins'+// Your own customisations (nav entries, slot widgets, table columns).+import './plugins'import { routeTree } from './routeTree.gen'// Build the Seller API client and register it with the shared frameworkdiff --git a/packages/seller-dashboard-starter/src/plugins.ts b/packages/seller-dashboard-starter/src/plugins.tsnew file mode 100644index 0000000000..c70c126796--- /dev/null+++ b/packages/seller-dashboard-starter/src/plugins.ts@@ -0,0 +1,30 @@+// Seller panel customisations for this marketplace.+//+// The seller panel is the part of a marketplace most often shaped to fit —+// but shaping it should mean adding and removing, not rewriting. Register+// nav entries, slot widgets and table columns against the shared registries+// here, the same API distributed plugins use. Imported once from main.tsx,+// before the panel renders.+//+// Example — add a payouts page and drop the built-in team screen:+//+// import { defineDashboardPlugin } from '@spree/seller-dashboard'+// import { PayoutsPage } from './pages/payouts'+//+// defineDashboardPlugin({+// nav: {+// add: [{ key: 'payouts', label: 'Payouts', path: '/payouts', position: 300 }],+// remove: ['team'],+// },+// slots: {+// 'seller.team.after': [{ id: 'audit', component: TeamAuditCard }],+// },+// })+//+// Slots the built-in screens expose: `seller.team.actions`, `seller.team.after`.+//+// Building custom pages? Add the framework and design-system packages first —+// `pnpm add @spree/dashboard-core @spree/dashboard-ui` — then import hooks,+// providers, and UI primitives from those.++export {}diff --git a/packages/seller-dashboard/src/index.ts b/packages/seller-dashboard/src/index.tsindex b41a5b7403..3d08c41da7 100644--- a/packages/seller-dashboard/src/index.ts+++ b/packages/seller-dashboard/src/index.ts@@ -3,6 +3,16 @@// evaluated them before this would bake raw keys into the UI. Side-effect// imports are ordering barriers, which is exactly what this relies on.import './i18n'+// The built-in sidebar entries. Registered on import — after i18n, since the+// labels are translated at registration time — and before any host plugin+// runs, so a plugin's `nav.remove('team')` finds the entry to remove.+import './nav/default'++// Plugin facade re-export — lets a marketplace register in-app customisations+// (nav entries, slot widgets, table columns) without declaring+// @spree/dashboard-core as a direct dependency. Same facade the operator's+// dashboard exposes: one API for extending either panel.+export * from '@spree/dashboard-core/plugin'export {createSellerApiClient,diff --git a/packages/seller-dashboard/src/nav/default.ts b/packages/seller-dashboard/src/nav/default.tsnew file mode 100644index 0000000000..7ddb0f4945--- /dev/null+++ b/packages/seller-dashboard/src/nav/default.ts@@ -0,0 +1,32 @@+import { i18n, nav } from '@spree/dashboard-core'+import { StoreIcon, UsersIcon } from 'lucide-react'++// The panel's built-in sidebar. Registered into the same registry a plugin+// writes to, so a marketplace can remove, reorder or add beside these with+// `defineDashboardPlugin({ nav: ... })` instead of forking the chrome.+//+// Positions leave room on either side (100/200/…) exactly as the operator's+// dashboard does, so a plugin slots between built-ins without renumbering.+//+// Subjects are the seller-branch CanCanCan subjects the API's `/me`+// serializes; an entry a member cannot act on is hidden by the same+// permission filter the operator's sidebar uses.++nav.add({+ key: 'profile',+ label: i18n.t('nav.profile'),+ path: '/',+ icon: StoreIcon,+ position: 100,+ subject: 'seller_profile',+})++nav.add({+ key: 'team',+ label: i18n.t('nav.team'),+ path: '/team',+ icon: UsersIcon,+ position: 200,+ subject: 'seller_profile',+ action: 'update',+})diff --git a/packages/seller-dashboard/src/pages/team.tsx b/packages/seller-dashboard/src/pages/team.tsxindex 7c6edd8044..4be904da00 100644--- a/packages/seller-dashboard/src/pages/team.tsx+++ b/packages/seller-dashboard/src/pages/team.tsx@@ -1,4 +1,4 @@-import { getInitials } from '@spree/dashboard-core'+import { Can, getInitials, Slot } from '@spree/dashboard-core'import {Avatar,AvatarFallback,@@ -91,10 +91,20 @@ export function TeamPage() {<h1 className="font-medium text-2xl">{t('team.title')}</h1><p className="text-muted-foreground text-sm">{t('team.subtitle')}</p></div>- <Button size="sm" onClick={() => setInviteOpen(true)}>- <PlusIcon className="size-4" />- {t('team.invite_cta')}- </Button>+ {/* Purely a UX gate — the API refuses the write regardless. Same+ `<Can>` the operator's dashboard uses, reading the CanCanCan rules+ the seller `/me` serializes. */}+ <div className="flex items-center gap-2">+ {/* A marketplace adds its own actions here via+ `defineDashboardPlugin({ slots: { 'seller.team.actions': [...] } })`. */}+ <Slot name="seller.team.actions" context={{ sellerId }} />+ <Can I="update" a="seller_profile">+ <Button size="sm" onClick={() => setInviteOpen(true)}>+ <PlusIcon className="size-4" />+ {t('team.invite_cta')}+ </Button>+ </Can>+ </div></div><MembersCard members={members.data?.data ?? []} loading={members.isLoading} />@@ -105,6 +115,10 @@ export function TeamPage() {<PendingInvitationsCard invitations={pending} loading={invitations.isLoading} />)}+ {/* Extra cards below the built-ins — a marketplace's own team-related+ content (roles they add, an audit trail) lands here. */}+ <Slot name="seller.team.after" context={{ sellerId }} />+<InviteDialog open={inviteOpen} onOpenChange={setInviteOpen} /></div>)diff --git a/packages/seller-dashboard/src/panel-chrome.tsx b/packages/seller-dashboard/src/panel-chrome.tsxindex e00d879f43..b960c606ed 100644--- a/packages/seller-dashboard/src/panel-chrome.tsx+++ b/packages/seller-dashboard/src/panel-chrome.tsx@@ -1,77 +1,59 @@-import { useAuth } from '@spree/dashboard-core'-import { Button } from '@spree/dashboard-ui'+import { NavMain, useAuth, useNavItems } from '@spree/dashboard-core'+import {+ Button,+ Sidebar,+ SidebarContent,+ SidebarFooter,+ SidebarHeader,+ SidebarInset,+ SidebarProvider,+} from '@spree/dashboard-ui'import { Link, useParams } from '@tanstack/react-router'-import { StoreIcon, UsersIcon } from 'lucide-react'import type { ReactNode } from 'react'import { useTranslation } from 'react-i18next'/**- * The panel's frame: a nav rail and a content column.+ * The panel's frame: the sidebar and a content column.*- * Deliberately small. The admin dashboard's chrome carries a store switcher,- * a command palette and a plugin slot system, none of which a seller managing- * one seller needs yet.+ * Built on the same sidebar primitives and the same nav registry as the+ * operator's dashboard, so a marketplace customises this panel the way it+ * customises that one — `defineDashboardPlugin({ nav, slots, ... })` — rather+ * than forking the chrome. `useNavItems` resolves the registry against the+ * seller id: entries are prefixed with it, `if` gates evaluated, and items the+ * member cannot act on hidden by the same permission filter.+ *+ * Deliberately without the operator's store switcher, settings sidebar and+ * command palette. A seller has one tenant at a time (switching is a link+ * back to the picker) and nothing here yet earns a palette.*/export function PanelChrome({ children }: { children: ReactNode }) {const { t } = useTranslation()const { logout } = useAuth()const { sellerId } = useParams({ from: '/_authenticated/$sellerId' })+ const { navItems, bottomItems } = useNavItems(sellerId)return (- <div className="flex min-h-screen">- <nav className="flex w-56 shrink-0 flex-col gap-1 border-border border-r p-4">- <p className="mb-4 font-medium text-sm">{t('app.name')}</p>-- <NavLink to="/$sellerId" params={{ sellerId }} icon={<StoreIcon className="size-4" />}>- {t('nav.profile')}- </NavLink>- <NavLink to="/$sellerId/team" params={{ sellerId }} icon={<UsersIcon className="size-4" />}>- {t('nav.team')}- </NavLink>-- <div className="mt-auto flex flex-col gap-1">+ <SidebarProvider>+ <Sidebar collapsible="icon">+ <SidebarHeader className="px-4 py-3">+ <p className="truncate font-medium text-sm">{t('app.name')}</p>+ </SidebarHeader>+ <SidebarContent>+ <NavMain items={navItems} bottomItems={bottomItems} />+ </SidebarContent>+ <SidebarFooter className="flex flex-col gap-1 p-2"><Button variant="ghost" size="sm" className="justify-start" asChild><Link to="/">{t('seller_picker.title')}</Link></Button><Button variant="ghost" size="sm" className="justify-start" onClick={() => logout()}>{t('nav.sign_out')}</Button>- </div>- </nav>-- <main className="min-w-0 flex-1 p-8">{children}</main>- </div>- )-}+ </SidebarFooter>+ </Sidebar>-/**- * A rail entry that highlights itself when its route is the active one.- *- * `activeProps` is TanStack's own active-state channel, so the highlight- * follows the router rather than a copy of the current page held in state.- */-function NavLink({- to,- params,- icon,- children,-}: {- to: string- params: Record<string, string>- icon: ReactNode- children: ReactNode-}) {- return (- <Button variant="ghost" className="justify-start" asChild>- <Link- to={to}- params={params}- activeOptions={{ exact: true }}- activeProps={{ 'data-active': 'true', className: 'bg-accent text-accent-foreground' }}- >- {icon}- {children}- </Link>- </Button>+ <SidebarInset>+ <div className="container mx-auto flex flex-1 flex-col gap-4 p-4 lg:p-6">{children}</div>+ </SidebarInset>+ </SidebarProvider>)}