@designtools/docs 0.0.0-stage → 0.2.0

package/src/lib/pseudo.ts

@@ -0,0 +1,74 @@
+/**
+ * Pinned states. A pointer cannot be faked, so instead every `:hover`, `:focus`
+ * and `:active` rule on the page gets a twin that applies inside an element
+ * carrying `data-pseudo="hover"` (or `focus`, `active`; space-separated for more
+ * than one). The twin sits beside the original, in the same layer and media
+ * query, so it wins and loses exactly where the real state would. This is how
+ * Storybook's pseudo-states addon works, done in the browser with no build step.
+ */
+
+export type Pseudo = "hover" | "focus" | "active";
+
+const PATTERNS: [Pseudo, RegExp][] = [
+  ["hover", /:hover(?![-\w])/g],
+  ["focus", /:focus-visible(?![-\w])/g],
+  ["focus", /:focus(?![-\w])/g],
+  ["active", /:active(?![-\w])/g],
+];
+
+/** A state inside :not(), :has(), :is() or :where() changes what the selector means when removed, so those are left alone. */
+const NESTED = /:(?:not|has|is|where)\([^)]*:(?:hover|focus|active)/;
+
+const done = new WeakSet<CSSStyleSheet>();
+
+/** Adds the twins to every stylesheet not yet seen. Cheap to call again: it runs once per sheet, and again only for sheets added since. */
+export function installPseudoStates(): void {
+  for (const sheet of Array.from(document.styleSheets)) {
+    if (done.has(sheet)) continue;
+    try {
+      walk(sheet);
+      done.add(sheet);
+    } catch {
+      // a stylesheet from another origin cannot be read; its states stay unpinnable
+    }
+  }
+}
+
+type Parent = CSSStyleSheet | CSSGroupingRule | CSSStyleRule;
+
+function walk(parent: Parent): void {
+  const rules = parent.cssRules;
+  // backwards, so a twin inserted after its rule never shifts the rules still to visit
+  for (let i = rules.length - 1; i >= 0; i--) {
+    const rule = rules[i];
+    if (rule instanceof CSSStyleRule) {
+      const twin = twinOf(rule.selectorText);
+      if (twin) {
+        try {
+          parent.insertRule(`${twin} { ${rule.style.cssText} }`, i + 1);
+        } catch {
+          // a selector the browser will not take back (a vendor pseudo-element): skip it
+        }
+      }
+      if (rule.cssRules?.length) walk(rule);
+    } else if ("cssRules" in rule) {
+      walk(rule as CSSGroupingRule);
+    }
+  }
+}
+
+function twinOf(selector: string): string | null {
+  const out: string[] = [];
+  // split on commas that are not inside parentheses
+  for (const part of selector.split(/,(?![^(]*\))/)) {
+    if (NESTED.test(part)) continue;
+    for (const [state, pattern] of PATTERNS) {
+      pattern.lastIndex = 0;
+      if (!pattern.test(part)) continue;
+      const rest = part.replace(pattern, "").trim();
+      out.push(`:where([data-pseudo~="${state}"]) ${rest || "*"}`);
+      break;
+    }
+  }
+  return out.length ? out.join(", ") : null;
+}

package/src/lib/registry.tsx

@@ -0,0 +1,29 @@
+"use client";
+
+import { type ComponentType, createContext, type ReactNode, useContext } from "react";
+
+/**
+ * Everything the docs render that lives in the project: each component, examples
+ * module, pattern module and brand asset, keyed the way the manifest names them.
+ * The project's generated registry (`designtools-docs map`) imports them and
+ * renders a `RegistryProvider` around the docs; a server page cannot hand a
+ * component to a client block, so this is how the blocks reach them.
+ */
+export interface Registry {
+  // biome-ignore lint/suspicious/noExplicitAny: components of every shape
+  components: Record<string, ComponentType<any>>;
+  examples: Record<string, Record<string, unknown>>;
+  patterns: Record<string, Record<string, unknown>>;
+  assets: Record<string, string | { src: string }>;
+}
+
+const EMPTY: Registry = { components: {}, examples: {}, patterns: {}, assets: {} };
+const RegistryContext = createContext<Registry>(EMPTY);
+
+export function RegistryProvider({ value, children }: { value: Registry; children: ReactNode }) {
+  return <RegistryContext.Provider value={value}>{children}</RegistryContext.Provider>;
+}
+
+export function useRegistry(): Registry {
+  return useContext(RegistryContext);
+}

