@designtools/docs 0.0.0-stage → 0.1.0

package/dist/lib/adherence-types.d.ts

@@ -0,0 +1,168 @@
+/**
+ * The adherence report: what `designtools-adherence` writes with `--json`, and
+ * what the "Adherence summary" docs block renders.
+ *
+ * This file has no imports on purpose, so @designtools/docs can carry a copy
+ * and read the report through the same types the tool wrote it with.
+ *
+ * Every path is relative to the project root, with forward slashes. Lines and
+ * columns start at 1. Every array is sorted (files and routes by path, findings
+ * by line then column, components and elements by name), and there are no
+ * timestamps, so the same source gives the same bytes.
+ */
+export declare const ADHERENCE_SCHEMA = "designtools.adherence/1";
+export interface AdherenceReport {
+    /** `@designtools/adherence@<version>`. */
+    generator: string;
+    schema: string;
+    /** The components.json the system was read from. */
+    manifest: string;
+    /** The system folder, which is never scanned as product. */
+    system: string;
+    /** The globs that chose the product files, as given or defaulted. */
+    include: string[];
+    exclude: string[];
+    summary: Summary;
+    /** One per Next app router page (`app/**\/page.tsx`), sorted by route. */
+    routes: RouteEntry[];
+    /** Every scanned file with at least one use, raw element or finding, sorted by path. */
+    files: FileEntry[];
+    /** Every system component, used or not, sorted by name. */
+    components: ComponentUsage[];
+    /** Every raw element some component `replaces`, sorted by selector. */
+    elements: ElementUsage[];
+    /** Files a scanner could not parse, sorted by path. Their numbers are missing from the report. */
+    skipped: SkippedFile[];
+}
+/** The numbers every level of the report shares: the whole product, a route, a file. */
+export interface Counts {
+    /** JSX uses of system components, sub-components included. */
+    systemUses: number;
+    /** Raw elements that some system component `replaces`, such as `<button>` when Button replaces it. */
+    rawElements: number;
+    /**
+     * systemUses ÷ (systemUses + rawElements), from 0 to 1, to four decimal places.
+     * Null when both are 0: there was nothing to measure.
+     */
+    share: number | null;
+    /** Classes that bypass the tokens: palette steps and arbitrary values. */
+    offSystemValues: number;
+    /** System components given a className that changes colour, spacing or radius. */
+    overrides: number;
+}
+export interface Summary extends Counts {
+    /** Product files scanned. */
+    files: number;
+    /** Files with at least one raw element, off-system value or override. */
+    filesWithFindings: number;
+    offSystem: Record<OffSystemKind, number>;
+    overrideKinds: Record<OverrideKind, number>;
+    /** System components used at least once. */
+    componentsUsed: number;
+    /** System components never used in the product, by name. */
+    componentsUnused: string[];
+    /**
+     * The raw elements counted, from every component's `replaces`. Empty means no
+     * component declares any, so `share` measures nothing yet.
+     */
+    replaceable: string[];
+}
+export interface RouteEntry {
+    /** The URL path: route groups and parallel-route slots removed, dynamic segments kept. `/companies/[key]`. */
+    route: string;
+    /** The page file. */
+    page: string;
+    /**
+     * The files counted for the route: the page, files beside it, and files in
+     * folders under it that lead to no other page. Layouts shared by several
+     * routes are counted per file only.
+     */
+    files: string[];
+    counts: Counts;
+}
+export interface FileEntry {
+    file: string;
+    /** The route the file is counted under, when it has one. */
+    route?: string;
+    counts: Counts;
+    uses: ComponentUse[];
+    raw: RawElement[];
+    offSystem: OffSystemValue[];
+    overrides: Override[];
+}
+/** A literal prop value, or the kind of expression it was, e.g. `(Identifier)`. */
+export type PropValue = string | number | boolean | null;
+export interface ComponentUse {
+    /** The component's name in the manifest. */
+    component: string;
+    /** The element as written, when it differs: `Select.Trigger`, `DS.Button`. */
+    as?: string;
+    line: number;
+    column: number;
+    /** Props as written, sorted. A className built from expressions keeps its literal classes only. */
+    props: Record<string, PropValue>;
+    /** True when it also takes `{...spread}` props, whose names are unknown. */
+    spread: boolean;
+}
+export interface RawElement {
+    /** The tag as written: `button`. */
+    element: string;
+    /** The `replaces` selector it matched: `button`, `input[type=checkbox]`. */
+    selector: string;
+    /** The components that replace it, most specific first. */
+    replacedBy: string[];
+    line: number;
+    column: number;
+}
+/**
+ * `palette`: a primitive ramp step used directly, `bg-blue-500` or `text-primary-500`.
+ * `arbitrary`: a value in brackets, `p-[13px]` or `bg-[#fff]`.
+ * `status-text`: a status fill used as text, `text-destructive`: use `text-destructive-subdued-foreground`,
+ * which reads on every background, or neutral text with an icon for a warning.
+ */
+export type OffSystemKind = "palette" | "arbitrary" | "status-text";
+export interface OffSystemValue {
+    /** The class as written, variants included: `hover:bg-blue-500`. */
+    class: string;
+    kind: OffSystemKind;
+    line: number;
+    column: number;
+}
+export type OverrideKind = "colour" | "spacing" | "radius";
+export interface Override {
+    component: string;
+    /** Each class in the className that overrides the component, with what it changes. */
+    classes: {
+        class: string;
+        kind: OverrideKind;
+    }[];
+    line: number;
+    column: number;
+}
+export interface ComponentUsage {
+    name: string;
+    source: string;
+    uses: number;
+    /** Files it is used in. */
+    files: number;
+    /** How many uses pass each prop, by prop name. */
+    props: Record<string, number>;
+    /**
+     * Per variant axis, how many uses pick each option. A use that leaves the prop
+     * out counts under the axis's default, or `(unset)`; one that computes it
+     * counts under `(dynamic)`.
+     */
+    variants?: Record<string, Record<string, number>>;
+}
+export interface ElementUsage {
+    /** The `replaces` selector. */
+    selector: string;
+    /** Raw uses in the product. */
+    uses: number;
+    files: number;
+    replacedBy: string[];
+}
+export interface SkippedFile {
+    file: string;
+    reason: string;
+}

