domma-cms 1.6.60 → 1.7.0

package/docs/superpowers/specs/plans/2026-03-12-page-editor-form-insert-and-per-page-theme.md

@@ -0,0 +1,125 @@
+# Page Editor: Form Insert & Per-Page Theme - Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan.
+
+**Goal:** Add a Form shortcode to the page editor Insert dropdown (server-side inline-schema embed) and allow individual pages to override the global site theme via frontmatter.
+
+**Architecture:** Feature 1 upgrades the existing processFormBlocks() in markdown.js from a client-side slug reference to a server-side base64-encoded schema embed, adds a Form picker to the admin toolbar, and hydrates the embed in site.js. Feature 2 adds a theme frontmatter field read by renderer.js and a theme select in the page editor UI.
+
+**Tech Stack:** Node.js ESM (Fastify 5), Domma SPA (admin), vanilla JS (public site), gray-matter, marked, sanitize-html.
+
+**Spec:** docs/superpowers/specs/2026-03-12-page-editor-form-insert-and-per-page-theme-design.md
+
+---
+
+## Chunk 1: Form Insert Shortcode
+
+### Task 1: Upgrade processFormBlocks to server-side inline schema
+
+**Files:**
+- Modify: server/services/markdown.js (lines 1082-1095 and 1300)
+
+Context: processFormBlocks currently outputs a client-side div placeholder. We need it to read the form JSON from disk and embed the schema as base64 in the HTML, matching the dconfig pattern. readFile is already imported. FORMS_DIR is path.resolve(__dirname_md, '../../content/forms').
+
+- [ ] Step 1: Replace the entire processFormBlocks function (lines 1082-1095) with an async version that reads content/forms/{slug}.json, base64-encodes it via Buffer.from(JSON.stringify(form)).toString('base64'), and outputs: <div class="cms-form-embed" data-form-inline="{encoded}"></div>. On file-not-found, output an error placeholder div with the slug visible. Support optional title attribute to override form.title before encoding.
+
+- [ ] Step 2: On line 1300, add await before processFormBlocks(withIcon) since it is now async.
+
+- [ ] Step 3: Verify with curl - POST to /api/pages/preview with body {"markdown":"[form slug=\"to-do\" /]"} and confirm the response contains data-form-inline= with a base64 string.
+
+- [ ] Step 4: Commit: "feat: upgrade processFormBlocks to server-side inline schema embed"
+
+---
+
+### Task 2: Hydrate form embeds in site.js
+
+**Files:**
+- Modify: public/js/site.js (append after closing }()); of enhanceCollectionTables at line 412)
+
+Context: site.js uses IIFE patterns for progressive enhancement. F.render is the Domma form renderer. The decoded form object has slug, fields, settings. Submissions POST to /api/forms/submit/:slug.
+
+- [ ] Step 5: Append a hydrateFormEmbeds IIFE after enhanceCollectionTables. It should: find all [data-form-inline] elements; decode each with atob + JSON.parse; build a blueprint object from form.fields (same field mapping as the admin preview - type, label, required, placeholder, helper, options, spread formConfig); call F.render(el, blueprint, {}, { submitText, layout, columns, onSubmit }) where onSubmit POSTs to /api/forms/submit/{form.slug} with JSON body.
+
+- [ ] Step 6: Test in browser - add [form slug="to-do" /] to a published page, save, visit the public URL. Confirm the form renders and a submission creates a collection entry.
+
+- [ ] Step 7: Commit: "feat: hydrate cms-form-embed elements in site.js"
+
+---
+
+### Task 3: Add Form to the Insert dropdown
+
+**Files:**
+- Modify: admin/js/lib/markdown-toolbar.js
+
+Context: The toolbar has a handlers map and onXxx(cb) registration pattern. The collection action delegates to handlers.collection(ta). Add the same for form.
+
+- [ ] Step 8: Add {label: 'Form', icon: 'file-text', action: 'form'} to the Insert dropdown items array after CTA Button.
+
+- [ ] Step 9: Add form: null to the handlers object (line 662).
+
+- [ ] Step 10: Add an else-if branch for action === 'form' in executeAction (after the cta branch): call handlers.form(ta) if set, otherwise insert [form slug="" /] as a fallback.
+
+- [ ] Step 11: Add onForm(cb) { handlers.form = cb; } to the createToolbar return object after onCta.
+
+- [ ] Step 12: Commit: "feat: add Form entry to Insert dropdown in markdown toolbar"
+
+---
+
+### Task 4: Wire Form picker modal in page-editor.js
+
+**Files:**
+- Modify: admin/js/views/page-editor.js (after toolbar.onCollection callback)
+
+Context: The collection picker pattern (lines 969-1070): fetch list, build DOM wrapper, open E.modal with light DOM projection, insert shortcode on confirm. Follow identical pattern for forms - simpler as it only needs a select + insert button.
+
+- [ ] Step 13: Confirm insertAtCursor is in the import from markdown-toolbar.js at the top of the file. Add it if missing.
+
+- [ ] Step 14: Add toolbar.onForm(async (ta) => { ... }) after toolbar.onCollection closes. The callback should: fetch /forms via api.request('GET', '/forms'); build a div wrapper with a form select (one option per form: value=slug, text=title); add an Insert Form button; open E.modal({title: 'Insert Form', size: 'sm'}) and project the wrapper via modal.element.appendChild(wrapper); on Insert Form click, call insertAtCursor(ta, [form slug="{slug}" /]) and close the modal.
+
+- [ ] Step 15: Test: open page editor, click Insert > Form, confirm modal appears with form list, select and insert, confirm shortcode appears in editor.
+
+- [ ] Step 16: Commit: "feat: add form picker modal to page editor Insert dropdown"
+
+---
+
+## Chunk 2: Per-Page Theme
+
+### Task 5: Per-page theme in renderer.js
+
+**Files:**
+- Modify: server/services/renderer.js (line 75)
+
+Context: All page frontmatter fields are on the page object directly (page.title, page.layout, etc.). One-line change to the activeTheme assignment.
+
+- [ ] Step 17: Confirm frontmatter fields are top-level on page by reading renderer.js lines 39-55.
+
+- [ ] Step 18: Change line 75 from:
+  const activeTheme = site.theme || 'charcoal-dark';
+  to:
+  const activeTheme = page.theme || site.theme || 'charcoal-dark';
+
+- [ ] Step 19: Test - manually add "theme: ocean-dark" to a page's frontmatter file, then curl the public page URL and grep for dm-theme-ocean-dark.
+
+- [ ] Step 20: Commit: "feat: support per-page theme override via frontmatter"
+
+---
+
+### Task 6: Theme select in the page editor admin UI
+
+**Files:**
+- Modify: admin/js/templates/page-editor.html (after Visibility row at line 93)
+- Modify: admin/js/views/page-editor.js (populate on load, include in save)
+
+Context: Add a Theme Override select with a blank "Use site default" option plus all Domma themes. On save, omit the key when blank to keep frontmatter clean.
+
+- [ ] Step 21: In page-editor.html, insert a new row after the Category/Visibility row (line 93) with a select#field-theme. Options: blank "Use site default", then all themes: charcoal-dark/light, ocean-dark/light, forest-dark/light, sunset-dark/light, royal-dark/light, lemon-dark/light, silver-dark/light, grayve-dark/light. Include a small hint: "Overrides the site-wide theme for this page only."
+
+- [ ] Step 22: In page-editor.js in the if (page) populate block (around line 749), add:
+  $container.find('#field-theme').val(page.theme || '');
+
+- [ ] Step 23: In the frontmatter object (around line 1401), add conditional theme spread:
+  ...(($container.find('#field-theme').val()) ? {theme: $container.find('#field-theme').val()} : {}),
+
+- [ ] Step 24: Test full flow: select Ocean Dark in editor, save, visit public page, confirm ocean-dark theme applied. Reset to blank, save, confirm site default restores.
+
+- [ ] Step 25: Commit: "feat: add per-page theme override select to page editor"