package/src/lib/search.ts

@@ -0,0 +1,99 @@
+/**
+ * The docs search: components, their parts, rules, patterns and pages, matched
+ * fuzzily on their names, with the taxonomy's wrong forms as aliases, so
+ * "dropdown" finds Select and "buton" finds Button. It aids navigation and does
+ * nothing else: no full text, no index to build, because the manifest is small
+ * enough to search in the browser. The same query always gives the same order.
+ */
+
+import fuzzysort from "fuzzysort";
+import { groupFamilies, slugOf } from "./manifest";
+import type { ComponentsManifest, PatternEntry, RuleEntry, TermEntry } from "./manifest-types";
+
+export type SearchKind = "Component" | "Rule" | "Pattern" | "Page";
+
+export interface SearchItem {
+  kind: SearchKind;
+  label: string;
+  href: string;
+  /** The taxonomy's wrong forms for it: typing one finds it, and the result says so. */
+  wrong: string[];
+  /** Anything else it answers to quietly, such as a rule's id. */
+  also?: string[];
+  /** One short line under the label: a category, "part of Card", a rule's kind. */
+  detail?: string;
+}
+
+export interface SearchGroup {
+  kind: SearchKind;
+  /** `matched` is the wrong form a result was found by ("Dropdown" for Select). */
+  items: (SearchItem & { matched?: string })[];
+}
+
+const ORDER: SearchKind[] = ["Component", "Rule", "Pattern", "Page"];
+
+export function searchIndex({
+  manifest,
+  rules = [],
+  patterns = [],
+  terms = [],
+  pages = [],
+  basePath = "/design/system",
+}: {
+  manifest: ComponentsManifest;
+  rules?: RuleEntry[];
+  patterns?: PatternEntry[];
+  terms?: TermEntry[];
+  pages?: { label: string; href: string }[];
+  basePath?: string;
+}): SearchItem[] {
+  const wrong = new Map<string, string[]>();
+  for (const t of terms) if (t.wrong?.length) wrong.set(t.name.toLowerCase(), t.wrong);
+  const wrongOf = (name: string) => wrong.get(name.toLowerCase()) ?? [];
+
+  const items: SearchItem[] = [];
+  for (const { category, families } of groupFamilies(manifest)) {
+    for (const { head, parts } of families) {
+      items.push({ kind: "Component", label: head.name, href: `${basePath}/components/${slugOf(head)}`, wrong: wrongOf(head.name), detail: category });
+      for (const p of parts) {
+        items.push({ kind: "Component", label: p.name, href: `${basePath}/components/${slugOf(p)}`, wrong: wrongOf(p.name), detail: `part of ${head.name}` });
+      }
+    }
+  }
+  for (const r of rules) {
+    items.push({ kind: "Rule", label: r.title, href: `${basePath}/rules#${r.id}`, wrong: wrongOf(r.title), also: [r.id.replace(/-/g, " ")], detail: r.kind === "brand" ? "Brand rule" : "Interface rule" });
+  }
+  for (const p of patterns) items.push({ kind: "Pattern", label: p.name, href: `${basePath}/patterns/${p.id}`, wrong: wrongOf(p.name) });
+  for (const p of pages) items.push({ kind: "Page", label: p.label, href: p.href, wrong: [] });
+  return items;
+}
+
+/**
+ * The matches for a query, grouped by kind (components, rules, patterns, pages),
+ * best first within each, at most `perGroup` of each. A match found only through
+ * an alias says which: `matched` is the wrong form typed ("Dropdown").
+ */
+export function search(items: SearchItem[], query: string, perGroup = 6): SearchGroup[] {
+  const q = query.trim();
+  if (!q) return [];
+  const results = fuzzysort.go(q, items, { keys: ["label", (item: SearchItem) => item.wrong.join(" / "), (item: SearchItem) => (item.also ?? []).join(" / ")], limit: 0, threshold: 0.3 });
+  const ranked = [...results].sort(
+    (a, b) => b.score - a.score || ORDER.indexOf(a.obj.kind) - ORDER.indexOf(b.obj.kind) || (a.obj.label < b.obj.label ? -1 : a.obj.label > b.obj.label ? 1 : 0),
+  );
+  return ORDER.map((kind) => ({
+    kind,
+    items: ranked
+      .filter((r) => r.obj.kind === kind)
+      .slice(0, perGroup)
+      .map((r) => {
+        const viaWrong = (r[1]?.score ?? 0) > Math.max(r[0]?.score ?? 0, r[2]?.score ?? 0);
+        // the wrong form that matched best, to say why a result is here ("Dropdown" for Select)
+        const alias = viaWrong
+          ? r.obj.wrong
+              .map((a) => ({ a, score: fuzzysort.single(q, a)?.score ?? 0 }))
+              .sort((x, y) => y.score - x.score)[0]?.a
+          : undefined;
+        return alias ? { ...r.obj, matched: alias } : r.obj;
+      }),
+  })).filter((g) => g.items.length > 0);
+}

