domma-cms 0.41.1 → 0.42.0

package/CLAUDE.md

@@ -147,6 +147,8 @@ See `docs/configuration.md` for full schema reference.
 
 Menus live in `config/menus/<slug>.json`. The slot → menu map lives in `config/menu-locations.json`. Built-in slots: `navbar`, `footer-primary`, `footer-legal`, `admin-sidebar`. Plugins register additional slots via `hooks.registerMenuLocation()`. The public navbar's brand is on `site.json.brand` (parallel to `adminBrand`); items + variant + position come from the menu mapped to `navbar`. The `[menu]` shortcode renders any menu inline (`[menu slug="…" /]` or `[menu location="…" /]`). On first boot the CMS auto-migrates the legacy `config/navigation.json` and `site.json.footer.links` into this system; the originals are renamed `.bak` and a one-release read-fallback restores the navbar from `navigation.json.bak` if the navbar slot is unmapped. See `docs/configuration.md` for full schema.
 
+**Overlay slot (place a menu anywhere).** `overlay` is a core slot that is *not* one-menu-wins: `resolveOverlaysForPage(ctx, user)` returns **every** menu bound to it that matches the page, plus the menu mapped to it in `menu-locations.json` (site-wide, deduped). The renderer injects them at the end of `<body>` via `buildOverlayMenus()`, so a `position: floating` overlay pins anywhere on the viewport with no navbar/footer/shortcode involved. Overlays with zero visible items after per-user filtering are dropped. Menu→HTML lives in `server/services/menuRender.js` (`buildMenuNav`/`renderMenuItemsAsUl`) and is shared with the `[menu]` shortcode, so both render identically — change markup there, not in markdown.js.
+
 **Bindings.** A menu can carry `binding: {slot, projects: [], pages: []}` and take that slot over on matching pages instead of being mapped globally. `resolveLocation(slot, user, {urlPath, project})` checks bindings first (exact page > `/glob/*` > project, longest pattern wins) and falls back to `menu-locations.json`; **callers that know the page must pass the ctx** or bindings silently never fire — `renderer.js` (both render paths) and `parseMarkdown({urlPath})` do. All menu files are cached in-process via `getAllMenus()`; anything writing a menu file outside `menus.js` must call `invalidateMenuIndex()` (the two boot migrations do).
 
 **Orientation.** `orientation: horizontal|vertical` + `side: left|right`. Vertical navbar = CSS rail over Domma's normal navbar markup (`#site-navbar.dm-nav-vertical` + server-stamped `body.dm-vnav-*` gutter, ≥993px only; below that the mobile drawer already applies). The `[menu]` shortcode emits `dm-menu--vertical|horizontal` **only when set** — no class means the historic plain-list rendering.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domma-cms",
-  "version": "0.41.1",
+  "version": "0.42.0",
   "description": "File-based CMS powered by Domma and Fastify. Run npx domma-cms my-site to create a new project.",
   "type": "module",
   "main": "server/server.js",

package/server/services/markdown.js

@@ -11,7 +11,8 @@ import {fileURLToPath} from 'url';
 import {applyTransforms, getSanitizeExtensions, getShortcodeProcessors} from './hooks.js';
 import {getConfig} from '../config.js';
 import {getCollection, listEntries} from './collections.js';
-import {getMenu, resolveLocation, resolveMenuDecorations, colourToCss, floatToCss} from './menus.js';
+import {getMenu, resolveLocation, resolveMenuDecorations} from './menus.js';
+import {buildMenuNav} from './menuRender.js';
 import {checkVisibility} from '../middleware/auth.js';
 
 const __dirname_md = path.dirname(fileURLToPath(import.meta.url));
