@designtools/docs 0.0.0-stage → 0.1.0

package/src/lib/adherence-types.ts

@@ -0,0 +1,181 @@
+/**
+ * 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";
+
+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/src/lib/boundary.tsx

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

package/src/lib/contrast.ts

@@ -0,0 +1,44 @@
+/**
+ * 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: CanvasRenderingContext2D | null = null;
+
+function rgb(css: string): [number, number, number] | null {
+  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]: [number, number, number]): number {
+  const channel = (v: number) => {
+    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: string, background: string): number | null {
+  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: number): "AAA" | "AA" | "AA large" | "Fail" {
+  return ratio >= 7 ? "AAA" : ratio >= 4.5 ? "AA" : ratio >= 3 ? "AA large" : "Fail";
+}

package/src/lib/cx.ts

@@ -0,0 +1,30 @@
+/**
+ * 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: (string | false | null | undefined)[]): string {
+  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/src/lib/jsx.ts

@@ -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 type JsxProps = Record<string, unknown>;
+
+export function toJSX(name: string, props: JsxProps, children?: string): string {
+  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: string, value: unknown): string {
+  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/src/lib/lookup.tsx

@@ -0,0 +1,49 @@
+import { createElement, isValidElement, type ComponentType, type ReactNode } from "react";
+import { componentKey } from "./manifest";
+import type { AssetEntry, ComponentEntry, PatternEntry } from "./manifest-types";
+import { type Registry, useRegistry } from "./registry";
+
+/**
+ * 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: Registry) {
+  return {
+    /** The real component a manifest entry describes. */
+    componentFor: (entry: ComponentEntry): ComponentType<any> | undefined => registry.components[componentKey(entry)],
+    /** The examples module for a component: each named export is an example. */
+    examplesFor: (entry: ComponentEntry): Record<string, unknown> | undefined => (entry.examples ? registry.examples[entry.examples.source] : undefined),
+    /** The pattern module: each named export is a composition. */
+    compositionsFor: (pattern: PatternEntry): Record<string, unknown> | undefined => registry.patterns[pattern.source],
+    /** A brand asset's URL, from its static import in the registry. */
+    assetUrl: (asset: AssetEntry): string | undefined => {
+      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: Record<string, string>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(values).map(([k, v]) => [k, v === "true" ? true : v === "false" ? false : v]));
+}
+
+export function Missing({ name, what = "component" }: { name: string; what?: string }) {
+  return (
+    <p data-slot="block-missing" className="rounded-md border border-dashed border-border p-4 text-sm text-muted-foreground">
+      {name}&apos;s {what} is not in the generated registry. Run <code className="font-mono">designtools-docs map</code>{" "}
+      after rebuilding the manifest.
+    </p>
+  );
+}
+
+/** An example export is a component that takes no props, or an element. */
+export function renderExample(value: unknown, name: string): ReactNode {
+  if (isValidElement(value)) return value;
+  if (typeof value === "function") return createElement(value as ComponentType);
+  return <span className="text-xs text-muted-foreground">{name} is not a component or an element.</span>;
+}

package/src/lib/manifest-types.ts