package/dist/lib/adherence-types.js

@@ -0,0 +1,13 @@
+/**
+ * The adherence report: what `designtools-adherence` writes with `--json`, and
+ * what the "Adherence summary" docs block renders.
+ *
+ * This file has no imports on purpose, so @designtools/docs can carry a copy
+ * and read the report through the same types the tool wrote it with.
+ *
+ * Every path is relative to the project root, with forward slashes. Lines and
+ * columns start at 1. Every array is sorted (files and routes by path, findings
+ * by line then column, components and elements by name), and there are no
+ * timestamps, so the same source gives the same bytes.
+ */
+export const ADHERENCE_SCHEMA = "designtools.adherence/1";

package/dist/lib/boundary.d.ts

@@ -0,0 +1,16 @@
+import { Component, type ReactNode } from "react";
+/** Keeps one broken example from blanking the whole page: the error shows where the example would. */
+export declare class Boundary extends Component<{
+    label: string;
+    children: ReactNode;
+}, {
+    error: Error | null;
+}> {
+    state: {
+        error: Error | null;
+    };
+    static getDerivedStateFromError(error: Error): {
+        error: Error;
+    };
+    render(): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
+}

package/dist/lib/boundary.js

@@ -0,0 +1,15 @@
+"use client";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+import { Component } from "react";
+/** Keeps one broken example from blanking the whole page: the error shows where the example would. */
+export class Boundary extends Component {
+    state = { error: null };
+    static getDerivedStateFromError(error) {
+        return { error };
+    }
+    render() {
+        if (!this.state.error)
+            return this.props.children;
+        return (_jsxs("p", { "data-slot": "block-error", role: "alert", className: "rounded-md border border-dashed border-destructive p-3 text-xs", children: [_jsxs("span", { className: "font-medium", children: [this.props.label, " did not render:"] }), " ", this.state.error.message] }));
+    }
+}

package/dist/lib/contrast.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Contrast measured on what the browser paints, not on the values written in
+ * the stylesheet: a 1px canvas turns any computed CSS colour (oklch, color-mix,
+ * a var chain) into sRGB bytes. Browser only.
+ */
+/** WCAG 2 contrast ratio between two CSS colours, or null where it cannot be measured. */
+export declare function contrastRatio(foreground: string, background: string): number | null;
+export declare function wcagGrade(ratio: number): "AAA" | "AA" | "AA large" | "Fail";

package/dist/lib/contrast.js