package/src/lib/standards.ts

@@ -0,0 +1,82 @@
+/**
+ * The baselines a project records (`.mxa/stack.json` `baselines`), as a person
+ * reads them: titled sections, labelled rows, notes as sentences, and nothing
+ * shown for a value nobody has set. One shape, so the page and its markdown agree.
+ */
+
+export interface StandardsSection {
+  key: string;
+  title: string;
+  rows: { label: string; value: string }[];
+  notes: string[];
+}
+
+const TITLES: Record<string, string> = {
+  a11y: "Accessibility",
+  performance: "Performance budgets",
+  support: "Support",
+  seo: "Search and discovery",
+  licences: "Licences allowed",
+  textSize: "Text size",
+  touchTargets: "Touch targets",
+};
+
+const LABELS: Record<string, string> = {
+  browsers: "Browsers",
+  devices: "Devices",
+  viewports: "Viewports",
+  LCP: "Largest contentful paint",
+  CLS: "Cumulative layout shift",
+  TBT: "Total blocking time",
+  INP: "Interaction to next paint",
+  lighthouse: "Lighthouse score",
+  aiCrawlable: "Readable by AI crawlers",
+};
+
+const UNITS: Record<string, string> = { viewports: "px" };
+
+/** `textSize` to "Text size", `aiCrawlable` to "Ai crawlable": a fallback, never as good as a title. */
+export function humanise(key: string): string {
+  const words = key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[-_]+/g, " ").toLowerCase();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+function shown(key: string, value: unknown): string | undefined {
+  if (value === null || value === undefined || value === "") return undefined;
+  if (typeof value === "boolean") return value ? "yes" : "no";
+  if (Array.isArray(value)) return value.length ? value.join(", ") + (UNITS[key] ? ` ${UNITS[key]}` : "") : "not agreed yet";
+  if (typeof value === "object") return undefined;
+  return String(value);
+}
+
+export function standardsSections(baselines: Record<string, unknown>): StandardsSection[] {
+  const keys = Object.keys(baselines).filter((k) => !k.startsWith("$"));
+  // `a11yNotes` is the note on `a11y`, not a section of its own
+  const noteOf = (k: string) => (/Notes?$/.test(k) && keys.includes(k.replace(/Notes?$/, "")) ? k.replace(/Notes?$/, "") : undefined);
+  const out: StandardsSection[] = [];
+  for (const key of keys) {
+    if (noteOf(key)) continue;
+    const value = baselines[key];
+    const section: StandardsSection = { key, title: TITLES[key] ?? humanise(key), rows: [], notes: [] };
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+        if (k.startsWith("$")) continue;
+        if (/^notes?$/i.test(k)) {
+          if (typeof v === "string" && v) section.notes.push(v);
+          continue;
+        }
+        const text = shown(k, v);
+        if (text !== undefined) section.rows.push({ label: LABELS[k] ?? humanise(k), value: text });
+      }
+    } else {
+      const text = shown(key, value);
+      if (text !== undefined) section.rows.push({ label: "", value: text });
+    }
+    for (const k of keys) {
+      const v = baselines[k];
+      if (noteOf(k) === key && typeof v === "string" && v) section.notes.push(v);
+    }
+    if (section.rows.length || section.notes.length) out.push(section);
+  }
+  return out;
+}

package/src/lib/status.tsx

