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.

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.mdx
index 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 entries
diff --git a/packages/dashboard-core/src/lib/nav-registry.ts b/packages/dashboard-core/src/lib/nav-registry.ts
index 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.ts
index 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.ts
index 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/)
+ })
})