domma-cms 1.6.60 → 1.7.1

package/docs/superpowers/specs/plans/2026-04-06-insert-builders.md

@@ -0,0 +1,1049 @@
+# Insert Builders - Tabs, Hero, Banner - Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:
+> executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Upgrade the Page Editor Insert toolbar with a richer Tabs dialog, a new Hero dialog, and a brand-new
+`[banner]` shortcode end-to-end (server render + CSS + dismiss + toolbar item + insert dialog).
+
+**Architecture:** A tiny shared utility (`shortcode-modal.js`) provides UI helpers imported by `page-editor.js`. The
+three insert handlers (`onTabs`, `onHero`, `onBanner`) live inline in `page-editor.js` using `E.modal()` light DOM
+projection. Server-side, `processBannerBlocks()` slots into the existing `parseMarkdown` pipeline and
+`processTabsBlocks()` is extended for new attributes.
+
+**Tech Stack:** Fastify 5 ESM, Domma SPA (admin), `E.modal()` light DOM, `markdown.js` shortcode pipeline,
+`public/css/site.css` (Domma CSS custom properties), `public/js/site.js` (Domma event delegation).
+
+---
+
+## File Map
+
+| File                               | Action     | Responsibility                                                                                                                                                                  |
+|------------------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `admin/js/lib/shortcode-modal.js`  | **Create** | Shared UI helpers: `makeField`, `makeSelect`, `makeTextInput`, `makeCheckbox`, `makeLivePreview`                                                                                |
+| `admin/js/views/page-editor.js`    | **Modify** | Add import; replace `onTabs`; add `onHero`; add `onBanner`                                                                                                                      |
+| `admin/js/lib/markdown-toolbar.js` | **Modify** | Register `banner-insert` icon; add `banner` insert item; add dispatch; add `onBanner` to handler chain                                                                          |
+| `server/services/markdown.js`      | **Modify** | Update `processTabsBlocks` (bordered/fade/icon); update `processHeroBlocks` (color/min-height); add `processBannerBlocks`; wire into pipeline; add `'banner'` to reserved names |
+| `public/css/site.css`              | **Modify** | Add `.dm-banner` base + 5 type variants                                                                                                                                         |
+| `public/js/site.js`                | **Modify** | Add `.dm-banner__dismiss` click handler                                                                                                                                         |
+
+---
+
+## Task 1: `shortcode-modal.js` - Shared UI utility
+
+**File:** Create `admin/js/lib/shortcode-modal.js`
+
+This module provides the styled form primitives used across all three insert dialogs. Without it, each handler
+copy-pastes the same CSS strings and DOM-building helpers.
+
+- [ ] **Step 1: Create the file**
+
+```js
+/**
+ * shortcode-modal.js
+ * Shared UI helpers for shortcode insert dialogs in the page editor.
+ *
+ * Exports:
+ *   makeField(label, control)         - labelled field wrapper
+ *   makeSelect(items)                 - styled <select>
+ *   makeTextInput(placeholder, value) - styled <input type="text">
+ *   makeCheckbox(label)               - styled checkbox row
+ *   makeLivePreview()                 - { el, update(str) } live shortcode preview box
+ */
+
+const LABEL_STYLE = 'display:block;font-size:.7rem;font-weight:600;color:var(--dm-text-muted,#aaa);text-transform:uppercase;letter-spacing:.05em;margin-bottom:.25rem;';
+const INPUT_STYLE = 'width:100%;padding:.4rem .6rem;background:var(--dm-input-bg,#1a1a1a);border:1px solid var(--dm-border,#333);border-radius:4px;color:var(--dm-text,#eee);font-size:.9em;box-sizing:border-box;';
+
+export function makeField(label, control) {
+    const wrap = document.createElement('div');
+    const lbl = document.createElement('label');
+    lbl.style.cssText = LABEL_STYLE;
+    lbl.textContent = label;
+    wrap.appendChild(lbl);
+    wrap.appendChild(control);
+    return wrap;
+}
+
+export function makeSelect(items) {
+    const sel = document.createElement('select');
+    sel.style.cssText = INPUT_STYLE;
+    items.forEach(([val, text]) => {
+        const opt = document.createElement('option');
+        opt.value = val;
+        opt.textContent = text;
+        sel.appendChild(opt);
+    });
+    return sel;
+}
+
+export function makeTextInput(placeholder = '', value = '') {
+    const inp = document.createElement('input');
+    inp.type = 'text';
+    inp.placeholder = placeholder;
+    inp.value = value;
+    inp.style.cssText = INPUT_STYLE;
+    return inp;
+}
+
+export function makeCheckbox(label) {
+    const wrap = document.createElement('label');
+    wrap.style.cssText = 'display:flex;align-items:center;gap:.5rem;cursor:pointer;';
+    const cb = document.createElement('input');
+    cb.type = 'checkbox';
+    const span = document.createElement('span');
+    span.style.cssText = 'font-size:.85em;color:var(--dm-text,#eee);';
+    span.textContent = label;
+    wrap.appendChild(cb);
+    wrap.appendChild(span);
+    return wrap;
+}
+
+export function makeLivePreview() {
+    const el = document.createElement('pre');
+    el.style.cssText = 'background:var(--dm-surface-subtle,#111);border:1px solid var(--dm-border,#333);border-radius:4px;padding:.5rem .75rem;font-size:.75em;color:var(--dm-text-muted,#aaa);white-space:pre-wrap;word-break:break-all;margin:0;max-height:120px;overflow:auto;';
+    el.textContent = '';
+    return {
+        el,
+        update(str) { el.textContent = str; },
+    };
+}
+```
+
+- [ ] **Step 2: Verify file exists**
+
+```bash
+ls /home/darryl/src/js/domma-cms/admin/js/lib/shortcode-modal.js
+```
+
+Expected: file path printed, no error.
+
+---
+
+## Task 2: `onTabs` - Upgraded insert dialog
+
+**File:** Modify `admin/js/views/page-editor.js`
+
+The existing `onTabs` handler builds a simple modal. Replace it with a richer version that uses `shortcode-modal.js`
+helpers and adds: bordered style, fade animation, multiple-open toggle, per-tab icon inputs, live preview.
+
+- [ ] **Step 1: Add the `shortcode-modal.js` import**
+
+Find the imports block at the top of `page-editor.js`. It currently reads:
+
+```js
+import{api as K}from"../api.js";import{CardBuilder}from"../lib/card-builder.js?v=4";import{attachEditorKeybindings as We,createToolbar as $e,insertAtCursor as ke}from"../lib/markdown-toolbar.js?v=9";import{populateThemeSelect as Ye}from"../lib/themes.js";import{createFoldingManager as je}from"../lib/editor-folding.js";
+```
+
+Add the import for `shortcode-modal.js` as a **new line immediately after** the existing single-line import block (do
+not insert into the middle of it - the existing block is a minified single line and must stay intact):
+
+```js
+import { makeField, makeSelect, makeTextInput, makeCheckbox, makeLivePreview } from '../lib/shortcode-modal.js';
+```
+
+Note: `page-editor.js` uses `?v=N` cache-busting suffixes on some imports during development. Add `?v=1` to
+`shortcode-modal.js` if hot-reloading issues occur.
+
+- [ ] **Step 2: Locate the existing `onTabs` handler**
+
+Search for `onTabs(` in `page-editor.js`. The handler starts with:
+
+```js
+V.onTabs(e=>{const l=document.createElement("div");l.style.cssText="padding:.25rem 0 .5rem;
+```
+
+And ends at the next `}),V.onGrid(` call.
+
+- [ ] **Step 3: Replace the `onTabs` handler**
+
+Replace the full existing `onTabs(...)` call (from `V.onTabs(` to the matching `}),` before `V.onGrid(`) with:
+
+```js
+V.onTabs(ta => {
+    const body = document.createElement('div');
+    body.style.cssText = 'padding:.25rem 0 .5rem;display:flex;flex-direction:column;gap:.75rem;';
+
+    // Style
+    const styleSelect = makeSelect([
+        ['', 'Default (underline)'],
+        ['pills', 'Pills'],
+        ['bordered', 'Bordered'],
+    ]);
+    body.appendChild(makeField('Style', styleSelect));
+
+    // Alignment
+    const alignSelect = makeSelect([
+        ['', 'Left'],
+        ['center', 'Centre'],
+        ['right', 'Right'],
+    ]);
+    body.appendChild(makeField('Alignment', alignSelect));
+
+    // Animation
+    const animSelect = makeSelect([['', 'None'], ['fade', 'Fade']]);
+    body.appendChild(makeField('Animation', animSelect));
+
+    // Multiple open
+    const multipleWrap = makeCheckbox('Allow multiple panels open at once');
+    const multipleCb = multipleWrap.querySelector('input');
+    body.appendChild(multipleWrap);
+
+    // Tab list
+    const tabListLabel = document.createElement('div');
+    tabListLabel.style.cssText = 'display:block;font-size:.7rem;font-weight:600;color:var(--dm-text-muted,#aaa);text-transform:uppercase;letter-spacing:.05em;';
+    tabListLabel.textContent = 'Tabs';
+    body.appendChild(tabListLabel);
+
+    const tabRows = document.createElement('div');
+    tabRows.style.cssText = 'display:flex;flex-direction:column;gap:.4rem;';
+    const tabs = [];
+
+    function syncRemoveButtons() {
+        tabs.forEach(t => {
+            t.removeBtn.disabled = tabs.length <= 2;
+            t.removeBtn.style.opacity = tabs.length <= 2 ? '0.3' : '1';
+        });
+    }
+
+    function buildShortcode() {
+        const style = styleSelect.value;
+        const align = alignSelect.value;
+        const anim = animSelect.value;
+        const multi = multipleCb.checked;
+        const parts = [];
+        if (style) parts.push(`style="${style}"`);
+        if (align) parts.push(`align="${align}"`);
+        if (anim) parts.push(anim);
+        if (multi) parts.push('multiple="true"');
+        const attrStr = parts.length ? ' ' + parts.join(' ') : '';
+        let out = `[tabs${attrStr}]\n`;
+        tabs.forEach((t, i) => {
+            const title = t.titleInput.value.trim() || `Tab ${i + 1}`;
+            const icon = t.iconInput.value.trim();
+            const tabAttr = icon ? ` title="${title}" icon="${icon}"` : ` title="${title}"`;
+            out += `[tab${tabAttr}]Tab content here.[/tab]\n`;
+        });
+        out += '[/tabs]';
+        return out;
+    }
+
+    function addTab(title = '') {
+        if (tabs.length >= 10) return;
+        const row = document.createElement('div');
+        row.style.cssText = 'display:flex;gap:.4rem;align-items:center;';
+
+        const titleInput = makeTextInput('Tab title', title);
+        titleInput.style.cssText += 'flex:1;';
+
+        const iconInput = makeTextInput('icon (optional)');
+        iconInput.style.cssText += 'flex:.6;';
+
+        const removeBtn = document.createElement('button');
+        removeBtn.type = 'button';
+        removeBtn.textContent = '×';
+        removeBtn.style.cssText = 'padding:.3rem .5rem;background:transparent;border:1px solid var(--dm-border,#333);border-radius:4px;color:var(--dm-text-muted,#aaa);cursor:pointer;font-size:.85em;flex-shrink:0;';
+
+        const entry = { row, titleInput, iconInput, removeBtn };
+        tabs.push(entry);
+        row.appendChild(titleInput);
+        row.appendChild(iconInput);
+        row.appendChild(removeBtn);
+        tabRows.appendChild(row);
+
+        removeBtn.addEventListener('click', () => {
+            if (tabs.length <= 2) return;
+            const idx = tabs.indexOf(entry);
+            tabs.splice(idx, 1);
+            tabRows.removeChild(row);
+            syncRemoveButtons();
+            preview.update(buildShortcode());
+        });
+
+        [titleInput, iconInput].forEach(el => el.addEventListener('input', () => preview.update(buildShortcode())));
+        syncRemoveButtons();
+    }
+
+    addTab('Overview');
+    addTab('Details');
+    body.appendChild(tabRows);
+
+    const addBtn = document.createElement('button');
+    addBtn.type = 'button';
+    addBtn.textContent = '+ Add Tab';
+    addBtn.style.cssText = 'padding:.35rem .75rem;background:transparent;border:1px dashed var(--dm-border,#555);border-radius:4px;color:var(--dm-text-muted,#aaa);cursor:pointer;font-size:.85em;align-self:flex-start;';
+    addBtn.addEventListener('click', () => { addTab(''); tabs[tabs.length - 1].titleInput.focus(); preview.update(buildShortcode()); });
+    body.appendChild(addBtn);
+
+    // Live preview
+    const preview = makeLivePreview();
+    preview.update(buildShortcode());
+    body.appendChild(makeField('Shortcode preview', preview.el));
+
+    // Wire all top-level fields to preview
+    [styleSelect, alignSelect, animSelect].forEach(el => el.addEventListener('change', () => preview.update(buildShortcode())));
+    multipleCb.addEventListener('change', () => preview.update(buildShortcode()));
+
+    // Insert button
+    const insertBtn = document.createElement('button');
+    insertBtn.type = 'button';
+    insertBtn.className = 'btn btn-primary';
+    insertBtn.textContent = 'Insert Tabs';
+    body.appendChild(insertBtn);
+
+    const modal = E.modal({ title: 'Insert Tabs', size: 'sm' });
+    modal.element.appendChild(body);
+    modal.open();
+    requestAnimationFrame(() => tabs[0].titleInput.focus());
+
+    insertBtn.addEventListener('click', () => {
+        modal.close();
+        ke(ta, buildShortcode());
+        ta.dispatchEvent(new Event('input', { bubbles: true }));
+        ta.focus();
+    });
+}),
+```
+
+- [ ] **Step 4: Smoke test in browser**
+
+1. Open the admin, navigate to any page editor
+2. Click Insert → Tabs
+3. Verify modal opens with Style/Alignment/Animation selects, Multiple checkbox, two tab rows each with title + icon
+   fields
+4. Change style to "Pills" → verify live preview updates to `[tabs style="pills"]`
+5. Add a tab → verify third row appears
+6. Remove a tab → verify it disappears (remove button disabled at 2 tabs)
+7. Click Insert Tabs → verify shortcode inserted at cursor in editor
+
+---
+
+## Task 3: `processTabsBlocks` - Server-side bordered/fade/icon support
+
+**File:** Modify `server/services/markdown.js`
+
+The insert dialog can now generate `style="bordered"`, `fade`, and per-tab `icon` attributes. Without server-side
+support, they silently render as unstyled tabs with no icons.
+
+- [ ] **Step 1: Locate `processTabsBlocks`**
+
+Find the function at approximately line 1466. It currently reads:
+
+```js
+const pillsClass = attrs.style === 'pills' ? ' tabs-pills' : '';
+const centeredClass = attrs.align === 'center' ? ' tabs-centered' : '';
+```
+
+- [ ] **Step 2: Add bordered and fade class support**
+
+After the existing class derivations, add:
+
+```js
+const borderedClass = attrs.style === 'bordered' ? ' tabs-bordered' : '';
+const fadeClass = 'fade' in attrs ? ' tabs-fade' : '';
+const rightClass = attrs.align === 'right' ? ' tabs-right' : '';
+```
+
+Update the wrapper div return value to include all new classes:
+
+```js
+`<div class="tabs${pillsClass}${borderedClass}${centeredClass}${rightClass}${fadeClass}"${idAttr}>\n` +
+```
+
+Note: `pills` and `bordered` are mutually exclusive (both use `style=`), so at most one will be non-empty.
+
+- [ ] **Step 3: Add per-tab icon support**
+
+Inside the `body.replace(/\[tab...` callback, the tab attrs are already parsed via `parseShortcodeAttrs(tabAttr)`. Find
+the line:
+
+```js
+const title = tabAttrs.title || `Tab ${tabIdx}`;
+```
+
+Add icon extraction immediately after:
+
+```js
+const icon = tabAttrs.icon || '';
+```
+
+Then update the `navItems` map to render the icon span before the title text:
+
+```js
+const navItems = items.map(t =>
+    `<button class="tab-item${t.first ? ' active' : ''}">${t.icon ? `<span data-icon="${escapeAttr(t.icon)}"></span>` : ''}${escapeAttr(t.title)}</button>`
+).join('\n    ');
+```
+
+Update the `items.push(...)` call to include `icon`:
+
+```js
+items.push({ title, icon, paneId, bodyHtml, first: tabIdx === 1 });
+```
+
+- [ ] **Step 4: Verify via curl**
+
+Create a test page or use the existing preview API:
+
+```bash
+curl -s -X POST http://localhost:4096/api/pages/preview \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -d '{"content":"[tabs style=\"bordered\" fade]\n[tab title=\"One\" icon=\"star\"]Hello[/tab]\n[tab title=\"Two\"]World[/tab]\n[/tabs]"}' \
+  | grep -o 'tabs[^"]*"'
+```
+
+Expected: response HTML contains `class="tabs tabs-bordered tabs-fade"` and `data-icon="star"`.
+
+---
+
+## Task 4: `onHero` - New insert dialog
+
+**File:** Modify `admin/js/views/page-editor.js`
+
+The toolbar already dispatches `handlers.hero(ta)` but no handler is registered. Add `V.onHero(...)` alongside the other
+handler registrations (near `V.onCard`, `V.onTabs`).
+
+- [ ] **Step 1: Locate where to add the handler**
+
+Find the line `V.onCard(e=>{CardBuilder.open(...)})` - this is near the end of the `onMount` function. Add
+`V.onHero(...)` immediately before or after `V.onCard(...)`.
+
+- [ ] **Step 2: Add the `onHero` handler**
+
+```js
+V.onHero(ta => {
+    const body = document.createElement('div');
+    body.style.cssText = 'padding:.25rem 0 .5rem;display:flex;flex-direction:column;gap:.75rem;';
+
+    const titleInput = makeTextInput('Hero title (required)');
+    body.appendChild(makeField('Title', titleInput));
+
+    const taglineInput = makeTextInput('Tagline / subtitle (optional)');
+    body.appendChild(makeField('Tagline', taglineInput));
+
+    const sizeSelect = makeSelect([
+        ['', 'Default'],
+        ['sm', 'Small'],
+        ['lg', 'Large'],
+        ['full', 'Full screen'],
+    ]);
+    body.appendChild(makeField('Size', sizeSelect));
+
+    const alignSelect = makeSelect([
+        ['center', 'Centre'],
+        ['left', 'Left'],
+        ['right', 'Right'],
+    ]);
+    body.appendChild(makeField('Alignment', alignSelect));
+
+    // Background type radio group
+    const bgLabel = document.createElement('div');
+    bgLabel.style.cssText = 'display:block;font-size:.7rem;font-weight:600;color:var(--dm-text-muted,#aaa);text-transform:uppercase;letter-spacing:.05em;';
+    bgLabel.textContent = 'Background';
+    body.appendChild(bgLabel);
+
+    const bgGroup = document.createElement('div');
+    bgGroup.style.cssText = 'display:flex;gap:.75rem;';
+    const bgOptions = ['None', 'Colour', 'Image'];
+    const bgRadios = bgOptions.map(opt => {
+        const lbl = document.createElement('label');
+        lbl.style.cssText = 'display:flex;align-items:center;gap:.3rem;font-size:.85em;cursor:pointer;color:var(--dm-text,#eee);';
+        const rb = document.createElement('input');
+        rb.type = 'radio';
+        rb.name = 'hero-bg';
+        rb.value = opt.toLowerCase();
+        if (opt === 'None') rb.checked = true;
+        lbl.appendChild(rb);
+        lbl.appendChild(document.createTextNode(opt));
+        bgGroup.appendChild(lbl);
+        return rb;
+    });
+    body.appendChild(bgGroup);
+
+    // Colour field (hidden by default)
+    const colorInput = makeTextInput('#3b82f6 or any CSS colour');
+    const colorField = makeField('Background Colour', colorInput);
+    colorField.style.display = 'none';
+    body.appendChild(colorField);
+
+    // Image fields (hidden by default)
+    const imageInput = makeTextInput('/media/hero.jpg');
+    const imageField = makeField('Image Path', imageInput);
+    imageField.style.display = 'none';
+
+    const overlaySelect = makeSelect([
+        ['', 'None'],
+        ['dark', 'Dark'],
+        ['light', 'Light'],
+        ['darker', 'Darker'],
+        ['gradient', 'Gradient'],
+    ]);
+    const overlayField = makeField('Overlay', overlaySelect);
+    overlayField.style.display = 'none';
+    body.appendChild(imageField);
+    body.appendChild(overlayField);
+
+    const minHeightInput = makeTextInput('e.g. 400px (optional)');
+    body.appendChild(makeField('Min Height', minHeightInput));
+
+    // Show/hide conditional fields
+    function syncBgFields() {
+        const val = bgRadios.find(r => r.checked)?.value || 'none';
+        colorField.style.display = val === 'colour' ? '' : 'none';
+        imageField.style.display = val === 'image' ? '' : 'none';
+        overlayField.style.display = val === 'image' ? '' : 'none';
+        preview.update(buildShortcode());
+    }
+    bgRadios.forEach(r => r.addEventListener('change', syncBgFields));
+
+    function buildShortcode() {
+        const parts = [];
+        const title = titleInput.value.trim();
+        if (title) parts.push(`title="${title}"`);
+        const tagline = taglineInput.value.trim();
+        if (tagline) parts.push(`tagline="${tagline}"`);
+        const size = sizeSelect.value;
+        if (size) parts.push(`size="${size}"`);
+        const align = alignSelect.value;
+        if (align && align !== 'center') parts.push(`align="${align}"`);
+
+        const bgType = bgRadios.find(r => r.checked)?.value || 'none';
+        if (bgType === 'colour') {
+            const col = colorInput.value.trim();
+            if (col) parts.push(`color="${col}"`);
+        } else if (bgType === 'image') {
+            const img = imageInput.value.trim();
+            if (img) parts.push(`image="${img}"`);
+            const ov = overlaySelect.value;
+            if (ov) parts.push(`overlay="${ov}"`);
+        }
+        const minH = minHeightInput.value.trim();
+        if (minH) parts.push(`min-height="${minH}"`);
+
+        const attrStr = parts.length ? ' ' + parts.join(' ') : '';
+        return `[hero${attrStr}]\nContent here.\n[/hero]`;
+    }
+
+    // Live preview
+    const preview = makeLivePreview();
+    preview.update(buildShortcode());
+    body.appendChild(makeField('Shortcode preview', preview.el));
+
+    const allInputs = [titleInput, taglineInput, colorInput, imageInput, minHeightInput];
+    allInputs.forEach(el => el.addEventListener('input', () => preview.update(buildShortcode())));
+    [sizeSelect, alignSelect, overlaySelect].forEach(el => el.addEventListener('change', () => preview.update(buildShortcode())));
+
+    const insertBtn = document.createElement('button');
+    insertBtn.type = 'button';
+    insertBtn.className = 'btn btn-primary';
+    insertBtn.textContent = 'Insert Hero';
+    body.appendChild(insertBtn);
+
+    const modal = E.modal({ title: 'Insert Hero', size: 'sm' });
+    modal.element.appendChild(body);
+    modal.open();
+    requestAnimationFrame(() => titleInput.focus());
+
+    insertBtn.addEventListener('click', () => {
+        modal.close();
+        ke(ta, buildShortcode());
+        ta.dispatchEvent(new Event('input', { bubbles: true }));
+        ta.focus();
+    });
+}),
+```
+
+- [ ] **Step 3: Smoke test**
+
+1. Click Insert → Hero
+2. Verify modal opens with all fields
+3. Select "Colour" → colour input appears; select "Image" → image + overlay appear; select "None" → both hidden
+4. Fill in title + image path → live preview updates
+5. Click Insert Hero → shortcode appears in editor
+
+---
+
+## Task 5: `processHeroBlocks` - Add `color` and `min-height` support
+
+**File:** Modify `server/services/markdown.js`
+
+The insert dialog can generate `color="..."` (custom background colour) and `min-height="..."`. `processHeroBlocks` at
+line ~2265 must handle these.
+
+- [ ] **Step 1: Locate attribute handling in `processHeroBlocks`**
+
+Find the block inside the regex callback where `attrs` is used to build inline styles or class names. The function
+currently handles `image`, `overlay`, `align`, `variant`, `size`.
+
+- [ ] **Step 2: Add `color` attribute**
+
+Find where the `style` attribute string is built for the hero wrapper div (where `image` is applied as
+`background-image`). Add handling for `color`:
+
+```js
+const colorStyle = attrs.color ? `background:${attrs.color};` : '';
+```
+
+Append `colorStyle` to the element's inline style (alongside any existing background-image style). Ensure `color` and
+`image` are mutually exclusive - if both are provided, `image` wins (it's the more specific declaration).
+
+- [ ] **Step 3: Add `min-height` attribute**
+
+```js
+const minHeightStyle = attrs['min-height'] ? `min-height:${attrs['min-height']};` : '';
+```
+
+Include `minHeightStyle` in the wrapper element's inline `style` attribute.
+
+- [ ] **Step 4: Verify via curl**
+
+```bash
+curl -s -X POST http://localhost:4096/api/pages/preview \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -d '{"content":"[hero title=\"Test\" color=\"#1e293b\" min-height=\"300px\"]\nHello\n[/hero]"}' \
+  | grep -o 'style="[^"]*"' | head -3
+```
+
+Expected: inline style contains `background:#1e293b` and `min-height:300px`.
+
+---
+
+## Task 6: `processBannerBlocks` - New server-side shortcode
+
+**File:** Modify `server/services/markdown.js`
+
+- [ ] **Step 1: Add `'banner'` to the reserved shortcode names array**
+
+Find the array near the top of `markdown.js` that lists reserved shortcode tag names (around line 19, containing
+`'block'`, `'collection'`, `'tabs'`, etc.). Add `'banner'` to the list:
+
+```js
+'banner',
+```
+
+- [ ] **Step 2: Add the `processBannerBlocks` function**
+
+Add this function after `processTextBlocks` (around line 1803) and before the next function:
+
+```js
+/**
+ * Pre-process [banner] shortcodes before running through marked.
+ *
+ * Syntax:
+ *   [banner type="info" title="Note" icon="info" dismissible class="my-class"]
+ *   Body content with **Markdown** support.
+ *   [/banner]
+ *
+ * Supported attributes:
+ *   type        - "info" (default), "success", "warning", "danger", "neutral"
+ *   title       - Optional bold heading
+ *   icon        - Optional Domma icon name
+ *   dismissible - Boolean flag - renders a dismiss (×) button
+ *   class       - Extra CSS classes on the wrapper
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processBannerBlocks(markdown) {
+    const { scrubbed, restore } = scrubCodeRegions(markdown);
+    const processed = scrubbed.replace(
+        /\[banner([^\]]*)\]([\s\S]*?)\[\/banner\]/gi,
+        (_, attrStr, body) => {
+            const attrs = parseShortcodeAttrs(attrStr);
+            const type = ['info', 'success', 'warning', 'danger', 'neutral'].includes(attrs.type)
+                ? attrs.type : 'info';
+            const extraClass = attrs.class ? ` ${attrs.class}` : '';
+            const dismissible = 'dismissible' in attrs;
+
+            const iconHtml = attrs.icon
+                ? `<span class="dm-banner__icon" data-icon="${escapeAttr(attrs.icon)}"></span>`
+                : '';
+            const titleHtml = attrs.title
+                ? `<strong class="dm-banner__title">${escapeAttr(attrs.title)}</strong>`
+                : '';
+            // Safe to call marked.parse() here - the resulting <div class="dm-banner ..."> block
+            // passes through the final outer marked.parse() call unchanged, because marked treats
+            // block-level HTML elements as HTML blocks and passes them through verbatim (CommonMark spec).
+            // This is the same pattern used by processCardBlocks, processTabsBlocks, etc.
+            const bodyHtml = marked.parse(body.trim());
+            const dismissHtml = dismissible
+                ? `<button class="dm-banner__dismiss" aria-label="Dismiss">×</button>`
+                : '';
+
+            return (
+                `<div class="dm-banner dm-banner--${type}${extraClass}">\n` +
+                (iconHtml ? `  ${iconHtml}\n` : '') +
+                `  <div class="dm-banner__body">\n` +
+                (titleHtml ? `    ${titleHtml}\n` : '') +
+                `    ${bodyHtml.trim()}\n` +
+                `  </div>\n` +
+                (dismissHtml ? `  ${dismissHtml}\n` : '') +
+                `</div>\n`
+            );
+        }
+    );
+    return restore(processed);
+}
+```
+
+- [ ] **Step 3: Wire into the `parseMarkdown` pipeline**
+
+Find these two consecutive lines in `parseMarkdown` (near line 2484):
+
+```js
+const withCard = processCardBlocks(withGrid);
+const withSlideover = processSlideoverBlocks(withCard);
+```
+
+Insert `processBannerBlocks` between them:
+
+```js
+const withCard = processCardBlocks(withGrid);
+const withBanner = processBannerBlocks(withCard);
+const withSlideover = processSlideoverBlocks(withBanner);
+```
+
+Also update the pipeline comment at the top of `parseMarkdown` to include `banner`:
+
+```
+//   → grid → card → banner → slideover → marked → sanitize → afterParse
+```
+
+- [ ] **Step 4: Add `aria-label` to the `sanitizeHtml` button allowlist**
+
+Find the `sanitizeHtml` config at the bottom of `parseMarkdown`. Locate the `button` entry in `allowedAttributes`:
+
+```js
+button: ['type', 'disabled', 'data-action', 'data-entry', 'data-confirm'],
+```
+
+Add `'aria-label'` unconditionally:
+
+```js
+button: ['type', 'disabled', 'aria-label', 'data-action', 'data-entry', 'data-confirm'],
+```
+
+This ensures the dismiss button's accessible label survives sanitisation.
+
+- [ ] **Step 5: Verify via curl**
+
+```bash
+curl -s -X POST http://localhost:4096/api/pages/preview \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -d '{"content":"[banner type=\"success\" title=\"Done\" icon=\"check-circle\" dismissible]\nAll saved.\n[/banner]"}' \
+  | grep -o 'dm-banner[^"]*"'
+```
+
+Expected: `dm-banner dm-banner--success"` in output, `dm-banner__icon`, `dm-banner__title`, `dm-banner__dismiss`.
+
+---
+
+## Task 7: Banner CSS
+
+**File:** Modify `public/css/site.css`
+
+- [ ] **Step 1: Add banner base and variant styles**
+
+Append to `public/css/site.css`:
+
+```css
+/* ─── Banner shortcode ──────────────────────────────────────────────────── */
+
+.dm-banner {
+    position: relative;
+    display: flex;
+    align-items: flex-start;
+    gap: .75rem;
+    padding: .85rem 1rem .85rem .9rem;
+    border-radius: 6px;
+    border-left: 4px solid;
+    margin-bottom: 1rem;
+}
+
+.dm-banner__icon {
+    flex-shrink: 0;
+    margin-top: .1rem;
+    width: 1.15rem;
+    height: 1.15rem;
+}
+.dm-banner__icon svg {
+    width: 1.15rem;
+    height: 1.15rem;
+}
+
+.dm-banner__body {
+    flex: 1;
+    min-width: 0;
+}
+
+.dm-banner__title {
+    display: block;
+    margin-bottom: .2rem;
+    font-size: .9em;
+}
+
+.dm-banner__dismiss {
+    position: absolute;
+    top: .5rem;
+    right: .5rem;
+    background: none;
+    border: none;
+    cursor: pointer;
+    font-size: 1.1rem;
+    line-height: 1;
+    padding: .1rem .3rem;
+    opacity: .5;
+    color: inherit;
+}
+.dm-banner__dismiss:hover { opacity: 1; }
+
+/* Type variants */
+.dm-banner--info    { background: color-mix(in srgb, var(--dm-accent, #3b82f6) 10%, transparent); border-color: var(--dm-accent, #3b82f6); color: var(--dm-text, #eee); }
+.dm-banner--success { background: color-mix(in srgb, #22c55e 10%, transparent); border-color: #22c55e; color: var(--dm-text, #eee); }
+.dm-banner--warning { background: color-mix(in srgb, #f59e0b 10%, transparent); border-color: #f59e0b; color: var(--dm-text, #eee); }
+.dm-banner--danger  { background: color-mix(in srgb, #ef4444 10%, transparent); border-color: #ef4444; color: var(--dm-text, #eee); }
+.dm-banner--neutral { background: var(--dm-surface-subtle, rgba(255,255,255,.05)); border-color: var(--dm-border, #444); color: var(--dm-text-muted, #aaa); }
+```
+
+- [ ] **Step 2: Verify in browser**
+
+Navigate to a public page, add a `[banner type="warning" title="Warning"]Test[/banner]` shortcode, preview - verify
+banner renders with amber left border and tinted background.
+
+---
+
+## Task 8: Banner dismiss handler
+
+**File:** Modify `public/js/site.js`
+
+- [ ] **Step 1: Locate a suitable place in `site.js`**
+
+Find the section near the bottom of `site.js` where other DOM event handlers are attached (e.g. accordion collapse,
+slideover wiring).
+
+- [ ] **Step 2: Add the dismiss handler**
+
+```js
+// Banner dismiss
+$(document).on('click', '.dm-banner__dismiss', function () {
+    $(this).closest('.dm-banner').remove();
+});
+```
+
+Important: use **unnamespaced** event delegation - `$(document).on('click.ns', ...)` silently fails in Domma.
+
+- [ ] **Step 3: Verify**
+
+Open a public page with a dismissible banner. Click the × button - banner should disappear with no console errors.
+
+---
+
+## Task 9: Toolbar - `banner` insert item + icon + handler
+
+**File:** Modify `admin/js/lib/markdown-toolbar.js` (1510 lines)
+
+Three changes in this file.
+
+- [ ] **Step 1: Register the `banner-insert` icon**
+
+Find `registerIcons()` (first function in the file). Add the `banner-insert` icon alongside the others:
+
+```js
+I.register('banner-insert', {
+    viewBox: '0 0 24 24',
+    paths: [
+        'M3 7a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2v10a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V7z',
+        'M3 10h18',
+        'M7 14h4',
+    ],
+    stroke: 'currentColor', fill: 'none', strokeWidth: 2, strokeLinecap: 'round', strokeLinejoin: 'round',
+});
+```
+
+- [ ] **Step 2: Add `banner` to the insert items array**
+
+Find the items array for the Insert dropdown (around line 1261). It starts with `{label: 'Accordion', ...}`. Add
+`Banner` in alphabetical position between `Accordion` and `Badge`:
+
+```js
+{label: 'Accordion', icon: 'accordion-insert', action: 'accordion'},
+{label: 'Banner',    icon: 'banner-insert',    action: 'banner'},     // [banner type="..."]...[/banner]
+{label: 'Badge',     icon: 'badge',             action: 'badge'},
+```
+
+- [ ] **Step 3: Add dispatch in the action switch**
+
+Find the `} else if (action === 'accordion') {` block. Add the banner dispatch nearby (alphabetical order is good, but
+any order works):
+
+```js
+} else if (action === 'banner') {
+    if (handlers.banner) handlers.banner(ta);
+}
+```
+
+- [ ] **Step 4: Add `banner` to the `handlers` object initialisation**
+
+Find the `const handlers = { link: null, image: null, card: null, ... }` object. Add:
+
+```js
+banner: null,
+```
+
+- [ ] **Step 5: Add `onBanner` to the returned handler chain**
+
+Find where `onAccordion(cb)` is defined in the returned object. Add alongside it:
+
+```js
+onBanner(cb) {
+    handlers.banner = cb;
+},
+```
+
+- [ ] **Step 6: Add `onBanner` to the JSDoc `@returns` block**
+
+Find the JSDoc comment above `export function createToolbar(...)`. Add to the returns list:
+
+```js
+ *   onBanner(cb: Function): void,
+```
+
+- [ ] **Step 7: Verify in browser**
+
+Open the admin page editor. Click Insert - verify "Banner" appears in the dropdown with the new icon. (It won't do
+anything yet - handler wired in Task 10.)
+
+---
+
+## Task 10: `onBanner` - Insert dialog
+
+**File:** Modify `admin/js/views/page-editor.js`
+
+- [ ] **Step 1: Add the `onBanner` handler**
+
+Add `V.onBanner(...)` alongside the other handler registrations:
+
+```js
+V.onBanner(ta => {
+    const body = document.createElement('div');
+    body.style.cssText = 'padding:.25rem 0 .5rem;display:flex;flex-direction:column;gap:.75rem;';
+
+    // Type - segmented button group
+    const typeLabel = document.createElement('div');
+    typeLabel.style.cssText = 'display:block;font-size:.7rem;font-weight:600;color:var(--dm-text-muted,#aaa);text-transform:uppercase;letter-spacing:.05em;';
+    typeLabel.textContent = 'Type';
+    body.appendChild(typeLabel);
+
+    const TYPE_OPTS = [
+        { val: 'info',    label: 'Info',    dot: '#3b82f6' },
+        { val: 'success', label: 'Success', dot: '#22c55e' },
+        { val: 'warning', label: 'Warning', dot: '#f59e0b' },
+        { val: 'danger',  label: 'Danger',  dot: '#ef4444' },
+        { val: 'neutral', label: 'Neutral', dot: '#888'    },
+    ];
+
+    const typeGroup = document.createElement('div');
+    typeGroup.style.cssText = 'display:flex;flex-wrap:wrap;gap:.3rem;';
+    let selectedType = 'info';
+
+    const typeBtns = TYPE_OPTS.map(opt => {
+        const btn = document.createElement('button');
+        btn.type = 'button';
+        btn.style.cssText = 'display:flex;align-items:center;gap:.35rem;padding:.3rem .6rem;border:1px solid var(--dm-border,#333);border-radius:4px;background:transparent;color:var(--dm-text,#eee);font-size:.8em;cursor:pointer;';
+        const dot = document.createElement('span');
+        dot.style.cssText = `width:8px;height:8px;border-radius:50%;background:${opt.dot};flex-shrink:0;`;
+        btn.appendChild(dot);
+        btn.appendChild(document.createTextNode(opt.label));
+        if (opt.val === 'info') btn.style.borderColor = opt.dot;
+        btn.addEventListener('click', () => {
+            selectedType = opt.val;
+            typeBtns.forEach((b, i) => {
+                b.style.borderColor = TYPE_OPTS[i].val === selectedType ? TYPE_OPTS[i].dot : 'var(--dm-border,#333)';
+                b.style.fontWeight = TYPE_OPTS[i].val === selectedType ? '600' : '';
+            });
+            preview.update(buildShortcode());
+        });
+        typeGroup.appendChild(btn);
+        return btn;
+    });
+    body.appendChild(typeGroup);
+
+    const titleInput = makeTextInput('Banner heading (optional)');
+    body.appendChild(makeField('Title', titleInput));
+
+    const iconInput = makeTextInput('Domma icon name (optional)');
+    body.appendChild(makeField('Icon', iconInput));
+
+    const dismissWrap = makeCheckbox('Dismissible (show × button)');
+    const dismissCb = dismissWrap.querySelector('input');
+    body.appendChild(dismissWrap);
+
+    function buildShortcode() {
+        const parts = [];
+        if (selectedType !== 'info') parts.push(`type="${selectedType}"`);
+        const title = titleInput.value.trim();
+        if (title) parts.push(`title="${title}"`);
+        const icon = iconInput.value.trim();
+        if (icon) parts.push(`icon="${icon}"`);
+        if (dismissCb.checked) parts.push('dismissible');
+        const attrStr = parts.length ? ' ' + parts.join(' ') : '';
+        return `[banner${attrStr}]\nBanner content here.\n[/banner]`;
+    }
+
+    // Live preview
+    const preview = makeLivePreview();
+    preview.update(buildShortcode());
+    body.appendChild(makeField('Shortcode preview', preview.el));
+
+    [titleInput, iconInput].forEach(el => el.addEventListener('input', () => preview.update(buildShortcode())));
+    dismissCb.addEventListener('change', () => preview.update(buildShortcode()));
+
+    const insertBtn = document.createElement('button');
+    insertBtn.type = 'button';
+    insertBtn.className = 'btn btn-primary';
+    insertBtn.textContent = 'Insert Banner';
+    body.appendChild(insertBtn);
+
+    const modal = E.modal({ title: 'Insert Banner', size: 'sm' });
+    modal.element.appendChild(body);
+    modal.open();
+    requestAnimationFrame(() => titleInput.focus());
+
+    insertBtn.addEventListener('click', () => {
+        modal.close();
+        ke(ta, buildShortcode());
+        ta.dispatchEvent(new Event('input', { bubbles: true }));
+        ta.focus();
+    });
+}),
+```
+
+- [ ] **Step 2: Smoke test end-to-end**
+
+1. Click Insert → Banner
+2. Verify modal opens with segmented type buttons, title/icon text inputs, dismissible checkbox, live preview
+3. Click "Warning" → preview updates to `type="warning"`, button highlights
+4. Enter title "Heads up" → preview updates
+5. Tick dismissible → `dismissible` appears in preview
+6. Click Insert Banner → shortcode inserted in editor
+7. Preview the page → banner renders with amber border, title, dismiss button (if ticked)
+8. On the public page, click × → banner disappears
+
+---
+
+## Task 11: Final smoke test checklist
+
+Verify all three features work together without regressions.
+
+- [ ] **Tabs**: Insert → Tabs → modal opens, all fields work, live preview updates, Insert inserts correctly, preview
+  renders styled tabs (pills/bordered/fade apply)
+- [ ] **Hero**: Insert → Hero → modal opens, conditional background fields show/hide, Insert inserts correctly, preview
+  renders hero with colour/image background as expected
+- [ ] **Banner**: Insert → Banner → modal opens, type selector highlights, Insert inserts correctly, public page renders
+  banner, dismiss works
+- [ ] **Existing Card insert still works** (CardBuilder opens, no JS errors)
+- [ ] **Existing Accordion insert still works** (no JS errors)
+- [ ] No console errors on admin load
+- [ ] No console errors on public page with banner shortcode