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
Expose nav remove/update declaratively in defineDashboardPlugin
Damian Legawiec7cf111df8a01
diff --git a/docs/developer/dashboard/customization/navigation.mdx b/docs/developer/dashboard/customization/navigation.mdxindex f7f798dedc..32e3ca89df 100644--- a/docs/developer/dashboard/customization/navigation.mdx+++ b/docs/developer/dashboard/customization/navigation.mdx@@ -68,11 +68,27 @@ The new entry inherits the target's `position` ± 1 unless you specify your own.### Modify or remove+Imperatively:+```tsnav.update('orders', { label: 'All orders' })nav.remove('legacy-thing')```+Or declaratively in `defineDashboardPlugin` — the `nav` object form adds, removes, and patches in one config (built-in entries included; they register before any plugin runs):++```ts+defineDashboardPlugin({+ nav: {+ add: [{ key: 'reviews', label: 'Reviews', path: '/reviews', position: 35 }],+ remove: ['gift-cards'],+ update: { products: { label: 'Catalog', position: 10 } },+ },+})+```++The array form (`nav: [...]`) remains the shorthand for `{ add: [...] }`. `remove` of an unknown key is a no-op; `update` of an unknown key throws. `settingsNav` accepts the same object form.+### Bottom-pinned entries`section: 'bottom'` pins to the sidebar footer (where "Settings" lives by default):diff --git a/packages/dashboard-core/src/lib/nav-registry.ts b/packages/dashboard-core/src/lib/nav-registry.tsindex d31d28dd43..6452ee972d 100644--- a/packages/dashboard-core/src/lib/nav-registry.ts+++ b/packages/dashboard-core/src/lib/nav-registry.ts@@ -168,3 +168,8 @@ export function __resetNavRegistry(): void {entries.length = 0notify()}++/** Test-only: raw entries in registration order (unsorted, unsectioned). */+export function __getNavEntries(): readonly NavEntry[] {+ return entries+}diff --git a/packages/dashboard-core/src/plugin.ts b/packages/dashboard-core/src/plugin.tsindex 62c38d1e07..0c80c49a14 100644--- a/packages/dashboard-core/src/plugin.ts+++ b/packages/dashboard-core/src/plugin.ts@@ -51,13 +51,44 @@ export interface TableMutations {update?: Record<string, Partial<ColumnDef>>}+export interface NavMutations {+ /** Sidebar entries to add. Each must have a unique `key`. */+ add?: NavEntry[]+ /** Entry keys to remove — built-in or plugin. No-op when already gone. */+ remove?: string[]+ /**+ * Patches keyed by entry key — reorder via `position`, rename via `label`,+ * gate via `subject`. Throws when the key isn't registered, so patch only+ * entries you know exist (built-ins register before any plugin runs).+ */+ update?: Record<string, Partial<Omit<NavEntry, 'key'>>>+}++export interface SettingsNavMutations {+ /** Settings sub-shell entries to add. */+ add?: SettingsNavEntry[]+ /** Entry keys to remove. No-op when already gone. */+ remove?: string[]+ /** Patches keyed by entry key. Throws when the key isn't registered. */+ update?: Record<string, Partial<Omit<SettingsNavEntry, 'key'>>>+}+export interface DashboardPluginConfig {- /** Sidebar entries. Each must have a unique `key`. */- nav?: NavEntry[]+ /**+ * Sidebar entries. The array form adds entries; the object form also+ * removes or patches existing ones (built-ins included):+ *+ * nav: {+ * add: [{ key: 'reviews', label: 'Reviews', path: '/reviews' }],+ * remove: ['gift-cards'],+ * update: { products: { position: 10 } },+ * }+ */+ nav?: NavEntry[] | NavMutations/** Settings sub-shell groups (defined before any entry that uses the group key). */settingsNavGroups?: SettingsNavGroup[]- /** Settings sub-shell entries. */- settingsNav?: SettingsNavEntry[]+ /** Settings sub-shell entries — array adds; object form also removes/patches. */+ settingsNav?: SettingsNavEntry[] | SettingsNavMutations/** Slot extensions keyed by slot name. Each entry must have a unique `id`. */slots?: Record<string, SlotEntry[]>/** Table mutations keyed by table key (see `defineTable`). */@@ -101,7 +132,10 @@ export function defineDashboardPlugin(config: DashboardPluginConfig): void {}if (config.nav) {- for (const entry of config.nav) safely(nav.add, entry)+ const m: NavMutations = Array.isArray(config.nav) ? { add: config.nav } : config.nav+ for (const entry of m.add ?? []) safely(nav.add, entry)+ for (const key of m.remove ?? []) safely(nav.remove, key)+ for (const [key, patch] of Object.entries(m.update ?? {})) safely(nav.update, key, patch)}if (config.settingsNavGroups) {@@ -109,7 +143,14 @@ export function defineDashboardPlugin(config: DashboardPluginConfig): void {}if (config.settingsNav) {- for (const entry of config.settingsNav) safely(settingsNav.add, entry)+ const m: SettingsNavMutations = Array.isArray(config.settingsNav)+ ? { add: config.settingsNav }+ : config.settingsNav+ for (const entry of m.add ?? []) safely(settingsNav.add, entry)+ for (const key of m.remove ?? []) safely(settingsNav.remove, key)+ for (const [key, patch] of Object.entries(m.update ?? {})) {+ safely(settingsNav.update, key, patch)+ }}if (config.slots) {diff --git a/packages/dashboard-core/tests/plugin-nav.test.ts b/packages/dashboard-core/tests/plugin-nav.test.tsnew file mode 100644index 0000000000..d00b8ad83e--- /dev/null+++ b/packages/dashboard-core/tests/plugin-nav.test.ts@@ -0,0 +1,59 @@+import { beforeEach, describe, expect, it } from 'vitest'+import { __getNavEntries, __resetNavRegistry, nav } from '../src/lib/nav-registry'+import { defineDashboardPlugin } from '../src/plugin'++function entryKeys(): string[] {+ return __getNavEntries().map((e) => e.key)+}++describe('defineDashboardPlugin nav', () => {+ beforeEach(() => {+ __resetNavRegistry()+ // Stand-ins for built-in entries, registered before any plugin runs —+ // same order as the real bootstrap.+ nav.add({ key: 'orders', label: 'Orders', path: '/orders', position: 20 })+ nav.add({ key: 'products', label: 'Products', path: '/products', position: 30 })+ })++ it('array form adds entries (shorthand for { add })', () => {+ defineDashboardPlugin({+ nav: [{ key: 'reviews', label: 'Reviews', path: '/reviews', position: 35 }],+ })+ expect(entryKeys()).toEqual(['orders', 'products', 'reviews'])+ })++ it('object form adds, removes, and patches entries', () => {+ defineDashboardPlugin({+ nav: {+ add: [{ key: 'reviews', label: 'Reviews', path: '/reviews' }],+ remove: ['orders'],+ update: { products: { label: 'Catalog', position: 5 } },+ },+ })+ expect(entryKeys()).toEqual(['products', 'reviews'])+ const products = __getNavEntries().find((e) => e.key === 'products')+ expect(products?.label).toBe('Catalog')+ expect(products?.position).toBe(5)+ })++ it('removing an unknown key is a no-op; patching one throws', () => {+ expect(() => defineDashboardPlugin({ nav: { remove: ['nope'] } })).not.toThrow()+ expect(() => defineDashboardPlugin({ nav: { update: { nope: { label: 'X' } } } })).toThrow(+ /not found/,+ )+ })++ it('collects every failure before throwing', () => {+ expect(() =>+ defineDashboardPlugin({+ nav: {+ add: [{ key: 'orders', label: 'Dup', path: '/dup' }],+ update: { nope: { label: 'X' } },+ },+ }),+ ).toThrow(AggregateError)+ // The valid parts of a partially-failing config still land — nothing+ // rolled back, matching the documented all-errors-at-once behavior.+ expect(entryKeys()).toEqual(['orders', 'products'])+ })+})