@designtools/blocks 0.0.0-stage → 0.2.0

package/registry/examples.tsx

@@ -0,0 +1,97 @@
+"use client";
+
+import { CodeView } from "./code-view";
+import { Boundary } from "./lib/boundary";
+import { cx, target } from "./lib/cx";
+import { examplesFor, Missing, renderExample } from "./lib/lookup";
+import type { ComponentEntry, ExampleRef } from "./lib/manifest-types";
+import { inline } from "./lib/text";
+
+/**
+ * The canonical example first, the one to copy, then each do beside its don't.
+ * Every example is the real component; the code under it is the code that drew it.
+ */
+export function Examples({ entry, previewHref }: { entry: ComponentEntry; previewHref?: string }) {
+  const ex = entry.examples;
+  if (!ex) {
+    return (
+      <p data-slot="examples-empty" className="text-sm text-muted-foreground">
+        No examples yet. Add <code className="font-mono text-xs">{entry.source.replace(/\.tsx$/, ".examples.tsx")}</code> with a{" "}
+        <code className="font-mono text-xs">canonical</code> export and do and don&apos;t pairs.
+      </p>
+    );
+  }
+  const module = examplesFor(entry);
+  if (!module) return <Missing name={entry.name} what="examples" />;
+
+  const pairs = Array.from({ length: Math.max(ex.do.length, ex.dont.length) }, (_, i) => [ex.do[i], ex.dont[i]] as const);
+  const card = (ref: ExampleRef, kind: "canonical" | "do" | "dont" | "other") => (
+    <Example key={ref.name} example={ref} kind={kind} value={module[ref.name]} href={previewHref && `${previewHref}/${encodeURIComponent(ref.name)}`} />
+  );
+
+  return (
+    <div data-slot="examples" className="flex flex-col gap-6">
+      {ex.canonical && card(ex.canonical, "canonical")}
+      {pairs.map(([d, n], i) => (
+        <div key={i} data-slot="examples-pair" className="grid grid-cols-1 gap-4 md:grid-cols-2">
+          {d ? card(d, "do") : <span />}
+          {n ? card(n, "dont") : <span />}
+        </div>
+      ))}
+      {ex.other.length > 0 && <div className="grid grid-cols-1 gap-4 md:grid-cols-2">{ex.other.map((o) => card(o, "other"))}</div>}
+    </div>
+  );
+}
+
+const LABEL = { canonical: "Copy this one", do: "Do", dont: "Don't", other: "" } as const;
+
+function Example({ example, kind, value, href }: { example: ExampleRef; kind: keyof typeof LABEL; value: unknown; href?: string }) {
+  return (
+    <figure
+      data-slot="example"
+      data-kind={kind}
+      className={cx(
+        "flex min-w-0 flex-col overflow-hidden rounded-lg border",
+        kind === "do" ? "border-success" : kind === "dont" ? "border-destructive" : "border-border",
+      )}
+    >
+      <div data-slot="example-frame" className="flex min-h-32 items-center justify-center overflow-auto bg-surface p-6 text-surface-foreground">
+        <Boundary label={example.name}>{renderExample(value, example.name)}</Boundary>
+      </div>
+      <figcaption className="flex flex-col gap-2 border-t border-border px-4 py-3 text-sm">
+        <span className="flex items-baseline justify-between gap-3">
+          <span className="flex items-baseline gap-2">
+            {LABEL[kind] && (
+              <span
+                // a measured pairing, not a fill colour used as text (text-success read 3.9:1 on the canvas)
+                className={cx(
+                  "rounded-sm px-1.5 font-medium",
+                  kind === "do" && "bg-success-subdued text-success-subdued-foreground",
+                  kind === "dont" && "bg-destructive-subdued text-destructive-subdued-foreground",
+                )}
+              >
+                {kind === "do" ? "✓ " : kind === "dont" ? "✕ " : ""}
+                {LABEL[kind]}
+              </span>
+            )}
+            <code className="font-mono text-xs text-muted-foreground">{example.name}</code>
+          </span>
+          {href && (
+            <a href={href} className={cx(target, "inline-flex items-center text-xs underline underline-offset-2")}>
+              Open alone
+            </a>
+          )}
+        </span>
+        {example.description && <span className="text-muted-foreground">{inline(example.description)}</span>}
+        {example.code && (
+          <details>
+            <summary className={cx(target, "flex w-fit cursor-pointer items-center text-xs text-muted-foreground")}>Code</summary>
+            <div className="mt-2">
+              <CodeView code={example.code} label={example.name} />
+            </div>
+          </details>
+        )}
+      </figcaption>
+    </figure>
+  );
+}

package/registry/glossary.tsx

