@designtools/docs 0.0.0-stage → 0.2.0

package/dist/lib/markdown.js

@@ -0,0 +1,286 @@
+/**
+ * The markdown form of every block, generated from the manifest rather than
+ * converted from HTML, so the same manifest always gives the same markdown.
+ * A docs page answers `Accept: text/markdown` (or `.md`) with these; the agent
+ * tabs show them; copy-page copies them.
+ *
+ * Structure survives as typed fences (```rule, ```example, ```do, ```dont) so
+ * an agent can tell what each part is. Status travels with everything.
+ */
+import { groupByCategory, importOf, ramps, semanticColours, shortName, slugOf, tokensOfTier, typeScale, valueIn } from "./manifest.js";
+import { standardsSections } from "./standards.js";
+// ------------------------------------------------------------ headers
+/** A generated page: the system version and commit it came from. Never a review date, which would be invented. */
+export function generatedHeader(provenance) {
+    return `> ${provenance}. Generated from the code; do not edit this page by hand.\n\n`;
+}
+/** An editorial page: who wrote it, when it was last reviewed, and whether it is settled. */
+export function editorialHeader({ author, reviewer, reviewed, status }) {
+    return `> Written by ${author}. ${reviewer ? `Reviewed by ${reviewer}, ${reviewed}` : `Last reviewed ${reviewed}`}. Status: ${status}.\n\n`;
+}
+// ------------------------------------------------------------ components
+/**
+ * A component as an agent reads it. `level` is its heading's: 1 when it is the
+ * whole page (`/components/button.md`), 2 inside a longer document (`context.md`),
+ * so a page never opens with the same heading twice.
+ */
+export function componentMarkdown(entry, level = 2) {
+    const out = [`${"#".repeat(level)} ${entry.name}`, ""];
+    out.push(`Status: ${entry.status ?? "not set"}${entry.statusNote ? `. ${entry.statusNote}` : ""}`, "");
+    out.push(`\`import { ${entry.export} } from "${importOf(entry)}"\``, "");
+    if (entry.description)
+        out.push(entry.description, "");
+    if (entry.usage) {
+        if (entry.usage.use)
+            out.push(`Use it for: ${entry.usage.use}`);
+        if (entry.usage.avoid)
+            out.push(`Not for: ${entry.usage.avoid}`);
+        if (entry.usage.instead?.length)
+            out.push(`Instead: ${entry.usage.instead.join(", ")}`);
+        out.push("");
+    }
+    if (entry.examples)
+        out.push(...examplesMarkdown(entry.examples.canonical, entry.examples.do, entry.examples.dont, entry.examples.other));
+    const own = Object.entries(entry.props).filter(([, p]) => !p.from);
+    const inherited = Object.entries(entry.props).filter(([, p]) => p.from);
+    if (own.length) {
+        out.push("Props:");
+        for (const [name, p] of own)
+            out.push(`- ${propLine(name, p)}`);
+        out.push("");
+    }
+    const also = [
+        ...(entry.inherits ?? []).map((x) => (/^[a-z][\w-]*$/.test(x) ? `every <${x}> prop` : `every prop of ${x}`)),
+        ...[...new Set(inherited.map(([, p]) => p.from))].map((pkg) => `${inherited.filter(([, p]) => p.from === pkg).length} props from ${pkg}`),
+    ];
+    if (also.length)
+        out.push(`Also accepts ${also.join(", ")}.`, "");
+    const variants = entry.variants;
+    if (variants?.axes.length) {
+        const from = variants.from === "props" ? "its props" : `the ${variants.from}() config \`${variants.config}\``;
+        out.push(`Variants, from ${from}. Use these, not classes, to change how it looks:`);
+        for (const axis of variants.axes) {
+            out.push(`- \`${axis.name}\`: ${axis.options.map((o) => (o.name === axis.default ? `${o.name} (default)` : o.name)).join(" | ")}`);
+            for (const o of axis.options)
+                if (o.description)
+                    out.push(`  - \`${o.name}\`: ${o.description}`);
+        }
+        out.push("");
+    }
+    if (entry.slots.length)
+        out.push(`Parts (\`data-slot\`): ${entry.slots.map((s) => `\`${s}\``).join(", ")}. Keep these on the elements they mark.`, "");
+    if (entry.a11y?.role || entry.a11y?.keyboard) {
+        out.push(`Accessibility: ${[entry.a11y.role && `role \`${entry.a11y.role}\``, entry.a11y.keyboard && `keys ${entry.a11y.keyboard.join(", ")}`].filter(Boolean).join("; ")}.`, "");
+    }
+    if (entry.replaces?.length)
+        out.push(`Use it instead of a raw ${entry.replaces.map((r) => `\`<${r}>\``).join(" or ")}.`, "");
+    for (const snippet of entry.snippets ?? [])
+        out.push("```tsx", snippet, "```", "");
+    if (entry.primitive)
+        out.push(`Wraps: ${entry.primitive}`, "");
+    if (entry.aria)
+        out.push(`ARIA pattern: ${entry.aria}`, "");
+    if (entry.see?.length)
+        out.push(`See also: ${entry.see.join(", ")}`, "");
+    return end(out);
+}
+function examplesMarkdown(canonical, dos, donts, other) {
+    const out = [];
+    const fence = (kind, ex) => {
+        if (ex.description)
+            out.push(ex.description);
+        out.push(`\`\`\`${kind} ${ex.name}`, ex.code ?? `// ${ex.name}`, "```", "");
+    };
+    if (canonical) {
+        out.push("Copy this one:");
+        fence("example", canonical);
+    }
+    // in pairs, as the page shows them: the first do beside the first don't
+    for (let i = 0; i < Math.max(dos.length, donts.length); i++) {
+        if (dos[i])
+            fence("do", dos[i]);
+        if (donts[i])
+            fence("dont", donts[i]);
+    }
+    for (const o of other)
+        fence("example", o);
+    return out;
+}
+function propLine(name, p) {
+    const type = p.values ? p.values.map((v) => `"${v}"`).join(" | ") : p.type;
+    const bits = [`\`${name}${p.required ? "" : "?"}\`: \`${type}\``];
+    if (p.default !== undefined)
+        bits.push(`default \`${p.default}\``);
+    if (p.deprecated !== undefined)
+        bits.push(`deprecated${p.deprecated ? `: ${p.deprecated}` : ""}`);
+    let line = bits.join(", ");
+    if (p.description)
+        line += `. ${p.description.replace(/\s*\n\s*/g, " ")}`;
+    return line;
+}
+// ------------------------------------------------------------ tokens
+const TIER_TITLES = [
+    ["spacing", "Spacing"],
+    ["size", "Size"],
+    ["radius", "Radius"],
+    ["shadow", "Shadow"],
+    ["duration", "Duration"],
+    ["ease", "Easing"],
+    ["motion", "Motion"],
+];
+export function coloursMarkdown(tokens) {
+    const out = ["## Colour", "", "Write the semantic names in components (`bg-primary text-primary-foreground`). The ramps are what they point at.", ""];
+    out.push("| Token | Light | Dark |", "| --- | --- | --- |");
+    for (const c of semanticColours(tokens)) {
+        out.push(`| \`${c.name}\`${c.foreground ? ` with \`${c.foreground.name}\`` : ""} | ${cell(valueIn(c.background, "light"))} | ${cell(valueIn(c.background, "dark"))} |`);
+    }
+    out.push("");
+    for (const ramp of ramps(tokens))
+        out.push(`- ${ramp.family}: ${ramp.steps.map((s) => s.step).join(", ")}`);
+    return end(out);
+}
+export function typeMarkdown(tokens) {
+    const out = ["## Type", "", "| Size | Value | Line height |", "| --- | --- | --- |"];
+    for (const s of typeScale(tokens))
+        out.push(`| \`text-${shortName(s.size, "text")}\` | ${cell(s.size.values.default)} | ${cell(s.lineHeight?.values.default)} |`);
+    for (const [tier, title] of [["font", "Families"], ["font-weight", "Weights"], ["leading", "Leading"], ["tracking", "Tracking"]]) {
+        const rows = tokensOfTier(tokens, tier);
+        if (rows.length)
+            out.push("", `${title}: ${rows.map((t) => `\`${shortName(t, tier)}\` ${t.values.default}`).join(", ")}`);
+    }
+    return end(out);
+}
+export function scaleMarkdown(tokens) {
+    const out = ["## Scale", ""];
+    for (const [tier, title] of TIER_TITLES) {
+        const rows = tokensOfTier(tokens, tier);
+        if (!rows.length)
+            continue;
+        out.push(`### ${title}`, "", "| Token | Value | Notes |", "| --- | --- | --- |");
+        for (const t of rows)
+            out.push(`| \`${t.name}\` | ${cell(t.values.default)} | ${cell(t.description)} |`);
+        out.push("");
+    }
+    return end(out);
+}
+// ------------------------------------------------------------ rules, patterns, taxonomy, brand
+export function ruleMarkdown(rule) {
+    const out = [`### ${rule.title}`, "", `\`\`\`rule id=${rule.id} kind=${rule.kind} status=${rule.status}`, rule.statement, "```", ""];
+    if (rule.threshold)
+        out.push(`- Threshold: ${rule.threshold}`);
+    if (rule.appliesTo?.length)
+        out.push(`- Applies to: ${rule.appliesTo.join(", ")}`);
+    if (rule.exceptions?.length)
+        out.push(`- Exceptions: ${rule.exceptions.join("; ")}`);
+    if (rule.tokens?.length)
+        out.push(`- Tokens: ${rule.tokens.map((t) => `\`${t}\``).join(", ")}`);
+    if (rule.check)
+        out.push(`- Checked by: ${rule.check.kind}${rule.check.ref ? ` (\`${rule.check.ref}\`)` : ""}${rule.check.description ? `. ${rule.check.description}` : ""}`);
+    if (rule.status === "assumption")
+        out.push("- Still an assumption: say so when you rely on it.");
+    if (out[out.length - 1] !== "")
+        out.push("");
+    if (rule.rationale)
+        out.push(rule.rationale, "");
+    return end(out);
+}
+/** A pattern; `level` as for `componentMarkdown`. */
+export function patternMarkdown(pattern, level = 2) {
+    const out = [`${"#".repeat(level)} ${pattern.name}`, "", `Status: ${pattern.status ?? "not set"}`, ""];
+    if (pattern.description)
+        out.push(pattern.description, "");
+    if (pattern.components.length)
+        out.push(`Composes: ${pattern.components.join(", ")}`, "");
+    for (const ex of pattern.examples) {
+        if (ex.description)
+            out.push(ex.description);
+        out.push(`\`\`\`example ${ex.name}`, ex.code ?? `// ${ex.name}`, "```", "");
+    }
+    return end(out);
+}
+export function glossaryMarkdown(terms) {
+    const out = ["## Vocabulary", "", "| Say | Not | Kind | Note |", "| --- | --- | --- | --- |"];
+    for (const t of terms)
+        out.push(`| ${t.name} | ${cell(t.wrong?.join(", "))} | ${t.kind} | ${cell(t.note)} |`);
+    return end(out);
+}
+export function assetsMarkdown(assets) {
+    const out = ["## Brand assets", "", "| Asset | Kind | Minimum size | Clear space | Surfaces | Usage |", "| --- | --- | --- | --- | --- | --- |"];
+    for (const a of assets) {
+        out.push(`| ${a.name} (\`${a.file}\`) | ${a.kind} | ${cell(a.minSize)} | ${cell(a.clearSpace)} | ${cell(a.surfaces?.join(", "))} | ${cell(a.usage)} |`);
+    }
+    return end(out);
+}
+/** `.mxa/stack.json` baselines, or anything shaped like them: a table of name and target. */
+export function standardsMarkdown(baselines) {
+    const out = ["## Standards", ""];
+    for (const section of standardsSections(baselines)) {
+        out.push(`### ${section.title}`, "");
+        for (const row of section.rows)
+            out.push(row.label ? `- ${row.label}: ${row.value}` : row.value);
+        if (section.rows.length)
+            out.push("");
+        for (const note of section.notes)
+            out.push(note, "");
+    }
+    return end(out);
+}
+/** The adherence report, as a page: totals, then routes. It informs; it never blocks. */
+export function adherenceMarkdown(report) {
+    const pct = (v) => (v === null ? "n/a" : `${Math.round(v * 1000) / 10}%`);
+    const s = report.summary;
+    const out = [
+        "## Adherence",
+        "",
+        "A report, never a gate.",
+        "",
+        `- From the system: ${pct(s.share)} (${s.systemUses} system uses, ${s.rawElements} raw elements a component replaces)`,
+        `- Off-system values: ${s.offSystemValues} (${s.offSystem.palette} palette steps, ${s.offSystem.arbitrary} arbitrary values, ${s.offSystem["status-text"] ?? 0} status colours as text)`,
+        `- Overrides: ${s.overrides}`,
+        `- Components never used: ${s.componentsUnused.length ? s.componentsUnused.join(", ") : "none"}`,
+        "",
+    ];
+    if (report.routes.length) {
+        out.push("| Route | From the system | Raw | Off-system | Overrides |", "| --- | --- | --- | --- | --- |");
+        for (const r of report.routes)
+            out.push(`| \`${r.route}\` | ${pct(r.counts.share)} | ${r.counts.rawElements} | ${r.counts.offSystemValues} | ${r.counts.overrides} |`);
+    }
+    return end(out);
+}
+// ------------------------------------------------------------ the whole system
+/** Everything an agent needs, in one file: tokens first, then rules, patterns and components by category. */
+export function systemMarkdown(input, title = "Design system", provenance) {
+    const out = [`# ${title}`, ""];
+    if (provenance)
+        out.push(generatedHeader(provenance).trimEnd(), "");
+    out.push(`Generated from \`${input.components.system}/manifest\`. Build screens from these components and tokens; do not restyle them with raw values. Carry each thing's status when you quote it.`, "");
+    if (input.tokens)
+        out.push(coloursMarkdown(input.tokens), typeMarkdown(input.tokens), scaleMarkdown(input.tokens));
+    if (input.rules?.length)
+        out.push("# Rules", "", ...input.rules.map(ruleMarkdown));
+    if (input.patterns?.length)
+        out.push("# Patterns", "", ...input.patterns.map((p) => patternMarkdown(p)));
+    for (const group of groupByCategory(input.components))
+        out.push(`# ${group.category}`, "", ...group.components.map((c) => componentMarkdown(c)));
+    if (input.terms?.length)
+        out.push(glossaryMarkdown(input.terms));
+    return end(out);
+}
+/** Links an agent outside the repo can follow to the exact data. */
+export function manifestLinks(base) {
+    return end([
+        "## The manifest, as data",
+        "",
+        ...["components", "tokens", "rules", "patterns", "taxonomy", "assets"].map((f) => `- [${f}.json](${base}/${f}.json)`),
+    ]);
+}
+export { slugOf };
+// ------------------------------------------------------------ helpers
+function cell(value) {
+    if (value === undefined || value === null || value === "")
+        return "";
+    return String(value).replace(/\|/g, "\\|").replace(/\s*\n\s*/g, " ");
+}
+function end(lines) {
+    return lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}