@@ -0,0 +1,42 @@
+/**
+ * Contrast measured on what the browser paints, not on the values written in
+ * the stylesheet: a 1px canvas turns any computed CSS colour (oklch, color-mix,
+ * a var chain) into sRGB bytes. Browser only.
+ */
+let context = null;
+function rgb(css) {
+    if (typeof document === "undefined")
+        return null;
+    if (!context) {
+        const canvas = document.createElement("canvas");
+        canvas.width = canvas.height = 1;
+        context = canvas.getContext("2d", { willReadFrequently: true });
+    }
+    if (!context)
+        return null;
+    context.clearRect(0, 0, 1, 1);
+    context.fillStyle = "#000";
+    context.fillStyle = css;
+    context.fillRect(0, 0, 1, 1);
+    const [r, g, b] = context.getImageData(0, 0, 1, 1).data;
+    return [r, g, b];
+}
+function luminance([r, g, b]) {
+    const channel = (v) => {
+        const s = v / 255;
+        return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+/** WCAG 2 contrast ratio between two CSS colours, or null where it cannot be measured. */
+export function contrastRatio(foreground, background) {
+    const a = rgb(foreground);
+    const b = rgb(background);
+    if (!a || !b)
+        return null;
+    const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (hi + 0.05) / (lo + 0.05);
+}
+export function wcagGrade(ratio) {
+    return ratio >= 7 ? "AAA" : ratio >= 4.5 ? "AA" : ratio >= 3 ? "AA large" : "Fail";
+}

package/dist/lib/cx.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Anything pressable in the docs: at least 44px by default (WCAG 2.5.5), with a
+ * pointer. A client with its own rule sets `--docs-target` on the docs layout
+ * (`3rem` for 48px), so the site that states the rule also meets it. Links inside
+ * a sentence are exempt, as WCAG exempts them. The pointer is here, not left to the
+ * project's base CSS: Tailwind v4 puts buttons back to the arrow, and a project
+ * without the rule would show every block's button and tab as inert.
+ */
+export declare const target = "min-h-[var(--docs-target,2.75rem)] min-w-[var(--docs-target,2.75rem)] cursor-pointer disabled:cursor-not-allowed data-disabled:cursor-not-allowed";
+/** Join class names, skipping the falsy ones. */
+export declare function cx(...classes: (string | false | null | undefined)[]): string;
+/**
+ * Headings in the docs: regular weight, large, so size makes the hierarchy rather
+ * than boldness; the brand's display face when the project names one
+ * (`--font-display`), else its body face. Set `--docs-display` on the docs layout
+ * to give the docs a face of their own.
+ */
+export declare const display = "font-normal [font-family:var(--docs-display,var(--font-display,var(--font-sans)))]";
+/**
+ * The docs' accent: the current page's marker in the navigation, the active tab. A
+ * fill or a bar, never text, so a pale brand colour (a yellow primary) cannot fail as
+ * text on the page. Defaults to the primary; set `--docs-accent` to change it.
+ */
+export declare const accent = "bg-[var(--docs-accent,var(--primary))]";

package/dist/lib/cx.js

@@ -0,0 +1,26 @@
+/**
+ * Anything pressable in the docs: at least 44px by default (WCAG 2.5.5), with a
+ * pointer. A client with its own rule sets `--docs-target` on the docs layout
+ * (`3rem` for 48px), so the site that states the rule also meets it. Links inside
+ * a sentence are exempt, as WCAG exempts them. The pointer is here, not left to the
+ * project's base CSS: Tailwind v4 puts buttons back to the arrow, and a project
+ * without the rule would show every block's button and tab as inert.
+ */
+export const target = "min-h-[var(--docs-target,2.75rem)] min-w-[var(--docs-target,2.75rem)] cursor-pointer disabled:cursor-not-allowed data-disabled:cursor-not-allowed";
+/** Join class names, skipping the falsy ones. */
+export function cx(...classes) {
+    return classes.filter(Boolean).join(" ");
+}
+/**
+ * Headings in the docs: regular weight, large, so size makes the hierarchy rather
+ * than boldness; the brand's display face when the project names one
+ * (`--font-display`), else its body face. Set `--docs-display` on the docs layout
+ * to give the docs a face of their own.
+ */
+export const display = "font-normal [font-family:var(--docs-display,var(--font-display,var(--font-sans)))]";
+/**
+ * The docs' accent: the current page's marker in the navigation, the active tab. A
+ * fill or a bar, never text, so a pale brand colour (a yellow primary) cannot fail as
+ * text on the page. Defaults to the primary; set `--docs-accent` to change it.
+ */
+export const accent = "bg-[var(--docs-accent,var(--primary))]";

package/dist/lib/jsx.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Props back to JSX, so the code shown beside a preview is the code that drew it.
+ * Defaults and undefined values are left out: the snippet is what a person would write.
+ */
+export type JsxProps = Record<string, unknown>;
+export declare function toJSX(name: string, props: JsxProps, children?: string): string;

package/dist/lib/jsx.js

@@ -0,0 +1,29 @@
+/**
+ * Props back to JSX, so the code shown beside a preview is the code that drew it.
+ * Defaults and undefined values are left out: the snippet is what a person would write.
+ */
+export function toJSX(name, props, children) {
+    const attrs = Object.entries(props)
+        .filter(([key, value]) => value !== undefined && key !== "children")
+        .map(([key, value]) => attribute(key, value));
+    // text with braces or angle brackets is not valid JSX as written; quote it as an expression
+    if (children && /[{}<>]/.test(children))
+        children = `{${JSON.stringify(children)}}`;
+    const open = attrs.length ? `<${name} ${attrs.join(" ")}` : `<${name}`;
+    const oneLine = children ? `${open}>${children}</${name}>` : `${open} />`;
+    if (oneLine.length <= 80)
+        return oneLine;
+    const lines = [`<${name}`, ...attrs.map((a) => `  ${a}`)];
+    return children ? `${lines.join("\n")}\n>\n  ${children}\n</${name}>` : `${lines.join("\n")}\n/>`;
+}
+function attribute(key, value) {
+    if (value === true)
+        return key;
+    if (typeof value === "string")
+        return /["\n{}]/.test(value) ? `${key}={${JSON.stringify(value)}}` : `${key}="${value}"`;
+    if (typeof value === "number" || typeof value === "boolean")
+        return `${key}={${String(value)}}`;
+    if (typeof value === "function")
+        return `${key}={() => {}}`;
+    return `${key}={${JSON.stringify(value)}}`;
+}

package/dist/lib/lookup.d.ts

@@ -0,0 +1,35 @@
+import { type ComponentType, type ReactNode } from "react";
+import type { AssetEntry, ComponentEntry, PatternEntry } from "./manifest-types.js";
+import { type Registry } from "./registry.js";
+/**
+ * The project's components, examples, patterns and assets, from the registry
+ * around the docs. Call it once at the top of a block, then look things up.
+ */
+export declare function useLookup(): {
+    /** The real component a manifest entry describes. */
+    componentFor: (entry: ComponentEntry) => ComponentType<any> | undefined;
+    /** The examples module for a component: each named export is an example. */
+    examplesFor: (entry: ComponentEntry) => Record<string, unknown> | undefined;
+    /** The pattern module: each named export is a composition. */
+    compositionsFor: (pattern: PatternEntry) => Record<string, unknown> | undefined;
+    /** A brand asset's URL, from its static import in the registry. */
+    assetUrl: (asset: AssetEntry) => string | undefined;
+};
+export declare function lookupIn(registry: Registry): {
+    /** The real component a manifest entry describes. */
+    componentFor: (entry: ComponentEntry) => ComponentType<any> | undefined;
+    /** The examples module for a component: each named export is an example. */
+    examplesFor: (entry: ComponentEntry) => Record<string, unknown> | undefined;
+    /** The pattern module: each named export is a composition. */
+    compositionsFor: (pattern: PatternEntry) => Record<string, unknown> | undefined;
+    /** A brand asset's URL, from its static import in the registry. */
+    assetUrl: (asset: AssetEntry) => string | undefined;
+};
+/** Variant values are text in the manifest; boolean variants want booleans. */
+export declare function coerce(values: Record<string, string>): Record<string, unknown>;
+export declare function Missing({ name, what }: {
+    name: string;
+    what?: string;
+}): import("react").JSX.Element;
+/** An example export is a component that takes no props, or an element. */
+export declare function renderExample(value: unknown, name: string): ReactNode;

package/dist/lib/lookup.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createElement, isValidElement } from "react";
+import { componentKey } from "./manifest.js";
+import { useRegistry } from "./registry.js";
+/**
+ * The project's components, examples, patterns and assets, from the registry
+ * around the docs. Call it once at the top of a block, then look things up.
+ */
+export function useLookup() {
+    return lookupIn(useRegistry());
+}
+export function lookupIn(registry) {
+    return {
+        /** The real component a manifest entry describes. */
+        componentFor: (entry) => registry.components[componentKey(entry)],
+        /** The examples module for a component: each named export is an example. */
+        examplesFor: (entry) => (entry.examples ? registry.examples[entry.examples.source] : undefined),
+        /** The pattern module: each named export is a composition. */
+        compositionsFor: (pattern) => registry.patterns[pattern.source],
+        /** A brand asset's URL, from its static import in the registry. */
+        assetUrl: (asset) => {
+            const imported = registry.assets[asset.file];
+            return typeof imported === "string" ? imported : imported?.src;
+        },
+    };
+}
+/** Variant values are text in the manifest; boolean variants want booleans. */
+export function coerce(values) {
+    return Object.fromEntries(Object.entries(values).map(([k, v]) => [k, v === "true" ? true : v === "false" ? false : v]));
+}
+export function Missing({ name, what = "component" }) {
+    return (_jsxs("p", { "data-slot": "block-missing", className: "rounded-md border border-dashed border-border p-4 text-sm text-muted-foreground", children: [name, "'s ", what, " is not in the generated registry. Run ", _jsx("code", { className: "font-mono", children: "designtools-docs map" }), " ", "after rebuilding the manifest."] }));
+}
+/** An example export is a component that takes no props, or an element. */
+export function renderExample(value, name) {
+    if (isValidElement(value))
+        return value;
+    if (typeof value === "function")
+        return createElement(value);
+    return _jsxs("span", { className: "text-xs text-muted-foreground", children: [name, " is not a component or an element."] });
+}