@weatherboard/gyde-design 0.4.0 → 0.4.2

package/emit.mjs

@@ -36,6 +36,7 @@
  */
 
 import { generateCss, SEED, varName, CSS_HEADER } from "./tokens.mjs";
+import { emitThemeChoice } from "./theme-choice.mjs";
 
 /**
  * The version of what this emits.
@@ -60,7 +61,7 @@ import { generateCss, SEED, varName, CSS_HEADER } from "./tokens.mjs";
  * `emit.test.mjs` enforces it: a fresh scaffold must pass the gate Gyde would
  * run against it.
  */
-export const SCAFFOLD_VERSION = "0.3.0";
+export const SCAFFOLD_VERSION = "0.3.2";
 
 const GENERATED = (what) => `/* GENERATED BY GYDE — then yours.
  *
@@ -199,8 +200,8 @@ export function generateCss(dict) {
     "  }", "}", "",
     "/* An explicit choice, on any element — which is what makes both themes",
     "   renderable on one page, and what a portalled popup looks up. */",
-    '[data-theme="dark"] {', decls("dark"), "}", "",
-    '[data-theme="light"] {', decls("light"), "}", "",
+    '[data-theme="dark"] {', '  color-scheme: dark;', decls("dark"), "}", "",
+    '[data-theme="light"] {', '  color-scheme: light;', decls("light"), "}", "",
   ].join("\\n");
 }
 `;
@@ -385,11 +386,25 @@ const defaultsModule = `${GENERATED("absence of a \"use client\" directive in th
  * both graphs and its values survive on the server.
  */
 
-export const BUTTON_DEFAULTS = { tone: "neutral", emphasis: "filled", size: "md" } as const;
-export const TEXT_DEFAULTS = { role: "body" } as const;
-export const CARD_DEFAULTS = { tone: "default", inset: "md" } as const;
-export const CHECKBOX_DEFAULTS = { disabled: false, indeterminate: false } as const;
-export const SELECT_DEFAULTS = { disabled: false } as const;
+/**
+ * G-127. EVERY prop a component declares appears here, except its children.
+ *
+ * The optional-props ban (G-68) removed the other way of saying "this one has
+ * an obvious answer". A destructure default — \`type = "button"\` — cannot say it
+ * any more, because the declaration it excused is gone. So the obvious answer
+ * moves here, where a caller opts into it explicitly by spreading, and the
+ * component itself makes no decision on anybody's behalf.
+ *
+ * The consequence to keep true: \`<Button {...BUTTON_DEFAULTS} onClick={...}>text</Button>\`
+ * must type-check. If a prop is added to a component and not added here, that
+ * sentence stops being true, and the only thing that will tell you is the
+ * scaffold's own gate.
+ */
+export const BUTTON_DEFAULTS = { tone: "neutral", emphasis: "filled", size: "md", type: "button", disabled: false, describedBy: null } as const;
+export const TEXT_DEFAULTS = { role: "body", as: null } as const;
+export const CARD_DEFAULTS = { tone: "default", inset: "md", as: "div" } as const;
+export const CHECKBOX_DEFAULTS = { disabled: false, indeterminate: false, name: null } as const;
+export const SELECT_DEFAULTS = { disabled: false, name: null } as const;
 `;
 
 /* -------------------------------------------------------------- components */
@@ -403,6 +418,22 @@ export const SELECT_DEFAULTS = { disabled: false } as const;
  */
 export const SEED_COMPONENTS = ["Button", "Text", "Card", "Checkbox", "Select"];
 
