@tonycodes-ui/mortar 0.0.0-stage → 0.12.0

package/dist/display.js

@@ -0,0 +1,75 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
+import { KitLink } from "./navigation.js";
+import { Check, Close, Paperclip, Person } from "./icons.js";
+import { headingTag } from "./heading.js";
+import { TermList, cx, componentRoot, focusAfterRemoval, classedIntroSlots, } from "./internal.js";
+function initials(name) {
+    return name
+        .split(/\s+/)
+        .filter(Boolean)
+        .slice(0, 2)
+        .map((part) => part.charAt(0).toUpperCase())
+        .join("");
+}
+export function Avatar({ name, src, size = "md", shape = "circle", status, statusPosition = "bottom", placeholder = "initials", decorative = false, className, }) {
+    return (_jsxs("span", { ...componentRoot("Avatar"), className: cx(`m-avatar m-avatar-${size}`, className), "data-shape": shape === "circle" ? undefined : shape, ...(decorative
+            ? { "aria-hidden": true }
+            : {
+                role: "img",
+                "aria-label": status ? `${name}, ${status}` : name,
+            }), children: [src ? (_jsx("img", { src: src, alt: "" })) : placeholder === "icon" ? (_jsx(Person, { className: "m-avatar-placeholder" })) : (_jsx("span", { "aria-hidden": "true", children: initials(name) })), status && (_jsx("span", { className: "m-avatar-status", "data-status": status, "data-position": statusPosition === "top" ? "top" : undefined, "aria-hidden": "true" }))] }));
+}
+export function AvatarGroup({ label, people, max = 4, className, }) {
+    const shown = people.slice(0, max), rest = people.length - shown.length;
+    return (_jsxs("ul", { ...componentRoot("AvatarGroup"), className: cx("m-avatar-group", className), "aria-label": label, children: [shown.map((person) => (_jsx("li", { children: _jsx(Avatar, { name: person.name, src: person.src, size: "sm" }) }, person.name))), rest > 0 && (_jsx("li", { children: _jsxs("span", { className: "m-avatar m-avatar-sm m-avatar-more", role: "img", "aria-label": `${rest} more`, children: ["+", rest] }) }))] }));
+}
+export function Kbd({ keys, className }) {
+    return (_jsx("span", { ...componentRoot("Kbd"), className: cx("m-kbd-group", className), children: keys.map((key, i) => (_jsx("kbd", { className: "m-kbd", children: key }, i))) }));
+}
+export function ProgressBar({ label, value, max = 100, valueLabel, tone, className, }) {
+    const labelId = useId();
+    const percent = Math.min(100, Math.max(0, (value / max) * 100));
+    return (_jsxs("div", { ...componentRoot("ProgressBar"), className: cx("m-progress", className), "data-tone": tone, children: [_jsxs("div", { className: "m-progress-label", children: [_jsx("span", { id: labelId, children: label }), valueLabel && _jsx("span", { "aria-hidden": "true", children: valueLabel })] }), _jsx("div", { className: "m-progress-track", role: "progressbar", "aria-labelledby": labelId, "aria-valuemin": 0, "aria-valuemax": max, "aria-valuenow": value, "aria-valuetext": valueLabel, children: _jsx("span", { style: { width: `${percent}%` } }) })] }));
+}
+export function FilterChip({ label, selected = false, onClick, onRemove, className, }) {
+    if (onRemove)
+        return (_jsxs("span", { ...componentRoot("FilterChip"), className: cx("m-chip", className), "data-selected": "true", children: [label, _jsx("button", { type: "button", onClick: (event) => {
+                        const chip = event.currentTarget.parentElement;
+                        if (chip)
+                            focusAfterRemoval(chip);
+                        onRemove();
+                    }, "aria-label": `Remove ${typeof label === "string" ? label : "filter"}`, children: _jsx(Close, {}) })] }));
+    return (_jsxs("button", { type: "button", ...componentRoot("FilterChip"), className: cx("m-chip", className), "aria-pressed": selected, "data-selected": selected || undefined, onClick: onClick, children: [!selected && _jsx("span", { "aria-hidden": "true", children: "+" }), label] }));
+}
+/** Feature or inclusion list with a check marker; replaces ad-hoc list-disc styling. */
+export function CheckList({ items, label, columns = 1, size = "md", className, }) {
+    return (_jsx("ul", { ...componentRoot("CheckList"), className: cx("m-check-list", className), "aria-label": label, "data-columns": columns === 1 ? undefined : columns, "data-size": size === "md" ? undefined : size, children: items.map((item, i) => (_jsxs("li", { children: [_jsx(Check, { variant: "list" }), _jsx("span", { children: item })] }, i))) }));
+}
+/** Label/value pairs for detail screens, stacked on narrow screens and in columns when wide. */
+export function DescriptionList({ title, description, headingLevel = 2, items, layout = "columns", variant = "plain", id, className, }) {
+    return (_jsxs("div", { id: id, ...componentRoot("DescriptionList"), className: cx("m-description-list", className), "data-layout": layout === "columns" ? undefined : layout, "data-variant": variant === "plain" ? undefined : variant, children: [title && (_jsxs("div", { className: "m-description-heading", children: [...classedIntroSlots({
+                        title,
+                        description,
+                        headingLevel,
+                        descriptionClassName: null,
+                    }, "m-description-title")] })), _jsx(TermList, { items: items.map((item) => ({
+                    term: item.term,
+                    details: item.details,
+                    attributes: { "data-action": item.action ? true : undefined },
+                    after: item.action && (_jsx("dd", { className: "m-description-action", children: item.action })),
+                })) })] }));
+}
+/**
+ * Responsive grid of cards for people, projects or files. A card's title link
+ * covers the card; links and buttons in `media`, `meta`, `details` and
+ * `actions` sit above it and stay clickable.
+ */
+export function GridList({ label, items, columns = 3, itemHeadingLevel = 3, actionsLayout = "inline", className, }) {
+    const Heading = headingTag(itemHeadingLevel);
+    return (_jsx("ul", { ...componentRoot("GridList"), className: cx("m-grid-list", className), "aria-label": label, "data-columns": columns === 3 ? undefined : columns, "data-actions": actionsLayout === "split" ? "split" : undefined, children: items.map((item) => (_jsxs("li", { children: [item.cover && (_jsx("div", { className: "m-grid-list-cover", children: _jsx("img", { src: item.cover.src, alt: item.cover.alt, loading: "lazy" }) })), _jsxs("div", { className: "m-grid-list-body", children: [item.media && (_jsx("span", { className: "m-grid-list-media", children: item.media })), _jsxs("div", { className: "m-grid-list-text", children: [_jsx(Heading, { className: "m-grid-list-title", children: item.href ? (_jsx(KitLink, { href: item.href, children: item.title })) : (item.title) }), item.description && _jsx("p", { children: item.description }), item.meta && _jsx("div", { className: "m-grid-list-meta", children: item.meta })] })] }), item.details && item.details.length > 0 && (_jsx(TermList, { className: "m-grid-list-details", items: item.details })), item.actions && (_jsx("div", { className: "m-grid-list-actions", children: item.actions }))] }, item.id))) }));
+}
+/** Files attached to a record, each with a size and a named download link. */
+export function AttachmentList({ files, label = "Attachments", className, }) {
+    return (_jsx("ul", { ...componentRoot("AttachmentList"), className: cx("m-attachments", className), "aria-label": label, children: files.map((file) => (_jsxs("li", { children: [_jsx("span", { className: "m-attachment-icon", "aria-hidden": "true", children: file.icon ?? _jsx(Paperclip, {}) }), _jsxs("span", { className: "m-attachment-text", children: [_jsx("span", { className: "m-attachment-name", children: file.name }), file.size && (_jsx("span", { className: "m-attachment-size", children: file.size }))] }), _jsxs(KitLink, { href: file.href, children: [file.actionLabel ?? "Download", _jsxs("span", { className: "m-sr-only", children: [" ", file.name] })] })] }, file.id))) }));
+}

