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.

Expose nav remove/update declaratively in defineDashboardPlugin

Damian Legawiec7cf111df8a01
diff --git a/docs/developer/dashboard/customization/navigation.mdx b/docs/developer/dashboard/customization/navigation.mdx
index 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:
+
```ts
nav.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.ts
index 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 = 0
notify()
}
+
+/** 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.ts
index 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.ts
new file mode 100644
index 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'])
+ })
+})