@@ -3894,26 +3895,15 @@ async function processMenuBlocks(markdown, user, ctx = {}) {
 
         const depth = Number.parseInt(attrs.depth, 10);
         const capped = Number.isFinite(depth) && depth > 0 ? capDepth(items, depth) : items;
-        const klass        = attrs.class   ? ` ${escapeAttr(attrs.class)}`                    : '';
-        const variantClass = attrs.variant ? ` dm-menu--variant-${escapeAttr(attrs.variant)}` : '';
-        // Orientation: the shortcode attribute wins over the menu's own setting,
-        // so one placement can run horizontally while the menu is vertical in
-        // its slot. A menu that sets neither emits no orientation class at all
-        // and keeps the historic plain-nested-list rendering.
-        const orientation = ['horizontal', 'vertical'].includes(attrs.orientation)
-            ? attrs.orientation
-            : (['horizontal', 'vertical'].includes(menu.orientation) ? menu.orientation : null);
-        const orientClass = orientation ? ` dm-menu--${orientation}` : '';
         const decorated = await resolveMenuDecorations(capped);
-        // A floating menu pins itself to a viewport corner/edge. `float="no"`
-        // opts a single placement out, so the same menu can be floated in its
-        // slot yet rendered inline where the shortcode drops it.
-        const floatCss   = attrs.float === 'no' ? '' : floatToCss(menu);
-        const floatClass = floatCss ? ' dm-menu-floating' : '';
-        const floatAttrs = floatCss
-            ? ` style="${escapeAttr(floatCss)}" data-float-anchor="${escapeAttr(menu.float?.anchor || 'TL')}"`
-            : '';
-        const html = `<nav class="dm-menu dm-menu--${escapeAttr(menu.slug)}${orientClass}${variantClass}${floatClass}${klass}" data-menu="${escapeAttr(menu.slug)}"${floatAttrs}>${renderMenuItemsAsUl(decorated)}</nav>`;
+        // `orientation` overrides the menu for this one placement; `float="no"`
+        // renders inline here even when the menu floats in its slot.
+        const html = buildMenuNav(menu, decorated, {
+            orientation: attrs.orientation,
+            variant:     attrs.variant,
+            class:       attrs.class,
+            noFloat:     attrs.float === 'no'
+        });
         out = out.replace(m[0], html);
     }
     return out;
@@ -3942,32 +3932,6 @@ async function resolveProjectForUrl(urlPath) {
     }
 }
 
