domma-cms 1.6.60 → 1.7.0

package/docs/plans/2026-03-02-cookie-consent-plugin.md

@@ -0,0 +1,453 @@
+# Cookie Consent Plugin
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Build a CMS plugin that injects Domma's built-in cookie consent banner into every public page, with all
+wording, appearance, and category settings configurable from the admin panel.
+
+**Architecture:** Follows the exact `back-to-top` and `contact-form` plugin structure. Server exposes `GET /settings` (
+public, called by the IIFE) and `PUT /settings` (admin-auth). The public `inject-body.html` IIFE fetches settings and
+calls `Domma.components.cookieConsent(cfg)` - Domma is already loaded on all public pages before `{{bodyEndInject}}` is
+injected, so no extra dependencies are needed.
+
+**Tech Stack:** Fastify 5 (ESM), Domma SPA (admin view), `Domma.components.cookieConsent()` (public banner).
+
+---
+
+## Task 1: Create plugin.json
+
+**File:** `plugins/cookie-consent/plugin.json`
+
+```json
+{
+    "name": "cookie-consent",
+    "displayName": "Cookie Consent",
+    "version": "1.0.0",
+    "description": "Injects a configurable GDPR cookie consent banner into every public page.",
+    "author": "Darryl Waterhouse",
+    "date": "2026-03-02",
+    "icon": "shield",
+    "admin": {
+        "sidebar": [
+            { "id": "cookie-consent", "text": "Cookie Consent", "icon": "shield", "url": "#/plugins/cookie-consent", "section": "#/plugins/cookie-consent" }
+        ],
+        "routes": [
+            { "path": "/plugins/cookie-consent", "view": "plugin-cookie-consent-settings", "title": "Cookie Consent - Domma CMS" }
+        ],
+        "views": {
+            "plugin-cookie-consent-settings": {
+                "entry": "cookie-consent/admin/views/cookie-consent-settings.js",
+                "exportName": "cookieConsentSettingsView"
+            }
+        }
+    },
+    "inject": {
+        "bodyEnd": "public/inject-body.html"
+    }
+}
+```
+
+---
+
+## Task 2: Create config.js
+
+**File:** `plugins/cookie-consent/config.js`
+
+```js
+/**
+ * Cookie Consent Plugin - Default Configuration
+ */
+export default {
+    // Wording
+    message: 'We use cookies to enhance your browsing experience, serve personalised content, and analyse our traffic. By clicking "Accept All", you consent to our use of cookies.',
+    acceptAllText: 'Accept All',
+    rejectAllText: 'Reject All',
+    customizeText: 'Customize',
+    savePreferencesText: 'Save Preferences',
+
+    // Policy links (empty cookiePolicyUrl hides the cookie policy link)
+    privacyPolicyText: 'Privacy Policy',
+    privacyPolicyUrl: '/privacy-policy',
+    cookiePolicyText: 'Cookie Policy',
+    cookiePolicyUrl: '',
+
+    // Appearance
+    position: 'bottom',
+    layout: 'bar',
+    theme: 'dark',
+
+    // Categories (Necessary is always shown and always required)
+    showFunctional: true,
+    showAnalytics: true,
+    showMarketing: true,
+
+    // Consent version - increment to re-prompt users who already accepted
+    consentVersion: '1.0'
+};
+```
+
+---
+
+## Task 3: Create plugin.js (server)
+
+**File:** `plugins/cookie-consent/plugin.js`
+
+```js
+/**
+ * Cookie Consent Plugin - Server
+ *
+ * Endpoints (prefix: /api/plugins/cookie-consent):
+ *   GET  /settings  - public (called by inject-body IIFE)
+ *   PUT  /settings  - admin-auth - saves user overrides
+ */
+import { getPluginSettings, savePluginState } from '../../server/services/plugins.js';
+
+export default async function cookieConsentPlugin(fastify, options) {
+    const { authenticate, requireAdmin } = options.auth;
+
+    // GET /settings - no auth, public read
+    fastify.get('/settings', async () => {
+        return getPluginSettings('cookie-consent');
+    });
+
+    // PUT /settings - admin only
+    fastify.put('/settings', { preHandler: [authenticate, requireAdmin] }, async (request) => {
+        const body = request.body || {};
+        savePluginState('cookie-consent', { settings: body });
+        return { ok: true };
+    });
+}
+```
+
+---
+
+## Task 4: Create admin HTML template
+
+**File:** `plugins/cookie-consent/admin/templates/cookie-consent-settings.html`
+
+```html
+<div class="view-header">
+    <h1><span data-icon="shield"></span> Cookie Consent</h1>
+    <div>
+        <button id="save-settings-btn" class="btn btn-primary">
+            <span data-icon="save"></span> Save
+        </button>
+    </div>
+</div>
+
+<div class="card mb-4">
+    <div class="card-header"><h2>Banner Wording</h2></div>
+    <div class="card-body">
+        <div class="row mb-3">
+            <div class="col">
+                <label class="form-label">Message</label>
+                <textarea id="field-message" class="form-input" rows="3"></textarea>
+            </div>
+        </div>
+        <div class="row mb-3">
+            <div class="col-6">
+                <label class="form-label">Accept All button</label>
+                <input id="field-accept-all-text" type="text" class="form-input">
+            </div>
+            <div class="col-6">
+                <label class="form-label">Reject All button</label>
+                <input id="field-reject-all-text" type="text" class="form-input">
+            </div>
+        </div>
+        <div class="row mb-3">
+            <div class="col-6">
+                <label class="form-label">Customize button</label>
+                <input id="field-customize-text" type="text" class="form-input">
+            </div>
+            <div class="col-6">
+                <label class="form-label">Save Preferences button</label>
+                <input id="field-save-preferences-text" type="text" class="form-input">
+            </div>
+        </div>
+        <div class="row mb-3">
+            <div class="col-6">
+                <label class="form-label">Privacy Policy link text</label>
+                <input id="field-privacy-policy-text" type="text" class="form-input">
+            </div>
+            <div class="col-6">
+                <label class="form-label">Privacy Policy URL</label>
+                <input id="field-privacy-policy-url" type="text" class="form-input" placeholder="/privacy-policy">
+            </div>
+        </div>
+        <div class="row">
+            <div class="col-6">
+                <label class="form-label">Cookie Policy link text</label>
+                <input id="field-cookie-policy-text" type="text" class="form-input">
+            </div>
+            <div class="col-6">
+                <label class="form-label">Cookie Policy URL <span class="text-muted">(leave empty to hide)</span></label>
+                <input id="field-cookie-policy-url" type="text" class="form-input" placeholder="/cookie-policy">
+            </div>
+        </div>
+    </div>
+</div>
+
+<div class="card mb-4">
+    <div class="card-header"><h2>Appearance &amp; Categories</h2></div>
+    <div class="card-body">
+        <div class="row mb-3">
+            <div class="col-4">
+                <label class="form-label">Position</label>
+                <select id="field-position" class="form-select">
+                    <option value="bottom">Bottom</option>
+                    <option value="top">Top</option>
+                </select>
+            </div>
+            <div class="col-4">
+                <label class="form-label">Layout</label>
+                <select id="field-layout" class="form-select">
+                    <option value="bar">Bar</option>
+                    <option value="modal">Modal</option>
+                </select>
+            </div>
+            <div class="col-4">
+                <label class="form-label">Theme</label>
+                <select id="field-theme" class="form-select">
+                    <option value="dark">Dark</option>
+                    <option value="light">Light</option>
+                </select>
+            </div>
+        </div>
+        <div class="row mb-3">
+            <div class="col">
+                <label class="form-label">Cookie categories shown in Customize panel</label>
+                <span class="form-hint">Necessary cookies are always shown and always required.</span>
+                <div style="margin-top:.75rem;display:flex;flex-direction:column;gap:.5rem;">
+                    <label class="form-check-label">
+                        <input id="field-show-functional" type="checkbox"> Functional Cookies
+                    </label>
+                    <label class="form-check-label">
+                        <input id="field-show-analytics" type="checkbox"> Analytics Cookies
+                    </label>
+                    <label class="form-check-label">
+                        <input id="field-show-marketing" type="checkbox"> Marketing Cookies
+                    </label>
+                </div>
+            </div>
+        </div>
+        <div class="row">
+            <div class="col-4">
+                <label class="form-label">Consent version</label>
+                <input id="field-consent-version" type="text" class="form-input" placeholder="1.0">
+                <span class="form-hint">Increment to re-prompt users who already accepted.</span>
+            </div>
+        </div>
+    </div>
+</div>
+```
+
+---
+
+## Task 5: Create admin settings view
+
+**File:** `plugins/cookie-consent/admin/views/cookie-consent-settings.js`
+
+```js
+/**
+ * Cookie Consent Plugin - Admin Settings View
+ */
+export const cookieConsentSettingsView = {
+    templateUrl: '/plugins/cookie-consent/admin/templates/cookie-consent-settings.html',
+
+    async onMount($container) {
+        let settings = {};
+        try {
+            const res = await fetch('/api/plugins/cookie-consent/settings', {
+                headers: { 'Authorization': 'Bearer ' + (S.get('auth_token') || '') }
+            });
+            if (!res.ok) throw new Error(`HTTP ${res.status}`);
+            settings = await res.json();
+        } catch {
+            E.toast('Could not load settings.', { type: 'error' });
+        }
+
+        // Wording
+        $container.find('#field-message').val(settings.message || '');
+        $container.find('#field-accept-all-text').val(settings.acceptAllText || '');
+        $container.find('#field-reject-all-text').val(settings.rejectAllText || '');
+        $container.find('#field-customize-text').val(settings.customizeText || '');
+        $container.find('#field-save-preferences-text').val(settings.savePreferencesText || '');
+        $container.find('#field-privacy-policy-text').val(settings.privacyPolicyText || '');
+        $container.find('#field-privacy-policy-url').val(settings.privacyPolicyUrl || '');
+        $container.find('#field-cookie-policy-text').val(settings.cookiePolicyText || '');
+        $container.find('#field-cookie-policy-url').val(settings.cookiePolicyUrl || '');
+
+        // Appearance
+        $container.find('#field-position').val(settings.position || 'bottom');
+        $container.find('#field-layout').val(settings.layout || 'bar');
+        $container.find('#field-theme').val(settings.theme || 'dark');
+
+        // Categories
+        $container.find('#field-show-functional').prop('checked', settings.showFunctional !== false);
+        $container.find('#field-show-analytics').prop('checked', settings.showAnalytics !== false);
+        $container.find('#field-show-marketing').prop('checked', settings.showMarketing !== false);
+
+        // Version
+        $container.find('#field-consent-version').val(settings.consentVersion || '1.0');
+
+        $container.find('#save-settings-btn').off('click').on('click', async () => {
+            const data = {
+                message:              $container.find('#field-message').val().trim(),
+                acceptAllText:        $container.find('#field-accept-all-text').val().trim(),
+                rejectAllText:        $container.find('#field-reject-all-text').val().trim(),
+                customizeText:        $container.find('#field-customize-text').val().trim(),
+                savePreferencesText:  $container.find('#field-save-preferences-text').val().trim(),
+                privacyPolicyText:    $container.find('#field-privacy-policy-text').val().trim(),
+                privacyPolicyUrl:     $container.find('#field-privacy-policy-url').val().trim(),
+                cookiePolicyText:     $container.find('#field-cookie-policy-text').val().trim(),
+                cookiePolicyUrl:      $container.find('#field-cookie-policy-url').val().trim(),
+                position:             $container.find('#field-position').val(),
+                layout:               $container.find('#field-layout').val(),
+                theme:                $container.find('#field-theme').val(),
+                showFunctional:       $container.find('#field-show-functional').prop('checked'),
+                showAnalytics:        $container.find('#field-show-analytics').prop('checked'),
+                showMarketing:        $container.find('#field-show-marketing').prop('checked'),
+                consentVersion:       $container.find('#field-consent-version').val().trim() || '1.0'
+            };
+            try {
+                const res = await fetch('/api/plugins/cookie-consent/settings', {
+                    method:  'PUT',
+                    headers: {
+                        'Content-Type':  'application/json',
+                        'Authorization': 'Bearer ' + (S.get('auth_token') || '')
+                    },
+                    body: JSON.stringify(data)
+                });
+                if (!res.ok) throw new Error('Save failed');
+                E.toast('Settings saved.', { type: 'success' });
+            } catch {
+                E.toast('Failed to save settings.', { type: 'error' });
+            }
+        });
+
+        Domma.icons.scan();
+    }
+};
+```
+
+---
+
+## Task 6: Create public inject-body.html
+
+**File:** `plugins/cookie-consent/public/inject-body.html`
+
+`Domma.components.cookieConsent()` is available because `domma.min.js` is loaded and `Domma.init()` runs before
+`{{bodyEndInject}}` in `server/templates/page.html`.
+
+The IIFE maps the flat config to the Domma component's `categories` object - only including categories that are enabled
+in settings. Necessary is always included.
+
+```html
+<script>
+(function () {
+    'use strict';
+
+    if (!window.Domma || !window.Domma.components || !window.Domma.components.cookieConsent) return;
+
+    fetch('/api/plugins/cookie-consent/settings')
+        .then(function (r) { return r.json(); })
+        .then(function (s) {
+            var categories = {
+                necessary: {
+                    label: 'Necessary Cookies',
+                    description: 'These cookies are essential for the website to function properly.',
+                    required: true
+                }
+            };
+
+            if (s.showFunctional !== false) {
+                categories.functional = {
+                    label: 'Functional Cookies',
+                    description: 'These cookies enable personalised features and functionality.',
+                    required: false
+                };
+            }
+
+            if (s.showAnalytics !== false) {
+                categories.analytics = {
+                    label: 'Analytics Cookies',
+                    description: 'These cookies help us understand how visitors interact with our website.',
+                    required: false
+                };
+            }
+
+            if (s.showMarketing !== false) {
+                categories.marketing = {
+                    label: 'Marketing Cookies',
+                    description: 'These cookies are used to deliver relevant ads and marketing campaigns.',
+                    required: false
+                };
+            }
+
+            var cfg = {
+                message:              s.message,
+                acceptAllText:        s.acceptAllText,
+                rejectAllText:        s.rejectAllText,
+                customizeText:        s.customizeText,
+                savePreferencesText:  s.savePreferencesText,
+                privacyPolicyText:    s.privacyPolicyText,
+                privacyPolicyUrl:     s.privacyPolicyUrl || null,
+                cookiePolicyText:     s.cookiePolicyText,
+                cookiePolicyUrl:      s.cookiePolicyUrl || null,
+                position:             s.position || 'bottom',
+                layout:               s.layout || 'bar',
+                theme:                s.theme || 'dark',
+                categories:           categories,
+                consentVersion:       s.consentVersion || '1.0',
+                autoShow:             true,
+                animation:            true
+            };
+
+            Domma.components.cookieConsent(cfg);
+        })
+        .catch(function () {
+            // Settings fetch failed - don't show banner
+        });
+})();
+</script>
+```
+
+---
+
+## Task 7: Enable plugin in config/plugins.json
+
+**Modify:** `config/plugins.json`
+
+Add the `cookie-consent` entry:
+
+```json
+{
+  "example-analytics": { "enabled": true, "settings": {} },
+  "contact-form":      { "enabled": true, "settings": {} },
+  "back-to-top":       { "enabled": true, "settings": {} },
+  "cookie-consent":    { "enabled": true, "settings": {} }
+}
+```
+
+---
+
+## Verification
+
+Restart the server (`node server/server.js`) and check:
+
+1. **Server log** - `[plugins] Loaded 4 plugins: back-to-top, contact-form, cookie-consent, example-analytics`
+
+2. **Settings endpoint** - `curl http://localhost:4096/api/plugins/cookie-consent/settings` returns the full defaults
+   JSON.
+
+3. **Public injection** - `curl http://localhost:4096/ | grep cookie-consent` shows the IIFE script in the page HTML.
+
+4. **Banner appears** - visit the public site in a browser (clear localStorage first). The cookie consent bar should
+   appear at the bottom of the page. Clicking "Customize" should open the category panel with Necessary, Functional,
+   Analytics, and Marketing options.
+
+5. **Admin settings** - navigate to `#/plugins/cookie-consent` in the admin. The settings form should load with all
+   defaults populated. Change the message, save, reload the public site - the new message should appear.
+
+6. **PUT protected** - `curl -X PUT http://localhost:4096/api/plugins/cookie-consent/settings` without a token returns
+   `401`.

