@threadlabs/looma 0.33.0 → 0.33.1

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,40 @@
+import { escapeHtml as escape } from './catalog.mjs';
+import { componentPath, previewPath } from './render.mjs';
+import { defaultRecipe, themeFields, startingPointLabels, startingPointFor, themeCSS, validateRecipe } 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'].map(tag => examples.find(example => example.tag === tag)).filter(Boolean).map(toCard);
+  if (!initial.length && examples.length) initial.push(toCard(examples[0]));
+  const field = field => `<ui-form-field><label slot="label" for="theme-${field.id}">${escape(field.label)}</label><span slot="help">${escape(field.description)}</span><ui-cluster wrap="nowrap" gap="xs">${field.type === 'colour' ? `<ui-color-picker size="sm" data-token="${field.id}" value="${escape(recipe.values[field.id])}" label="${escape(field.label)} colour picker"></ui-color-picker>` : ''}<ui-input id="theme-${field.id}" size="sm" data-token="${field.id}" value="${escape(recipe.values[field.id])}" aria-label="${escape(field.label)}" type="${['positive','ratio','nonnegative','fraction','weight'].includes(field.type) ? 'number' : 'text'}"${['positive','ratio','nonnegative','fraction','weight'].includes(field.type) ? ' step="any"' : ''}></ui-input></ui-cluster></ui-form-field>`;
+  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'].includes(item.id)).map(field).join('')}${family === '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(field).join('')}</ui-stack></ui-disclosure>` : ''}</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))}">${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'].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. Unsaved changes affect the cards; saving applies the theme throughout your documentation.</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>
+  <p role="status" aria-live="polite" data-message>Preview changes on the documentation cards.</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-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; }
+    @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,118 @@
+import { componentRegistry } from '@nextwebwg/html-next/runtime';
+import { startingPoints, startingPointFor, themeCSS, validateRecipe } from './theme.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]');
+  let recipe = validateRecipe(JSON.parse(root.dataset.recipe));
+  let saved = structuredClone(recipe);
+  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 updateControl = (element, value) => componentRegistry.update(element, { value });
+  const paint = () => {
+    const css = themeCSS(recipe);
+    for (const card of root.querySelectorAll('[data-example-card]')) card.dispatchEvent(new CustomEvent('looma-theme-preview', { detail: { css } }));
+    updateControl(root.querySelector('[data-css]'), css);
+  };
+  const show = next => {
+    recipe = validateRecipe(next);
+    for (const control of root.querySelectorAll('[data-token]')) updateControl(control, recipe.values[control.dataset.token]);
+    updateControl(root.querySelector('[data-preset]'), startingPointFor(recipe));
+    changed = JSON.stringify(recipe) !== JSON.stringify(saved);
+    paint();
+  };
+  const input = event => {
+    const control = event.target.closest?.('[data-token]');
+    if (!control) return;
+    const value = event.detail?.value ?? control.value;
+    const next = { schemaVersion: 1, values: { ...recipe.values, [control.dataset.token]: value } };
+    try {
+      recipe = validateRecipe(next); changed = true;
+      updateControl(root.querySelector('[data-preset]'), startingPointFor(recipe));
+      control.removeAttribute('aria-invalid');
+      for (const sibling of root.querySelectorAll('[data-token]')) if (sibling !== control && sibling.dataset.token === control.dataset.token) updateControl(sibling, value);
+      paint(); say('Unsaved preview. Download the theme 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); 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(structuredClone(saved)); say('Returned to the saved theme.'); 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;
+          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-preset]')) { show(structuredClone(startingPoints[event.target.value])); say('Starting point applied to every preview card.'); }
+    if (event.target === file && file.files[0]) {
+      try { show(JSON.parse(await file.files[0].text())); say('Recipe imported as an unsaved preview.'); }
+      catch (error) { say(error.message, true); }
+      file.value = '';
+    }
+  };
+  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('change', change);
+  root.addEventListener('click', click);
+  view.addEventListener('message', ready);
+  paint();
+  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 session = await response.json(); if (!alive) return;
+      capability = session.capability;
+      if (!changed) { saved = validateRecipe(session.recipe); revision = session.revision; show(saved); }
+      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('change', change); root.removeEventListener('click', click); view.removeEventListener('message', ready); };
+}

package/docs/documentation.css

@@ -0,0 +1,8 @@
+/* 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-card]) { --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; }
+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; }

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);
+}

package/docs/examples/ui-search-shell/examples/02-label-dismissible-status-and-footer.behavior.js

@@ -0,0 +1,34 @@
+/** Filters the example's results as the query changes; a real application would query its index. */
+export default function filterResults(root) {
+    const update = () => {
+        const input = root.querySelector("#docs-search-input");
+        const status = root.querySelector("#docs-search-status");
+        const empty = root.querySelector("#docs-search-empty");
+        const results = [
+            root.querySelector("#docs-result-design-tokens"),
+            root.querySelector("#docs-result-token-overrides"),
+            root.querySelector("#docs-result-button-variants")
+        ].filter((result) => result !== null);
+        if (!input || !status || !empty || results.length === 0)
+            return;
+        const query = input.value.trim().toLowerCase();
+        let visible = 0;
+        for (const result of results) {
+            result.hidden = !result.textContent?.toLowerCase().includes(query);
+            if (!result.hidden)
+                visible += 1;
+        }
+        status.textContent = `${visible} result${visible === 1 ? "" : "s"}`;
+        empty.hidden = visible !== 0;
+    };
+    const onInput = (event) => {
+        if (event.target?.id === "docs-search-input")
+            update();
+    };
+    root.addEventListener("input", onInput);
+    const frame = requestAnimationFrame(update);
+    return () => {
+        cancelAnimationFrame(frame);
+        root.removeEventListener("input", onInput);
+    };
+}

package/docs/examples/ui-toast/examples/01-authored.behavior.js

@@ -0,0 +1,15 @@
+/** Shows a hidden authored toast when the example's button is pressed; the toast hides itself when dismissed. */
+export function showToastOnClick(buttonId, toastId) {
+    return (root) => {
+        const button = root.querySelector(`#${buttonId}`);
+        const toast = root.querySelector(`#${toastId}`);
+        if (!button || !toast)
+            return () => { };
+        const show = () => {
+            toast.hidden = false;
+        };
+        button.addEventListener("click", show);
+        return () => button.removeEventListener("click", show);
+    };
+}
+export default showToastOnClick("show-saved-toast", "saved-toast");

