actual-css 0.11.0 → 0.12.0

package/src/css/forms/native.css

@@ -19,7 +19,11 @@
      the whole control, not just the filename text. */
   min-block-size: var(--control-size);
   padding-block: var(--space-10);
-  padding-block: max(var(--space-10), calc((var(--control-size) - 1lh) / 2));
+  /* Border-box height: both borders come out of the padding, as on .btn. */
+  padding-block: max(
+    var(--space-10),
+    calc((var(--control-size) - 1lh - 2 * var(--border-width)) / 2)
+  );
   padding-inline: var(--space-20);
   border: var(--border-width) solid var(--border);
   border-radius: var(--radius-sm);

package/src/css/layout/cluster.css

@@ -9,6 +9,7 @@
  * --cluster-wrap
  *
  * Child contract: direct-child margins are reset, spacing comes from --gap.
+ * A ul/ol/menu keeps its semantics but loses list chrome (see below).
  */
 .cluster {
   display: flex;
@@ -22,3 +23,13 @@
 .cluster > * {
   margin: 0;
 }
+
+/* Horizontal, wrapping layout is incompatible with list markers and native
+   indentation: a ul/ol/menu applied with .cluster stays a list in the DOM, but
+   its visual chrome would be accidental. .stack intentionally leaves this
+   alone — a vertical list can keep its numbers. */
+:where(ul, ol, menu).cluster {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}

package/src/css/layout/topbar.css

@@ -1,8 +1,9 @@
 /*
  * Sticky, frosted top bar shell for app/dashboard shells (persistent
  * sidebar + topbar layouts). Owns positioning, stacking, and the frosted
- * background only — row content (search, breadcrumb, actions) stays local
- * to the page.
+ * background; it also lays its children out as a default row that a layout
+ * primitive on the same element (such as .cluster) replaces. Row content
+ * (search, breadcrumb, actions) stays local to the page.
  *
  * Docs: docs/pages/layout/topbar.md
  *
@@ -16,16 +17,21 @@
   inset-block-start: 0;
   z-index: var(--z-sticky);
   isolation: isolate;
-  display: flex;
-  flex-direction: row;
-  align-items: center;
-  gap: var(--gap);
   padding-block: var(--space-30);
   padding-inline: var(--space-40);
   border-block-end: var(--border-width) solid var(--border);
   background: var(--surface);
 }
 
+/* The row is a default at zero specificity: .topbar and the primitives share
+   layout/, so at class weight their file order alone would pick the winner. */
+:where(.topbar) {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: var(--gap);
+}
+
 /* Both conditions are required: the translucent background contains var(),
    so a browser with backdrop-filter but not color-mix (e.g. Safari < 16.2)
    would accept the declaration at parse time, fail it at computed-value

package/src/css/utilities/base.css

@@ -74,6 +74,11 @@
   align-items: end;
 }
 
+.items-baseline {
+  --items-align: baseline;
+  align-items: baseline;
+}
+
 .muted {
   color: var(--text-muted);
 }

package/src/css/utilities/extra.css

@@ -10,9 +10,6 @@
  * - utilities consume the current context instead of defining their own -sm/-lg scale.
  * - optional utilities extend core utilities, they do not re-express them.
  * - follow verbose .{property}-{value} naming.
- *
- * Internal:
- * --cluster-justify (local relay consumed by .cluster)
  */
 
 /* Display */
@@ -87,23 +84,22 @@
   flex-wrap: nowrap;
 }
 
+/* The property is written directly, never relayed through the cluster hook:
+   a relay would inherit into every .cluster nested inside. Utilities load last,
+   so the direct declaration already beats .cluster at equal specificity. */
 .justify-content-start {
-  --cluster-justify: flex-start;
   justify-content: flex-start;
 }
 
 .justify-content-center {
-  --cluster-justify: center;
   justify-content: center;
 }
 
 .justify-content-end {
-  --cluster-justify: flex-end;
   justify-content: flex-end;
 }
 
 .justify-content-space-between {
-  --cluster-justify: space-between;
   justify-content: space-between;
 }
 

package/src/tooling/color.js

