@rmdes/indiekit-endpoint-site-config 1.0.0-alpha.3 → 1.0.0-alpha.7

package/README.md

@@ -1,9 +1,95 @@
 # @rmdes/indiekit-endpoint-site-config
 
-Site identity, branding, layout, and feature flag configuration plugin for Indiekit.
+Site identity, branding, layout, and feature-flag configuration endpoint for [Indiekit](https://getindiekit.com).
 
-Documentation lives in `documentation-central/docs/site-config-plugin.md` in the workspace.
+Provides an admin UI for configuring a multi-tenant Indiekit deployment from a single canonical theme. Runtime CSS generation lets operators customize colors, typography, and layout without redeploying the theme.
+
+## Status
+
+`1.0.0-alpha.7` — usable, in production on [rmendes.net](https://rmendes.net). API may still shift before `1.0.0`.
+
+## Features
+
+- **12-control admin UI** for site theming (palette presets, semantic role overrides, mode preference)
+- **Runtime CSS generation** — writes `theme.css` and `critical.css` to disk on each save; Eleventy picks them up via `inlineFile` filter on next rebuild
+- **APCA Lc contrast validation** — blocks saves with unreadable color combinations (Lc < 30 hard, < 45 warn)
+- **Version history** — last 10 saves snapshot to MongoDB; one-click revert
+- **Reset per-section + global** — undo any subsection or all branding back to defaults
+- **Live preview iframe** — pending form state previewed before save via query-param-driven endpoint
+- **Mode-aware preview toggle** — preview light or dark mode independently of OS preference
+
+## Architecture — 3-Tier Token System
+
+| Tier | What | Examples |
+|------|------|----------|
+| **1. Reference (palette)** | Derived OKLCH-based color scales | `--c-surface-50..950`, `--c-accent-50..950` |
+| **2. Semantic (roles)** | What templates actually USE | `--c-bg`, `--c-fg`, `--c-fg-muted`, `--c-heading`, `--c-link`, `--c-action`, `--c-action-fg`, `--c-surface`, `--c-border`, `--c-focus` |
+| **3. Alert states** | Fixed for accessibility | `--c-success`, `--c-warning`, `--c-danger` (with `-fg` variants) |
+
+Templates reference Tier 2 utility classes (`text-heading`, `bg-action`, `border-border`, etc.). When the admin saves a role override, only that semantic token changes — every template element bound to that role updates within one Eleventy rebuild cycle.
+
+This mirrors the established CMS pattern documented by [WordPress theme.json](https://developer.wordpress.org/themes/global-settings-and-styles/), [Material Design 3](https://m3.material.io/styles/color/system/overview), and [W3C Design Tokens Community Group](https://design-tokens.github.io/community-group/format/).
+
+## Installation
+
+```bash
+npm install @rmdes/indiekit-endpoint-site-config
+```
+
+## Configuration
+
+In your `indiekit.config.js`:
+
+```js
+import SiteConfigEndpoint from "@rmdes/indiekit-endpoint-site-config";
+
+export default {
+  plugins: [
+    new SiteConfigEndpoint({
+      mountPath: "/site-config",  // default
+    }),
+    // ... other plugins
+  ],
+};
+```
+
+## Storage
+
+- MongoDB collection: `siteConfig`
+- Document `_id`: `"primary"` (singleton per deployment)
+- Schema version: `2` (Path D, Phase 2a+)
+
+## Theme integration
+
+The companion Eleventy theme [`indiekit-eleventy-theme`](https://github.com/rmdes/indiekit-eleventy-theme) reads:
+- `/app/data/content/_data/theme.css` (runtime CSS vars, via `inlineFile` filter in a `theme.css.njk` template)
+- `/app/data/content/_data/critical.css` (per-site critical CSS for first paint)
+- `/app/data/content/_data/site-config.json` (structured config for `_data/site.js`)
+
+The theme's `tailwind.config.js` exposes Tier 2 utility classes (`text-heading`, `bg-action`, `border-border`, etc.) bound to the CSS variables this plugin emits.
+
+## Mode handling
+
+Three states: `light`, `dark`, `auto`. In `auto` mode the plugin emits both `@media (prefers-color-scheme: dark)` AND a `.dark` class block, with the `@media` rule scoped to `:root:not(.light)` so an explicit user override (via JS toggle adding `.light`) wins over OS preference.
+
+## Testing
+
+```bash
+npm test
+```
+
+Currently 159 tests covering schema, storage, palette derivation, semantic resolution, contrast validation, history snapshotting, reset paths, and form parsing.
 
 ## Dependencies
 
-- `culori` — used for OKLCH-based palette derivation (see `lib/render/derive-palette.js`, added in a later task).
+- `apca-w3` + `colorparsley` — APCA Lc contrast calculation
+- `culori` — OKLCH palette derivation
+- `@indiekit/error`, `@indiekit/frontend`, `express@^5`
+
+## Development
+
+This plugin is developed inside the [Indiekit development workspace](https://github.com/rmdes/indiekit-dev). The design spec lives at `documentation-central/plans/2026-05-24-theming-v2-design.md` in that workspace.
+
+## License
+
+MIT

package/index.js

@@ -10,6 +10,7 @@ import { apiRouter } from "./lib/controllers/api.js";
 import { getSiteConfig } from "./lib/storage/get-site-config.js";
 import { maybeSeedFromEnv } from "./lib/storage/seed-from-env.js";
 import { writeThemeCss } from "./lib/render/write-theme-css.js";
+import { writeCriticalCss } from "./lib/render/write-critical-css.js";
 import { writeSiteJson } from "./lib/render/write-site-json.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -69,6 +70,7 @@ export default class SiteConfigEndpoint {
       await maybeSeedFromEnv(Indiekit);
       const config = await getSiteConfig(Indiekit);
       await writeThemeCss(config);
+      await writeCriticalCss(config);
       await writeSiteJson(config);
     } catch (error) {
       console.warn("[site-config] initial render skipped:", error.message);

package/lib/controllers/api.js

@@ -1,43 +1,325 @@
 import express from "express";
-import { getSiteConfig } from "../storage/get-site-config.js";
+import { getSiteConfig, mergeWithDefaults } from "../storage/get-site-config.js";
 import { renderThemeCss } from "../render/write-theme-css.js";
+import { parseBrandingForm } from "./branding.js";
+import { validateBranding } from "../validators/contrast.js";
 
 export function apiRouter(Indiekit) {
   const router = express.Router();
 
+  /**
+   * GET /site-config/api/preview
+   *
+   * Renders a live preview of a theme — either the persisted state (when no
+   * query params are present) or a pending state derived from query params.
+   *
+   * The branding form's color pickers submit `input` events to the iframe
+   * (debounced ~200ms) and re-set the iframe's src with a serialized form
+   * snapshot. This endpoint runs the same parser the POST handler uses —
+   * with `skipContrastCheck: true` so a low-contrast color choice can
+   * still be PREVIEWED, only blocked from being SAVED.
+   *
+   * Query params (all optional):
+   *   surfacePreset            — Tier 1 input
+   *   accentBase               — Tier 1 input (hex)
+   *   accentPreset             — metadata
+   *   mode                     — light | dark | auto
+   *   surfaceCustom_<tone>     — when surfacePreset=custom
+   *   roles_<role>_inherit=1   — inherit palette default
+   *   roles_<role>_light/dark  — override (both required if neither inherit)
+   *   typography_sans/serif/mono/hosting
+   *   previewMode              — light | dark | auto (overrides mode for preview only)
+   *
+   * The endpoint always returns 200 with HTML; for invalid inputs (e.g. bad
+   * accent hex), it falls back to the persisted state with a warning banner
+   * so the user can SEE the broken state and recover from it.
+   */
   router.get("/preview", async (req, res, next) => {
     try {
-      const config = await getSiteConfig(Indiekit);
-      const themeCss = renderThemeCss(config);
+      const persisted = await getSiteConfig(Indiekit);
+      const hasQuery = req.query && Object.keys(req.query).length > 0;
+
+      let configForPreview = persisted;
+      let parseError = null;
+      let contrastResults = [];
+
+      if (hasQuery) {
+        // Bridge multipart-friendly query params to the urlencoded shape
+        // parseBrandingForm expects. Express already gives us a plain
+        // object via req.query — Object.entries casts arrays to strings
+        // when a key appears more than once (we ignore that edge case).
+        const parsed = parseBrandingForm(
+          req.query,
+          persisted.branding?.roles || {},
+          { skipContrastCheck: true },
+        );
+
+        if (parsed.ok) {
+          // Build a synthetic full config: take the persisted state and
+          // overlay the pending branding subtree. mergeWithDefaults guards
+          // against missing keys.
+          configForPreview = mergeWithDefaults({
+            ...persisted,
+            branding: {
+              ...persisted.branding,
+              ...parsed.patch.branding,
+            },
+          });
+        } else {
+          parseError = parsed.message;
+        }
+      }
+
+      // Per-mode preview override: the iframe's light/dark toggle button
+      // sets `previewMode` independent of the persisted mode setting.
+      const previewMode =
+        typeof req.query.previewMode === "string" &&
+        ["light", "dark", "auto"].includes(req.query.previewMode)
+          ? req.query.previewMode
+          : configForPreview.branding.mode;
+
+      // We render theme.css with the pending mode so the preview iframe
+      // shows colors for the chosen side without needing JS to flip
+      // .dark on the iframe (which works too — both paths are wired).
+      const themeConfig = {
+        ...configForPreview,
+        branding: { ...configForPreview.branding, mode: previewMode },
+      };
+
+      // Run contrast check on the preview's resolved state so the iframe
+      // can show whether the visible colors are passing. Wrapped in try
+      // so a broken accentBase doesn't blow up the preview.
+      try {
+        contrastResults = validateBranding(configForPreview.branding);
+      } catch {
+        contrastResults = [];
+      }
+
+      const themeCss = renderThemeCss(themeConfig);
       res.setHeader("Content-Type", "text/html");
       res.setHeader("X-Content-Type-Options", "nosniff");
       res.setHeader("Cache-Control", "no-store");
-      res.send(`<!doctype html>
-<html lang="${escapeHtml(config.identity.locale || "en")}">
+      res.send(renderPreviewHtml({
+        themeCss,
+        config: configForPreview,
+        previewMode,
+        parseError,
+        contrastResults,
+      }));
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  return router;
+}
+
+/**
+ * Render the preview HTML body. Includes a comprehensive sample of theme
+ * elements (heading, body text, link, action button, card, focus state,
+ * alert pills) so users see how each token affects real surfaces.
+ *
+ * The light/dark mode toggle is a vanilla `<button>` with inline JS that
+ * adds/removes a `.dark` class on the document element AND persists the
+ * choice in localStorage. The persisted choice is read on load and
+ * applied to the html element.
+ *
+ * Exported for unit testing.
+ */
+export function renderPreviewHtml({ themeCss, config, previewMode, parseError, contrastResults }) {
+  const locale = config.identity?.locale || "en";
+  const siteName = config.identity?.name || "Untitled site";
+  const tagline = config.identity?.tagline || "";
+  const description = config.identity?.description || "Sample description for the preview.";
+
+  const failures = (contrastResults || []).filter((r) => r.status === "fail");
+  const warnings = (contrastResults || []).filter((r) => r.status === "warn");
+
+  // The button toggles `.dark` on <html> regardless of preview mode so
+  // operators can flip between sides without re-saving.
+  return `<!doctype html>
+<html lang="${escapeHtml(locale)}">
 <head>
   <meta charset="utf-8">
   <title>Preview</title>
   <style>
 ${themeCss}
-    body { font-family: var(--font-sans); background: rgb(var(--c-surface-50)); color: rgb(var(--c-surface-900)); margin: 0; padding: 1.5rem; }
-    h1 { font-family: var(--font-serif); color: rgb(var(--c-primary)); margin: 0 0 0.5em; font-size: 1.5em; }
-    p { color: rgb(var(--c-surface-700)); line-height: 1.5; margin: 0 0 1em; }
-    .button { background: rgb(var(--c-accent-500)); color: rgb(var(--c-surface-50)); padding: 0.4em 0.8em; border-radius: 0.4em; display: inline-block; font-weight: 600; }
-    a { color: rgb(var(--c-link)); }
+    html, body { margin: 0; padding: 0; }
+    body {
+      font-family: var(--font-sans);
+      background: rgb(var(--c-bg));
+      color: rgb(var(--c-fg));
+      padding: 1.5rem;
+      min-height: 100vh;
+    }
+    h1, h2, h3 { font-family: var(--font-serif); color: rgb(var(--c-heading)); margin: 0 0 0.5rem; }
+    h1 { font-size: 1.75rem; }
+    h2 { font-size: 1.25rem; margin-top: 1.5rem; }
+    h3 { font-size: 1rem; }
+    p  { line-height: 1.6; margin: 0 0 0.75rem; color: rgb(var(--c-fg)); }
+    .muted { color: rgb(var(--c-fg-muted)); font-size: 0.875rem; }
+    a { color: rgb(var(--c-link)); text-decoration: underline; }
+    .button {
+      background: rgb(var(--c-action));
+      color: rgb(var(--c-action-fg));
+      padding: 0.5rem 1rem;
+      border-radius: 0.4rem;
+      display: inline-block;
+      font-weight: 600;
+      border: none;
+      cursor: pointer;
+    }
+    .button:focus {
+      outline: 2px solid rgb(var(--c-focus));
+      outline-offset: 2px;
+    }
+    .card {
+      background: rgb(var(--c-surface));
+      border: 1px solid rgb(var(--c-border));
+      border-radius: 0.5rem;
+      padding: 1rem;
+      margin-block: 1rem;
+    }
+    code {
+      font-family: var(--font-mono);
+      background: rgb(var(--c-surface));
+      padding: 0.1em 0.3em;
+      border-radius: 0.2em;
+      border: 1px solid rgb(var(--c-border));
+    }
+    .pills { display: flex; gap: 0.5rem; flex-wrap: wrap; margin-block: 0.75rem; }
+    .pill {
+      display: inline-block;
+      padding: 0.25rem 0.6rem;
+      border-radius: 999px;
+      font-size: 0.75rem;
+      font-weight: 600;
+    }
+    .pill--success { background: rgb(var(--c-success)); color: rgb(var(--c-success-fg)); }
+    .pill--warning { background: rgb(var(--c-warning)); color: rgb(var(--c-warning-fg)); }
+    .pill--danger  { background: rgb(var(--c-danger));  color: rgb(var(--c-danger-fg)); }
+
+    .pv-toolbar {
+      position: sticky;
+      top: 0;
+      display: flex;
+      gap: 0.5rem;
+      align-items: center;
+      padding: 0.5rem 0.75rem;
+      margin: -1.5rem -1.5rem 1rem;
+      background: rgb(var(--c-surface));
+      border-bottom: 1px solid rgb(var(--c-border));
+      font-size: 0.75rem;
+    }
+    .pv-toggle {
+      background: transparent;
+      color: rgb(var(--c-fg));
+      border: 1px solid rgb(var(--c-border));
+      padding: 0.25rem 0.6rem;
+      border-radius: 0.25rem;
+      cursor: pointer;
+      font: inherit;
+    }
+    .pv-toggle--active {
+      background: rgb(var(--c-action));
+      color: rgb(var(--c-action-fg));
+      border-color: rgb(var(--c-action));
+    }
+    .pv-note { color: rgb(var(--c-fg-muted)); margin-left: auto; }
+    .pv-error {
+      background: rgb(var(--c-danger));
+      color: rgb(var(--c-danger-fg));
+      padding: 0.5rem 0.75rem;
+      border-radius: 0.25rem;
+      margin-block-end: 1rem;
+      font-size: 0.875rem;
+    }
+    .pv-warn {
+      background: rgb(var(--c-warning));
+      color: rgb(var(--c-warning-fg));
+      padding: 0.5rem 0.75rem;
+      border-radius: 0.25rem;
+      margin-block-end: 1rem;
+      font-size: 0.875rem;
+    }
+    .pv-fail {
+      background: rgb(var(--c-danger));
+      color: rgb(var(--c-danger-fg));
+      padding: 0.5rem 0.75rem;
+      border-radius: 0.25rem;
+      margin-block-end: 1rem;
+      font-size: 0.875rem;
+    }
   </style>
 </head>
 <body>
-  <h1>${escapeHtml(config.identity.name || "Untitled site")}</h1>
-  <p>${escapeHtml(config.identity.description || "Sample description")}</p>
-  <p><a href="#">A sample link</a> and <span class="button">an action button</span>.</p>
-</body>
-</html>`);
-    } catch (error) {
-      next(error);
-    }
-  });
+  <div class="pv-toolbar">
+    <button type="button" class="pv-toggle" data-pv-mode="light">Light</button>
+    <button type="button" class="pv-toggle" data-pv-mode="dark">Dark</button>
+    <span class="pv-note">Mode: ${escapeHtml(previewMode)}</span>
+  </div>
 
-  return router;
+  ${parseError ? `<div class="pv-error">Preview parse error: ${escapeHtml(parseError)}</div>` : ""}
+  ${failures.length > 0 ? `<div class="pv-fail">Contrast fails: ${escapeHtml(failures.map((f) => f.message).join("; "))}</div>` : ""}
+  ${warnings.length > 0 ? `<div class="pv-warn">Contrast warnings: ${escapeHtml(warnings.map((w) => w.message).join("; "))}</div>` : ""}
+
+  <h1>${escapeHtml(siteName)}</h1>
+  ${tagline ? `<p class="muted">${escapeHtml(tagline)}</p>` : ""}
+  <p>${escapeHtml(description)}</p>
+
+  <p>This paragraph contains <a href="#">a sample link</a> and some <code>inline code</code> alongside <span class="muted">muted secondary text</span>.</p>
+
+  <h2>Card surface</h2>
+  <div class="card">
+    <h3>Card heading</h3>
+    <p>Cards use the <code>surface</code> role for their background and <code>border</code> for the outline. Body text inside cards inherits the page foreground color.</p>
+    <button class="button" type="button">Primary action</button>
+  </div>
+
+  <h2>Alert tokens</h2>
+  <p class="muted">Fixed Tier 3 colors — not user-configurable.</p>
+  <div class="pills">
+    <span class="pill pill--success">Success</span>
+    <span class="pill pill--warning">Warning</span>
+    <span class="pill pill--danger">Danger</span>
+  </div>
+
+  <h2>Focus ring</h2>
+  <p class="muted">Tab to the button below to see the focus outline.</p>
+  <p><button class="button" type="button">Focusable</button></p>
+
+  <script>
+    (function () {
+      var KEY = 'sc.preview.mode';
+      var stored = null;
+      try { stored = localStorage.getItem(KEY); } catch (e) {}
+      var html = document.documentElement;
+      var buttons = document.querySelectorAll('[data-pv-mode]');
+
+      function apply(mode) {
+        if (mode === 'dark') html.classList.add('dark');
+        else html.classList.remove('dark');
+        buttons.forEach(function (b) {
+          var active = b.getAttribute('data-pv-mode') === mode;
+          b.classList.toggle('pv-toggle--active', active);
+        });
+      }
+
+      // Initial state: stored preference > URL-given previewMode > light
+      var initial = stored || ${JSON.stringify(previewMode === "dark" ? "dark" : "light")};
+      apply(initial);
+
+      buttons.forEach(function (btn) {
+        btn.addEventListener('click', function () {
+          var mode = btn.getAttribute('data-pv-mode');
+          try { localStorage.setItem(KEY, mode); } catch (e) {}
+          apply(mode);
+        });
+      });
+    })();
+  </script>
+</body>
+</html>`;
 }
 
 export function escapeHtml(s) {