domma-cms 1.6.60 → 1.7.1

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

@@ -0,0 +1,278 @@
+# Insert Builders - Tabs, Hero, Banner
+
+**Date:** 2026-04-06  
+**Status:** Approved  
+**Scope:** Admin page editor - Insert dropdown enhancements
+
+---
+
+## Overview
+
+Three improvements to the Page Editor Insert toolbar:
+
+1. **Tabs** - upgrade the existing basic modal to a richer, field-organised dialog with live shortcode preview
+2. **Hero** - wire up the currently dead `onHero` handler with a full-featured insert dialog
+3. **Banner** - new `[banner]` shortcode (server-side + CSS + insert dialog + toolbar item)
+
+A shared utility module (`shortcode-modal.js`) provides UI primitives for the new and upgraded handlers. Each of
+`onTabs` (upgraded), `onHero` (new), and `onBanner` (new) in `page-editor.js` will import from it. Note:
+`markdown-toolbar.js` also has its own duplicated helpers inside its action-handler closures (for text, timeline,
+etc.) - those are a separate concern and not in scope here.
+
+---
+
+## Architecture
+
+### Files
+
+| File                               | Change                                                             |
+|------------------------------------|--------------------------------------------------------------------|
+| `admin/js/lib/shortcode-modal.js`  | **New** - shared UI primitives                                     |
+| `admin/js/views/page-editor.js`    | Upgrade `onTabs`, add `onHero`, add `onBanner`                     |
+| `admin/js/lib/markdown-toolbar.js` | Add `banner` insert item, `onBanner` handler, `banner-insert` icon |
+| `server/services/markdown.js`      | Add `processBannerBlocks()`                                        |
+| `public/css/site.css`              | Add `.dm-banner` styles and type variants                          |
+
+### Shared utility: `shortcode-modal.js`
+
+Exports the following helpers. Imported by `page-editor.js` for the upgraded `onTabs` and new `onHero`/`onBanner`
+handlers:
+
+```js
+export function makeField(label, control)        // label + control wrapper div
+export function makeSelect(items)                // styled <select>
+export function makeTextInput(placeholder, val)  // styled <input type="text">
+export function makeCheckbox(label)              // styled checkbox row
+export function makeLivePreview()                // returns { el, update(str) }
+```
+
+`makeLivePreview()` returns a `<pre>` element that displays the current shortcode string and a helper `update(str)`
+function to refresh it. Wired to field `input`/`change` events in each handler.
+
+---
+
+## Section 1: Tabs Builder
+
+### Handler: `onTabs` in `page-editor.js`
+
+Replaces the existing basic handler. Opens an `E.modal({ title: 'Insert Tabs', size: 'sm' })`.
+
+### Fields
+
+| Field          | Control                            | Shortcode attribute                  |
+|----------------|------------------------------------|--------------------------------------|
+| Style          | Select: Default / Pills / Bordered | `style="pills"` / `style="bordered"` |
+| Alignment      | Select: Left / Centre / Right      | `align="center"` / `align="right"`   |
+| Animation      | Select: None / Fade                | `fade` (boolean flag)                |
+| Multiple open  | Checkbox                           | `multiple="true"`                    |
+| Tab list       | Dynamic rows (title + icon inputs) | `[tab title="..." icon="..."]`       |
+| Add Tab button | -                                  | max 10 tabs, min 2                   |
+| Live preview   | `<pre>` box                        | -                                    |
+
+### Tab rows
+
+Each tab row contains:
+
+- Text input: tab title (required, placeholder "Tab title")
+- Text input: icon name (optional, placeholder "icon (optional)")
+- Remove button (disabled when ≤2 tabs)
+
+Default state: 2 tabs pre-populated ("Overview", "Details").
+
+### Shortcode output
+
+```
+[tabs style="pills" align="center" fade]
+[tab title="Overview" icon="home"]Tab content here.[/tab]
+[tab title="Details"]Tab content here.[/tab]
+[/tabs]
+```
+
+Omit attributes that are default/empty (e.g. no `style` attribute if "Default" selected, no `icon` if blank).
+
+---
+
+## Section 2: Hero Builder
+
+### Handler: `onHero` in `page-editor.js`
+
+The toolbar item `{label: 'Hero', icon: 'hero', action: 'hero'}` **already exists** in the `markdown-toolbar.js` items
+array, and the dispatch `if (handlers.hero) handlers.hero(ta)` already exists in the action switch. What is missing is
+the handler registration in `page-editor.js` - so clicking Insert → Hero currently does nothing. This task adds only the
+`page-editor.js` handler; no changes to `markdown-toolbar.js` are required for Hero.
+
+Opens `E.modal({ title: 'Insert Hero', size: 'sm' })`.
+
+### Fields
+
+| Field        | Control                               | Shortcode attribute                 |
+|--------------|---------------------------------------|-------------------------------------|
+| Title        | Text input (required)                 | `title="..."`                       |
+| Tagline      | Text input (optional)                 | `tagline="..."`                     |
+| Size         | Select: Small / Medium / Large / Full | `size="sm/md/lg/full"`              |
+| Alignment    | Select: Left / Centre / Right         | `align="center"`                    |
+| Background   | Radio: None / Colour / Image          | -                                   |
+| → Colour     | Text input (hex/CSS)                  | `color="..."` - shown when Colour   |
+| → Image path | Text input                            | `image="..."` - shown when Image    |
+| → Overlay    | Select: None / Dark / Light           | `overlay="dark"` - shown when Image |
+| Min height   | Text input (optional, e.g. `400px`)   | `min-height="..."`                  |
+| Live preview | `<pre>` box                           | -                                   |
+
+The Background radio group conditionally shows/hides Colour and Image fields. When "None" is selected, both are hidden.
+
+### Shortcode output
+
+```
+[hero title="Our Story" tagline="Building something great" size="lg" align="center" image="/media/hero.jpg" overlay="dark"]
+Content here.
+[/hero]
+```
+
+Omit attributes that are default/empty.
+
+---
+
+## Section 3: Banner Shortcode
+
+### 3a. Server side - `markdown.js`
+
+Add `processBannerBlocks(content)` function. The existing pipeline order in `parseMarkdown` is:
+
+```
+processCollectionBlocks → processViewBlocks → processStaticBlocks
+→ processDConfigBlocks → processGridBlocks → processCardBlocks
+→ processSlideoverBlocks
+```
+
+Insert `processBannerBlocks` **after `processCardBlocks` and before `processSlideoverBlocks`** - this ensures banners
+render inside grid columns but can also sit inside a slideover body. Nesting banners inside card bodies is out of scope
+for the initial implementation (card body rendering would need a separate call to `processBannerBlocks` on the inner
+content).
+
+**Syntax:**
+
+```
+[banner type="info" title="Note" icon="info" dismissible]
+Read this message.
+[/banner]
+```
+
+**Attributes:**
+
+| Attribute     | Values                                                | Default |
+|---------------|-------------------------------------------------------|---------|
+| `type`        | `info` / `success` / `warning` / `danger` / `neutral` | `info`  |
+| `title`       | String                                                | -       |
+| `icon`        | Domma icon name                                       | -       |
+| `dismissible` | Boolean flag                                          | false   |
+| `class`       | Extra CSS class                                       | -       |
+
+**Rendered HTML:**
+
+```html
+<div class="dm-banner dm-banner--info [extra-class]">
+  <span class="dm-banner__icon" data-icon="info"></span>
+  <div class="dm-banner__body">
+    <strong class="dm-banner__title">Note</strong>
+    <p><!-- body content (Markdown parsed) --></p>
+  </div>
+  <button class="dm-banner__dismiss" aria-label="Dismiss">×</button>
+</div>
+```
+
+- `dm-banner__icon` omitted if no `icon` attribute
+- `dm-banner__title` omitted if no `title` attribute
+- `dm-banner__dismiss` omitted if `dismissible` not set
+
+### 3b. CSS - `public/css/site.css`
+
+Five type variants using Domma CSS custom properties. Base styles cover layout (flex row, aligned icon + body),
+border-left accent, padding, border-radius. Each `--info/success/warning/danger/neutral` variant sets background tint
+and accent colour.
+
+`.dm-banner` base style must include `position: relative` for the dismiss button's absolute positioning to work. Dismiss
+button: `position: absolute; top: 0.5rem; right: 0.5rem;` - hides banner on click via `site.js`.
+
+### 3c. Client dismiss handler - `public/js/site.js`
+
+Add event delegation for `.dm-banner__dismiss` clicks:
+
+```js
+$(document).on('click', '.dm-banner__dismiss', function() {
+  $(this).closest('.dm-banner').remove();
+});
+```
+
+Note: `.closest()` is a standard Domma (jQuery-compatible) method - confirmed available.
+
+### 3d. Toolbar - `markdown-toolbar.js`
+
+Three changes:
+
+1. **Register icon** - new `banner-insert` SVG (horizontal strip with lines, consistent with toolbar icon style)
+2. **Add insert item** to the items array (alphabetical order between `Accordion` and `Badge`):
+   ```js
+   {label: 'Banner', icon: 'banner-insert', action: 'banner'},
+   ```
+3. **Add dispatch** in the action switch:
+   ```js
+   } else if (action === 'banner') {
+     if (handlers.banner) handlers.banner(ta);
+   }
+   ```
+4. **Add `onBanner` to the returned handler chain and JSDoc**
+
+### 3e. Insert dialog - `onBanner` in `page-editor.js`
+
+Opens `E.modal({ title: 'Insert Banner', size: 'sm' })`.
+
+| Field        | Control                                                                                                                                                                               |
+|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Type         | Segmented button group (5 buttons, each with a coloured dot + label) - not a `<select>`, since `<option>` colour styling is browser-inconsistent. Active button gets `.active` class. |
+| Title        | Text input (optional)                                                                                                                                                                 |
+| Icon         | Text input (optional, Domma icon name)                                                                                                                                                |
+| Dismissible  | Checkbox                                                                                                                                                                              |
+| Live preview | `<pre>` box                                                                                                                                                                           |
+
+**Shortcode output:**
+
+```
+[banner type="success" title="All done" icon="check-circle" dismissible]
+Banner content here.
+[/banner]
+```
+
+---
+
+## Data Flow
+
+```
+User clicks Insert → Banner
+  → onBanner(ta) fires
+  → E.modal opens with fields
+  → fields change → live preview updates
+  → user clicks Insert Banner
+  → shortcode inserted at cursor in textarea
+  → preview re-renders via existing debounced preview call
+  → server processBannerBlocks() → HTML → CSS styles applied
+```
+
+---
+
+## Out of Scope
+
+- Layout management (separate spec)
+- Banner `action` link attribute (can be added in future)
+- Banner nested inside card bodies (requires `processBannerBlocks` call inside card body render)
+- Tabs per-tab body content editing within the dialog (user fills body content in the editor after insert)
+- Hero video background (future enhancement)
+
+## In Scope - Server-side Tabs Rendering
+
+The new `[tabs]` attributes (`style="bordered"`, `fade`, per-tab `icon`) must be rendered server-side or the insert
+dialog generates attributes the server silently ignores - a misleading UX. `markdown.js` `processTabsBlocks()` (or
+equivalent) must be updated to:
+
+- `style="bordered"` → add `tabs--bordered` class to wrapper
+- `fade` → add `tabs--fade` class to wrapper
+- Per-tab `icon` attribute → render `<span data-icon="...">` before tab title text in the tab button

