@designtools/docs 0.0.0-stage → 0.2.0

package/dist/next/site.js

@@ -0,0 +1,136 @@
+import { findBySlug, readComponents, readTokens, slugOf } from "../lib/manifest.js";
+export function siteOf(config) {
+    const hidden = new Set(config.hide ?? []);
+    return {
+        config,
+        base: (config.basePath ?? "/design/system").replace(/\/$/, ""),
+        title: config.title,
+        components: readComponents(config.manifest.components),
+        tokens: readTokens(config.manifest.tokens),
+        rules: config.manifest.rules ?? { rules: [] },
+        patterns: config.manifest.patterns ?? { patterns: [] },
+        taxonomy: config.manifest.taxonomy ?? { terms: [] },
+        assets: config.manifest.assets ?? { assets: [] },
+        editorial: config.editorial ?? [],
+        shows: (page) => !hidden.has(page),
+    };
+}
+const BUILT_IN = {
+    "brand/logo": "logo",
+    "brand/imagery": "imagery",
+    "brand/voice": "voice",
+    colour: "colour",
+    type: "type",
+    scale: "scale",
+    rules: "rules",
+    standards: "standards",
+    vocabulary: "vocabulary",
+};
+/** Whether a built-in page has anything to show, as well as not being hidden. */
+function has(site, kind) {
+    return site.shows(kind) && KIND_NEEDS[kind](site);
+}
+const KIND_NEEDS = {
+    logo: (s) => s.assets.assets.some((a) => a.kind === "logo"),
+    imagery: (s) => s.assets.assets.some((a) => a.kind !== "logo"),
+    voice: (s) => s.taxonomy.terms.some((t) => t.kind === "product" || t.wrong?.length),
+    colour: () => true,
+    type: () => true,
+    scale: () => true,
+    rules: (s) => s.rules.rules.length > 0,
+    standards: (s) => !!s.config.baselines || !!s.config.adherence,
+    vocabulary: (s) => s.taxonomy.terms.length > 0,
+};
+/** The page at a path under the docs, or nothing. */
+export function resolve(site, slug = []) {
+    const path = slug.join("/");
+    if (!path)
+        return { kind: "overview" };
+    const editorial = site.editorial.find((p) => p.slug === path);
+    if (editorial)
+        return { kind: "editorial", page: editorial };
+    const builtIn = BUILT_IN[path];
+    if (builtIn)
+        return has(site, builtIn) ? { kind: builtIn } : undefined;
+    const [section, id] = slug;
+    if (section === "components" && id && site.shows("components")) {
+        const entry = findBySlug(site.components, id);
+        return entry ? { kind: "component", entry } : undefined;
+    }
+    if (section === "patterns" && id && site.shows("patterns")) {
+        const pattern = site.patterns.patterns.find((p) => p.id === id);
+        return pattern ? { kind: "pattern", pattern } : undefined;
+    }
+    return undefined;
+}
+/** Every page's path, for static generation. */
+export function allSlugs(site) {
+    const out = [[]];
+    for (const p of site.editorial)
+        out.push(p.slug.split("/"));
+    for (const [path, kind] of Object.entries(BUILT_IN))
+        if (has(site, kind))
+            out.push(path.split("/"));
+    if (site.shows("components"))
+        for (const c of site.components.components)
+            out.push(["components", slugOf(c)]);
+    if (site.shows("patterns"))
+        for (const p of site.patterns.patterns)
+            out.push(["patterns", p.id]);
+    return out;
+}
+/** The navigation's editorial and generated groups: brand, foundations, standards. Rules, patterns and components the shell adds from the manifest. */
+export function navOf(site) {
+    const link = (label, path) => ({ label, href: `${site.base}/${path}` });
+    const written = (section) => site.editorial.filter((p) => (p.section ?? "brand") === section).map((p) => link(p.nav ?? p.title, p.slug));
+    return {
+        brand: [
+            ...written("brand"),
+            ...(has(site, "logo") ? [link("Logo", "brand/logo")] : []),
+            ...(has(site, "imagery") ? [link("Imagery and icons", "brand/imagery")] : []),
+            ...(has(site, "voice") ? [link("Voice and terms", "brand/voice")] : []),
+        ],
+        foundations: [...written("foundations"), link("Colour", "colour"), link("Type", "type"), link("Scale", "scale")].filter((l) => !["colour", "type", "scale"].some((k) => l.href.endsWith(`/${k}`) && !site.shows(k))),
+        standards: [
+            ...written("standards"),
+            ...(has(site, "standards") ? [link("Standards", "standards")] : []),
+            ...(has(site, "vocabulary") ? [link("Vocabulary", "vocabulary")] : []),
+        ],
+    };
+}
+/** Each built-in page's title and lead: what the page says it is, which is also its description. */
+export const COPY = {
+    logo: { title: "Logo", lead: "Each logo on the surfaces it may sit on, at its smallest, with its clear space." },
+    imagery: { title: "Imagery and icons", lead: "The approved icons and imagery, and how to use each." },
+    voice: { title: "Voice and terms", lead: "The words we use, beside the ones we do not." },
+    colour: {
+        title: "Colour",
+        lead: "Generated from the brand colour by @designtools/tokens. Write the semantic names in components; the ramps are what they point at.",
+    },
+    type: { title: "Type", lead: "Each family, then the scale: a size is never set without its leading." },
+    scale: { title: "Scale", lead: "Space, size, radius, elevation and motion, each drawn the way it is used." },
+    rules: {
+        title: "Rules",
+        lead: "Brand and interface rules in one format, each with the check that proves it. Written for people; agents read the same rule.",
+    },
+    standards: {
+        title: "Standards",
+        lead: "The budgets and targets the project holds itself to, read from .mxa/stack.json, where the checks read them too.",
+    },
+    vocabulary: { title: "Vocabulary", lead: "Every name in the system. Search by a wrong name and it finds the right one." },
+};
+/** A page's title and description, for its metadata. */
+export function metaOf(site, ref) {
+    switch (ref.kind) {
+        case "overview":
+            return { title: site.title, description: site.config.lead ?? `${site.title}: the brand and the design system in one place.` };
+        case "editorial":
+            return { title: ref.page.title, description: ref.page.lead };
+        case "component":
+            return { title: `${ref.entry.name} · Components`, description: ref.entry.description };
+        case "pattern":
+            return { title: `${ref.pattern.name} · Patterns`, description: ref.pattern.description };
+        default:
+            return { title: COPY[ref.kind].title, description: COPY[ref.kind].lead };
+    }
+}

