@threadlabs/looma 0.33.0 → 0.34.0

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";

package/docs/index.d.ts

@@ -0,0 +1,56 @@
+export interface DocumentationGroup { id: string; label: string }
+export interface ExampleCode { language: string; code: string }
+export interface DocumentationExample {
+  id: string; name: string; title: string; description: string; markup: string;
+  resizable: boolean; frameworks: Record<string, ExampleCode>; behavior?: string; bindings?: string;
+}
+export interface DocumentationComponent {
+  id: string; package: string; tag: string; title: string; description: string; group: string;
+  root: string; resource: string; source?: string; navigationParent?: string;
+  targets: string[]; examples: DocumentationExample[];
+  attributes: Record<string, unknown>[]; properties: Record<string, unknown>[];
+  events: Record<string, unknown>[]; slots: Record<string, unknown>[];
+  designTokens: { sources?: string[]; component: Record<string, unknown>[]; shared: Record<string, unknown>[] };
+}
+export interface DocumentationCatalog {
+  schemaVersion: 1; package?: string; version?: string; groups: DocumentationGroup[];
+  resources?: { tag: string; package: string; resource: string }[]; components: DocumentationComponent[];
+}
+export interface DiscoveryRoot { directory: string; packageName: string; groups?: DocumentationGroup[] }
+export interface ThemeRecipe { schemaVersion: 1; values: Record<string, string> }
+export interface ThemeField { family: string; id: string; label: string; property: string; type: string; defaultValue: string; description: string; min?: number; max?: number }
+export interface DocumentationConfiguration {
+  title?: string; base?: string; origin?: string; outDir?: string; content?: string;
+  logo?: string | { light: string; dark?: string }; nav?: { label: string; href: string }[];
+  components?: DiscoveryRoot[]; catalogs?: string[]; categories?: Record<string, string>;
+  theme?: { recipe?: string; css?: string }; overrides?: string[];
+  recipe?: ThemeRecipe;
+}
+export interface DocumentationInput { root?: string; config?: DocumentationConfiguration; catalog?: DocumentationCatalog }
+export interface DocumentationSite {
+  root: string; config: DocumentationConfiguration; base: string; catalog: DocumentationCatalog;
+  examples: (DocumentationExample & { file: string; component: string; path: string })[];
+  generated: string; content: string; previews: string; redirects: Record<string, string>;
+}
+export interface DocumentationBuild { outDir: string; routes: readonly string[]; browserInputs: readonly string[]; site: DocumentationSite }
+export interface DocumentationServer { url: string; close(): Promise<void> }
+export function readCatalog(specifier?: string | URL): Promise<DocumentationCatalog>;
+export function discoverComponents(input: DiscoveryRoot & { root: string }): Promise<DocumentationCatalog>;
+export function mergeCatalogs(catalogs: DocumentationCatalog[], options?: { categories?: Record<string, string> }): DocumentationCatalog;
+export function prepareDocumentation(input: DocumentationInput & { root: string }): Promise<DocumentationSite>;
+export function buildDocumentation(input?: DocumentationInput): Promise<DocumentationBuild>;
+/** Optional HTMLKit integration; server tooling peers are loaded only when invoked. */
+export function documentationOptions(site: DocumentationSite): Promise<import('@nextwebwg/htmlkit').ApplicationOptions>;
+export function documentationPlugin(site: DocumentationSite): import('@nextwebwg/htmlkit').HtmlKitPlugin;
+export function initializeDocumentation(input?: { root?: string; title?: string }): Promise<{ config: DocumentationConfiguration; files: string[]; applicationImport: string }>;
+export function readConfiguration(root?: string): Promise<{ root: string; config: DocumentationConfiguration }>;
+export function buildProjectDocumentation(input?: DocumentationInput): Promise<DocumentationBuild>;
+export function devProjectDocumentation(input?: DocumentationInput & { port?: number; onError?: (error: unknown) => void }): Promise<DocumentationServer>;
+export function previewProjectDocumentation(input?: DocumentationInput & { port?: number }): Promise<DocumentationServer>;
+export const themeFields: readonly ThemeField[];
+export const startingPoints: Record<string, ThemeRecipe>;
+export function defaultRecipe(): ThemeRecipe;
+export function validateRecipe(input: unknown): ThemeRecipe;
+export interface ResolvedTheme { tokens: Record<string, string>; adjustments: { id: string; requested: string; resolved: string; reason: string }[] }
+export function deriveTheme(input: ThemeRecipe, options?: { mode?: 'light' | 'dark' }): ResolvedTheme;
+export function themeCSS(input: ThemeRecipe, systemCSS?: string, options?: { scope?: 'portable' | 'documentation' }): string;

