actual-css 0.12.0 → 0.13.0

package/src/js/inline-visible.js

@@ -0,0 +1,54 @@
+/*
+ * Brings a target into view inside one horizontal scrollport — internal, not
+ * a package export. Tabs call it at connect, so a selected tab rendered
+ * off-screen starts visible, and on every selection.
+ *
+ * Contract:
+ * - Scrolls `container` only. scrollIntoView() would also scroll ancestors and
+ *   the page, so a strip below the fold would yank the reader down to it.
+ * - Horizontal, nearest only: a target already visible stays put; one that
+ *   overflows a single edge moves the minimum to show that edge; one wider
+ *   than the visible area that covers it on both sides stays put too.
+ * - The visible area is the scrollport minus its computed scroll-padding, the
+ *   native vocabulary also honoured by focus scrolling: a component that
+ *   keeps an edge clear (a strip's focus line) declares it there, not here.
+ * - The delta comes from physical rects and goes through scrollBy(), so RTL
+ *   needs no scrollLeft sign convention.
+ * - Rects are in transformed pixels; clientWidth, scroll-padding and scrollBy()
+ *   are in layout pixels. The strip's own scale converts between them, so a
+ *   strip under transform: scale() reveals the same item. Rotation is out of
+ *   scope.
+ * - Inline axis only: the block scroll position is left as it is. Callers are
+ *   one-row strips whose block axis does not scroll.
+ * - Requires a laid-out, visible container and target. A strip hidden at
+ *   connect (inside a closed dialog or drawer) or a target without a box (a
+ *   current link inside a closed flyout) gets a no-op, not a deferred retry.
+ */
+
+// Sub-pixel layout must not read as overflow and nudge an aligned strip.
+const TOLERANCE = 1;
+
+// scroll-padding computes to `auto`, a length, or a percentage of the
+// scrollport; auto adds no inset. A calc() mixing the two reads as none.
+const inset = (value, scrollport) =>
+  value.endsWith("%")
+    ? (Number.parseFloat(value) * scrollport) / 100
+    : Number.parseFloat(value) || 0;
+
+export function ensureInlineVisible(container, target) {
+  const width = container?.clientWidth;
+  if (!width || !target?.getClientRects().length) return;
+  const style = getComputedStyle(container);
+  const box = container.getBoundingClientRect();
+  const scale = box.width / container.offsetWidth || 1;
+  const start = box.left + (container.clientLeft + inset(style.scrollPaddingLeft, width)) * scale;
+  const end =
+    box.left + (container.clientLeft + width - inset(style.scrollPaddingRight, width)) * scale;
+  const rect = target.getBoundingClientRect();
+  const before = rect.left < start - TOLERANCE;
+  const after = rect.right > end + TOLERANCE;
+  if (before === after) return;
+  const delta = before ? rect.left - start : rect.right - end;
+  // A placement, not a transition: it must not animate under scroll-behavior: smooth.
+  container.scrollBy({ left: delta / scale, behavior: "instant" });
+}

package/src/js/parsed.js

@@ -0,0 +1,21 @@
+/*
+ * Runs a callback once the document has finished parsing — internal, not a
+ * package export.
+ *
+ * The runtime connects an element as soon as the parser inserts it. With a
+ * classic script in <head>, a <script> inside the element hands control back
+ * mid-parse, so an enhancer that reads its children at connect can find them
+ * missing. Deferring that one read to DOMContentLoaded needs no observer; after
+ * parsing the callback runs at once. Returns a cancel for the enhancer's
+ * cleanup, so an element removed before the document is parsed does nothing.
+ */
+export function afterParse(node, callback) {
+  const doc = node.ownerDocument;
+  if (doc.readyState !== "loading") {
+    callback();
+    return () => {};
+  }
+  const controller = new AbortController();
+  doc.addEventListener("DOMContentLoaded", callback, { once: true, signal: controller.signal });
+  return () => controller.abort();
+}

