@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

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/analyzer/selectors.d.mts

@@ -0,0 +1,21 @@
+export interface SelectorCompound {
+  combinator: '' | ' ' | '>' | '+' | '~';
+  compound: string;
+}
+
+export function ownsClass(rootClass: string, candidate: string): boolean;
+export function complexSelectorParts(
+  selectorList: string,
+): SelectorCompound[][];
+export function complexSelectors(selectorList: string): string[][];
+export function kuiClasses(selector: string): string[];
+export function classNames(selector: string): string[];
+export function dataComponents(selector: string): string[];
+export function withoutPseudoArguments(
+  compound: string,
+  names: string[],
+): string;
+export function withoutRelationalArguments(compound: string): string;
+export function pseudoArguments(compound: string, name: string): string[];
+export function splitTopLevel(list: string): string[];
+export function subjectTypes(compound: string): string[] | null;

package/analyzer/selectors.mjs

@@ -0,0 +1,212 @@
+/**
+ * Selector parsing shared by the package stylesheet ownership check
+ * (`scripts/lib/css-ownership.mjs`, `npm run check:css-ownership`) and the
+ * downstream component-ownership diagnostics in `kerf-ui-analyze`
+ * (`component-ownership.mjs`). Pure string work over one selector list: no
+ * PostCSS, no filesystem. One copy means the package rule and the consumer
+ * rule agree on which compound a selector styles.
+ */
+
+export function ownsClass(rootClass, candidate) {
+  return (
+    candidate === rootClass ||
+    candidate.startsWith(`${rootClass}__`) ||
+    candidate.startsWith(`${rootClass}--`)
+  );
+}
+
+/**
+ * Split a selector list into its complex selectors, and each complex selector
+ * into compounds, ignoring commas and combinators nested inside parentheses,
+ * attribute brackets, or quotes. Each compound records the combinator that
+ * joins it to the previous one (`''` for the first).
+ */
+export function complexSelectorParts(selectorList) {
+  const selectors = [];
+  let compounds = [];
+  let current = '';
+  let combinator = '';
+  let pending = '';
+  let depth = 0;
+  let quote = null;
+  const endCompound = () => {
+    if (current.trim()) {
+      compounds.push({ combinator, compound: current.trim() });
+      combinator = '';
+    }
+    current = '';
+  };
+  for (const char of selectorList) {
+    if (quote) {
+      current += char;
+      if (char === quote) quote = null;
+    } else if (char === '"' || char === "'") {
+      quote = char;
+      current += char;
+    } else if (char === '(' || char === '[') {
+      depth += 1;
+      current += char;
+    } else if (char === ')' || char === ']') {
+      depth -= 1;
+      current += char;
+    } else if (depth === 0 && char === ',') {
+      endCompound();
+      selectors.push(compounds);
+      compounds = [];
+      pending = '';
+    } else if (depth === 0 && /[\s>+~]/.test(char)) {
+      const hadCompound = current.trim() !== '';
+      endCompound();
+      if (/[>+~]/.test(char)) pending = char;
+      else if (!pending && (hadCompound || compounds.length > 0)) pending = ' ';
+    } else {
+      if (!current && compounds.length > 0) {
+        combinator = pending || ' ';
+        pending = '';
+      }
+      current += char;
+    }
+  }
+  endCompound();
+  selectors.push(compounds);
+  return selectors;
+}
+
+/** Complex selectors as arrays of compound strings. */
+export function complexSelectors(selectorList) {
+  return complexSelectorParts(selectorList).map((parts) =>
+    parts.map(({ compound }) => compound),
+  );
+}
+
+export function kuiClasses(selector) {
+  return [...selector.matchAll(/\.((?:kui)-[a-z0-9_-]+)/gi)].map(
+    ([, name]) => name,
+  );
+}
+
+/** Every class name a selector names, in any namespace. */
+export function classNames(selector) {
+  return [...selector.matchAll(/\.(-?[_a-zA-Z][_a-zA-Z0-9-]*)/g)].map(
+    ([, name]) => name,
+  );
+}
+
+export function dataComponents(selector) {
+  return [
+    ...selector.matchAll(
+      /\[data-component\s*=\s*["']?([a-z0-9-]+)["']?\s*\]/gi,
+    ),
+  ].map(([, name]) => name);
+}
+
+/**
+ * Remove the arguments of every pseudo-class named in `names` from a
+ * compound, keeping the empty call.
+ */
+export function withoutPseudoArguments(compound, names) {
+  const opener = new RegExp(`^:(?:${names.join('|')})\\(`, 'i');
+  let result = '';
+  let skipDepth = 0;
+  for (let index = 0; index < compound.length; index += 1) {
+    if (skipDepth === 0) {
+      const match = opener.exec(compound.slice(index));
+      if (match) {
+        result += match[0];
+        skipDepth = 1;
+        index += match[0].length - 1;
+      } else result += compound[index];
+    } else if (compound[index] === '(') skipDepth += 1;
+    else if (compound[index] === ')') {
+      skipDepth -= 1;
+      if (skipDepth === 0) result += ')';
+    }
+  }
+  return result;
+}
+
+/**
+ * Remove the arguments of every `:has()` and `:not()` in a compound. A parent
+ * may key its own styles on a composed child's state
+ * (`:has(> .kui-select[open])`) or exclude a kerf child it does not own
+ * (`wa-dropdown:not(.kui-popup-menu)`): neither styles that child.
+ */
+export function withoutRelationalArguments(compound) {
+  return withoutPseudoArguments(compound, ['has', 'not']);
+}
+
+/** The top-level arguments of each `:name(...)` call in a compound. */
+export function pseudoArguments(compound, name) {
+  const args = [];
+  const opener = new RegExp(`:${name}\\(`, 'gi');
+  for (const match of compound.matchAll(opener)) {
+    let depth = 1;
+    let index = match.index + match[0].length;
+    const start = index;
+    for (; index < compound.length && depth > 0; index += 1) {
+      if (compound[index] === '(') depth += 1;
+      else if (compound[index] === ')') depth -= 1;
+    }
+    args.push(compound.slice(start, index - 1));
+  }
+  return args;
+}
+
+export function splitTopLevel(list) {
+  const parts = [];
+  let depth = 0;
+  let current = '';
+  for (const char of list) {
+    if (char === '(' || char === '[') depth += 1;
+    else if (char === ')' || char === ']') depth -= 1;
+    if (char === ',' && depth === 0) {
+      parts.push(current.trim());
+      current = '';
+    } else current += char;
+  }
+  if (current.trim()) parts.push(current.trim());
+  return parts;
+}
+
+/**
+ * The element types a subject compound can match: its own type selector and
+ * the subject types inside its `:is()` / `:where()` arguments. `null` means the
+ * compound places no type constraint (universal).
+ */
+export function subjectTypes(compound) {
+  const bare = withoutPseudoArguments(compound, [
+    'has',
+    'not',
+    'is',
+    'where',
+    'part',
+    'nth-child',
+    'nth-last-child',
+    'nth-of-type',
+    'nth-last-of-type',
+  ]);
+  const own = /^([a-z][a-z0-9-]*)/i.exec(bare);
+  if (own) return [own[1].toLowerCase()];
+  const types = [];
+  for (const name of ['is', 'where']) {
+    for (const args of pseudoArguments(
+      withoutRelationalArguments(compound),
+      name,
+    )) {
+      for (const arg of splitTopLevel(args)) {
+        const parts = complexSelectors(arg)[0] ?? [];
+        const last = parts.at(-1);
+        if (!last) return null;
+        const inner = subjectTypes(last);
+        if (inner === null) {
+          // A class-only argument constrains nothing by type, but it names an
+          // element that must carry that class.
+          if (kuiClasses(withoutRelationalArguments(last)).length > 0) continue;
+          return null;
+        }
+        types.push(...inner);
+      }
+    }
+  }
+  return types.length > 0 ? types : null;
+}