package/dist/page-actions.d.ts

@@ -0,0 +1,9 @@
+/**
+ * What a reader can take from a page, as one split button: copy the page as
+ * markdown, the same markdown any agent gets at `.md`, with a menu beside it to
+ * view that markdown, copy the whole system as one file, or open the manifest.
+ * Put it in a `DocsHeader`.
+ */
+export declare function PageActions({ basePath }: {
+    basePath?: string;
+}): import("react").JSX.Element;

package/dist/page-actions.js

@@ -0,0 +1,32 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Menu } from "@base-ui/react/menu";
+import { Braces, Check, ChevronDown, Copy, FileText, Files } from "lucide-react";
+import { usePathname } from "next/navigation";
+import { useState } from "react";
+/**
+ * What a reader can take from a page, as one split button: copy the page as
+ * markdown, the same markdown any agent gets at `.md`, with a menu beside it to
+ * view that markdown, copy the whole system as one file, or open the manifest.
+ * Put it in a `DocsHeader`.
+ */
+export function PageActions({ basePath = "/design/system" }) {
+    const path = usePathname().replace(/\/$/, "");
+    const [done, setDone] = useState(null);
+    const copyFrom = async (url, what) => {
+        try {
+            const res = await fetch(url);
+            if (!res.ok)
+                throw new Error(String(res.status));
+            await navigator.clipboard.writeText(await res.text());
+            setDone(what);
+        }
+        catch {
+            setDone("Could not copy");
+        }
+        setTimeout(() => setDone(null), 1600);
+    };
+    const item = "flex min-h-(--docs-target,2.75rem) cursor-pointer items-center gap-3 rounded-md px-3 text-sm outline-none select-none data-highlighted:bg-muted";
+    const icon = "size-4 shrink-0 text-muted-foreground";
+    return (_jsxs("div", { "data-slot": "page-actions", className: "inline-flex items-stretch rounded-lg border border-border bg-canvas text-sm shadow-xs", children: [_jsxs("button", { type: "button", onClick: () => copyFrom(`${path}.md`, "Page copied"), className: "inline-flex min-h-9 cursor-pointer items-center gap-2 rounded-l-lg py-1.5 pr-3 pl-3 font-medium hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring", children: [done === "Page copied" ? _jsx(Check, { "aria-hidden": true, className: "size-4" }) : _jsx(Copy, { "aria-hidden": true, className: icon }), done === "Page copied" ? "Copied" : "Copy page"] }), _jsxs(Menu.Root, { children: [_jsx(Menu.Trigger, { "aria-label": "More ways to take this page", className: "inline-flex min-h-9 w-9 cursor-pointer items-center justify-center rounded-r-lg border-l border-border text-muted-foreground hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring data-popup-open:bg-muted", children: _jsx(ChevronDown, { "aria-hidden": true, className: "size-4" }) }), _jsx(Menu.Portal, { children: _jsx(Menu.Positioner, { "data-designtools": "", align: "end", sideOffset: 6, className: "z-50", children: _jsxs(Menu.Popup, { className: "w-72 rounded-xl border border-border bg-overlay p-1.5 text-overlay-foreground shadow-lg transition-[opacity,scale] duration-(--dt-duration-fast) data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0", children: [_jsxs(Menu.Item, { className: item, onClick: () => copyFrom(`${path}.md`, "Page copied"), children: [_jsx(Copy, { "aria-hidden": true, className: icon }), _jsxs("span", { className: "flex flex-col", children: ["Copy page", _jsx("span", { className: "text-xs text-muted-foreground", children: "As markdown, for an assistant" })] })] }), _jsxs(Menu.LinkItem, { className: item, href: `${path}.md`, target: "_blank", rel: "noreferrer", children: [_jsx(FileText, { "aria-hidden": true, className: icon }), _jsxs("span", { className: "flex flex-col", children: ["View as markdown", _jsx("span", { className: "text-xs text-muted-foreground", children: "What an agent reads at this address" })] })] }), _jsx(Menu.Separator, { className: "my-1.5 h-px bg-border" }), _jsxs(Menu.Item, { className: item, onClick: () => copyFrom(`${basePath}/context.md`, "System copied"), children: [_jsx(Files, { "aria-hidden": true, className: icon }), _jsxs("span", { className: "flex flex-col", children: ["Copy the whole system", _jsx("span", { className: "text-xs text-muted-foreground", children: "Every page in one markdown file" })] })] }), _jsxs(Menu.LinkItem, { className: item, href: `${basePath}/manifest/components.json`, target: "_blank", rel: "noreferrer", children: [_jsx(Braces, { "aria-hidden": true, className: icon }), _jsxs("span", { className: "flex flex-col", children: ["Open the manifest", _jsx("span", { className: "text-xs text-muted-foreground", children: "Components, tokens and rules as JSON" })] })] })] }) }) })] }), _jsx("span", { className: "sr-only", "aria-live": "polite", children: done ?? "" })] }));
+}

package/dist/pattern.d.ts