package/src/js/tab.js

@@ -9,6 +9,8 @@
  *            ArrowUp/Down for aria-orientation="vertical"
  *            ArrowDown (focus selected panel)
  *            [hidden], disabled and panel-less tabs are skipped
+ * Overflow:  a horizontal strip shows its whole selected tab, at connect and
+ *            on every selection
  *
  * Self-registers via registerEnhancement: injected tablists wire automatically.
  * The tab→panel map is rebuilt from the live tablist on each interaction,
@@ -17,9 +19,13 @@
  */
 
 import { registerEnhancement } from "./enhance.js";
+import { ensureInlineVisible } from "./inline-visible.js";
 import { itemForKey, shouldIgnoreKey } from "./keys.js";
+import { afterParse } from "./parsed.js";
 
-const TABLIST_SELECTOR = '[data-enhance~="tabs"]';
+// Ownership follows the ARIA structure, not the activation token: a tab
+// belongs to its closest role="tablist", enhanced or not.
+const TABLIST_SELECTOR = '[role="tablist"]';
 
 // A tablist owns only the tabs directly beneath it, not those of a nested
 // tablist. Filtering by closest owner keeps the outer list from operating on
@@ -85,10 +91,19 @@ function activate(tab) {
   }
 }
 
-function activateAndFocus(tab) {
+/* An overflowing horizontal strip shows the whole tab. At connect a
+   server-selected tab may render off-screen; on arrow keys and clicks the
+   native focus scroll is not enough: Chrome skips a tab already partly inside
+   the scrollport, so one showing a sliver at the edge stayed clipped. */
+function reveal(list, tab) {
+  if (list.getAttribute("aria-orientation") !== "vertical") ensureInlineVisible(list, tab);
+}
+
+function activateAndFocus(list, tab) {
   if (!tab) return;
   activate(tab);
   tab.focus();
+  reveal(list, tab);
 }
 
 function initialize(list) {
@@ -96,6 +111,7 @@ function initialize(list) {
   if (!tabs.length) return;
   const selected = tabs.find((tab) => tab.getAttribute("aria-selected") === "true") || tabs[0];
   activate(selected);
+  reveal(list, selected);
 }
 
 function onKeydown(e) {
@@ -133,7 +149,7 @@ function onKeydown(e) {
   if (!target) return;
 
   e.preventDefault();
-  activateAndFocus(target);
+  activateAndFocus(list, target);
 }
 
 function onClick(e) {
@@ -146,14 +162,24 @@ function onClick(e) {
   }
   e.preventDefault();
   if (tab.getAttribute("aria-selected") === "true") return;
-  activate(tab);
-  tab.focus();
+  activateAndFocus(list, tab);
 }
 
 registerEnhancement("tabs", (list) => {
+  // Tabs find their list through role="tablist"; without it nothing would
+  // respond, so say why instead of wiring a dead strip.
+  if (list.getAttribute("role") !== "tablist") {
+    console.warn('data-enhance="tabs" needs role="tablist" on the same element', list);
+    return;
+  }
   const controller = new AbortController();
-  initialize(list);
+  // Once parsed: a tablist connected mid-parse had no tabs yet, so the roving
+  // tabindex and the selected tab's placement were skipped for good.
+  const cancelInit = afterParse(list, () => initialize(list));
   list.addEventListener("click", onClick, { signal: controller.signal });
   list.addEventListener("keydown", onKeydown, { signal: controller.signal });
-  return () => controller.abort();
+  return () => {
+    cancelInit();
+    controller.abort();
+  };
 });

package/src/tooling/design-export.js

@@ -31,7 +31,7 @@ const PLUGIN = fileURLToPath(new URL("./penpot-plugin/", import.meta.url));
  */
 export async function exportDesign({ themeFile, name, out }) {
   const themeCss = themeFile ? await inlineImports(themeFile) : "";
-  const theme = themeFile ? (name ?? themeNameOf(themeCss)) : null;
+  const theme = themeFile ? themeNameOf(themeCss, name) : null;
   const css = `${await inlineImports(FRAMEWORK)}\n${themeCss}`;
 
   const resolved = await resolveTokens({

package/src/tooling/design-tokens.js

@@ -42,6 +42,7 @@ export const THEME_COLORS = [
   "text-subtle",
   "heading",
   "border",
+  "border-control",
   "focus",
   "hover-overlay",
   "hover-overlay-solid",
@@ -131,7 +132,6 @@ export const NOT_EXPORTED = {
     "soft-border-mix",
     "soft-hover-alpha",
     "soft-fg-mix",
-    "focus-outline",
     "focus-outline-color",
   ],
   "soft recipe, exported with the components": [
@@ -162,7 +162,9 @@ const ROLE_OF = new Map(
 
 const DECLARATION_RE = /(?<![-\w])--([a-z0-9-]+)\s*:\s*([^;{}]*);/gi;
 const ALIAS_RE = /^var\(\s*--([a-z0-9-]+)\s*\)$/i;
-const THEME_NAME_RE = /\[data-theme="([^"]+)"\]/g;
+// Every valid spelling — either quote, a bare ident, whitespace inside the
+// brackets, an i/s flag: a missed name falls back to the :root theme silently.
+const THEME_NAME_RE = /\[\s*data-theme\s*=\s*(?:(["'])([^"']+)\1|([-\w]+))\s*(?:[is]\s*)?\]/gi;
 
 export function declaredTokens(css) {
   return new Set([...stripComments(css).matchAll(DECLARATION_RE)].map((m) => m[1]));
@@ -183,17 +185,29 @@ export function aliasCandidates(...sources) {
   return aliases;
 }
 
-/* The one data-theme value a theme file declares, light/dark excluded. */
-export function themeNameOf(css) {
+/* The one data-theme value a theme file declares, light/dark excluded. null
+   when it declares none: the theme is written on :root, the application's
+   own sheet rather than an island. An explicit name must be one the file
+   declares: an island no rule matches would measure the framework defaults
+   and report them as the theme (a typo passed silently). */
+export function themeNameOf(css, explicit) {
   const names = new Set(
-    [...css.matchAll(THEME_NAME_RE)].map((m) => m[1]).filter((n) => n !== "light" && n !== "dark"),
+    // Comments stripped: a selector quoted in a doc comment is not a theme.
+    [...stripComments(css).matchAll(THEME_NAME_RE)]
+      .map((m) => m[2] ?? m[3])
+      .filter((n) => n !== "light" && n !== "dark"),
   );
-  if (names.size !== 1) {
+  if (explicit != null) {
+    if (names.has(explicit)) return explicit;
+    const found = names.size ? `it declares ${[...names].join(", ")}` : "it declares none";
+    throw new Error(`The theme declares no [data-theme="${explicit}"]; ${found}.`);
+  }
+  if (names.size > 1) {
     throw new Error(
-      `Expected one [data-theme="…"] name in the theme, found ${names.size === 0 ? "none" : [...names].join(", ")}; pass the name explicitly.`,
+      `Expected one [data-theme="…"] name in the theme, found ${[...names].join(", ")}; pass the name explicitly.`,
     );
   }
-  return [...names][0];
+  return names.size === 1 ? [...names][0] : null;
 }
 
 export async function coreTokenCss() {
@@ -246,7 +260,7 @@ function readIslands({ css, islands, colors, lengths, weights }) {
       const raw = read(name);
       if (raw) values.weights[name] = Number(raw);
     }
-    values.scheme = attribute ? getComputedStyle(island).colorScheme : null;
+    values.scheme = getComputedStyle(island).colorScheme;
     result.push(values);
     island.remove();
   }
@@ -266,31 +280,28 @@ const evaluateIslands = (input) => inPage(readIslands, input);
 
 /*
  * Resolves one theme. `css` is the full stylesheet (framework + theme, imports
- * inlined). Without `theme`, the default theme is read through its light and
- * dark boundaries. A named theme exports the schemes it declares: `light dark`
- * gives two modes, anything else one. `islands` is returned so component
- * measurements read the same boundaries.
+ * inlined). Without `theme`, the theme is the root's — the default one, or an
+ * application theme written on :root. The theme exports the schemes it
+ * declares: `light dark` gives two modes, anything else one. `islands` is
+ * returned so component measurements read the same boundaries.
  */
-export async function resolveTokens({ css, theme, aliasSources = [] }) {
-  let islands = [
-    { mode: "light", attribute: "light" },
-    { mode: "dark", attribute: "dark" },
-  ];
-  if (theme) {
-    const [declared] = await evaluateIslands({
-      css,
-      islands: [{ attribute: theme }],
-      colors: [],
-      lengths: [],
-      weights: [],
-    });
-    const schemes = declared.scheme.split(/\s+/).filter((s) => s === "light" || s === "dark");
-    islands = (schemes.length > 0 ? schemes : ["light"]).map((mode) => ({
-      mode,
-      attribute: theme,
-      scheme: mode,
-    }));
-  }
+export async function resolveTokens({ css, theme = null, aliasSources = [] }) {
+  // A root island carries no data-theme: the core redeclares the default
+  // palette on [data-theme="light"|"dark"], which would mask a :root theme.
+  // Pinning color-scheme alone is what picks the light-dark() side.
+  const [declared] = await evaluateIslands({
+    css,
+    islands: [{ attribute: theme }],
+    colors: [],
+    lengths: [],
+    weights: [],
+  });
+  const schemes = declared.scheme.split(/\s+/).filter((s) => s === "light" || s === "dark");
+  const islands = (schemes.length > 0 ? schemes : ["light"]).map((mode) => ({
+    mode,
+    attribute: theme,
+    scheme: mode,
+  }));
 
   const read = await evaluateIslands({
     css,

package/src/tooling/theme-contrast.js

@@ -24,10 +24,13 @@ const FRAMEWORK = fileURLToPath(new URL("../css/actual.full.css", import.meta.ur
 export const INTENTS = ["primary", "secondary", "success", "warning", "danger", "neutral"];
 
 /* Badges state .soft explicitly: a theme may fill badges by default
-   (bootstrap-v6), which would measure a solid pair against the soft hover. */
-function islandMarkup(id, attribute, scheme) {
+   (bootstrap-v6), which would measure a solid pair against the soft hover.
+   The theme name is read from a file by a regex, so it never enters this
+   markup: measureContrast() sets it through dataset. `scheme` is only ever
+   "light" or "dark". */
+function islandMarkup(id, scheme) {
   const style = scheme ? ` style="color-scheme: ${scheme}"` : "";
-  return `<div data-theme="${attribute}"${style} id="${id}">
+  return `<div${style} id="${id}">
     ${INTENTS.map((i) => `<span class="badge soft ${i}" data-badge="${i}">t</span>`).join("")}
     ${INTENTS.map((i) => `<button class="btn soft ${i}" data-hover="${i}" type="button">t</button>`).join("")}
     <span data-pair="focus-surface" style="color: var(--focus); background: var(--surface)"></span>
@@ -41,23 +44,27 @@ const ratio = (fg, bg) => (fg[3] < 255 || bg[3] < 255 ? null : contrast(fg, bg))
 
 /*
  * Measures each theme of `themes` (data-theme values) in `css`, the full
- * stylesheet with imports inlined. `null` stands for the default theme, read
- * through its light and dark boundaries; a named theme is read in each scheme
- * its `color-scheme` declares. Returns one row per island.
+ * stylesheet with imports inlined. `null` stands for the root's theme — the
+ * default one, or an application theme written on :root — labelled `label`.
+ * Each theme is read in every scheme its `color-scheme` declares. Returns one
+ * row per island.
  */
-export async function measureContrast({ css, themes }) {
+export async function measureContrast({ css, themes, label = "default" }) {
   await using view = new Bun.WebView({ backend: "chrome" });
   await view.navigate("about:blank");
 
   // Transitions off: a forced :hover must compute its end state at once.
-  const islands = await view.evaluate(`((css, themes) => {
+  const islands = await view.evaluate(`((css, themes, label) => {
     const style = document.createElement("style");
     style.textContent = css + "\\n* { transition-duration: 0s !important; }";
     document.head.append(style);
 
+    // A root island carries no data-theme: the core redeclares the default
+    // palette on [data-theme="light"|"dark"], which would mask a :root theme.
+    // Pinning color-scheme alone is what picks the light-dark() side.
     const schemesOf = (attribute) => {
       const probe = document.createElement("div");
-      probe.dataset.theme = attribute;
+      if (attribute) probe.dataset.theme = attribute;
       document.body.append(probe);
       const declared = getComputedStyle(probe).colorScheme.split(/\\s+/);
       probe.remove();
@@ -65,19 +72,19 @@ export async function measureContrast({ css, themes }) {
       return schemes.length > 0 ? schemes : ["light"];
     };
 
-    return themes.flatMap((theme) =>
-      theme === null
-        ? ["light", "dark"].map((scheme) => ({ theme: "default", scheme, attribute: scheme, pin: false }))
-        : schemesOf(theme).map((scheme, _, all) => ({ theme, scheme, attribute: theme, pin: all.length > 1 })),
+    return themes.flatMap((attribute) =>
+      schemesOf(attribute).map((scheme) => ({ theme: attribute ?? label, scheme, attribute })),
     );
-  })(${JSON.stringify(css)}, ${JSON.stringify(themes)})`);
-
-  const markup = islands
-    .map((island, i) =>
-      islandMarkup(`island-${i}`, island.attribute, island.pin ? island.scheme : null),
-    )
-    .join("\n");
-  await view.evaluate(`document.body.insertAdjacentHTML("beforeend", ${JSON.stringify(markup)})`);
+  })(${JSON.stringify(css)}, ${JSON.stringify(themes)}, ${JSON.stringify(label)})`);
+
+  const markup = islands.map((island, i) => islandMarkup(`island-${i}`, island.scheme)).join("\n");
+  const attributes = islands.map((island) => island.attribute);
+  await view.evaluate(`((markup, attributes) => {
+    document.body.insertAdjacentHTML("beforeend", markup);
+    attributes.forEach((attribute, i) => {
+      if (attribute) document.getElementById("island-" + i).dataset.theme = attribute;
+    });
+  })(${JSON.stringify(markup)}, ${JSON.stringify(attributes)})`);
 
   await view.cdp("DOM.enable");
   await view.cdp("CSS.enable");
@@ -136,13 +143,14 @@ export async function measureContrast({ css, themes }) {
 
 /*
  * Measures one theme file over the framework, or the default theme without
- * `themeFile`. `name` overrides the data-theme name read from the file.
+ * `themeFile`. `name` overrides the data-theme name read from the file; a file
+ * that declares none is a :root theme.
  */
 export async function measureThemeFile({ themeFile, name }) {
   const themeCss = themeFile ? await inlineImports(themeFile) : "";
-  const theme = themeFile ? (name ?? themeNameOf(themeCss)) : null;
+  const theme = themeFile ? themeNameOf(themeCss, name) : null;
   const css = `${await inlineImports(FRAMEWORK)}\n${themeCss}`;
-  return measureContrast({ css, themes: [theme] });
+  return measureContrast({ css, themes: [theme], label: themeFile ? ":root" : "default" });
 }
 
 /* Text tables for `rows`, and the number of pairs under their threshold. */