package/dist/lib/measure.d.ts

@@ -0,0 +1,12 @@
+import { type RefObject } from "react";
+/**
+ * Point at anything in the preview to see its box: the element outlined with its
+ * size, its padding tinted inside it and its margin tinted outside, each side
+ * labelled where it is not zero. Drawn over `area`, measuring elements inside
+ * `target`. Colours are the docs' own: margin in warning, padding in success, the
+ * box in the focus ring.
+ */
+export declare function Measure({ area, target }: {
+    area: RefObject<HTMLElement | null>;
+    target: RefObject<HTMLElement | null>;
+}): import("react").JSX.Element | null;

package/dist/lib/measure.js

@@ -0,0 +1,62 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+const px = (v) => Number.parseFloat(v) || 0;
+const round = (n) => Math.round(n * 10) / 10;
+/**
+ * Point at anything in the preview to see its box: the element outlined with its
+ * size, its padding tinted inside it and its margin tinted outside, each side
+ * labelled where it is not zero. Drawn over `area`, measuring elements inside
+ * `target`. Colours are the docs' own: margin in warning, padding in success, the
+ * box in the focus ring.
+ */
+export function Measure({ area, target }) {
+    const [box, setBox] = useState(null);
+    useEffect(() => {
+        const host = area.current;
+        if (!host)
+            return;
+        const move = (e) => {
+            const inside = target.current;
+            const el = e.target instanceof HTMLElement || e.target instanceof SVGElement ? e.target : null;
+            if (!inside || !el || !inside.contains(el) || el === inside)
+                return setBox(null);
+            const r = el.getBoundingClientRect();
+            const origin = host.getBoundingClientRect();
+            const s = getComputedStyle(el);
+            setBox({
+                tag: el.tagName.toLowerCase(),
+                x: r.left - origin.left + host.scrollLeft,
+                y: r.top - origin.top + host.scrollTop,
+                w: r.width,
+                h: r.height,
+                padding: [px(s.paddingTop), px(s.paddingRight), px(s.paddingBottom), px(s.paddingLeft)],
+                margin: [px(s.marginTop), px(s.marginRight), px(s.marginBottom), px(s.marginLeft)],
+            });
+        };
+        const leave = () => setBox(null);
+        host.addEventListener("pointermove", move);
+        host.addEventListener("pointerleave", leave);
+        return () => {
+            host.removeEventListener("pointermove", move);
+            host.removeEventListener("pointerleave", leave);
+        };
+    }, [area, target]);
+    if (!box)
+        return null;
+    const [pt, pr, pb, pl] = box.padding;
+    const [mt, mr, mb, ml] = box.margin;
+    const tint = (token) => `color-mix(in oklch, var(${token}) 32%, transparent)`;
+    const label = "absolute rounded-sm bg-canvas-foreground px-1 font-mono text-[0.625rem] leading-4 text-canvas whitespace-nowrap";
+    return (_jsxs("div", { "aria-hidden": true, "data-slot": "measure", className: "pointer-events-none absolute inset-0 z-20", children: [_jsx("div", { className: "absolute border-solid", style: {
+                    left: box.x - ml,
+                    top: box.y - mt,
+                    width: box.w + ml + mr,
+                    height: box.h + mt + mb,
+                    borderColor: tint("--warning"),
+                    borderWidth: `${mt}px ${mr}px ${mb}px ${ml}px`,
+                } }), _jsx("div", { className: "absolute border-solid", style: { left: box.x, top: box.y, width: box.w, height: box.h, borderColor: tint("--success"), borderWidth: `${pt}px ${pr}px ${pb}px ${pl}px` } }), _jsx("div", { className: "absolute outline-1 outline-[var(--ring)] outline-solid", style: { left: box.x, top: box.y, width: box.w, height: box.h } }), _jsxs("span", { className: label, style: { left: box.x, top: Math.max(0, box.y - mt - 18) }, children: [box.tag, " \u00B7 ", round(box.w), " \u00D7 ", round(box.h)] }), pt > 0 && _jsx(Side, { className: label, x: box.x + box.w / 2, y: box.y + pt / 2, value: pt }), pb > 0 && _jsx(Side, { className: label, x: box.x + box.w / 2, y: box.y + box.h - pb / 2, value: pb }), pl > 0 && _jsx(Side, { className: label, x: box.x + pl / 2, y: box.y + box.h / 2, value: pl }), pr > 0 && _jsx(Side, { className: label, x: box.x + box.w - pr / 2, y: box.y + box.h / 2, value: pr })] }));
+}
+function Side({ className, x, y, value }) {
+    return (_jsx("span", { className: className, style: { left: x, top: y, transform: "translate(-50%, -50%)" }, children: round(value) }));
+}

