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
Support nesting nav items under an existing parent
Damian Legawiec2a83c4ee87c2
diff --git a/docs/developer/dashboard/customization/navigation.mdx b/docs/developer/dashboard/customization/navigation.mdxindex 32e3ca89df..b0ce0b8a67 100644--- a/docs/developer/dashboard/customization/navigation.mdx+++ b/docs/developer/dashboard/customization/navigation.mdx@@ -57,6 +57,33 @@ nav.add({Children declare their own `subject` independently — the parent doesn't auto-gate them.+### Nest under an existing (built-in) parent++To add an item **inside** a menu you don't own — e.g. a "Brands" page under the built-in **Products** menu — use `addChild`, which preserves the parent's existing children. (`nav.update('products', { children: [...] })` would *replace* them, dropping the built-ins.)++```ts+nav.addChild('products', {+ key: 'products.brands',+ label: 'Brands',+ path: '/products/brands',+ subject: 'Spree::Brand',+})+```++Or declaratively, keyed by parent:++```ts+defineDashboardPlugin({+ nav: {+ addChildren: {+ products: [{ key: 'products.brands', label: 'Brands', path: '/products/brands' }],+ },+ },+})+```++Nesting under a missing parent throws; a duplicate child key throws (`updateChild` / `removeChild` mutate an existing one). Built-in parents (`products`, `orders`, `customers`, `promotions`) register during app bootstrap, before any plugin runs, so they're always available to nest into.+### Insert relative to an existing entry```ts@@ -87,7 +114,7 @@ defineDashboardPlugin({})```-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.+The array form (`nav: [...]`) remains the shorthand for `{ add: [...] }`. The object form also takes `addChildren` (see [Nest under an existing parent](#nest-under-an-existing-built-in-parent)). `remove` of an unknown key is a no-op; `update` of an unknown key throws. `settingsNav` accepts the same object form (minus `addChildren` — settings entries are flat).### Bottom-pinned entriesdiff --git a/packages/dashboard-core/src/lib/nav-registry.ts b/packages/dashboard-core/src/lib/nav-registry.tsindex 6452ee972d..bfdd0ce02b 100644--- a/packages/dashboard-core/src/lib/nav-registry.ts+++ b/packages/dashboard-core/src/lib/nav-registry.ts@@ -56,6 +56,17 @@ interface NavMutator {insertBefore(targetKey: string, entry: NavEntry): void/** Insert a new entry immediately after `targetKey`. Throws if the target is missing. */insertAfter(targetKey: string, entry: NavEntry): void+ /**+ * Append a child under an existing top-level entry (e.g. nest a plugin page+ * under the built-in `products` menu). Preserves the parent's existing+ * children — unlike `update(parent, { children })`, which replaces them.+ * Throws if the parent is missing or the child key already exists there.+ */+ addChild(parentKey: string, child: NavEntry): void+ /** Remove a child by key from a parent. No-op when either is absent. */+ removeChild(parentKey: string, childKey: string): void+ /** Patch a child of `parentKey`. Throws if the parent or child is missing. */+ updateChild(parentKey: string, childKey: string, patch: Partial<Omit<NavEntry, 'key'>>): void}// ============================================================================@@ -128,6 +139,37 @@ export const nav: NavMutator = {entries.splice(i + 1, 0, adjusted)notify()},+ addChild(parentKey, child) {+ const parent = requireEntry(parentKey)+ if (parent.children?.some((c) => c.key === child.key)) {+ throw new Error(+ `Nav child "${child.key}" already exists under "${parentKey}". Use nav.updateChild().`,+ )+ }+ parent.children = [...(parent.children ?? []), child]+ notify()+ },+ removeChild(parentKey, childKey) {+ const parent = entries.find((e) => e.key === parentKey)+ if (!parent?.children) return+ const next = parent.children.filter((c) => c.key !== childKey)+ if (next.length === parent.children.length) return+ parent.children = next+ notify()+ },+ updateChild(parentKey, childKey, patch) {+ const parent = requireEntry(parentKey)+ const child = parent.children?.find((c) => c.key === childKey)+ if (!child) throw new Error(`Nav child "${childKey}" not found under "${parentKey}".`)+ Object.assign(child, patch)+ notify()+ },+}++function requireEntry(key: string): NavEntry {+ const entry = entries.find((e) => e.key === key)+ if (!entry) throw new Error(`Nav entry "${key}" not found.`)+ return entry}function subscribe(listener: () => void): () => void {diff --git a/packages/dashboard-core/src/plugin.ts b/packages/dashboard-core/src/plugin.tsindex 0c80c49a14..c3146922ca 100644--- a/packages/dashboard-core/src/plugin.ts+++ b/packages/dashboard-core/src/plugin.ts@@ -62,6 +62,13 @@ export interface NavMutations {* entries you know exist (built-ins register before any plugin runs).*/update?: Record<string, Partial<Omit<NavEntry, 'key'>>>+ /**+ * Children to append under existing top-level entries, keyed by parent key+ * — e.g. `{ products: [{ key: 'products.brands', … }] }` nests an item in+ * the built-in Products menu. Preserves the parent's existing children.+ * Throws when the parent is missing or a child key already exists there.+ */+ addChildren?: Record<string, NavEntry[]>}export interface SettingsNavMutations {@@ -133,7 +140,11 @@ export function defineDashboardPlugin(config: DashboardPluginConfig): void {if (config.nav) {const m: NavMutations = Array.isArray(config.nav) ? { add: config.nav } : config.nav+ // add before addChildren so a plugin can add a parent then nest under it.for (const entry of m.add ?? []) safely(nav.add, entry)+ for (const [parentKey, children] of Object.entries(m.addChildren ?? {})) {+ for (const child of children) safely(nav.addChild, parentKey, child)+ }for (const key of m.remove ?? []) safely(nav.remove, key)for (const [key, patch] of Object.entries(m.update ?? {})) safely(nav.update, key, patch)}diff --git a/packages/dashboard-core/tests/plugin-nav.test.ts b/packages/dashboard-core/tests/plugin-nav.test.tsindex d00b8ad83e..4703ad8e7e 100644--- a/packages/dashboard-core/tests/plugin-nav.test.ts+++ b/packages/dashboard-core/tests/plugin-nav.test.ts@@ -6,13 +6,24 @@ function entryKeys(): string[] {return __getNavEntries().map((e) => e.key)}+function childKeys(parentKey: string): string[] {+ return (__getNavEntries().find((e) => e.key === parentKey)?.children ?? []).map((c) => c.key)+}+describe('defineDashboardPlugin nav', () => {beforeEach(() => {__resetNavRegistry()// Stand-ins for built-in entries, registered before any plugin runs —- // same order as the real bootstrap.+ // same order as the real bootstrap. Products carries a built-in child so+ // child-append can be checked for preservation.nav.add({ key: 'orders', label: 'Orders', path: '/orders', position: 20 })- nav.add({ key: 'products', label: 'Products', path: '/products', position: 30 })+ nav.add({+ key: 'products',+ label: 'Products',+ path: '/products',+ position: 30,+ children: [{ key: 'products.categories', label: 'Categories', path: '/products/categories' }],+ })})it('array form adds entries (shorthand for { add })', () => {@@ -56,4 +67,79 @@ describe('defineDashboardPlugin nav', () => {// rolled back, matching the documented all-errors-at-once behavior.expect(entryKeys()).toEqual(['orders', 'products'])})++ it('addChildren nests under a built-in parent, preserving its children', () => {+ defineDashboardPlugin({+ nav: {+ addChildren: {+ products: [{ key: 'products.brands', label: 'Brands', path: '/products/brands' }],+ },+ },+ })+ expect(childKeys('products')).toEqual(['products.categories', 'products.brands'])+ })++ it('can add a parent and nest under it in the same config', () => {+ defineDashboardPlugin({+ nav: {+ add: [{ key: 'catalog', label: 'Catalog', path: '/catalog' }],+ addChildren: {+ catalog: [{ key: 'catalog.brands', label: 'Brands', path: '/catalog/brands' }],+ },+ },+ })+ expect(childKeys('catalog')).toEqual(['catalog.brands'])+ })++ it('nesting under an unknown parent throws', () => {+ expect(() =>+ defineDashboardPlugin({+ nav: { addChildren: { nope: [{ key: 'x', label: 'X', path: '/x' }] } },+ }),+ ).toThrow(/not found/)+ })+})++describe('nav child mutators', () => {+ beforeEach(() => {+ __resetNavRegistry()+ nav.add({+ key: 'products',+ label: 'Products',+ path: '/products',+ children: [{ key: 'products.categories', label: 'Categories', path: '/products/categories' }],+ })+ })++ it('removeChild removes only the named child', () => {+ nav.addChild('products', { key: 'products.brands', label: 'Brands', path: '/products/brands' })+ nav.removeChild('products', 'products.categories')+ expect(childKeys('products')).toEqual(['products.brands'])+ })++ it('removeChild is a no-op for unknown parent or child', () => {+ expect(() => nav.removeChild('nope', 'x')).not.toThrow()+ expect(() => nav.removeChild('products', 'nope')).not.toThrow()+ expect(childKeys('products')).toEqual(['products.categories'])+ })++ it('updateChild patches an existing child; throws when missing', () => {+ nav.updateChild('products', 'products.categories', { label: 'Collections', position: 5 })+ const child = __getNavEntries()+ .find((e) => e.key === 'products')+ ?.children?.find((c) => c.key === 'products.categories')+ expect(child?.label).toBe('Collections')+ expect(child?.position).toBe(5)+ expect(() => nav.updateChild('products', 'nope', { label: 'X' })).toThrow(/not found/)+ })++ it('addChild rejects a duplicate child key', () => {+ expect(() =>+ nav.addChild('products', {+ key: 'products.categories',+ label: 'Dup',+ path: '/dup',+ }),+ ).toThrow(/already exists/)+ })})