@threadlabs/looma 0.33.0 → 0.34.0

package/docs/catalog.mjs

@@ -0,0 +1,131 @@
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const catalogVersion = 1;
+export const escapeHtml = value => String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+export const titleOf = tag => tag.replace(/^ui-/, '').split('-').map(word => word[0].toUpperCase() + word.slice(1)).join(' ');
+export async function readJson(file, fallback) {
+  try { return JSON.parse(await readFile(file, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT' && fallback !== undefined) return fallback; throw error; }
+}
+
+/** Authored examples are data during discovery; controllers are never evaluated. */
+export async function readExamples(directory, componentId) {
+  let files;
+  try { files = (await readdir(directory)).sort(); } catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  return Promise.all(files.filter(file => /^[^.]+\.html$/.test(file)).map(async file => {
+    const name = file.slice(0, -5);
+    const source = await readFile(path.join(directory, file), 'utf8');
+    const meta = /^<!--\r?\n([\s\S]*?)\r?\n-->\s*/.exec(source);
+    if (!meta) throw new Error(`${path.join(directory, file)}: example requires title/description metadata.`);
+    const fields = Object.fromEntries(meta[1].split(/\r?\n/).map(line => {
+      const at = line.indexOf(':'); return at < 0 ? [] : [line.slice(0, at).trim(), line.slice(at + 1).trim()];
+    }).filter(pair => pair.length));
+    const frameworks = {};
+    for (const [target, extension, language] of [['html-next', '.snippet.html', 'html'], ['vue', '.vue', 'vue']]) {
+      if (files.includes(name + extension)) frameworks[target] = { language, code: await readFile(path.join(directory, name + extension), 'utf8') };
+    }
+    const behavior = files.includes(name + '.behavior.ts') ? path.join(directory, name + '.behavior.ts') : files.includes(name + '.behavior.js') ? path.join(directory, name + '.behavior.js') : undefined;
+    return { id: `${componentId}/${name}`, name, title: fields.title ?? name, description: fields.description ?? '', markup: source.slice(meta[0].length).trim(), resizable: fields.preview === 'resizable', bindings: fields.bind ?? '', frameworks, ...(behavior ? { behavior } : {}) };
+  }));
+}
+
+async function resources(directory) {
+  const result = [];
+  for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'examples') continue;
+    const file = path.join(directory, entry.name);
+    if (entry.isDirectory()) result.push(...await resources(file));
+    else if (entry.name.endsWith('.html')) result.push(file);
+  }
+  return result;
+}
+
+/** Discover only explicitly selected roots through HTML Next's public parser. */
+export async function discoverComponents({ root, directory, packageName, groups = [] }) {
+  if (!packageName || !directory) throw new Error('A discovery root requires packageName and directory.');
+  const { parseComponentResource, typeScriptType } = await import('@nextwebwg/html-next');
+  const components = [];
+  for (const source of await resources(path.resolve(root, directory))) {
+    const html = await readFile(source, 'utf8');
+    if (!/<template\b[^>]*\bcomponent=/.test(html)) continue;
+    const parsed = parseComponentResource(html, source);
+    const metadata = await readJson(path.join(path.dirname(source), 'docs.json'), {});
+    for (const definition of parsed.definitions) {
+      const contract = definition.contract;
+      const docs = metadata.components?.[contract.tag] ?? metadata;
+      const id = `${packageName}/${contract.tag}`;
+      const properties = Object.entries(contract.props).map(([name, prop]) => ({ name, type: typeScriptType(prop.type), description: prop.description ?? '', ...(Object.hasOwn(prop, 'default') ? { default: prop.default } : {}), ...(prop.values ? { options: prop.values } : {}) }));
+      const attributes = properties.map(prop => ({ ...prop, property: prop.name, name: prop.name.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`) }));
+      const events = (definition.declarations ?? []).filter(item => item.kind === 'event').map(event => ({ name: event.name, detailType: event.shape ? typeScriptType(event.shape) : String(event.type), detailDocs: docs.events?.[event.name] ?? '' }));
+      const slots = (definition.slots ?? []).map(slot => ({ name: slot.name ?? 'default', description: docs.slots?.[slot.name ?? 'default'] ?? '' }));
+      const tokens = [...new Set([...definition.css.matchAll(/var\(\s*(--[\w-]+)/g)].map(match => match[1]))].sort();
+      components.push({ id, package: packageName, tag: contract.tag, title: docs.title ?? titleOf(contract.tag), description: docs.description ?? contract.summary ?? '', group: docs.group ?? 'project', ...(docs.navigationParent ? { navigationParent: docs.navigationParent } : {}), root: contract.nativeElement, source, resource: source, targets: ['html-next'], attributes, properties, events, slots, designTokens: { sources: [path.relative(root, source)], component: [], shared: tokens.map(name => ({ name, fallbacks: [] })) }, examples: await readExamples(path.join(path.dirname(source), 'examples'), id) });
+    }
+  }
+  const categories = components.some(component => component.group === 'project') && !groups.some(group => group.id === 'project') ? [...groups, { id: 'project', label: 'Project components' }] : groups;
+  return { schemaVersion: catalogVersion, package: packageName, groups: categories, components };
+}
+
+/** Merge deterministically, reporting both owners instead of silently shadowing resources. */
+export function mergeCatalogs(catalogs, { categories = {} } = {}) {
+  const resourceByTag = new Map();
+  const exampleOwners = new Map();
+  const groups = new Map(); const byId = new Map(); const byTag = new Map();
+  for (const catalog of catalogs) {
+    if (catalog.schemaVersion !== catalogVersion) throw new Error(`Unsupported documentation catalog version ${catalog.schemaVersion} for ${catalog.package}.`);
+    for (const group of catalog.groups ?? []) {
+      const mapped = categories[group.id] ?? group.id;
+      if (typeof mapped !== 'string' || !/^[a-z][a-z0-9-]*$/.test(mapped)) throw new Error(`Invalid category identity ${JSON.stringify(mapped)} in ${catalog.package}.`);
+      const previous = groups.get(mapped);
+      if (previous && previous.label !== group.label && mapped === group.id) throw new Error(`Conflicting category ${mapped}: ${previous.label} and ${group.label}. Configure a category mapping explicitly.`);
+      if (!previous) groups.set(mapped, { ...group, id: mapped });
+    }
+    for (const entry of catalog.components) {
+      // HTML Next's public component-tag grammar also keeps generated filenames inside their tree.
+      if (typeof entry.tag !== 'string' || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/.test(entry.tag)) throw new Error(`Invalid component tag ${JSON.stringify(entry.tag)} in ${catalog.package}.`);
+      if (typeof entry.id !== 'string' || !entry.id) throw new Error(`Missing component identity for ${entry.tag} in ${catalog.package}.`);
+      const component = { ...entry, group: categories[entry.group] ?? entry.group };
+      const previous = byTag.get(component.tag) ?? byId.get(component.id);
+      if (previous) throw new Error(`Duplicate component ${component.tag}: ${previous.id} (${previous.source ?? previous.resource}) and ${component.id} (${component.source ?? component.resource}).`);
+      byId.set(component.id, component); byTag.set(component.tag, component);
+      if (!Array.isArray(component.examples)) throw new Error(`Component ${component.id} requires an examples array.`);
+      for (const example of component.examples) {
+        if (typeof example.id !== 'string' || !example.id || typeof example.markup !== 'string') throw new Error(`Invalid example identity or markup in ${component.id}.`);
+        if (!example.id.startsWith(component.id + '/')) throw new Error(`Example ${example.id} must belong to ${component.id}.`);
+        const previous = exampleOwners.get(example.id);
+        if (previous) throw new Error(`Duplicate example ${example.id}: ${previous} and ${component.id}.`);
+        exampleOwners.set(example.id, component.id);
+      }
+    }
+    for (const entry of [...catalog.resources ?? [], ...catalog.components]) {
+      const previous = resourceByTag.get(entry.tag);
+      if (previous && (previous.package !== entry.package || previous.resource !== entry.resource)) throw new Error(`Conflicting resource ${entry.tag}: ${previous.resource} and ${entry.resource}.`);
+      resourceByTag.set(entry.tag, { tag: entry.tag, package: entry.package, resource: entry.resource });
+    }
+  }
+  const ownerOf = (component, trail = []) => {
+    if (trail.includes(component.id)) throw new Error(`Compound parent cycle: ${[...trail, component.id].join(' → ')}.`);
+    if (!component.navigationParent) return component;
+    const parent = byId.get(component.navigationParent) ?? byTag.get(component.navigationParent);
+    if (!parent) throw new Error(`Missing compound parent ${component.navigationParent} for ${component.id}.`);
+    return ownerOf(parent, [...trail, component.id]);
+  };
+  for (const component of byId.values()) {
+    if (component.navigationParent) {
+      const owner = ownerOf(component);
+      component.navigationParent = owner.tag;
+      component.group = owner.group;
+    }
+    if (!groups.has(component.group)) throw new Error(`Unknown category ${component.group} for ${component.id}. Declare its category or map it to an existing one.`);
+  }
+  return { schemaVersion: catalogVersion, resources: [...resourceByTag.values()], groups: [...groups.values()], components: [...byId.values()].sort((a, b) => a.id.localeCompare(b.id)) };
+}
+
+/** Read a published catalog without importing the optional documentation server. */
+export async function readCatalog(specifier = new URL('./catalog.json', import.meta.url)) {
+  const catalog = await readJson(specifier instanceof URL ? fileURLToPath(specifier) : specifier);
+  if (catalog.schemaVersion !== catalogVersion) throw new Error(`Unsupported documentation catalog version ${catalog.schemaVersion}.`);
+  return catalog;
+}

package/docs/cli.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { initializeDocumentation, buildProjectDocumentation, devProjectDocumentation, previewProjectDocumentation } from './commands.mjs';
+
+try {
+  const { values, positionals } = parseArgs({ allowPositionals: true, options: { root: { type: 'string' }, port: { type: 'string' }, title: { type: 'string' }, help: { type: 'boolean', short: 'h' } } });
+  const [command = 'help'] = positionals;
+  if (values.help || command === 'help') {
+    console.log('looma-docs init | dev | build | preview\n\n  --root <project>  Project directory\n  --port <number>   Local server port (default 3000)\n  --title <name>    Documentation title for init\n\nInstall the optional documentation peers: markupress, @nextwebwg/htmlkit and vite.');
+  } else {
+    const options = { ...(values.root ? { root: values.root } : {}), ...(values.title ? { title: values.title } : {}) };
+    if (values.port) { const port = Number(values.port); if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Port must be an integer from 0 to 65535.'); options.port = port; }
+    if (command === 'init') {
+      const result = await initializeDocumentation(options);
+      console.log(`Created ${result.files.join(', ')}.\nImport ${result.applicationImport} after Looma styles in your application.\nRun looma-docs dev to weave your design system.`);
+    } else if (command === 'build') {
+      const built = await buildProjectDocumentation(options); console.log(`Built ${built.routes.length} documentation routes in ${built.outDir}.`);
+    } else if (command === 'dev' || command === 'preview') {
+      const server = await (command === 'dev' ? devProjectDocumentation : previewProjectDocumentation)(options);
+      console.log(server.url);
+      let closing = false;
+      const close = async () => { if (closing) return; closing = true; await server.close(); process.exitCode = 0; };
+      process.once('SIGINT', close); process.once('SIGTERM', close);
+    } else throw new Error(`Unknown documentation command ${command}. Use looma-docs --help.`);
+  }
+} catch (error) { console.error(error.message); process.exitCode = 1; }

package/docs/commands.mjs

@@ -0,0 +1,94 @@
+import { watch } from 'node:fs';
+import { lstat, open, readFile, realpath, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildDocumentation, tool } from './site.mjs';
+import { createThemeStore } from './store.mjs';
+import { serveLocalDocumentation } from './local-server.mjs';
+import { defaultRecipe, themeCSS } from './theme.mjs';
+
+export const configName = 'looma.docs.json';
+export async function readConfiguration(root = process.cwd()) {
+  root = await realpath(path.resolve(root));
+  try { return { root, config: JSON.parse(await readFile(path.join(root, configName), 'utf8')) }; }
+  catch (error) { if (error.code === 'ENOENT') throw new Error(`No ${configName} in this project. Run looma-docs init first.`); throw error; }
+}
+
+/** Initialization creates explicit owned files, leaving the application's imports to its author. */
+export async function initializeDocumentation({ root = process.cwd(), title = 'Your design system' } = {}) {
+  root = await realpath(path.resolve(root));
+  const config = { title, base: '/', outDir: '.looma/site', theme: { recipe: 'looma.theme.json', css: 'looma.theme.css' }, components: [] };
+  const recipe = defaultRecipe();
+  const system = await readFile(fileURLToPath(import.meta.resolve('@threadlabs/looma/theme-system.css')), 'utf8');
+  const files = new Map([[configName, JSON.stringify(config, null, 2) + '\n'], [config.theme.recipe, JSON.stringify(recipe, null, 2) + '\n'], [config.theme.css, themeCSS(recipe, system)]]);
+  for (const name of files.keys()) {
+    try { await lstat(path.join(root, name)); throw new Error(`${name} already exists. Initialization will not replace it.`); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  const created = [];
+  try {
+    for (const [name, source] of files) {
+      const file = path.join(root, name); const handle = await open(file, 'wx', 0o644); created.push(file);
+      try { await handle.writeFile(source); } finally { await handle.close(); }
+    }
+  } catch (error) { await Promise.all(created.map(file => unlink(file))); throw error; }
+  return { config, files: [...files.keys()], applicationImport: './' + config.theme.css };
+}
+
+async function themeConfiguration(root, config, local = false) {
+  if (!config.theme && !local) return config;
+  const store = await createThemeStore({ root, ...config.theme });
+  const current = await store.read({ includeCSS: true });
+  return { ...config, recipe: current.recipe, revision: current.revision, ...(current.css !== null ? { themeCSSContents: current.css } : {}), local };
+}
+export async function buildProjectDocumentation({ root = process.cwd(), config, catalog } = {}) {
+  if (!config) ({ root, config } = await readConfiguration(root));
+  return buildDocumentation({ root, config: await themeConfiguration(root, config), catalog });
+}
+export async function previewProjectDocumentation({ root = process.cwd(), config, port = 3000 } = {}) {
+  if (!config) ({ root, config } = await readConfiguration(root));
+  const { previewApplication } = await tool('@nextwebwg/htmlkit', root);
+  return previewApplication({ root, outDir: config.outDir ?? '.looma/site', base: config.base ?? '/', host: '127.0.0.1', port });
+}
+
+/** HTMLKit serves the build; this local-only gateway adds the constrained repository writer. */
+export async function devProjectDocumentation({ root = process.cwd(), config, catalog, port = 3000, onError = console.error } = {}) {
+  const configured = Boolean(config);
+  if (!config) ({ root, config } = await readConfiguration(root));
+  const store = await createThemeStore({ root, ...config.theme });
+  let closed = false, dirty = true, building, timer;
+  const rebuild = () => {
+    clearTimeout(timer);
+    if (building) return building;
+    building = (async () => {
+      while (dirty && !closed) {
+        dirty = false;
+        if (!configured) {
+          const next = (await readConfiguration(root)).config;
+          if (['base', 'outDir', 'theme'].some(key => JSON.stringify(next[key]) !== JSON.stringify(config[key]))) throw new Error('The server address, output or theme-file configuration changed. Restart looma-docs dev to use it.');
+          config = next;
+        }
+        await buildDocumentation({ root, config: await themeConfiguration(root, config, true), catalog });
+      }
+    })().finally(() => { building = undefined; });
+    return building;
+  };
+  await rebuild();
+  const upstream = await previewProjectDocumentation({ root, config, port: 0 });
+  let gateway;
+  try {
+    gateway = await serveLocalDocumentation({ upstream: upstream.url, store, base: config.base ?? '/', port, onSaved: async () => { dirty = true; await rebuild(); } });
+  } catch (error) { await upstream.close(); throw error; }
+  const watcher = watch(root, { recursive: true }, (_event, filename) => {
+    if (!filename || closed) return;
+    const relative = String(filename).split(path.sep).join('/');
+    if (relative.split('/').some(part => part === 'node_modules' || part === '.git' || part === '.looma')) return;
+    const output = config.outDir ?? '.looma/site';
+    if (relative === output || relative.startsWith(output + '/')) return;
+    const inputs = [configName, config.theme?.recipe ?? 'looma.theme.json', config.theme?.css ?? 'looma.theme.css', config.content, ...(config.components ?? []).map(entry => entry.directory), ...(config.overrides ?? [])].filter(Boolean).map(value => value.replace(/^\.\//, ''));
+    if (!inputs.some(input => relative === input || relative.startsWith(input + '/'))) return;
+    dirty = true;
+    clearTimeout(timer); timer = setTimeout(() => { void rebuild().catch(onError); }, 150);
+  });
+  return { url: gateway.url, close: async () => { closed = true; clearTimeout(timer); watcher.close(); await building?.catch(() => {}); await gateway.close(); await upstream.close(); } };
+}

package/docs/customizer-render.mjs

@@ -0,0 +1,66 @@
+import { escapeHtml as escape } from './catalog.mjs';
+import { componentPath, previewPath } from './render.mjs';
+import { valueEditor } from './value-editors.mjs';
+import { defaultRecipe, themeFields, startingPointLabels, startingPointFor, themeCSS, validateRecipe, themePalettes, paletteFor } from './theme.mjs';
+
+export function customizerResource(site, input = defaultRecipe()) {
+  const recipe = validateRecipe(input);
+  const cardFields = ['id', 'title', 'description', 'exampleTitle', 'src', 'resizable', 'category', 'tag', 'nativeRoot', 'href', 'packageName'];
+  const examples = site.catalog.components.flatMap(component => component.examples.map(example => ({ id: example.id, title: component.title, description: component.description, exampleTitle: example.title, src: site.base + previewPath(example).slice(1), resizable: Boolean(example.resizable), category: component.group, tag: component.tag, packageName: component.package, nativeRoot: component.root ? `<${component.root}>` : '', href: site.base + componentPath(component).slice(1) })));
+  const toCard = example => Object.fromEntries(cardFields.map(key => [key, example[key]]));
+  const initial = ['ui-button', 'ui-input', 'ui-color-picker', 'ui-checkbox', 'ui-card', 'ui-switch', 'ui-text', 'ui-dialog', 'ui-popover'].map(tag => examples.find(example => example.tag === tag && (tag !== 'ui-button' || example.id.endsWith('/02-variant')) && (tag !== 'ui-text' || example.id.endsWith('/02-variants')) && (tag !== 'ui-card' || example.id.endsWith('/04-glass'))) ?? examples.find(example => example.tag === tag)).filter(Boolean).map(toCard);
+  if (!initial.length && examples.length) initial.push(toCard(examples[0]));
+  const renderField = field => {
+    const value = recipe.values[field.id], editor = valueEditor(field, value);
+    const common = `size="sm" data-token="${field.id}" label="${escape(field.label)}"`;
+    let control;
+    if (field.type === 'easing') {
+      control = `<ui-input id="theme-${field.id}" size="sm" data-token="${field.id}" aria-label="${escape(field.label)}" value="${escape(value)}"></ui-input><div data-curve-for="${field.id}"${editor.kind === 'text' ? ' hidden' : ''}><ui-curve-editor ${common} data-editor-kind="curve" value="${escape(value)}"></ui-curve-editor></div>`;
+    } else if (editor.kind === 'number' || editor.kind === 'slider') {
+      const tag = editor.kind === 'slider' ? 'ui-slider' : 'ui-number-input';
+      const numeric = `<${tag} id="theme-${field.id}" ${common} data-editor-kind="${editor.kind}" value="${escape(editor.value)}" unit="${editor.unit}" min="${editor.min}" max="${editor.max}" step="${editor.step}"></${tag}>`;
+      control = editor.units ? `<ui-cluster wrap="nowrap" gap="xs">${numeric}<ui-select size="sm" style="--ui-select-inline-size: auto" data-unit-for="${field.id}" aria-label="${escape(field.label)} unit" value="${editor.unit}">${[...new Set([...editor.units, editor.unit])].map(unit => `<option value="${unit}">${unit}</option>`).join('')}</ui-select></ui-cluster>` : numeric;
+    } else {
+      control = `<ui-cluster wrap="nowrap" gap="xs">${field.type === 'colour' ? `<ui-color-picker size="sm" data-token="${field.id}" value="${escape(value)}" label="${escape(field.label)} colour picker"></ui-color-picker>` : ''}<ui-input id="theme-${field.id}" size="sm" data-token="${field.id}" value="${escape(value)}" aria-label="${escape(field.label)}"></ui-input></ui-cluster>`;
+    }
+    return `<ui-form-field><label slot="label" for="theme-${field.id}">${escape(field.label)}</label><span slot="help">${escape(field.description)}</span>${control}</ui-form-field>`;
+  };
+  const supplements = {
+    'Colour': `<ui-form-field><label slot="label" for="theme-palette">Coordinated palette</label><span slot="help">Choose related action, paper and ink colors together. Size, material and motion stay yours. Both light and dark ranges are generated.</span><ui-select id="theme-palette" size="sm" data-palette value="${paletteFor(recipe)}"><option value="custom" disabled>Your palette</option>${Object.entries(themePalettes).map(([id, palette]) => `<option value="${id}">${escape(palette.label)}</option>`).join('')}</ui-select></ui-form-field><ui-cluster>${['light', 'dark'].map(mode => `<ui-card data-theme="${mode}" padding="sm"><ui-text variant="label">${mode === 'light' ? 'Light' : 'Dark'} range</ui-text><div class="palette-range" role="img" aria-label="${mode} canvas, content and action range"><span class="palette-canvas"></span><span class="palette-content"></span><span class="palette-action"></span></div><ui-text variant="caption">Fellowship office</ui-text></ui-card>`).join('')}</ui-cluster><p data-palette-adjustments role="status" aria-live="polite"></p><ui-disclosure summary="Resolved palette values"><p data-palette-adjustment-details></p></ui-disclosure><ui-disclosure summary="Palette seeds"><ui-stack>${themeFields.filter(item => item.family === 'Colour').map(renderField).join('')}</ui-stack></ui-disclosure>`,
+    'Material': `<ui-disclosure summary="Material details"><ui-stack><p>Glassiness and surface separation coordinate the material. These controls preserve older recipes and offer finer adjustments.</p>${themeFields.filter(item => ['translucency', 'edge-light'].includes(item.id)).map(renderField).join('')}</ui-stack></ui-disclosure>`,
+    'Size & spacing': `<ui-cluster><ui-button size="sm">Small</ui-button><ui-button>Medium</ui-button><ui-button size="lg">Large</ui-button></ui-cluster><ui-disclosure summary="How the scale grows"><ui-stack><p>Control size anchors one shared height. Size ratio separates small from large. Density and spacing curve change breathing room independently.</p>${themeFields.filter(item => ['scale-contrast','space-curve'].includes(item.id)).map(renderField).join('')}</ui-stack></ui-disclosure>`,
+  };
+  const families = [...new Set(themeFields.map(field => field.family))].map(family => `<ui-disclosure summary="${family}"${family === 'Colour' ? ' open' : ''}><ui-stack>${themeFields.filter(item => item.family === family && !['scale-contrast', 'space-curve', 'translucency', 'edge-light'].includes(item.id) && family !== 'Colour').map(renderField).join('')}${supplements[family] ?? ''}</ui-stack></ui-disclosure>`).join('');
+  const options = site.catalog.groups.map(group => `<optgroup label="${escape(group.label)}">${examples.filter(example => example.category === group.id).map(example => `<option value="${escape(example.id)}" data-example="${escape(JSON.stringify(example))}" data-search="${escape(`${example.title} ${example.tag} ${example.description} ${example.exampleTitle}`.toLocaleLowerCase())}">${escape(example.title)} · ${escape(example.exampleTitle)}</option>`).join('')}</optgroup>`).join('');
+  const links = ['ui-stack','ui-grid','ui-cluster','ui-form-field','ui-input','ui-select','ui-color-picker','ui-button','ui-disclosure','ui-textarea','ui-number-input','ui-slider','ui-curve-editor','ui-card','ui-text'].map(tag => `<link rel="component" href="@threadlabs/looma/components/${tag}/${tag}.html">`).join('\n');
+  return `${links}\n<link rel="component" href="./card.html">\n<template component="looma-customizer" module="./customizer.js"><defs>
+  <state name="cards" type="list" value="${escape(JSON.stringify(initial))}"><prop type="object">${cardFields.map(name => `<prop name="${name}" required type="${name === 'resizable' ? 'boolean' : 'string'}"></prop>`).join('')}</prop></state>
+  </defs>
+  <div data-looma-customizer data-recipe="${escape(JSON.stringify(recipe))}" data-base="${escape(site.base)}" data-mode="${site.config.local ? 'local' : 'public'}" data-revision="${escape(site.config.revision ?? '')}">
+  <ui-stack gap="xl"><p>Shape your design system through shared decisions. These are the actual examples from the component documentation. Changes apply throughout your documentation and are remembered in this browser until reset. Save to repository writes the theme to your project; downloads let you use it elsewhere.</p>
+  <div class="customizer-layout">
+  <aside><ui-stack><ui-form-field><label slot="label" for="theme-start">Starting point</label><ui-select id="theme-start" data-preset value="${startingPointFor(recipe)}"><option value="custom" disabled>Your theme</option>${Object.entries(startingPointLabels).map(([id,label]) => `<option value="${id}">${label}</option>`).join('')}</ui-select></ui-form-field>
+  ${families}
+  <ui-cluster><ui-button data-action="css" variant="solid">Download CSS</ui-button><ui-button data-action="recipe">Download recipe</ui-button><ui-button data-action="import">Import recipe</ui-button><ui-button data-action="reset" variant="ghost">Reset changes</ui-button></ui-cluster>
+  <input type="file" accept="application/json,.json" hidden data-recipe-file>
+  <ui-button data-action="save" variant="solid" hidden>Save to repository</ui-button>
+  <ui-disclosure summary="Use your theme"><p>Every export includes light and dark. Leave data-theme off the page to follow system preference, or set it to light or dark on the page or a section. <a href="${escape(site.base)}design-system/">Installation and mode guidance</a></p></ui-disclosure>
+  <p role="status" aria-live="polite" data-message>Your theme is remembered in this browser. Repository files change only when you save.</p>
+  <ui-disclosure summary="Theme CSS"><ui-textarea data-css readonly rows="12" aria-label="Generated theme CSS" value="${escape(themeCSS(recipe))}"></ui-textarea></ui-disclosure>
+  </ui-stack></aside>
+  <section class="examples"><ui-stack><ui-form-field><label slot="label" for="example-query">Find components and examples</label><ui-input id="example-query" type="search" data-example-query placeholder="Name, tag or purpose"></ui-input></ui-form-field><p role="status" aria-live="polite" data-example-count></p><ui-form-field><label slot="label" for="example-choice">Add a documentation example</label><ui-select id="example-choice" data-add-example>${options}</ui-select></ui-form-field><ui-button data-action="add">Add example card</ui-button>
+  <ui-grid columns="2" min="sm"><section $each="card of $cards" $key="$card.id"><looma-example-card ${cardFields.filter(name => name !== 'id').map(name => `from:${name.replace(/[A-Z]/g, letter => '-' + letter.toLowerCase())}="$card.${name}"`).join(' ')} from:identity="$card.id" loading="eager" removable></looma-example-card></section></ui-grid>
+  <noscript>Enable JavaScript to edit the theme. The component reference and example previews remain available.</noscript>
+  </ui-stack></section></div></ui-stack></div>
+  <style>
+    .customizer-layout { display: grid !important; grid-template-columns: minmax(16rem, 20rem) minmax(0, 1fr); gap: var(--ui-space-6) !important; align-items: start !important; }
+    aside { position: sticky; inset-block-start: 5rem; max-block-size: calc(100dvh - 6rem); overflow: auto; padding-inline-end: var(--ui-space-2) !important; }
+    .examples { min-inline-size: 0; }
+    .palette-range { display: flex !important; min-block-size: var(--ui-control-size-sm); border: var(--ui-border-width) solid var(--ui-control-border); border-radius: var(--ui-radius-sm); overflow: hidden; }
+    .palette-range > span { flex: 1; min-inline-size: var(--ui-space-5); }
+    .palette-canvas { background: var(--ui-surface); }
+    .palette-content { background: var(--ui-surface-raised); }
+    .palette-action { background: var(--ui-accent); }
+    @media (max-width: 64rem) { .customizer-layout { grid-template-columns: minmax(0, 1fr); } aside { position: static; max-block-size: none; } }
+  </style></template>`;
+}

package/docs/customizer.js

@@ -0,0 +1,181 @@
+import { documentationTheme, themeEvent } from './theme-session.mjs';
+import { componentRegistry } from '@nextwebwg/html-next/runtime';
+import { startingPoints, startingPointFor, themeCSS, validateRecipe, themeFields, themePalettes, paletteFor, deriveTheme } from './theme.mjs';
+
+import { valueEditor, editorValue, convertValueUnit } from './value-editors.mjs';
+
+/** The editor changes public theme values; the library owns every control's layout. */
+export function connect(host) {
+  const root = host.element;
+  const document = root.ownerDocument;
+  const view = document.defaultView;
+  const message = root.querySelector('[data-message]');
+  const file = root.querySelector('[data-recipe-file]');
+  const theme = documentationTheme(view);
+  let saved = validateRecipe(JSON.parse(root.dataset.recipe));
+  let recipe = theme?.recipe ?? structuredClone(saved);
+  let revision = root.dataset.revision;
+  let capability;
+  let changed = false;
+  let saving = false;
+  let alive = true;
+  const abort = new AbortController();
+  const say = (text, error = false) => { message.textContent = text; message.setAttribute('role', error ? 'alert' : 'status'); };
+  const sayApplied = text => say(theme?.storageAvailable ? text : 'Theme applies to this page. Browser storage is unavailable; download CSS or a recipe to keep it.');
+  const fields = new Map(themeFields.map(field => [field.id, field]));
+  const unitContext = () => ({ remPixels: parseFloat(view.getComputedStyle(document.documentElement).fontSize) });
+  const updateControl = (element, value) => {
+    const field = fields.get(element.dataset.token);
+    if (!field || !element.dataset.editorKind) { componentRegistry.update(element, { value }); return; }
+    const editor = valueEditor(field, value, unitContext());
+    if (element.dataset.editorKind === 'curve') {
+      element.closest('[data-curve-for]').hidden = editor.kind !== 'curve';
+      if (editor.kind === 'curve') componentRegistry.update(element, { value });
+    } else componentRegistry.update(element, Object.fromEntries(['value', 'unit', 'min', 'max', 'step'].map(key => [key, editor[key]])));
+  };
+  const updateUnits = () => {
+    for (const control of root.querySelectorAll('[data-unit-for]')) {
+      const field = fields.get(control.dataset.unitFor), editor = valueEditor(field, recipe.values[field.id], unitContext());
+      if (![...control.options].some(option => option.value === editor.unit)) control.add(new view.Option(editor.unit, editor.unit));
+      componentRegistry.update(control, { value: editor.unit });
+    }
+  };
+  const paint = () => {
+    const css = themeCSS(recipe);
+    updateControl(root.querySelector('[data-palette]'), paletteFor(recipe));
+    const adjustments = ['light', 'dark'].flatMap(mode => deriveTheme(recipe, { mode }).adjustments.map(item => ({ ...item, mode })));
+    const report = root.querySelector('[data-palette-adjustments]');
+    report.textContent = adjustments.length ? 'Paired ranges are derived for readability. Your seed colors stay editable; resolved values are shown below.' : 'Both ranges preserve your seeds with readable text and essential outlines.';
+    root.querySelector('[data-palette-adjustment-details]').textContent = adjustments.length ? adjustments.map(item => `${item.mode} ${fields.get(item.id).label.toLowerCase()} ${item.requested} → ${item.resolved}`).join('; ') + '. Seed colors remain editable.' : 'Both ranges preserve your seeds with readable text and essential outlines.';
+    for (const card of root.querySelectorAll('[data-example-card]')) card.dispatchEvent(new CustomEvent('looma-theme-preview', { detail: { css: theme?.css ?? css } }));
+    updateControl(root.querySelector('[data-css]'), css);
+  };
+  const show = (next, persist = true) => {
+    recipe = validateRecipe(next);
+    if (persist) theme?.apply(recipe);
+    for (const control of root.querySelectorAll('[data-token]')) updateControl(control, recipe.values[control.dataset.token]);
+    updateControl(root.querySelector('[data-preset]'), startingPointFor(recipe));
+    updateUnits();
+    changed = JSON.stringify(recipe) !== JSON.stringify(saved);
+    paint();
+  };
+  const filterExamples = () => {
+    const words = root.querySelector('[data-example-query]').value.toLocaleLowerCase().trim().split(/\s+/).filter(Boolean);
+    const select = root.querySelector('[data-add-example]');
+    const options = [...select.options];
+    for (const option of options) option.hidden = !words.every(word => option.dataset.search.includes(word));
+    for (const group of select.querySelectorAll('optgroup')) group.hidden = [...group.children].every(option => option.hidden);
+    if (select.selectedOptions[0]?.hidden) select.value = options.find(option => !option.hidden)?.value ?? '';
+    for (const card of root.querySelectorAll('[data-example-card]')) card.closest('section').hidden = !words.every(word => card.textContent.toLocaleLowerCase().includes(word) || card.dataset.componentCard.includes(word));
+    const matches = options.filter(option => !option.hidden).length;
+    root.querySelector('[data-example-count]').textContent = matches ? `${matches} matching examples` : 'No examples match. Try another name or purpose.';
+    componentRegistry.update(root.querySelector('[data-action="add"]'), { disabled: matches === 0 });
+  };
+  const input = event => {
+    if (event.target.matches('[data-example-query]')) { filterExamples(); return; }
+    const control = event.target.closest?.('[data-token]');
+    if (!control) return;
+    const field = fields.get(control.dataset.token);
+    const raw = event.detail?.value ?? control.value;
+    const value = control.dataset.editorKind ? editorValue(field, raw) : String(raw);
+    const next = { schemaVersion: 1, values: { ...recipe.values, [control.dataset.token]: value } };
+    try {
+      recipe = validateRecipe(next);
+      theme?.apply(recipe); changed = true;
+      updateControl(root.querySelector('[data-preset]'), startingPointFor(recipe));
+      control.removeAttribute('aria-invalid');
+      for (const sibling of root.querySelectorAll('[data-token]')) if (sibling.dataset.token === control.dataset.token) updateControl(sibling, value);
+      updateUnits();
+      paint(); sayApplied('Theme remembered in this browser. Download it or save it to your repository.');
+    } catch (error) { control.setAttribute('aria-invalid', 'true'); say(error.message, true); }
+  };
+  const download = (data, name, type) => {
+    const url = URL.createObjectURL(new Blob([data], { type }));
+    const link = document.createElement('a'); link.href = url; link.download = name; link.click();
+    setTimeout(() => URL.revokeObjectURL(url), 0);
+  };
+  const click = async event => {
+    const button = event.target.closest?.('[data-action]');
+    if (!button || (button.dataset.action === 'save' && saving)) return;
+    try {
+      switch (button.dataset.action) {
+        case 'add': {
+          const select = root.querySelector('[data-add-example]');
+          const option = select.selectedOptions[0];
+          const selected = JSON.parse(option.dataset.example);
+          const card = Object.fromEntries(['id','title','description','exampleTitle','src','resizable','category','tag','nativeRoot','href','packageName'].map(key => [key, selected[key]]));
+          if (!host.state.cards.some(item => item.id === card.id)) host.state.cards = [...host.state.cards, card];
+          view.requestAnimationFrame(() => { paint(); filterExamples(); }); break;
+        }
+        case 'css': {
+          const response = await fetch(root.dataset.base + '_looma/theme-system.css', { signal: abort.signal });
+          if (!response.ok) throw new Error('Could not load the shared theme recipe.');
+          download(themeCSS(recipe, await response.text()), 'looma.theme.css', 'text/css'); say('Theme CSS downloaded.'); break;
+        }
+        case 'recipe': download(JSON.stringify(recipe, null, 2) + '\n', 'looma.theme.json', 'application/json'); say('Editable recipe downloaded.'); break;
+        case 'import': file.click(); break;
+        case 'reset': show(theme?.reset() ?? structuredClone(saved), false); say(theme?.storageAvailable ? 'Browser customization reset to the saved theme.' : 'Changes reset for this page. Browser storage is unavailable, so a previous browser theme may return after reload.'); break;
+        case 'save': {
+          if (!capability) throw new Error('Repository saving is available only in the local documentation server.');
+          const submitted = structuredClone(recipe);
+          saving = true;
+          say('Saving your theme and rebuilding the documentation…');
+          const response = await fetch(root.dataset.base + '_looma/theme', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Looma-Capability': capability }, body: JSON.stringify({ recipe: submitted, revision }), signal: abort.signal });
+          const result = await response.json();
+          if (!response.ok) throw new Error(result.error ?? 'Could not save this theme.');
+          revision = result.revision; saved = submitted; theme?.baseline(saved);
+          changed = JSON.stringify(recipe) !== JSON.stringify(saved);
+          if (changed) { say('Saved the submitted theme. Your newer edits are still an unsaved preview.'); break; }
+          say('Saved to your repository. Reloading your design system…');
+          view.location.reload(); break;
+        }
+      }
+    } catch (error) { if (error.name !== 'AbortError' && alive) say(error.message, true); }
+    finally { if (button.dataset.action === 'save') saving = false; }
+  };
+  const change = async event => {
+    if (event.target.matches('[data-unit-for]')) {
+      const field = fields.get(event.target.dataset.unitFor);
+      try {
+        let current = recipe.values[field.id];
+        try { current = convertValueUnit(current, event.target.value, unitContext()); }
+        catch { current = convertValueUnit(view.getComputedStyle(document.documentElement).getPropertyValue(field.property).trim(), event.target.value, unitContext()); }
+        show({ ...recipe, values: { ...recipe.values, [field.id]: current } });
+        sayApplied(`${field.label} units updated and remembered in this browser.`);
+      } catch (error) { updateUnits(); say(error.message, true); }
+    }
+    if (event.target.matches('[data-palette]')) { show({ ...recipe, values: { ...recipe.values, ...themePalettes[event.target.value].values } }); sayApplied('Coordinated palette applied. Both color modes are remembered with your existing size, material and motion.'); }
+    if (event.target.matches('[data-preset]')) { show(structuredClone(startingPoints[event.target.value])); sayApplied('Starting point applied throughout the documentation and remembered in this browser.'); }
+    if (event.target === file && file.files[0]) {
+      try { show(JSON.parse(await file.files[0].text())); sayApplied('Recipe applied throughout the documentation and remembered in this browser.'); }
+      catch (error) { say(error.message, true); }
+      file.value = '';
+    }
+  };
+  const blur = event => { const control = event.target; if (control.closest?.('[data-token]')) queueMicrotask(() => { if (alive && control.validity?.customError) say(control.validationMessage, true); }); };
+  const synchronize = () => { if (theme && JSON.stringify(recipe) !== JSON.stringify(theme.recipe)) show(theme.recipe, false); };
+  const ready = event => {
+    if (event.data?.type === 'looma-preview-ready' && [...root.querySelectorAll('iframe')].some(frame => frame.contentWindow === event.source)) paint();
+  };
+  const remove = event => { host.state.cards = host.state.cards.filter(card => card.id !== event.detail.id); };
+  root.addEventListener('looma-example-remove', remove);
+  root.addEventListener('input', input);
+  root.addEventListener('blur', blur, true);
+  root.addEventListener('change', change);
+  root.addEventListener('click', click);
+  view.addEventListener('message', ready);
+  view.addEventListener(themeEvent, synchronize);
+  show(recipe, false); filterExamples();
+  if (theme?.storageAvailable === false) sayApplied('');
+  if (root.dataset.mode === 'local') {
+    fetch(root.dataset.base + '_looma/session', { signal: abort.signal }).then(async response => {
+      if (!response.ok) throw new Error('Local theme saving is unavailable.');
+      const local = await response.json(); if (!alive) return;
+      capability = local.capability;
+      saved = validateRecipe(local.recipe); revision = local.revision; theme?.baseline(saved);
+      if (!changed && !theme?.hasOverride) show(saved, false);
+      root.querySelector('[data-action="save"]').hidden = false;
+    }).catch(error => { if (alive && error.name !== 'AbortError') say(error.message, true); });
+  }
+  return () => { alive = false; abort.abort(); root.removeEventListener('looma-example-remove', remove); root.removeEventListener('input', input); root.removeEventListener('blur', blur, true); root.removeEventListener('change', change); root.removeEventListener('click', click); view.removeEventListener('message', ready); view.removeEventListener(themeEvent, synchronize); };
+}

package/docs/documentation.css

@@ -0,0 +1,16 @@
+/* Documentation presentation owns only its native preview frame and code overflow. Controls use Looma. */
+[data-example-card] iframe { display: block; max-inline-size: 100%; border: 0; background: transparent; }
+[data-example-card] pre { overflow: auto; }
+/* The customizer is an application page; use Markupress's public width token instead of patching its layout. */
+:root:has([data-looma-customizer]), :root:has([data-component~="looma-catalog"]) { --markupress-content-width: 110rem; }
+body:has([data-preview]) { background: var(--ui-surface); color: var(--ui-text); font-family: var(--ui-font-sans); font-size: var(--ui-font-size); line-height: var(--ui-line-height); }
+[data-preview] { display: grid; place-items: center; gap: var(--ui-space-4); min-block-size: 13rem; padding: 1.35rem; box-sizing: border-box; }
+[data-preview-layout] { justify-items: stretch; }
+body:has([data-preview]) { margin: 0; background: linear-gradient(90deg, rgb(43 37 56 / .035) 1px, transparent 1px), linear-gradient(rgb(43 37 56 / .035) 1px, transparent 1px), color-mix(in srgb, var(--ui-accent) 5%, var(--ui-surface)); background-size: 22px 22px; }
+
+/* These headings are authored page content projected through the example card's heading slot. */
+.looma-reference-examples { padding-block-start: var(--ui-space-5); }
+.looma-example-heading h3 { margin: 0; font-size: var(--ui-font-size-lg); line-height: var(--ui-line-height-tight); }
+.looma-example-heading p { margin: var(--ui-space-2) 0 0; font-size: var(--ui-font-size-sm); color: var(--ui-text-secondary); }
+html[data-preview-reference], html[data-preview-reference] body { background: var(--ui-surface); }
+html[data-preview-reference] [data-preview] { min-block-size: 11rem; }

package/docs/examples/ui-action-bar/examples/01-form-footer.behavior.js

@@ -0,0 +1,7 @@
+/** Keep the form demonstration on this page while exercising native submit behavior. */
+export default function setupExample(root) {
+    const form = root.querySelector("form");
+    const submit = (event) => event.preventDefault();
+    form?.addEventListener("submit", submit);
+    return () => form?.removeEventListener("submit", submit);
+}

package/docs/examples/ui-button/examples/08-loading.behavior.js

@@ -0,0 +1,21 @@
+import { componentRegistry } from "@nextwebwg/html-next/runtime";
+/** Simulates a save so the example shows the transition into and out of loading. */
+export default function saveChanges(root) {
+    const button = root.querySelector("#docs-save-changes");
+    if (!button)
+        return () => { };
+    let timer;
+    const onClick = () => {
+        componentRegistry.update(button, { loading: true });
+        timer = setTimeout(() => {
+            componentRegistry.update(button, { loading: false });
+            timer = undefined;
+        }, 1500);
+    };
+    button.addEventListener("click", onClick);
+    return () => {
+        button.removeEventListener("click", onClick);
+        if (timer !== undefined)
+            clearTimeout(timer);
+    };
+}

package/docs/examples/ui-checkbox/examples/02-checked-indeterminate-and-disabled.behavior.js

@@ -0,0 +1,30 @@
+import { componentRegistry } from "@nextwebwg/html-next/runtime";
+/** Keeps the summary checkbox in step with three independently checked items. */
+export default function connectSelection(root) {
+    const all = root.querySelector("#docs-checkbox-all");
+    const items = Array.from(root.querySelectorAll(".docs-checkbox-item"));
+    if (!all || !items.length)
+        return () => { };
+    const checked = (item) => Boolean(item.querySelector('input[type="checkbox"]')?.checked);
+    const onItemChange = (event) => {
+        if (!(event instanceof CustomEvent) || typeof event.detail?.checked !== "boolean")
+            return;
+        const count = items.filter(checked).length;
+        componentRegistry.update(all, { checked: count === items.length, indeterminate: count > 0 && count < items.length });
+    };
+    const onAllChange = (event) => {
+        if (!(event instanceof CustomEvent) || typeof event.detail?.checked !== "boolean")
+            return;
+        for (const item of items)
+            componentRegistry.update(item, { checked: event.detail.checked });
+        componentRegistry.update(all, { indeterminate: false });
+    };
+    all.addEventListener("change", onAllChange);
+    for (const item of items)
+        item.addEventListener("change", onItemChange);
+    return () => {
+        all.removeEventListener("change", onAllChange);
+        for (const item of items)
+            item.removeEventListener("change", onItemChange);
+    };
+}

package/docs/examples/ui-combobox/examples/06-selected-values.behavior.js

@@ -0,0 +1,11 @@
+import { componentRegistry } from "@nextwebwg/html-next/runtime";
+/** Takes each change the user makes, as a consumer that owns selectedValues does. */
+export default function keepSelection(root) {
+    const onChange = (event) => {
+        const { selectedValues } = event.detail;
+        // A rendered component's data-* attributes only record its options; the runtime's prop channel sets them.
+        componentRegistry.update(event.target, { selectedValues });
+    };
+    root.addEventListener("selected-values-change", onChange);
+    return () => root.removeEventListener("selected-values-change", onChange);
+}