package/docs/index.mjs

@@ -0,0 +1,4 @@
+export { readCatalog, discoverComponents, mergeCatalogs } from './catalog.mjs';
+export { prepareDocumentation, documentationOptions, documentationPlugin, buildDocumentation } from './site.mjs';
+export { defaultRecipe, startingPoints, themeFields, validateRecipe, deriveTheme, themeCSS } from './theme.mjs';
+export { initializeDocumentation, buildProjectDocumentation, devProjectDocumentation, previewProjectDocumentation, readConfiguration } from './commands.mjs';

package/docs/local-server.mjs

@@ -0,0 +1,68 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { createServer, request as proxyRequest } from 'node:http';
+
+const rejected = (message, status = 403) => Object.assign(new Error(message), { status });
+const secretMatches = (value, secret) => typeof value === 'string' && Buffer.byteLength(value) === secret.length && timingSafeEqual(Buffer.from(value), Buffer.from(secret));
+async function body(request) {
+  const chunks = []; let size = 0;
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > 64 * 1024) throw rejected('Theme request is too large.', 413);
+    chunks.push(chunk);
+  }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+  catch { throw rejected('Expected a JSON theme recipe and revision.', 400); }
+}
+
+/** Local capabilities stay in the parent editor; opaque example frames receive only theme CSS. */
+export async function serveLocalDocumentation({ upstream, store, base = '/', port = 0, onSaved = async () => {} }) {
+  const target = new URL(upstream);
+  if (target.protocol !== 'http:' || target.hostname !== '127.0.0.1') throw new Error('The documentation upstream must be a loopback HTMLKit server.');
+  const capability = randomBytes(32).toString('hex');
+  let origin;
+  const json = (response, status, data) => {
+    response.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' });
+    response.end(JSON.stringify(data));
+  };
+  const sameOrigin = request => {
+    if (request.headers.origin) return request.headers.origin === origin;
+    return request.headers['sec-fetch-site'] === 'same-origin';
+  };
+  const server = createServer((request, response) => {
+    void (async () => {
+      if (request.headers.host !== new URL(origin).host) throw rejected('Unexpected local documentation host.');
+      const url = new URL(request.url, origin);
+      const api = base + '_looma/';
+      if (url.pathname === api + 'session' || url.pathname === api + 'theme') {
+        if (!sameOrigin(request)) throw rejected('Open this editor from its local documentation address.');
+        if (url.pathname.endsWith('/session')) {
+          if (request.method !== 'GET') throw rejected('Use GET for the local session.', 405);
+          json(response, 200, { ...await store.read(), capability }); return;
+        }
+        if (request.method !== 'POST') throw rejected('Use POST to save a theme.', 405);
+        if (request.headers['content-type']?.split(';')[0].trim() !== 'application/json') throw rejected('Use application/json to save a theme.', 415);
+        if (!secretMatches(request.headers['x-looma-capability'], capability)) throw rejected('The local editing session expired. Reload before saving.');
+        const result = await store.save(await body(request));
+        try { await onSaved(result); }
+        catch (error) { throw rejected(`Theme files were saved, but the documentation could not rebuild: ${error.message}`, 500); }
+        json(response, 200, result); return;
+      }
+      if (!['GET', 'HEAD'].includes(request.method)) throw rejected('Documentation supports GET and HEAD.', 405);
+      const headers = { ...request.headers, host: target.host };
+      delete headers['x-looma-capability'];
+      const proxy = proxyRequest(target.origin + request.url, { method: request.method, headers }, remote => {
+        const responseHeaders = { ...remote.headers };
+        if (url.pathname.startsWith(api + 'preview/')) {
+          const existing = responseHeaders['content-security-policy'];
+          responseHeaders['content-security-policy'] = [...(existing ? [existing].flat() : []), 'sandbox allow-scripts'];
+        }
+        response.writeHead(remote.statusCode, responseHeaders); remote.pipe(response);
+      });
+      proxy.on('error', () => { if (!response.headersSent) json(response, 502, { error: 'The documentation renderer is unavailable.' }); else response.destroy(); });
+      request.on('aborted', () => proxy.destroy()); proxy.end();
+    })().catch(error => { if (!response.headersSent) json(response, error.status ?? 500, { error: error.status ? error.message : 'Could not process this local documentation request.' }); else response.destroy(); });
+  });
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', resolve); });
+  origin = `http://127.0.0.1:${server.address().port}`;
+  return { url: origin + base, close: () => new Promise((resolve, reject) => { server.close(error => error ? reject(error) : resolve()); server.closeIdleConnections(); }) };
+}