+/**
+ * G-127. Which defaults constant belongs to which component.
+ *
+ * Derived rather than hard-coded looks tidier — `Button` -> `BUTTON_DEFAULTS`
+ * is a `toUpperCase()` away — and it would emit a barrel export for a constant
+ * `defaults.ts` does not declare the moment somebody emits a set that is not
+ * the seed five. A map is the thing that can be wrong out loud.
+ */
+export const DEFAULTS_EXPORTS = {
+  Button: "BUTTON_DEFAULTS",
+  Text: "TEXT_DEFAULTS",
+  Card: "CARD_DEFAULTS",
+  Checkbox: "CHECKBOX_DEFAULTS",
+  Select: "SELECT_DEFAULTS",
+};
+
 function componentSources(primitive) {
   return {
     "Button.tsx": `"use client";
@@ -434,13 +465,22 @@ export type ButtonProps = {
    * deliberate.
    */
   onClick: (() => void) | null;
-  type?: "button" | "submit";
-  disabled?: boolean;
-  /** A disabled control with no explanation is the most common accessibility defect there is. */
-  describedBy?: string;
+  /**
+   * Required, with no default in the destructure. \`type = "button"\` looked like
+   * the same thing and is not: it put the answer where no caller could see it.
+   * BUTTON_DEFAULTS carries it instead.
+   */
+  type: "button" | "submit";
+  disabled: boolean;
+  /**
+   * A disabled control with no explanation is the most common accessibility
+   * defect there is. Required so the absence is a decision, nullable because
+   * "there is nothing to point at" is a real answer to it.
+   */
+  describedBy: string | null;
 };
 
-export function Button({ children, tone, emphasis, size, onClick, type = "button", disabled = false, describedBy }: ButtonProps) {
+export function Button({ children, tone, emphasis, size, onClick, type, disabled, describedBy }: ButtonProps) {
   return (
     <Base
       // focusableWhenDisabled: a disabled button that leaves the tab order is a
@@ -448,7 +488,7 @@ export function Button({ children, tone, emphasis, size, onClick, type = "button
       focusableWhenDisabled
       type={type}
       disabled={disabled}
-      aria-describedby={describedBy}
+      aria-describedby={describedBy ?? undefined}
       onClick={onClick ?? undefined}
       data-ds="button"
       data-tone={tone}
@@ -478,7 +518,11 @@ export type TextRole = "micro" | "small" | "body" | "lead" | "title" | "display"
 export type TextProps = {
   children: ReactNode;
   role: TextRole;
-  as?: "p" | "span" | "code";
+  /**
+   * Nullable rather than optional: null means "take the element this role
+   * implies", which is a choice, and DEFAULT_ELEMENT below is where it is read.
+   */
+  as: "p" | "span" | "code" | null;
 };
 
 const DEFAULT_ELEMENT: Record<TextRole, "p" | "span"> = {
@@ -530,10 +574,15 @@ export type CardProps = {
   children: ReactNode;
   tone: CardTone;
   inset: CardInset;
-  as?: "div" | "section" | "article" | "li";
+  /**
+   * Not nullable. Unlike Text there is no role to derive an element from, so
+   * "no answer" would have to mean \`div\` silently — which is the omission the
+   * ban is about. CARD_DEFAULTS says \`div\` out loud.
+   */
+  as: "div" | "section" | "article" | "li";
 };
 
-export function Card({ children, tone, inset, as: Tag = "div" }: CardProps) {
+export function Card({ children, tone, inset, as: Tag }: CardProps) {
   return <Tag data-ds="card" data-tone={tone} data-inset={inset}>{children}</Tag>;
 }
 `,
@@ -560,17 +609,18 @@ export type CheckboxProps = {
   onChange: (checked: boolean) => void;
   label: string;
   id: string;
-  name?: string;
-  disabled?: boolean;
-  indeterminate?: boolean;
+  /** Nullable: a checkbox outside a form has no name, and that is an answer. */
+  name: string | null;
+  disabled: boolean;
+  indeterminate: boolean;
 };
 
-export function Checkbox({ checked, onChange, label, id, name, disabled = false, indeterminate = false }: CheckboxProps) {
+export function Checkbox({ checked, onChange, label, id, name, disabled, indeterminate }: CheckboxProps) {
   return (
     <span data-ds="checkbox">
       <Base.Root
         id={id}
-        name={name}
+        name={name ?? undefined}
         checked={checked}
         indeterminate={indeterminate}
         disabled={disabled}
@@ -610,18 +660,19 @@ export type SelectProps = {
   onChange: (value: string) => void;
   options: readonly SelectOption[];
   label: string;
-  disabled?: boolean;
-  name?: string;
+  disabled: boolean;
+  /** Nullable: a select outside a form has no name, and that is an answer. */
+  name: string | null;
 };
 
-export function Select({ value, onChange, options, label, disabled = false, name }: SelectProps) {
+export function Select({ value, onChange, options, label, disabled, name }: SelectProps) {
   const trigger = useRef<HTMLDivElement>(null);
 
   return (
     <div ref={trigger} data-ds="select">
       <Base.Root
         value={value}
-        name={name}
+        name={name ?? undefined}
         disabled={disabled}
         // The primitive can clear to null; this control has no clear affordance,
         // so narrowing here keeps the callback honest about what can happen.
@@ -770,6 +821,7 @@ function stylesheet(dict) {
 export function emitSystem({ dict = SEED, primitive = "@base-ui/react", path = "packages/design-system", components = SEED_COMPONENTS, tokensPackage = "@scaffold/design-tokens", systemPackage = "@scaffold/design-system" } = {}) {
   const sources = componentSources(primitive);
   const out = {};
+  Object.assign(out, emitThemeChoice({ path, storageKey: `${systemPackage}:theme` }));
 
   for (const name of components) {
     const src = sources[`${name}.tsx`];
@@ -789,7 +841,7 @@ export function emitSystem({ dict = SEED, primitive = "@base-ui/react", path = "
     type: "module",
     main: "./src/index.ts",
     types: "./src/index.ts",
-    exports: { ".": "./src/index.ts", "./styles.css": "./src/styles.css" },
+    exports: { ".": "./src/index.ts", "./styles.css": "./src/styles.css", "./theme-choice": "./src/theme-choice.js", "./theme-bootstrap.js": "./src/theme-bootstrap.js" },
     // The primitive is a real dependency of THIS package and of nothing else —
     // the boundary rule forbids an app from even declaring it.
     dependencies: { [primitive]: "^1.0.0", [tokensPackage]: "workspace:*" },
@@ -800,6 +852,16 @@ export function emitSystem({ dict = SEED, primitive = "@base-ui/react", path = "
   out[`${path}/src/index.ts`] =
 `${GENERATED("completeness of this barrel — set.test.ts fails if a component is missing")}
 ${components.map((n) => `export { ${n} } from "./${n}";\nexport type { ${n}Props } from "./${n}";`).join("\n")}
+/**
+ * G-127. The defaults are part of the public API, not an internal detail.
+ *
+ * Every prop is required (G-68), so \`{...BUTTON_DEFAULTS}\` is how a caller says
+ * "the ordinary answers, please" without restating six of them. Leaving these
+ * out of the barrel left the only ergonomic path behind a deep import into
+ * \`src/\`, which the boundary rules forbid — so the ban had no usable escape
+ * and every call site paid for it.
+ */
+export { ${components.filter((n) => DEFAULTS_EXPORTS[n]).map((n) => DEFAULTS_EXPORTS[n]).join(", ")} } from "./defaults";
 export { themeVars, themeVar } from "./theme";
 export type { SurfaceTheme, ThemeSlot } from "./theme";
 `;

package/index.mjs

@@ -21,7 +21,7 @@ export { SEED, themed, validate, generateCss, generateConstants, generateDtcg, g
 export { seedBoundaries, seedDependencyBoundaries, validateBoundaries, proveBoundaries, proveDependencyBoundaries, loadBoundaries, loadDependencyBoundaries, isImportBreach, checkBoundaries, checkDependencyBoundaries, findVersionDrift } from "./boundaries.mjs";
 export { record, compare, gate, formatGate, tally, LEDGER_NOTE } from "./ratchet.mjs";
 
-export { emitTokens, emitSystem, emitConfig, SEED_COMPONENTS, SCAFFOLD_VERSION, NOT_UPGRADEABLE } from "./emit.mjs";
+export { emitTokens, emitSystem, emitConfig, SEED_COMPONENTS, DEFAULTS_EXPORTS, SCAFFOLD_VERSION, NOT_UPGRADEABLE } from "./emit.mjs";
 export { emitCatalogue, CATALOGUE_ENTRIES } from "./catalogue.mjs";
 export { emitAgentDocs, agentDoc, agentInstructionsFragment } from "./agentdocs.mjs";
 
@@ -37,4 +37,5 @@ export { reconcile, formatAdoption, LAYERS as ADOPTION_LAYERS } from "./adoption
 export { classifyMarkup, markupAdoption, formatMarkup, KIND as MARKUP_KIND } from "./markup.mjs";
 export { orphanedParts, formatOrphanedParts, RULE as COMPOUND_RULE } from "./compound.mjs";
 export { checkDocDrift, importedFrom, formatDocDrift, namedInProse, isContractDoc, isFixtureDeclaration, stalePaths, rootDirectories, formatStalePaths, RULE as DOC_DRIFT_RULE, PROSE_RULE, PATH_RULE } from "./docdrift.mjs";
+export { rules, rulesJson } from "./ruleindex.mjs";
 export { isClientModule, parseImports, parseReexports, valueUses, checkClientBoundary, formatClientBoundary } from "./clientboundary.mjs";

package/markup.mjs

@@ -117,7 +117,7 @@ export function classifyMarkup(text, { systemNames = null } = {}) {
     counts,
     // The population where "should this have been a component?" is a real
     // question. Never the total element count.
-    adoption: { used: counts.system, of, percent: of ? Math.round((counts.system / of) * 100) : null },
+    adoption: { used: counts.system, of, percent: of ? Math.floor((counts.system / of) * 100) : null },
     bespokeElements,
   };
 }
@@ -149,7 +149,7 @@ export function markupAdoption(files, { systemNames = null } = {}) {
   return {
     unknown: false,
     counts: totals,
-    adoption: { used: totals.system, of, percent: of ? Math.round((totals.system / of) * 100) : null },
+    adoption: { used: totals.system, of, percent: of ? Math.floor((totals.system / of) * 100) : null },
     perFile: perFile.sort((a, b) => (a.percent ?? 101) - (b.percent ?? 101)),
     filesWithMarkup: perFile.length,
   };

package/normalise.mjs

@@ -342,6 +342,111 @@ export function normaliseUtilities(classString, { spacingStep = TAILWIND_SPACING
   return out;
 }
 
+/**
+ * Does this quoted run read as a class list, or as an English sentence?
+ *
+ * G-110. The unattached-string matcher below exists for `cva("… rounded-md
+ * px-4 …")`, which carries no `className`. Its gate was a word test — the run
+ * had to mention `shadow`, `border`, `flex` and so on — and the word `shadow`
+ * is *also* a complete Tailwind utility. So
+ *
+ *     includes(f, "gl.shadowMap.enabled", "parks renderer shadow map must be enabled")
+ *
+ * parsed as a class list containing one class, and a Node assertion harness
+ * with no markup in it at all scored four `arbitrary-shadow` violations. A
+ * false positive of that shape cannot be fixed — nobody can tokenise an English
+ * sentence — so the only available response is a ledger entry, and the ledger is
+ * supposed to only ever get shorter.
+ *
+ * The distinguishing property is not vocabulary, it is SHAPE. Utility classes
+ * are overwhelmingly compound — `rounded-md`, `px-4`, `hover:bg-primary`,
+ * `w-[7px]` — while English words are bare. So: at least two compound tokens,
+ * and compound tokens in the majority.
+ *
+ * A ratio rather than "every token", deliberately. Real class lists are full of
+ * bare utilities (`flex`, `grid`, `border`, `truncate`, `italic`) and that set
+ * is open-ended; requiring all of them to be recognised is the widening that
+ * ends in a rule which matches nothing. This test is checked in both directions
+ * by fixtures: prose must not parse, and `cva("inline-flex … shadow-sm")` must.
+ */
+const COMPOUND_CLASS = /^-?[a-z0-9]+[a-z0-9./[\]-]*(?:[-:/[][^\s]*)$/i;
+
+export function looksLikeClassList(run) {
+  const tokens = String(run).trim().split(/\s+/).filter(Boolean);
+  if (tokens.length < 3) return false;
+  const compound = tokens.filter((t) => /[-:/[]/.test(t) && COMPOUND_CLASS.test(t)).length;
+  return compound >= 2 && compound * 2 > tokens.length;
+}
+
+/**
+ * Is this `prop: value` inside a string literal a declaration, or a sentence
+ * with a colon in it?
+ *
+ * G-110, the same defect reached by the other matcher. The style-object pass
+ * reads `prop: value` out of raw line text, so
+ *
+ *     assert(ok, "expected background: #ffffff to be applied")
+ *
+ * produced an `untokenised-colour` finding against a message.
+ *
+ * Refusing string literals wholesale would be wrong in the expensive direction,
+ * and it was measured before it was reasoned about: a consumer repository builds
+ * markup as strings —
+ *
+ *     html += '<div style="display:flex;gap:8px;margin-bottom:20px">'
+ *
+ * — and blanket-skipping literals silently dropped **seven real findings** in
+ * four files. A styled-components template is the same shape. So the test is
+ * per-declaration and structural: the `;{}`-delimited SEGMENT the match sits in
+ * must be exactly `ident: value`, with nothing either side of it. `gap:8px` is;
+ * `expected background: #ffffff to be applied` is not, because of the words in
+ * front of the colon.
+ *
+ * The residual is narrow and worth naming: a sentence that BEGINS with a real
+ * CSS property name and a plausible value — `"color: red is expected"` — still
+ * parses. It takes a segment boundary to hide behind, and no such string exists
+ * in either repository measured.
+ */
+const DECL_SEGMENT = /^\s*-{0,2}[A-Za-z][\w$-]*\s*:\s*[^:;{}]+$/;
+// Nested quotes are a boundary too: the whole reason these literals contain
+// declarations is `style="…"` inside built markup, and without it the first
+// declaration in every inline style block keeps the `<div style="` prefix and
+// fails the test. That was measured — it cost `background:#4a3000` on the first
+// attempt at this fix.
+const SEGMENT_BOUNDARY = /[;{}"'`]/;
+
+/** The `;{}"'`-delimited segment of `text` containing offset `at`. */
+export function segmentAround(text, at) {
+  let start = at;
+  while (start > 0 && !SEGMENT_BOUNDARY.test(text[start - 1])) start--;
+  let end = at;
+  while (end < text.length && !SEGMENT_BOUNDARY.test(text[end])) end++;
+  return text.slice(start, end);
+}
+
+/** Single-line string literal spans on a line, as [start, end) over the QUOTED text. */
+function stringSpans(line) {
+  const spans = [];
+  let i = 0;
+  while (i < line.length) {
+    const ch = line[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      let j = i + 1;
+      while (j < line.length) {
+        if (line[j] === "\\") { j += 2; continue; }
+        if (line[j] === ch) break;
+        j++;
+      }
+      if (j >= line.length) return spans;            // unterminated: a multi-line template
+      spans.push({ start: i, end: j + 1, content: line.slice(i + 1, j) });
+      i = j + 1;
+      continue;
+    }
+    i++;
+  }
+  return spans;
+}
+
 function utilityProperty(prefix) {
   if (prefix === "rounded") return PROP.RADIUS;
   if (prefix === "text") return PROP.TYPE;
@@ -395,6 +500,9 @@ export function normaliseSource(text, { filename = "", rootFontSize = 16, spacin
     // the same string seen twice.
     for (const m of line.matchAll(/["'`]([a-z0-9-]+(?:\s+[a-z0-9:./[\]-]+){2,})["'`]/gi)) {
       if (overlaps(m.index, m.index + m[0].length)) continue;
+      // G-110. Shape first: a word test admits any sentence containing the word
+      // `shadow`, and `shadow` is itself a complete utility.
+      if (!looksLikeClassList(m[1])) continue;
       if (/\b(rounded|text-|bg-|p-|px-|py-|m-|gap-|border|shadow|flex|grid|h-|w-)/.test(m[1])) {
         claim(m.index, m.index + m[0].length);
         at(normaliseUtilities(m[1], { spacingStep }));
@@ -402,7 +510,14 @@ export function normaliseSource(text, { filename = "", rootFontSize = 16, spacin
     }
 
     // Style objects: `borderRadius: 8`, `padding: "16px"`, `color: colors.ink`.
+    //
+    // G-110. A `prop: value` pair INSIDE a string literal is only styling if
+    // the whole literal is declaration shaped — `styled.div\`padding: 12px\`` is,
+    // `"expected background: #ffffff to be applied"` is not.
+    const literals = stringSpans(line);
     for (const m of line.matchAll(/([A-Za-z][\w$]*)\s*:\s*("[^"]*"|'[^']*'|`[^`]*`|[\w$.()#%-]+)/g)) {
+      const inside = literals.find((s) => m.index > s.start && m.index < s.end - 1);
+      if (inside && !DECL_SEGMENT.test(segmentAround(inside.content, m.index - inside.start - 1))) continue;
       const value = m[2].replace(/^["'`]|["'`]$/g, "");
       at(normaliseDeclaration(m[1], value, { source: "object", rootFontSize }));
     }

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@weatherboard/gyde-design",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "private": false,
   "description": "Scaffolds a design system into a product repository, then keeps auditing it.",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Another-Iteration/gyde.git",
+    "url": "git+https://github.com/Weatherboard-Studio/gyde.git",
     "directory": "packages/design"
   },
   "bin": {
@@ -18,6 +18,7 @@
     "./workspace.mjs": "./workspace.mjs",
     "./normalise.mjs": "./normalise.mjs",
     "./rules.mjs": "./rules.mjs",
+    "./ruleindex.mjs": "./ruleindex.mjs",
     "./scan.mjs": "./scan.mjs",
     "./tokens.mjs": "./tokens.mjs",
     "./boundaries.mjs": "./boundaries.mjs",

package/props.mjs

@@ -29,11 +29,14 @@
  * repository starts. That is CHARTER §4 exactly: debt is recorded, never
  * amnestied, and the list may only get shorter.
  *
- * The mechanism that lets it arrive at all is G-68's other half — a rule a
- * ledger predates is adopted as existing debt rather than failing the build
- * (ratchet.mjs, `rulesKnownTo`). Without it this rule could not ship to an
- * existing consumer without turning their gate red for code they did not
- * change.
+ * The mechanism that lets it arrive at all is `gate --record-new-rules`: a rule
+ * the ledger does not name fails, and the failure carries the command that
+ * records its findings as existing debt (ratchet.mjs, `rulesKnownTo`, `adopt`).
+ *
+ * G-68 made that recording automatic and this rule is the reason we know it was
+ * wrong — it shipped after one consumer's baseline and was absorbed on every
+ * run: 173 findings across 80 files, gate green, ledger silently growing. G-108
+ * kept the escape hatch and removed the silence.
  *
  * WHAT IT DELIBERATELY DOES NOT DO.
  *