@@ -0,0 +1,11 @@
+import type { ComponentsManifest, PatternEntry } from "./lib/manifest-types.js";
+/**
+ * A recurring screen composition: each composition live in its frame, with its code, then the
+ * components it is made of, each linking to its page. Its status sits in the page header.
+ */
+export declare function Pattern({ pattern, manifest, basePath, }: {
+    pattern: PatternEntry;
+    /** To link the components it uses to their pages. */
+    manifest?: ComponentsManifest;
+    basePath?: string;
+}): import("react").JSX.Element;

package/dist/pattern.js

@@ -0,0 +1,22 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import Link from "next/link";
+import { ExampleFrame } from "./examples.js";
+import { Missing, renderExample, useLookup } from "./lib/lookup.js";
+import { slugOf } from "./lib/manifest.js";
+import { StatusBadge } from "./lib/status.js";
+import { DocsSection } from "./shell.js";
+/**
+ * A recurring screen composition: each composition live in its frame, with its code, then the
+ * components it is made of, each linking to its page. Its status sits in the page header.
+ */
+export function Pattern({ pattern, manifest, basePath = "/design/system", }) {
+    const lookup = useLookup();
+    const module = lookup.compositionsFor(pattern);
+    const known = new Map((manifest?.components ?? []).map((c) => [c.name, c]));
+    return (_jsxs(_Fragment, { children: [_jsx("div", { "data-slot": "pattern", className: "flex flex-col gap-10", children: !module ? (_jsx(Missing, { name: pattern.name, what: "compositions" })) : (pattern.examples.map((ex, i) => (_jsx(ExampleFrame, { name: ex.name, kind: i === 0 ? "canonical" : "other", description: ex.description, code: ex.code, children: renderExample(module[ex.name], ex.name) }, ex.name)))) }), pattern.components.length > 0 && (_jsx(DocsSection, { title: "Made of", lead: "The system's own components, so the pattern changes when they do.", children: _jsx("ul", { "data-slot": "pattern-parts", className: "grid gap-x-10 sm:grid-cols-2", children: pattern.components.map((name) => {
+                        const c = known.get(name);
+                        const body = (_jsxs(_Fragment, { children: [_jsxs("span", { className: "flex items-center justify-between gap-3", children: [_jsx("span", { className: "text-lg tracking-tight underline-offset-4 group-hover:underline", children: name }), c && _jsx(StatusBadge, { status: c.status })] }), c?.description && _jsx("span", { className: "line-clamp-2 text-sm text-muted-foreground", children: c.description })] }));
+                        return (_jsx("li", { className: "border-t border-border", children: c ? (_jsx(Link, { href: `${basePath}/components/${slugOf(c)}`, className: "group flex flex-col gap-1.5 py-4 focus-visible:outline-2 focus-visible:outline-ring", children: body })) : (_jsx("span", { className: "flex flex-col gap-1.5 py-4", children: body })) }, name));
+                    }) }) }))] }));
+}

package/dist/playground.d.ts