package/dist/lib/pseudo.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Pinned states. A pointer cannot be faked, so instead every `:hover`, `:focus`
+ * and `:active` rule on the page gets a twin that applies inside an element
+ * carrying `data-pseudo="hover"` (or `focus`, `active`; space-separated for more
+ * than one). The twin sits beside the original, in the same layer and media
+ * query, so it wins and loses exactly where the real state would. This is how
+ * Storybook's pseudo-states addon works, done in the browser with no build step.
+ */
+export type Pseudo = "hover" | "focus" | "active";
+/** Adds the twins to every stylesheet not yet seen. Cheap to call again: it runs once per sheet, and again only for sheets added since. */
+export declare function installPseudoStates(): void;

package/dist/lib/pseudo.js

@@ -0,0 +1,71 @@
+/**
+ * Pinned states. A pointer cannot be faked, so instead every `:hover`, `:focus`
+ * and `:active` rule on the page gets a twin that applies inside an element
+ * carrying `data-pseudo="hover"` (or `focus`, `active`; space-separated for more
+ * than one). The twin sits beside the original, in the same layer and media
+ * query, so it wins and loses exactly where the real state would. This is how
+ * Storybook's pseudo-states addon works, done in the browser with no build step.
+ */
+const PATTERNS = [
+    ["hover", /:hover(?![-\w])/g],
+    ["focus", /:focus-visible(?![-\w])/g],
+    ["focus", /:focus(?![-\w])/g],
+    ["active", /:active(?![-\w])/g],
+];
+/** A state inside :not(), :has(), :is() or :where() changes what the selector means when removed, so those are left alone. */
+const NESTED = /:(?:not|has|is|where)\([^)]*:(?:hover|focus|active)/;
+const done = new WeakSet();
+/** Adds the twins to every stylesheet not yet seen. Cheap to call again: it runs once per sheet, and again only for sheets added since. */
+export function installPseudoStates() {
+    for (const sheet of Array.from(document.styleSheets)) {
+        if (done.has(sheet))
+            continue;
+        try {
+            walk(sheet);
+            done.add(sheet);
+        }
+        catch {
+            // a stylesheet from another origin cannot be read; its states stay unpinnable
+        }
+    }
+}
+function walk(parent) {
+    const rules = parent.cssRules;
+    // backwards, so a twin inserted after its rule never shifts the rules still to visit
+    for (let i = rules.length - 1; i >= 0; i--) {
+        const rule = rules[i];
+        if (rule instanceof CSSStyleRule) {
+            const twin = twinOf(rule.selectorText);
+            if (twin) {
+                try {
+                    parent.insertRule(`${twin} { ${rule.style.cssText} }`, i + 1);
+                }
+                catch {
+                    // a selector the browser will not take back (a vendor pseudo-element): skip it
+                }
+            }
+            if (rule.cssRules?.length)
+                walk(rule);
+        }
+        else if ("cssRules" in rule) {
+            walk(rule);
+        }
+    }
+}
+function twinOf(selector) {
+    const out = [];
+    // split on commas that are not inside parentheses
+    for (const part of selector.split(/,(?![^(]*\))/)) {
+        if (NESTED.test(part))
+            continue;
+        for (const [state, pattern] of PATTERNS) {
+            pattern.lastIndex = 0;
+            if (!pattern.test(part))
+                continue;
+            const rest = part.replace(pattern, "").trim();
+            out.push(`:where([data-pseudo~="${state}"]) ${rest || "*"}`);
+            break;
+        }
+    }
+    return out.length ? out.join(", ") : null;
+}