@@ -0,0 +1,65 @@
+/*
+ * sRGB color math shared by `actual-css contrast`, the repository reports and
+ * the browser tests.
+ * Colors are [r, g, b, a] byte arrays as returned by RASTERIZE in the page;
+ * plain [r, g, b] triplets are accepted and treated as opaque.
+ */
+
+/*
+ * Page-side rasterizer, injected into a view.evaluate() program as
+ * `const rgba = ${RASTERIZE};`. getComputedStyle returns color-mix() and
+ * light-dark() results as oklab() or color(), so a 1x1 canvas turns any
+ * computed color into sRGB bytes. Alpha is kept so contrast() can refuse a
+ * translucent color instead of measuring it as if it were opaque.
+ */
+export const RASTERIZE = `(() => {
+  const canvas = Object.assign(document.createElement("canvas"), { width: 1, height: 1 });
+  const ctx = canvas.getContext("2d", { willReadFrequently: true });
+  return (value) => {
+    ctx.clearRect(0, 0, 1, 1);
+    ctx.fillStyle = value;
+    ctx.fillRect(0, 0, 1, 1);
+    return [...ctx.getImageData(0, 0, 1, 1).data];
+  };
+})()`;
+
+/* 0.04045 is the sRGB (IEC 61966-2-1) threshold and the one WCAG 2.2 defines.
+   WCAG 2.0/2.1 printed 0.03928, from an older sRGB draft. No 8-bit channel
+   falls between the two (10/255 = 0.0392, 11/255 = 0.0431), so ratios are
+   identical either way. */
+const toLinear = (byte) => {
+  const c = byte / 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+};
+
+/* WCAG 2 relative luminance. */
+export const luminance = ([r, g, b]) =>
+  0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+
+/* WCAG 2 contrast ratio, 1 to 21. The formula has no alpha: a translucent
+   color must be composited over its real background before it is measured. */
+export function contrast(a, b) {
+  if (a[3] < 255 || b[3] < 255) {
+    throw new Error(`contrast() needs opaque colors, got [${a}] and [${b}]`);
+  }
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/* OKLCH of an sRGB color: L 0-1, C chroma, h degrees. */
+export function oklch([r, g, b]) {
+  const [lr, lg, lb] = [r, g, b].map(toLinear);
+  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+  const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+  const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+  const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+  return { L, C: Math.hypot(A, B), h: ((Math.atan2(B, A) * 180) / Math.PI + 360) % 360 };
+}
+
+/* Shortest arc between two hues, in degrees. */
+export const hueDistance = (a, b) => {
+  const d = Math.abs(a - b) % 360;
+  return d > 180 ? 360 - d : d;
+};

package/src/tooling/design-components.js

@@ -0,0 +1,286 @@
+/*
+ * Design-tool component export: renders every variant of a component in the
+ * theme's islands, measures the computed box, and binds each value to a token.
+ *
+ * Nothing is modelled: the browser answers what a `.btn.danger.soft.lg`
+ * looks like, so a theme's overrides and every derived value come along for
+ * free. A component is described as one box and its texts — the box's layout
+ * (hug or fill, fixed or content height, row or column, centred or not) is
+ * read from the rendered element too, so the plugin only replays it.
+ *
+ * Colors bind to the theme token that paints the same value in every mode; a
+ * color no theme token paints (a soft fill, a soft border) becomes a recipe
+ * token named `<variant>-<intent>-<role>`, so the design tool still switches
+ * it with the mode. Lengths stay measured px: binding them too (radius,
+ * padding, height, type — about 1,800 bindings over 221 variants) froze
+ * Penpot, and a theme's own lengths already arrive through the measurement.
+ */
+import { hexOf, inPage, parseSrgb } from "./design-tokens.js";
+
+/* Every list starts with its default: the first combination is the one a
+   design tool picks for a new instance. */
+const INTENTS = ["default", "primary", "secondary", "success", "warning", "danger", "neutral"];
+const SIZES = ["md", "sm", "lg"];
+const BUTTON_VARIANTS = ["solid", "soft", "outline", "surface", "ghost", "link"];
+
+const classes = (...names) => names.filter((n) => n && n !== "default" && n !== "md").join(" ");
+
+/* One entry per design-tool component. Every combination of `properties` is
+   measured and built, and each property becomes a variant property, in the
+   order given — Intent, Variant, Size, the way an author stacks the classes.
+   `html` renders one combination: classes are the public API, so the markup
+   is what an author writes. "default" and "md" add no class. A soft-by-default
+   component (badge, alert) still measures its default as `soft`, so its
+   recipes share the button's names (`soft-danger-bg`) instead of doubling
+   them; the recipe guard below fails if the two ever paint differently. */
+export const COMPONENTS = [
+  {
+    name: "Button",
+    properties: { Intent: INTENTS, Variant: BUTTON_VARIANTS, Size: SIZES },
+    html: ({ Intent, Variant, Size }) =>
+      `<button class="btn ${classes(Intent, Variant, Size)}" type="button">Button</button>`,
+  },
+  {
+    name: "Input",
+    properties: { Size: SIZES },
+    html: ({ Size }) => `<input class="input ${classes(Size)}" value="Input" aria-label="Input">`,
+  },
+  {
+    name: "Badge",
+    properties: { Intent: INTENTS, Variant: ["soft", "solid", "outline"], Size: SIZES },
+    html: ({ Intent, Variant, Size }) =>
+      `<span class="badge ${classes(Intent, Variant, Size)}">Badge</span>`,
+  },
+  {
+    name: "Alert",
+    properties: { Intent: INTENTS, Variant: ["soft", "solid", "outline", "surface"] },
+    html: ({ Intent, Variant }) =>
+      `<div class="alert ${classes(Intent, Variant)}" role="status">Alert message</div>`,
+  },
+  {
+    name: "Card",
+    properties: {},
+    html: () => '<article class="card"><h3>Card title</h3><p>Card content goes here.</p></article>',
+  },
+];
+
+/* Wide enough for a card, narrow enough that a fill-width component (input,
+   alert) reads as a component rather than a page-wide bar. */
+const SPECIMEN_WIDTH = "20rem";
+
+/* Runs in the page: every specimen in every island, computed values only.
+   A specimen is one box plus its texts: the element's own text, an input's
+   value, or each child element (a card's title and body). */
+function measureSpecimens({ css, islands, specimens, width }) {
+  const style = document.createElement("style");
+  style.textContent = css;
+  document.head.append(style);
+  const probe = document.createElement("div");
+  document.body.append(probe);
+  const srgb = (value) => {
+    probe.style.color = `color-mix(in srgb, ${value}, ${value})`;
+    return getComputedStyle(probe).color;
+  };
+  const px = (value) => Number.parseFloat(value) || 0;
+
+  const text = (cs, rect, label) => ({
+    label,
+    width: rect.width,
+    height: rect.height,
+    color: srgb(cs.color),
+    fontSize: px(cs.fontSize),
+    fontWeight: Number(cs.fontWeight),
+    lineHeight: cs.lineHeight === "normal" ? 1.2 : px(cs.lineHeight) / px(cs.fontSize),
+    underline: cs.textDecorationLine.includes("underline"),
+  });
+
+  const texts = (el, cs, rect) => {
+    if (el instanceof HTMLInputElement) {
+      const inner = {
+        width:
+          rect.width -
+          px(cs.paddingLeft) -
+          px(cs.paddingRight) -
+          px(cs.borderLeftWidth) -
+          px(cs.borderRightWidth),
+        height: cs.lineHeight === "normal" ? px(cs.fontSize) * 1.2 : px(cs.lineHeight),
+      };
+      return [{ ...text(cs, inner, el.value), rect: inner }];
+    }
+    if (el.children.length > 0) {
+      return [...el.children].map((child) => {
+        const box = child.getBoundingClientRect();
+        return { ...text(getComputedStyle(child), box, child.textContent.trim()), rect: box };
+      });
+    }
+    const range = document.createRange();
+    range.selectNodeContents(el);
+    const box = range.getBoundingClientRect();
+    return [{ ...text(cs, box, el.textContent.trim()), rect: box }];
+  };
+
+  return islands.map(({ attribute, scheme }) => {
+    const island = document.createElement("div");
+    if (attribute) island.dataset.theme = attribute;
+    if (scheme) island.style.colorScheme = scheme;
+    // What body gives the page: an island does not reset `color`, and the
+    // currentColor variants (outline, ghost, link) would otherwise inherit
+    // the ink of body's scheme instead of this island's.
+    island.style.color = "var(--text)";
+    island.innerHTML = specimens
+      .map((html) => `<div style="inline-size: ${width}">${html}</div>`)
+      .join("");
+    document.body.append(island);
+
+    const measured = [...island.children].map((wrap) => {
+      const el = wrap.firstElementChild;
+      const cs = getComputedStyle(el);
+      const rect = el.getBoundingClientRect();
+      const children = texts(el, cs, rect);
+      const flex = cs.display.includes("flex");
+      const column = flex ? cs.flexDirection.startsWith("column") : children.length > 1;
+      const [a, b] = children;
+      return {
+        width: rect.width,
+        height: rect.height,
+        // Narrower than its container: the component sizes to its content.
+        hug: rect.width < wrap.getBoundingClientRect().width - 0.5,
+        // A minimum height is a control size; otherwise content decides.
+        fixedHeight: px(cs.minHeight) > 0,
+        dir: column ? "column" : "row",
+        justify: cs.justifyContent === "center" ? "center" : "start",
+        gap: b ? Math.max(0, column ? b.rect.top - a.rect.bottom : b.rect.left - a.rect.right) : 0,
+        padding: {
+          top: px(cs.paddingTop),
+          right: px(cs.paddingRight),
+          bottom: px(cs.paddingBottom),
+          left: px(cs.paddingLeft),
+        },
+        borderWidth: px(cs.borderTopWidth),
+        radius: px(cs.borderTopLeftRadius),
+        bg: srgb(cs.backgroundColor),
+        border: srgb(cs.borderTopColor),
+        children: children.map(({ rect: _, ...child }) => child),
+      };
+    });
+    island.remove();
+    return measured;
+  });
+}
+
+function combinations(properties) {
+  return Object.entries(properties).reduce(
+    (acc, [name, values]) => acc.flatMap((props) => values.map((v) => ({ ...props, [name]: v }))),
+    [{}],
+  );
+}
+
+/*
+ * Measures `components` for the islands of a resolved theme. Returns the
+ * recipe colors per mode (same shape as linked theme colors) and the spec a
+ * design-tool plugin builds from: per variant, the box and its texts in px,
+ * and each color's value for the first mode plus the token it binds to.
+ */
+export async function measureComponents({ css, resolved, linked, components = COMPONENTS }) {
+  const modes = Object.keys(resolved.modes);
+  const specimens = components.flatMap((component) =>
+    combinations(component.properties).map((props) => ({ component, props })),
+  );
+  const measured = await inPage(measureSpecimens, {
+    css,
+    islands: resolved.islands,
+    specimens: specimens.map(({ component, props }) => component.html(props)),
+    width: SPECIMEN_WIDTH,
+  });
+
+  // Theme colors keyed by their value in every mode; aliases are skipped so a
+  // color binds to the concrete token (`text`, not `heading`).
+  const themeByValue = new Map();
+  for (const name of Object.keys(linked.modes[modes[0]])) {
+    if (linked.modes[modes[0]][name].alias) continue;
+    const key = modes.map((mode) => hexOf(resolved.modes[mode][name])).join(" ");
+    if (!themeByValue.has(key)) themeByValue.set(key, name);
+  }
+
+  const recipes = Object.fromEntries(modes.map((mode) => [mode, {}]));
+  // `perMode` is one computed color per mode.
+  const bindColor = (perMode, recipeName) => {
+    const colors = perMode.map(parseSrgb);
+    if (colors.every((c) => c.alpha === 0)) return null;
+    const hexes = colors.map(hexOf);
+    let token = themeByValue.get(hexes.join(" "));
+    if (!token) {
+      token = recipeName;
+      modes.forEach((mode, m) => {
+        const known = recipes[mode][token];
+        // A recipe name carries no size and no component: if two of them
+        // ever paint different colors, the name has to grow a dimension.
+        if (known && known.hex !== hexes[m]) {
+          throw new Error(`Recipe ${token} paints ${known.hex} and ${hexes[m]} in ${mode}`);
+        }
+        recipes[mode][token] = { color: colors[m], hex: hexes[m] };
+      });
+    }
+    const [first] = colors;
+    return { hex: hexOf({ ...first, alpha: 1 }), opacity: first.alpha, token };
+  };
+
+  const describe = (component, props, i) => {
+    const [m] = measured.map((island) => island[i]);
+    const each = (read) => measured.map((island) => read(island[i]));
+    // Intent and variant name the recipe; a component with neither uses its
+    // own name, so two plain components never share one.
+    const scope = [props.Variant, props.Intent].filter(Boolean);
+    const recipe = (role) =>
+      [...(scope.length ? scope : [component.name]), role].join("-").toLowerCase();
+    return {
+      props,
+      box: {
+        width: Math.ceil(m.width),
+        height: m.height,
+        hug: m.hug,
+        fixedHeight: m.fixedHeight,
+        dir: m.dir,
+        justify: m.justify,
+        gap: m.gap,
+        padding: m.padding,
+        radius: m.radius,
+        borderWidth: m.borderWidth,
+        fill: bindColor(
+          each((s) => s.bg),
+          recipe("bg"),
+        ),
+        stroke:
+          m.borderWidth > 0
+            ? bindColor(
+                each((s) => s.border),
+                recipe("border"),
+              )
+            : null,
+      },
+      texts: m.children.map((child, c) => ({
+        label: child.label,
+        width: Math.ceil(child.width),
+        height: Math.ceil(child.height),
+        lineHeight: Math.round(child.lineHeight * 1000) / 1000,
+        fontSize: child.fontSize,
+        fontWeight: child.fontWeight,
+        underline: child.underline,
+        color: bindColor(
+          each((s) => s.children[c].color),
+          recipe(c === 0 ? "fg" : `fg-${c + 1}`),
+        ),
+      })),
+    };
+  };
+
+  const spec = components.map((component) => ({
+    name: component.name,
+    properties: Object.keys(component.properties),
+    variants: specimens.flatMap(({ component: owner, props }, i) =>
+      owner === component ? [describe(component, props, i)] : [],
+    ),
+  }));
+
+  return { recipes, spec: { components: spec } };
+}

package/src/tooling/design-export.js

@@ -0,0 +1,69 @@
+/*
+ * Design-tool export for one theme: Figma and Penpot tokens, the measured
+ * component spec, and the Penpot plugin that builds it. Shared by the CLI
+ * (`actual-css design`) and the repository script (`bun run export:design`).
+ * Bun only: values are read in headless Chrome through Bun.WebView.
+ */
+import { copyFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { inlineImports } from "./css-bundle.js";
+import { measureComponents } from "./design-components.js";
+import {
+  coreTokenCss,
+  linkTokens,
+  resolveTokens,
+  themeNameOf,
+  toFigma,
+  toPenpot,
+} from "./design-tokens.js";
+
+const FRAMEWORK = fileURLToPath(new URL("../css/actual.full.css", import.meta.url));
+const PLUGIN = fileURLToPath(new URL("./penpot-plugin/", import.meta.url));
+
+/*
+ * Writes, under `out`:
+ *   figma/foundations.tokens.json, figma/<scheme>.tokens.json
+ *   penpot/tokens.json
+ *   penpot/plugin/ (manifest.json, plugin.js, ui.html, spec.json)
+ * Without `themeFile`, exports the default theme. `name` overrides the
+ * data-theme name read from the theme file. Returns the written paths.
+ */
+export async function exportDesign({ themeFile, name, out }) {
+  const themeCss = themeFile ? await inlineImports(themeFile) : "";
+  const theme = themeFile ? (name ?? themeNameOf(themeCss)) : null;
+  const css = `${await inlineImports(FRAMEWORK)}\n${themeCss}`;
+
+  const resolved = await resolveTokens({
+    css,
+    theme,
+    aliasSources: [await coreTokenCss(), themeFile ? await readFile(themeFile, "utf8") : ""],
+  });
+  const linked = linkTokens(resolved);
+  const { recipes, spec } = await measureComponents({ css, resolved, linked });
+
+  const documents = {
+    ...Object.fromEntries(
+      Object.entries(toFigma(linked, recipes)).map(([file, doc]) => [
+        `figma/${file}.tokens.json`,
+        doc,
+      ]),
+    ),
+    "penpot/tokens.json": toPenpot(linked, recipes),
+    "penpot/plugin/spec.json": spec,
+  };
+
+  const written = [];
+  for (const [path, doc] of Object.entries(documents)) {
+    const file = join(out, path);
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, `${JSON.stringify(doc, null, 2)}\n`);
+    written.push(file);
+  }
+  for (const entry of await readdir(PLUGIN)) {
+    const file = join(out, "penpot", "plugin", entry);
+    await copyFile(join(PLUGIN, entry), file);
+    written.push(file);
+  }
+  return written;
+}