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.

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.md
index 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.tsx
index 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 ?? null
const { 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.tsx
index 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.tsx
index 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 framework
diff --git a/packages/seller-dashboard-starter/src/plugins.ts b/packages/seller-dashboard-starter/src/plugins.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.tsx
index 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.tsx
index 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>
)
}