package/docs/preview.js

@@ -0,0 +1,22 @@
+/** An opaque sandbox cannot read its parent; it accepts only theme CSS from that parent. */
+export function connect(host) {
+  const document = host.element.ownerDocument;
+  const view = document.defaultView;
+  const theme = document.createElement('style');
+  theme.dataset.loomaTheme = '';
+  document.head.append(theme);
+  const height = () => view.parent.postMessage({ type: 'looma-preview-height', height: Math.max(host.element.getBoundingClientRect().height, host.element.scrollHeight) }, '*');
+  const receive = event => {
+    if (event.source !== view.parent || event.data?.type !== 'looma-theme' || typeof event.data.css !== 'string') return;
+    theme.textContent = event.data.css;
+    document.documentElement.toggleAttribute('data-preview-reference', event.data.reference === true);
+    if (['light', 'dark'].includes(event.data.mode)) document.documentElement.dataset.theme = event.data.mode;
+    height();
+  };
+  view.addEventListener('message', receive);
+  const observer = new ResizeObserver(height);
+  observer.observe(host.element);
+  view.parent.postMessage({ type: 'looma-preview-ready' }, '*');
+  height();
+  return () => { observer.disconnect(); view.removeEventListener('message', receive); theme.remove(); };
+}

package/docs/reference.html

@@ -0,0 +1 @@
+<template component="looma-reference" module="./reference.js"><defs></defs><div><slot></slot></div></template>

package/docs/reference.js

@@ -0,0 +1,36 @@
+/** A deep link opens its containing tab through the tab's native, accessible activation. */
+export function connect(host) {
+  const root = host.element;
+  const view = root.ownerDocument.defaultView;
+  let currentHash = view.location.hash;
+  const open = () => {
+    let id;
+    try { id = decodeURIComponent(currentHash.slice(1)); } catch { return; }
+    const target = root.ownerDocument.getElementById(id);
+    if (!target || !root.contains(target)) { observer.disconnect(); return; }
+    const panel = target.closest('[role="tabpanel"]');
+    const tab = panel && [...root.querySelectorAll('[role="tab"]')].find(button => button.getAttribute('aria-controls') === panel.id);
+    if (!tab) return;
+    if (panel.hidden) tab.click();
+    if (!panel.hidden) { target.scrollIntoView({ block: 'start' }); observer.disconnect(); }
+  };
+  const observer = new MutationObserver(open);
+  const activate = value => {
+    currentHash = value;
+    observer.disconnect();
+    if (!currentHash) return;
+    observer.observe(root, { subtree: true, childList: true, attributes: true, attributeFilter: ['role', 'id', 'hidden'] });
+    open();
+  };
+  const hash = () => activate(view.location.hash);
+  const click = event => {
+    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    const link = event.target.closest?.('a[href]');
+    if (!link || link.target && link.target !== '_self') return;
+    const target = new URL(link.href, view.location.href);
+    if (target.origin === view.location.origin && target.pathname === view.location.pathname && target.hash) activate(target.hash);
+  };
+  root.addEventListener('click', click);
+  view.addEventListener('hashchange', hash); hash();
+  return () => { observer.disconnect(); root.removeEventListener('click', click); view.removeEventListener('hashchange', hash); };
+}