@@ -0,0 +1,62 @@
+import type { ReactNode } from "react";
+import type { ComponentEntry, VariantAxis } from "./lib/manifest-types.js";
+/**
+ * The component, live, with controls generated from its variants and its own
+ * boolean props, and the JSX for exactly what is showing. Pass `props` for what
+ * it needs to render at all; the controls change everything else.
+ */
+export declare function Playground({ entry, props: base, children: initialText, }: {
+    entry: ComponentEntry;
+    props?: Record<string, unknown>;
+    /** Text content, editable in the playground. Pass "" for a component without children. */
+    children?: string;
+}): import("react").JSX.Element;
+/** Props passed only so the component renders (handlers, data) are left out of the snippet unless they are short. */
+export declare function visible(props: Record<string, unknown>): Record<string, unknown>;
+/** `variant` → `Variant`, `aria-label` → `Aria label`: a control reads as a setting, not a prop name. */
+export declare function title(name: string): string;
+/** A control's label, with the prop it sets and what its options mean behind an info button. */
+export declare function Label({ id, name, info, htmlFor }: {
+    id?: string;
+    name: string;
+    info?: ReactNode;
+    htmlFor?: string;
+}): import("react").JSX.Element;
+export declare function AxisControl({ axis, value, onChange }: {
+    axis: VariantAxis;
+    value: string;
+    onChange: (v: string) => void;
+}): import("react").JSX.Element;
+export declare function FlagControl({ name, checked, onChange }: {
+    name: string;
+    checked: boolean;
+    onChange: (v: boolean) => void;
+}): import("react").JSX.Element;
+export declare function TextControl({ value, onChange }: {
+    value: string;
+    onChange: (v: string) => void;
+}): import("react").JSX.Element;
+/** A number prop: a field with steppers. */
+export declare function NumberControl({ name, value, onChange, info }: {
+    name: string;
+    value: number | undefined;
+    onChange: (v: number | undefined) => void;
+    info?: ReactNode;
+}): import("react").JSX.Element;
+/** A string prop: a text field. */
+export declare function StringControl({ name, value, onChange, info }: {
+    name: string;
+    value: string;
+    onChange: (v: string) => void;
+    info?: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * An array or object prop (a Select's options): JSON, applied while it parses,
+ * and said plainly when it does not, so a half-typed edit never breaks the preview.
+ */
+export declare function JsonControl({ name, value, onChange, info }: {
+    name: string;
+    value: unknown;
+    onChange: (v: unknown) => void;
+    info?: ReactNode;
+}): import("react").JSX.Element;

package/dist/playground.js

@@ -0,0 +1,111 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Select } from "@base-ui/react/select";
+import { Switch } from "@base-ui/react/switch";
+import { Toggle } from "@base-ui/react/toggle";
+import { ToggleGroup } from "@base-ui/react/toggle-group";
+import { Tooltip } from "@base-ui/react/tooltip";
+import { Check, ChevronDown, Info, Moon, RotateCcw, SlidersHorizontal, Sun } from "lucide-react";
+import { useId, useState } from "react";
+import { CodeView } from "./code-view.js";
+import { Boundary } from "./lib/boundary.js";
+import { toJSX } from "./lib/jsx.js";
+import { coerce, Missing, useLookup } from "./lib/lookup.js";
+import { Frame, IconButton, Stage, Toolbar } from "./lib/ui.js";
+/**
+ * The component, live, with controls generated from its variants and its own
+ * boolean props, and the JSX for exactly what is showing. Pass `props` for what
+ * it needs to render at all; the controls change everything else.
+ */
+export function Playground({ entry, props: base = {}, children: initialText = entry.name, }) {
+    const lookup = useLookup();
+    const Component = lookup.componentFor(entry);
+    const axes = entry.variants?.axes ?? [];
+    const axisNames = new Set(axes.map((a) => a.name));
+    const flags = Object.entries(entry.props)
+        .filter(([name, p]) => !p.from && !axisNames.has(name) && p.type === "boolean" && p.deprecated === undefined)
+        .map(([name]) => name);
+    const [variants, setVariants] = useState({});
+    const [on, setOn] = useState({});
+    const [text, setText] = useState(initialText);
+    const [theme, setTheme] = useState();
+    if (!Component)
+        return _jsx(Missing, { name: entry.name });
+    const chosen = { ...coerce(variants), ...Object.fromEntries(Object.entries(on).filter(([, v]) => v)) };
+    const code = toJSX(entry.export, { ...visible(base), ...chosen }, text || undefined);
+    const changed = Object.keys(variants).length > 0 || Object.values(on).some(Boolean) || text !== initialText;
+    const reset = () => {
+        setVariants({});
+        setOn({});
+        setText(initialText);
+    };
+    return (_jsxs(Frame, { "data-slot": "playground", children: [_jsxs("div", { className: "grid lg:grid-cols-[minmax(0,1fr)_20rem]", children: [_jsxs("div", { className: "flex min-w-0 flex-col", children: [_jsxs(Toolbar, { children: [_jsxs("span", { className: "flex items-center gap-2 pl-2 text-xs font-medium text-muted-foreground", children: [_jsx(SlidersHorizontal, { "aria-hidden": true, className: "size-(--dt-size-xs)" }), "Live"] }), _jsxs("span", { className: "flex items-center gap-0.5", children: [_jsx(IconButton, { icon: theme === "dark" ? Sun : Moon, label: theme === "dark" ? "Show in light mode" : "Show in dark mode", pressed: theme !== undefined, onClick: () => setTheme(theme === "dark" ? "light" : "dark") }), _jsx(IconButton, { icon: RotateCcw, label: "Reset the controls", onClick: reset, disabled: !changed, className: "disabled:pointer-events-none disabled:opacity-40" })] })] }), _jsx(Stage, { theme: theme, "data-slot": "playground-preview", className: "min-h-72 flex-1", children: _jsx(Boundary, { label: entry.name, children: _jsx(Component, { ...base, ...chosen, children: text || undefined }) }) })] }), _jsxs("div", { "data-slot": "playground-controls", className: "flex flex-col gap-6 border-t border-border p-5 lg:border-t-0 lg:border-l", children: [axes.map((axis) => (_jsx(AxisControl, { axis: axis, value: variants[axis.name] ?? axis.default ?? "", onChange: (v) => setVariants((s) => ({ ...s, [axis.name]: v })) }, axis.name))), flags.map((name) => (_jsx(FlagControl, { name: name, checked: !!on[name], onChange: (v) => setOn((s) => ({ ...s, [name]: v })) }, name))), initialText !== "" && _jsx(TextControl, { value: text, onChange: setText }), axes.length === 0 && flags.length === 0 && initialText === "" && _jsx("p", { className: "text-sm text-muted-foreground", children: "Nothing to change: it has no variants or flags." })] })] }), _jsx("div", { className: "border-t border-border", children: _jsx(CodeView, { code: code, label: "JSX", bare: true }) })] }));
+}
+/** Props passed only so the component renders (handlers, data) are left out of the snippet unless they are short. */
+export function visible(props) {
+    return Object.fromEntries(Object.entries(props).filter(([, v]) => typeof v !== "function" && JSON.stringify(v ?? "").length <= 40));
+}
+/** `variant` → `Variant`, `aria-label` → `Aria label`: a control reads as a setting, not a prop name. */
+export function title(name) {
+    const words = name.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[-_]/g, " ").toLowerCase();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+/** Options fit one segmented row when there are few and their names are short; otherwise a menu. */
+const fitsSegments = (axis) => axis.options.length <= 4 && axis.options.reduce((n, o) => n + o.name.length, 0) <= 26;
+/** A control's label, with the prop it sets and what its options mean behind an info button. */
+export function Label({ id, name, info, htmlFor }) {
+    const text = (_jsx("span", { className: "text-sm font-medium", children: title(name) }));
+    return (_jsxs("div", { className: "flex items-center justify-between gap-2", children: [htmlFor ? (_jsx("label", { id: id, htmlFor: htmlFor, children: text })) : (_jsx("span", { id: id, children: text })), _jsxs(Tooltip.Root, { children: [_jsx(Tooltip.Trigger, { delay: 0, closeDelay: 0, "aria-label": `About ${title(name)}`, className: "relative inline-flex size-6 cursor-pointer items-center justify-center rounded-full text-muted-foreground hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring after:absolute after:-inset-2.5 after:content-['']", children: _jsx(Info, { "aria-hidden": true, className: "size-4" }) }), _jsx(Tooltip.Portal, { children: _jsx(Tooltip.Positioner, { "data-designtools": "", side: "left", sideOffset: 8, className: "z-50", children: _jsxs(Tooltip.Popup, { "data-slot": "docs-tooltip", className: "flex max-w-64 flex-col gap-1 rounded-md bg-canvas-foreground px-2.5 py-2 text-xs leading-snug text-canvas shadow-md transition-opacity duration-(--dt-duration-fast) data-ending-style:opacity-0 data-starting-style:opacity-0 [&_*]:text-canvas/80", children: [_jsx("code", { className: "font-mono font-medium text-canvas!", children: name }), info] }) }) })] })] }));
+}
+function AxisInfo({ axis }) {
+    const described = axis.options.filter((o) => o.description);
+    return (_jsxs(_Fragment, { children: [axis.default && _jsxs("span", { className: "text-muted-foreground", children: ["Default: ", axis.default] }), described.map((o) => (_jsxs("span", { children: [_jsx("span", { className: "font-medium", children: o.name }), ": ", _jsx("span", { className: "text-muted-foreground", children: o.description })] }, o.name)))] }));
+}
+export function AxisControl({ axis, value, onChange }) {
+    const id = useId();
+    if (fitsSegments(axis)) {
+        return (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Label, { id: id, name: axis.name, info: _jsx(AxisInfo, { axis: axis }) }), _jsx(ToggleGroup, { "aria-labelledby": id, value: value ? [value] : [], onValueChange: (next) => next[0] && onChange(String(next[0])), className: "grid grid-flow-col auto-cols-fr gap-0.5 rounded-lg bg-muted p-1", children: axis.options.map((o) => (_jsx(Toggle, { value: o.name, className: "relative h-8 min-w-0 cursor-pointer truncate rounded-md px-2 text-sm text-muted-foreground transition-colors duration-(--dt-duration-fast) after:absolute after:inset-x-0 after:-inset-y-1.5 after:content-[''] hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring data-[pressed]:bg-canvas data-[pressed]:font-medium data-[pressed]:text-canvas-foreground data-[pressed]:shadow-xs", children: title(o.name) }, o.name))) })] }));
+    }
+    return (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Label, { id: id, name: axis.name, info: _jsx(AxisInfo, { axis: axis }) }), _jsxs(Select.Root, { value: value, onValueChange: (v) => typeof v === "string" && onChange(v), children: [_jsxs(Select.Trigger, { "aria-labelledby": id, className: "flex h-10 cursor-pointer items-center justify-between rounded-lg bg-muted px-3 text-sm font-medium hover:bg-muted/70 focus-visible:outline-2 focus-visible:outline-ring", children: [_jsx(Select.Value, { children: (v) => title(v) }), _jsx(Select.Icon, { "aria-hidden": true, children: _jsx(ChevronDown, { className: "size-4 text-muted-foreground" }) })] }), _jsx(Select.Portal, { children: _jsx(Select.Positioner, { "data-designtools": "", sideOffset: 4, alignItemWithTrigger: false, className: "z-50", children: _jsx(Select.Popup, { className: "min-w-(--anchor-width) rounded-lg border border-border bg-overlay p-1 text-overlay-foreground shadow-md", children: _jsx(Select.List, { children: axis.options.map((o) => (_jsxs(Select.Item, { value: o.name, className: "grid min-h-(--docs-target,2.75rem) cursor-pointer grid-cols-[1fr_auto] items-center gap-3 rounded-md px-3 text-sm outline-none data-[highlighted]:bg-muted", children: [_jsx(Select.ItemText, { children: title(o.name) }), _jsx(Select.ItemIndicator, { children: _jsx(Check, { "aria-hidden": true, className: "size-4" }) })] }, o.name))) }) }) }) })] })] }));
+}
+export function FlagControl({ name, checked, onChange }) {
+    const id = useId();
+    return (_jsxs("div", { className: "flex items-center justify-between gap-3", children: [_jsx("label", { htmlFor: id, className: "text-sm font-medium", children: title(name) }), _jsx(Switch.Root, { id: id, checked: checked, onCheckedChange: onChange, 
+                // drawn small, pressed large: the hit area reaches the docs' target without the switch growing
+                className: "relative h-6 w-10 shrink-0 cursor-pointer rounded-full bg-input p-0.5 transition-colors duration-(--dt-duration-fast) after:absolute after:-inset-2.5 after:content-[''] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring data-[checked]:bg-primary", children: _jsx(Switch.Thumb, { className: "block size-5 rounded-full bg-primary-foreground shadow-xs transition-transform duration-(--dt-duration-fast) data-[checked]:translate-x-4" }) })] }));
+}
+export function TextControl({ value, onChange }) {
+    const id = useId();
+    return (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Label, { name: "children", htmlFor: id, info: _jsx("span", { className: "text-muted-foreground", children: "The text inside it." }) }), _jsx("input", { id: id, value: value, onChange: (e) => onChange(e.target.value), className: "h-10 rounded-lg bg-muted px-3 text-sm focus-visible:outline-2 focus-visible:outline-ring" })] }));
+}
+/** A number prop: a field with steppers. */
+export function NumberControl({ name, value, onChange, info }) {
+    const id = useId();
+    const step = (d) => onChange((value ?? 0) + d);
+    const button = "relative flex w-9 cursor-pointer items-center justify-center text-muted-foreground hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring after:absolute after:-inset-y-1 after:inset-x-0 after:content-['']";
+    return (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Label, { name: name, htmlFor: id, info: info }), _jsxs("div", { className: "flex h-10 items-stretch overflow-hidden rounded-lg bg-muted", children: [_jsx("button", { type: "button", "aria-label": `Less ${title(name)}`, onClick: () => step(-1), className: button, children: "\u2212" }), _jsx("input", { id: id, type: "number", inputMode: "decimal", value: value ?? "", onChange: (e) => onChange(e.target.value === "" ? undefined : Number(e.target.value)), className: "min-w-0 flex-1 bg-transparent text-center font-mono text-sm tabular-nums outline-none [appearance:textfield] focus-visible:outline-2 focus-visible:outline-ring [&::-webkit-inner-spin-button]:appearance-none" }), _jsx("button", { type: "button", "aria-label": `More ${title(name)}`, onClick: () => step(1), className: button, children: "+" })] })] }));
+}
+/** A string prop: a text field. */
+export function StringControl({ name, value, onChange, info }) {
+    const id = useId();
+    return (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Label, { name: name, htmlFor: id, info: info }), _jsx("input", { id: id, value: value, onChange: (e) => onChange(e.target.value), className: "h-10 rounded-lg bg-muted px-3 text-sm focus-visible:outline-2 focus-visible:outline-ring" })] }));
+}
+/**
+ * An array or object prop (a Select's options): JSON, applied while it parses,
+ * and said plainly when it does not, so a half-typed edit never breaks the preview.
+ */
+export function JsonControl({ name, value, onChange, info }) {
+    const id = useId();
+    const [text, setText] = useState(() => JSON.stringify(value ?? null, null, 2));
+    const [error, setError] = useState(null);
+    return (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Label, { name: name, htmlFor: id, info: info }), _jsx("textarea", { id: id, value: text, rows: Math.min(10, text.split("\n").length), spellCheck: false, "aria-invalid": !!error, "aria-describedby": error ? `${id}-error` : undefined, onChange: (e) => {
+                    setText(e.target.value);
+                    try {
+                        onChange(JSON.parse(e.target.value));
+                        setError(null);
+                    }
+                    catch (err) {
+                        setError(err instanceof Error ? err.message : "Not valid JSON");
+                    }
+                }, className: "resize-y rounded-lg bg-muted px-3 py-2 font-mono text-xs leading-relaxed focus-visible:outline-2 focus-visible:outline-ring aria-invalid:outline-2 aria-invalid:outline-destructive" }), error && (_jsxs("p", { id: `${id}-error`, className: "text-xs text-destructive-subdued-foreground", children: ["Not applied: ", error] }))] }));
+}

