Feature: hierarchical plugin admin navigation separate from admin.pages

[schiste]

Feature: hierarchical plugin admin navigation separate from admin.pages

Problem

EmDash plugins can already expose multiple admin pages through admin.pages, but the admin sidebar renders those pages as a flat list.

For larger plugins, this makes the plugin area hard to scan, especially with numerous plugins. A plugin with pages like Overview, Queue, Settings, Logs, and Diagnostics should ideally appear as one plugin parent with child pages underneath it, rather than several unrelated flat plugin entries.

Today plugin authors have to work around this by building their own internal navigation inside each plugin page. That works, but it duplicates navigation UI and means the main admin sidebar does not reflect the actual plugin page hierarchy.

Proposed API

Keep routable pages and navigation presentation separate:

interface PluginAdminPage {
path: string;
label: string;
icon?: string;
}

interface PluginAdminNavItem {
path: string;
label: string;
icon?: string;
order?: number;
hidden?: boolean;
children?: PluginAdminNavItem[];
}

interface PluginAdminConfig {
pages?: PluginAdminPage[];
nav?: PluginAdminNavItem[];
widgets?: PluginDashboardWidget[];
}

Example:

admin: {
pages: [
{ path: "/", label: "Overview" },
{ path: "/queue", label: "Queue" },
{ path: "/settings", label: "Settings" },
{ path: "/diagnostics", label: "Diagnostics" },
],
nav: [
{
path: "/",
label: "Translations",
icon: "languages",
children: [
{ path: "/queue", label: "Queue" },
{ path: "/settings", label: "Settings" },
{ path: "/diagnostics", label: "Diagnostics" },
],
},
],
}

Backward compatibility

This can be fully additive:

• If admin.nav is omitted, derive the current flat navigation from admin.pages.
• Existing plugins keep rendering exactly as they do today.
• admin.pages remains the source of truth for routable plugin pages.
• admin.nav only controls sidebar and command-palette presentation.
• Hidden nav items should remain routable if they exist in admin.pages.

I would suggest initially supporting only two visible levels:

• Plugin/root item
• Child pages

That keeps the first version simple and avoids turning the sidebar into a sitemap.

Acceptance criteria

• Plugin admin pages can be visually grouped under a parent plugin nav item.
• Active child route expands/highlights the correct parent.
• Command palette uses admin.nav when present, with sensible labels.
• Hidden nav items are excluded from sidebar/palette but remain routable.
• Existing flat plugins remain unchanged.
• Mobile sidebar behavior still works.

Related references (thank you to Codex to unearth all those pages for me)

• Discussion feat(admin): allow hiding built-in core features from admin sidebar #866: admin sidebar customization / hiding built-in core features
  feat(admin): allow hiding built-in core features from admin sidebar #866
• Discussion Feature: Collection grouping support for plugin organization #291 and PR feat(core): add group and sortOrder to collections for admin UI organization #292: collection grouping for plugin organization
  Feature: Collection grouping support for plugin organization #291
  feat(core): add group and sortOrder to collections for admin UI organization #292
• PR feat: extensions — custom admin pages with sidebar navigation #572: custom admin pages with sidebar navigation for extensions
  feat: extensions — custom admin pages with sidebar navigation #572
• Issue Bug: Plugin admin React page resolution is brittle for settings routes #281: plugin admin React page resolution is brittle for settings routes
  Bug: Plugin admin React page resolution is brittle for settings routes #281
• Issue Plugin settingsSchema does not auto-generate admin settings UI #341: settingsSchema does not auto-generate admin settings UI
  Plugin settingsSchema does not auto-generate admin settings UI #341
• PR fix: default adminPages and dashboardWidgets to empty arrays in manifest #357: default adminPages / dashboard widgets to arrays in manifest
  fix: default adminPages and dashboardWidgets to empty arrays in manifest #357
• PR fix(admin): show nav items in mobile sidebar drawer #490: mobile sidebar group-content behavior
  fix(admin): show nav items in mobile sidebar drawer #490

Why this matters

This would make plugin admin UX scale better without changing the plugin routing model. It also keeps the current API clean: pages says what exists, nav says how it should be presented.