@@ -0,0 +1,284 @@
+/**
+ * The manifest schema: what `designtools-manifest build` writes to
+ * `<system>/manifest/`: components.json, tokens.json, rules.json,
+ * patterns.json, taxonomy.json and assets.json.
+ *
+ * This file has no imports on purpose. @designtools/docs carries a byte-identical
+ * copy, so a project's docs read the manifest through the same types the tool
+ * wrote it with, and a test in this repo fails if the two drift.
+ *
+ * Every path is relative to the project root, with forward slashes. Arrays keep
+ * source order where order means something (variant axes, fixture states, token
+ * ramps); everything else is sorted, so a diff of the files shows only real changes.
+ */
+
+export const MANIFEST_SCHEMA = "designtools.manifest/1";
+
+/** What every manifest file opens with. */
+interface ManifestFile {
+  /** `@designtools/manifest@<version>`, so `check` can tell a tool upgrade from an edit. */
+  generator: string;
+  schema: string;
+}
+
+/** components.json */
+export interface ComponentsManifest extends ManifestFile {
+  /** The system folder the components were read from. */
+  system: string;
+  /** Sorted by name, then source. */
+  components: ComponentEntry[];
+}
+
+export interface ComponentEntry {
+  /** The export name, or `@name` when the JSDoc gives one. */
+  name: string;
+  /** The exported identifier to import. Equals `name` unless `@name` renamed it. */
+  export: string;
+  /** The file that exports it. */
+  source: string;
+  /**
+   * The module specifier an app imports it by, through the tsconfig path alias
+   * that reaches the system folder (`@ds/button/button`). Absent when no alias does,
+   * in which case `source` is the only honest answer.
+   */
+  import?: string;
+  /** The component's JSDoc, or its variant config's when the component has none. */
+  description?: string;
+  /** `@category`. Blocks group components without one under "Components". */
+  category?: string;
+  /** `@status`, or `deprecated` from `@deprecated`. Absent until someone decides it. */
+  status?: Status;
+  /** Why it has that status: the `@deprecated` reason, or text after `@status`. */
+  statusNote?: string;
+  /** `@use`, `@avoid`, `@instead`: when to reach for it, when not, and what instead. */
+  usage?: Usage;
+  /** `@example` snippets in the JSDoc, each one JSX. */
+  snippets?: string[];
+  /** `@see`, each one a link or a component name. */
+  see?: string[];
+  /** `@primitive`: the primitive it wraps, as a link or a package path. */
+  primitive?: string;
+  /** `@aria`: the ARIA pattern it follows, usually a link. */
+  aria?: string;
+  /** `@role` and `@keyboard`: what assistive technology meets, and the keys it answers. */
+  a11y?: { role?: string; keyboard?: string[] };
+  /** `@replaces`: raw elements this component stands in for, which the adherence report counts. */
+  replaces?: string[];
+  /**
+   * What it also accepts beyond its own props: an intrinsic element (`"span"`)
+   * or a wrapped primitive (`"@base-ui/react/select:Root"`).
+   */
+  inherits?: string[];
+  /** Its own props, and those of a primitive it wraps. Inherited DOM props are left out. */
+  props: Record<string, PropEntry>;
+  /** Absent when it has no variants by any route. */
+  variants?: VariantsEntry;
+  /** Every `data-slot` it renders, sorted. */
+  slots: string[];
+  /** Absent when the component has no examples file. */
+  examples?: ExamplesEntry;
+}
+
+export type Status = "stable" | "emerging" | "deprecated";
+
+export interface Usage {
+  use?: string;
+  avoid?: string;
+  /** Components, or other things, to use instead. */
+  instead?: string[];
+}
+
+export interface PropEntry {
+  /** The type as written or resolved, e.g. `string`, `"sm" | "md"`, `(v: string) => void`. */
+  type: string;
+  /** Present when the type is a union of literals: each value, unquoted. */
+  values?: string[];
+  required: boolean;
+  /** The default, as source text, when the component destructures one. */
+  default?: string;
+  description?: string;
+  deprecated?: string;
+  /** The package that declares it, when it comes from a wrapped primitive rather than the project. */
+  from?: string;
+}
+
+export interface VariantsEntry {
+  /** Where the axes came from: a `tv()` or `cva()` config, or the props' literal union types. */
+  from: "tv" | "cva" | "props";
+  /** The config's variable name. Absent when `from` is `"props"`. */
+  config?: string;
+  /** Source order. */
+  axes: VariantAxis[];
+  /** Conditions only, without their classes, in source order. */
+  compound?: Record<string, string | string[]>[];
+  /** A `tv()` config's named parts, in source order. */
+  parts?: string[];
+}
+
+export interface VariantAxis {
+  name: string;
+  /** Source order. */
+  options: VariantOption[];
+  default?: string;
+}
+
+export interface VariantOption {
+  name: string;
+  description?: string;
+}
+
+/**
+ * A co-located `*.examples.tsx`: `canonical` is the one to copy, `do*` and
+ * `dont*` render as pairs in order, anything else is a further example.
+ */
+export interface ExamplesEntry {
+  source: string;
+  canonical?: ExampleRef;
+  do: ExampleRef[];
+  dont: ExampleRef[];
+  other: ExampleRef[];
+}
+
+export interface ExampleRef {
+  /** The export name. */
+  name: string;
+  /** Its JSDoc: why to do it, or why not. */
+  description?: string;
+  /** The JSX it returns, as written, for agents and code views. */
+  code?: string;
+}
+
+/** tokens.json */
+export interface TokensManifest extends ManifestFile {
+  /** The stylesheets read, in the order given. */
+  sources: string[];
+  /** Source order: file by file, declaration by declaration. */
+  tokens: TokenEntry[];
+}
+
+export type TokenTier =
+  | "color"
+  | "font"
+  | "font-weight"
+  | "text"
+  | "leading"
+  | "tracking"
+  | "spacing"
+  | "size"
+  | "radius"
+  | "shadow"
+  | "ease"
+  | "duration"
+  | "motion"
+  | "breakpoint"
+  | "container"
+  | "other";
+
+export interface TokenEntry {
+  /** The custom property, with its dashes: `--color-primary-500`. */
+  name: string;
+  tier: TokenTier;
+  /**
+   * The value in each context it is declared in. `default` is `@theme` or `:root`;
+   * `light` and `dark` are the mode blocks; a `p3:` prefix marks the
+   * `@media (color-gamut: p3)` layer. Any other selector is kept as written.
+   */
+  values: Record<string, string>;
+  /** The comment above it, or above the run of declarations it belongs to. */
+  description?: string;
+  /** The stylesheet that first declares it. */
+  source: string;
+  /** Later stylesheets whose declaration replaced a value, in the order read: an override layer. */
+  overriddenIn?: string[];
+}
+
+/** rules.json: brand and interface rules in one format. */
+export interface RulesManifest extends ManifestFile {
+  /** Sorted by id. */
+  rules: RuleEntry[];
+}
+
+export interface RuleEntry {
+  /** The file name without `.rule.json`, used as its anchor: `touch-target`. */
+  id: string;
+  kind: "brand" | "interface";
+  title: string;
+  /** The rule, in one or two sentences, for people first. */
+  statement: string;
+  /** Why it exists. */
+  rationale?: string;
+  /** The measurable line, e.g. `44 × 44 CSS px`. */
+  threshold?: string;
+  /** Components, elements, assets or pages it governs. */
+  appliesTo?: string[];
+  exceptions?: string[];
+  /** Tokens it rests on, e.g. `--size-2xl`. */
+  tokens?: string[];
+  /**
+   * Confirmed with the client, an assumption still to confirm, or measured: generated from the
+   * tokens (where a colour can be text), a fact that changes when they do, not a decision.
+   */
+  status: "confirmed" | "assumption" | "measured";
+  /** How it is proved: a test, a lint rule, an audit, or a person. */
+  check?: { kind: "test" | "lint" | "audit" | "manual"; ref?: string; description?: string };
+  source: string;
+}
+
+/** patterns.json: the product's recurring screen compositions. */
+export interface PatternsManifest extends ManifestFile {
+  /** Sorted by name. */
+  patterns: PatternEntry[];
+}
+
+export interface PatternEntry {
+  /** From the file name: `checkout` for `checkout.pattern.tsx`. */
+  id: string;
+  name: string;
+  description?: string;
+  status?: Status;
+  /** The system components it imports, by name, sorted. */
+  components: string[];
+  /** Each named export is a composition, in source order. */
+  examples: ExampleRef[];
+  source: string;
+}
+
+/** taxonomy.json: one vocabulary, with the wrong forms to avoid. */
+export interface TaxonomyManifest extends ManifestFile {
+  /** Sorted by name. */
+  terms: TermEntry[];
+}
+
+export interface TermEntry {
+  /** The canonical form. */
+  name: string;
+  kind: "component" | "variant" | "token" | "pattern" | "rule" | "product";
+  /** Known wrong forms: `error` for `destructive`, `Modal` for `Dialog`, "log in" for "sign in". */
+  wrong?: string[];
+  note?: string;
+  /** Where it is defined: a component's source, a token's name, a rule's id. */
+  ref?: string;
+}
+
+/** assets.json: logos, icons and imagery, with how to use them. */
+export interface AssetsManifest extends ManifestFile {
+  /** Sorted by file. */
+  assets: AssetEntry[];
+}
+
+export interface AssetEntry {
+  file: string;
+  kind: "logo" | "icon" | "image" | "other";
+  name: string;
+  usage?: string;
+  /** e.g. `24px tall` */
+  minSize?: string;
+  /** e.g. `the height of the wordmark's x` or a length */
+  clearSpace?: string;
+  /** Surfaces it may sit on, as semantic colour names: `canvas`, `primary`. */
+  surfaces?: string[];
+  alt?: string;
+  /** Intrinsic size, read from an SVG's viewBox or a PNG's header. */
+  width?: number;
+  height?: number;
+}