@hanzo/design 0.4.13 → 0.5.0

package/scripts/check-preference.mjs

@@ -1,168 +0,0 @@
-/**
- * Preference contract, checked the way this package already checks tokens:
- * a plain node script, no framework, run by `npm test`.
- *
- * The load-bearing check is the last one. The first version of preference.ts
- * kept its own copy of the type ramp and the copy was WRONG (lg/xl were 16/18
- * against the tokens' 15/17), so a preference of 1 — "leave it alone" — would
- * have resized two rungs of the published design. Nothing caught it, because
- * nothing compared the copy to the source. Now there is no copy: the knobs are
- * multipliers and the ramps live only in tokens/*.css, and check 5 fails if a
- * rung ever stops carrying its multiplier.
- */
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-
-const here = dirname(fileURLToPath(import.meta.url));
-const root = join(here, "..");
-
-// Load the source directly — this package ships tokens, and the preference
-// module is small enough to evaluate without a build step in the check.
-const src = readFileSync(join(root, "src/preference.ts"), "utf8");
-const js = src
-  .replace(/^import[^\n]*\n/gm, "")
-  .replace(/export (type|interface) [\s\S]*?\n}\n/g, "")
-  .replace(/export type [^\n]*\n/g, "")
-  .replace(/: Record<[^>]*>/g, "")
-  .replace(/: Preference/g, "")
-  .replace(/: Density/g, "")
-  .replace(/: string/g, "")
-  .replace(/: number/g, "")
-  .replace(/: boolean/g, "")
-  .replace(/export /g, "");
-
-const mod = new Function(`${js}; return { vars, css, isColor, TYPE_MIN, TYPE_MAX };`)();
-const { vars, css, isColor, TYPE_MIN, TYPE_MAX } = mod;
-
-let failed = 0;
-const check = (name, fn) => {
-  try {
-    fn();
-    console.log(`  ok   ${name}`);
-  } catch (e) {
-    failed++;
-    console.error(`  FAIL ${name}\n       ${e.message}`);
-  }
-};
-const eq = (a, b, m) => {
-  const A = JSON.stringify(a), B = JSON.stringify(b);
-  if (A !== B) throw new Error(`${m || ""} got ${A} want ${B}`);
-};
-const ok = (v, m) => { if (!v) throw new Error(m || "expected truthy"); };
-
-console.log("preference:");
-
-check("an unset preference changes nothing", () => {
-  eq(vars({}), {});
-  eq(css({}), "");
-});
-
-check("type is ONE knob, not a restated ramp", () => {
-  const v = vars({ type: 1.2 });
-  eq(Object.keys(v), ["--type-scale"], "type must emit exactly one name:");
-  eq(v["--type-scale"], "1.2");
-});
-
-check("type is CLAMPED — a preference cannot make the UI illegible", () => {
-  eq(vars({ type: 0.1 })["--type-scale"], String(TYPE_MIN), "min");
-  eq(vars({ type: 99 })["--type-scale"], String(TYPE_MAX), "max");
-  // the smallest rung must stay readable at the floor: 11px * TYPE_MIN
-  ok(11 * TYPE_MIN >= 9, "xs falls below 9px at the floor");
-});
-
-check("density moves spacing only, and never touches type", () => {
-  const v = vars({ density: "compact" });
-  eq(Object.keys(v), ["--density"]);
-  ok(Number(v["--density"]) < 1, "compact should tighten");
-  ok(Number(vars({ density: "comfortable" })["--density"]) > 1, "comfortable should loosen");
-  ok(!("--type-scale" in v), "density must not touch type");
-  // Spacing compounds through nesting, so the range stays tight enough that a
-  // 44px coarse-pointer target does not fall under the floor.
-  ok(Number(vars({ density: "compact" })["--density"]) >= 0.8, "compact is too tight to stay tappable");
-});
-
-check("EVERY ramp rung carries its multiplier — no rung can opt out", () => {
-  // This is the check that the drifting copy would have failed.
-  const type = readFileSync(join(root, "tokens/typography.css"), "utf8");
-  const space = readFileSync(join(root, "tokens/spacing.css"), "utf8");
-
-  const bare = [];
-  for (const [file, text, knob, re] of [
-    ["typography.css", type, "--type-scale", /--text-[a-z0-9]+:\s*([^;]+);/g],
-    ["spacing.css", space, "--density", /--space-\d+:\s*([^;]+);/g],
-  ]) {
-    for (const m of text.matchAll(re)) {
-      const value = m[1].trim();
-      if (value === "0") continue;                 // zero times anything is zero
-      if (value.startsWith("var(")) continue;      // an alias inherits its target's calc
-      if (!value.includes(`var(${knob}`)) bare.push(`${file}: ${m[0].trim()}`);
-    }
-  }
-  eq(bare, [], "rungs that do NOT scale with their knob:");
-});
-
-check("a unitless leading stays a RATIO — scaling it would double-apply", () => {
-  const type = readFileSync(join(root, "tokens/typography.css"), "utf8");
-  const bad = [];
-  for (const m of type.matchAll(/--leading-[a-z0-9]+:\s*([^;]+);/g)) {
-    const v = m[1].trim();
-    // A ratio (`1.05`) already scales with the font size it multiplies.
-    if (/^[0-9.]+$/.test(v) === false) continue;
-    if (v.includes("var(")) bad.push(m[0].trim());
-  }
-  eq(bad, [], "unitless leadings must not carry a multiplier:");
-});
-
-check("a colour lands on both --primary and --accent", () => {
-  const v = vars({ accent: "#808000" });
-  eq(v["--primary"], "#808000");
-  eq(v["--accent"], "#808000");
-});
-
-check("a NON-colour is dropped, never sanitised into something plausible", () => {
-  for (const bad of [
-    "red; background-image:url(//evil/x)",
-    "}html{display:none",
-    "url(//evil/x)",
-    "expression(alert(1))",
-    "",
-    "   ",
-  ]) {
-    const v = vars({ accent: bad });
-    ok(!("--primary" in v), `accepted ${JSON.stringify(bad)}`);
-    ok(!isColor(bad), `isColor said yes to ${JSON.stringify(bad)}`);
-  }
-});
-
-check("real colour notations are accepted", () => {
-  for (const good of ["#fff", "#ffffff", "#ffffffff", "rgb(1 2 3)", "oklch(.7 .1 120)", "rebeccapurple"]) {
-    ok(isColor(good), `isColor said no to ${good}`);
-  }
-});
-
-check("css() emits ONE block for the selector it is given", () => {
-  const out = css({ type: 1.1, density: "compact", accent: "#fff" }, ":root");
-  ok(out.startsWith(":root{") && out.endsWith("}"), out.slice(0, 40));
-  ok(!out.includes("}" + "{"), "emitted more than one block");
-});
-
-check("every emitted name is one the token files actually read", () => {
-  // A variable nothing reads is a write into another document — the exact
-  // mistake this package exists to prevent. The knobs are READ by the ramps
-  // (as var(--knob, 1)); the colours are DECLARED by colors.css.
-  const files = ["tokens/typography.css", "tokens/spacing.css", "tokens/grid.css", "tokens/colors.css"];
-  const text = files.map((f) => readFileSync(join(root, f), "utf8")).join("\n");
-  const declared = new Set([...text.matchAll(/^\s*(--[a-z0-9-]+)\s*:/gm)].map((m) => m[1]));
-  const read = new Set([...text.matchAll(/var\((--[a-z0-9-]+)/g)].map((m) => m[1]));
-
-  const emitted = Object.keys(vars({ type: 1.1, density: "compact", accent: "#fff" }));
-  const orphans = emitted.filter((k) => !declared.has(k) && !read.has(k));
-  eq(orphans, [], "emitted names no token file declares or reads:");
-});
-
-if (failed) {
-  console.error(`\n${failed} preference check(s) failed`);
-  process.exit(1);
-}
-console.log("preference: all checks passed");

package/src/preference.ts

@@ -1,122 +0,0 @@
-/**
- * A person's own reading of the system: type size, density, accent.
- *
- * Three knobs, and each is ONE multiplier on a whole axis — never a restated
- * ramp. The ramps live in `tokens/*.css`, authored once, and each rung carries
- * its own `calc(<base> * var(--type-scale, 1))`. So a preference sets three
- * numbers and every rung follows, including rungs added later and rungs this
- * file has never heard of.
- *
- * That is not a style choice; it is the fix for a real bug. The first version of
- * this module kept its own copy of the type ramp so it could recompute each
- * rung, and the copy was WRONG — it had `lg: 1rem` and `xl: 1.125rem` (16px and
- * 18px) while `tokens/typography.css` says `0.9375rem` and `1.0625rem` (15px and
- * 17px). Setting a preference of 1 — "leave it alone" — would have silently
- * resized two rungs of the published design. A second copy of a value is a
- * second source of truth, and it drifted before anyone used it.
- *
- * Because the knobs are plain multipliers, any OTHER ramp can opt in the same
- * way. @hanzo/gui compiles its own `--f-size-*` scale for the 1600-odd
- * `fontSize="$n"` call sites in the apps; an app that redeclares those as
- * `calc(<its px> * var(--type-scale, 1))` gets the same control with no change
- * at scale 1.
- *
- * It is a pure function on purpose: it maps a preference to custom properties
- * and returns them, touching no document. That is what lets an app, an embedded
- * preview and a server render apply it identically.
- */
-
-export type Density = "compact" | "default" | "comfortable";
-
-export interface Preference {
-  /** Multiplier on the type ramp. 1 is the published scale. */
-  type?: number;
-  density?: Density;
-  /** A CSS colour for --primary / --accent. Rejected unless it is one. */
-  accent?: string;
-}
-
-/**
- * The type multiplier is CLAMPED, and the bounds are not arbitrary.
- *
- * Below 0.85 the smallest rung (--text-xs, 11px) drops under 9.4px, which stops
- * being small and starts being unreadable — and a preference that lets someone
- * render their own tools illegible is a trap, not a choice. Above 1.4 the
- * chrome stops fitting its own containers: this app's builder header already
- * overlaps its actions below 1440px at scale 1.
- */
-export const TYPE_MIN = 0.85;
-export const TYPE_MAX = 1.4;
-
-/**
- * Density moves SPACING only, and its range is much tighter than type's.
- *
- * Spacing compounds: a page nests padding inside gap inside margin, so a 0.75
- * multiplier is already three-quarters of every one of those in sequence. Below
- * that, touch targets fall under the 44px floor `base.css` sets for coarse
- * pointers, and the control that promised comfort takes it away.
- */
-const DENSITY: Record<Density, number> = {
-  compact: 0.85,
-  default: 1,
-  comfortable: 1.15,
-};
-
-const clamp = (n: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, n));
-
-/** Trim to 4dp so a multiplier cannot emit a 17-digit float into a stylesheet. */
-const round = (n: number) => String(Math.round(n * 10000) / 10000);
-
-/**
- * Is this a colour, or is it something being smuggled into a style attribute?
- *
- * A preference is user input and its destination is CSS. `#fff`, `rgb(...)`,
- * `oklch(...)` and the bare keywords are colours; anything carrying a `;`, a
- * `}`, or a `url(` is trying to be a second declaration, and the answer is to
- * drop the axis rather than to sanitise a string into something plausible.
- */
-export function isColor(v: string): boolean {
-  const s = v.trim();
-  if (!s || s.length > 64) return false;
-  if (/[;{}()]/.test(s) && !/^(rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|color)\([^;{}]*\)$/i.test(s)) return false;
-  return (
-    /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(s) ||
-    /^(rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|color)\([^;{}]*\)$/i.test(s) ||
-    /^[a-z]{3,20}$/i.test(s)
-  );
-}
-
-/**
- * The custom properties a preference produces.
- *
- * Only the axes actually set appear, so an app can spread the result over
- * whatever it already has without a default silently overriding a brand.
- */
-export function vars(p: Preference): Record<string, string> {
-  const out: Record<string, string> = {};
-
-  if (typeof p.type === "number" && Number.isFinite(p.type)) {
-    out["--type-scale"] = round(clamp(p.type, TYPE_MIN, TYPE_MAX));
-  }
-
-  if (p.density && p.density in DENSITY) {
-    out["--density"] = round(DENSITY[p.density]);
-  }
-
-  if (p.accent && isColor(p.accent)) {
-    // Both names, because the ramp uses --primary for action surfaces and
-    // --accent for selection. One hue, stated once, landing on both.
-    out["--primary"] = p.accent.trim();
-    out["--accent"] = p.accent.trim();
-  }
-
-  return out;
-}
-
-/** `vars()` as a declaration block, for a <style> tag or an SSR inline. */
-export function css(p: Preference, selector = "html:root"): string {
-  const v = vars(p);
-  const keys = Object.keys(v);
-  if (!keys.length) return "";
-  return `${selector}{${keys.map((k) => `${k}:${v[k]}`).join(";")}}`;
-}