package/docs/plans/2026-03-02-tooltip-sweep-and-back-to-top-plugin-design.md

@@ -0,0 +1,126 @@
+# Tooltip Sweep & Back-to-Top Plugin
+
+**Date:** 2026-03-02
+
+---
+
+## 1. Tooltip Sweep
+
+### Problem
+
+Icon-only interactive buttons across the admin have no accessible labels or hover hints. The sidebar and topbar already
+have tooltips; the rest of the UI does not.
+
+### Scope
+
+Add `data-tooltip` to icon-only buttons in:
+
+- **Pages table** - Edit, Delete row actions (rendered by `pages.js` via `T.create`)
+- **User editor** - Save/Cancel header buttons (icon + text, but Save has an icon)
+- **Navigation view** - Add/Delete/move row action buttons
+- **Page editor header** - Save/Cancel buttons already have text; no change needed
+- **Plugin cards** - Toggle enable/disable buttons (if icon-only)
+
+Out of scope: buttons that already have visible text labels.
+
+### Implementation
+
+Each view that renders icon-only actions via `T.create` columns or dynamic HTML passes `data-tooltip="..."` on the
+element, then calls `E.tooltip('[data-tooltip]', { placement: 'top' })` at the end of the render function - matching the
+pattern already used in `media.js`.
+
+---
+
+## 2. Back-to-Top Plugin
+
+### Overview
+
+A lightweight CMS plugin that injects a scroll-to-top button into every public page. Configurable from the admin panel.
+Follows the established plugin pattern (contact-form as reference).
+
+### File Structure
+
+```
+plugins/back-to-top/
+├── plugin.json          - metadata, admin routes, inject references
+├── plugin.js            - Fastify plugin: GET/PUT /settings
+├── config.js            - default settings
+├── admin/
+│   └── views/
+│       └── back-to-top-settings.js   - admin SPA view
+│   └── templates/
+│       └── back-to-top-settings.html - admin template
+└── public/
+    └── inject-body.html - IIFE injected at </body> on every public page
+```
+
+### Config Defaults (`config.js`)
+
+| Key               | Default          | Description                                   |
+|-------------------|------------------|-----------------------------------------------|
+| `scrollThreshold` | `300`            | px scrolled before button appears             |
+| `position`        | `'bottom-right'` | `'bottom-right'` or `'bottom-left'`           |
+| `label`           | `''`             | Optional text next to icon; empty = icon only |
+| `smooth`          | `true`           | Smooth scroll vs instant                      |
+| `offset`          | `32`             | px from bottom/side edge                      |
+
+### Server (`plugin.js`)
+
+Two endpoints under `/api/plugins/back-to-top/`:
+
+- `GET /settings` - admin-auth - returns merged settings
+- `PUT /settings` - admin-auth - saves user overrides via `savePluginState`
+
+No public endpoints needed.
+
+### Public Injection (`inject-body.html`)
+
+Self-contained IIFE:
+
+1. Fetches `/api/plugins/back-to-top/settings` (unauthenticated - settings are public read)
+2. Creates a `<button id="back-to-top-btn">` with inline styles driven by config
+3. Uses `IntersectionObserver` on a sentinel element (or `scroll` event) to show/hide
+4. Clicking scrolls to top using `window.scrollTo` (smooth or instant per config)
+5. Uses a Domma `arrow-up` icon (`data-icon` pattern won't work outside admin - renders a plain SVG inline)
+
+The button is self-styled (no dependency on site.css) so it works regardless of theme.
+
+### Admin Panel (`back-to-top-settings.js`)
+
+Simple settings form matching the contact-form settings pattern:
+
+- Number input: Scroll threshold (px)
+- Select: Position (Bottom right / Bottom left)
+- Text input: Button label (optional)
+- Checkbox: Smooth scroll
+- Number input: Edge offset (px)
+- Save button with success toast
+
+### plugin.json Admin Section
+
+```json
+"admin": {
+    "sidebar": [{ "id": "back-to-top", "text": "Back to Top", "icon": "arrow-up", "url": "#/plugins/back-to-top" }],
+    "routes": [{ "path": "/plugins/back-to-top", "view": "plugin-back-to-top-settings", "title": "Back to Top - Domma CMS" }],
+    "views": {
+        "plugin-back-to-top-settings": {
+            "entry": "back-to-top/admin/views/back-to-top-settings.js",
+            "exportName": "backToTopSettingsView"
+        }
+    }
+}
+```
+
+### Note on Settings Endpoint Auth
+
+The `GET /settings` endpoint is called from the public site (unauthenticated). It returns only non-sensitive display
+config (threshold, position, label, smooth, offset) - no credentials. This is intentional and safe.
+
+---
+
+## Decisions
+
+- Plugin follows contact-form structure exactly (no new patterns)
+- Public button is self-contained (no Domma dependency on public side)
+- Settings fetched client-side (no server-side variable substitution needed)
+- Tooltip sweep is targeted (icon-only buttons only, not all interactive elements)