package/dist/preview-frame.d.ts

@@ -0,0 +1,31 @@
+import { type ReactNode } from "react";
+import type { ComponentEntry, PatternEntry } from "./lib/manifest-types.js";
+/**
+ * A preview route in an iframe, at set widths and in either mode, so a
+ * component is seen at a phone's width and its media queries actually fire.
+ */
+export declare function PreviewFrame({ src, title, widths, height, }: {
+    /** The preview route, e.g. `/design/system/preview/badge/canonical`. */
+    src: string;
+    title: string;
+    widths?: number[];
+    height?: number;
+}): import("react").JSX.Element;
+/**
+ * What the preview route renders around a state: the page's canvas in the
+ * requested mode, set on the document too, so popups in portals match.
+ */
+export declare function PreviewSurface({ theme, children }: {
+    theme?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** One example on its own, for the preview route to render inside a PreviewSurface. */
+export declare function PreviewExample({ entry, example }: {
+    entry: ComponentEntry;
+    example: string;
+}): import("react").JSX.Element;
+/** One pattern composition on its own. */
+export declare function PreviewComposition({ pattern, composition }: {
+    pattern: PatternEntry;
+    composition: string;
+}): import("react").JSX.Element;

package/dist/preview-frame.js

@@ -0,0 +1,63 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ExternalLink, Monitor, Moon, Smartphone, Sun, Tablet } from "lucide-react";
+import { useEffect, useState } from "react";
+import { Boundary } from "./lib/boundary.js";
+import { cx } from "./lib/cx.js";
+import { Missing, renderExample, useLookup } from "./lib/lookup.js";
+import { Frame, IconButton, IconLink, Toolbar } from "./lib/ui.js";
+/**
+ * A preview route in an iframe, at set widths and in either mode, so a
+ * component is seen at a phone's width and its media queries actually fire.
+ */
+export function PreviewFrame({ src, title, widths = [375, 768, 1280], height = 360, }) {
+    const [width, setWidth] = useState(widths[0]);
+    const [theme, setTheme] = useState("light");
+    const url = `${src}${src.includes("?") ? "&" : "?"}theme=${theme}`;
+    const device = (w) => (w < 600 ? Smartphone : w < 1024 ? Tablet : Monitor);
+    return (_jsxs(Frame, { "data-slot": "preview-frame", children: [_jsxs(Toolbar, { children: [_jsx("div", { role: "group", "aria-label": "Preview width", className: "flex items-center gap-0.5 rounded-lg border border-border p-0.5", children: widths.map((w) => {
+                            const Icon = device(w);
+                            return (_jsxs("button", { type: "button", "aria-pressed": width === w, onClick: () => setWidth(w), className: cx("relative inline-flex h-7 cursor-pointer items-center gap-1.5 rounded-md px-2.5 font-mono text-xs text-muted-foreground transition-colors duration-(--dt-duration-fast) hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring aria-pressed:bg-muted aria-pressed:text-canvas-foreground", "after:absolute after:inset-x-0 after:-inset-y-[calc((var(--docs-target,2.75rem)-1.75rem)/2)] after:content-['']"), children: [_jsx(Icon, { "aria-hidden": true, className: "size-(--dt-size-xs)" }), w] }, w));
+                        }) }), _jsxs("span", { className: "flex items-center gap-0.5", children: [_jsx(IconButton, { icon: theme === "dark" ? Sun : Moon, label: theme === "dark" ? "Show in light mode" : "Show in dark mode", pressed: theme === "dark", onClick: () => setTheme(theme === "dark" ? "light" : "dark") }), _jsx(IconLink, { icon: ExternalLink, label: "Open in a new tab", href: url, target: "_blank", rel: "noreferrer" })] })] }), _jsx("div", { className: "overflow-x-auto bg-muted/50 bg-[radial-gradient(color-mix(in_oklch,var(--border)_85%,transparent)_1px,transparent_1px)] [background-size:14px_14px] p-6", tabIndex: 0, role: "region", "aria-label": "Preview", children: _jsxs("div", { className: "mx-auto flex flex-col overflow-hidden rounded-lg border border-border bg-canvas shadow-md", style: { width, maxWidth: "none" }, children: [_jsxs("div", { "aria-hidden": true, className: "flex items-center gap-3 border-b border-border bg-surface px-3 py-2", children: [_jsxs("span", { className: "flex gap-1.5", children: [_jsx("span", { className: "size-2.5 rounded-full bg-border" }), _jsx("span", { className: "size-2.5 rounded-full bg-border" }), _jsx("span", { className: "size-2.5 rounded-full bg-border" })] }), _jsxs("span", { className: "min-w-0 flex-1 truncate rounded-md bg-muted px-2 py-0.5 text-center font-mono text-xs text-muted-foreground", children: [title, " \u00B7 ", width, "px"] })] }), _jsx("iframe", { title: `${title}, ${width}px wide, ${theme} mode`, src: url, "data-slot": "preview-iframe", className: "block w-full resize-y bg-canvas", style: { height } })] }) })] }));
+}
+/**
+ * What the preview route renders around a state: the page's canvas in the
+ * requested mode, set on the document too, so popups in portals match.
+ */
+export function PreviewSurface({ theme, children }) {
+    const mode = theme === "dark" || theme === "light" ? theme : undefined;
+    useEffect(() => {
+        if (!mode)
+            return;
+        const root = document.documentElement;
+        const previous = root.dataset.theme;
+        root.dataset.theme = mode;
+        return () => {
+            if (previous === undefined)
+                delete root.dataset.theme;
+            else
+                root.dataset.theme = previous;
+        };
+    }, [mode]);
+    return (_jsx("div", { "data-designtools": "", "data-docs-stage": "", "data-slot": "preview-surface", "data-theme": mode, className: "min-h-dvh bg-canvas p-6 text-canvas-foreground", children: children }));
+}
+/** One example on its own, for the preview route to render inside a PreviewSurface. */
+export function PreviewExample({ entry, example }) {
+    const lookup = useLookup();
+    const module = lookup.examplesFor(entry);
+    if (!module)
+        return _jsx(Missing, { name: entry.name, what: "examples" });
+    if (!(example in module))
+        return _jsxs("p", { className: "text-sm", children: [entry.name, " has no example called ", example, "."] });
+    return _jsx(Boundary, { label: example, children: renderExample(module[example], example) });
+}
+/** One pattern composition on its own. */
+export function PreviewComposition({ pattern, composition }) {
+    const lookup = useLookup();
+    const module = lookup.compositionsFor(pattern);
+    if (!module)
+        return _jsx(Missing, { name: pattern.name, what: "compositions" });
+    if (!(composition in module))
+        return _jsxs("p", { className: "text-sm", children: [pattern.name, " has no composition called ", composition, "."] });
+    return _jsx(Boundary, { label: composition, children: renderExample(module[composition], composition) });
+}

package/dist/props-table.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentEntry } from "./lib/manifest-types.js";
+/**
+ * A component's props, as an API reference: name, type and default on one line,
+ * each row opening to its description. Its own props first, then those of the
+ * primitive it wraps, folded away. Deprecated props are struck through with the
+ * reason; what it inherits from an element or primitive is named underneath.
+ */
+export declare function PropsTable({ entry }: {
+    entry: ComponentEntry;
+}): import("react").JSX.Element;