package/docs/render.mjs

@@ -0,0 +1,93 @@
+import { createHash } from 'node:crypto';
+import { escapeHtml as escape } from './catalog.mjs';
+import { createLoomaMarkdownIt } from '@threadlabs/looma/markdown/markdown-it';
+
+const descriptions = createLoomaMarkdownIt().set({ html: false });
+
+const literal = value => escape(value).replaceAll('{', '\\{');
+const code = value => `<code>${literal(value ?? '—')}</code>`;
+const table = (head, rows) => `<table><thead><tr>${head.map(h => `<th>${literal(h)}</th>`).join('')}</tr></thead><tbody>${rows.map(row => `<tr>${row.map(value => `<td>${value}</td>`).join('')}</tr>`).join('')}</tbody></table>`;
+export const exampleKey = id => createHash('sha256').update(id).digest('hex').slice(0, 20);
+export const componentPath = component => `/components/${component.navigationParent ?? component.tag}/` + (component.navigationParent ? `#${component.tag}-api` : '');
+export const previewPath = example => `/_looma/preview/${exampleKey(example.id)}/`;
+
+export function apiBody(api, prefix = '') {
+  const attributes = api.attributes ?? [];
+  const properties = api.properties ?? [];
+  const events = api.events ?? [];
+  const slots = api.slots ?? [];
+  const tokens = api.designTokens ?? { component: [], shared: [] };
+  const section = (name, items, headings, render) => `<h2 id="${prefix}${name.toLowerCase().replaceAll(' ', '-')}">${name}</h2>${items.length ? table(headings, items.map(render)) : `<p>No ${name.toLowerCase()}.</p>`}`;
+  const fields = value => value?.length ? `<ul>${value.map(field => `<li>${code(field.path)}: ${code(field.type)}${field.required ? ' (required)' : ''}</li>`).join('')}</ul>` : '';
+  return `<p><strong>Package:</strong> ${code(api.package)} · <strong>Native root:</strong> ${code(api.root)}</p>`
+    + section('Attributes', attributes, ['Name', 'Description', 'Property', 'Type', 'Default', 'Allowed values'], p => [code(p.name), literal(p.description ?? ''), code(p.property), code(p.type) + fields(p.fields), code(p.default), code(p.options?.join(', '))])
+    + (api.targets?.includes('vue') ? section('Framework props', properties, ['Name', 'Type', 'Default', 'Allowed values'], p => [code(p.name), code(p.type) + fields(p.fields), code(p.default), code(p.options?.join(', '))]) : '')
+    + section('Events', events, ['Name', 'Detail', 'Description'], e => [code(e.name), code(e.detailSchema ?? e.detailType) + fields(e.fields), literal(e.detailDocs ?? '')])
+    + section('Slots', slots, ['Name', 'Purpose'], s => [code(s.name), literal(s.description ?? '')])
+    + `<h2 id="${prefix}design-tokens">Design tokens</h2><p>Set shared theme properties on a theme boundary. Component hooks apply only to their owning component.</p>`
+    + section('Component tokens', tokens.component ?? [], ['Token', 'Declared values', 'Fallback'], t => [code(t.name), code(t.declarations?.join(' | ')), code(t.fallbacks?.join(' | '))])
+    + section('Shared tokens', tokens.shared ?? [], ['Token', 'Fallback'], t => [code(t.name), code(t.fallbacks?.join(' | '))]);
+}
+
+function structuredBindings(example) {
+  let markup = example.markup;
+  const assignments = [];
+  for (const pair of (example.bindings ?? '').split(/\s+/).filter(Boolean)) {
+    const [attribute, variable] = pair.split('=');
+    if (!/^[a-zA-Z_$][\w$]*$/.test(variable ?? '') || !/^[\w-]+$/.test(attribute)) throw new Error(`Invalid example binding ${pair} in ${example.id}.`);
+    const match = new RegExp(`<[^>]*\\s${attribute}='([^']*)'[^>]*>`).exec(markup);
+    const id = match && /\sid="([^"]+)"/.exec(match[0])?.[1];
+    if (!match || !id) throw new Error(`Example binding ${pair} in ${example.id} needs an element with an id.`);
+    const value = JSON.parse(match[1].replaceAll('&#39;', "'").replaceAll('&quot;', '"').replaceAll('&amp;', '&'));
+    assignments.push({ id, variable, property: attribute.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase()), value });
+    markup = markup.replace(match[0], match[0].replace(` ${attribute}='${match[1]}'`, ''));
+  }
+  return { markup, assignments };
+}
+
+export function exampleCodes(example, component, components) {
+  const tags = [...new Set([...example.markup.matchAll(/<([a-z][\w]*-[\w-]+)\b/g)].map(match => match[1]))];
+  const owners = [...new Set(tags.map(tag => components.find(c => c.tag === tag)?.package).filter(Boolean))];
+  const html = `<script type="module">\n${owners.map(owner => `import ${JSON.stringify(owner)};`).join('\n')}\n</script>\n\n${example.markup}`;
+  const codes = { 'html-next': { language: 'html', code: html } };
+  if (component.targets?.includes('vue')) {
+    const toName = tag => tag.replace(/^ui-/, '').split('-').map(word => word[0].toUpperCase() + word.slice(1)).join('');
+    const groups = new Map();
+    for (const tag of tags) {
+      const entry = components.find(c => c.tag === tag);
+      if (!entry?.targets?.includes('vue')) continue;
+      const owner = entry.vueImport ?? `${entry.package}/vue${tag.startsWith('ui-editor-') ? '/editor' : ''}`;
+      groups.set(owner, [...groups.get(owner) ?? [], toName(tag)]);
+    }
+    const binding = structuredBindings(example);
+    let markup = binding.markup;
+    for (const tag of tags) if (components.find(c => c.tag === tag)?.targets?.includes('vue')) markup = markup.replace(new RegExp(`(</?)${tag}(?=[\\s/>])`, 'g'), (_, start) => start + toName(tag));
+    for (const assignment of binding.assignments) markup = markup.replace(`id="${assignment.id}"`, `id="${assignment.id}" :${assignment.property}="${assignment.variable}"`);
+    const declarations = binding.assignments.map(assignment => `const ${assignment.variable} = ${JSON.stringify(assignment.value, null, 2)};`).join('\n');
+    codes.vue = { language: 'vue', code: `<script setup>\n${[...groups].map(([owner, names]) => `import { ${names.sort().join(', ')} } from ${JSON.stringify(owner)};`).join('\n')}\n${declarations}\n</script>\n\n<template>\n${markup}\n</template>` };
+  }
+  return { ...codes, ...example.frameworks };
+}
+
+/** The same card invocation is embedded in reference pages and rendered by the customizer. */
+export function cardMarkup(example, base = '/', component = {}, { reference = false, code: exampleCode = '' } = {}) {
+  return `<looma-example-card identity="${escape(example.id)}"${reference ? ' reference' : ''} title="${escape(component.title ?? example.title)}" description="${escape(reference ? example.description : component.description ?? example.description)}" example-title="${escape(example.title)}" category="${escape(component.group ?? 'forms')}" tag="${escape(component.tag ?? '')}" package-name="${escape(component.package ?? '')}" native-root="${escape(component.root ? `<${component.root}>` : '')}" href="${component.tag ? base + componentPath(component).slice(1) : ''}" src="${base}${previewPath(example).slice(1)}"${example.resizable ? ' resizable' : ''}>${reference ? `<div slot="heading" class="looma-example-heading"><h3 id="example-${exampleKey(example.id)}">${escape(example.title)}</h3><p>${escape(example.description)}</p></div>` : ''}${exampleCode}</looma-example-card>`;
+}
+
+export function referencePage(component, catalog, cardResource, base) {
+  const parts = catalog.components.filter(c => c.navigationParent === component.tag);
+  const examples = [...component.examples, ...parts.flatMap(part => part.examples)];
+  const codes = example => {
+    const owner = catalog.components.find(c => c.examples.some(e => e.id === example.id)) ?? component;
+    // Blank lines let Markupress parse real fences inside the projected HTML slots.
+    // A fence longer than any authored run keeps snippets literal, including nested fences.
+    const tabs = Object.entries(exampleCodes(example, owner, catalog.components)).map(([mode, value]) => {
+      const fence = '~'.repeat(Math.max(3, ...[...value.code.matchAll(/~+/g)].map(match => match[0].length + 1)));
+      const language = /^[\w+-]+$/.test(value.language) ? value.language : 'text';
+      return `<section aria-label="${mode === 'vue' ? 'Vue' : 'HTML Next'}"><div data-theme="dark" style="--ui-surface-sunken: #0d1117">\n\n${fence}${language}\n${value.code}\n${fence}\n\n</div></section>`;
+    }).join('\n');
+    return `<ui-tabs slot="code" label="Example syntax" group="syntax" style="--ui-tabs-panel-padding: 0px">${tabs}</ui-tabs>`;
+  };
+  const body = `<div class="looma-reference-examples"><ui-stack gap="xl">${examples.map(example => `<ui-card as="section" variant="subtle" padding="lg">${cardMarkup(example, base, catalog.components.find(c => c.examples.some(e => e.id === example.id)) ?? component, { reference: true, code: codes(example) })}</ui-card>`).join('')}</ui-stack></div>`;
+  return `---\ntitle: ${JSON.stringify(component.title)}\ndescription: ${JSON.stringify(component.description || `${component.title} component reference.`)}\nid: ${JSON.stringify(component.id)}\n---\n\n# ${escape(component.title)}\n\n<div class="component-description"><p>${descriptions.renderInline(component.description).replaceAll('{', '\\{').replaceAll('\n', '&#10;')}</p></div>\n\n<link rel="component" href="${cardResource}">\n<link rel="component" href="${cardResource.replace(/card\.html$/, 'reference.html')}">\n<link rel="component" href="@threadlabs/looma/components/ui-card/ui-card.html">\n<link rel="component" href="@threadlabs/looma/components/ui-tabs/ui-tabs.html">\n<link rel="component" href="@threadlabs/looma/components/ui-disclosure/ui-disclosure.html">\n<link rel="component" href="@threadlabs/looma/components/ui-stack/ui-stack.html">\n\n<looma-reference>\n\n<div class="looma-reference-tabs"><ui-tabs label="Component reference" style="--ui-tabs-panel-padding: 0px; --ui-tabs-tab-min-block-size: var(--ui-control-size-lg)"><section aria-label="Examples">${body}</section><section aria-label="API"><h2 id="api">API</h2>\n${apiBody(component)}\n${parts.map(part => `<h2 id="${part.tag}-api">${literal(part.title)} API</h2><p>${literal(part.description)}</p>${apiBody(part, part.tag + '-')}`).join('\n')}</section></ui-tabs></div>\n\n</looma-reference>\n`;
+}