package/dist/docs.d.ts

@@ -0,0 +1,145 @@
+import { type ReactNode } from "react";
+import { type LinkAction, type Tone } from "./primitives.js";
+import type { NavigationItem } from "./application.js";
+import { type CommandItem } from "./workspace.js";
+import type { ItemGroup, LinkItem } from "./navigation.js";
+import { type HeadingLevel } from "./heading.js";
+export interface DocsShellProps {
+    className?: string;
+    brand: string;
+    /** Logo node shown in place of the placeholder brand mark. */
+    logo?: ReactNode;
+    /** Use the available content width for explorers and workspaces. */
+    layout?: "article" | "wide";
+    navigationLabel?: string;
+    homeHref?: string;
+    version?: ReactNode;
+    sections?: Pick<LinkItem, "label" | "href" | "current">[];
+    /** Groups of pages; items show their icon and count, and children become disclosures. */
+    navigation: ItemGroup<NavigationItem>[];
+    toc?: {
+        id: string;
+        label: string;
+        current?: boolean;
+    }[];
+    tocLabel?: string;
+    tocFooter?: ReactNode;
+    search?: ReactNode;
+    actions?: ReactNode;
+    children: ReactNode;
+}
+export declare function DocsShell({ className, brand, logo, layout, navigationLabel, homeHref, version, sections, navigation, toc, tocLabel, tocFooter, search, actions, children, }: DocsShellProps): import("react").JSX.Element;
+export declare function SearchTrigger({ className, onOpen, label, }: {
+    className?: string;
+    onOpen: () => void;
+    label?: string;
+}): import("react").JSX.Element;
+export declare function SearchDialog(props: {
+    open: boolean;
+    onClose: () => void;
+    query: string;
+    onQueryChange: (value: string) => void;
+    groups: ItemGroup<CommandItem>[];
+    attribution?: ReactNode;
+}): import("react").JSX.Element;
+export declare function Steps({ id, className, items, itemHeadingLevel, }: {
+    id?: string;
+    className?: string;
+    items: {
+        title: string;
+        id?: string;
+        description?: ReactNode;
+        content?: ReactNode;
+    }[];
+    /** Level of each step's title. */
+    itemHeadingLevel?: HeadingLevel;
+}): import("react").JSX.Element;
+export declare function Callout({ id, className, tone, title, children, }: {
+    id?: string;
+    className?: string;
+    /** neutral: a note. info: a highlighted note. success: a tip. warning and danger: a caution, e.g. a breaking change. */
+    tone?: Tone;
+    /** Visible lead-in that also names the note; defaults to the tone's word, e.g. "Warning". */
+    title?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export interface FileNode {
+    name: string;
+    note?: string;
+    highlighted?: boolean;
+    children?: FileNode[];
+}
+export declare function FileTree({ id, className, label, items, }: {
+    id?: string;
+    className?: string;
+    label: string;
+    items: FileNode[];
+}): import("react").JSX.Element;
+/** Dark code surface with optional language tabs, filename, line numbers and highlighted lines. */
+export declare function CodeTabs({ id, className, tabs, filename, language, lineNumbers, highlightLines, prompt, }: {
+    id?: string;
+    className?: string;
+    tabs: {
+        id: string;
+        label: string;
+        code: string;
+    }[];
+    filename?: string;
+    language?: string;
+    lineNumbers?: boolean;
+    highlightLines?: number[];
+    prompt?: string;
+}): import("react").JSX.Element | null;
+export declare function Release({ id, className, version, date, dateLabel, changes, headingLevel, }: {
+    id?: string;
+    className?: string;
+    /** Level of the version heading; change groups sit one level below. */
+    headingLevel?: HeadingLevel;
+    version: string;
+    date: string;
+    dateLabel: string;
+    changes: {
+        type: "added" | "changed" | "fixed" | "deprecated" | "removed";
+        items: ReactNode[];
+    }[];
+}): import("react").JSX.Element;
+export declare function ApiEndpoint({ id, className, headingLevel, method, path, title, description, paramsLabel, params, examples, }: {
+    id?: string;
+    className?: string;
+    /** Level of the endpoint title; the parameters heading sits one level below. */
+    headingLevel?: HeadingLevel;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    title: string;
+    description?: ReactNode;
+    paramsLabel?: string;
+    params: {
+        name: string;
+        type: string;
+        required?: boolean;
+        description: ReactNode;
+    }[];
+    /** Request/response samples, typically CodeTabs. */
+    examples?: ReactNode;
+}): import("react").JSX.Element;
+export declare function PageFeedback({ id, className, question, value, onChange, updated, }: {
+    id?: string;
+    className?: string;
+    question?: string;
+    value: "yes" | "no" | null;
+    onChange: (value: "yes" | "no") => void;
+    updated?: ReactNode;
+}): import("react").JSX.Element;
+export declare function PagerLinks({ id, className, previous, next, label, }: {
+    id?: string;
+    className?: string;
+    previous?: LinkAction;
+    next?: LinkAction;
+    /** Names the navigation landmark; keep it distinct from other navigation on the page. */
+    label?: string;
+}): import("react").JSX.Element;
+export declare function LinkCards({ id, className, items, }: {
+    id?: string;
+    className?: string;
+    items: Pick<LinkItem, "label" | "href" | "description">[];
+}): import("react").JSX.Element;

package/dist/docs.js

@@ -0,0 +1,141 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { KitLink } from "./navigation.js";
+import { useEffect, useId, useState } from "react";
+import { Button } from "./primitives.js";
+import { CommandPalette } from "./workspace.js";
+import { Kbd } from "./display.js";
+import { BrandMark } from "./layout.js";
+import { childLevel, headingTag } from "./heading.js";
+import { AsComponentRoot, MobileNavDialog, NavGroups, TermList, cx, componentRoot, rovingIndex, } from "./internal.js";
+export function DocsShell({ className, brand, logo, layout = "article", navigationLabel = "Documentation", homeHref = "/", version, sections = [], navigation, toc = [], tocLabel = "On this page", tocFooter, search, actions, children, }) {
+    const [open, setOpen] = useState(false);
+    const contentId = useId();
+    const tree = (_jsx("nav", { "aria-label": navigationLabel, children: _jsx(NavGroups, { groups: navigation, onNavigate: () => setOpen(false) }) }));
+    return (_jsxs("div", { ...componentRoot("DocsShell"), className: cx("m-docs-shell", className), "data-layout": layout === "article" ? undefined : layout, children: [_jsx(KitLink, { className: "m-skip", href: `#${contentId}`, children: "Skip to content" }), _jsxs("header", { className: "m-docs-header", children: [_jsx(Button, { variant: "ghost", className: "m-menu-trigger", onClick: () => setOpen(true), "aria-haspopup": "dialog", "aria-expanded": open, children: "Menu" }), _jsxs(KitLink, { className: "m-brand", href: homeHref, children: [_jsx(BrandMark, { logo: logo }), brand] }), version && _jsx("div", { className: "m-docs-version", children: version }), sections.length > 0 && (_jsx("nav", { "aria-label": "Sections", className: "m-docs-sections", children: sections.map((s, index) => (_jsx(KitLink, { href: s.href, "aria-current": s.current ? "page" : undefined, children: s.label }, `${s.label}:${s.href}:${index}`))) })), _jsxs("div", { className: "m-actions", children: [search, actions] })] }), _jsxs("div", { className: "m-docs-body", children: [_jsx("aside", { className: "m-docs-nav", children: tree }), _jsx("main", { id: contentId, tabIndex: -1, children: children }), toc.length > 0 && (_jsxs("aside", { className: "m-docs-toc", children: [_jsxs("nav", { "aria-label": tocLabel, children: [_jsx("h2", { children: tocLabel }), toc.map((t) => (_jsx(KitLink, { href: `#${t.id}`, "aria-current": t.current ? "location" : undefined, children: t.label }, t.id)))] }), tocFooter && _jsx("div", { className: "m-docs-toc-footer", children: tocFooter })] }))] }), _jsx(MobileNavDialog, { open: open, onClose: () => setOpen(false), title: brand, children: tree })] }));
+}
+/** True when a key press belongs to a text field or an open dialog, not the page. */
+function ownedKeyPress(target) {
+    if (!(target instanceof Element))
+        return false;
+    return Boolean(target.closest('input, textarea, select, [contenteditable]:not([contenteditable="false"]), [role="dialog"], [role="alertdialog"], dialog[open]'));
+}
+export function SearchTrigger({ className, onOpen, label = "Search docs", }) {
+    // The shortcut hint is platform-specific; it renders after mount so server
+    // and client markup agree.
+    const [apple, setApple] = useState();
+    useEffect(() => {
+        setApple(/Mac|iPhone|iPad|iPod/.test(navigator.platform || navigator.userAgent));
+    }, []);
+    useEffect(() => {
+        const onKey = (e) => {
+            if (!(e.metaKey || e.ctrlKey) ||
+                e.altKey ||
+                e.shiftKey ||
+                e.key.toLowerCase() !== "k" ||
+                e.repeat ||
+                // Another trigger on the page already handled this press.
+                e.defaultPrevented ||
+                ownedKeyPress(e.target))
+                return;
+            e.preventDefault();
+            onOpen();
+        };
+        window.addEventListener("keydown", onKey);
+        return () => window.removeEventListener("keydown", onKey);
+    }, [onOpen]);
+    return (_jsxs("button", { type: "button", ...componentRoot("SearchTrigger"), className: cx("m-search-trigger", className), onClick: onOpen, "aria-keyshortcuts": "Meta+K Control+K", children: [_jsx("span", { children: label }), apple !== undefined && _jsx(Kbd, { keys: [apple ? "⌘K" : "Ctrl K"] })] }));
+}
+export function SearchDialog(props) {
+    return (_jsx(AsComponentRoot, { name: "SearchDialog", of: "CommandPalette", children: _jsx(CommandPalette, { ...props, label: "Search documentation", placeholder: "Search docs", footer: _jsxs(_Fragment, { children: [_jsxs("span", { children: [_jsx(Kbd, { keys: ["↑", "↓"] }), " navigate"] }), _jsxs("span", { children: [_jsx(Kbd, { keys: ["↵"] }), " open"] }), props.attribution && (_jsx("span", { className: "m-palette-attribution", children: props.attribution }))] }) }) }));
+}
+export function Steps({ id, className, items, itemHeadingLevel = 3, }) {
+    const Heading = headingTag(itemHeadingLevel);
+    return (_jsx("ol", { id: id, ...componentRoot("Steps"), className: cx("m-steps", className), children: items.map((item, i) => (_jsxs("li", { children: [_jsx("span", { className: "m-step-number", "aria-hidden": "true", children: i + 1 }), _jsxs("div", { children: [_jsx(Heading, { id: item.id, children: item.title }), item.description && (_jsx("div", { className: "m-step-description", children: item.description })), item.content] })] }, `${item.title}:${i}`))) }));
+}
+const calloutLabel = {
+    neutral: "Note",
+    info: "Note",
+    success: "Tip",
+    warning: "Warning",
+    danger: "Caution",
+};
+export function Callout({ id, className, tone = "neutral", title, children, }) {
+    const labelId = useId();
+    return (_jsxs("div", { id: id, ...componentRoot("Callout"), className: cx("m-callout", className), role: "note", "aria-labelledby": labelId, "data-tone": tone === "neutral" ? undefined : tone, children: [_jsx("strong", { id: labelId, children: title || calloutLabel[tone] }), _jsx("span", { "aria-hidden": "true", children: " \u00B7 " }), _jsx("div", { children: children })] }));
+}
+function FileBranch({ nodes }) {
+    return (_jsx("ul", { children: nodes.map((node) => (_jsxs("li", { "data-folder": !!node.children || undefined, "data-highlighted": node.highlighted || undefined, children: [_jsxs("span", { className: "m-file-row", children: [_jsx("span", { "aria-hidden": "true", className: "m-file-caret", children: node.children ? "▾" : "" }), _jsx("span", { children: node.name }), node.note && _jsx("small", { children: node.note })] }), node.children && _jsx(FileBranch, { nodes: node.children })] }, node.name))) }));
+}
+export function FileTree({ id, className, label, items, }) {
+    return (_jsx("figure", { id: id, ...componentRoot("FileTree"), className: cx("m-file-tree", className), "aria-label": label, children: _jsx(FileBranch, { nodes: items }) }));
+}
+function CopyButton({ text }) {
+    const [result, setResult] = useState();
+    useEffect(() => {
+        if (!result)
+            return;
+        const t = setTimeout(() => setResult(undefined), 1600);
+        return () => clearTimeout(t);
+    }, [result]);
+    const copy = async () => {
+        try {
+            // A missing API (insecure context) and a denied permission both fail.
+            if (!navigator.clipboard)
+                throw Error("Clipboard unavailable");
+            await navigator.clipboard.writeText(text);
+            setResult("copied");
+        }
+        catch {
+            setResult("failed");
+        }
+    };
+    return (_jsx("button", { type: "button", className: "m-code-copy", "data-result": result, onClick: copy, children: _jsx("span", { "aria-live": "polite", children: result === "copied"
+                ? "Copied"
+                : result === "failed"
+                    ? "Copy failed"
+                    : "Copy" }) }));
+}
+/** Dark code surface with optional language tabs, filename, line numbers and highlighted lines. */
+export function CodeTabs({ id, className, tabs, filename, language, lineNumbers = false, highlightLines = [], prompt, }) {
+    const [active, setActive] = useState(tabs[0]?.id);
+    const base = useId();
+    const current = tabs.find((t) => t.id === active) || tabs[0];
+    if (!current)
+        return null;
+    const lines = current.code.split("\n");
+    const tabId = (tab) => `${base}-tab-${tab.id}`;
+    const panelId = `${base}-panel`;
+    return (_jsxs("figure", { id: id, ...componentRoot("CodeTabs"), className: cx("m-code-tabs", className), children: [_jsxs("div", { className: "m-code-bar", children: [tabs.length > 1 ? (_jsx("div", { role: "tablist", "aria-label": filename || "Code examples", children: tabs.map((t) => (_jsx("button", { type: "button", role: "tab", id: tabId(t), "aria-selected": t.id === current.id, "aria-controls": panelId, tabIndex: t.id === current.id ? 0 : -1, onClick: () => setActive(t.id), onKeyDown: (e) => {
+                                const n = rovingIndex(e.key, tabs.findIndex((x) => x.id === current.id), tabs.length);
+                                if (n === null)
+                                    return;
+                                e.preventDefault();
+                                const next = tabs[n];
+                                setActive(next.id);
+                                document.getElementById(tabId(next))?.focus();
+                            }, children: t.label }, t.id))) })) : (_jsx("figcaption", { children: filename || current.label })), language && _jsx("span", { className: "m-code-language", children: language }), _jsx(CopyButton, { text: current.code })] }), _jsx("pre", { tabIndex: 0, id: tabs.length > 1 ? panelId : undefined, role: tabs.length > 1 ? "tabpanel" : undefined, "aria-labelledby": tabs.length > 1 ? tabId(current) : undefined, children: _jsx("code", { children: lines.map((line, i) => (_jsxs("span", { className: "m-code-line", "data-highlighted": highlightLines.includes(i + 1) || undefined, children: [lineNumbers && (_jsx("span", { className: "m-code-number", "aria-hidden": "true", children: i + 1 })), prompt && (_jsxs("span", { className: "m-code-prompt", "aria-hidden": "true", children: [prompt, " "] })), line || " "] }, i))) }) })] }));
+}
+export function Release({ id, className, version, date, dateLabel, changes, headingLevel = 3, }) {
+    const Heading = headingTag(headingLevel);
+    const GroupHeading = headingTag(childLevel(headingLevel));
+    return (_jsxs("article", { id: id, ...componentRoot("Release"), className: cx("m-release", className), children: [_jsxs("header", { children: [_jsx(Heading, { className: "m-release-version", children: version }), _jsx("time", { dateTime: date, children: dateLabel })] }), _jsx("div", { children: changes.map((c) => (_jsxs("section", { "data-type": c.type, children: [_jsx(GroupHeading, { className: "m-release-type", children: c.type.charAt(0).toUpperCase() + c.type.slice(1) }), _jsx("ul", { children: c.items.map((item, i) => (_jsx("li", { children: item }, i))) })] }, c.type))) })] }));
+}
+export function ApiEndpoint({ id, className, headingLevel = 2, method, path, title, description, paramsLabel = "Body parameters", params, examples, }) {
+    const headingId = useId();
+    const Heading = headingTag(headingLevel);
+    const ParamsHeading = headingTag(childLevel(headingLevel));
+    return (_jsxs("section", { id: id, ...componentRoot("ApiEndpoint"), className: cx("m-api-endpoint", className), "aria-labelledby": headingId, children: [_jsxs("div", { className: "m-api-text", children: [_jsxs("p", { className: "m-api-route", children: [_jsx("span", { "data-method": method, children: method }), _jsx("code", { children: path })] }), _jsx(Heading, { id: headingId, className: "m-api-title", children: title }), description && _jsx("div", { className: "m-api-description", children: description }), _jsx(ParamsHeading, { className: "m-api-params-title", children: paramsLabel }), _jsx(TermList, { className: "m-param-list", items: params.map((p) => ({
+                            key: p.name,
+                            term: (_jsxs(_Fragment, { children: [_jsx("code", { children: p.name }), _jsx("span", { children: p.type }), _jsx("span", { "data-required": p.required || undefined, children: p.required ? "Required" : "Optional" })] })),
+                            details: p.description,
+                        })) })] }), examples && _jsx("div", { className: "m-api-examples", children: examples })] }));
+}
+export function PageFeedback({ id, className, question = "Was this page helpful?", value, onChange, updated, }) {
+    return (_jsxs("div", { id: id, ...componentRoot("PageFeedback"), className: cx("m-page-feedback", className), children: [_jsxs("div", { role: "group", "aria-label": question, children: [_jsx("span", { children: question }), ["yes", "no"].map((v) => (_jsx("button", { type: "button", "aria-pressed": value === v, onClick: () => onChange(v), children: v === "yes" ? "Yes" : "No" }, v)))] }), updated && _jsx("span", { children: updated })] }));
+}
+export function PagerLinks({ id, className, previous, next, label = "Previous and next page", }) {
+    return (_jsxs("nav", { id: id, ...componentRoot("PagerLinks"), className: cx("m-pager", className), "aria-label": label, children: [previous ? (_jsxs(KitLink, { href: previous.href, rel: "prev", children: [_jsx("small", { children: "Previous" }), _jsxs("span", { children: [_jsx("span", { "aria-hidden": "true", children: "\u2190 " }), previous.label] })] })) : (_jsx("span", {})), next && (_jsxs(KitLink, { href: next.href, rel: "next", "data-next": "true", children: [_jsx("small", { children: "Next" }), _jsxs("span", { children: [next.label, _jsx("span", { "aria-hidden": "true", children: " \u2192" })] })] }))] }));
+}
+export function LinkCards({ id, className, items, }) {
+    return (_jsx("ul", { id: id, ...componentRoot("LinkCards"), className: cx("m-link-cards", className), children: items.map((item, index) => (_jsx("li", { children: _jsxs(KitLink, { href: item.href, children: [_jsxs("strong", { children: [item.label, _jsx("span", { "aria-hidden": "true", children: " \u2192" })] }), item.description && _jsx("span", { children: item.description })] }) }, `${item.label}:${item.href}:${index}`))) }));
+}

package/dist/ecommerce.d.ts

@@ -0,0 +1,261 @@
+import { type ReactNode } from "react";
+import { type ProgressStep } from "./application.js";
+import { type HeadingLevel } from "./heading.js";
+export interface ProductImage {
+    src: string;
+    /** Describe the product shown; images are the main product information. */
+    alt: string;
+}
+export interface ProductCard {
+    id: string;
+    name: string;
+    href: string;
+    /** Preformatted price, e.g. "£32" or "From £18". */
+    price: string;
+    image: ProductImage;
+    /** Colour, variant or category shown under the name. */
+    meta?: string;
+    badge?: string;
+    /** Supporting text under the name, e.g. in the card variant. */
+    description?: string;
+    /** Available colours as data: `swatch` is any CSS colour the consumer supplies; the label is announced. */
+    swatches?: {
+        label: string;
+        swatch: string;
+    }[];
+    /** Control under the card, e.g. an "Add to bag" button; it sits above the card link. */
+    action?: ReactNode;
+}
+export interface ProductListProps {
+    /** Accessible name of the list. */
+    label: string;
+    products: ProductCard[];
+    columns?: 2 | 3 | 4;
+    /** Heading level of each product name (default 3). */
+    itemHeadingLevel?: HeadingLevel;
+    /**
+     * `cards` frames each product with a border, for listings with full
+     * details; `overlay` sets the name and price on a panel over the image.
+     */
+    variant?: "plain" | "cards" | "overlay";
+    id?: string;
+    className?: string;
+}
+/** Grid of product cards; each card's name link covers the card. */
+export declare function ProductList({ label, products, columns, itemHeadingLevel, variant, id, className, }: ProductListProps): import("react").JSX.Element;
+export interface ProductOption {
+    id: string;
+    label: string;
+    values: {
+        value: string;
+        label: string;
+        /** CSS colour for a swatch; the label remains the accessible name. */
+        swatch?: string;
+        disabled?: boolean;
+    }[];
+}
+export interface ProductOverviewProps {
+    name: string;
+    price: string;
+    description?: ReactNode;
+    images: ProductImage[];
+    rating?: {
+        value: number;
+        count: number;
+        href?: string;
+    };
+    options?: ProductOption[];
+    /** Selected value per option id. */
+    selected?: Record<string, string>;
+    onSelect?: (option: string, value: string) => void;
+    /** Called when the add form is submitted (button click or Enter). */
+    onAdd?: () => void;
+    addLabel?: string;
+    /** Shows the add button as busy while the item is being added. */
+    loading?: boolean;
+    details?: string[];
+    /** Level of the product name heading (default 1: the product page's title). */
+    headingLevel?: HeadingLevel;
+    /** Omit the name heading when a container (e.g. a dialog title) already shows it. */
+    hideName?: boolean;
+    /** `grid` shows every image at once: the first large, the rest tiered beneath it. */
+    gallery?: "thumbnails" | "grid";
+    id?: string;
+    className?: string;
+}
+/** Product page body: gallery, price, rating, option pickers, add to bag and details. */
+export declare function ProductOverview({ name, price, description, images, rating, options, selected, onSelect, onAdd, addLabel, loading, details, headingLevel, hideName, gallery, id, className, }: ProductOverviewProps): import("react").JSX.Element;
+export interface CartItem {
+    id: string;
+    name: string;
+    href: string;
+    price: string;
+    quantity: number;
+    image: ProductImage;
+    /** Chosen options, e.g. "Natural · Small". */
+    meta?: string;
+    /** Availability note, e.g. "In stock" or "Ships in 3 weeks". */
+    stock?: string;
+}
+/** Content of an empty state: a title, an optional description and action. */
+export interface EmptyContent {
+    title: string;
+    description?: string;
+    action?: ReactNode;
+}
+export interface ShoppingCartProps {
+    items: CartItem[];
+    onQuantityChange: (id: string, quantity: number) => void;
+    onRemove: (id: string) => void;
+    /** Accessible name of the list of lines. */
+    label?: string;
+    maxQuantity?: number;
+    /** Level of each line's product name, and of the empty state's title (default 3). */
+    headingLevel?: HeadingLevel;
+    /** Shown when there are no items. */
+    empty?: EmptyContent;
+    /**
+     * Beside the lines when wide and below them when narrow, e.g. an
+     * OrderSummary with shipping and tax estimates and the checkout action.
+     */
+    summary?: ReactNode;
+    /**
+     * Products to suggest under the bag, shown as a ProductList with a heading
+     * (default level 2; product names one level below). Also shown when the
+     * bag is empty.
+     */
+    related?: {
+        title: string;
+        products: ProductCard[];
+        headingLevel?: HeadingLevel;
+    };
+    id?: string;
+    className?: string;
+}
+/**
+ * Bag contents with per-line quantity and remove controls. After a removal,
+ * focus moves to the next line's Remove button (the previous one after the
+ * last line), or to the empty state once the bag is empty.
+ */
+export declare function ShoppingCart({ summary, related, id, className, ...props }: ShoppingCartProps): import("react").JSX.Element;
+/** Cost breakdown with a distinguished total and a checkout action. */
+export declare function OrderSummary({ title, lines, total, action, headingLevel, children, id, className, }: {
+    title?: string;
+    /**
+     * Cost lines. `hint` explains an estimate under its label, e.g. "Calculated
+     * at checkout" or a link to how shipping is worked out.
+     */
+    lines: {
+        label: string;
+        value: string;
+        hint?: ReactNode;
+    }[];
+    total: {
+        label: string;
+        value: string;
+    };
+    action?: ReactNode;
+    headingLevel?: HeadingLevel;
+    /** Notes such as a discount code field or delivery estimate. */
+    children?: ReactNode;
+    id?: string;
+    className?: string;
+}): import("react").JSX.Element;
+/** Product overview in a dialog, with a link to the full product page. */
+export declare function ProductQuickView({ open, onClose, href, detailsLabel, className, ...product }: Omit<ProductOverviewProps, "headingLevel" | "hideName" | "id" | "className"> & {
+    open: boolean;
+    onClose: () => void;
+    /** Full product page. */
+    href: string;
+    detailsLabel?: string;
+    /** Class on the dialog's content wrapper. */
+    className?: string;
+}): import("react").JSX.Element;
+export interface FilterFacet {
+    id: string;
+    label: string;
+    options: {
+        value: string;
+        label: string;
+        count?: number;
+    }[];
+}
+/**
+ * Collapsible checkbox facets with counts, plus removable chips for active
+ * filters. Every change, Clear all included, calls `onChange` once with the
+ * complete next selection.
+ */
+export declare function ProductFilters({ facets, selected, onChange, label, id, className, }: {
+    facets: FilterFacet[];
+    /** Selected values per facet id. */
+    selected: Record<string, string[]>;
+    /** The complete next selection, keyed by facet id. */
+    onChange: (selected: Record<string, string[]>) => void;
+    label?: string;
+    id?: string;
+    className?: string;
+}): import("react").JSX.Element;
+export interface Review {
+    id: string;
+    author: string;
+    rating: number;
+    date: string;
+    title: string;
+    body: ReactNode;
+    /** Reviewer's photo, shown with `avatars`; without it the Avatar shows initials. */
+    avatar?: string;
+}
+/** Rating summary with a star distribution, followed by individual reviews. */
+export declare function ProductReviews({ title, average, count, distribution, reviews, action, avatars, headingLevel, id, className, }: {
+    title?: string;
+    average: number;
+    count: number;
+    distribution: {
+        stars: number;
+        count: number;
+    }[];
+    reviews: Review[];
+    /** E.g. a "Write a review" button. */
+    action?: ReactNode;
+    /** Shows each reviewer's Avatar (their `avatar` photo or initials) beside their name. */
+    avatars?: boolean;
+    /** Level of the title; each review's title is one level below. */
+    headingLevel?: HeadingLevel;
+    id?: string;
+    className?: string;
+}): import("react").JSX.Element;
+export interface Order {
+    id: string;
+    number: string;
+    date: string;
+    total: string;
+    status: string;
+    href: string;
+    /** Order-level controls in the header, e.g. "View invoice" or an actions menu. */
+    actions?: ReactNode;
+    /**
+     * Delivery stages shown as a tracker under the status, e.g. Order placed,
+     * Processing, Shipped and Delivered, with the latest stage `current`.
+     */
+    progress?: ProgressStep[];
+    items: {
+        id: string;
+        name: string;
+        image: ProductImage;
+        quantity: number;
+        price: string;
+        href?: string;
+        /** Per-item controls, e.g. "Buy again" and "View product". */
+        actions?: ReactNode;
+    }[];
+}
+/** Past orders, each with its summary, status and line items. */
+export declare function OrderHistory({ orders, headingLevel, empty, id, className, }: {
+    orders: Order[];
+    /** Level of each order's heading, and of the empty state's title (default 2). */
+    headingLevel?: HeadingLevel;
+    /** Shown when there are no orders. */
+    empty?: EmptyContent;
+    id?: string;
+    className?: string;
+}): import("react").JSX.Element;