asma-ui-core 3.78.4 → 3.78.6

package/dist/src/a11y/contrast/contrastPairs.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The colour pairs this library actually puts on screen, as a data table.
+ *
+ * Every row cites the component file that pairs the two tokens, so a reviewer can check the claim
+ * without trusting the table. Tokens are cited by NAME, never by line number — `src/styles/**` is
+ * ASMA-8133's area and its line numbers move.
+ *
+ * Rows with a `finding` are measured failures against master. They are quarantined, not fixed:
+ * changing a token value is a visual (potentially breaking) change to a brand theme and needs
+ * design sign-off, so each one is written up in `docs/a11y-contrast.md` and escalated instead.
+ *
+ * @see docs/a11y-contrast.md — findings register, exemption rationale, measured ratios
+ * @see docs/a11y-allowlist.md — the axe (SC 1.4.3 only) story baseline this cross-references
+ */
+/**
+ * The surface the library composites onto when a token is `transparent`, and the surface an
+ * unparented control is assumed to sit on. The library ships no page-background token; every
+ * component that sets its own opaque surface (input, tooltip, chip) uses white or a delta tint.
+ */
+export declare const APP_SURFACE = "#ffffff";
+export declare const REQUIREMENT_RATIO: {
+    /** SC 1.4.3, body text below 18.66px bold / 24px regular. */
+    readonly text: 4.5;
+    /** SC 1.4.3, large text at or above that size. */
+    readonly largeText: 3;
+    /** SC 1.4.11, UI component boundaries, state indicators and focus rings. */
+    readonly nonText: 3;
+};
+export type ContrastRequirement = keyof typeof REQUIREMENT_RATIO;
+export interface ContrastPair {
+    /** Stable id. Quarantined rows use it to join to `docs/a11y-contrast.md`. */
+    readonly id: string;
+    /** Custom-property name, or a literal colour for a hard-coded component value. */
+    readonly foreground: string;
+    readonly background: string;
+    readonly requirement: ContrastRequirement;
+    /** Repo-relative path of the component that pairs these two. */
+    readonly usedBy: string;
+    /** Findings id in docs/a11y-contrast.md. Present means "measured failing, quarantined". */
+    readonly finding?: string;
+}
+/**
+ * Hand-curated pairs. The button token family is generated instead — see `buildButtonPairs`.
+ */
+export declare const COMPONENT_PAIRS: readonly ContrastPair[];
+/**
+ * `StyledButton.module.scss` builds every button from a single mixin over
+ * `--colors-button-{type}-{color}-{state}-{text|bg|border}-color`, so the button pairs are
+ * generated from the token names rather than transcribed. A new variant or state added to the
+ * token files is contrast-checked the moment it lands, with no edit here.
+ */
+export declare const BUTTON_TYPES: readonly ["contained", "outlined", "text", "textGray", "textWhite"];
+export declare const BUTTON_COLORS: readonly ["common", "error"];
+/**
+ * `disabled` is deliberately absent. SC 1.4.3 exempts "text ... that is part of an inactive user
+ * interface component", and 1.4.11 exempts inactive components in the same words. See the
+ * exemptions section of docs/a11y-contrast.md.
+ */
+export declare const BUTTON_STATES: readonly ["base", "hover", "active", "focused"];
+export type ButtonType = (typeof BUTTON_TYPES)[number];
+export type ButtonState = (typeof BUTTON_STATES)[number];
+export interface ButtonTokenNames {
+    readonly text: string;
+    readonly background: string;
+    readonly border: string;
+}
+export declare const buttonTokenNames: (type: ButtonType, color: (typeof BUTTON_COLORS)[number], state: ButtonState) => ButtonTokenNames;
+/**
+ * Types whose boundary is a designed, always-present edge. `text` / `textGray` are borderless by
+ * design — the label carries the affordance and is held to 4.5:1, which is what SC 1.4.11's
+ * "visual information required to identify user interface components" asks for. `textWhite` is
+ * excluded from contrast assertions entirely: it is white-on-transparent, meant to be placed on a
+ * consumer-supplied dark surface this package never sees. Documented in docs/a11y-contrast.md.
+ */
+export declare const BUTTON_TYPES_WITH_BOUNDARY: readonly ButtonType[];
+export declare const BUTTON_TYPES_WITHOUT_KNOWN_SURFACE: readonly ButtonType[];
+/**
+ * Button pairs that fail against master, keyed `{type}/{color}/{state}/{aspect}`.
+ *
+ * `text-on-tinted-hover` (F-12): outlined/text/textGray put gama-500 on a gama-50 or gama-100 tint
+ * at hover and active, which drops the label under 4.5:1 in every theme.
+ * `boundary-focus` (F-07): the focus border is gama-400 everywhere, which is under 3:1 on white in
+ * default and fretex.
+ * `boundary-outlined-hover` (F-13): outlined's hover/active border is gama-300, under 3:1 in all
+ * three themes.
+ * `outlined/error/focused/text` (F-16): white label on a beta-100 tint, 1.27:1 in every theme.
+ * The error/focused boundary rows (F-15): the border points at `--colors-beta-400`, which no theme
+ * defines, so `default` and `greenish` render no focus border at all; `fretex` overrides it to
+ * gama-400 and lands at 2.24:1, which is F-07's root cause again.
+ */
+export declare const BUTTON_FINDINGS: Readonly<Record<string, string>>;
+/**
+ * Regression floors for the quarantined pairs: the ratio each one measures on master, per theme.
+ *
+ * A quarantined pair is asserted against its floor rather than against the WCAG threshold, so the
+ * suite still detects *decay* on an already-failing pair while staying green if ASMA-8133 or a
+ * design fix legitimately *improves* the number. This is a characterization test — the floor is a
+ * record of the status quo, not a standard. The real target stays in docs/a11y-contrast.md against
+ * the finding id, and lifting a quarantine means deleting the pair's `finding` key so the live SC
+ * assertion takes over.
+ *
+ * `null` means the pair has no computed value at all — see F-15, where the `var()` chain is
+ * dangling so the browser drops the declaration outright. A floor is meaningless there, so those
+ * stay skipped.
+ *
+ * Values are produced by `contrastRatio`, which already truncates to two decimals, so the floor and
+ * the measurement are byte-identical and the comparison needs no epsilon. Regenerate after
+ * ASMA-8133 lands.
+ */
+export declare const REGRESSION_FLOORS: Readonly<Record<string, Readonly<Record<string, number | null>>>>;

