domma-cms 1.6.60 → 1.7.0

package/docs/superpowers/specs/plans/2026-03-25-text-shortcode.md

@@ -0,0 +1,545 @@
+# [text] Shortcode 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:** Add a `[text]` shortcode that renders a styled `<span>` with inline CSS, accessible via a modal in the Page
+Editor Insert menu.
+
+**Architecture:** Server-side processor `processTextBlocks()` in `markdown.js` handles rendering; the Insert menu entry
+and modal live entirely in `markdown-toolbar.js`; `docs/markdown-shortcodes.md` is updated to document the shortcode.
+
+**Tech Stack:** Fastify 5 (ESM), Domma SPA admin (`E.modal`, `insertAtCursor`), `sanitize-html`, `gray-matter` +
+`marked`.
+
+**Spec:** `docs/superpowers/specs/2026-03-25-text-shortcode-design.md`
+
+---
+
+## File Map
+
+| File                               | Change                                                                                                   |
+|------------------------------------|----------------------------------------------------------------------------------------------------------|
+| `server/services/markdown.js`      | Add `processTextBlocks()` function + wire into pipeline between `withBadge` and `withButton`             |
+| `admin/js/lib/markdown-toolbar.js` | Register `text-style` icon + add Insert menu entry + add `action === 'text'` branch in `executeAction()` |
+| `docs/markdown-shortcodes.md`      | Add `[text]` section                                                                                     |
+
+---
+
+## Task 1: `processTextBlocks()` - server-side shortcode processor
+
+**Files:**
+
+- Modify: `server/services/markdown.js`
+
+### Background
+
+`processBadgeBlocks` (just above the insertion point) is the closest model - it also outputs a `<span>`, uses
+`scrubCodeRegions`/`restore`, and handles flag attributes via regex rather than `parseShortcodeAttrs`.
+
+Two subtleties:
+
+- `bold` and `italic` are **flag** attributes - use `/\bbold\b/i.test(attrStr)` for consistency with
+  `processBadgeBlocks` (`pill`, `outline`). While `parseShortcodeAttrs` Pass 2 does capture standalone flags as `true`,
+  the regex approach matches existing convention and avoids edge-case ambiguity.
+- `bold` flag takes precedence over `weight` attribute when both are present
+
+- [ ] **Step 1: Add `processTextBlocks` function to `markdown.js`**
+
+Find the closing `}` of `processBadgeBlocks` (search for the line `return restore(result);` followed by `}` in that
+function) and add the following function immediately after it:
+
+```js
+/**
+ * Pre-process [text] shortcodes before running through marked.
+ *
+ * Syntax (paired):
+ *   [text size="xl" bold italic color="primary" font="Georgia"]Your text[/text]
+ *
+ * Outputs a <span> with all resolved styles inlined.
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processTextBlocks(markdown) {
+    const {scrubbed, restore} = scrubCodeRegions(markdown);
+
+    const SIZE_MAP = {
+        xs: '.75rem', sm: '.875rem', base: '1rem', lg: '1.125rem',
+        xl: '1.25rem', '2xl': '1.5rem', '3xl': '1.875rem', '4xl': '2.25rem',
+    };
+    const WEIGHT_MAP = {
+        thin: '100', light: '300', normal: '400', medium: '500',
+        semibold: '600', bold: '700', extrabold: '800', black: '900',
+    };
+    const SPACING_MAP = {
+        tight: '-0.05em', normal: '0em', wide: '0.05em', wider: '0.1em',
+    };
+    const COLOR_TOKENS = {
+        primary: 'var(--dm-color-primary)', secondary: 'var(--dm-color-secondary)',
+        muted: 'var(--dm-text-muted)', danger: 'var(--dm-color-danger)',
+        success: 'var(--dm-color-success)', warning: 'var(--dm-color-warning)',
+        info: 'var(--dm-color-info)',
+    };
+    const FONT_MAP = {
+        'Georgia': 'Georgia,serif',
+        'Arial': 'Arial,sans-serif',
+        'Verdana': 'Verdana,sans-serif',
+        'Courier New': "'Courier New',monospace",
+        'Times New Roman': "'Times New Roman',serif",
+        'Trebuchet MS': "'Trebuchet MS',sans-serif",
+    };
+    const TRANSFORM_MAP = {
+        upper: 'uppercase', lower: 'lowercase', capitalize: 'capitalize', none: 'none',
+    };
+    const DECORATION_MAP = {
+        underline: 'underline', 'line-through': 'line-through', none: 'none',
+    };
+
+    function buildText(attrStr, inner) {
+        const attrs = parseShortcodeAttrs(attrStr || '');
+        const styles = [];
+
+        if (attrs.size) {
+            styles.push(`font-size:${SIZE_MAP[attrs.size] || attrs.size}`);
+        }
+
+        // bold flag takes precedence over weight attr
+        const isBold = /\bbold\b/i.test(attrStr);
+        if (isBold) {
+            styles.push('font-weight:700');
+        } else if (attrs.weight && WEIGHT_MAP[attrs.weight]) {
+            styles.push(`font-weight:${WEIGHT_MAP[attrs.weight]}`);
+        }
+
+        if (/\bitalic\b/i.test(attrStr)) {
+            styles.push('font-style:italic');
+        }
+
+        if (attrs.color) {
+            styles.push(`color:${COLOR_TOKENS[attrs.color] || attrs.color}`);
+        }
+
+        if (attrs.font && FONT_MAP[attrs.font]) {
+            styles.push(`font-family:${FONT_MAP[attrs.font]}`);
+        }
+
+        if (attrs.transform && TRANSFORM_MAP[attrs.transform]) {
+            styles.push(`text-transform:${TRANSFORM_MAP[attrs.transform]}`);
+        }
+
+        if (attrs.decoration && DECORATION_MAP[attrs.decoration]) {
+            styles.push(`text-decoration:${DECORATION_MAP[attrs.decoration]}`);
+        }
+
+        if (attrs.spacing) {
+            styles.push(`letter-spacing:${SPACING_MAP[attrs.spacing] || attrs.spacing}`);
+        }
+
+        const styleAttr = styles.length ? ` style="${styles.join(';')}"` : '';
+        const classAttr = attrs.class ? ` class="${escapeAttr(attrs.class)}"` : '';
+        const idAttr = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
+
+        return `<span${styleAttr}${classAttr}${idAttr}>${inner.trim()}</span>`;
+    }
+
+    const result = scrubbed.replace(
+        /\[text([^\]]*)\]([\s\S]*?)\[\/text\]/gi,
+        (_, attrStr, body) => buildText(attrStr, body)
+    );
+
+    return restore(result);
+}
+```
+
+- [ ] **Step 2: Wire `processTextBlocks` into the parse pipeline**
+
+In the same file, find these two adjacent lines (around the `withBadge`/`withButton` section):
+
+```js
+const withBadge  = processBadgeBlocks(withTable);
+const withButton = processButtonBlocks(withBadge);
+```
+
+Replace with:
+
+```js
+const withBadge  = processBadgeBlocks(withTable);
+const withText   = processTextBlocks(withBadge);
+const withButton = processButtonBlocks(withText);
+```
+
+- [ ] **Step 3: Verify the processor works**
+
+The server is always running on port 4096. Create a quick test page using the API - or just edit an existing page's
+content via the admin - to contain:
+
+```
+[text size="xl" bold italic color="primary"]Hello styled world[/text]
+```
+
+Then curl the public page and check the rendered HTML contains:
+
+```
+<span style="font-size:1.25rem;font-weight:700;font-style:italic;color:var(--dm-color-primary);">Hello styled world</span>
+```
+
+Also verify these edge cases render correctly:
+
+- `[text]Plain text[/text]` → `<span>Plain text</span>` (no style attr)
+- `[text bold weight="light"]Text[/text]` → `font-weight:700` only (bold wins)
+- `[text size="2em"]Big[/text]` → `font-size:2em` (raw value passthrough)
+- Shortcode inside a fenced code block should be left untouched (scrubCodeRegions)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add server/services/markdown.js
+git commit -m "feat: add [text] shortcode server-side processor"
+```
+
+---
+
+## Task 2: Insert menu entry + modal - `markdown-toolbar.js`
+
+**Files:**
+
+- Modify: `admin/js/lib/markdown-toolbar.js`
+
+### Background
+
+All insert-action modals live directly inside `executeAction()` in `markdown-toolbar.js` - there is no `onText` callback
+and no `page-editor.js` change. The modal uses `E.modal` (Domma global), `insertAtCursor` (imported in the same file),
+and the same `makeRow`/`makeSelect`/`makeInput` helper pattern seen in other actions.
+
+The live preview uses a `<span>` inside a wrapping `<div>` - styles are applied directly to the `<span>` to match the
+actual rendered element (inline context).
+
+- [ ] **Step 1: Register the `text-style` icon**
+
+Inside `registerIcons()`, add after the last `I.register(...)` call:
+
+```js
+I.register('text-style', {
+    viewBox: '0 0 24 24',
+    paths: [
+        'M4 7V5h16v2',
+        'M9 19h6',
+        'M12 5v14',
+        'M5 12h14',
+    ],
+    stroke: 'currentColor', fill: 'none', strokeWidth: 2, strokeLinecap: 'round', strokeLinejoin: 'round'
+});
+```
+
+- [ ] **Step 2: Add the Insert menu entry**
+
+Find the Insert dropdown items array (search for `{label: 'Tabs', icon:`). Add the `Text` entry between `Tabs` and
+`Timeline`:
+
+```js
+{label: 'Tabs',     icon: 'layout-list',   action: 'tabs'},
+{label: 'Text',     icon: 'text-style',    action: 'text'},   // ← add this line
+{label: 'Timeline', icon: 'activity',      action: 'timeline'},
+```
+
+- [ ] **Step 3: Add the `text` action handler in `executeAction()`**
+
+Find the closing branch before the final `}` of `executeAction` - it ends with:
+
+```js
+  } else if (action === 'help') {
+    if (handlers.help) handlers.help(ta);
+  }
+}
+```
+
+Insert the `text` branch before the `help` branch:
+
+```js
+  } else if (action === 'text') {
+    const start = ta.selectionStart;
+    const end   = ta.selectionEnd;
+    const selected = ta.value.substring(start, end) || '';
+
+    const labelStyle = 'display:block;font-size:.7rem;font-weight:600;color:var(--dm-text-muted,#aaa);text-transform:uppercase;letter-spacing:.05em;';
+    const inputStyle = '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;';
+
+    function makeRow(labelText, control) {
+      const row = document.createElement('div');
+      const lbl = document.createElement('label');
+      lbl.style.cssText = labelStyle;
+      lbl.textContent = labelText;
+      row.appendChild(lbl);
+      row.appendChild(control);
+      return row;
+    }
+
+    function makeSelect(options) {
+      const sel = document.createElement('select');
+      sel.style.cssText = inputStyle;
+      [['', '- default -'], ...options].forEach(([val, text]) => {
+        const opt = document.createElement('option');
+        opt.value = val;
+        opt.textContent = text;
+        sel.appendChild(opt);
+      });
+      return sel;
+    }
+
+    function makeTextInput(placeholder, value) {
+      const inp = document.createElement('input');
+      inp.type = 'text';
+      inp.placeholder = placeholder || '';
+      inp.value = value || '';
+      inp.style.cssText = inputStyle;
+      return inp;
+    }
+
+    function makeCheckbox(labelText) {
+      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 = labelText;
+      wrap.appendChild(cb);
+      wrap.appendChild(span);
+      return {wrap, cb};
+    }
+
+    const wrapper = document.createElement('div');
+    wrapper.style.cssText = 'padding:1rem;display:flex;flex-direction:column;gap:.75rem;';
+
+    const contentInput = makeTextInput('Text to style…', selected);
+    wrapper.appendChild(makeRow('Content', contentInput));
+
+    const sizeSelect = makeSelect([
+      ['xs','xs - 0.75rem'], ['sm','sm - 0.875rem'], ['base','base - 1rem'],
+      ['lg','lg - 1.125rem'], ['xl','xl - 1.25rem'], ['2xl','2xl - 1.5rem'],
+      ['3xl','3xl - 1.875rem'], ['4xl','4xl - 2.25rem'],
+    ]);
+    wrapper.appendChild(makeRow('Size', sizeSelect));
+
+    const weightSelect = makeSelect([
+      ['thin','Thin (100)'], ['light','Light (300)'], ['normal','Normal (400)'],
+      ['medium','Medium (500)'], ['semibold','Semibold (600)'], ['bold','Bold (700)'],
+      ['extrabold','Extrabold (800)'], ['black','Black (900)'],
+    ]);
+    wrapper.appendChild(makeRow('Weight', weightSelect));
+
+    const {wrap: boldWrap, cb: boldCb} = makeCheckbox('Bold (shorthand - overrides Weight)');
+    wrapper.appendChild(boldWrap);
+
+    const {wrap: italicWrap, cb: italicCb} = makeCheckbox('Italic');
+    wrapper.appendChild(italicWrap);
+
+    const colorInput = makeTextInput('e.g. primary, #ff0000, rgb(255,0,0)');
+    wrapper.appendChild(makeRow('Colour', colorInput));
+
+    const fontSelect = makeSelect([
+      ['Georgia','Georgia (serif)'], ['Arial','Arial (sans-serif)'],
+      ['Verdana','Verdana (sans-serif)'], ['Courier New','Courier New (monospace)'],
+      ['Times New Roman','Times New Roman (serif)'], ['Trebuchet MS','Trebuchet MS (sans-serif)'],
+    ]);
+    wrapper.appendChild(makeRow('Font', fontSelect));
+
+    const transformSelect = makeSelect([
+      ['upper','Uppercase'], ['lower','Lowercase'], ['capitalize','Capitalise'], ['none','None'],
+    ]);
+    wrapper.appendChild(makeRow('Transform', transformSelect));
+
+    const decorationSelect = makeSelect([
+      ['underline','Underline'], ['line-through','Line-through'], ['none','None'],
+    ]);
+    wrapper.appendChild(makeRow('Decoration', decorationSelect));
+
+    const spacingSelect = makeSelect([
+      ['tight','Tight'], ['normal','Normal'], ['wide','Wide'], ['wider','Wider'],
+    ]);
+    wrapper.appendChild(makeRow('Spacing', spacingSelect));
+
+    const classInput = makeTextInput('Optional CSS class');
+    wrapper.appendChild(makeRow('CSS Class', classInput));
+
+    const idInput = makeTextInput('Optional ID');
+    wrapper.appendChild(makeRow('ID', idInput));
+
+    // Live preview - <span> inside <div> for accurate inline-context representation
+    const previewWrap = document.createElement('div');
+    previewWrap.style.cssText = 'padding:.75rem;background:var(--dm-surface-subtle,#111);border-radius:4px;min-height:2.5rem;display:flex;align-items:center;';
+    const previewSpan = document.createElement('span');
+    previewSpan.textContent = selected || 'Preview text';
+    previewWrap.appendChild(previewSpan);
+    wrapper.appendChild(makeRow('Preview', previewWrap));
+
+    const COLOR_TOKENS_PREV = {
+      primary:'var(--dm-color-primary)',secondary:'var(--dm-color-secondary)',
+      muted:'var(--dm-text-muted)',danger:'var(--dm-color-danger)',
+      success:'var(--dm-color-success)',warning:'var(--dm-color-warning)',info:'var(--dm-color-info)',
+    };
+    const SIZE_MAP_PREV = {xs:'.75rem',sm:'.875rem',base:'1rem',lg:'1.125rem',xl:'1.25rem','2xl':'1.5rem','3xl':'1.875rem','4xl':'2.25rem'};
+    const WEIGHT_MAP_PREV = {thin:'100',light:'300',normal:'400',medium:'500',semibold:'600',bold:'700',extrabold:'800',black:'900'};
+    const SPACING_MAP_PREV = {tight:'-0.05em',normal:'0em',wide:'0.05em',wider:'0.1em'};
+    const FONT_MAP_PREV = {'Georgia':'Georgia,serif','Arial':'Arial,sans-serif','Verdana':'Verdana,sans-serif','Courier New':"'Courier New',monospace",'Times New Roman':"'Times New Roman',serif",'Trebuchet MS':"'Trebuchet MS',sans-serif"};
+    const TRANSFORM_MAP_PREV = {upper:'uppercase',lower:'lowercase',capitalize:'capitalize',none:'none'};
+    const DECORATION_MAP_PREV = {underline:'underline','line-through':'line-through',none:'none'};
+
+    function updatePreview() {
+      const styles = [];
+      if (sizeSelect.value) styles.push(`font-size:${SIZE_MAP_PREV[sizeSelect.value] || sizeSelect.value}`);
+      if (boldCb.checked) {
+        styles.push('font-weight:700');
+      } else if (weightSelect.value) {
+        styles.push(`font-weight:${WEIGHT_MAP_PREV[weightSelect.value] || weightSelect.value}`);
+      }
+      if (italicCb.checked) styles.push('font-style:italic');
+      const col = colorInput.value.trim();
+      if (col) styles.push(`color:${COLOR_TOKENS_PREV[col] || col}`);
+      if (fontSelect.value) styles.push(`font-family:${FONT_MAP_PREV[fontSelect.value]}`);
+      if (transformSelect.value) styles.push(`text-transform:${TRANSFORM_MAP_PREV[transformSelect.value]}`);
+      if (decorationSelect.value) styles.push(`text-decoration:${DECORATION_MAP_PREV[decorationSelect.value]}`);
+      if (spacingSelect.value) styles.push(`letter-spacing:${SPACING_MAP_PREV[spacingSelect.value]}`);
+      previewSpan.style.cssText = styles.join(';');
+      previewSpan.textContent = contentInput.value || 'Preview text';
+    }
+
+    boldCb.addEventListener('change', () => {
+      weightSelect.disabled = boldCb.checked;
+      if (boldCb.checked) weightSelect.value = '';
+      updatePreview();
+    });
+    [sizeSelect, weightSelect, fontSelect, transformSelect, decorationSelect, spacingSelect].forEach(el => {
+      el.addEventListener('change', updatePreview);
+    });
+    [colorInput, contentInput].forEach(el => {
+      el.addEventListener('input', updatePreview);
+    });
+    italicCb.addEventListener('change', updatePreview);
+
+    const insertBtn = document.createElement('button');
+    insertBtn.type = 'button';
+    insertBtn.className = 'btn btn-primary';
+    insertBtn.textContent = 'Insert';
+    wrapper.appendChild(insertBtn);
+
+    const modal = E.modal({title: 'Style Text', size: 'sm'});
+    modal.element.appendChild(wrapper);
+    modal.open();
+
+    insertBtn.addEventListener('click', () => {
+      const content = contentInput.value;
+      if (!content) return;
+      const parts = [];
+      if (sizeSelect.value) parts.push(`size="${sizeSelect.value}"`);
+      if (boldCb.checked) {
+        parts.push('bold');
+      } else if (weightSelect.value) {
+        parts.push(`weight="${weightSelect.value}"`);
+      }
+      if (italicCb.checked) parts.push('italic');
+      if (colorInput.value.trim()) parts.push(`color="${colorInput.value.trim()}"`);
+      if (fontSelect.value) parts.push(`font="${fontSelect.value}"`);
+      if (transformSelect.value) parts.push(`transform="${transformSelect.value}"`);
+      if (decorationSelect.value) parts.push(`decoration="${decorationSelect.value}"`);
+      if (spacingSelect.value) parts.push(`spacing="${spacingSelect.value}"`);
+      if (classInput.value.trim()) parts.push(`class="${classInput.value.trim()}"`);
+      if (idInput.value.trim()) parts.push(`id="${idInput.value.trim()}"`);
+      const attrStr = parts.length ? ' ' + parts.join(' ') : '';
+      const snippet = `[text${attrStr}]${content}[/text]`;
+      modal.close();
+      insertAtCursor(ta, snippet);
+      ta.dispatchEvent(new Event('input', {bubbles: true}));
+      ta.focus();
+    });
+  // end of action === 'text' branch
+  }
+```
+
+- [ ] **Step 4: Verify in the browser**
+
+Open the page editor in the admin. Click the Insert (`+`) dropdown. Confirm **Text** appears between Tabs and Timeline
+with the `text-style` icon.
+
+Click Text → confirm the "Style Text" modal opens with all controls. Test:
+
+- Select a size, enable Bold, add a colour token (`primary`) → preview updates in real time
+- Enable Bold → confirm Weight select is disabled
+- Type content → confirm preview text updates
+- Click Insert → confirm the correct shortcode is inserted at the cursor, modal closes
+
+Also verify that selecting text in the editor before opening the modal pre-fills the Content field.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add admin/js/lib/markdown-toolbar.js
+git commit -m "feat: add [text] shortcode insert modal to Page Editor"
+```
+
+---
+
+## Task 3: Document `[text]` in `docs/markdown-shortcodes.md`
+
+**Files:**
+
+- Modify: `docs/markdown-shortcodes.md`
+
+- [ ] **Step 1: Add the `[text]` section**
+
+Find the `## [badge]` section and add the following section immediately before it (text sorts before badge
+alphabetically, but place it wherever the doc's existing ordering convention dictates - check if sections are
+alphabetical or by category):
+
+```markdown
+## `[text]`
+
+Wraps inline text in a `<span>` with custom styles. All attributes are optional.
+
+```
+
+[text size="xl" bold italic color="primary"]Styled text[/text]
+[text font="Georgia" decoration="underline" spacing="wide"]Classic[/text]
+[text size="2em" color="#ff6600"]Custom size and colour[/text]
+
+```
+
+### Attributes
+
+| Attribute    | Values | Notes |
+|---|---|---|
+| `size`       | `xs` `sm` `base` `lg` `xl` `2xl` `3xl` `4xl` or raw CSS (e.g. `"1.5em"`) | Maps to `font-size` |
+| `weight`     | `thin` `light` `normal` `medium` `semibold` `bold` `extrabold` `black` | Maps to `font-weight` |
+| `bold`       | flag | Shorthand for `font-weight:700`. Overrides `weight` if both present |
+| `italic`     | flag | `font-style:italic` |
+| `color`      | Token (`primary` `secondary` `muted` `danger` `success` `warning` `info`) or any CSS colour | Maps to `color` |
+| `font`       | `Georgia` `Arial` `Verdana` `Courier New` `Times New Roman` `Trebuchet MS` | Web-safe fonts only |
+| `transform`  | `upper` `lower` `capitalize` `none` | Maps to `text-transform` |
+| `decoration` | `underline` `line-through` `none` | Maps to `text-decoration` |
+| `spacing`    | `tight` `normal` `wide` `wider` or raw CSS (e.g. `"0.1em"`) | Maps to `letter-spacing` |
+| `class`      | CSS class name(s) | Added to the `<span>` element |
+| `id`         | Element ID | Added to the `<span>` element |
+
+### Notes
+
+- `align` is intentionally not supported - `text-align` has no effect on inline elements. Use `[center]` for centring or a grid/card for other layout alignment.
+- The Page Editor Insert menu includes a **Text** entry that opens a configuration modal with live preview.
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add docs/markdown-shortcodes.md
+git commit -m "docs: document [text] shortcode"
+```
+
+---
+
+## Done
+
+At this point:
+
+- `[text size="xl" bold italic]Hello[/text]` renders correctly in public pages
+- The Page Editor Insert → Text menu item opens the modal, live preview works, Insert button writes the shortcode
+- `docs/markdown-shortcodes.md` is updated