npm - @terpjs/contract - Versions diffs - 0.6.1 → 0.7.0 - Mend

@terpjs/contract 0.6.1 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/package.json +3 -2
package/scripts/build-tokens.mjs +156 -25
package/src/css-rules.js +107 -0
package/src/css-rules.test.js +110 -0
package/src/tokens.contrast.test.js +244 -0
package/src/tokens.css +293 -14
package/src/tokens.manifest.json +1266 -0
package/src/tokens.manifest.test.js +149 -0
package/src/tokens.themes.test.js +177 -0
package/themes.json +43 -0
package/token-pairs.json +138 -0
package/tokens.contrast.json +71 -0
package/tokens.dark.json +41 -4
package/tokens.json +98 -7
package/tokens.midnight.json +71 -0
package/tokens.twilight.json +71 -0

package/package.json CHANGED Viewed

@@ -1,13 +1,14 @@
 {
   "name": "@terpjs/contract",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "description": "Terp frontend contract \u2014 the OpenAPI-generated TypeScript client, design tokens, and the stack-agnostic module/route/nav + auth types.",
   "exports": {
     ".": "./src/index.ts",
     "./schema": "./src/schema.d.ts",
     "./openapi.json": "./openapi.json",
-    "./tokens.css": "./src/tokens.css"
+    "./tokens.css": "./src/tokens.css",
+    "./tokens.manifest.json": "./src/tokens.manifest.json"
   },
   "types": "./src/index.ts",
   "bin": {

package/scripts/build-tokens.mjs CHANGED Viewed

@@ -1,12 +1,19 @@
 /**
- * Token build: tokens.json (light, the framework-agnostic source of truth) +
- * tokens.dark.json (the dark colour overrides) -> src/tokens.css (design §7.1, item 2).
+ * Token build: the theme registry in `themes.json` plus one source per theme -> the compiled
+ * stylesheet `src/tokens.css` and the published `src/tokens.manifest.json` (design §7.1, item 2).
  *
- * The output is one stylesheet with three blocks:
- *   1. `:root`                       — the light theme (every token).
- *   2. `[data-theme="dark"]`         — the dark colour overrides (explicit choice).
- *   3. `@media (prefers-color-scheme: dark)` scoped to `:root:not([data-theme="light"])`
- *      — the OS preference applies automatically unless the app pinned a theme.
+ * The output is one stylesheet with a block per theme:
+ *   1. `:root`                       — the base theme, and the only block carrying geometry.
+ *   2. `[data-theme='<name>']`       — one per non-base theme, colours only, an explicit choice.
+ *   3. `@media (prefers-color-scheme: dark)` scoped to `:root:not([data-theme])`
+ *      — the OS preference selects the registry's `systemDark` theme when nothing is pinned.
+ *
+ * The media selector matches only an *unpinned* root. It used to be
+ * `:root:not([data-theme='light'])`, which was equivalent while `light` and `dark` were the
+ * only themes and became a defect the moment a third existed: it matches
+ * `[data-theme='contrast']`, outranks it on specificity (two compound parts against one), and
+ * so laid the dark colours over a theme the app had explicitly pinned whenever the OS
+ * preferred dark.
  *
  * Apps opt in/out per user via the `data-theme` attribute on <html> (react-core's
  * `ThemeProvider` manages it); with no attribute the OS preference wins. Regenerate with
@@ -22,6 +29,32 @@ import StyleDictionary from "style-dictionary";
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const buildDir = mkdtempSync(join(tmpdir(), "terp-tokens-"));
+const read = (name) => JSON.parse(readFileSync(join(packageRoot, name), "utf8"));
+const registry = read("themes.json");
+const themes = registry.themes;
+const base = themes.find((theme) => theme.name === registry.base);
+const overlays = themes.filter((theme) => theme.name !== registry.base);
+// The generator is the first thing to read the registry, so it is the right place to refuse a
+// registry that cannot produce a coherent sheet. Each of these would otherwise emit something
+// that looks fine and behaves wrongly in the browser.
+if (!base) throw new Error(`themes.json: base theme "${registry.base}" is not in the list`);
+if (!themes.some((theme) => theme.name === registry.systemDark)) {
+  throw new Error(`themes.json: systemDark "${registry.systemDark}" is not in the list`);
+}
+if (registry.systemDark === registry.base) {
+  throw new Error("themes.json: systemDark must not be the base theme");
+}
+for (const theme of themes) {
+  if (!/^[a-z][a-z0-9-]*$/.test(theme.name)) {
+    throw new Error(`themes.json: "${theme.name}" is not usable as a data-theme value`);
+  }
+  if (theme.appearance !== "light" && theme.appearance !== "dark") {
+    throw new Error(`themes.json: ${theme.name} appearance must be "light" or "dark"`);
+  }
+}
 async function buildCss(sourceFile, outputFile) {
   const sd = new StyleDictionary({
     source: [join(packageRoot, sourceFile)],
@@ -51,36 +84,134 @@ function declarations(css) {
     .join("\n");
 }
-const light = declarations(await buildCss("tokens.json", "tokens.light.css"));
-const dark = declarations(await buildCss("tokens.dark.json", "tokens.dark.css"));
+/** Every theme's compiled declaration lines, keyed by theme name, in registry order. */
+const compiled = new Map();
+for (const theme of themes) {
+  compiled.set(
+    theme.name,
+    declarations(await buildCss(theme.source, `tokens.${theme.name}.css`)),
+  );
+}
 rmSync(buildDir, { recursive: true, force: true });
+const themeBlocks = overlays
+  .map(
+    (theme) => `
+/* ${theme.label}: an explicit choice via <html data-theme="${theme.name}">.
+   ${theme.description} */
+[data-theme='${theme.name}'] {
+  color-scheme: ${theme.appearance};
+${compiled.get(theme.name)}
+}
+`,
+  )
+  .join("");
+const systemDark = themes.find((theme) => theme.name === registry.systemDark);
 const output = `/**
  * Do not edit directly, this file was auto-generated.
  */
 :root {
   /* Opts native chrome (scrollbars, the <select> option popup, form controls,
-     text-field carets) into the light palette so it never renders as foreign
-     OS-light chrome. The dark blocks below flip it to dark. */
-  color-scheme: light;
-${light}
-}
-/* Dark theme: an explicit user/app choice via <html data-theme="dark">. */
-[data-theme='dark'] {
-  color-scheme: dark;
-${dark}
+     text-field carets) into the ${base.appearance} palette so it never renders as foreign
+     OS-${base.appearance === "light" ? "dark" : "light"} chrome. Each theme block below sets its own. */
+  color-scheme: ${base.appearance};
+${compiled.get(base.name)}
 }
-/* Dark theme: the OS preference, unless the app pinned light explicitly. */
+${themeBlocks}
+/* ${systemDark.label}: the OS preference, unless the app pinned any theme explicitly. */
 @media (prefers-color-scheme: dark) {
-  :root:not([data-theme='light']) {
-    color-scheme: dark;
-${dark.replace(/^ {2}/gm, "    ")}
+  :root:not([data-theme]) {
+    color-scheme: ${systemDark.appearance};
+${compiled.get(systemDark.name).replace(/^ {2}/gm, "    ")}
   }
 }
 `;
 writeFileSync(join(packageRoot, "src", "tokens.css"), output);
-console.log("wrote src/tokens.css");
+console.log(`wrote src/tokens.css (${themes.length} themes)`);
+/**
+ * The manifest: the same tokens as machine-readable data, so a consumer does not have to
+ * parse a stylesheet to find out what exists.
+ *
+ * Three consumers need it and none of them could get it before. A theme editor had to
+ * hard-code its own token list, because `tokens.json` is Style-Dictionary-shaped and is not
+ * exported from the package — only the compiled CSS is. An agent editing a theme by hand had
+ * to infer names from whatever it found in `node_modules`, with no way to tell which tokens
+ * are safe to theme or which must stay legible against which. And a human had no list at all.
+ *
+ * Everything here is derived, never restated: the token set comes from the theme sources, the
+ * category from the token's own path, `themeable` from whether any non-base theme overrides it,
+ * and the pairings from `token-pairs.json` — the same file the contrast gate reads. Nothing in
+ * this file can disagree with the stylesheet beside it, because both are generated from the
+ * same input in the same run.
+ */
+function cssName(path) {
+  return `--${path.join("-")}`.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/**
+ * Every leaf `{ value }` in a token tree, as `[cssName, { value, category }]`.
+ *
+ * The category is the source tree's own top-level family, not a re-split of the CSS name:
+ * `zIndex.base` is in the `zIndex` family even though it flattens to `--z-index-base`, and
+ * splitting the CSS name would have called that family `z`.
+ */
+function flatten(node, path = []) {
+  if (node && typeof node === "object" && "value" in node) {
+    return [[cssName(path), { value: String(node.value), category: path[0] }]];
+  }
+  if (!node || typeof node !== "object") return [];
+  return Object.entries(node).flatMap(([key, child]) => flatten(child, [...path, key]));
+}
+const sources = new Map(
+  themes.map((theme) => [theme.name, new Map(flatten(read(theme.source)))]),
+);
+const baseTokens = sources.get(base.name);
+const pairs = read("token-pairs.json");
+const manifest = {
+  $comment:
+    "Generated by scripts/build-tokens.mjs from themes.json, the per-theme token sources and " +
+    "token-pairs.json. Do not edit directly; regenerate with `npm run -w @terpjs/contract " +
+    "tokens`. CI fails on drift.",
+  // The themes a `values` key can name, so a consumer can build a theme picker from this file
+  // alone rather than hard-coding the list it happens to know about.
+  base: registry.base,
+  systemDark: registry.systemDark,
+  themes: themes.map(({ name, label, appearance, description }) => ({
+    name,
+    label,
+    appearance,
+    description,
+  })),
+  tokens: [...baseTokens.entries()].map(([name, token]) => ({
+    name,
+    category: token.category,
+    // Only the themes that actually declare the token, base always included. A theme absent
+    // here inherits the base value — the cascade the sheet performs, stated as data. A token
+    // present under the base alone is theme-invariant by design (space, radius, font, motion,
+    // z-index): declared once and inherited. Saying so is what stops an editor from offering a
+    // per-theme control that would have no effect.
+    values: Object.fromEntries(
+      themes
+        .map((theme) => [theme.name, sources.get(theme.name).get(name)?.value])
+        .filter(([, value]) => value !== undefined),
+    ),
+    themeable: overlays.some((theme) => sources.get(theme.name).has(name)),
+  })),
+  textPairs: pairs.textPairs,
+};
+writeFileSync(
+  join(packageRoot, "src", "tokens.manifest.json"),
+  `${JSON.stringify(manifest, null, 2)}\n`,
+);
+console.log(
+  `wrote src/tokens.manifest.json (${manifest.tokens.length} tokens, ` +
+    `${manifest.themes.length} themes, ${manifest.textPairs.length} pairs)`,
+);

package/src/css-rules.js ADDED Viewed

@@ -0,0 +1,107 @@
+// A minimal CSS rule reader for the token-sheet gates.
+//
+// Not a general parser and not exported from the package (`exports` in package.json
+// publishes only the entry, the schema, the OpenAPI document and the sheet itself). It
+// exists because two gates read `tokens.css` and a naive "slice to the next `}`" scan is
+// wrong in a way that passes: a value containing a brace, or an `@media` wrapper, ends the
+// block early and the gate then asserts about a fragment.
+/**
+ * Every `selector { … }` rule in `css`, flattened.
+ *
+ * An `@media` (or any other conditional group) contributes its inner rules rather than
+ * itself, so a nested `:root` is reachable by selector. A statement at-rule — `@charset`,
+ * `@import`, `@layer a, b;` — declares no block and is skipped; without that, its trailing
+ * `;` would let the scan run on to the *next* rule's brace and silently merge two rules.
+ *
+ * Each rule carries its custom properties as `declarations` and *every* declaration —
+ * standard properties included — as `properties`. The two are separate because the token
+ * gates want only custom properties nearly everywhere (a theme block is a set of tokens),
+ * and exactly one gate wants a standard one: `color-scheme`, which every theme block must
+ * declare and which is invisible to a custom-property reader.
+ *
+ * @param {string} css
+ * @returns {{ selector: string, declarations: Map<string, string>, properties: Map<string, string> }[]}
+ */
+export function parseRules(css) {
+  const source = stripComments(css);
+  const rules = [];
+  let index = 0;
+  while (index < source.length) {
+    const open = source.indexOf("{", index);
+    if (open === -1) break;
+    // A `;` before the next `{` means the run of text is a statement at-rule, not a
+    // selector: consume it and carry on rather than treating the following block as its own.
+    const statementEnd = source.indexOf(";", index);
+    if (statementEnd !== -1 && statementEnd < open) {
+      index = statementEnd + 1;
+      continue;
+    }
+    const selector = source.slice(index, open).trim();
+    let depth = 1;
+    let cursor = open + 1;
+    // Quote-aware: a brace inside a quoted value (a font stack, a `url()`, a `content`
+    // string) is data, not structure. Counting it would end the block early and leave every
+    // later declaration in the rule unread — silently, because the fragment still parses.
+    let quote = "";
+    while (cursor < source.length && depth > 0) {
+      const character = source[cursor];
+      if (quote) {
+        if (character === "\\") cursor += 1;
+        else if (character === quote) quote = "";
+      } else if (character === '"' || character === "'") {
+        quote = character;
+      } else if (character === "{") depth += 1;
+      else if (character === "}") depth -= 1;
+      cursor += 1;
+    }
+    const body = source.slice(open + 1, cursor - 1);
+    if (selector.startsWith("@")) {
+      rules.push(...parseRules(body));
+    } else if (selector) {
+      rules.push({
+        selector,
+        declarations: parseDeclarations(body),
+        properties: parseProperties(body),
+      });
+    }
+    index = cursor;
+  }
+  return rules;
+}
+/**
+ * The `--token: value` custom properties declared directly in a rule body, in source order.
+ *
+ * @param {string} body
+ * @returns {Map<string, string>}
+ */
+export function parseDeclarations(body) {
+  const declarations = new Map();
+  for (const match of body.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) {
+    declarations.set(match[1], match[2].trim());
+  }
+  return declarations;
+}
+/**
+ * Every declaration directly in a rule body, standard properties included, in source order.
+ *
+ * Only `color-scheme` is read through this today, but a reader that special-cased that one
+ * name would quietly stop working the moment a second standard property mattered.
+ *
+ * @param {string} body
+ * @returns {Map<string, string>}
+ */
+export function parseProperties(body) {
+  const properties = new Map();
+  for (const match of body.matchAll(/([a-zA-Z-][\w-]*)\s*:\s*([^;]+);/g)) {
+    properties.set(match[1], match[2].trim());
+  }
+  return properties;
+}
+/** `css` with `/* … *\/` comments removed. */
+export function stripComments(css) {
+  return css.replace(/\/\*[\s\S]*?\*\//g, "");
+}

package/src/css-rules.test.js ADDED Viewed

@@ -0,0 +1,110 @@
+import { describe, expect, it } from "vitest";
+import {
+  parseDeclarations,
+  parseProperties,
+  parseRules,
+  stripComments,
+} from "./css-rules.js";
+// The reader the two token gates are built on. Every case here is a shape that made an
+// earlier, naive version of this code assert about a fragment of a rule while still
+// reporting green — which is the only failure mode that matters for a gate.
+describe("parseRules", () => {
+  it("reads a flat rule's custom properties", () => {
+    const rules = parseRules(":root { --a: 1; --b: 2; }");
+    expect(rules).toHaveLength(1);
+    expect(rules[0].selector).toBe(":root");
+    expect([...rules[0].declarations]).toEqual([
+      ["--a", "1"],
+      ["--b", "2"],
+    ]);
+  });
+  it("flattens a conditional group to its inner rules", () => {
+    // The sheet's OS-preference dark theme is a `:root:not(…)` nested in `@media`. A reader
+    // that returned the `@media` itself would find no declarations and the completeness
+    // gate would pass by asserting about nothing.
+    const rules = parseRules(
+      "@media (prefers-color-scheme: dark) { :root:not([data-theme='light']) { --a: 9; } }",
+    );
+    expect(rules.map((rule) => rule.selector)).toEqual([":root:not([data-theme='light'])"]);
+    expect(rules[0].declarations.get("--a")).toBe("9");
+  });
+  it("skips a statement at-rule instead of swallowing the next rule", () => {
+    // `@layer tokens;` declares no block. Scanning to the next `{` would make the selector
+    // `@layer tokens; :root`, which starts with `@`, so the reader would recurse into
+    // `:root`'s body and drop the rule — `:root` then does not exist and every downstream
+    // assertion is about a sheet with no light theme.
+    const rules = parseRules("@layer tokens;\n:root { --a: 1; }");
+    expect(rules.map((rule) => rule.selector)).toEqual([":root"]);
+    expect(rules[0].declarations.get("--a")).toBe("1");
+  });
+  it("skips a charset or import line the same way", () => {
+    const rules = parseRules('@charset "utf-8";\n@import "x.css";\n:root { --a: 1; }');
+    expect(rules.map((rule) => rule.selector)).toEqual([":root"]);
+  });
+  it("does not end a block on a brace inside a value", () => {
+    // Not hypothetical for a generated sheet: a font stack or a `url()` can carry one.
+    const rules = parseRules(':root { --a: "}"; --b: 2; }');
+    expect(rules).toHaveLength(1);
+    expect(rules[0].declarations.get("--b")).toBe("2");
+  });
+  it("ignores commented-out declarations", () => {
+    const rules = parseRules(":root { /* --a: 1; */ --b: 2; }");
+    expect([...rules[0].declarations.keys()]).toEqual(["--b"]);
+  });
+  it("returns nothing for a sheet with no rules", () => {
+    expect(parseRules("")).toEqual([]);
+    expect(parseRules("/* just a comment */")).toEqual([]);
+  });
+});
+describe("parseProperties", () => {
+  it("reads standard properties alongside custom ones", () => {
+    // `color-scheme` is the reason this exists: every theme block must declare it, and a
+    // custom-property reader cannot see it, so the gate that checks it would pass vacuously.
+    const properties = parseProperties("color-scheme: dark; --a: 1;");
+    expect([...properties]).toEqual([
+      ["color-scheme", "dark"],
+      ["--a", "1"],
+    ]);
+  });
+  it("does not read a property name out of a value", () => {
+    // A value containing a colon — a `url(https://…)`, a media condition — would otherwise
+    // register as a second property and the caller would be reading noise.
+    expect([...parseProperties("background: url(https://x/y.png);").keys()]).toEqual([
+      "background",
+    ]);
+  });
+  it("is exposed on every rule the reader returns", () => {
+    const [rule] = parseRules(":root { color-scheme: light; --a: 1; }");
+    expect([...rule.declarations.keys()]).toEqual(["--a"]);
+    expect(rule.properties.get("color-scheme")).toBe("light");
+  });
+});
+describe("parseDeclarations", () => {
+  it("keeps the last value when a property repeats", () => {
+    // The cascade's own behaviour: a duplicated property in one block resolves to the last.
+    expect(parseDeclarations("--a: 1; --a: 2;").get("--a")).toBe("2");
+  });
+  it("ignores ordinary properties", () => {
+    expect([...parseDeclarations("color: red; --a: 1;").keys()]).toEqual(["--a"]);
+  });
+});
+describe("stripComments", () => {
+  it("removes multi-line comments", () => {
+    expect(stripComments("a/* x\ny */b")).toBe("ab");
+  });
+});