@weatherboard/gyde-design 0.3.0

package/catalogue.mjs

@@ -0,0 +1,506 @@
+/**
+ * G-50 — the catalogue, generated rather than authored.
+ *
+ * @gyde-emits-source-for-another-repo
+ *
+ * WHY GENERATED.
+ *
+ * Both source repositories hand-authored one, and the larger of the two shows
+ * what that costs at scale: a 433-line registry whose `sourcePath` entries point
+ * at a superseded generation of its own components, whose Button lists four
+ * variants where the real one has nine, and which has **no coverage test**. It
+ * documents a system that no longer exists, confidently.
+ *
+ * Generating it makes "every component is catalogued" true by construction
+ * instead of true by a test somebody has to keep passing. The prior-art survey
+ * found Storybook does not enforce catalogue coverage either, so this is a real
+ * gap rather than a preference.
+ *
+ * WHAT IT MUST RENDER, AND WHY EACH ONE IS ON THE LIST.
+ *
+ * Every item here is a defect class a deployed catalogue has already caught once:
+ *
+ *   every variant          a Button that rendered nothing at all
+ *   both themes            three muted notes running together into one word
+ *   a portalled surface    a Select popup opening light against a dark panel
+ *   a runtime-themed one   the capability whose absence cost two apps 0% adoption
+ *   the usage index        a component reporting itself unused while demonstrating itself
+ *
+ * A catalogue that renders only first paint, in one theme, is a screenshot.
+ *
+ * THE HONESTY TEST, which is a gate rather than a convention:
+ *
+ *   "It boots with nothing else running — no manager, no database, no network.
+ *    That is not a convenience, it is the test of whether the catalogue is still
+ *    honest… If this command ever grows a prerequisite, read the vite config
+ *    before fixing it, because the prerequisite is the bug."
+ */
+
+/**
+ * What each seed component can be shown as.
+ *
+ * Data, not JSX, so the coverage test can read it as text — the same reason
+ * System A keeps its entries in a declarative array. A test that
+ * imports the catalogue would resolve a typo'd component name to `undefined`
+ * and pass while covering nothing.
+ *
+ * `states` is deliberately plural everywhere. The defects worth catching are
+ * states, and none of them exists on load.
+ */
+export const CATALOGUE_ENTRIES = {
+  Button: {
+    purpose: "The one action a view wants, and every lesser action beside it.",
+    replaces: ["a styled <button>", "an <a> that looks like a button"],
+    states: [
+      { label: "accent / filled", props: { tone: "accent", emphasis: "filled", size: "md" }, children: "Save changes" },
+      { label: "neutral / outline", props: { tone: "neutral", emphasis: "outline", size: "md" }, children: "Cancel" },
+      { label: "danger / filled", props: { tone: "danger", emphasis: "filled", size: "md" }, children: "Delete" },
+      { label: "ghost, small", props: { tone: "neutral", emphasis: "ghost", size: "sm" }, children: "Dismiss" },
+      { label: "disabled", props: { tone: "accent", emphasis: "filled", size: "md", disabled: true }, children: "Saving…" },
+    ],
+  },
+  Text: {
+    purpose: "Every piece of prose, at the role it plays rather than the size it is.",
+    replaces: ["a <p> with a font-size", "a <span> with a colour"],
+    states: [
+      { label: "display", props: { role: "display" }, children: "A page title" },
+      { label: "title", props: { role: "title" }, children: "A panel title" },
+      { label: "body", props: { role: "body" }, children: "Body copy, which is what most text is." },
+      { label: "muted", props: { role: "muted", as: "p" }, children: "Supporting text that is still information." },
+      { label: "faint", props: { role: "faint", as: "p" }, children: "Present, but not information." },
+    ],
+  },
+  Card: {
+    purpose: "A bordered surface. The only one, which is the point.",
+    replaces: ["a div with a border and a radius", "a panel", "a well"],
+    states: [
+      { label: "default", props: { tone: "default", inset: "md" }, children: "A surface." },
+      { label: "muted", props: { tone: "muted", inset: "md" }, children: "A surface sunk into another." },
+      { label: "danger", props: { tone: "danger", inset: "md" }, children: "Something failed here." },
+      { label: "no inset", props: { tone: "default", inset: "none" }, children: "Edge to edge." },
+    ],
+  },
+  Checkbox: {
+    purpose: "A binary choice that is part of a form.",
+    replaces: ["an <input type=checkbox> with a label beside it"],
+    controlled: { checked: false },
+    states: [
+      { label: "unchecked", props: { checked: false, label: "Include drafts", id: "cb-1" } },
+      { label: "checked", props: { checked: true, label: "Include drafts", id: "cb-2" } },
+      { label: "indeterminate", props: { checked: false, indeterminate: true, label: "Some selected", id: "cb-3" } },
+      { label: "disabled", props: { checked: true, disabled: true, label: "Locked", id: "cb-4" } },
+    ],
+  },
+  Select: {
+    purpose: "One of a known set of options.",
+    replaces: ["a <select>", "a dropdown built from a button and a list"],
+    controlled: { value: "b" },
+    /**
+     * The open state is the reason this component is in the seed set — the popup
+     * is portalled, and a portal is where inheritance-based theming stops
+     * reaching. It is also the state this catalogue CANNOT render: forcing it
+     * would need `defaultOpen`, which the wrapper deliberately does not expose.
+     *
+     * An earlier version listed an "open" example that rendered exactly the
+     * closed one. A label that lies is worse than a gap, so the states below are
+     * the ones the closed API can actually produce, and the gap is recorded in
+     * `notes` where a reader of the catalogue will see it.
+     */
+    notes: [
+      "Its open state is portalled and cannot be forced through the closed API. " +
+      "That is where theming across a portal boundary is proved, so it needs a " +
+      "rendered-artifact review rather than a static example (G-11).",
+    ],
+    states: [
+      { label: "a value selected", props: { label: "Sort by", options: [{ value: "a", label: "Newest" }, { value: "b", label: "Oldest" }] } },
+      { label: "a different value selected", props: { value: "a", label: "Sort by", options: [{ value: "a", label: "Newest" }, { value: "b", label: "Oldest" }] } },
+      { label: "disabled", props: { disabled: true, label: "Sort by", options: [{ value: "a", label: "Newest" }, { value: "b", label: "Oldest" }] } },
+    ],
+  },
+};
+
+const lit = (v) =>
+  typeof v === "string" ? JSON.stringify(v)
+  : typeof v === "boolean" || typeof v === "number" ? `{${v}}`
+  : `{${JSON.stringify(v)}}`;
+
+/**
+ * Render one example as JSX.
+ *
+ * An explicit builder, not a chain of `.replace()` calls on a formatted string.
+ * The first version was the latter and shipped two bugs into a scaffolded
+ * repository: `Select` emitted without its required `value` prop, and every
+ * state of a controlled component rendered identically because the
+ * substitutions silently did not match.
+ *
+ * A generator whose output is assembled by patching text produces output nobody
+ * predicted, and the failure is invisible until somebody reads the emitted file.
+ */
+function exampleJsx(name, state, entry) {
+  const props = { ...(entry.controlled ?? {}), ...state.props };
+  const attrs = Object.entries(props).map(([k, v]) => `${k}=${lit(v)}`);
+
+  // A controlled component needs a handler. The catalogue holds no state on
+  // purpose — what is being reviewed is the rendering, not the interaction.
+  if (entry.controlled) attrs.push("onChange={() => {}}");
+
+  const open = `<${name} ${attrs.join(" ")}`;
+  return state.children ? `${open}>${state.children}</${name}>` : `${open} />`;
+}
+
+/**
+ * A KNOWN GAP, stated rather than worked around.
+ *
+ * `Select`'s open state is the reason it is in the seed set: the popup is
+ * portalled, and a portal is where inheritance-based theming stops reaching.
+ * But the wrapper deliberately does not expose `defaultOpen` — the primitive
+ * has it, and forwarding it would be an escape hatch opened for the
+ * catalogue's convenience, which is exactly how closure erodes.
+ *
+ * So **a closed component set cannot demonstrate its own interactive states.**
+ * That is a real tension, not an oversight, and the catalogue says so at the
+ * call site rather than printing "open" beside a control that is closed. A
+ * label that lies is worse than an admission.
+ *
+ * The fix is a decision rather than a patch: either the set gains a reviewed
+ * way to force a state, or interactive states are explicitly out of the
+ * catalogue's scope and a rendered-artifact review (G-11) covers them instead.
+ */
+export const INTERACTIVE_GAP = "a closed component set cannot force its own interactive states";
+
+/**
+ * The entries module.
+ *
+ * Generated from the same list the barrel is generated from, which is what
+ * makes coverage structural: a component cannot be added to the set without
+ * appearing here, because both come from one array.
+ */
+function entriesSource(components, systemPackage) {
+  const missing = components.filter((c) => !CATALOGUE_ENTRIES[c]);
+  if (missing.length) {
+    throw new Error(
+      `No catalogue entry for ${missing.join(", ")}. A component that cannot be ` +
+      "demonstrated cannot be reviewed — add states before emitting it, or the " +
+      "catalogue documents a set it does not cover.",
+    );
+  }
+
+  const blocks = components.map((name) => {
+    const e = CATALOGUE_ENTRIES[name];
+    const states = e.states.map((s) =>
+      `    { label: ${JSON.stringify(s.label)}, node: ${exampleJsx(name, s, e)} },`).join("\n");
+
+    return `  {
+    name: ${JSON.stringify(name)},
+    purpose: ${JSON.stringify(e.purpose)},
+    replaces: ${JSON.stringify(e.replaces)},
+    notes: ${JSON.stringify(e.notes ?? [])},
+    examples: [
+${states}
+    ],
+  },`;
+  }).join("\n");
+
+  return `/* GENERATED BY GYDE — regenerate rather than edit.
+ *
+ * Entries are DATA, not JSX scattered through a page, so the coverage test can
+ * read this file as text. A test that imported it would resolve a typo'd
+ * component name to \`undefined\` and pass while covering nothing.
+ */
+import type { ReactNode } from "react";
+import { ${components.join(", ")} } from "${systemPackage}";
+
+export type Example = { label: string; node: ReactNode };
+export type Entry = { name: string; purpose: string; replaces: readonly string[]; notes: readonly string[]; examples: readonly Example[] };
+
+export const ENTRIES: readonly Entry[] = [
+${blocks}
+];
+`;
+}
+
+const app = (systemPackage, tokensPackage) => `/* GENERATED BY GYDE — then yours.
+ *
+ * The shell. It renders every entry, in BOTH THEMES side by side, because
+ * \`[data-theme]\` is emitted as an unqualified selector and therefore works on a
+ * container. A catalogue that can only show one theme at a time is a catalogue
+ * where a theme regression is found by a person switching back and forth.
+ */
+import { ENTRIES } from "./entries";
+import { Tokens } from "./Tokens";
+import { Usage } from "./Usage";
+
+export function App() {
+  return (
+    <main className="dx-page">
+      <h1 className="dx-title">The component set</h1>
+      <p className="dx-note">
+        Every component, every state, both themes. Nothing else is running —
+        no database, no network. If this page ever needs something else to
+        boot, that prerequisite is the bug.
+      </p>
+
+      <Tokens />
+
+      {ENTRIES.map((entry) => (
+        <section key={entry.name} className="dx-entry">
+          <h2 className="dx-entry__name">{entry.name}</h2>
+          <p className="dx-note">{entry.purpose}</p>
+          <p className="dx-note">Replaces: {entry.replaces.join(", ")}</p>
+          {entry.notes.map((n) => (
+            <p key={n} className="dx-note dx-note--gap">Not shown here: {n}</p>
+          ))}
+          <Usage name={entry.name} />
+
+          {entry.examples.map((ex) => (
+            <div key={ex.label} className="dx-example">
+              <div className="dx-example__label">{ex.label}</div>
+              {/* Both themes, side by side, from one render. */}
+              <div className="dx-themes">
+                <div data-theme="light" className="dx-theme">{ex.node}</div>
+                <div data-theme="dark" className="dx-theme">{ex.node}</div>
+              </div>
+            </div>
+          ))}
+
+          {/* The runtime-theming path, which no static example exercises.
+              Its absence is what cost a real product two apps' adoption. */}
+          {entry.name === "Card" ? <ThemedExample /> : null}
+        </section>
+      ))}
+    </main>
+  );
+}
+
+import { Card, themeVars } from "${systemPackage}";
+
+function ThemedExample() {
+  return (
+    <div className="dx-example">
+      <div className="dx-example__label">runtime theme — a per-tenant brand</div>
+      <div style={themeVars({ surface: "#1d2b53", text: "#f2f0e6", border: "#3b4d7a" })}>
+        <Card tone="themed" inset="md">
+          A surface taking colours resolved at request time, with the dictionary
+          as its fallback.
+        </Card>
+      </div>
+    </div>
+  );
+}
+`;
+
+const tokensPage = (tokensPackage) => `/* GENERATED BY GYDE — then yours. */
+import { tokens } from "${tokensPackage}/dictionary.mjs";
+
+/**
+ * The dictionary, rendered.
+ *
+ * Every token with its ROLE beside it, because a swatch without a purpose is
+ * how a token gets used for the wrong thing. Both themes, for the same reason
+ * the components show both.
+ */
+export function Tokens() {
+  return (
+    <section className="dx-entry">
+      <h2 className="dx-entry__name">Tokens</h2>
+      {Object.entries(tokens).map(([group, entries]) => (
+        <div key={group} className="dx-tokens">
+          <h3 className="dx-tokens__group">{group}</h3>
+          {Object.entries(entries as Record<string, { value: unknown; role: string }>).map(([name, token]) => (
+            <div key={name} className="dx-token">
+              <code className="dx-token__name">--{group}-{name}</code>
+              <span className="dx-token__role">{token.role}</span>
+            </div>
+          ))}
+        </div>
+      ))}
+    </section>
+  );
+}
+`;
+
+const USAGE_PAGE = `/* GENERATED BY GYDE — regenerate rather than edit. */
+import usage from "./usage.json";
+
+/**
+ * Where each component is actually rendered.
+ *
+ * Read from a committed file because this is a browser app with no filesystem.
+ * The index that produced it excludes THIS catalogue's entries — a component
+ * demonstrating itself is not a use — but not the catalogue's own chrome, which
+ * is. A real index once reported a component unused while it sat at the top of
+ * a page demonstrating itself.
+ */
+export function Usage({ name }: { name: string }) {
+  const sites: string[] = (usage.used as Record<string, string[]>)[name] ?? [];
+  if (sites.length === 0) {
+    return <p className="dx-note">Not rendered anywhere yet — either use it, or delete it.</p>;
+  }
+  return <p className="dx-note">Used in {sites.length} place{sites.length === 1 ? "" : "s"}.</p>;
+}
+`;
+
+const CHROME_CSS = `/* GENERATED BY GYDE — then yours.
+ *
+ * The catalogue's own chrome, prefixed \`dx-\` so it is a DECLARED vocabulary
+ * rather than bespoke styling the audit has to guess about. A surface that is
+ * legitimately outside the component set says so at every call site, instead of
+ * being excluded by path in a config nobody reads.
+ */
+.dx-page { padding: var(--space-6); font-family: var(--font-sans); background: var(--color-surface); color: var(--color-text); }
+.dx-title { font-size: var(--text-display); line-height: var(--line-height-flush); }
+.dx-note { color: var(--color-muted); font-size: var(--text-small); }
+.dx-entry { margin-top: var(--space-7); border-top: var(--border-hair) solid var(--color-border); padding-top: var(--space-5); }
+.dx-entry__name { font-size: var(--text-title); }
+.dx-example { margin-top: var(--space-5); }
+.dx-example__label { font-size: var(--text-micro); color: var(--color-faint); margin-bottom: var(--space-2); }
+.dx-themes { display: flex; gap: var(--space-4); }
+.dx-theme { flex: 1; padding: var(--space-4); background: var(--color-surface); border-radius: var(--radius-card); }
+.dx-tokens { margin-top: var(--space-4); }
+.dx-token { display: flex; gap: var(--space-4); font-size: var(--text-small); }
+.dx-token__name { font-family: var(--font-mono); color: var(--color-muted); min-width: 16rem; }
+.dx-token__role { color: var(--color-text); }
+`;
+
+const VITE_CONFIG = `/* GENERATED BY GYDE — then yours.
+ *
+ * DO NOT ADD A PREREQUISITE TO THIS FILE.
+ *
+ * The catalogue boots with nothing else running — no database, no network, no
+ * other app. That is not a convenience, it is the test of whether it is still
+ * honest: a catalogue that needs the product running can only show what the
+ * product's state allows, which is a screenshot with extra steps.
+ *
+ * If this config ever grows a proxy, an env requirement or a fixture server,
+ * the prerequisite is the bug. Gyde's gate fails on it.
+ */
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  server: { port: 3300 },
+  build: { outDir: "dist" },
+});
+`;
+
+const COVERAGE_TEST = `/* GENERATED BY GYDE — then yours. */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Coverage, read as TEXT rather than imported.
+ *
+ * An import resolves a typo'd name to \`undefined\`, so an import-based check
+ * passes while covering nothing. Both files are read as source for that reason.
+ *
+ * This test is a backstop, not the mechanism. Coverage is true by construction
+ * because the barrel and the entries are generated from one list — if this ever
+ * fails, something has been hand-edited, and that is worth knowing.
+ */
+test("every exported component appears in the catalogue", () => {
+  const barrel = readFileSync(join(HERE, "../../../packages/design-system/src/index.ts"), "utf8");
+  const entries = readFileSync(join(HERE, "entries.tsx"), "utf8");
+
+  const exported = [...barrel.matchAll(/export \\{ (\\w+) \\}/g)].map((m) => m[1]);
+  assert.ok(exported.length > 0, "read no components out of the barrel");
+
+  for (const name of exported) {
+    assert.match(entries, new RegExp(\`name: "\${name}"\`), \`\${name} is exported and not catalogued\`);
+  }
+});
+
+test("the catalogue lists nothing that is not exported", () => {
+  const barrel = readFileSync(join(HERE, "../../../packages/design-system/src/index.ts"), "utf8");
+  const entries = readFileSync(join(HERE, "entries.tsx"), "utf8");
+  const exported = new Set([...barrel.matchAll(/export \\{ (\\w+) \\}/g)].map((m) => m[1]));
+
+  for (const m of entries.matchAll(/name: "(\\w+)"/g)) {
+    assert.ok(exported.has(m[1]), \`\${m[1]} is catalogued and not exported\`);
+  }
+});
+
+test("every entry shows more than one state", () => {
+  // A single example is a screenshot. The defects worth catching are states.
+  const entries = readFileSync(join(HERE, "entries.tsx"), "utf8");
+  for (const block of entries.split(/\\n  \\{\\n/).slice(1)) {
+    const name = block.match(/name: "(\\w+)"/)?.[1];
+    if (!name) continue;
+    const labels = [...block.matchAll(/label: "/g)].length;
+    assert.ok(labels >= 2, \`\${name} shows \${labels} state(s); a single example proves nothing\`);
+  }
+});
+`;
+
+/**
+ * Emit the catalogue.
+ *
+ * Throws when a component has no entry, rather than emitting a catalogue that
+ * silently covers less than the set. That is the whole guarantee: a component
+ * you cannot demonstrate is one nobody can review.
+ */
+export function emitCatalogue({
+  components,
+  path = "apps/design",
+  /**
+   * The names the SCAFFOLDED workspace uses, not names Gyde invented.
+   *
+   * The first version hardcoded `@gyde-scaffold/*`, so every emitted import
+   * resolved to nothing and a scaffolded repository would not build. Every test
+   * passed, because each compared the emitted text against itself. The CLI now
+   * derives these from the workspace's own scope.
+   */
+  systemPackage = "@scaffold/design-system",
+  tokensPackage = "@scaffold/design-tokens",
+  cataloguePackage = "@scaffold/design-catalogue",
+} = {}) {
+  return {
+    /**
+     * The catalogue is an app, so it needs a manifest.
+     *
+     * Found by Gyde's own scan reporting `apps/design — no package.json`:
+     * without one it cannot be started, cannot be filtered to by the package
+     * manager, and is invisible to workspace discovery — a catalogue nobody can
+     * run is a catalogue nobody looks at, which is the whole value gone.
+     *
+     * `dev` and `build` and nothing else. The moment this grows a script that
+     * needs another process, the honesty test in vite.config.ts is broken.
+     */
+    [`${path}/package.json`]: JSON.stringify({
+      name: `${cataloguePackage}`,
+      version: "0.0.0",
+      private: true,
+      type: "module",
+      scripts: { dev: "vite", build: "vite build", test: "node --test src/*.test.mjs" },
+      dependencies: { [systemPackage]: "workspace:*", [tokensPackage]: "workspace:*", react: "^19.0.0", "react-dom": "^19.0.0" },
+      devDependencies: { vite: "^6.0.0", "@vitejs/plugin-react": "^4.3.0" },
+    }, null, 2) + "\n",
+    [`${path}/src/entries.tsx`]: entriesSource(components, systemPackage),
+    [`${path}/src/App.tsx`]: app(systemPackage, tokensPackage),
+    [`${path}/src/Tokens.tsx`]: tokensPage(tokensPackage),
+    [`${path}/src/Usage.tsx`]: USAGE_PAGE,
+    [`${path}/src/chrome.css`]: CHROME_CSS,
+    [`${path}/src/usage.json`]: JSON.stringify({ used: {}, unused: components, leftovers: {} }, null, 2) + "\n",
+    [`${path}/src/coverage.test.mjs`]: COVERAGE_TEST,
+    [`${path}/vite.config.ts`]: VITE_CONFIG,
+    [`${path}/src/main.tsx`]: `/* GENERATED BY GYDE — then yours. */
+import { createRoot } from "react-dom/client";
+import "${systemPackage}/styles.css";
+import "./chrome.css";
+import { App } from "./App";
+
+createRoot(document.getElementById("root")!).render(<App />);
+`,
+    [`${path}/index.html`]: `<!doctype html>
+<html lang="en">
+  <head><meta charset="utf-8" /><meta name="viewport" content="width=device-width,initial-scale=1" /><title>Design system</title></head>
+  <body><div id="root"></div><script type="module" src="/src/main.tsx"></script></body>
+</html>
+`,
+  };
+}