package/dist/lib/registry.d.ts

@@ -0,0 +1,21 @@
+import { type ComponentType, type ReactNode } from "react";
+/**
+ * Everything the docs render that lives in the project: each component, examples
+ * module, pattern module and brand asset, keyed the way the manifest names them.
+ * The project's generated registry (`designtools-docs map`) imports them and
+ * renders a `RegistryProvider` around the docs; a server page cannot hand a
+ * component to a client block, so this is how the blocks reach them.
+ */
+export interface Registry {
+    components: Record<string, ComponentType<any>>;
+    examples: Record<string, Record<string, unknown>>;
+    patterns: Record<string, Record<string, unknown>>;
+    assets: Record<string, string | {
+        src: string;
+    }>;
+}
+export declare function RegistryProvider({ value, children }: {
+    value: Registry;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useRegistry(): Registry;

package/dist/lib/registry.js

@@ -0,0 +1,11 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const EMPTY = { components: {}, examples: {}, patterns: {}, assets: {} };
+const RegistryContext = createContext(EMPTY);
+export function RegistryProvider({ value, children }) {
+    return _jsx(RegistryContext.Provider, { value: value, children: children });
+}
+export function useRegistry() {
+    return useContext(RegistryContext);
+}

package/dist/lib/search.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The docs search: components, their parts, rules, patterns and pages, matched
+ * fuzzily on their names, with the taxonomy's wrong forms as aliases, so
+ * "dropdown" finds Select and "buton" finds Button. It aids navigation and does
+ * nothing else: no full text, no index to build, because the manifest is small
+ * enough to search in the browser. The same query always gives the same order.
+ */
+import type { ComponentsManifest, PatternEntry, RuleEntry, TermEntry } from "./manifest-types.js";
+export type SearchKind = "Component" | "Rule" | "Pattern" | "Page";
+export interface SearchItem {
+    kind: SearchKind;
+    label: string;
+    href: string;
+    /** The taxonomy's wrong forms for it: typing one finds it, and the result says so. */
+    wrong: string[];
+    /** Anything else it answers to quietly, such as a rule's id. */
+    also?: string[];
+    /** One short line under the label: a category, "part of Card", a rule's kind. */
+    detail?: string;
+}
+export interface SearchGroup {
+    kind: SearchKind;
+    /** `matched` is the wrong form a result was found by ("Dropdown" for Select). */
+    items: (SearchItem & {
+        matched?: string;
+    })[];
+}
+export declare function searchIndex({ manifest, rules, patterns, terms, pages, basePath, }: {
+    manifest: ComponentsManifest;
+    rules?: RuleEntry[];
+    patterns?: PatternEntry[];
+    terms?: TermEntry[];
+    pages?: {
+        label: string;
+        href: string;
+    }[];
+    basePath?: string;
+}): SearchItem[];
+/**
+ * The matches for a query, grouped by kind (components, rules, patterns, pages),
+ * best first within each, at most `perGroup` of each. A match found only through
+ * an alias says which: `matched` is the wrong form typed ("Dropdown").
+ */
+export declare function search(items: SearchItem[], query: string, perGroup?: number): SearchGroup[];

package/dist/lib/search.js

@@ -0,0 +1,62 @@
+/**
+ * The docs search: components, their parts, rules, patterns and pages, matched
+ * fuzzily on their names, with the taxonomy's wrong forms as aliases, so
+ * "dropdown" finds Select and "buton" finds Button. It aids navigation and does
+ * nothing else: no full text, no index to build, because the manifest is small
+ * enough to search in the browser. The same query always gives the same order.
+ */
+import fuzzysort from "fuzzysort";
+import { groupFamilies, slugOf } from "./manifest.js";
+const ORDER = ["Component", "Rule", "Pattern", "Page"];
+export function searchIndex({ manifest, rules = [], patterns = [], terms = [], pages = [], basePath = "/design/system", }) {
+    const wrong = new Map();
+    for (const t of terms)
+        if (t.wrong?.length)
+            wrong.set(t.name.toLowerCase(), t.wrong);
+    const wrongOf = (name) => wrong.get(name.toLowerCase()) ?? [];
+    const items = [];
+    for (const { category, families } of groupFamilies(manifest)) {
+        for (const { head, parts } of families) {
+            items.push({ kind: "Component", label: head.name, href: `${basePath}/components/${slugOf(head)}`, wrong: wrongOf(head.name), detail: category });
+            for (const p of parts) {
+                items.push({ kind: "Component", label: p.name, href: `${basePath}/components/${slugOf(p)}`, wrong: wrongOf(p.name), detail: `part of ${head.name}` });
+            }
+        }
+    }
+    for (const r of rules) {
+        items.push({ kind: "Rule", label: r.title, href: `${basePath}/rules#${r.id}`, wrong: wrongOf(r.title), also: [r.id.replace(/-/g, " ")], detail: r.kind === "brand" ? "Brand rule" : "Interface rule" });
+    }
+    for (const p of patterns)
+        items.push({ kind: "Pattern", label: p.name, href: `${basePath}/patterns/${p.id}`, wrong: wrongOf(p.name) });
+    for (const p of pages)
+        items.push({ kind: "Page", label: p.label, href: p.href, wrong: [] });
+    return items;
+}
+/**
+ * The matches for a query, grouped by kind (components, rules, patterns, pages),
+ * best first within each, at most `perGroup` of each. A match found only through
+ * an alias says which: `matched` is the wrong form typed ("Dropdown").
+ */
+export function search(items, query, perGroup = 6) {
+    const q = query.trim();
+    if (!q)
+        return [];
+    const results = fuzzysort.go(q, items, { keys: ["label", (item) => item.wrong.join(" / "), (item) => (item.also ?? []).join(" / ")], limit: 0, threshold: 0.3 });
+    const ranked = [...results].sort((a, b) => b.score - a.score || ORDER.indexOf(a.obj.kind) - ORDER.indexOf(b.obj.kind) || (a.obj.label < b.obj.label ? -1 : a.obj.label > b.obj.label ? 1 : 0));
+    return ORDER.map((kind) => ({
+        kind,
+        items: ranked
+            .filter((r) => r.obj.kind === kind)
+            .slice(0, perGroup)
+            .map((r) => {
+            const viaWrong = (r[1]?.score ?? 0) > Math.max(r[0]?.score ?? 0, r[2]?.score ?? 0);
+            // the wrong form that matched best, to say why a result is here ("Dropdown" for Select)
+            const alias = viaWrong
+                ? r.obj.wrong
+                    .map((a) => ({ a, score: fuzzysort.single(q, a)?.score ?? 0 }))
+                    .sort((x, y) => y.score - x.score)[0]?.a
+                : undefined;
+            return alias ? { ...r.obj, matched: alias } : r.obj;
+        }),
+    })).filter((g) => g.items.length > 0);
+}

package/dist/lib/standards.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The baselines a project records (`.mxa/stack.json` `baselines`), as a person
+ * reads them: titled sections, labelled rows, notes as sentences, and nothing
+ * shown for a value nobody has set. One shape, so the page and its markdown agree.
+ */
+export interface StandardsSection {
+    key: string;
+    title: string;
+    rows: {
+        label: string;
+        value: string;
+    }[];
+    notes: string[];
+}
+/** `textSize` to "Text size", `aiCrawlable` to "Ai crawlable": a fallback, never as good as a title. */
+export declare function humanise(key: string): string;
+export declare function standardsSections(baselines: Record<string, unknown>): StandardsSection[];