@kerfjs/ui 5.0.0-beta.52 → 5.0.0-beta.54

package/analyzer/index.mjs

@@ -14,6 +14,7 @@ import ts from 'typescript';
 
 import { loadApplicationUiProfile } from '../ai/application-ui-profile.mjs';
 import { isUiTraversalExcluded } from '../traversal-exclusions.mjs';
+import { collectLoudDeclarations, inspectLoudPairs } from './loud-pairs.mjs';
 
 export const UI_ANALYSIS_SCHEMA_VERSION = 1;
 
@@ -41,6 +42,10 @@ export const UI_ANALYSIS_RULES = Object.freeze({
   'KUI-L015': { severity: 'error', title: 'Non-standalone CSS expression' },
   'KUI-L016': { severity: 'error', title: 'Forbidden declaration-list escape' },
   'KUI-L017': { severity: 'review', title: 'Exceptional spacing shorthand' },
+  'KUI-L018': {
+    severity: 'review',
+    title: 'Loud fill override without its on-loud pair',
+  },
 });
 
 const adoptionRules = new Set([
@@ -344,6 +349,7 @@ async function inspectCss(
   diagnostics,
   cssFacts,
   adoption = false,
+  siblingOnLoud = [],
 ) {
   let root;
   try {
@@ -358,6 +364,15 @@ async function inspectCss(
     );
     return;
   }
+  inspectLoudPairs(
+    file,
+    root,
+    (decl, message, evidence) =>
+      diagnostics.push(
+        diagnostic('KUI-L018', location(file, decl), message, evidence),
+      ),
+    siblingOnLoud,
+  );
   root.walkRules((rule) => {
     const classes = [
       ...rule.selector.matchAll(/\.([_a-zA-Z]+[_a-zA-Z0-9-]*)/g),
@@ -962,6 +977,38 @@ export async function analyzeUiProject({
   const styleConsumers = new Map(
     [...styleFacts.keys()].map((file) => [file, new Set()]),
   );
+  // KUI-L018 accepts an on-loud from another stylesheet the same entry loads:
+  // every stylesheet reachable from one file (a source module's CSS imports,
+  // or a stylesheet with its @imports) is loaded together.
+  const onLoudByStyle = new Map();
+  for (const style of styleFacts.keys()) {
+    let parsed;
+    try {
+      parsed = postcss.parse(contents.get(style), { from: style });
+    } catch {
+      continue;
+    }
+    onLoudByStyle.set(
+      style,
+      collectLoudDeclarations(style, parsed).filter(
+        ({ kind }) => kind === 'on-loud',
+      ),
+    );
+  }
+  const coLoadedStyles = new Map(
+    [...styleFacts.keys()].map((style) => [style, new Set()]),
+  );
+  for (const file of files) {
+    const loaded = new Set(reachableStyleFiles(file, imports, styleFacts));
+    if (styleFacts.has(file)) loaded.add(file);
+    for (const style of loaded)
+      for (const sibling of loaded)
+        if (sibling !== style) coLoadedStyles.get(style).add(sibling);
+  }
+  const siblingOnLoud = (style) =>
+    [...coLoadedStyles.get(style)]
+      .sort()
+      .flatMap((sibling) => onLoudByStyle.get(sibling) ?? []);
   for (const file of files.filter((item) =>
     sourceExtensions.has(extname(item)),
   )) {
@@ -991,6 +1038,7 @@ export async function analyzeUiProject({
         fileDiagnostics,
         new Map(),
         adoption,
+        siblingOnLoud(file),
       );
       recordDiagnostics(fileDiagnostics, context);
     }

package/analyzer/loud-pairs.d.mts

@@ -0,0 +1,49 @@
+import type { Declaration, Root } from 'postcss';
+
+export type Rgb = [number, number, number];
+
+export interface LoudScope {
+  key: string;
+  atScope: string;
+  bare: string;
+  selector: string;
+}
+
+export interface LoudDeclaration {
+  decl: Declaration;
+  file: string;
+  tone: string;
+  kind: 'fill-loud' | 'on-loud';
+  value: string;
+  scope: LoudScope;
+}
+
+export declare const LOUD_PAIR_MIN_CONTRAST: number;
+export declare const DEFAULT_ON_LOUD: Readonly<Record<string, string>>;
+
+export declare function literalSchemeColors(
+  value: string,
+): { light: Rgb; dark: Rgb } | undefined;
+
+export declare function contrastRatio(first: Rgb, second: Rgb): number;
+
+export declare function loudPairContrast(
+  fillValue: string,
+  onLoudValue: string,
+): { scheme: 'light' | 'dark'; ratio: number } | undefined;
+
+export declare function collectLoudDeclarations(
+  file: string,
+  root: Root,
+): LoudDeclaration[];
+
+export declare function inspectLoudPairs(
+  file: string,
+  root: Root,
+  report: (
+    decl: Declaration,
+    message: string,
+    evidence: Record<string, unknown>,
+  ) => void,
+  siblingOnLoud?: readonly LoudDeclaration[],
+): void;

package/analyzer/loud-pairs.mjs

@@ -0,0 +1,357 @@
+import postcss from 'postcss';
+
+// KUI-L018: the shipped Web Awesome theme pairs every loud fill with an
+// on-loud foreground that clears WCAG AA; an override that moves one without
+// the other silently drops that guarantee (see docs/webawesome-theme.md).
+const loudToken =
+  /^--wa-color-(neutral|brand|success|warning|danger|pop)-(fill-loud|on-loud)$/;
+
+/** WCAG AA contrast for normal text. */
+export const LOUD_PAIR_MIN_CONTRAST = 4.5;
+
+/**
+ * The on-loud foreground `@kerfjs/ui/webawesome.css` ships for each tone,
+ * where it is a literal color. An unpaired fill that still clears AA against
+ * it keeps the guarantee. `neutral` follows the surface token and `pop` has no
+ * Web Awesome default, so neither can be proven and an unpaired fill stays a
+ * finding. A unit test keeps this table equal to the shipped stylesheet.
+ */
+export const DEFAULT_ON_LOUD = Object.freeze({
+  brand: 'light-dark(#fff, #111113)',
+  success: '#1d1d1f',
+  warning: '#1d1d1f',
+  danger: 'light-dark(#fff, #111113)',
+});
+
+const NAMED_COLORS = new Map([
+  ['white', [255, 255, 255]],
+  ['black', [0, 0, 0]],
+]);
+
+function channel(value, scale) {
+  const text = value.trim();
+  if (text.endsWith('%')) return (Number(text.slice(0, -1)) / 100) * scale;
+  return Number(text);
+}
+
+function opaque(alpha) {
+  if (alpha === undefined) return true;
+  const text = alpha.trim();
+  const value = text.endsWith('%')
+    ? Number(text.slice(0, -1)) / 100
+    : Number(text);
+  return value === 1;
+}
+
+function hslToRgb(hue, saturation, lightness) {
+  const h = (((hue % 360) + 360) % 360) / 360;
+  const s = saturation / 100;
+  const l = lightness / 100;
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  const convert = (t) => {
+    const x = t < 0 ? t + 1 : t > 1 ? t - 1 : t;
+    if (x < 1 / 6) return p + (q - p) * 6 * x;
+    if (x < 1 / 2) return q;
+    if (x < 2 / 3) return p + (q - p) * (2 / 3 - x) * 6;
+    return p;
+  };
+  return [convert(h + 1 / 3), convert(h), convert(h - 1 / 3)].map(
+    (component) => component * 255,
+  );
+}
+
+/** An opaque literal sRGB color as `[r, g, b]` (0-255), else `undefined`. */
+function parseOpaqueColor(value) {
+  const text = value.trim().toLowerCase();
+  if (NAMED_COLORS.has(text)) return NAMED_COLORS.get(text);
+  const hex = /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/.exec(text);
+  if (hex) {
+    const digits =
+      hex[1].length <= 4
+        ? [...hex[1]].map((digit) => digit + digit).join('')
+        : hex[1];
+    if (digits.length === 8 && digits.slice(6) !== 'ff') return undefined;
+    return [0, 2, 4].map((start) =>
+      Number.parseInt(digits.slice(start, start + 2), 16),
+    );
+  }
+  const functional = /^(rgba?|hsla?)\(([^()]*)\)$/.exec(text);
+  if (!functional) return undefined;
+  const [components, alpha] = functional[2].includes('/')
+    ? functional[2].split('/')
+    : [functional[2]];
+  const parts = components.split(/[\s,]+/).filter(Boolean);
+  const alphaPart = alpha ?? parts[3];
+  if (parts.length < 3 || !opaque(alphaPart)) return undefined;
+  const rgb = functional[1].startsWith('rgb')
+    ? parts.slice(0, 3).map((part) => channel(part, 255))
+    : hslToRgb(
+        Number(parts[0].replace(/deg$/, '')),
+        Number(parts[1].replace(/%$/, '')),
+        Number(parts[2].replace(/%$/, '')),
+      );
+  return rgb.every((component) => Number.isFinite(component))
+    ? rgb.map((component) => Math.min(255, Math.max(0, component)))
+    : undefined;
+}
+
+/**
+ * A literal color value resolved per color scheme: `{ light, dark }` of
+ * `[r, g, b]`. `light-dark(a, b)` splits by scheme; a plain literal applies to
+ * both. Anything else (a `var()`, `color-mix()`, a keyword, transparency) is
+ * not provable and returns `undefined`.
+ */
+export function literalSchemeColors(value) {
+  const text = value
+    .replace(/!important\s*$/i, '')
+    .trim()
+    .toLowerCase();
+  const lightDark = /^light-dark\((.*)\)$/.exec(text);
+  if (lightDark) {
+    const parts = postcss.list.comma(lightDark[1]);
+    if (parts.length !== 2) return undefined;
+    const [light, dark] = parts.map(parseOpaqueColor);
+    return light && dark ? { light, dark } : undefined;
+  }
+  const color = parseOpaqueColor(text);
+  return color ? { light: color, dark: color } : undefined;
+}
+
+function luminance([red, green, blue]) {
+  const linear = (component) => {
+    const value = component / 255;
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * linear(red) + 0.7152 * linear(green) + 0.0722 * linear(blue);
+}
+
+/** WCAG 2 contrast ratio between two `[r, g, b]` colors. */
+export function contrastRatio(first, second) {
+  const [lighter, darker] = [luminance(first), luminance(second)].sort(
+    (a, b) => b - a,
+  );
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * The lowest per-scheme contrast of a fill/foreground pair, or `undefined`
+ * when either value is not a provable literal color.
+ */
+export function loudPairContrast(fillValue, onLoudValue) {
+  const fill = literalSchemeColors(fillValue);
+  const foreground = literalSchemeColors(onLoudValue);
+  if (!fill || !foreground) return undefined;
+  const results = ['light', 'dark'].map((scheme) => ({
+    scheme,
+    ratio: contrastRatio(fill[scheme], foreground[scheme]),
+  }));
+  return results.reduce((lowest, item) =>
+    item.ratio < lowest.ratio ? item : lowest,
+  );
+}
+
+function normalizeSelector(selector) {
+  return selector
+    .replace(/\s+/g, ' ')
+    .replace(/\s*([>+~])\s*/g, '$1')
+    .trim();
+}
+
+function resolvedSelectors(node) {
+  const chain = [];
+  let current = node;
+  while (current && current.type !== 'root') {
+    chain.unshift(current);
+    current = current.parent;
+  }
+  let selectors = [''];
+  const atRules = [];
+  for (const item of chain) {
+    if (item.type === 'atrule')
+      atRules.push(`@${item.name} ${item.params.replace(/\s+/g, ' ').trim()}`);
+    if (item.type !== 'rule') continue;
+    const own = postcss.list.comma(item.selector).map(normalizeSelector);
+    selectors = selectors.flatMap((parent) =>
+      own.map((child) => {
+        if (child.includes('&'))
+          return child.replaceAll('&', parent || ':root');
+        return parent ? `${parent} ${child}` : child;
+      }),
+    );
+  }
+  const atScope = atRules.join(' ');
+  return selectors.map((selector) => ({
+    key: `${atScope}|${selector}`,
+    atScope,
+    bare: selector,
+    selector: atScope ? `${atScope} ${selector}`.trim() : selector,
+  }));
+}
+
+/**
+ * Every loud-token declaration in a stylesheet, one record per resolved
+ * selector scope: `{ decl, file, tone, kind, value, scope }`.
+ */
+export function collectLoudDeclarations(file, root) {
+  const records = [];
+  root.walkDecls((decl) => {
+    const match = loudToken.exec(decl.prop.trim());
+    if (!match) return;
+    for (const scope of resolvedSelectors(decl.parent))
+      records.push({
+        decl,
+        file,
+        tone: match[1],
+        kind: match[2],
+        value: decl.value,
+        scope,
+      });
+  });
+  return records;
+}
+
+// Selectors that match the document root (or a shadow root's host), so a
+// custom property set there inherits into every other scope.
+const rootSelectors = new Set(['', ':root', 'html', ':host', '*']);
+
+// Whether an on-loud declared in `outer` provably reaches an element that
+// `inner` matches: the same scope, or an ancestor one. The outer at-rule chain
+// must be absent or a prefix of the inner one (an unconditional value applies
+// inside `@media`, not the reverse), and the outer selector must be a document
+// root selector or the leading compound selector of a descendant/child chain.
+function reaches(outer, inner) {
+  if (
+    outer.atScope &&
+    outer.atScope !== inner.atScope &&
+    !inner.atScope.startsWith(`${outer.atScope} `)
+  )
+    return false;
+  if (outer.bare === inner.bare || rootSelectors.has(outer.bare)) return true;
+  return (
+    inner.bare.startsWith(outer.bare) &&
+    [' ', '>'].includes(inner.bare[outer.bare.length])
+  );
+}
+
+// The on-loud that governs a fill scope: the same scope wins (this stylesheet
+// before a co-loaded one), then the nearest ancestor (the longest selector).
+function governingOnLoud(fill, onLoud) {
+  const candidates = onLoud.filter(
+    (record) => record.tone === fill.tone && reaches(record.scope, fill.scope),
+  );
+  const rank = (record) => [
+    record.scope.key === fill.scope.key ? 1 : 0,
+    record.file === fill.file ? 1 : 0,
+    record.scope.atScope.length + record.scope.bare.length,
+  ];
+  return candidates.sort((a, b) => {
+    const [left, right] = [rank(a), rank(b)];
+    for (let index = 0; index < left.length; index += 1)
+      if (left[index] !== right[index]) return right[index] - left[index];
+    return 0;
+  })[0];
+}
+
+const scopeLabel = (selector) => selector || '(top level)';
+// Truncated rather than rounded, so a pair just under 4.5:1 never reads as
+// passing.
+const truncatedRatio = (ratio) => Math.floor(ratio * 100) / 100;
+const ratioLabel = (ratio) => `${truncatedRatio(ratio).toFixed(2)}:1`;
+
+/**
+ * Report each loud fill override whose tone lacks a governing on-loud (unless
+ * the fill provably clears AA against the theme's default foreground), and
+ * each literal pair that is present but below 4.5:1. `siblingOnLoud` holds
+ * on-loud records from the other stylesheets the same entry loads.
+ */
+export function inspectLoudPairs(file, root, report, siblingOnLoud = []) {
+  const records = collectLoudDeclarations(file, root);
+  const onLoud = [
+    ...records.filter(({ kind }) => kind === 'on-loud'),
+    ...siblingOnLoud,
+  ];
+  const fills = new Map();
+  for (const record of records.filter(({ kind }) => kind === 'fill-loud')) {
+    const group = fills.get(record.decl) ?? [];
+    group.push(record);
+    fills.set(record.decl, group);
+  }
+  for (const [decl, scopes] of fills) {
+    const { tone } = scopes[0];
+    const pair = `--wa-color-${tone}-on-loud`;
+    const missing = [];
+    const failing = [];
+    for (const fill of scopes) {
+      const governing = governingOnLoud(fill, onLoud);
+      if (governing) {
+        const contrast = loudPairContrast(fill.value, governing.value);
+        if (contrast && contrast.ratio < LOUD_PAIR_MIN_CONTRAST)
+          failing.push({ fill, governing, contrast });
+        continue;
+      }
+      const fallback = DEFAULT_ON_LOUD[tone]
+        ? loudPairContrast(fill.value, DEFAULT_ON_LOUD[tone])
+        : undefined;
+      if (fallback && fallback.ratio >= LOUD_PAIR_MIN_CONTRAST) continue;
+      missing.push({ fill, fallback });
+    }
+    if (missing.length) {
+      const [measured] = missing
+        .map(({ fallback }) => fallback)
+        .filter(Boolean)
+        .sort((a, b) => a.ratio - b.ratio);
+      report(
+        decl,
+        `${decl.prop} is overridden without ${pair} in the same or an ancestor scope (${missing
+          .map(({ fill }) => scopeLabel(fill.scope.selector))
+          .join(', ')})${
+          measured
+            ? `, and it measures ${ratioLabel(measured.ratio)} against the theme's default ${pair} in the ${measured.scheme} scheme`
+            : ''
+        }; set ${pair} alongside it so the loud fill keeps an AA-clearing foreground.`,
+        {
+          property: decl.prop,
+          value: decl.value,
+          tone,
+          pairProperty: pair,
+          selectors: missing.map(({ fill }) => fill.scope.selector),
+          ...(measured
+            ? {
+                defaultPairValue: DEFAULT_ON_LOUD[tone],
+                contrast: truncatedRatio(measured.ratio),
+                scheme: measured.scheme,
+              }
+            : {}),
+        },
+      );
+    }
+    if (failing.length) {
+      const worst = failing.reduce((lowest, item) =>
+        item.contrast.ratio < lowest.contrast.ratio ? item : lowest,
+      );
+      report(
+        decl,
+        `${decl.prop} (${decl.value.trim()}) and its ${pair} (${worst.governing.value.trim()}) measure ${ratioLabel(worst.contrast.ratio)} in the ${worst.contrast.scheme} scheme, below the ${LOUD_PAIR_MIN_CONTRAST}:1 AA minimum (${failing
+          .map(({ fill }) => scopeLabel(fill.scope.selector))
+          .join(
+            ', ',
+          )}); choose a fill or foreground that clears 4.5:1 in every scheme.`,
+        {
+          property: decl.prop,
+          value: decl.value,
+          tone,
+          pairProperty: pair,
+          pairValue: worst.governing.value,
+          pairLocation: {
+            file: worst.governing.file,
+            line: worst.governing.decl.source?.start?.line ?? 1,
+          },
+          contrast: truncatedRatio(worst.contrast.ratio),
+          scheme: worst.contrast.scheme,
+          selectors: failing.map(({ fill }) => fill.scope.selector),
+        },
+      );
+    }
+  }
+}

package/dist/app-tab.d.ts

@@ -33,11 +33,13 @@ interface AppTabProps {
     /** Render as an unanimated loading skeleton, disabling select/close and dragging. */
     placeholder?: boolean;
     /**
-     * Dormant but named: the tab is known and still opening. Keeps `name`
-     * visible in the quiet text color and as the tab's accessible name, shows
-     * `trailing` (for example a `LoadingSpinner`), and disables select, close,
-     * and dragging with `aria-busy`, like `placeholder`. Same pill geometry as
-     * the live tab, so swapping it in place does not shift the bar.
+     * Named and still opening: the tab is known but its content is loading.
+     * Keeps `name` visible in the quiet text color and as the tab's accessible
+     * name, shows `trailing` (for example a `LoadingSpinner`), and marks the
+     * tab `aria-busy`. Unlike `placeholder` it stays selectable — the
+     * application shows placeholder content in its panel until loading
+     * completes — while close and dragging stay disabled. Same pill geometry
+     * as the live tab, so swapping it in place does not shift the bar.
      * `placeholder` wins when both are set.
      */
     pending?: boolean;

package/dist/app-tab.js

@@ -1,4 +1,4 @@
-export { AppTab } from './chunk-IR53BQUJ.js';
+export { AppTab } from './chunk-NE5JAOQS.js';
 
 
 

package/dist/browser/segmented-control.js

@@ -1,4 +1,3 @@
 import '../styles/foundation.css';
-import '../styles/skeleton.css';
 import '../styles/segmented-control.css';
 export * from '../segmented-control.js';

package/dist/catalog.js

@@ -1,12 +1,12 @@
 import { ToolbarControlGroup, ToolbarActionLink } from './chunk-ZIYOJFZD.js';
 import { Toolbar } from './chunk-MTM43SJO.js';
-import { ListItem } from './chunk-LIOXPQ7N.js';
-import { List } from './chunk-7XJO4D6A.js';
-import { ToolbarText } from './chunk-YZV2PTY4.js';
+import { ListItem } from './chunk-GUIHMIT2.js';
+import { List } from './chunk-3NBL3OUQ.js';
+import { ToolbarText } from './chunk-TZ5IHWB2.js';
 import { Pane } from './chunk-7GUQYHKA.js';
 
 
-import { ListHeader } from './chunk-3S7OUHUN.js';
+import { ListHeader } from './chunk-KPNTVB7A.js';
 
 
 import { filterDataAttributes } from './chunk-SRSJO5QE.js';