package/dist/src/a11y/contrast/themeContrast.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/a11y/contrast/themeTokens.d.ts

@@ -0,0 +1,36 @@
+/** The theme every other theme layers on top of; selected by `:root`, not by a `data-theme` value. */
+export declare const DEFAULT_THEME = "default";
+export type ThemeName = string;
+/**
+ * Every theme the stylesheets define, discovered rather than listed, so adding a fourth theme file
+ * automatically brings it into the contrast matrix instead of silently going unchecked.
+ */
+export declare const discoverThemeNames: () => ThemeName[];
+export declare class TokenResolutionError extends Error {
+}
+/**
+ * Follows a `var()` chain to a literal. `var(--a, fallback)` uses the fallback only when `--a` is
+ * undefined, matching CSS. A cycle or a missing terminal value throws rather than resolving to
+ * something plausible — a contrast suite that silently treats an unresolvable token as black would
+ * report passes it has not earned.
+ */
+export declare const resolveDeclaration: (declarations: ReadonlyMap<string, string>, value: string, seen?: ReadonlySet<string>) => string;
+export interface UnresolvableToken {
+    readonly property: string;
+    readonly reason: string;
+}
+export interface ThemeResolution {
+    readonly resolved: Map<string, string>;
+    /**
+     * Properties whose `var()` chain never reaches a literal. At runtime the browser treats these
+     * as invalid at computed-value time, so the declaration is dropped entirely and the element
+     * falls back to the inherited or initial value — i.e. the styling the token file *says* it
+     * applies is silently not applied. Worth a test of its own.
+     */
+    readonly unresolvable: UnresolvableToken[];
+}
+export declare const resolveTheme: (theme: ThemeName) => ThemeResolution;
+/** Every custom property that applies to `theme`, resolved to a literal value. */
+export declare const resolveThemeTokens: (theme: ThemeName) => Map<string, string>;
+/** `resolveThemeTokens` for every discovered theme, keyed by theme name. */
+export declare const resolveAllThemes: () => Map<ThemeName, Map<string, string>>;

package/dist/src/a11y/contrast/themeTokens.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/a11y/contrast/wcagContrast.d.ts

@@ -0,0 +1,32 @@
+/**
+ * WCAG 2.2 contrast maths, kept dependency-free and side-effect-free so it can be exercised from a
+ * plain node-environment vitest run (the `unit` project in vite.config.ts) with no DOM.
+ *
+ * Only the colour notations the theme CSS actually uses are supported — `#rgb` / `#rgba` /
+ * `#rrggbb` / `#rrggbbaa`, `rgb()` / `rgba()` (comma or space separated), and the `white` / `black`
+ * / `transparent` keywords. Anything else returns `null` rather than guessing, so an unparsed value
+ * surfaces as a loud failure instead of a silently-skipped assertion.
+ *
+ * @see https://www.w3.org/TR/WCAG22/#dfn-relative-luminance
+ * @see https://www.w3.org/TR/WCAG22/#dfn-contrast-ratio
+ */
+export interface Rgba {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    /** 0–1. */
+    readonly a: number;
+}
+export declare const parseCssColor: (value: string) => Rgba | null;
+/** Source-over compositing. `backdrop` must be opaque; the result always is. */
+export declare const compositeOver: (source: Rgba, backdrop: Rgba) => Rgba;
+export declare const relativeLuminance: ({ r, g, b }: Rgba) => number;
+/**
+ * Contrast ratio of two opaque colours, truncated to two decimals.
+ *
+ * Truncated rather than rounded, for two reasons. It is conservative at the threshold — rounding
+ * would report a true 4.4951:1 as "4.5" and let a failing pair through — and it is what axe-core
+ * reports, so a ratio quoted in docs/a11y-contrast.md is digit-for-digit the same number as the
+ * one in the axe baseline in docs/a11y-allowlist.md.
+ */
+export declare const contrastRatio: (first: Rgba, second: Rgba) => number;

package/dist/src/a11y/contrast/wcagContrast.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -3,7 +3,7 @@
     "publishConfig": {
         "access": "public"
     },
-    "version": "3.78.4",
+    "version": "3.78.6",
     "type": "module",
     "sideEffects": [
         "**/*.css",
@@ -66,6 +66,7 @@
         "vrt:accept": "bash scripts/vrt.sh accept",
         "vrt:report": "playwright show-report",
         "test-storybook": "npx vitest --project=storybook",
+        "test:interaction": "vitest --project=interaction --run",
         "changeset:pre-beta": "changeset pre enter beta",
         "changeset:pre-exit": "changeset pre exit",
         "changeset:version": "changeset version",