package/docs/superpowers/specs/2026-04-06-layouts-design.md

@@ -0,0 +1,226 @@
+# Layout Presets - Design Spec
+
+## Goal
+
+Extend the existing layout preset system so presets control page width, background colour, background image, and custom
+CSS class - in addition to the existing navbar/footer/sidebar toggles. Add full CRUD in the admin UI (create, edit,
+delete), with three built-in presets (default, landing, blank) that can be edited but not deleted.
+
+---
+
+## Data Model
+
+Each layout preset is a keyed object stored in `config/presets.json` (via `getConfig('presets')` /
+`saveConfig('presets', data)`).
+
+**Full shape:**
+
+```json
+{
+  "default": {
+    "key": "default",
+    "label": "Default",
+    "description": "Standard page with navbar and footer.",
+    "builtin": true,
+    "navbar": true,
+    "footer": true,
+    "sidebar": false,
+    "width": "normal",
+    "bgColor": "",
+    "bgImage": "",
+    "class": ""
+  }
+}
+```
+
+**Fields:**
+
+| Field         | Type    | Description                                                                     |
+|---------------|---------|---------------------------------------------------------------------------------|
+| `key`         | string  | Unique identifier (slug). Auto-generated from label on create.                  |
+| `label`       | string  | Display name shown in the admin and the page editor dropdown.                   |
+| `description` | string  | Optional short description shown on the preset card.                            |
+| `builtin`     | boolean | If `true`, the preset cannot be deleted via the API.                            |
+| `navbar`      | boolean | Whether the public navbar renders on this layout.                               |
+| `footer`      | boolean | Whether the public footer renders on this layout.                               |
+| `sidebar`     | boolean | Whether a page sidebar region renders.                                          |
+| `width`       | string  | One of: `narrow`, `normal`, `wide`, `full`. Default: `normal`.                  |
+| `bgColor`     | string  | CSS colour value for the page background (e.g. `#f5f5f5`). Empty = no override. |
+| `bgImage`     | string  | URL for a background image. Empty = no override.                                |
+| `class`       | string  | Space-separated extra CSS classes added to `<body>`.                            |
+
+**Built-in presets** - seeded on server startup (see API section):
+
+| Key       | navbar | footer | sidebar | width  |
+|-----------|--------|--------|---------|--------|
+| `default` | true   | true   | false   | normal |
+| `landing` | true   | false  | false   | full   |
+| `blank`   | false  | false  | false   | normal |
+
+---
+
+## Server - API (`server/routes/api/layouts.js`)
+
+**Existing routes kept as-is:**
+
+- `GET /api/layouts` - returns all presets
+- `PUT /api/layouts` - bulk-saves presets
+- `GET /api/layouts/options` / `PUT /api/layouts/options` - spacer config (unchanged)
+
+**New routes:**
+
+| Method   | Path                | Purpose                                                                                                                                                |
+|----------|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `POST`   | `/api/layouts`      | Create a new preset. Validates: `label` required, `key` auto-generated (slugified from label), key must be unique, `builtin` always forced to `false`. |
+| `PUT`    | `/api/layouts/:key` | Update a single preset by key. All fields editable except `builtin`. Returns `404` if the key does not exist.                                          |
+| `DELETE` | `/api/layouts/:key` | Delete a preset. Returns `400` if `builtin: true`. Returns `404` if the key does not exist.                                                            |
+
+**Key collision on `POST`:** If the slugified label produces a key that already exists, return `409` with
+`{ error: 'A preset with this key already exists' }`. The client shows the error message in a toast and keeps the
+slideover open.
+
+**Validation rules:**
+
+- `width` must be one of `narrow | normal | wide | full` (default `normal` if missing/invalid).
+- `bgColor`: if non-empty, must match `/^[a-zA-Z0-9#(),.\s%/-]+$/`. This guard is intentionally permissive - it prevents
+  CSS injection, not invalid colour syntax.
+- `bgImage`: stored as-is (URL); renderer applies `url(...)` wrapper.
+- `class`: stripped of any characters outside `[a-zA-Z0-9\s_-]`.
+- `label`: max 60 chars.
+- `description`: max 200 chars.
+
+**Built-in preset seeding:** `config/presets.json` is committed to the repository with the three built-in presets as its
+initial content. On server startup (in `server/routes/api/layouts.js` route registration), a merge-in check runs: for
+each of the three built-in keys (`default`, `landing`, `blank`), if the key is absent from the loaded config, it is
+written in. This handles upgrades on existing installs without overwriting user edits. Do not duplicate this logic
+elsewhere. `config/presets.json` must not be gitignored.
+
+---
+
+## Server - Renderer (`server/services/renderer.js`)
+
+When assembling a public page, look up the page's `layout` frontmatter value against the presets config:
+
+```js
+const presets = getConfig('presets') || {};
+const preset = presets[page.layout] || presets['default'] || {};
+```
+
+Apply the preset to the rendered HTML:
+
+1. **Width class** - add `dm-layout-{width}` to `<body>` classlist (e.g. `dm-layout-normal`). If `width` is missing, use
+   `normal`.
+2. **Custom class** - append preset `class` string to `<body>` classlist.
+3. **Background colour** - if `bgColor` is non-empty, add `background-color:{bgColor}` to the inline style of the
+   `.page-body` wrapper element.
+4. **Background image** - if `bgImage` is non-empty, append
+   `background-image:url('{bgImage}');background-size:cover;background-position:center;` to the `.page-body` inline
+   style. Both `bgColor` and `bgImage` may be set simultaneously - the image renders over the colour as per normal CSS
+   stacking.
+5. **Navbar / footer** - existing mechanism (already controlled by preset); no change needed.
+
+The `data-layout="{{layout}}"` attribute on `<body>` is preserved as-is for CSS targeting.
+
+---
+
+## Public CSS (`public/css/site.css`)
+
+Four width utility classes controlling `.page-body` max-width:
+
+```css
+body.dm-layout-narrow .page-body {
+    max-width: 768px;
+}
+
+body.dm-layout-normal .page-body {
+    max-width: 1100px;
+}
+
+body.dm-layout-wide .page-body {
+    max-width: 1280px;
+}
+
+body.dm-layout-full .page-body {
+    max-width: none;
+}
+```
+
+All four are centred: `.page-body` already has `margin: 0 auto` (or this is added if missing).
+
+---
+
+## Admin UI (`admin/js/views/layouts.js`)
+
+### Preset Cards Grid
+
+Each card shows:
+
+- **Label** (bold) + builtin badge (`built-in`) if `builtin: true`
+- **Width** as a small pill (e.g. `normal`)
+- **Toggle indicators**: three small labelled dots or icons - Navbar / Footer / Sidebar - filled if enabled, muted if
+  not
+- **Background colour swatch** (small square) if `bgColor` is set
+- Click anywhere on the card → opens the edit slideover
+
+**Create button** - top-right of the grid section. Opens a blank edit slideover (all defaults).
+
+### Edit Slideover
+
+Opened via `E.slideover({ title: 'Edit Layout' / 'New Layout', size: 'md' })` using the light DOM slot pattern.
+
+**Form fields (top to bottom):**
+
+1. **Label** - text input (required)
+2. **Description** - text input (optional)
+3. **Width** - `<select>`: Narrow (768px) / Normal (1100px) / Wide (1280px) / Full
+4. **Navbar** - checkbox
+5. **Footer** - checkbox
+6. **Sidebar** - checkbox
+7. **Background Colour** - `<input type="color">` paired with a "Clear" button. When the current `bgColor` value is
+   `""`, the colour picker is disabled and visually greyed out; the label reads "None". The user must click "Choose" (or
+   interact with the picker) to enable it, which sets a default of `#ffffff`. Clicking "Clear" disables the picker again
+   and writes `""` back.
+8. **Background Image** - text input (URL). Empty string = no image.
+9. **Custom CSS Class** - text input. Empty string = no extra class.
+
+**Action buttons:**
+
+- **Save** - calls `POST /api/layouts` (create) or `PUT /api/layouts/:key` (update). On success: closes slideover,
+  refreshes card grid, shows success toast. On error: shows error toast with the server's message; slideover remains
+  open.
+- **Delete** (custom presets only, not shown for `builtin: true`) - `await E.confirm('Delete this layout?')` →
+  `DELETE /api/layouts/:key` → on success: closes slideover, removes card, shows success toast. On error: shows error
+  toast; slideover remains open.
+
+### Layout Options Tab
+
+The existing spacer config tab is unchanged.
+
+---
+
+## Page Editor Integration
+
+No changes required. The page editor already populates the layout dropdown from `api.layouts.get()` and saves `layout`
+to frontmatter. The new fields are transparent to the editor - they are applied server-side at render time.
+
+---
+
+## Files to Create / Modify
+
+| File                              | Change                                                                    |
+|-----------------------------------|---------------------------------------------------------------------------|
+| `config/presets.json`             | Update committed file to include new fields on all three built-in presets |
+| `server/routes/api/layouts.js`    | Add `POST`, `PUT /:key`, `DELETE /:key` routes; add field validation      |
+| `server/services/renderer.js`     | Look up preset, apply width class, custom class, bg styles to page output |
+| `admin/js/views/layouts.js`       | Full rebuild: CRUD cards + slideover edit form                            |
+| `admin/js/templates/layouts.html` | Update template if needed for new card structure                          |
+| `public/css/site.css`             | Add four `dm-layout-*` width utility classes                              |
+
+---
+
+## Out of Scope
+
+- Drag-to-reorder presets
+- Per-column or per-section width overrides
+- Background image upload (URL input only; media browser integration is a future enhancement)
+- Sidebar region implementation (toggle stored in preset but sidebar HTML is not in scope for this spec)