@ecoma-io/loom 0.1.0 → 0.2.0

package/dist/styles/global.css

@@ -38,6 +38,7 @@
   }
 
   html {
+    color-scheme: light dark;
     -webkit-font-smoothing: antialiased;
     -moz-osx-font-smoothing: grayscale;
     text-rendering: optimizeLegibility;
@@ -69,6 +70,56 @@
   font-family: var(--font-mono);
 }
 
+/* ---- Vendor corrections ----------------------------------------------------
+ * Rules that exist only because a dependency renders something Loom cannot
+ * reach from its own markup. Each one is coupled to that dependency's DOM, so
+ * each names what it couples to and is pinned by an end-to-end test.
+ *
+ * `StepperRoot` renders its own position announcement — "Step 3 of 5" — as a
+ * text node inside its render function. There is no prop, no slot and no
+ * attribute for it, so it is the one string in this library that a binding on
+ * Loom's side cannot replace, and it is English however the host is localised.
+ * `Stepper.vue` renders a translatable one beside it and this takes Reka's out
+ * of the accessibility tree, leaving exactly one region to announce a step
+ * change instead of two saying it in two languages.
+ *
+ * `display: none` rather than `aria-hidden="true"`, and the difference is not
+ * stylistic. `aria-hidden` on an element that is *already* a live region is not
+ * something the ARIA specification settles — implementations differ on whether
+ * a region that was live at announcement time is silenced by it — and a fix
+ * whose correctness cannot be checked without a screen reader on every platform
+ * is not a fix. Removal from the box tree is unambiguous: an element that
+ * generates no box is in no accessibility tree, so nothing announces it.
+ *
+ * Scoped to `[data-loom-stepper]`, so a host mounting Reka's Stepper directly
+ * keeps its own behaviour. `:not([data-loom-live])` is what spares Loom's — the
+ * two are told apart by what Loom marked, not by which came first, so neither
+ * a change in Reka's render order nor one in Loom's can silence the wrong one. */
+[data-loom-stepper] > [role="status"]:not([data-loom-live]) {
+  display: none;
+}
+
+/* ---- PWA window controls overlay ------------------------------------------
+ * When a PWA is installed and the `window-controls-overlay` feature is visible,
+ * the browser draws native minimize/maximize/close buttons over the app's title
+ * bar. The app must leave space for them. This is a PWA concern (not Electron
+ * or Tauri, which handle their own chrome), and it is CSS-only — no JavaScript
+ * runtime dependency.
+ *
+ * The overlay region is exposed through `env(titlebar-area-x)` and friends.
+ * The `[data-loom-titlebar]` attribute is set by TitleBar, which knows its own
+ * layout. When the overlay is active, the brand cluster's left padding expands
+ * to clear the native controls on the left edge (same corner as macOS), and
+ * the drag region continues to work over the full bar width. */
+@supports (window-controls-overlay: visible) {
+  [data-loom-titlebar] {
+    /* Narrow the drag spacer so the title text is not pushed too far right.
+     * The brand cluster already handles its own left offset via the platform
+     * prop; this rule is for PWA installs where the host did not set macOS. */
+    padding-left: env(titlebar-area-x, 0px);
+  }
+}
+
 /* ---- The motion keyframe library ------------------------------------------
  * Named and reusable; `theme.css` maps each to an `animate-*` utility. All of
  * them are short and purposeful, and nothing loops for decoration except the
@@ -109,36 +160,84 @@
   }
 }
 
-@keyframes shimmer {
+/* ---- The exits. Each mirrors the entrance above it, and the pairing is the
+ * point: a surface that rose 4px on the way in falls 4px on the way out rather
+ * than dissolving in place, so the eye reads one gesture reversed instead of
+ * two unrelated ones. `theme.css` carries the timing argument for why they are
+ * not simply the entrances run backwards. */
+
+@keyframes fade-out {
   from {
-    background-position: -180% 0;
+    opacity: 1;
   }
   to {
-    background-position: 180% 0;
+    opacity: 0;
+  }
+}
+
+@keyframes fade-fall {
+  from {
+    opacity: 1;
+    transform: translateY(0);
+  }
+  to {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+}
+
+@keyframes scale-out {
+  from {
+    opacity: 1;
+    transform: scale(1);
+  }
+  to {
+    opacity: 0;
+    transform: scale(0.97);
+  }
+}
+
+/* An edge-anchored panel leaving along its own axis.
+ *
+ * These animate `translate`, not `transform`, and the distinction is the whole
+ * reason they are usable: Reka writes a live swipe onto a drawer as `transform`
+ * and leaves the rendering to the component, so a keyframe on `transform` would
+ * overwrite a gesture mid-drag. On `translate` the two properties compose, the
+ * same way the entry `@starting-style` transition already does.
+ *
+ * Only the `to` frame is declared. The implicit `from` is the element's own
+ * computed value, so a panel that is already part-way out under a finger leaves
+ * from where it actually sits rather than snapping back to the origin first. */
+@keyframes slide-out-to-left {
+  to {
+    translate: -100% 0;
   }
 }
 
-/* Conduct — "an agent is working": the weft's shuttle beat, a pulse keeping
- * time while the thread is carried across. This is Force 2's motion voice. */
-@keyframes conduct {
-  0%,
-  100% {
-    box-shadow: 0 0 0 0 transparent;
+@keyframes slide-out-to-right {
+  to {
+    translate: 100% 0;
   }
-  50% {
-    box-shadow: 0 0 0 4px color-mix(in oklab, var(--color-agent) 18%, transparent);
+}
+
+@keyframes slide-out-to-top {
+  to {
+    translate: 0 -100%;
   }
 }
 
-/* Seam-flow — a live seam: the warp↔weft boundary drifts while a human↔agent
- * collaboration is running. Apply to a `bg-seam` element with
- * `background-size: 200% 100%`, and stop it once the work settles. */
-@keyframes seam-flow {
+@keyframes slide-out-to-bottom {
+  to {
+    translate: 0 100%;
+  }
+}
+
+@keyframes shimmer {
   from {
-    background-position: 0% 0;
+    background-position: -180% 0;
   }
   to {
-    background-position: -200% 0;
+    background-position: 180% 0;
   }
 }
 

package/dist/styles/theme.contrast.test.ts

@@ -0,0 +1,460 @@
+import { readFile } from "node:fs/promises";
+import { describe, expect, it } from "vitest";
+
+// `import.meta.dirname` (Node 24) rather than `import.meta.url`, because the
+// file is rewritten by Vitest's transform — `new URL(…, import.meta.url)`
+// gets a bare path as its base and dies with a scheme error.
+const THEME_CSS = `${import.meta.dirname}/theme.css`;
+
+// ---- Token parsing ----------------------------------------------------------
+
+type TokenMap = Map<string, string>;
+
+/**
+ * Every `--name: value;` declaration inside a given block of CSS.
+ * The regex is intentionally simple: it matches any `--custom-property: …;`
+ * line, and `parseHsl` below validates the shape of the value.
+ */
+function extractDeclarations(block: string): TokenMap {
+  const entries = [...block.matchAll(/--([\w-]+):\s*([^;]+);/g)]
+    .map((m): readonly [string, string] | null => {
+      const name = m[1];
+      const value = m[2];
+      if (name === undefined || value === undefined) return null;
+      return [name, value.trim()] as const;
+    })
+    .filter((e): e is readonly [string, string] => e !== null);
+  return new Map(entries);
+}
+
+/**
+ * Read the light tokens from the `@theme static { }` block. The regex is
+ * lazy (`*?`) so it stops at the first closing `}` on its own line — the
+ * `@theme static` block itself — rather than reaching past it into the
+ * dark-theme overrides that follow.
+ */
+async function readLightTokens(): Promise<TokenMap> {
+  const css = await readFile(THEME_CSS, "utf8");
+  const block = /@theme static \{([\s\S]*?)\n\}/.exec(css)?.[1];
+  if (block === undefined) throw new Error(`${THEME_CSS}: no "@theme static {" block found.`);
+  return extractDeclarations(block);
+}
+
+/**
+ * Read the dark tokens from the `:root[data-theme="dark"] { }` block.
+ * Uses brace-depth counting to find the matching close brace, because the
+ * block may contain nested comments or multi-line values that a simple
+ * regex cannot handle.
+ *
+ * The marker `:root[data-theme="dark"] {` (with the opening brace) is used
+ * rather than just the selector string, because the file's header comment
+ * also mentions `:root[data-theme="dark"]` in prose — and a bare `indexOf`
+ * would find that first and then latch onto the wrong opening brace.
+ */
+async function readDarkTokens(): Promise<TokenMap> {
+  const css = await readFile(THEME_CSS, "utf8");
+  const marker = ':root[data-theme="dark"] {';
+  const start = css.indexOf(marker);
+  if (start === -1) throw new Error(`${THEME_CSS}: no dark theme block found.`);
+
+  const openBrace = start + marker.length - 1;
+  if (openBrace === -1) throw new Error(`${THEME_CSS}: dark theme block has no opening brace.`);
+
+  let depth = 0;
+  let end = -1;
+  for (let i = openBrace; i < css.length; i++) {
+    if (css[i] === "{") depth++;
+    else if (css[i] === "}") {
+      depth--;
+      if (depth === 0) {
+        end = i;
+        break;
+      }
+    }
+  }
+  if (end === -1) throw new Error(`${THEME_CSS}: dark theme block is never closed.`);
+
+  return extractDeclarations(css.slice(openBrace + 1, end));
+}
+
+// ---- Colour math ------------------------------------------------------------
+
+interface Rgb {
+  readonly r: number;
+  readonly g: number;
+  readonly b: number;
+  readonly a: number;
+}
+
+/**
+ * Parse `hsl(H S% L%)` and the `/ alpha` form. Returns null for values
+ * that are not a single HSL colour (shadows, durations, etc.).
+ */
+function parseHsl(value: string): Rgb | null {
+  const match =
+    /^hsl\(\s*(\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)%\s+(\d+(?:\.\d+)?)%\s*\)$/.exec(value) ??
+    /^hsl\(\s*(\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)%\s+(\d+(?:\.\d+)?)%\s*\/\s*(\d+(?:\.\d+)?)%\s*\)$/.exec(
+      value,
+    );
+  if (!match) return null;
+  const h = Number(match[1]);
+  const s = Number(match[2]) / 100;
+  const l = Number(match[3]) / 100;
+  const a = match[4] === undefined ? 1 : Number(match[4]) / 100;
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const hPrime = h / 60;
+  const x = c * (1 - Math.abs((hPrime % 2) - 1));
+  const m = l - c / 2;
+  let rgb: [number, number, number];
+  if (hPrime < 1) rgb = [c, x, 0];
+  else if (hPrime < 2) rgb = [x, c, 0];
+  else if (hPrime < 3) rgb = [0, c, x];
+  else if (hPrime < 4) rgb = [0, x, c];
+  else if (hPrime < 5) rgb = [x, 0, c];
+  else rgb = [c, 0, x];
+  return {
+    r: Math.round((rgb[0] + m) * 255),
+    g: Math.round((rgb[1] + m) * 255),
+    b: Math.round((rgb[2] + m) * 255),
+    a,
+  };
+}
+
+function linear(v: number): number {
+  return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+}
+
+function luminance(c: Rgb): number {
+  return 0.2126 * linear(c.r / 255) + 0.7152 * linear(c.g / 255) + 0.0722 * linear(c.b / 255);
+}
+
+function contrastRatio(a: Rgb, b: Rgb): number {
+  const la = luminance(a);
+  const lb = luminance(b);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+/**
+ * Resolve a token name to an opaque HSL colour, or throw. A missing or
+ * non-HSL token is a structural defect the test must not silently skip.
+ */
+function colorOf(tokens: TokenMap, name: string, theme: string): Rgb {
+  const value = tokens.get(name);
+  const color = value === undefined ? null : parseHsl(value);
+  if (!color) throw new Error(`"${name}" is not an opaque hsl token in the ${theme} theme`);
+  if (color.a !== 1) throw new Error(`"${name}" carries an alpha; its ratio depends on the page`);
+  return color;
+}
+
+// ---- Contrast floors --------------------------------------------------------
+
+/** WCAG 1.4.3 AA for normal text. */
+const TEXT_FLOOR = 4.5;
+/** WCAG 1.4.11 AA for graphical objects and UI components. */
+const GRAPHICAL_FLOOR = 3;
+
+// ---- Pairings to verify -----------------------------------------------------
+// Each pairing names a foreground (text/graphical) token against a background
+// token. The same pairs are checked for both themes.
+
+interface Pairing {
+  readonly fg: string;
+  readonly bg: string;
+  readonly floor: number;
+  readonly label: string;
+}
+
+const TEXT_PAIRINGS: Pairing[] = [
+  // Structural text-on-background
+  { fg: "color-foreground", bg: "color-background", floor: TEXT_FLOOR, label: "body text" },
+  { fg: "color-foreground", bg: "color-card", floor: TEXT_FLOOR, label: "card text" },
+  { fg: "color-foreground", bg: "color-popover", floor: TEXT_FLOOR, label: "popover text" },
+  {
+    fg: "color-card-foreground",
+    bg: "color-card",
+    floor: TEXT_FLOOR,
+    label: "card-foreground on card",
+  },
+  {
+    fg: "color-popover-foreground",
+    bg: "color-popover",
+    floor: TEXT_FLOOR,
+    label: "popover-foreground on popover",
+  },
+  {
+    fg: "color-muted-foreground",
+    bg: "color-background",
+    floor: TEXT_FLOOR,
+    label: "secondary text",
+  },
+  {
+    fg: "color-muted-foreground",
+    bg: "color-card",
+    floor: TEXT_FLOOR,
+    label: "secondary text on card",
+  },
+  {
+    fg: "color-muted-foreground",
+    bg: "color-muted",
+    floor: TEXT_FLOOR,
+    label: "secondary text on muted",
+  },
+  { fg: "color-subtle-foreground", bg: "color-subtle", floor: TEXT_FLOOR, label: "subtle text" },
+  {
+    fg: "color-secondary-foreground",
+    bg: "color-secondary",
+    floor: TEXT_FLOOR,
+    label: "secondary text on secondary",
+  },
+
+  // Action colour labels
+  {
+    fg: "color-primary-foreground",
+    bg: "color-primary",
+    floor: TEXT_FLOOR,
+    label: "primary button label",
+  },
+  {
+    fg: "color-accent-foreground",
+    bg: "color-accent",
+    floor: TEXT_FLOOR,
+    label: "accent button label",
+  },
+
+  // Functional colour labels
+  {
+    fg: "color-destructive-foreground",
+    bg: "color-destructive",
+    floor: TEXT_FLOOR,
+    label: "destructive button label",
+  },
+  {
+    fg: "color-success-foreground",
+    bg: "color-success",
+    floor: TEXT_FLOOR,
+    label: "success label",
+  },
+  {
+    fg: "color-warning-foreground",
+    bg: "color-warning",
+    floor: TEXT_FLOOR,
+    label: "warning label",
+  },
+  { fg: "color-info-foreground", bg: "color-info", floor: TEXT_FLOOR, label: "info label" },
+
+  // Text on muted surfaces (foreground token, which should always be readable)
+  {
+    fg: "color-foreground",
+    bg: "color-primary-muted",
+    floor: TEXT_FLOOR,
+    label: "text on primary-muted",
+  },
+  {
+    fg: "color-foreground",
+    bg: "color-destructive-muted",
+    floor: TEXT_FLOOR,
+    label: "text on destructive-muted",
+  },
+  {
+    fg: "color-foreground",
+    bg: "color-success-muted",
+    floor: TEXT_FLOOR,
+    label: "text on success-muted",
+  },
+  {
+    fg: "color-foreground",
+    bg: "color-warning-muted",
+    floor: TEXT_FLOOR,
+    label: "text on warning-muted",
+  },
+  {
+    fg: "color-foreground",
+    bg: "color-info-muted",
+    floor: TEXT_FLOOR,
+    label: "text on info-muted",
+  },
+];
+
+const GRAPHICAL_PAIRINGS: Pairing[] = [
+  // Graphical-object tokens
+  {
+    fg: "color-muted-foreground-soft",
+    bg: "color-background",
+    floor: GRAPHICAL_FLOOR,
+    label: "muted-soft on background",
+  },
+  {
+    fg: "color-muted-foreground-soft",
+    bg: "color-card",
+    floor: GRAPHICAL_FLOOR,
+    label: "muted-soft on card",
+  },
+
+  // Functional colours as graphical indicators on their surfaces
+  {
+    fg: "color-primary",
+    bg: "color-background",
+    floor: GRAPHICAL_FLOOR,
+    label: "primary indicator",
+  },
+  { fg: "color-accent", bg: "color-background", floor: GRAPHICAL_FLOOR, label: "accent indicator" },
+  {
+    fg: "color-destructive",
+    bg: "color-background",
+    floor: GRAPHICAL_FLOOR,
+    label: "destructive indicator",
+  },
+  {
+    fg: "color-success",
+    bg: "color-background",
+    floor: GRAPHICAL_FLOOR,
+    label: "success indicator",
+  },
+  {
+    fg: "color-warning",
+    bg: "color-background",
+    floor: GRAPHICAL_FLOOR,
+    label: "warning indicator",
+  },
+  { fg: "color-info", bg: "color-background", floor: GRAPHICAL_FLOOR, label: "info indicator" },
+
+  // Focus ring
+  { fg: "color-ring", bg: "color-background", floor: GRAPHICAL_FLOOR, label: "focus ring" },
+
+  // Functional hues on their own muted surface (icons, indicators)
+  {
+    fg: "color-primary",
+    bg: "color-primary-muted",
+    floor: GRAPHICAL_FLOOR,
+    label: "primary on primary-muted",
+  },
+  {
+    fg: "color-accent",
+    bg: "color-accent-muted",
+    floor: GRAPHICAL_FLOOR,
+    label: "accent on accent-muted",
+  },
+  {
+    fg: "color-destructive",
+    bg: "color-destructive-muted",
+    floor: GRAPHICAL_FLOOR,
+    label: "destructive on destructive-muted",
+  },
+  {
+    fg: "color-success",
+    bg: "color-success-muted",
+    floor: GRAPHICAL_FLOOR,
+    label: "success on success-muted",
+  },
+  {
+    fg: "color-warning",
+    bg: "color-warning-muted",
+    floor: GRAPHICAL_FLOOR,
+    label: "warning on warning-muted",
+  },
+  { fg: "color-info", bg: "color-info-muted", floor: GRAPHICAL_FLOOR, label: "info on info-muted" },
+];
+
+const ALL_PAIRINGS = [...TEXT_PAIRINGS, ...GRAPHICAL_PAIRINGS];
+
+// ---- Tests ------------------------------------------------------------------
+
+describe("Light theme contrast", () => {
+  it("meets the contrast floor for every structural pairing", async () => {
+    const tokens = await readLightTokens();
+    for (const { fg, bg, floor, label } of ALL_PAIRINGS) {
+      const fgColor = colorOf(tokens, fg, "light");
+      const bgColor = colorOf(tokens, bg, "light");
+      const cr = contrastRatio(fgColor, bgColor);
+      expect(
+        cr,
+        `${label}: ${fg} on ${bg} = ${cr.toFixed(2)}:1 (needs ${String(floor)})`,
+      ).toBeGreaterThanOrEqual(floor);
+    }
+  });
+});
+
+describe("Dark theme contrast", () => {
+  it("meets the contrast floor for every structural pairing", async () => {
+    const tokens = await readDarkTokens();
+    for (const { fg, bg, floor, label } of ALL_PAIRINGS) {
+      const fgColor = colorOf(tokens, fg, "dark");
+      const bgColor = colorOf(tokens, bg, "dark");
+      const cr = contrastRatio(fgColor, bgColor);
+      expect(
+        cr,
+        `${label}: ${fg} on ${bg} = ${cr.toFixed(2)}:1 (needs ${String(floor)})`,
+      ).toBeGreaterThanOrEqual(floor);
+    }
+  });
+});
+
+describe("Elevation hierarchy", () => {
+  it("light: sunken < background < card <= popover (by lightness)", async () => {
+    const tokens = await readLightTokens();
+    // In light mode, higher elevation = higher lightness
+    const sunkenL = luminance(colorOf(tokens, "color-sunken", "light"));
+    const backgroundL = luminance(colorOf(tokens, "color-background", "light"));
+    const cardL = luminance(colorOf(tokens, "color-card", "light"));
+    const popoverL = luminance(colorOf(tokens, "color-popover", "light"));
+    expect(sunkenL, "sunken < background").toBeLessThan(backgroundL);
+    expect(backgroundL, "background < card").toBeLessThan(cardL);
+    expect(cardL, "card <= popover").toBeLessThanOrEqual(popoverL);
+  });
+
+  it("dark: sunken < background < card < popover (by lightness)", async () => {
+    const tokens = await readDarkTokens();
+    // In dark mode, higher elevation = higher lightness (lighter background)
+    const sunkenL = luminance(colorOf(tokens, "color-sunken", "dark"));
+    const backgroundL = luminance(colorOf(tokens, "color-background", "dark"));
+    const cardL = luminance(colorOf(tokens, "color-card", "dark"));
+    const popoverL = luminance(colorOf(tokens, "color-popover", "dark"));
+    expect(sunkenL, "sunken < background").toBeLessThan(backgroundL);
+    expect(backgroundL, "background < card").toBeLessThan(cardL);
+    expect(cardL, "card < popover").toBeLessThan(popoverL);
+  });
+});
+
+describe("Text prominence hierarchy", () => {
+  it("light: muted-foreground-soft < muted-foreground < foreground (by luminance)", async () => {
+    const tokens = await readLightTokens();
+    // In light mode, less prominent text = higher luminance (lighter on light)
+    const softL = luminance(colorOf(tokens, "color-muted-foreground-soft", "light"));
+    const mutedL = luminance(colorOf(tokens, "color-muted-foreground", "light"));
+    const fgL = luminance(colorOf(tokens, "color-foreground", "light"));
+    expect(softL, "soft > muted (lighter = less prominent)").toBeGreaterThan(mutedL);
+    expect(mutedL, "muted > foreground (lighter = less prominent)").toBeGreaterThan(fgL);
+  });
+
+  it("dark: muted-foreground-soft < muted-foreground < foreground (by luminance)", async () => {
+    const tokens = await readDarkTokens();
+    // In dark mode, less prominent text = lower luminance (darker on dark)
+    const softL = luminance(colorOf(tokens, "color-muted-foreground-soft", "dark"));
+    const mutedL = luminance(colorOf(tokens, "color-muted-foreground", "dark"));
+    const fgL = luminance(colorOf(tokens, "color-foreground", "dark"));
+    expect(softL, "soft < muted (darker = less prominent)").toBeLessThan(mutedL);
+    expect(mutedL, "muted < foreground (darker = less prominent)").toBeLessThan(fgL);
+  });
+});
+
+describe("Border visibility hierarchy", () => {
+  it("light: border < input < border-strong (by luminance)", async () => {
+    const tokens = await readLightTokens();
+    // In light mode, more visible border = lower luminance (darker on light)
+    const borderL = luminance(colorOf(tokens, "color-border", "light"));
+    const inputL = luminance(colorOf(tokens, "color-input", "light"));
+    const strongL = luminance(colorOf(tokens, "color-border-strong", "light"));
+    expect(borderL, "border > input (lighter = less visible)").toBeGreaterThan(inputL);
+    expect(inputL, "input > strong (lighter = less visible)").toBeGreaterThan(strongL);
+  });
+
+  it("dark: border < input < border-strong (by luminance)", async () => {
+    const tokens = await readDarkTokens();
+    // In dark mode, more visible border = higher luminance (lighter on dark)
+    const borderL = luminance(colorOf(tokens, "color-border", "dark"));
+    const inputL = luminance(colorOf(tokens, "color-input", "dark"));
+    const strongL = luminance(colorOf(tokens, "color-border-strong", "dark"));
+    expect(borderL, "border < input (darker = less visible)").toBeLessThan(inputL);
+    expect(inputL, "input < strong (darker = less visible)").toBeLessThan(strongL);
+  });
+});