domma-cms 1.6.60 → 1.7.1

package/docs/superpowers/specs/2026-05-25-admin-sidebar-via-menus-design.md

@@ -0,0 +1,358 @@
+# Admin Sidebar via Menus Design
+
+**Date:** 2026-05-25
+**Status:** Approved
+**Scope:** Replace the hand-rolled `admin/js/config/sidebar-config.js` flat-array sidebar with a menu rendered from the Menus system at a new built-in slot `admin-sidebar`. Plugins extend via the existing menu-locations registry. The Menus admin can edit the sidebar visually. Native `<details>`/`<summary>` provides expand/collapse for nested folder behaviour.
+
+## Problem
+
+The admin sidebar is currently generated by `admin/js/config/sidebar-config.js` - a hand-rolled flat array of `heading`, `divider`, and item objects passed to `Domma.elements.sidebar(...)`. This shape:
+
+- Forces every new feature to edit the code to add an entry, instead of editing data.
+- Has no native nesting - "headings" are visual groupings, not collapsible folders.
+- Permission-gates each item in code (`if (canAny('pages'))`), with the rules buried in the file.
+- Cannot be edited by an admin in the UI.
+- Has bespoke handling for plugin-injected items via `pluginSidebarItems` in `app.js`.
+- Special-cased the Projects section in the recent redesign - per-project nested entries are generated procedurally rather than living as menu data.
+
+The Menus system shipped earlier supports unbounded depth, plugin-registered slots, per-item visibility/hidden flags, and admin-editable items. The admin sidebar is the natural next consumer.
+
+## Goals
+
+- Render the admin sidebar from a menu stored at `config/menus/admin-sidebar.json` (mapped to a new core slot `admin-sidebar`).
+- Each menu item gains an optional `permission` field - a resource key from `permissionRegistry`. The renderer hides items the user can't act on.
+- Plugins register sidebar items via a new `hooks.registerSidebarItem({parent, item})` hook. Registered items are merged into the rendered tree without modifying the menu JSON.
+- Auto-migrate the current `sidebar-config.js` output to `admin-sidebar.json` on first boot. Idempotent.
+- Admin-editable: the existing Menus admin lists `admin-sidebar` like any other menu; the menu editor's item row gains a `permission` field.
+- Nested folder behaviour via native `<details>`/`<summary>` - works in every browser, no upstream PR required.
+
+## Non-Goals (YAGNI)
+
+- Drag-and-drop reordering directly in the sidebar (use the menu editor).
+- Per-user sidebar customisation (everyone with the same permissions sees the same sidebar).
+- Sidebar themes / colour overrides.
+- Removing the legacy `Domma.elements.sidebar` rendering path (kept for non-CMS Domma sites that still use it).
+
+## Data Model
+
+### Menu shape - adds `permission`
+
+Existing item shape (from the Menus design):
+
+```json
+{
+  "text":       "Pages",
+  "url":        "#/pages",
+  "icon":       "file-text",
+  "hidden":     false,
+  "visibility": "public",
+  "items":      []
+}
+```
+
+Adds one field:
+
+| Field | Type | Description |
+|---|---|---|
+| `permission` | string | Resource key from `permissionRegistry` (e.g. `pages`, `menus`, `projects`). The renderer hides the item when the user doesn't have any action under that resource. Missing = always visible (subject to existing `visibility`). |
+
+`visibility` (per-role/per-project) and `permission` (resource access) are different axes. Both apply at render time. Most admin items use `permission`; public-site menu items use `visibility`. Items can have both.
+
+### Built-in slot - `admin-sidebar`
+
+Registered by core in `server/services/menus.js` alongside `navbar`, `footer-primary`, `footer-legal`:
+
+```js
+registerLocation('admin-sidebar', {
+    label:       'Admin sidebar',
+    description: 'The left-side navigation in the admin panel',
+    source:      'core',
+    maxDepth:    null  // unbounded
+});
+```
+
+After migration, `config/menu-locations.json` includes:
+
+```json
+{
+  "navbar":         "main",
+  "footer-primary": "footer",
+  "admin-sidebar":  "admin-sidebar"
+}
+```
+
+### Migrated menu shape
+
+`config/menus/admin-sidebar.json` after auto-migration mirrors the current sidebar structure, with sections (which are headings today) becoming top-level items that nest their links:
+
+```json
+{
+  "slug": "admin-sidebar",
+  "name": "Admin sidebar",
+  "items": [
+    {
+      "text": "Overview",
+      "icon": "home",
+      "items": [
+        {"text": "Dashboard", "url": "#/", "icon": "home"}
+      ]
+    },
+    {
+      "text": "Projects",
+      "icon": "folder",
+      "permission": "projects",
+      "items": [
+        {"text": "Manage projects", "url": "#/projects", "icon": "folder", "permission": "projects"}
+      ]
+    },
+    {
+      "text": "Content",
+      "icon": "edit",
+      "items": [
+        {"text": "Pages", "url": "#/pages", "icon": "file-text", "permission": "pages"},
+        {"text": "Media", "url": "#/media", "icon": "image",     "permission": "media"},
+        {"text": "Menus", "url": "#/menus", "icon": "menu",      "permission": "menus"}
+      ]
+    },
+    {
+      "text": "Data",
+      "icon": "database",
+      "items": [
+        {"text": "Collections", "url": "#/collections", "icon": "database",  "permission": "collections"},
+        {"text": "Forms",       "url": "#/forms",       "icon": "layout",    "permission": "collections"},
+        {"text": "Views",       "url": "#/views",       "icon": "eye",       "permission": "views"},
+        {"text": "Actions",     "url": "#/actions",     "icon": "zap",       "permission": "actions"},
+        {"text": "Blocks",      "url": "#/blocks",      "icon": "box",       "permission": "pages"},
+        {"text": "Components",  "url": "#/components",  "icon": "component", "permission": "components"}
+      ]
+    },
+    {
+      "text": "System",
+      "icon": "settings",
+      "items": [
+        {"text": "Notifications", "url": "#/system/notifications", "icon": "bell",     "permission": "notifications"},
+        {"text": "Roles",         "url": "#/roles",                "icon": "shield",   "permission": "plugins"},
+        {"text": "Users",         "url": "#/users",                "icon": "users",    "permission": "users"},
+        {"text": "Site Settings", "url": "#/settings",             "icon": "settings", "permission": "settings"},
+        {"text": "Effects",       "url": "#/effects",              "icon": "sparkles", "permission": "settings"},
+        {"text": "Layouts",       "url": "#/layouts",              "icon": "layout",   "permission": "layouts"},
+        {"text": "Plugins",       "url": "#/plugins",              "icon": "package",  "permission": "plugins"},
+        {"text": "My Profile",    "url": "#/my-profile",           "icon": "user"}
+      ]
+    },
+    {
+      "text": "Documentation",
+      "icon": "book",
+      "items": [
+        {"text": "Usage",         "url": "#/documentation",  "icon": "book"},
+        {"text": "Tutorials",     "url": "#/tutorials",      "icon": "document"},
+        {"text": "API Reference", "url": "#/api-reference",  "icon": "code"}
+      ]
+    }
+  ]
+}
+```
+
+### Projects - special-case rendering
+
+Per-project entries are NOT stored in the menu JSON. The `Projects` top-level item is a placeholder (it has only the static `Manage projects` child by default). At render time, the sidebar renderer:
+
+1. Detects the item with `id === 'projects'` (or text `Projects`)
+2. Calls `/api/projects` to get the user's visible projects + per-project artefact counts
+3. Synthesises a child item per project with sub-items (Overview, populated type rows, Settings) - same shape as the current procedural code
+
+This keeps per-project entries dynamic (they react to data changes without menu edits) while letting the admin still re-order or hide the `Projects` parent in the menu editor.
+
+## Server-side Services
+
+### `server/services/sidebar-migration.js` (new)
+
+`runMigration({configDir})` - idempotent one-shot. Guarded by the existence of `config/menus/admin-sidebar.json`. Steps:
+
+1. If `config/menus/admin-sidebar.json` exists → return `{migrated: false, reason: 'already present'}`
+2. Write the seeded menu JSON (the shape above) to `config/menus/admin-sidebar.json`
+3. Patch `config/menu-locations.json` to add `"admin-sidebar": "admin-sidebar"`
+4. Log success
+
+The seeded JSON is held in code (in the migration module). Future admin edits don't touch the migration - once the file exists, the migration is permanently skipped.
+
+### `server/services/menus.js`
+
+- Register the `admin-sidebar` core slot at module load (alongside the existing three core slots).
+- Update `validateMenu` to allow the `permission` field on items (no validation of the value - that's a registry lookup at render time, runtime-tolerant).
+
+### `server/services/hooks.js`
+
+Add the `registerSidebarItem(opts)` export. Plugin-call shape:
+
+```js
+hooks.registerSidebarItem({
+    parent: 'system',        // existing item id to nest under; default = root level
+    item: {
+        text:       'My Plugin',
+        url:        '#/plugins/my-plugin',
+        icon:       'package',
+        permission: 'plugins'
+    }
+});
+```
+
+Storage: module-level array `_registeredSidebarItems`. Exposed via `getRegisteredSidebarItems()` for the admin renderer to consume. Not persisted - plugins re-register on each server boot via their `setupPlugin()` hook.
+
+## Server-side Boot Wiring
+
+In `server/server.js`, after config load and before route registration (i.e. alongside the existing menus migration call):
+
+```js
+try {
+    const {runMigration: runSidebarMigration} = await import('./services/sidebar-migration.js');
+    await runSidebarMigration();
+} catch (err) {
+    app.log.warn(`[admin-sidebar] Migration skipped: ${err.message}`);
+}
+```
+
+## Admin Renderer
+
+### `admin/js/lib/sidebar-renderer.js` (new)
+
+Drop-in replacement for the existing `Domma.elements.sidebar(...)` call. Signature:
+
+```js
+export async function renderAdminSidebar({mount, user, permissions, counts}) {
+    // ...
+}
+```
+
+Behaviour:
+
+1. Fetch the resolved admin-sidebar menu via `/api/menus/admin-sidebar` (or the slug mapped at the `admin-sidebar` slot).
+2. Fetch `/api/projects` and per-project artefact counts (for the synthesised Projects sub-tree).
+3. Fetch dynamically-registered plugin items (from a new endpoint `/api/sidebar/registered-items` that returns the server-side `_registeredSidebarItems` snapshot).
+4. Merge plugin items into the tree under their declared `parent`.
+5. Walk the tree, filtering items by `permission` (using the supplied `permissions` array).
+6. Render as nested `<details>`/`<summary>` elements. Expansion state per-item persists to `S.set('sidebar.expanded.<itemId>', bool)`.
+7. Apply `data-icon` + run `Domma.icons.scan()` after render.
+8. Wire the active-item indicator via `M.subscribe('router:afterChange', ...)`.
+
+The render is async (it fetches projects). The mount point shows a skeleton (or the last cached render) until the first response lands.
+
+**Fallback when no menu is mapped to `admin-sidebar`:** the renderer falls back to a minimal hardcoded tree containing only `Dashboard` + `Menus` (the second so the admin can navigate to fix the broken state). A WARN-level log entry is emitted. This covers: first boot before migration runs, an admin who deletes the menu by accident, or the menu file being lost on disk.
+
+### `admin/js/app.js`
+
+Find the existing `Domma.elements.sidebar('#admin-sidebar', {...})` call (around line 150). Replace with:
+
+```js
+const {renderAdminSidebar} = await import('./lib/sidebar-renderer.js');
+await renderAdminSidebar({
+    mount:        '#admin-sidebar',
+    user,
+    permissions,
+    counts
+});
+```
+
+`buildSidebar(permissions)` simplifies - it no longer composes the items array; the renderer does that internally from menu data.
+
+### `admin/js/config/sidebar-config.js`
+
+Deprecated. Keep the file with a single-line export that returns `[]` for one release (in case any external code imports it). Add a deprecation comment at the top. Delete in v2.
+
+### `admin/js/views/menu-editor.js`
+
+The item-row template gains a `permission` field - a `<select>` populated from `/api/auth/permissions-registry` (already exposed). Default value: empty (no permission gate). The save handler includes `permission` on each item that has a value.
+
+### `admin/css/admin.css`
+
+Append styles for the `<details>`-based sidebar:
+
+```css
+#admin-sidebar details        { /* no native marker; we provide our own */ }
+#admin-sidebar details > summary {
+    list-style:    none;
+    cursor:        pointer;
+    display:       flex;
+    align-items:   center;
+    gap:           0.5rem;
+    padding:       0.4rem 0.75rem;
+    border-radius: 4px;
+}
+#admin-sidebar details > summary::-webkit-details-marker { display: none; }
+#admin-sidebar details > summary::after {
+    content:    '▸';
+    margin-left: auto;
+    transition:  transform 0.15s;
+}
+#admin-sidebar details[open] > summary::after { transform: rotate(90deg); }
+#admin-sidebar details > div     { padding-left: 1rem; }   /* indent rail for children */
+#admin-sidebar a.active          { background: var(--dm-accent-bg, rgba(0,0,0,0.06)); font-weight: 600; }
+```
+
+## Data Flow (on render)
+
+```
+Browser load
+  ↓
+admin/js/app.js buildSidebar() → renderAdminSidebar()
+  ↓
+GET /api/menu-locations           → slot map
+GET /api/menus/admin-sidebar      → full tree
+GET /api/auth/permissions         → user's permissions
+GET /api/projects                 → user-visible projects (for Projects branch)
+GET /api/projects/<slug>/artefacts (parallel per project) → per-section counts
+GET /api/sidebar/registered-items → plugin-injected items
+  ↓
+Merge plugin items + project sub-tree into menu data
+Filter by permission
+Render nested <details>/<summary>
+Apply icon scan + active-state subscriber
+```
+
+## API Surface
+
+One new endpoint:
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| `GET` | `/api/sidebar/registered-items` | `menus.read` | Plugin-registered sidebar items (read snapshot of `getRegisteredSidebarItems()`) |
+
+No new permission family - reuses `menus.read` for the registry endpoint, and the existing `permissionRegistry` keys for item gating.
+
+## Caching
+
+New cache tag:
+
+| Tag | Invalidated when |
+|---|---|
+| `admin-sidebar` | The `admin-sidebar` menu changes, or plugin items registered/removed |
+
+The sidebar renderer's fetches go through the existing per-role + per-user cache keying so scoped users see correctly-filtered sidebars.
+
+## Migration / Backwards Compat
+
+- **`Domma.elements.sidebar` API is untouched** - non-CMS Domma sites that use the sidebar component directly are unaffected.
+- **`sidebar-config.js` becomes a stub** for one release. Anyone importing it gets `[]` and a deprecation warning.
+- **Existing user installs auto-migrate on first boot.** No admin action required. The migration is idempotent - re-runs are no-ops.
+- **The Projects synth code** stays in `sidebar-renderer.js` rather than being injected into menu data, so a re-run of the sidebar migration doesn't try to re-import per-project entries.
+
+## Documentation Updates
+
+- `docs/configuration.md` - add a section on the `admin-sidebar` slot + the `permission` item field.
+- `docs/plugin-development.md` - document `hooks.registerSidebarItem()` alongside the existing hooks.
+- `docs/api-reference.md` - add `/api/sidebar/registered-items`.
+- `CLAUDE.md` - note that the admin sidebar is now menu-data-driven and editable from the Menus admin.
+
+## Out of Scope (Recorded for Later)
+
+- Per-user sidebar customisation
+- Drag-and-drop reorder directly in the sidebar
+- Sidebar themes
+- Removing the legacy `Domma.elements.sidebar` rendering path
+
+## Open Follow-Ups (Tracked)
+
+- **Once `domma-js` flyout PR lands**, optionally swap the `<details>`-based render for the native flyout behaviour (cleaner mobile UX).
+- **Sidebar visual editor** in the Menus admin - drag-drop reorder, live preview of the rendered sidebar.
+- **Plugin items declared in plugin manifest** (`plugin.json` `sidebar: {...}`) as an alternative to the `hooks.registerSidebarItem()` runtime call - declarative for plugins that don't need dynamic items.
+- **`roles` permission family** - the seeded menu gates the Roles item via `permission: 'plugins'` to preserve the current sidebar quirk. Once `roles.{read,create,update,delete}` exists as its own family, the seeded menu (and the migration) should switch to the proper key. Tracked separately because it touches the permission registry shape.