package/docs/examples/ui-toast/examples/02-danger.behavior.js

@@ -0,0 +1,2 @@
+import { showToastOnClick } from "./01-authored.behavior.js";
+export default showToastOnClick("show-failed-toast", "failed-toast");

package/docs/examples/ui-tree/examples/03-max-depth-2-and-hover-expand-delay-300.behavior.js

@@ -0,0 +1,30 @@
+/**
+ * Applies a tree's `reorder` requests, as an application does: the tree reports a drop, and the
+ * application moves the item. The tree re-derives levels from the DOM.
+ */
+export default function applyTreeReorder(root) {
+    const onReorder = (event) => {
+        const { sourceId, targetId, position } = event.detail;
+        const tree = event.target?.closest('[role="tree"]');
+        const item = (id) => tree?.querySelector(`[role="treeitem"][data-item-id="${CSS.escape(id)}"]`);
+        const source = item(sourceId);
+        const target = item(targetId);
+        if (!source || !target || source === target || source.contains(target))
+            return;
+        if (position === "before")
+            target.before(source);
+        else if (position === "after")
+            target.after(source);
+        else {
+            const group = target.querySelector(':scope > [role="group"]');
+            if (!group)
+                return;
+            // Stay inside the group's slot range: before its closing marker when there is one.
+            const last = group.lastChild;
+            const marker = last && (last.nodeType === Node.PROCESSING_INSTRUCTION_NODE || last.nodeType === Node.COMMENT_NODE) ? last : null;
+            group.insertBefore(source, marker);
+        }
+    };
+    root.addEventListener("reorder", onReorder, true);
+    return () => root.removeEventListener("reorder", onReorder, true);
+}

package/docs/examples/ui-tree/examples/06-move-without-dragging.behavior.js

@@ -0,0 +1,2 @@
+// Apply reorder requests so the click and keyboard example changes the authored tree.
+export { default } from "./03-max-depth-2-and-hover-expand-delay-300.behavior.js";

package/docs/examples/ui-tree/examples/07-multiple-selection.behavior.js

@@ -0,0 +1,16 @@
+import { componentRegistry } from "@nextwebwg/html-next/runtime";
+/** Apply Tree's controlled selection request to the authored items in this example. */
+export default function applyTreeSelection(root) {
+    const onSelect = (event) => {
+        const { ids } = event.detail;
+        const tree = event.target?.closest('[role="tree"]');
+        if (!tree)
+            return;
+        const selected = new Set(ids);
+        for (const item of tree.querySelectorAll('[role="treeitem"][data-item-id]')) {
+            componentRegistry.update(item, { selected: selected.has(item.dataset.itemId ?? "") });
+        }
+    };
+    root.addEventListener("select", onSelect, true);
+    return () => root.removeEventListener("select", onSelect, true);
+}

package/docs/examples/ui-tree-item/examples/02-container.behavior.js

@@ -0,0 +1 @@
+export { default } from "../../ui-tree/examples/03-max-depth-2-and-hover-expand-delay-300.behavior.js";