@@ -0,0 +1,32 @@
+import { cx } from "./cx";
+
+export type Status = "stable" | "emerging" | "deprecated" | "confirmed" | "assumption" | "measured" | "draft" | "published";
+
+const LOOK: Record<Status, string> = {
+  stable: "bg-success-subdued text-success-subdued-foreground",
+  confirmed: "bg-success-subdued text-success-subdued-foreground",
+  published: "bg-success-subdued text-success-subdued-foreground",
+  emerging: "bg-warning-subdued text-warning-subdued-foreground",
+  assumption: "bg-warning-subdued text-warning-subdued-foreground",
+  // generated from the tokens: a fact, not a decision, so neither settled nor pending
+  measured: "bg-muted text-muted-foreground",
+  draft: "bg-warning-subdued text-warning-subdued-foreground",
+  deprecated: "bg-destructive-subdued text-destructive-subdued-foreground",
+};
+
+/** A status, everywhere one is shown: components, patterns, rules and editorial pages. Unset says so. */
+export function StatusBadge({ status, className }: { status?: Status; className?: string }) {
+  return (
+    <span
+      data-slot="status-badge"
+      data-status={status ?? "unset"}
+      className={cx(
+        "inline-flex h-6 items-center rounded-full px-2.5 text-xs font-medium",
+        status ? LOOK[status] : "border border-dashed border-border text-muted-foreground",
+        className,
+      )}
+    >
+      {status ?? "status not set"}
+    </span>
+  );
+}

package/src/lib/terms.tsx

@@ -0,0 +1,53 @@
+import { X } from "lucide-react";
+import type { TermEntry } from "./manifest-types";
+import { inline } from "./text";
+
+/** The wrong forms of a term: quiet chips, each with a cross, so "not this" reads without shouting. */
+export function WrongForms({ wrong }: { wrong?: string[] }) {
+  if (!wrong?.length) return <span className="text-sm text-muted-foreground">None</span>;
+  return (
+    <span className="flex flex-wrap gap-1.5">
+      <span className="sr-only">Not </span>
+      {wrong.map((w) => (
+        <span key={w} data-slot="term-wrong" className="inline-flex min-h-7 items-center gap-1 rounded-md bg-muted px-2 text-sm text-muted-foreground">
+          <X aria-hidden className="size-3 shrink-0" />
+          <span className="line-through decoration-current/40">{w}</span>
+        </span>
+      ))}
+    </span>
+  );
+}
+
+/**
+ * One term on one row: the word to use, the words not to, and why. Three columns on a wide screen, under
+ * the labels `TermHead` draws; stacked on a phone.
+ */
+export function TermRow({ term, kind }: { term: TermEntry; kind?: boolean }) {
+  return (
+    <div data-slot="term" className="grid gap-x-8 gap-y-2 border-t border-border py-5 md:grid-cols-[minmax(10rem,14rem)_minmax(0,1fr)_minmax(0,1.3fr)] md:items-baseline">
+      <dt className="flex items-baseline gap-2">
+        <span className="text-xl leading-snug tracking-tight">{term.name}</span>
+        {kind && <span className="font-mono text-xs text-muted-foreground">{term.kind}</span>}
+        <span className="sr-only">, say this</span>
+      </dt>
+      <dd>
+        <WrongForms wrong={term.wrong} />
+      </dd>
+      <dd className="text-sm leading-relaxed text-muted-foreground">
+        {term.note ? inline(term.note) : term.kind !== "product" ? `The ${term.kind}'s name in the code.` : null}
+        {term.ref && <code className="ml-1 font-mono text-xs">{term.ref}</code>}
+      </dd>
+    </div>
+  );
+}
+
+/** The column labels over a list of `TermRow`s, on a wide screen. */
+export function TermHead() {
+  return (
+    <div aria-hidden className="hidden gap-x-8 pb-3 text-xs font-medium text-muted-foreground md:grid md:grid-cols-[minmax(10rem,14rem)_minmax(0,1fr)_minmax(0,1.3fr)]">
+      <span>Say</span>
+      <span>Not</span>
+      <span>Why</span>
+    </div>
+  );
+}

package/src/lib/text.tsx

@@ -0,0 +1,27 @@
+import type { ReactNode } from "react";
+
+/** JSDoc prose: paragraphs split on blank lines, `code` spans set as code. Nothing else is interpreted. */
+export function Prose({ text, className }: { text: string; className?: string }) {
+  return (
+    <>
+      {text.split(/\n{2,}/).map((p, i) => (
+        <p key={i} className={className}>
+          {inline(p)}
+        </p>
+      ))}
+    </>
+  );
+}
+
+/** One line of prose with its `code` spans. */
+export function inline(text: string): ReactNode[] {
+  return text.split(/(`[^`]+`)/).map((part, i) =>
+    /^`[^`]+`$/.test(part) ? (
+      <code key={i} className="rounded-sm bg-muted px-1 font-mono text-[0.9em]">
+        {part.slice(1, -1)}
+      </code>
+    ) : (
+      part
+    ),
+  );
+}