@@ -0,0 +1,59 @@
+"use client";
+
+import { useId, useState } from "react";
+import type { TermEntry } from "./lib/manifest-types";
+import { inline } from "./lib/text";
+import { target } from "./lib/cx";
+
+/** Every name in the system, searchable by its wrong forms too, so a wrong name finds the right one. */
+export function Glossary({ terms }: { terms: TermEntry[] }) {
+  const id = useId();
+  const [query, setQuery] = useState("");
+  const q = query.trim().toLowerCase();
+  const matches = q ? terms.filter((t) => t.name.toLowerCase().includes(q) || t.wrong?.some((w) => w.toLowerCase().includes(q))) : terms;
+  const corrected = q ? terms.find((t) => t.wrong?.some((w) => w.toLowerCase() === q)) : undefined;
+
+  return (
+    <div data-slot="glossary" className="flex flex-col gap-4">
+      <div className="flex flex-col gap-1.5">
+        <label htmlFor={id} className="text-sm font-medium">
+          Find a term
+        </label>
+        <input
+          id={id}
+          type="search"
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          placeholder="Try a name you half remember"
+          className={`${target} h-(--size-xl) max-w-sm rounded-md border border-input bg-canvas px-3 text-sm focus-visible:outline-2 focus-visible:outline-ring`}
+        />
+      </div>
+      <p aria-live="polite" className="text-sm text-muted-foreground">
+        {corrected ? (
+          <>
+            The system calls “{query.trim()}” <strong className="text-canvas-foreground">{corrected.name}</strong>.
+          </>
+        ) : q ? (
+          `${matches.length} ${matches.length === 1 ? "term" : "terms"}`
+        ) : (
+          `${terms.length} terms`
+        )}
+      </p>
+      <dl data-slot="glossary-list" className="flex flex-col divide-y divide-border border-y border-border">
+        {matches.map((t) => (
+          <div key={`${t.kind}:${t.name}`} className="grid gap-1 py-3 sm:grid-cols-[12rem_1fr]">
+            <dt className="flex items-baseline gap-2">
+              <span className="font-medium">{t.name}</span>
+              <span className="text-xs text-muted-foreground">{t.kind}</span>
+            </dt>
+            <dd className="flex flex-col gap-0.5 text-sm text-muted-foreground">
+              {t.wrong?.length ? <span>Not {t.wrong.map((w) => `“${w}”`).join(", ")}</span> : null}
+              {t.note && <span>{inline(t.note)}</span>}
+              {t.ref && <code className="font-mono text-xs">{t.ref}</code>}
+            </dd>
+          </div>
+        ))}
+      </dl>
+    </div>
+  );
+}

package/registry/imagery.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import { assetUrl } from "./lib/lookup";
+import type { AssetEntry } from "./lib/manifest-types";
+import { inline } from "./lib/text";
+
+/** The approved icons and imagery, each with how to use it. */
+export function Imagery({ assets, kinds = ["icon", "image", "other"] }: { assets: AssetEntry[]; kinds?: AssetEntry["kind"][] }) {
+  const shown = assets.filter((a) => kinds.includes(a.kind));
+  if (shown.length === 0) return <p className="text-sm text-muted-foreground">No icons or imagery in the brand folder yet.</p>;
+  return (
+    <ul data-slot="imagery" className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+      {shown.map((a) => {
+        const src = assetUrl(a);
+        return (
+          <li key={a.file} className="min-w-0">
+            <figure data-slot="asset" className="flex h-full flex-col overflow-hidden rounded-lg border border-border">
+              <div className="flex h-36 items-center justify-center bg-surface p-4 text-surface-foreground">
+                {src ? (
+                  <img src={src} alt={a.alt ?? ""} className={a.kind === "icon" ? "size-12" : "max-h-full max-w-full object-contain"} />
+                ) : (
+                  <span className="font-mono text-xs text-muted-foreground">{a.file}</span>
+                )}
+              </div>
+              <figcaption className="flex flex-col gap-1 border-t border-border px-4 py-3 text-sm">
+                <span className="font-medium">{a.name}</span>
+                {a.usage ? <span className="text-muted-foreground">{inline(a.usage)}</span> : <span className="text-muted-foreground">No usage notes yet.</span>}
+                <span className="font-mono text-xs text-muted-foreground">
+                  {a.kind}
+                  {a.width && a.height ? ` · ${a.width} × ${a.height}` : ""}
+                </span>
+              </figcaption>
+            </figure>
+          </li>
+        );
+      })}
+    </ul>
+  );
+}

package/registry/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/blocks 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/registry/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/registry/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/registry/lib/cx.ts

@@ -0,0 +1,12 @@
+/**
+ * The smallest a pressable thing in the docs may be: 44px by default (WCAG 2.5.5).
+ * 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.
+ */
+export const target = "min-h-[var(--docs-target,2.75rem)] min-w-[var(--docs-target,2.75rem)]";
+
+/** Join class names, skipping the falsy ones. */
+export function cx(...classes: (string | false | null | undefined)[]): string {
+  return classes.filter(Boolean).join(" ");
+}

package/registry/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/registry/lib/lookup.tsx

@@ -0,0 +1,46 @@
+import { createElement, isValidElement, type ComponentType, type ReactNode } from "react";
+import { componentKey } from "./manifest";
+import type { AssetEntry, ComponentEntry, PatternEntry } from "./manifest-types";
+import { assets, components, examples, patterns } from "../registry.generated";
+
+/** The real component a manifest entry describes, from the registry `designtools-blocks map` generates. */
+export function componentFor(entry: ComponentEntry): ComponentType<any> | undefined {
+  return components[componentKey(entry)];
+}
+
+/** The examples module for a component: each named export is an example. */
+export function examplesFor(entry: ComponentEntry): Record<string, unknown> | undefined {
+  return entry.examples ? examples[entry.examples.source] : undefined;
+}
+
+/** The pattern module: each named export is a composition. */
+export function compositionsFor(pattern: PatternEntry): Record<string, unknown> | undefined {
+  return patterns[pattern.source];
+}
+
+/** A brand asset's URL, from its static import in the registry. */
+export function assetUrl(asset: AssetEntry): string | undefined {
+  const imported = 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-blocks 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>;
+}