-function renderMenuItemsAsUl(items) {
-    if (!items.length) return '';
-    const lis = items.map(it => {
-        // Separator items render as a list-style <hr> divider.
-        if (it && it.type === 'separator') return '<li class="dm-menu-sep" role="separator"><hr></li>';
-        const href  = escapeAttr(it.url || '#');
-        const text  = escapeAttr(it.text || '');
-        const child = Array.isArray(it.items) && it.items.length ? renderMenuItemsAsUl(it.items) : '';
-
-        // Colour override (server sanitiser allows inline style on <a>).
-        const colourCss = it.colour ? colourToCss(it.colour) : '';
-        const styleAttr = colourCss ? ` style="color:${colourCss}"` : '';
-
-        // Badge (static text or resolver-stamped count). Background from variant.
-        let badge = '';
-        if (it.badge && it.badge.text != null && it.badge.text !== '') {
-            const bg = it.badge.variant ? colourToCss(it.badge.variant) : '';
-            const badgeStyle = bg ? ` style="background:${bg};color:#fff"` : '';
-            badge = `<span class="dm-menu-badge"${badgeStyle}>${escapeAttr(String(it.badge.text))}</span>`;
-        }
-
-        return `<li><a href="${href}"${styleAttr}>${text}${badge}</a>${child}</li>`;
-    }).join('');
-    return `<ul>${lis}</ul>`;
-}
-
 function capDepth(items, max, depth = 1) {
     return items.map(it => ({
         ...it,

package/server/services/menuRender.js

@@ -0,0 +1,90 @@
+/**
+ * Menu → HTML.
+ *
+ * One builder, three callers: the `[menu]` shortcode, the overlay menus the
+ * renderer injects into the page shell, and anything a plugin wants to render
+ * itself. Keeping it here means a menu looks the same however it reaches the
+ * page — the shortcode and an overlay binding of the same menu produce byte-
+ * identical markup.
+ *
+ * Item filtering (visibility, `hidden`), depth capping and badge-count
+ * resolution happen before this — callers hand in the items they want drawn.
+ */
+import {colourToCss, floatToCss} from './menus.js';
+
+/** Attribute-safe escaping — mirrors escapeAttr in markdown.js. */
+function esc(str) {
+    return String(str ?? '')
+        .replace(/&/g, '&')
+        .replace(/"/g, '"')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+
+/**
+ * Render a menu's items as a nested `<ul>`.
+ *
+ * Separators become a classed `<li><hr></li>`; colour, badge and nested
+ * children are drawn inline. Returns '' for an empty list so callers can
+ * decide whether an empty menu is worth a wrapper at all.
+ *
+ * @param   {Array} items
+ * @returns {string}
+ */
+export function renderMenuItemsAsUl(items) {
+    if (!items || !items.length) return '';
+    const lis = items.map(it => {
+        if (it && it.type === 'separator') return '<li class="dm-menu-sep" role="separator"><hr></li>';
+        const href  = esc(it.url || '#');
+        const text  = esc(it.text || '');
+        const child = Array.isArray(it.items) && it.items.length ? renderMenuItemsAsUl(it.items) : '';
+
+        // Colour override (the server sanitiser allows inline style on <a>).
+        const colourCss = it.colour ? colourToCss(it.colour) : '';
+        const styleAttr = colourCss ? ` style="color:${colourCss}"` : '';
+
+        // Badge — static text, or a count stamped on by resolveMenuDecorations.
+        let badge = '';
+        if (it.badge && it.badge.text != null && it.badge.text !== '') {
+            const bg = it.badge.variant ? colourToCss(it.badge.variant) : '';
+            const badgeStyle = bg ? ` style="background:${bg};color:#fff"` : '';
+            badge = `<span class="dm-menu-badge"${badgeStyle}>${esc(String(it.badge.text))}</span>`;
+        }
+
+        return `<li><a href="${href}"${styleAttr}>${text}${badge}</a>${child}</li>`;
+    }).join('');
+    return `<ul>${lis}</ul>`;
+}
+
+/**
+ * Build the full `<nav>` for a menu.
+ *
+ * @param {object} menu            The menu record (slug, orientation, position, float)
+ * @param {Array}  items           Items to draw — already filtered/capped/decorated
+ * @param {object} [opts]
+ * @param {string} [opts.orientation] Override the menu's own orientation for this placement
+ * @param {string} [opts.variant]     Adds `dm-menu--variant-<x>`
+ * @param {string} [opts.class]       Extra classes on the wrapper
+ * @param {boolean}[opts.noFloat]     Render inline even if the menu floats in its slot
+ * @returns {string}
+ */
+export function buildMenuNav(menu, items, opts = {}) {
+    const klass        = opts.class   ? ` ${esc(opts.class)}`                    : '';
+    const variantClass = opts.variant ? ` dm-menu--variant-${esc(opts.variant)}` : '';
+
+    // A menu that declares no orientation emits no class at all and keeps the
+    // historic plain-nested-list rendering.
+    const orientation = ['horizontal', 'vertical'].includes(opts.orientation)
+        ? opts.orientation
+        : (['horizontal', 'vertical'].includes(menu.orientation) ? menu.orientation : null);
+    const orientClass = orientation ? ` dm-menu--${orientation}` : '';
+
+    const floatCss   = opts.noFloat ? '' : floatToCss(menu);
+    const floatClass = floatCss ? ' dm-menu-floating' : '';
+    const floatAttrs = floatCss
+        ? ` style="${esc(floatCss)}" data-float-anchor="${esc(menu.float?.anchor || 'TL')}"`
+        : '';
+
+    return `<nav class="dm-menu dm-menu--${esc(menu.slug)}${orientClass}${variantClass}${floatClass}${klass}"`
+        + ` data-menu="${esc(menu.slug)}"${floatAttrs}>${renderMenuItemsAsUl(items)}</nav>`;
+}

package/server/services/menus.js

@@ -710,6 +710,11 @@ registerLocation('navbar',         {label: 'Navbar',         description: 'Site
 registerLocation('footer-primary', {label: 'Footer primary', description: 'Primary footer column', source: 'core', maxDepth: 1});
 registerLocation('footer-legal',   {label: 'Footer legal',   description: 'Legal/secondary footer column', source: 'core', maxDepth: 1});
 registerLocation('admin-sidebar',  {label: 'Admin sidebar',  description: 'The left-side navigation in the admin panel', source: 'core', maxDepth: null});
+// The overlay slot is the "anywhere" placement: menus bound to it render on
+// matching pages positioned by their own `float` config, with no navbar, no
+// footer and no shortcode involved. Unlike the other slots it is not
+// one-menu-wins — a page can carry several overlays at once.
+registerLocation('overlay',        {label: 'Page overlay',   description: 'Floating menus placed on matching pages by their binding', source: 'core', maxDepth: null});
 
 // ---------------------------------------------------------------------------
 // Slot → menu-slug map
@@ -904,6 +909,47 @@ export async function resolveLocation(slot, user, ctx = {}) {
     };
 }
 
+/** The slot whose menus are drawn over the page rather than in a fixed region. */
+export const OVERLAY_SLOT = 'overlay';
+
+/**
+ * Every overlay menu that applies to this page.
+ *
+ * Overlays are the "place a menu anywhere" path: instead of one menu winning a
+ * region, *all* menus whose binding matches the page render, each positioned by
+ * its own `float` config. A menu mapped to the overlay slot in
+ * menu-locations.json applies site-wide and joins the list.
+ *
+ * Menus left with no visible items after per-user filtering are dropped, so a
+ * fully gated overlay doesn't leave an empty box floating on the page.
+ *
+ * @param   {{urlPath?: string, project?: string|null}} ctx
+ * @param   {object|null} user
+ * @returns {Promise<object[]>} menus with filtered items, ordered by slug
+ */
+export async function resolveOverlaysForPage(ctx = {}, user = null) {
+    const bySlug = new Map();
+
+    for (const menu of await getAllMenus()) {
+        if (menu?.binding?.slot !== OVERLAY_SLOT) continue;
+        if (!scoreBinding(menu.binding, ctx)) continue;
+        bySlug.set(menu.slug, menu);
+    }
+
+    // A site-wide overlay: mapped rather than bound, so it needs no page rules.
+    const mappedSlug = (await getLocations())[OVERLAY_SLOT];
+    if (mappedSlug && !bySlug.has(mappedSlug)) {
+        const mapped = await getMenu(mappedSlug);
+        if (mapped) bySlug.set(mapped.slug, mapped);
+        else console.warn(`[menus] Overlay slot maps to "${mappedSlug}" which doesn't exist`);
+    }
+
+    return [...bySlug.values()]
+        .map(menu => ({...menu, items: filterItemsForUser(menu.items || [], user)}))
+        .filter(menu => menu.items.length > 0)
+        .sort((a, b) => String(a.slug).localeCompare(String(b.slug)));
+}
+
 function filterItemsForUser(items, user) {
     const out = [];
     for (const item of items) {

package/server/services/renderer.js

@@ -8,7 +8,8 @@ import {fileURLToPath} from 'url';
 import {getConfig} from '../config.js';
 import {getInjectionSnippets} from './plugins.js';
 import {applyTransforms} from './hooks.js';
-import {resolveLocation, resolveMenuDecorations} from './menus.js';
+import {resolveLocation, resolveMenuDecorations, resolveOverlaysForPage} from './menus.js';
+import {buildMenuNav} from './menuRender.js';
 import {getProjectForPage} from './projects.js';
 
 const VALID_LAYOUT_WIDTHS = new Set(['narrow', 'normal', 'wide', 'full']);
@@ -53,6 +54,26 @@ function filterHiddenNavItems(nav) {
     return {...nav, items};
 }
 
+/**
+ * Build the overlay menus for a page: every menu bound to the `overlay` slot
+ * whose binding matches, each drawn by the same builder the `[menu]` shortcode
+ * uses so an overlay and a shortcode of the same menu look identical.
+ *
+ * Emitted as bare <nav> elements with no wrapper — a wrapping element would
+ * risk becoming a containing block for their position:fixed pinning.
+ *
+ * @param {{urlPath?: string, project?: string|null}} menuCtx
+ * @param {object|null} user
+ * @returns {Promise<string>} concatenated HTML, '' when nothing applies
+ */
+async function buildOverlayMenus(menuCtx, user) {
+    const overlays = await resolveOverlaysForPage(menuCtx, user);
+    if (!overlays.length) return '';
+    const navs = await Promise.all(overlays.map(async (menu) =>
+        buildMenuNav(menu, await resolveMenuDecorations(menu.items))));
+    return navs.join('');
+}
+
 /**
  * Render a page to a full HTML string.
  *
@@ -89,10 +110,11 @@ export async function renderPage(page, opts = {}) {
 
     // Resolve live badge counts (countFrom) before the menus are injected as
     // globals. Static badges/colours/pills pass through unchanged.
-    const [navItemsDecorated, footerPrimaryDecorated, footerLegalDecorated] = await Promise.all([
+    const [navItemsDecorated, footerPrimaryDecorated, footerLegalDecorated, overlayMenus] = await Promise.all([
         resolveMenuDecorations(navMenu ? navMenu.items : []),
         resolveMenuDecorations(footerPrimary ? footerPrimary.items : []),
-        resolveMenuDecorations(footerLegal ? footerLegal.items : [])
+        resolveMenuDecorations(footerLegal ? footerLegal.items : []),
+        buildOverlayMenus(menuCtx, opts.user || null)
     ]);
 
     // Compose the navigation object the public site script expects:
@@ -220,6 +242,10 @@ export async function renderPage(page, opts = {}) {
         headInject: [injection.head, navbarFontLink].filter(Boolean).join('\n'),
         headInjectLate: [injection.headLate, customCssTag, navbarStyleTag].filter(Boolean).join('\n'),
         bodyEndInject: [
+            // Overlay menus — bound to the `overlay` slot and pinned by their own
+            // float config, so they belong at the end of the body, clear of the
+            // content flow.
+            overlayMenus,
             injection.bodyEnd,
             site.backToTop?.enabled    ? '<script src="/public/js/btt.js"></script>'             : '',
             site.cookieConsent?.enabled ? '<script src="/public/js/cookie-consent.js"></script>' : '',
@@ -516,10 +542,11 @@ export async function renderBlogPage(templatePath, data = {}, seoMeta = {}) {
 
     // Resolve live badge counts (countFrom) before the menus are injected as
     // globals. Static badges/colours/pills pass through unchanged.
-    const [navItemsDecorated, footerPrimaryDecorated, footerLegalDecorated] = await Promise.all([
+    const [navItemsDecorated, footerPrimaryDecorated, footerLegalDecorated, overlayMenus] = await Promise.all([
         resolveMenuDecorations(navMenu ? navMenu.items : []),
         resolveMenuDecorations(footerPrimary ? footerPrimary.items : []),
-        resolveMenuDecorations(footerLegal ? footerLegal.items : [])
+        resolveMenuDecorations(footerLegal ? footerLegal.items : []),
+        buildOverlayMenus(menuCtx, user)
     ]);
 
     // Compose the navigation object the public site script expects:
@@ -623,6 +650,7 @@ export async function renderBlogPage(templatePath, data = {}, seoMeta = {}) {
         headInject: [injection.head, navbarFontLink].filter(Boolean).join('\n'),
         headInjectLate: [injection.headLate, customCssTag, navbarStyleTag].filter(Boolean).join('\n'),
         bodyEndInject: [
+            overlayMenus,
             injection.bodyEnd,
             (seoMeta.usedComponents || [])
                 .map(n => `<script type="module" src="/api/components/${n}.js"></script>`)