domma-cms 1.6.60 → 1.7.0

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

@@ -0,0 +1,168 @@
+# Design Spec: `[text]` Shortcode
+
+**Date:** 2026-03-25
+**Status:** Approved
+
+## Overview
+
+Add a `[text]` shortcode that renders a `<span>` with inline styles, giving content authors a simple, readable way to
+apply rich text formatting directly in Markdown without writing raw HTML.
+
+The shortcode is accessible via the existing Page Editor Insert icon menu (the `plus-circle` dropdown), which opens a
+modal letting users configure options and preview the result before inserting.
+
+---
+
+## Shortcode Syntax
+
+```
+[text size="xl" bold italic color="primary" font="Georgia"]Your text[/text]
+```
+
+Renders:
+
+```html
+<span style="font-size:1.25rem;font-weight:700;font-style:italic;color:var(--dm-color-primary);font-family:Georgia,serif;">Your text</span>
+```
+
+Only attributes that differ from defaults are emitted. All attributes are optional. Paired syntax only - no self-closing
+form.
+
+---
+
+## Supported Attributes
+
+| Attribute    | Values                                                                                | CSS Property        |
+|--------------|---------------------------------------------------------------------------------------|---------------------|
+| `size`       | `xs` `sm` `base` `lg` `xl` `2xl` `3xl` `4xl` or raw (e.g. `"1.5em"`)                  | `font-size`         |
+| `weight`     | `thin` `light` `normal` `medium` `semibold` `bold` `extrabold` `black`                | `font-weight`       |
+| `bold`       | flag (presence in raw attr string)                                                    | `font-weight:700`   |
+| `italic`     | flag (presence in raw attr string)                                                    | `font-style:italic` |
+| `color`      | CSS color OR token: `primary` `secondary` `muted` `danger` `success` `warning` `info` | `color`             |
+| `font`       | `Georgia` `Arial` `Verdana` `Courier New` `Times New Roman` `Trebuchet MS`            | `font-family`       |
+| `transform`  | `upper` `lower` `capitalize` `none`                                                   | `text-transform`    |
+| `decoration` | `underline` `line-through` `none`                                                     | `text-decoration`   |
+| `spacing`    | `tight` `normal` `wide` `wider` or raw (e.g. `"0.1em"`)                               | `letter-spacing`    |
+| `class`      | Extra CSS class(es)                                                                   | `class` attribute   |
+| `id`         | Element ID                                                                            | `id` attribute      |
+
+> **Note:** `align` (`text-align`) is intentionally excluded. `text-align` has no effect on inline `<span>` elements.
+> Use the `[center]` shortcode for centering, or wrap content in a `[card]` / `[grid]` for other alignment needs.
+
+### Size token map
+
+`xs→.75rem` · `sm→.875rem` · `base→1rem` · `lg→1.125rem` · `xl→1.25rem` · `2xl→1.5rem` · `3xl→1.875rem` · `4xl→2.25rem`
+
+Unrecognised values pass through as raw CSS (e.g. `size="2em"` → `font-size:2em`).
+
+### Weight token map
+
+`thin→100` · `light→300` · `normal→400` · `medium→500` · `semibold→600` · `bold→700` · `extrabold→800` · `black→900`
+
+### Spacing token map
+
+`tight→-0.05em` · `normal→0em` · `wide→0.05em` · `wider→0.1em`
+
+Unrecognised values pass through as raw CSS.
+
+### Color token map
+
+`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)`
+
+Unrecognised values pass through as raw CSS (hex, rgb, named CSS colours all work).
+
+### Font family 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"`
+
+### Transform map
+
+`upper→uppercase` · `lower→lowercase` · `capitalize→capitalize` · `none→none`
+
+---
+
+## Processing Pipeline
+
+`processTextBlocks()` is added to `server/services/markdown.js` and inserted between `[badge]` and `[button]`:
+
+```js
+const withBadge  = processBadgeBlocks(withTable);
+const withText   = processTextBlocks(withBadge);   // ← new
+const withButton = processButtonBlocks(withText);
+```
+
+### Implementation notes
+
+- Uses `scrubCodeRegions` / `restore` pattern (same as all other shortcode processors) to skip fenced code blocks.
+- **Flag detection:** `bold` and `italic` are flag attributes detected via regex on the raw attribute string - do NOT
+  use `parseShortcodeAttrs()` for these, as it only handles `key=value` pairs. Use `/\bbold\b/i.test(attrStr)` and
+  `/\bitalic\b/i.test(attrStr)`.
+- **`bold` + `weight` precedence:** If both `bold` flag and `weight` attribute are present, `bold` wins - emit
+  `font-weight:700` and ignore `weight`.
+- **`class` and `id` escaping:** Values from `class` and `id` attributes must be passed through `escapeAttr()` before
+  being written into the HTML output.
+- **Inner content:** The shortcode body passes through `marked` and then `sanitize-html` downstream - no extra escaping
+  needed in the processor itself.
+
+No changes needed to sanitize-html config - `style`, `class`, and `id` are already whitelisted via
+`'*': ['class', 'id', 'style', 'data-*']`.
+
+---
+
+## Admin Insert Menu
+
+### markdown-toolbar.js changes
+
+1. Register a `text-style` SVG icon in `registerIcons()`.
+2. Add `{label: 'Text', icon: 'text-style', action: 'text'}` to the Insert dropdown items array between
+   `{label: 'Tabs', ...}` and `{label: 'Timeline', ...}`.
+3. Add `} else if (action === 'text') { ... }` inside the existing `executeAction()` function's `else if` chain - this
+   is where the modal is opened. **There is no `onText` callback and no `page-editor.js` change needed.** All
+   insert-action modals live directly inside `executeAction()` in `markdown-toolbar.js`.
+
+### Modal: "Style Text" (size `sm`)
+
+Opened from the `action === 'text'` branch in `executeAction()`. Controls:
+
+| Field      | Control                   | Notes                                                                    |
+|------------|---------------------------|--------------------------------------------------------------------------|
+| Content    | `<input type="text">`     | Pre-filled with any currently selected editor text                       |
+| Size       | `<select>`                | Blank (default) + xs/sm/base/lg/xl/2xl/3xl/4xl                           |
+| Weight     | `<select>`                | Blank (default) + thin/light/normal/medium/semibold/bold/extrabold/black |
+| Bold       | `<input type="checkbox">` | Shorthand - disables the Weight select when checked                      |
+| Italic     | `<input type="checkbox">` |                                                                          |
+| Colour     | `<input type="text">`     | Placeholder lists token names; accepts any CSS colour                    |
+| Font       | `<select>`                | Blank (default) + 6 web-safe fonts                                       |
+| Transform  | `<select>`                | Blank (default) + uppercase/lowercase/capitalise/none                    |
+| Decoration | `<select>`                | Blank (default) + underline/line-through/none                            |
+| Spacing    | `<select>`                | Blank (default) + tight/normal/wide/wider                                |
+| CSS Class  | `<input type="text">`     | Optional                                                                 |
+| ID         | `<input type="text">`     | Optional                                                                 |
+
+**Live preview:** A wrapping `<div>` containing a `<span>` that updates in real time as controls change. Styles are
+applied directly to the inner `<span>` to faithfully represent the actual rendered element (inline context, not block).
+
+**Insert button:** Builds the shortcode string from only non-blank/non-default values, calls
+`insertAtCursor(ta, snippet)`, closes the modal.
+
+---
+
+## Files Changed
+
+| File                               | Change                                                                                                            |
+|------------------------------------|-------------------------------------------------------------------------------------------------------------------|
+| `server/services/markdown.js`      | Add `processTextBlocks()`, insert 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()` with modal |
+| `docs/markdown-shortcodes.md`      | Document new shortcode                                                                                            |
+
+---
+
+## Notes
+
+- `[text]` is safe to nest inside `[card]`, `[slideover]`, `[grid]`, `[hero]`, etc.
+- No client-side JS required - output is a plain `<span>` with inline styles, works in SSR.
+- The modal is the canonical entry point; users can also write the shortcode by hand.

package/docs/superpowers/specs/2026-04-05-card-builder-design.md

@@ -0,0 +1,315 @@
+# Card Builder - Design Spec
+
+**Date:** 2026-04-05  
+**Status:** Approved
+
+---
+
+## Overview
+
+Enhance the page editor's card shortcode with an interactive visual builder dialog and significantly expand the `[card]`
+shortcode to support 33 layout templates (27 Tier 1 attribute-driven + 6 Tier 2 sub-tag structured), 6 style variants,
+and 14 gradient presets. The builder is a modal UI that generates a shortcode string and inserts it into the markdown
+editor at the cursor position. No new API routes or database changes are required.
+
+---
+
+## Files
+
+| File                                   | Change                                                   |
+|----------------------------------------|----------------------------------------------------------|
+| `admin/js/lib/card-builder.js`         | **New** - self-contained builder module                  |
+| `admin/js/templates/card-builder.html` | **New** - builder dialog template                        |
+| `admin/js/views/page-editor.js`        | **Modified** - wire `toolbar.onCard()`                   |
+| `server/services/markdown.js`          | **Modified** - extend `processCardBlocks` for 33 layouts |
+| `public/css/site.css`                  | **Modified** - 6 variants, 14 gradients, layout CSS      |
+
+---
+
+## Architecture
+
+**Approach:** Dedicated `card-builder.js` module (Option A).
+
+**Flow:**
+
+1. User clicks **Card** in the markdown toolbar
+2. `toolbar.onCard()` fires → `CardBuilder.open(textarea)` called
+3. Modal dialog opens with layout picker, style swatches, dynamic fields, live preview
+4. User configures card visually - preview updates in real time
+5. User clicks **Insert Card** → shortcode string inserted at cursor → modal closes
+6. On save/preview, `processCardBlocks()` in `markdown.js` renders shortcode to HTML
+
+The builder is completely decoupled from the editor. It receives a textarea reference on open and writes a shortcode
+string back on insert. It has no knowledge of the editor's internal state.
+
+---
+
+## Shortcode Grammar
+
+### Universal attributes (all layouts)
+
+| Attribute     | Values                                            | Notes                                                         |
+|---------------|---------------------------------------------------|---------------------------------------------------------------|
+| `layout`      | 33 layout keys                                    | Routes to correct renderer. Omit for `header-body` (default). |
+| `title`       | string                                            | Header title where applicable                                 |
+| `subtitle`    | string                                            | Secondary line beneath title                                  |
+| `icon`        | string                                            | Domma icon name                                               |
+| `icon-layout` | `inline` \| `stacked`                             | Icon position relative to title                               |
+| `variant`     | `clean` `gradient` `glass` `accent` `dark` `glow` | Visual style                                                  |
+| `gradient`    | See gradient presets                              | Only used when `variant="gradient"`                           |
+| `hover`       | flag                                              | Adds lift effect on hover                                     |
+| `collapsible` | `"true"`                                          | Toggleable body via header click                              |
+| `image`       | URL                                               | Image source for image-based layouts                          |
+| `footer`      | string                                            | Simple text footer                                            |
+| `class`       | string                                            | Extra CSS classes                                             |
+| `id`          | string                                            | Anchor ID                                                     |
+
+### Layout-specific attributes
+
+| Attribute      | Layouts                   | Purpose                                   |
+|----------------|---------------------------|-------------------------------------------|
+| `value`        | stat-metric               | Big display value                         |
+| `delta`        | stat-metric               | Change indicator e.g. `↑ 12.4%`           |
+| `progress`     | progress-goal             | Integer 0-100 for progress bar fill       |
+| `price`        | pricing                   | Price string e.g. `£29`                   |
+| `period`       | pricing                   | Billing period label                      |
+| `lang`         | code-snippet              | Language label for syntax highlight badge |
+| `filename`     | file-document             | Display filename                          |
+| `filesize`     | file-document             | Size label e.g. `2.4 MB`                  |
+| `filetype`     | file-document             | Extension badge e.g. `PDF`                |
+| `rating`       | rating-review             | Integer 1-5 for star display              |
+| `duration`     | video-media               | Time label e.g. `4:32`                    |
+| `address`      | location-map              | Address line beneath map placeholder      |
+| `step`         | step-numbered             | Step number                               |
+| `badge`        | corner-badge, badge-band  | Badge label text                          |
+| `tags`         | avatar-profile, tag-cloud | Comma-separated pill labels               |
+| `callout-type` | callout                   | `info` `warn` `success` `error`           |
+
+### Sub-tags (Tier 2 layouts)
+
+```
+[before]...[/before]   → before-after (left column)
+[after]...[/after]     → before-after (right column)
+[feature]...[/feature] → pricing, feature-comparison (repeating rows)
+[activity user="..." action="..." time="..."] → activity-feed
+[milestone done]...[/milestone] → progress-goal
+```
+
+---
+
+## The 33 Layouts
+
+### Tier 1 - Attribute-driven (27 layouts, body is plain Markdown)
+
+| Key                     | Description                                                          |
+|-------------------------|----------------------------------------------------------------------|
+| `basic`                 | Body only, no header                                                 |
+| `header-body`           | Header + body (default)                                              |
+| `header-body-footer`    | Header + body + footer                                               |
+| `no-header-footer`      | Body + footer, no header                                             |
+| `icon-top`              | Icon centred above title (stacked)                                   |
+| `icon-inline`           | Icon beside title in flex row                                        |
+| `image-top`             | Image at top, content below                                          |
+| `image-overlay`         | Image with title overlaid via gradient scrim                         |
+| `thumb-left`            | Narrow image strip left, content right                               |
+| `thumb-right`           | Narrow image strip right, content left                               |
+| `wide-left-image`       | Wide image left, content right                                       |
+| `full-bg`               | Full dark/image background card                                      |
+| `split-half`            | Colour/image left half, dark content right half                      |
+| `avatar-profile`        | Circular avatar, name, role, tag pills                               |
+| `stat-metric`           | Large value, label, delta, progress bar                              |
+| `quote-testimonial`     | Quote marks, italic text, avatar attribution                         |
+| `callout`               | Left accent stripe + icon (info/warn/success/error)                  |
+| `video-media`           | Thumbnail with play button + duration badge                          |
+| `location-map`          | Grid map placeholder + address                                       |
+| `step-numbered`         | Ghost large number + step badge                                      |
+| `corner-badge`          | Badge pinned top-right, icon, centred title                          |
+| `badge-band`            | Gradient band with badge + icon, then content                        |
+| `glass-gradient-border` | Multi-stop gradient border ring on frosted glass                     |
+| `rating-review`         | Stars, italic review, avatar attribution + verified                  |
+| `tag-cloud`             | Heading + wrapped coloured pill tags                                 |
+| `timeline-entry`        | Date, dot, vertical line, title, text, tag                           |
+| `code-snippet`          | Body is raw code (no sub-tags); `lang` attribute sets language badge |
+
+### Tier 2 - Sub-tag structured (6 layouts, body uses named sub-tags)
+
+| Key                  | Sub-tags used                                                          |
+|----------------------|------------------------------------------------------------------------|
+| `before-after`       | `[before]` / `[after]`                                                 |
+| `pricing`            | `[feature]` list                                                       |
+| `feature-comparison` | `[feature]` with ✓/✗ values                                            |
+| `activity-feed`      | `[activity]` items                                                     |
+| `progress-goal`      | `[milestone]` items                                                    |
+| `file-document`      | Attributes only - any body content is silently ignored by the renderer |
+
+---
+
+## 6 Style Variants
+
+| Variant    | Class               | Hover Effect                                  |
+|------------|---------------------|-----------------------------------------------|
+| `clean`    | `.dm-card-clean`    | translateY(-4px) + shadow deepen              |
+| `gradient` | `.dm-card-gradient` | translateY(-5px) + violet shadow bloom        |
+| `glass`    | `.dm-card-glass`    | translateY(-4px) + backdrop lightens          |
+| `accent`   | `.dm-card-accent`   | translateY(-3px) + border deepens + shadow    |
+| `dark`     | `.dm-card-dark`     | translateY(-4px) + scale(1.012) + deep shadow |
+| `glow`     | `.dm-card-glow`     | ring glow expands + border brightens          |
+
+Utility: `.card-hover` (opt-in lift, no variant needed), `.card-collapsible` (header toggles body with `max-height`
+transition).
+
+**Collapsible wiring:** When `collapsible="true"` is parsed, `processCardBlocks` adds `.card-collapsible` to the root
+element and `data-collapsible="true"`. `site.js` delegates a click handler on `.card-collapsible .card-header` that
+toggles `.is-collapsed` on the root. `.is-collapsed .card-body` has `max-height: 0; overflow: hidden` with a CSS
+transition. The header receives a CSS-only chevron via `::after` that rotates on `.is-collapsed`.
+
+---
+
+## 14 Gradient Presets
+
+Applied via `gradient="name"` when `variant="gradient"`. Also controls the coloured element in `badge-band` (the top
+band), `pricing` (the header), `step-numbered` (the background strip), and `split-half` (the left half) - all Tier 1
+layouts. The `gradient` attribute is ignored on all other layouts.
+
+| Name       | Stops                           |
+|------------|---------------------------------|
+| `indigo`   | `#6366f1 → #8b5cf6` (default)   |
+| `ocean`    | `#0891b2 → #2563eb`             |
+| `sunset`   | `#f59e0b → #ef4444 → #ec4899`   |
+| `forest`   | `#10b981 → #0d9488`             |
+| `rose`     | `#fb7185 → #e11d48`             |
+| `midnight` | `#1e1b4b → #4338ca`             |
+| `aurora`   | `#06b6d4 → #6366f1 → #a855f7`   |
+| `fire`     | `#ef4444 → #f97316 → #fbbf24`   |
+| `lagoon`   | `#06b6d4 → #0e7490`             |
+| `dusk`     | `#7c3aed → #db2777`             |
+| `lime`     | `#84cc16 → #10b981`             |
+| `gold`     | `#f59e0b → #b45309`             |
+| `arctic`   | `#bae6fd → #e0f2fe` (dark text) |
+| `slate`    | `#475569 → #1e293b`             |
+
+---
+
+## Card Builder Dialog (card-builder.js)
+
+### Structure
+
+- **Left panel (280px):** Layout dropdown (grouped, with thumbnail previews) → Style swatches → dynamic fields (change
+  per layout) → Options row (Collapsible / Hover toggles)
+- **Right panel (flex):** Live preview card → Shortcode output box
+- **Footer:** Status line (layout + style) + Cancel / Insert Card buttons
+
+### Dynamic fields per layout tier
+
+- **All layouts:** Title, Body textarea
+- **Icon layouts:** Icon input + Browse Icons button (opens icon picker overlay) + icon-layout toggle
+- **Image layouts:** Image URL + Browse Media button (opens existing media modal)
+- **Tier 2 layouts:** Structured field set appropriate to the layout (e.g., price + period fields for pricing; step
+  number for step-numbered)
+- **Gradient variant:** Circle swatch picker (14 presets) appears below style swatches
+- **Glass variant:** Warning note - "Glass looks best inside a coloured [hero] or [card] section."
+
+### Icon picker
+
+Overlay panel with search input + grid of all Domma icons. Click to select → populates icon field + closes overlay.
+Confirm button shows selected icon name.
+
+### Media browser
+
+`CardBuilder` accepts an optional `onMediaBrowse` callback in its options object:
+`CardBuilder.open(textarea, { onMediaBrowse })`. `page-editor.js` provides this callback, which opens the existing media
+picker modal and resolves with the selected URL. This keeps `card-builder.js` decoupled from the media system.
+
+### Live preview
+
+The builder ships a lightweight **client-side preview renderer** (inline in `card-builder.js`). It builds DOM nodes
+directly using `document.createElement` and the same CSS classes that `processCardBlocks` outputs (e.g. `.card`,
+`.dm-card-gradient`, `.card-header`, `.card-body`). It does **not** call any API endpoint. For Tier 2 layouts the
+preview renders a simplified representative structure - e.g. pricing shows a static two-feature list rather than parsing
+`[feature]` sub-tags. This is clearly labelled in the preview panel as "Simplified preview - full render on save."
+
+### Shortcode generator
+
+Builds the shortcode string from current state. Displayed in the snippet box and used on Insert.
+
+---
+
+## CSS (site.css)
+
+### New rules added
+
+- `.dm-card-{variant}` - 6 variant base + hover rules
+- `.card-gradient-{name}` - 14 gradient classes (used on header/band elements)
+- `.card-layout-{key}` - structural CSS for layouts that need it (flex, grid, image sizing)
+- `.card-img-top`, `.card-img-left`, `.card-img-right` - image containers using `background-image` + `cover`
+- Responsive: side-image layouts stack at `480px`
+- Dark variant + image: auto dark scrim overlay on image containers
+
+### toolbar.onCard() integration
+
+`markdown-toolbar.js` already exposes `toolbar.onCard(cb)` - when the Card button is clicked, it calls `cb(textarea)` if
+registered, otherwise falls back to a dumb snippet insert. In `page-editor.js` `onMount`, after the toolbar is
+initialised:
+
+```js
+toolbar.onCard((ta) => {
+  CardBuilder.open(ta, {
+    onMediaBrowse: () => openMediaPicker(), // returns Promise<url>
+  });
+});
+```
+
+`CardBuilder.open(textarea, options)` is the sole public API of `card-builder.js`. It opens the dialog, and on Insert
+calls:
+
+```js
+const snippet = buildShortcode(state);
+const start = textarea.selectionStart;
+textarea.value = textarea.value.slice(0, start) + snippet + textarea.value.slice(textarea.selectionEnd);
+textarea.dispatchEvent(new Event('input', { bubbles: true }));
+textarea.focus();
+```
+
+### Backwards compatibility
+
+All existing shortcodes continue to work unchanged. `processCardBlocks` checks for `layout` attribute; if absent, falls
+back to the existing rendering path.
+
+---
+
+## Image handling
+
+- All image containers use `background-image: url(...)` + `background-size: cover` + `background-position: center`
+- Fallback when no image provided: themed gradient placeholder matching current variant
+- Side-image layouts (`thumb-left`, `thumb-right`, `wide-left-image`, `split-half`) stack vertically at `≤480px`
+
+---
+
+## Shortcode Examples
+
+```markdown
+[card layout="image-top" title="Getting Started" image="/media/hero.jpg"
+      variant="gradient" gradient="ocean" hover footer="5 min read"]
+A short description below the image.
+[/card]
+
+[card layout="pricing" title="Pro" price="£29" period="per month"
+      variant="gradient" gradient="indigo"]
+[feature]Unlimited pages[/feature]
+[feature]All plugins[/feature]
+[feature]Priority support[/feature]
+[/card]
+
+[card layout="callout" callout-type="info" icon="bulb" title="Good to know"]
+This tip will save you time.
+[/card]
+
+[card layout="stat-metric" title="Monthly Revenue" value="£24,980"
+      delta="↑ 12.4%" variant="clean" hover]
+[/card]
+
+[card layout="before-after" title="Why switch?"]
+[before]Manual updates · No versioning · Dev dependency[/before]
+[after]Auto deploy · Full history · Editors own it[/after]
+[/card]
+```