domma-cms 1.6.59 → 1.7.0

package/docs/superpowers/specs/2026-05-24-menus-design.md

@@ -0,0 +1,466 @@
+# Menus Design
+
+**Date:** 2026-05-24
+**Status:** Approved
+**Scope:** Replace `config/navigation.json` (single navbar) and `config/site.json.footer.links` (single footer) with a multi-menu system. Arbitrary named menus, each a tree of items with per-menu style/behaviour overrides, mapped to named locations (slots) for theme injection and renderable inline via a `[menu]` shortcode.
+
+## Problem
+
+The CMS today has exactly two implicit menus:
+
+- A single navbar described by `config/navigation.json` (`brand`, `items`, `variant`, `position`, `style`). Items support one level of nesting (parent + one dropdown level).
+- A single footer described by `config/site.json` → `footer.links` (`text`, `url`, `hidden`).
+
+These are conceptually the same thing - a list of links rendered in a slot - stored in two different config files with two different shapes. Sites that want a third menu (sidebar, members area, legal footer split from primary footer) have no path. Sites that want to render a curated list of links inside page content can only do it by hand-writing Markdown.
+
+The recipe scaffolder seeds collections, forms, actions, roles, and users - but cannot seed navigation. As scaffolder recipes become the unit of "install a feature", a plugin or recipe that installs e.g. a members area can create the pages but cannot wire them into the nav.
+
+## Goals
+
+- Multiple named menus, each a tree of items with unbounded depth.
+- Per-menu style/behaviour overrides (variant, position, style) that travel with the menu.
+- Named locations (slots) mapped to menus; theme/plugin code renders the menu mapped to its slot.
+- Plugin-contributed locations via a `registerMenuLocation` hook.
+- `[menu]` shortcode renders any menu (by slug or by location) inline anywhere in page content.
+- Per-item visibility gating matching the page-visibility shape.
+- Recipe scaffolder can seed menus and (optionally) map them to locations.
+- Auto-migration from `config/navigation.json` + `site.json.footer.links` on first boot, with a one-release `.bak` read-fallback for safety.
+
+## Non-Goals (YAGNI)
+
+- Mega-menu layouts (multi-column dropdowns with sections, images, embedded blocks). Tree depth handles this conceptually; presentation is a follow-up.
+- Per-menu A/B variants or scheduled menus.
+- Drag-and-drop reordering of locations themselves (registry is registered-only; the order is presentational, not behavioural).
+- Multi-site menu sharing.
+- A bespoke renderer for the third level of dropdowns in the CMS layer - that work lands upstream in `domma-js` (see Prerequisites).
+
+## Prerequisites - `domma-js` work
+
+Tracked separately; Menus depends on a `domma-js` release containing both:
+
+- **Navbar flyout.** Nested `.navbar-dropdown` panels at depth ≥ 2. Hover-on-desktop / click-on-touch. ARIA `aria-haspopup="menu"` and `aria-expanded` on toggles. Keyboard arrow navigation, Home/End, Escape-to-close. Mobile accordion mode below the `md` breakpoint (configurable).
+- **Navbar `position: "floating"`.** New value alongside `sticky | fixed | static`. Renders with viewport margin (configurable via CSS custom property), border-radius, soft shadow. Transitions smoothly to `static` on mobile.
+
+The CMS-side renderer assembles the correct nested markup; `domma-js` handles behaviour and styling.
+
+## Data Model
+
+### Per-menu file: `config/menus/<slug>.json`
+
+```json
+{
+  "slug":        "main",
+  "name":        "Main navigation",
+  "description": "Top-level site nav",
+  "variant":     "transparent",
+  "position":    "floating",
+  "style": {
+    "fontFamily":    "Inter",
+    "fontSize":      "14px",
+    "fontWeight":    "500",
+    "letterSpacing": "0.01em",
+    "iconSize":      "15px"
+  },
+  "items": [
+    {
+      "text":       "Home",
+      "url":        "/",
+      "icon":       "home",
+      "hidden":     false,
+      "bundled":    false,
+      "visibility": "public",
+      "items":      []
+    },
+    {
+      "text": "Resources",
+      "url":  "/resources",
+      "icon": "book-open",
+      "items": [
+        {
+          "text": "Guides",
+          "url":  "/resources/guides",
+          "items": [
+            { "text": "Beginner", "url": "/resources/guides/beginner" },
+            { "text": "Advanced", "url": "/resources/guides/advanced" }
+          ]
+        }
+      ]
+    }
+  ],
+  "meta": {
+    "createdAt":   "2026-05-24T10:00:00Z",
+    "updatedAt":   "2026-05-24T10:00:00Z",
+    "bundled":     false,
+    "presetOwner": null
+  }
+}
+```
+
+**Menu fields**
+
+| Field         | Required | Type                    | Description                                                                                |
+|---------------|----------|-------------------------|--------------------------------------------------------------------------------------------|
+| `slug`        | yes      | string                  | URL-safe identifier; matches filename                                                      |
+| `name`        | yes      | string                  | Human-readable label shown in admin                                                        |
+| `description` | no       | string                  | Free text                                                                                  |
+| `variant`     | no       | string                  | Domma navbar variant - only meaningful in the navbar location                              |
+| `position`    | no       | string                  | `sticky | fixed | static | floating` - only meaningful in the navbar location              |
+| `style`       | no       | object                  | Font/spacing overrides; applied as CSS custom properties on the menu root                  |
+| `items`       | yes      | array                   | Items tree (depth-unbounded)                                                               |
+| `meta`        | no       | object                  | Audit / lifecycle metadata                                                                 |
+
+**Item fields**
+
+| Field        | Required | Type                       | Description                                                                       |
+|--------------|----------|----------------------------|-----------------------------------------------------------------------------------|
+| `text`       | yes      | string                     | Label                                                                             |
+| `url`        | yes      | string                     | href                                                                              |
+| `icon`       | no       | string                     | Domma icon name                                                                   |
+| `hidden`     | no       | boolean                    | Hard off-switch - never rendered                                                  |
+| `bundled`    | no       | boolean                    | Preset/plugin-seeded marker (mirrors today's nav editor)                          |
+| `visibility` | no       | string \| string[]         | `public | private | <role> | [<role>, ...]` (page-style). Defaults to `public`.    |
+| `items`      | no       | array                      | Nested children                                                                   |
+
+`visibility` is checked at render time by `checkVisibility(userRole, visibility)` from `server/middleware/auth.js` (already in use for pages). Items the requesting user can't see are removed from the rendered output server-side.
+
+### Slot mapping: `config/menu-locations.json`
+
+```json
+{
+  "navbar":         "main",
+  "footer-primary": "footer",
+  "footer-legal":   "legal"
+}
+```
+
+Keys are slot names (must exist in the registry). Values are menu slugs (must resolve to a file in `config/menus/`). Unmapped slots render empty. Mappings to non-existent menus log a warning at request time and render empty.
+
+### Locations registry
+
+Built-in slots registered by core in `server/services/menus.js`:
+
+| Slot             | Where it renders                                     | Default `maxDepth` |
+|------------------|------------------------------------------------------|--------------------|
+| `navbar`         | `server/templates/page.html` navbar                  | unbounded *(post-`domma-js` upgrade)* |
+| `footer-primary` | Primary footer column rendered by `public/js/site.js`| 1                  |
+| `footer-legal`   | Legal/secondary footer column                        | 1                  |
+
+Plugins register additional slots through a new hook on `server/services/hooks.js`:
+
+```js
+hooks.registerMenuLocation('sidebar', {
+  label:       'Sidebar',
+  description: 'Renders in the left sidebar of pages with sidebar layout',
+  maxDepth:    1
+});
+```
+
+`maxDepth` is advisory - the admin UI surfaces a warning when a mapped menu's depth exceeds it, but rendering still attempts to flatten beyond the cap.
+
+## Server-side Services
+
+### `server/services/menus.js` (new)
+
+| Export                       | Description                                                                    |
+|------------------------------|--------------------------------------------------------------------------------|
+| `listMenus()`                | Returns array of `{slug, name, description, meta}` (no items)                  |
+| `getMenu(slug)`              | Returns the full menu file as parsed JSON, or `null`                           |
+| `createMenu(menu)`           | Validates + writes a new menu file; refuses on slug collision                  |
+| `updateMenu(slug, menu)`     | Validates + writes; preserves `meta.createdAt`, updates `meta.updatedAt`       |
+| `deleteMenu(slug)`           | Refuses if the slug appears in `menu-locations.json`; otherwise unlinks file   |
+| `duplicateMenu(slug)`        | Copies as `<slug>-copy` (next-available suffix)                                |
+| `getLocations()`             | Reads `menu-locations.json` (default `{}`)                                     |
+| `setLocations(map)`          | Validates keys against registry + values against existing menus; writes file   |
+| `registerLocation(slot, def)`| Core/plugin slot registration                                                  |
+| `getLocationRegistry()`      | Returns `[{slot, label, description, maxDepth, source}]`                       |
+| `resolveLocation(slot, user)`| Returns the menu mapped to `slot` with items filtered by `user`'s visibility   |
+
+Core registers `navbar`, `footer-primary`, `footer-legal` at module load. Plugin hooks fire during `setupPlugin()`.
+
+### Validation
+
+Implemented in `server/services/menus.js` and shared by the API + scaffolder paths:
+
+- `slug` matches `/^[a-z0-9][a-z0-9-]*$/` (mirrors existing collection slug rules).
+- `items[].url` is a non-empty string starting with `/`, `#`, `http://`, `https://`, or `mailto:`.
+- `items[].visibility` parsed by the same helper as page frontmatter; unknown roles fail validation.
+- Cycle detection on save: no node may appear twice in the tree (slug + position fingerprint).
+- `position` ∈ `{sticky, fixed, static, floating}` when set.
+
+## API Surface
+
+`server/routes/api/menus.js` (new) and `server/routes/api/menu-locations.js` (new), registered from `server/server.js`.
+
+| Method   | Path                                | Permission       | Description                                                          |
+|----------|-------------------------------------|------------------|----------------------------------------------------------------------|
+| `GET`    | `/api/menus`                        | `menus.read`     | List menus (slug, name, description, meta)                           |
+| `GET`    | `/api/menus/:slug`                  | `menus.read`     | Full menu including items                                            |
+| `POST`   | `/api/menus`                        | `menus.create`   | Create a new menu                                                    |
+| `PUT`    | `/api/menus/:slug`                  | `menus.update`   | Replace a menu                                                       |
+| `DELETE` | `/api/menus/:slug`                  | `menus.delete`   | Delete (409 if mapped to a location)                                 |
+| `POST`   | `/api/menus/:slug/duplicate`        | `menus.create`   | Copy as `<slug>-copy`                                                |
+| `GET`    | `/api/menu-locations`               | `menus.read`     | Current slot → menu map                                              |
+| `PUT`    | `/api/menu-locations`               | `menus.update`   | Replace slot map (validates against registry + existing menus)        |
+| `GET`    | `/api/menu-locations/registry`      | `menus.read`     | All registered slots (core + plugin-contributed) with metadata        |
+
+### Permissions
+
+New family `menus.{read, create, update, delete}` added to `server/services/permissionRegistry.js`. Defaults:
+
+| Role        | read | create | update | delete |
+|-------------|:----:|:------:|:------:|:------:|
+| subscriber  | ❌   | ❌     | ❌     | ❌     |
+| editor      | ✅   | ❌     | ❌     | ❌     |
+| manager     | ✅   | ✅     | ✅     | ❌     |
+| admin       | ✅   | ✅     | ✅     | ✅     |
+
+## Public Renderer Integration
+
+### Navbar slot
+
+`server/services/renderer.js` currently injects `window.__CMS_NAV__` from `getConfig('navigation')`. Updated flow:
+
+1. Read `menu-locations.json` → resolve slot `navbar` to a menu slug.
+2. `resolveLocation('navbar', user)` returns the menu with items filtered by visibility.
+3. Read `site.json.brand` (new top-level field, parallel to existing `adminBrand` - populated by migration; admins edit it from the Settings view in a follow-up task).
+4. Compose `{brand, items, variant, position, style}`:
+   - `items` from the resolved menu.
+   - `variant`, `position`, `style` from the menu's own overrides, falling back to defaults.
+5. Inject as `window.__CMS_NAV__` - key preserved so `public/js/site.js` reads it unchanged.
+
+### Footer slots
+
+`public/js/site.js` footer init reads a new injected global `window.__CMS_FOOTER__`:
+
+```js
+window.__CMS_FOOTER__ = {
+  primary:   [/* items from menu mapped to footer-primary */],
+  legal:     [/* items from menu mapped to footer-legal */],
+  copyright: "© 2026 My Company"
+};
+```
+
+`copyright` stays on `site.json`. Footer items come from the mapped menus.
+
+### `[menu]` shortcode
+
+Processed by `server/services/markdown.js` after grids and cards (same processing tier as `[block]` / `[view]` / `[collection]`).
+
+```
+[menu slug="legal" /]
+[menu location="footer-primary" /]
+[menu slug="legal" variant="inline" class="prose-nav" /]
+[menu slug="legal" depth="2" /]
+```
+
+**Attributes**
+
+| Attr       | Description                                                                              |
+|------------|------------------------------------------------------------------------------------------|
+| `slug`     | Render this menu by slug. One of `slug` or `location` required.                          |
+| `location` | Render whichever menu is currently mapped to this slot.                                  |
+| `variant`  | Optional render variant override                                                         |
+| `class`    | Extra CSS class on the wrapper                                                           |
+| `depth`    | Cap render depth (integer ≥ 1); items deeper than this are dropped from the output      |
+
+**Output**
+
+```html
+<nav class="dm-menu dm-menu--legal {class}" data-menu="legal">
+  <ul>
+    <li><a href="/privacy">Privacy</a></li>
+    <li>
+      <a href="/legal">Legal</a>
+      <ul>
+        <li><a href="/legal/terms">Terms</a></li>
+      </ul>
+    </li>
+  </ul>
+</nav>
+```
+
+Visibility filtering runs server-side per request, so each user sees only the items their role permits.
+
+## Admin UI
+
+### Sidebar entry
+
+"Navigation" sidebar item is renamed to "Menus" and points at `#/menus`. A hash redirect from `#/navigation` to `#/menus` preserves any bookmarked links during the transition.
+
+### `#/menus` - list view
+
+`admin/js/views/menus.js` + `admin/js/templates/menus.html`.
+
+`T.create()` table:
+
+| Column   | Content                                                                       |
+|----------|-------------------------------------------------------------------------------|
+| Slug     | Menu slug                                                                     |
+| Name     | Human-readable name                                                           |
+| Items    | Top-level item count, with a `(depth N)` suffix when the tree depth > 1       |
+| Mapped   | Chips for each location the menu is mapped to (`navbar`, `footer-primary`)    |
+| Bundled  | Badge if `meta.bundled === true`                                              |
+| Actions  | Edit · Duplicate · Delete (Delete disabled with tooltip if mapped)            |
+
+Top-right toolbar: "New menu" button, "Manage locations" button (opens `#/menu-locations`).
+
+### `#/menus/:slug` - per-menu editor
+
+`admin/js/views/menu-editor.js` + `admin/js/templates/menu-editor.html`.
+
+Three tabs (using `E.tabs()` with the verified class names - `.tabs`, `.tab-list`, `button.tab-item`, `.tab-panel`):
+
+**Items tab.** Tree editor with:
+
+- Recursive item rows, indented per depth level
+- Drag-to-reparent (HTML5 drag-and-drop on row handles)
+- Indent / outdent buttons per row (keyboard fallback to drag-and-drop)
+- Per-row fields: text, url, icon, visibility chooser (`F.create` blueprint reused from page editor)
+- Per-row toggles: bundled, hidden, delete
+- "Add item" button inserts a new item at root
+- Move-up / move-down arrows for ordering within a parent
+
+**Behaviour tab.** `F.create` blueprint:
+
+- `variant` - select (`transparent`, `dark`, `light`, `default`)
+- `position` - select (`sticky`, `fixed`, `static`, `floating`)
+- `style` group - text inputs for `fontFamily`, `fontSize`, `fontWeight`, `letterSpacing`, `iconSize`
+
+**Meta tab.** `F.create` blueprint:
+
+- `name`, `description`
+- `slug` - rename (with `await E.confirm()` warning if the menu is currently mapped to any location or referenced by any `[menu slug="..."]` shortcode found in pages)
+
+Save sends `PUT /api/menus/:slug`. On rename, the editor issues a three-request sequence: `POST /api/menus` (write the menu under the new slug) → `PUT /api/menu-locations` (rewrite any slot mapped to the old slug to point at the new one) → `DELETE /api/menus/<old>` (now unmapped, deletion succeeds). If the third call fails for any reason, the new menu and updated mappings are already live, so the worst-case state is a leftover orphan menu file under the old slug - surfaced for cleanup in the menus list rather than a broken site.
+
+### `#/menu-locations` - locations editor
+
+`admin/js/views/menu-locations.js`.
+
+Table of registered slots from `/api/menu-locations/registry`:
+
+| Column      | Content                                                              |
+|-------------|----------------------------------------------------------------------|
+| Slot        | `slot` (machine name)                                                |
+| Label       | `def.label` (human-readable)                                         |
+| Source      | `core` or plugin name                                                |
+| Description | `def.description`                                                    |
+| Mapped menu | `<select>` of menu slugs (+ "- none -" for unmapped)                |
+| Warnings    | If selected menu's depth > `maxDepth`, surfaces an inline warning    |
+
+Save sends `PUT /api/menu-locations` with the complete map.
+
+## Migration (Auto on Boot)
+
+`server/services/menus-migration.js` (new). Called from `server/server.js` startup, after config load, before route registration.
+
+```js
+async function migrateLegacyNavIfPresent() {
+  // 1. Ensure config/menus/ exists
+  // 2. If config/menu-locations.json exists → already migrated, return
+  // 3. If config/navigation.json present:
+  //    - Write config/menus/main.json with slug='main', name='Main navigation',
+  //      and the items + variant + position + style from navigation.json
+  //    - Copy navigation.json.brand into site.json under a new top-level
+  //      `brand` field (parallel to the existing `adminBrand`). The public
+  //      renderer reads site.json.brand when composing the navbar.
+  //    - Record navbar → main in locations map
+  //    - Rename original to config/navigation.json.bak
+  // 4. If site.json.footer.links.length:
+  //    - Convert to config/menus/footer.json
+  //    - Record footer-primary → footer in locations map
+  //    - Set site.json.footer.links = [] (preserve copyright)
+  // 5. Write config/menu-locations.json
+  // 6. Log:
+  //    [menus] Migrated navigation.json → menus/main.json + locations.navbar
+  //    [menus] Migrated footer.links → menus/footer.json + locations.footer-primary
+}
+```
+
+Migration is one-shot - re-running has no effect (the existence of `config/menu-locations.json` is the guard).
+
+### Read-fallback (one release)
+
+If the navbar location resolves to no menu (admin deleted it, mapping is empty, or the file was lost) **and** `config/navigation.json.bak` exists, the renderer falls back to reading the `.bak` so a site that restored its backup keeps rendering. Logged at WARN level:
+
+```
+[menus] navbar location unmapped - falling back to navigation.json.bak (will be removed in v2)
+```
+
+The fallback is documented as deprecated and removed in the next major version.
+
+## Scaffolder Integration
+
+Recipe format (`server/services/recipes/*.json`) gains an optional `menus` array, parallel to `collection`, `form`, `actions`:
+
+```json
+"menus": [
+  {
+    "slug":      "{{menuSlug}}",
+    "name":      "{{menuName}}",
+    "items":     [
+      { "text": "Members", "url": "/members" },
+      { "text": "Profile", "url": "/members/profile" }
+    ],
+    "variant":   "default",
+    "position":  "sticky",
+    "locations": ["sidebar"]
+  }
+]
+```
+
+`server/services/scaffolder.js` gains a new step in the apply pipeline, **between roles and collection**:
+
+1. Pre-flight: refuse if any menu slug already exists.
+2. Apply: validate + write each menu file. If `locations[]` present, validate each slot against the registry; refuse to overwrite an existing mapping unless the recipe entry sets `force: true`.
+
+Failures degrade gracefully - a single conflicting menu slug aborts pre-flight (consistent with existing recipe behaviour); a missing slot reference logs a warning and continues.
+
+The Projects feature (next brainstorm) builds on this: a Project IS a recipe's output, so Projects will own menus alongside collections, forms, and actions under the project's namespace.
+
+## Caching
+
+New cache tags registered with `server/services/cache/index.js`:
+
+| Tag                   | Invalidated when                                                                |
+|-----------------------|---------------------------------------------------------------------------------|
+| `menu:<slug>`         | The menu is created / updated / deleted                                         |
+| `menu-locations`      | The slot map is saved                                                           |
+| `nav` *(preserved)*   | Either of the above, when the affected menu/slot is the one feeding the navbar |
+
+Per-request cache key composition is unchanged. The renderer's existing per-role cache key (`role${userRole ?? 'anon'}`) gates visibility-filtered menus correctly - anonymous users and members see different navs but each tier is cached.
+
+## Plugin Hook
+
+`server/services/hooks.js` gains `registerMenuLocation(slot, def)`. Definition shape:
+
+| Field         | Required | Description                                          |
+|---------------|----------|------------------------------------------------------|
+| `label`       | yes      | Human-readable slot name shown in admin              |
+| `description` | no       | What the slot is for and where it renders            |
+| `maxDepth`    | no       | Advisory depth cap; admin warns on overflow          |
+
+Slot names must match `/^[a-z0-9][a-z0-9-]*$/` (same shape as menu slugs). Re-registering an existing slot logs a warning and the second registration wins (last-write semantics - the same pattern used by other plugin hooks).
+
+## Documentation Updates
+
+- `docs/configuration.md` - replace the `config/navigation.json` section with `config/menus/` and `config/menu-locations.json`; document the menu item shape and the location registry.
+- `docs/markdown-shortcodes.md` - add `[menu]` entry alongside `[block]` / `[view]` / `[collection]`.
+- `docs/plugin-development.md` - document `hooks.registerMenuLocation()` alongside existing hooks.
+- `docs/scaffolding.md` - add the `menus` branch to the recipe format reference.
+- `CLAUDE.md` (project) - update the Domma navbar dropdown section to note multi-menu architecture and link to the new docs.
+
+## Out of Scope (Recorded for Later)
+
+- **Mega-menu layouts.** Tree depth supports the data; presentation belongs in a follow-up.
+- **Per-menu A/B variants / scheduled menus.** No current use case.
+- **Drag-to-reorder locations.** Registry order is presentational only.
+- **Multi-site menu sharing.** Out of scope until multi-site is.
+- **Built-in `sidebar` slot.** A sidebar slot is shown as a plugin-registration example in section 3, not registered by core. Adding a default sidebar layout + a core-registered `sidebar` slot is a separate spec.
+
+## Open Follow-Ups (Tracked)
+
+- **Projects feature** - next brainstorm cycle. Recipe-apply produces a Project; Menus is one of the things a Project owns.
+- **Bundled-menu lifecycle parity** - extend the bundled/plugin metadata machinery (memory: `project_bundled_plugin_system.md`) to cover menus so plugins can install/teardown menus cleanly.
+- **`domma-js` flyout + floating PR** - prerequisite; lands before Menus ships.
+- **Settings UI for `site.json.brand`.** Migration creates the field; an editor in the Settings admin view lets admins update brand text/icon/logo/url without hand-editing JSON. Small follow-up - the same form blueprint pattern as `adminBrand`.