package/dist/props-table.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ChevronDown } from "lucide-react";
+import { cx } from "./lib/cx.js";
+import { inline } from "./lib/text.js";
+/**
+ * A component's props, as an API reference: name, type and default on one line,
+ * each row opening to its description. Its own props first, then those of the
+ * primitive it wraps, folded away. Deprecated props are struck through with the
+ * reason; what it inherits from an element or primitive is named underneath.
+ */
+export function PropsTable({ entry }) {
+    const rows = Object.entries(entry.props);
+    const own = rows.filter(([, p]) => !p.from);
+    const byPackage = new Map();
+    for (const row of rows.filter(([, p]) => p.from)) {
+        byPackage.set(row[1].from, [...(byPackage.get(row[1].from) ?? []), row]);
+    }
+    return (_jsxs("div", { "data-slot": "props-table", className: "flex flex-col gap-4", children: [own.length > 0 ? _jsx(Table, { rows: own }) : _jsx("p", { className: "text-sm text-muted-foreground", children: "No props of its own." }), [...byPackage.entries()].map(([pkg, inherited]) => (_jsxs("details", { "data-slot": "props-inherited", className: "group/inherited overflow-hidden rounded-xl border border-border bg-surface text-surface-foreground", children: [_jsxs("summary", { className: "flex min-h-(--docs-target,2.75rem) cursor-pointer list-none items-center justify-between gap-3 px-4 text-sm hover:bg-muted [&::-webkit-details-marker]:hidden", children: [_jsxs("span", { children: [inherited.length, " more from ", _jsx("code", { className: "font-mono text-xs", children: pkg })] }), _jsx(ChevronDown, { "aria-hidden": true, className: "size-(--dt-size-xs) text-muted-foreground transition-transform group-open/inherited:rotate-180" })] }), _jsx("div", { className: "border-t border-border", children: _jsx(Table, { rows: inherited, bare: true }) })] }, pkg))), entry.inherits && entry.inherits.length > 0 && (_jsxs("p", { "data-slot": "props-inherits", className: "text-sm text-muted-foreground", children: ["Also accepts every prop of", " ", entry.inherits.map((x, i) => (_jsxs("span", { children: [i > 0 && ", ", _jsx("code", { className: "rounded-sm bg-muted px-1 py-0.5 font-mono text-xs text-canvas-foreground", children: /^[a-z][\w-]*$/.test(x) ? `<${x}>` : x })] }, x))), "."] }))] }));
+}
+const COLS = "grid grid-cols-[minmax(0,1fr)_auto] gap-x-4 gap-y-1 md:grid-cols-[minmax(9rem,0.9fr)_minmax(0,1.6fr)_minmax(5rem,0.6fr)_1.25rem] md:items-center";
+function Table({ rows, bare }) {
+    return (_jsxs("div", { className: cx("min-w-0 text-sm", !bare && "overflow-hidden rounded-xl border border-border bg-surface text-surface-foreground"), children: [_jsxs("div", { "aria-hidden": true, className: cx(COLS, "hidden border-b border-border bg-muted/50 px-4 py-2.5 text-xs font-medium text-muted-foreground md:grid"), children: [_jsx("span", { children: "Prop" }), _jsx("span", { children: "Type" }), _jsx("span", { children: "Default" }), _jsx("span", {})] }), _jsx("ul", { "aria-label": "Props", className: "divide-y divide-border", children: rows.map(([name, prop]) => (_jsx("li", { children: _jsx(Row, { name: name, prop: prop }) }, name))) })] }));
+}
+function Row({ name, prop }) {
+    const deprecated = prop.deprecated !== undefined;
+    const line = (_jsxs(_Fragment, { children: [_jsxs("span", { className: "flex min-w-0 items-center gap-1", children: [_jsx("code", { className: cx("truncate font-mono text-xs font-medium text-primary-subdued-foreground", deprecated && "line-through opacity-70"), children: name }), prop.required && (_jsxs("span", { "data-slot": "props-required", className: "font-mono text-xs text-destructive-subdued-foreground", title: "Required", children: ["*", _jsx("span", { className: "sr-only", children: " required" })] }))] }), _jsxs("span", { className: "col-span-2 min-w-0 md:col-span-1", children: [_jsx("span", { className: "sr-only", children: ", type " }), _jsx(Type, { prop: prop })] }), _jsx("span", { className: "hidden font-mono text-xs text-muted-foreground md:block", children: prop.default !== undefined ? (_jsxs(_Fragment, { children: [_jsx("span", { className: "sr-only", children: ", default " }), prop.default] })) : (_jsx("span", { "aria-hidden": true, children: "\u2014" })) })] }));
+    const described = deprecated || !!prop.description;
+    if (!described)
+        return (_jsxs("div", { "data-slot": "props-row", className: cx(COLS, "px-4 py-3"), children: [line, _jsx("span", {})] }));
+    return (_jsxs("details", { "data-slot": "props-row", className: "group/row", children: [_jsxs("summary", { className: cx(COLS, "min-h-(--docs-target,2.75rem) cursor-pointer list-none px-4 py-3 hover:bg-muted/60 [&::-webkit-details-marker]:hidden"), children: [line, _jsx(ChevronDown, { "aria-hidden": true, className: "col-start-2 row-start-1 size-(--dt-size-xs) justify-self-end text-muted-foreground transition-transform group-open/row:rotate-180 md:col-start-4" })] }), _jsxs("div", { className: "flex flex-col gap-2 px-4 pb-4 text-sm text-muted-foreground", children: [prop.default !== undefined && (_jsxs("p", { className: "md:hidden", children: ["Default ", _jsx("code", { className: "font-mono text-xs text-canvas-foreground", children: prop.default })] })), deprecated && _jsxs("p", { className: "font-medium text-canvas-foreground", children: ["Deprecated", prop.deprecated ? _jsxs(_Fragment, { children: [": ", inline(prop.deprecated)] }) : "."] }), prop.description?.split("\n\n").map((p) => (_jsx("p", { className: "max-w-prose whitespace-pre-line", children: inline(p) }, p)))] })] }));
+}
+/** A type, coloured by kind: literals, primitives and functions read apart at a glance. */
+function Type({ prop }) {
+    const parts = prop.values ?? prop.type.split(/\s*\|\s*/);
+    return (_jsx("span", { className: "flex flex-wrap items-center gap-x-1 gap-y-1 font-mono text-xs", children: parts.map((t, i) => (_jsxs("span", { className: "inline-flex items-center gap-1", children: [i > 0 && _jsx("span", { className: "text-muted-foreground", children: "|" }), _jsx("span", { className: cx("break-all", tone(t, !!prop.values)), children: prop.values ? `"${t}"` : t })] }, `${t}-${i}`))) }));
+}
+function tone(t, literal) {
+    if (literal || /^["'].*["']$/.test(t))
+        return "text-success-subdued-foreground";
+    if (/^(boolean|number|string|true|false|null|undefined)$/.test(t))
+        return "text-primary-subdued-foreground";
+    if (/=>|^\(|Function|Handler|EventHandler/.test(t))
+        return "text-destructive-subdued-foreground";
+    return "text-canvas-foreground";
+}

package/dist/rule.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from "react";
+import type { RuleEntry } from "./lib/manifest-types.js";
+/**
+ * One rule, brand or interface, written for people. On a wide screen, its name, status and the check
+ * that proves it hold the left column while the right reads: the statement set large, the
+ * demonstration (pass it as children, for a rule that needs persuading), the facts, then why. A small
+ * switch shows the same rule as an agent reads it.
+ */
+export declare function Rule({ rule, children }: {
+    rule: RuleEntry;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/** Every rule on one screen, a line each, linking to the rule: what it is, how settled, how it is checked. */
+export declare function RuleIndex({ rules }: {
+    rules: RuleEntry[];
+}): import("react").JSX.Element;