domma-cms 1.6.59 → 1.7.0

package/docs/superpowers/specs/plans/2026-03-17-nav-hidden-items.md

@@ -0,0 +1,578 @@
+# Nav Hidden Items Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or
+> superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a per-item "hidden" toggle to the navigation editor so items and footer links can be suppressed from the
+public site without deleting them.
+
+**Architecture:** A `hidden: true` flag is stored optionally on each nav item and footer link in their respective config
+files. The admin editor toggles this flag in-memory and saves it via the existing Save button. At render time,
+`renderer.js` strips hidden items before serialising `__CMS_NAV__` into the public page - hidden data never reaches the
+browser.
+
+**Tech Stack:** Fastify 5 (ESM) backend, Domma SPA admin (Domma JS framework), CSS in `admin/css/admin.css`.
+
+**Spec:** `docs/superpowers/specs/2026-03-17-nav-hidden-items-design.md`
+
+---
+
+## File Map
+
+| File                                 | What changes                                                                                                                            |
+|--------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
+| `server/services/renderer.js`        | Add `filterHiddenNavItems()` helper; apply before building `navJson` and `siteJson`                                                     |
+| `admin/css/admin.css`                | Add `.nav-item-row--hidden` and `.btn-toggle-hidden.active` styles                                                                      |
+| `admin/js/views/navigation.js`       | `flattenItems`, `nestItems`, `footerLinks` init, `syncFromDom`, `syncFooterFromDom`, `renderItems`, `renderFooterLinks`, click handlers |
+| `admin/js/templates/navigation.html` | Add "Actions" label to both `nav-col-action` header spans                                                                               |
+
+---
+
+## Task 1: Server-side filtering
+
+**Files:**
+
+- Modify: `server/services/renderer.js`
+
+The goal is to strip `hidden: true` items before the nav config is JSON-serialised into the public page. The filter must
+handle:
+
+- Top-level items (hidden parent → entire entry gone, children included)
+- Children of visible parents (hidden child → removed from parent's `items` array)
+- Footer links in `site.footer.links`
+
+The codebase only supports two levels of nesting, so no recursive traversal is needed.
+
+- [ ] **Step 1.1: Open `server/services/renderer.js` and add the filter helper**
+
+  Add this function before the JSDoc block that documents `renderPage` (the JSDoc starts at line 33 with
+  `/** Render a page...`). Do NOT insert it between the JSDoc and the function signature - place it before line 33:
+
+  ```js
+  /**
+   * Strip hidden items from the navigation config before public injection.
+   * Returns a shallow clone - never mutates the cached config object.
+   *
+   * @param {object} nav - Raw navigation config from getConfig('navigation')
+   * @returns {object} Filtered navigation object safe for public injection
+   */
+  function filterHiddenNavItems(nav) {
+      const items = (nav.items || [])
+          .filter(item => !item.hidden)
+          .map(item => {
+              if (!item.items?.length) return item;
+              const visibleChildren = item.items.filter(c => !c.hidden);
+              return visibleChildren.length === item.items.length
+                  ? item
+                  : { ...item, items: visibleChildren };
+          });
+      return { ...nav, items };
+  }
+  ```
+
+- [ ] **Step 1.2: Apply the filter in `renderPage`**
+
+  Find line 101 in `renderer.js`:
+  ```js
+  navJson: JSON.stringify(navigation).replace(/<\/script>/gi, '<\\/script>'),
+  ```
+
+  Replace it with:
+  ```js
+  navJson: JSON.stringify(filterHiddenNavItems(navigation)).replace(/<\/script>/gi, '<\\/script>'),
+  ```
+
+- [ ] **Step 1.3: Filter footer links in `siteJson`**
+
+  Find the `siteJson` block (lines 102-107). Replace the opening of `Object.assign`:
+
+  From:
+  ```js
+  siteJson: JSON.stringify(Object.assign(
+      { title: site.title, footer: site.footer, social: site.social || null },
+  ```
+
+  To:
+  ```js
+  siteJson: JSON.stringify(Object.assign(
+      {
+          title: site.title,
+          footer: site.footer
+              ? {
+                  ...site.footer,
+                  links: (site.footer.links || []).filter(l => !l.hidden)
+              }
+              : site.footer,
+          social: site.social || null
+      },
+  ```
+
+- [ ] **Step 1.4: Verify server-side filtering manually**
+
+  Temporarily edit `config/navigation.json` - add `"hidden": true` to one top-level item (e.g. "About"):
+
+  ```json
+  { "text": "About", "url": "/about", "icon": "info", "hidden": true }
+  ```
+
+  Then run (`getConfig` reads fresh from disk on every call - confirmed from `server/config.js` line 30-32:
+  `return JSON.parse(fs.readFileSync(...))` - no caching, no restart needed):
+  ```bash
+  curl -s http://localhost:4096/ | grep -o '__CMS_NAV__ = [^;]*' | head -c 500
+  ```
+
+  Expected: the "About" item is **absent** from the JSON blob in the output.
+
+- [ ] **Revert the manual edit to `navigation.json`:**
+
+  ```bash
+  git checkout config/navigation.json
+  ```
+
+  Confirm the file is clean:
+  ```bash
+  git diff config/navigation.json
+  ```
+  Expected: no output (no changes).
+
+- [ ] **Step 1.5: Commit**
+
+  ```bash
+  git add server/services/renderer.js
+  git commit -m "feat: strip hidden nav items/footer links at render time"
+  ```
+
+---
+
+## Task 2: Admin CSS
+
+**Files:**
+
+- Modify: `admin/css/admin.css`
+
+- [ ] **Step 2.1: Add hidden-row styles**
+
+  Find the nav section in `admin/css/admin.css` (around line 423, just after `.nav-item-row--child`). Add:
+
+  ```css
+  .nav-col-action { display: flex; align-items: center; gap: .25rem; }
+
+  .nav-item-row--hidden { opacity: 0.45; }
+  .nav-item-row--hidden .item-text,
+  .nav-item-row--hidden .footer-link-text { text-decoration: line-through; }
+
+  .btn-toggle-hidden { color: var(--text-muted, #888); }
+  .btn-toggle-hidden.active { color: var(--color-warning, #f59e0b); }
+  ```
+
+  The `nav-col-action` flex rule is required - the span now holds two buttons and without it they render with no
+  controlled spacing. The amber `color-warning` gives the active (item-is-hidden) button state a distinct colour.
+
+- [ ] **Step 2.2: Visual regression check**
+
+  Open `http://localhost:4096/admin/#/navigation` in a browser. Layout should look identical to before - no new buttons
+  yet, just verifying the CSS additions don't break anything.
+
+- [ ] **Step 2.3: Commit**
+
+  ```bash
+  git add admin/css/admin.css
+  git commit -m "feat: add hidden nav row styles"
+  ```
+
+---
+
+## Task 3: Update `navigation.js` - data model
+
+**Files:**
+
+- Modify: `admin/js/views/navigation.js`
+
+**Note on `_nextId`:** This module-level counter never resets across view mounts - this is intentional. IDs only need to
+be unique within a session (not persistent), and an ever-incrementing counter guarantees that. Do not reset it.
+
+**Note on `.attr()` vs `.data()` - plan overrides spec:** The spec (line 41) suggests `.data('hidden') === 'true'`.
+This plan overrides that with `.attr('data-hidden') === 'true'` because Domma's `.data()` (jQuery-compatible) auto-coerces
+`"true"`/`"false"` attribute strings to actual booleans, making the `=== 'true'` string comparison always false. Using
+`.attr('data-hidden')` returns the raw string and makes the comparison work correctly. The spec is wrong on this specific
+point; follow the plan.
+
+**Note on `.data()` for numeric IDs:** The toggle click handlers use `$(this).data('id')` and `$(this).data('idx')` to
+read numeric IDs. `.data()` auto-coercing `"123"` → `123` is harmless (the `parseInt` call is a safe no-op on a
+number). The `.attr()` rule applies specifically to the boolean `data-hidden` attribute.
+
+### 3a - `flattenItems`: read `hidden` from JSON
+
+- [ ] **Step 3a.1: Update `flattenItems` (lines 10-20)**
+
+  Replace the whole function with:
+
+  ```js
+  function flattenItems(items) {
+      const flat = [];
+      (items || []).forEach(item => {
+          const id = _nextId++;
+          flat.push({ _id: id, text: item.text || '', url: item.url || '', icon: item.icon || '', hidden: item.hidden || false, parentId: null });
+          (item.items || item.children || []).forEach(child => {
+              flat.push({ _id: _nextId++, text: child.text || '', url: child.url || '', icon: child.icon || '', hidden: child.hidden || false, parentId: id });
+          });
+      });
+      return flat;
+  }
+  ```
+
+### 3b - `nestItems`: pass `hidden` through to JSON
+
+- [ ] **Step 3b.1: Update `nestItems` (lines 22-33)**
+
+  Replace the whole function with:
+
+  ```js
+  function nestItems(flat) {
+      return flat
+          .filter(i => i.parentId === null)
+          .map(parent => {
+              const children = flat
+                  .filter(i => i.parentId === parent._id)
+                  .map(c => ({
+                      text: c.text,
+                      url: c.url,
+                      ...(c.icon   && { icon: c.icon }),
+                      ...(c.hidden && { hidden: true }),
+                  }));
+              const obj = {
+                  text: parent.text,
+                  url: parent.url,
+                  ...(parent.icon   && { icon: parent.icon }),
+                  ...(parent.hidden && { hidden: true }),
+              };
+              if (children.length) obj.items = children;
+              return obj;
+          });
+  }
+  ```
+
+### 3c - `footerLinks` initialisation: preserve `hidden`
+
+- [ ] **Step 3c.1: Update the `footerLinks` initialisation in `onMount` (line 54)**
+
+  Find:
+  ```js
+  let footerLinks = (site.footer?.links || []).map(l => ({text: l.text || '', url: l.url || ''}));
+  ```
+
+  Replace with:
+  ```js
+  let footerLinks = (site.footer?.links || []).map(l => ({
+      text: l.text || '',
+      url: l.url || '',
+      ...(l.hidden && { hidden: true }),
+  }));
+  ```
+
+  **Why this matters:** Without this, any `hidden: true` flags that already exist in `site.json` will be silently
+  stripped when the view mounts. The first save after opening the editor would then write back the links without the
+  `hidden` flag, permanently losing the state.
+
+### 3d - `#add-nav-item` and `#add-footer-link` handlers: include `hidden`
+
+Edit these in document order (line 136 first, then line 156).
+
+- [ ] **Step 3d.1: Add `hidden` to the `#add-footer-link` push (line 136)**
+
+  Find:
+  ```js
+  footerLinks.push({text: '', url: ''});
+  ```
+
+  Replace with:
+  ```js
+  footerLinks.push({ text: '', url: '', hidden: false });
+  ```
+
+- [ ] **Step 3d.2: Add `hidden: false` to the `#add-nav-item` push (line 156)**
+
+  Find:
+  ```js
+  flatItems.push({ _id: _nextId++, text: '', url: '', icon: '', parentId: null });
+  ```
+
+  Replace with:
+  ```js
+  flatItems.push({ _id: _nextId++, text: '', url: '', icon: '', hidden: false, parentId: null });
+  ```
+
+  *(New items default to visible - `hidden: false` keeps the model consistent so `renderItems`/`renderFooterLinks` never encounter `undefined`.)*
+
+### 3e - `syncFromDom`: read `hidden` from toggle button
+
+- [ ] **Step 3e.1: Update `syncFromDom` (lines 56-72)**
+
+  Use `.attr('data-hidden')` (raw string) not `.data('hidden')` (auto-coerces to boolean). Also scope the selector to
+  `#nav-items-list .nav-item-row` so footer link rows (which share the `.nav-item-row` class) are not accidentally
+  matched:
+
+  ```js
+  const syncFromDom = () => {
+      $container.find('#nav-items-list .nav-item-row').each(function () {
+          const id = parseInt($(this).data('id'), 10);
+          const item = flatItems.find(i => i._id === id);
+          if (!item) return;
+          item.text   = $(this).find('.item-text').val();
+          item.url    = $(this).find('.item-url').val();
+          item.icon   = $(this).find('.item-icon').val();
+          item.hidden = $(this).find('.btn-toggle-hidden').attr('data-hidden') === 'true';
+          const parentVal = $(this).find('.item-parent').val();
+          item.parentId = parentVal ? parseInt(parentVal, 10) : null;
+      });
+      // Promote children whose parent is now itself a child
+      const childIds = new Set(flatItems.filter(i => i.parentId !== null).map(i => i._id));
+      flatItems.forEach(i => {
+          if (i.parentId !== null && childIds.has(i.parentId)) i.parentId = null;
+      });
+  };
+  ```
+
+### 3f - `syncFooterFromDom`: read `hidden` from toggle button
+
+- [ ] **Step 3f.1: Update `syncFooterFromDom` (lines 124-132)**
+
+  Use `.attr('data-hidden')` (raw string), same reasoning as `syncFromDom`:
+
+  ```js
+  const syncFooterFromDom = () => {
+      footerLinks = [];
+      $container.find('#footer-links-list .nav-item-row').each(function () {
+          const hidden = $(this).find('.btn-toggle-hidden').attr('data-hidden') === 'true';
+          const link = {
+              text: $(this).find('.footer-link-text').val().trim(),
+              url:  $(this).find('.footer-link-url').val().trim(),
+          };
+          if (hidden) link.hidden = true;
+          footerLinks.push(link);
+      });
+  };
+  ```
+
+  **Note on blank+hidden links:** If a footer link has no text or URL but is marked hidden, it will still be dropped by
+  the existing `validFooterLinks` filter in the save handler (`footerLinks.filter(l => l.text || l.url)`). This is
+  acceptable - a blank link has no value regardless of its hidden state.
+
+- [ ] **Step 3f.2: Commit the data-model changes**
+
+  ```bash
+  git add admin/js/views/navigation.js
+  git commit -m "feat: propagate hidden flag through nav flattenItems/nestItems/sync"
+  ```
+
+---
+
+## Task 4: Update `navigation.js` - render + interaction
+
+**Files:**
+
+- Modify: `admin/js/views/navigation.js`
+
+### 4a - `renderItems`: add toggle button, apply hidden class
+
+- [ ] **Step 4a.1: Replace `renderItems` (lines 74-103)**
+
+  ```js
+  const renderItems = () => {
+      const $list = $container.find('#nav-items-list').empty();
+      const topLevel = flatItems.filter(i => i.parentId === null);
+
+      getOrderedItems(flatItems).forEach(item => {
+          const isChild  = item.parentId !== null;
+          const isHidden = item.hidden === true;
+          const parentOptions = `<option value="">- top-level -</option>` +
+              topLevel
+                  .filter(t => t._id !== item._id)
+                  .map(t => `<option value="${t._id}"${t._id === item.parentId ? ' selected' : ''}>${esc(t.text) || '(untitled)'}</option>`)
+                  .join('');
+
+          $list.append(`
+              <div class="nav-item-row${isChild ? ' nav-item-row--child' : ''}${isHidden ? ' nav-item-row--hidden' : ''}" data-id="${item._id}">
+                  <span class="nav-col-indent">${isChild ? '↳' : ''}</span>
+                  <input type="text" class="form-input item-text nav-col-main" value="${esc(item.text)}" placeholder="Label">
+                  <input type="text" class="form-input item-url nav-col-main" value="${esc(item.url)}" placeholder="/url">
+                  <input type="text" class="form-input item-icon nav-col-icon" value="${esc(item.icon)}" placeholder="icon">
+                  <select class="form-select item-parent nav-col-parent">${parentOptions}</select>
+                  <span class="nav-col-action">
+                      <button class="btn btn-sm btn-ghost btn-toggle-hidden${isHidden ? ' active' : ''}" data-id="${item._id}" data-hidden="${isHidden}" data-tooltip="${isHidden ? 'Show' : 'Hide'}"><span data-icon="eye-off"></span></button>
+                      <button class="btn btn-sm btn-danger btn-remove-item" data-id="${item._id}" data-tooltip="Remove"><span data-icon="trash"></span></button>
+                  </span>
+              </div>
+          `);
+      });
+      Domma.icons.scan('#nav-items-list');
+      document.querySelectorAll('#nav-items-list [data-tooltip]').forEach(el => {
+          E.tooltip(el, {content: el.getAttribute('data-tooltip'), position: 'top'});
+      });
+  };
+  ```
+
+### 4b - `renderFooterLinks`: add toggle button, apply hidden class
+
+- [ ] **Step 4b.1: Replace `renderFooterLinks` (lines 105-122)**
+
+  ```js
+  const renderFooterLinks = () => {
+      const $list = $container.find('#footer-links-list').empty();
+      footerLinks.forEach((link, idx) => {
+          const isHidden = link.hidden === true;
+          $list.append(`
+              <div class="nav-item-row${isHidden ? ' nav-item-row--hidden' : ''}" data-footer-idx="${idx}">
+                  <input type="text" class="form-input footer-link-text nav-col-main" value="${esc(link.text)}" placeholder="Label">
+                  <input type="text" class="form-input footer-link-url nav-col-main" value="${esc(link.url)}" placeholder="/url">
+                  <span class="nav-col-action">
+                      <button class="btn btn-sm btn-ghost btn-toggle-hidden${isHidden ? ' active' : ''}" data-idx="${idx}" data-hidden="${isHidden}" data-tooltip="${isHidden ? 'Show' : 'Hide'}"><span data-icon="eye-off"></span></button>
+                      <button class="btn btn-sm btn-danger btn-remove-footer" data-idx="${idx}" data-tooltip="Remove"><span data-icon="trash"></span></button>
+                  </span>
+              </div>
+          `);
+      });
+      Domma.icons.scan('#footer-links-list');
+      document.querySelectorAll('#footer-links-list [data-tooltip]').forEach(el => {
+          E.tooltip(el, {content: el.getAttribute('data-tooltip'), position: 'top'});
+      });
+  };
+  ```
+
+### 4c - Wire up the toggle click handlers
+
+- [ ] **Step 4c.1: Add click handlers alongside the existing `btn-remove-item` / `btn-remove-footer` handlers (after
+  line ~165)**
+
+  Use scoped selectors (`#nav-items-list` / `#footer-links-list`) to prevent cross-list double-firing:
+
+  ```js
+  $container.off('click', '#nav-items-list .btn-toggle-hidden').on('click', '#nav-items-list .btn-toggle-hidden', function (e) {
+      e.stopPropagation();
+      syncFromDom();
+      const id = parseInt($(this).data('id'), 10);
+      const item = flatItems.find(i => i._id === id);
+      if (item) item.hidden = !item.hidden;
+      renderItems();
+  });
+
+  $container.off('click', '#footer-links-list .btn-toggle-hidden').on('click', '#footer-links-list .btn-toggle-hidden', function (e) {
+      e.stopPropagation();
+      syncFooterFromDom();
+      const idx = parseInt($(this).data('idx'), 10);
+      if (footerLinks[idx]) footerLinks[idx].hidden = !footerLinks[idx].hidden;
+      renderFooterLinks();
+  });
+  ```
+
+- [ ] **Step 4c.2: Commit the render + interaction changes**
+
+  ```bash
+  git add admin/js/views/navigation.js
+  git commit -m "feat: add hidden toggle button and visual treatment to nav editor rows"
+  ```
+
+---
+
+## Task 5: Update `navigation.html` - column headers
+
+**Files:**
+
+- Modify: `admin/js/templates/navigation.html`
+
+**Note on header label:** The spec suggests "Vis." as a dedicated column label for the toggle. This plan uses "Actions"
+instead because both the eye-off toggle and the trash button share the existing `nav-col-action` span - adding a
+separate narrow "Vis." column would require restructuring the column layout. "Actions" covers both controls and requires
+no layout changes. This is an intentional deviation from the spec's suggested label.
+
+- [ ] **Step 5.1: Update the Menu Items header**
+
+  Find the `nav-items-header` div inside the "Menu Items" card (lines 46-53). Change:
+  ```html
+  <span class="nav-col-action"></span>
+  ```
+  To:
+  ```html
+  <span class="nav-col-action text-muted"><small>Actions</small></span>
+  ```
+
+- [ ] **Step 5.2: Update the Footer Links header**
+
+  Find the `nav-items-header` inside the "Footer Links" card (lines 65-70). Change:
+  ```html
+  <span class="nav-col-action"></span>
+  ```
+  To:
+  ```html
+  <span class="nav-col-action text-muted"><small>Actions</small></span>
+  ```
+
+- [ ] **Step 5.3: Commit**
+
+  ```bash
+  git add admin/js/templates/navigation.html
+  git commit -m "feat: label actions column in nav editor headers"
+  ```
+
+---
+
+## Task 6: End-to-end verification
+
+- [ ] **Step 6.1: Open the Navigation editor**
+
+  Open `http://localhost:4096/admin/#/navigation`.
+
+    - Confirm each nav item row has an eye-off icon button to the left of the trash button.
+    - Confirm each footer link row has the same.
+    - Confirm rows look normal (not dimmed) when hidden is off.
+
+- [ ] **Step 6.2: Toggle a nav item hidden**
+
+    - Click the eye-off button on any nav item (e.g. "About").
+    - Row should dim and the label input should gain a strikethrough.
+    - Button should turn amber.
+
+- [ ] **Step 6.3: Save and verify public navbar**
+
+    - Click Save. Toast: "Navigation saved."
+    - Open `http://localhost:4096/` in the browser - "About" must be absent from the navbar.
+    - Open `config/navigation.json` - "About" must still be there with `"hidden": true`.
+
+- [ ] **Step 6.4: Toggle back and save**
+
+    - Return to the editor, click the eye-off button on "About" again.
+    - Row should un-dim, button returns to muted colour.
+    - Save. Verify "About" reappears on the public navbar.
+
+- [ ] **Step 6.5: Test pre-existing hidden state round-trips correctly**
+
+    - Manually add `"hidden": true` to a footer link in `config/site.json` (under `footer.links`).
+    - Reload the Navigation editor (`http://localhost:4096/admin/#/navigation`).
+    - The footer link row should render dimmed with its button in amber - confirming `footerLinks` init preserves the
+      flag.
+    - Save without changing anything - verify the link still has `"hidden": true` in `site.json`.
+
+- [ ] **Step 6.6: Test footer link hidden via UI**
+
+    - Toggle a footer link hidden via the UI. Save. Run:
+      ```bash
+      curl -s http://localhost:4096/ | grep -o '__CMS_SITE__ = [^;]*' | head -c 600
+      ```
+    - Confirm the hidden footer link is absent from the `links` array in `__CMS_SITE__`.
+
+- [ ] **Step 6.7: Test a parent with hidden children**
+
+    - Mark a child item (e.g. one under "Resources") hidden. Save.
+    - Verify the "Resources" dropdown still appears in the navbar, but the hidden child does not.
+
+- [ ] **Step 6.8: Test a hidden parent**
+
+    - Mark "Resources" (a parent with children) hidden. Save.
+    - Verify neither "Resources" nor any of its children appear in the navbar.
+
+- [ ] **Step 6.9: Final commit if any tweaks were needed**
+
+  ```bash
+  git add -p
+  git commit -m "fix: nav hidden items polish after e2e verification"
+  ```