@cueplusplus/theme-base 1.0.2

package/dist/contrast.mjs

@@ -0,0 +1,226 @@
+import { converter, parse } from "culori";
+//#region src/contrast.ts
+/**
+* WCAG contrast, and the eleven pairs a theme is judged on.
+*
+* A generator that only derived colours would be a colour toy: the reason to
+* compute a palette instead of picking one is that the computer can then *check*
+* it, on every build, against the one part of visual design that is not a matter
+* of taste. So `createTheme()` never hands back a theme without a report, and
+* the report is the deliverable — a failing pair is information, not an error to
+* swallow.
+*
+* The maths is WCAG 2.x relative luminance (sRGB, linearised, 0.2126/0.7152/
+* 0.0722), deliberately not APCA. APCA is better, and it is also not what
+* anyone's compliance checklist says; a theme that has to survive an audit needs
+* the number the audit will compute.
+*/
+const toRgb = converter("rgb");
+/** Non-text and large-text AA: UI components, graphics, status dots. */
+const WCAG_AA_NON_TEXT = 3;
+/** Body-text AA. The floor for anything a reader is expected to read. */
+const WCAG_AA_TEXT = 4.5;
+/** Body-text AAA. What this portfolio holds its primary ink to. */
+const WCAG_AAA_TEXT = 7;
+/** sRGB gamma decode, per WCAG's definition of relative luminance. */
+function linearize(channel) {
+	return channel <= .04045 ? channel / 12.92 : ((channel + .055) / 1.055) ** 2.4;
+}
+/** Parse to sRGB, or say which value could not be read. */
+function toSrgb(input, label = "colour") {
+	const color = toRgb(parse(input));
+	if (color === void 0) throw new TypeError(`${label} is not a colour this can measure: ${JSON.stringify(input)}`);
+	return color;
+}
+/** Source-over composite of `over` onto `under`, in (non-linear) sRGB. */
+function composite(over, under) {
+	const alpha = over.alpha ?? 1;
+	if (alpha >= 1) return over;
+	return {
+		r: over.r * alpha + under.r * (1 - alpha),
+		g: over.g * alpha + under.g * (1 - alpha),
+		b: over.b * alpha + under.b * (1 - alpha)
+	};
+}
+function luminanceOf(color) {
+	return .2126 * linearize(color.r) + .7152 * linearize(color.g) + .0722 * linearize(color.b);
+}
+/**
+* WCAG relative luminance: 0 for black, 1 for white.
+*
+* Alpha is ignored — a translucent colour has no luminance of its own, only one
+* in front of something. {@link contrastRatio} is where that composite happens.
+*
+* @param color - Any CSS colour string.
+* @returns Relative luminance in `[0, 1]`.
+* @throws TypeError if the value is not a colour.
+* @example
+* relativeLuminance("#767676"); // → 0.1845…
+*/
+function relativeLuminance(color) {
+	return luminanceOf(toSrgb(color));
+}
+/**
+* WCAG contrast ratio between two colours, from 1:1 to 21:1.
+*
+* Symmetric, because a ratio has no direction — the arguments are named for
+* readability, not for order. A **translucent foreground is composited over the
+* background first**, which is not decoration: half this system's `fg-muted`
+* tokens are white-alpha ink, and measuring them raw would report the ratio of
+* pure white and pass everything.
+*
+* @param foreground - The ink. Composited over `background` if it has alpha.
+* @param background - The ground. Its own alpha is ignored — nothing is behind it.
+* @returns The ratio, `>= 1`.
+* @throws TypeError naming whichever value could not be read.
+* @example
+* contrastRatio("#767676", "#ffffff"); // → 4.5422…
+*/
+function contrastRatio(foreground, background) {
+	const ground = toSrgb(background, "background");
+	const [high, low] = [luminanceOf(composite(toSrgb(foreground, "foreground"), ground)), luminanceOf(ground)].toSorted((a, b) => b - a);
+	return (high + .05) / (low + .05);
+}
+/**
+* The eleven pairs that decide whether a theme is usable, and the nine that
+* warn about it.
+*
+* Not every pair in the palette: the ones a reader's comprehension actually
+* depends on. Primary ink is held to AAA because it carries the prose; secondary
+* ink and accent ink to AA because they carry labels; the five status colours
+* and the live hue to the non-text AA floor because they are read as *signals*
+* — a dot, a rim, a bar — never as body copy.
+*
+* `danger` and `warn` each appear twice, and they are the only tones that do.
+* `ok`, `busy`, `info` and `stream` are *only* ever signals, so the non-text
+* floor is the whole truth about them. The red and the amber are also grounds:
+* they are the two tones this system fills a control with, and what they fill is
+* the confirm on something irreversible and the confirm on something merely
+* consequential. Text on either fill is text, so its ink is held to the text
+* floor against the tone it sits on rather than against the page.
+*
+* `stream` is measured for the same reason `ok` is: `createTheme()` darkens it
+* to this floor when it has to invent a light block, and a report that did not
+* check what the derivation targets would be checking the wrong thing.
+*/
+/**
+* Every ground a control can paint a ring over.
+*
+* Module-local on purpose. It is the same set the preset gate has always walked,
+* and it is a fact about where controls sit rather than part of the contract a
+* consumer reads — exporting it would invite a caller to hold their own themes
+* to a list this file is free to grow.
+*
+* None of the eleven required pairs involves `sunken` or any `surface-*` rung,
+* which is the other half of why the ring went unmeasured: a consumer overriding
+* `surfaces`, which `ThemeAnchors` invites, moves the grounds the ring is painted
+* on without moving a single measured pair.
+*/
+const RING_GROUNDS = [
+	"sunken",
+	"bg",
+	"surface-1",
+	"surface-2",
+	"surface-3"
+];
+const CONTRAST_REQUIREMENTS = [
+	{
+		id: "fg/bg",
+		foreground: "fg",
+		background: "bg",
+		minimum: 7,
+		reason: "Primary ink carries the prose, and this portfolio holds it to AAA."
+	},
+	{
+		id: "fg-muted/bg",
+		foreground: "fg-muted",
+		background: "bg",
+		minimum: WCAG_AA_TEXT,
+		reason: "Secondary ink is still text: labels, captions, table headers."
+	},
+	{
+		id: "accent-fg/accent",
+		foreground: "accent-fg",
+		background: "accent",
+		minimum: WCAG_AA_TEXT,
+		reason: "The label on a solid accent button has to be readable."
+	},
+	{
+		id: "danger-fg/danger",
+		foreground: "danger-fg",
+		background: "danger",
+		minimum: WCAG_AA_TEXT,
+		reason: "The label on a solid destructive fill is read before something irreversible happens."
+	},
+	{
+		id: "warn-fg/warn",
+		foreground: "warn-fg",
+		background: "warn",
+		minimum: WCAG_AA_TEXT,
+		reason: "The label on a solid warning fill is read before a consequential press lands."
+	},
+	...[
+		"ok",
+		"busy",
+		"warn",
+		"danger",
+		"info",
+		"stream"
+	].map((status) => ({
+		id: `${status}/bg`,
+		foreground: status,
+		background: "bg",
+		minimum: 3,
+		reason: `The ${status} tone is read as a signal — dot, rim, bar — not as body copy.`
+	})),
+	...["focus", "danger"].flatMap((ring) => RING_GROUNDS.filter((ground) => !(ring === "danger" && ground === "bg")).map((ground) => ({
+		id: `${ring}/${ground}`,
+		foreground: ring,
+		background: ground,
+		minimum: 3,
+		advisory: true,
+		reason: ring === "focus" ? "The focus ring is the only thing telling a keyboard user where they are (WCAG 1.4.11)." : "An invalid field's ring replaces its rim, so the ring itself carries the state."
+	})))
+];
+/**
+* Measure every requirement against every block handed in.
+*
+* A pair whose tokens are missing is **skipped**, not failed: the report says
+* what it measured, and a caller checking a partial palette should not be told
+* that a colour it never supplied is unreadable.
+*
+* @param inputs - One entry per block, dark first by convention.
+* @returns The report.
+* @example
+* contrastReport([{ mode: "dark", tokens: { fg: "#fff", bg: "#000" } }]).passes; // → true
+*/
+function contrastReport(inputs) {
+	const checks = [];
+	for (const { mode, tokens, provisional = false } of inputs) for (const requirement of CONTRAST_REQUIREMENTS) {
+		const foregroundValue = tokens[requirement.foreground];
+		const backgroundValue = tokens[requirement.background];
+		if (foregroundValue === void 0 || backgroundValue === void 0) continue;
+		const ratio = contrastRatio(foregroundValue, backgroundValue);
+		checks.push({
+			...requirement,
+			mode,
+			foregroundValue,
+			backgroundValue,
+			ratio,
+			passes: ratio >= requirement.minimum,
+			provisional
+		});
+	}
+	const missed = checks.filter((check) => !check.passes);
+	const failures = missed.filter((check) => check.advisory !== true);
+	const advisories = missed.filter((check) => check.advisory === true);
+	return {
+		passes: failures.length === 0,
+		provisional: checks.some((check) => check.provisional),
+		checks,
+		failures,
+		advisories
+	};
+}
+//#endregion
+export { CONTRAST_REQUIREMENTS, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport, relativeLuminance };

package/dist/index.d.mts

@@ -0,0 +1,182 @@
+import { COLOR_CONTRACT, ColorToken, ColorToken as ColorToken$1, DENSITIES, Density as Density$1, FONTS, FONT_TOKENS, FontName as FontName$1, FontToken, GEOMETRY_CONTRACT, GeometryToken, GeometryToken as GeometryToken$1, MODES, Mode } from "@cueplusplus/tokens";
+//#region src/contract.d.ts
+/** The manifest format this package reads. Bumped only for a breaking shape change. */
+declare const MANIFEST_SCHEMA_VERSION: 1;
+/**
+ * What may be interpolated into `[data-theme="…"]`. The same grammar
+ * `@cueplusplus/ui/theming`'s serializer has always used: an attribute selector
+ * is the one place a theme name is written into CSS, and a name that could
+ * close the quote there is not a name.
+ */
+declare const THEME_NAME_PATTERN: RegExp;
+/**
+ * The two halves of the shared monospace token, and the resolution of them.
+ *
+ * `--cue-font-mono` is owned jointly by two axes that land on **different
+ * elements**: a provider stamps `data-theme` on a `<div>` inside the `<html>`
+ * the pre-paint script stamped `data-font` on, and for an inherited property the
+ * nearer declaration wins whatever the stylesheet's order is. So neither axis
+ * writes the shared token — the theme publishes `--cue-font-theme-mono`, a
+ * pairing publishes `--cue-font-pairing-mono`, and every block that owns a half
+ * restates `--cue-font-mono` as the `var()` chain below, pairing first.
+ *
+ * Three packages write CSS carrying that chain — `tokens`' own build,
+ * `theme-tools`' emitter and `@cueplusplus/ui`'s serializer — and none of them
+ * imports the others, so until this release each spelled it for itself and
+ * nothing compared the three. `tokens` still needs the literal to emit
+ * `axes.css`, so it stays the author and publishes the strings in `base.json`;
+ * this package re-exports them because it is the one every theme-side consumer
+ * already depends on. `tokens/test/fonts.test.mjs` holds the emitted stylesheet
+ * to the same values, so the data and the CSS cannot come apart either.
+ */
+declare const PAIRING_MONO: string;
+/** The theme axis's half. See {@link PAIRING_MONO}. */
+declare const THEME_MONO: string;
+/** What every block that owns a half resolves `--cue-font-mono` to. See {@link PAIRING_MONO}. */
+declare const RESOLVED_MONO: string;
+/**
+ * The theme registry: an empty interface a theme package augments.
+ *
+ * ```ts
+ * declare module "@cueplusplus/theme-base" {
+ *   interface ThemeRegistry { "foo": typeof manifest }
+ * }
+ * ```
+ *
+ * Quoted, as `theme-tools` emits it: `THEME_NAME_PATTERN` allows a hyphen, and
+ * `acme-brand` unquoted is not an interface key TypeScript can parse.
+ *
+ * `ThemeName` is its keys, or `string` in an app that installed no theme —
+ * `keyof {}` is `never`, and a `never`-typed prop would make `ThemeProvider`
+ * unusable until the first theme arrived, which is the wrong first experience.
+ */
+interface ThemeRegistry {}
+type ThemeName = keyof ThemeRegistry extends never ? string : keyof ThemeRegistry;
+/** The density ladder: the five base rungs, plus whatever a theme adds by augmentation. */
+interface DensityRegistry extends Record<Density$1, true> {}
+type Density = keyof DensityRegistry;
+/** The font pairings: the eight base ones, plus whatever a theme adds by augmentation. */
+interface FontRegistry extends Record<FontName$1, true> {}
+type FontName = keyof FontRegistry;
+/** A complete colour block: every token in {@link COLOR_CONTRACT}, resolved. */
+type ColorBlock = Readonly<Record<ColorToken$1, string>>;
+/** A complete geometry block: every token in {@link GEOMETRY_CONTRACT}. */
+type GeometryBlock = Readonly<Record<GeometryToken$1, string>>;
+/** A partial geometry block: only what an override changes. */
+type GeometryPatch = Readonly<Partial<Record<GeometryToken$1, string>>>;
+/** The stacks a pairing names. A pairing must name a sans; the rest are optional. */
+interface FontStacks {
+  readonly "font-sans": string;
+  readonly "font-mono"?: string;
+  readonly "font-display"?: string;
+}
+interface ManifestColors {
+  readonly dark: ColorBlock;
+  /** Absent exactly when {@link ThemeManifest.supportsLight} is false. */
+  readonly light?: ColorBlock;
+}
+interface ManifestDensities {
+  /** Rungs this theme adds. Each carries the full geometry contract. */
+  readonly adds: Readonly<Record<string, GeometryBlock>>;
+  /** Base rungs this theme retunes, scoped to itself. Each carries only what changed. */
+  readonly overrides: Readonly<Partial<Record<Density$1, GeometryPatch>>>;
+  /** The rung this theme prefers when the consumer names none. Base default when absent. */
+  readonly default?: string;
+}
+interface ManifestFontPairings {
+  readonly adds: Readonly<Record<string, FontStacks>>;
+  readonly overrides: Readonly<Partial<Record<FontName$1, Partial<FontStacks>>>>;
+  readonly default?: string;
+}
+interface ManifestContrast {
+  /** Every required pair cleared its floor. False is emitted only when every failure is waived. */
+  readonly passes: boolean;
+  /** Advisory pairs that missed. Reported, never fatal. */
+  readonly advisories: number;
+  /** Required pairs the theme named as known-bad. Counted, never silent: `passes` stays false. */
+  readonly waived: number;
+  /** `sha256-…` over the resolved colours; what a production `ThemeProvider` trusts. */
+  readonly digest: string;
+}
+/** The runtime's whole view of a theme. CSS paints; this enumerates, validates and types. */
+interface ThemeManifest {
+  readonly schemaVersion: typeof MANIFEST_SCHEMA_VERSION;
+  /** Matches {@link THEME_NAME_PATTERN}; becomes `data-theme`. */
+  readonly name: string;
+  readonly package: string;
+  /** The `theme-base` range this manifest was resolved against, e.g. `@cueplusplus/theme-base@^1`. */
+  readonly extends: string;
+  /** `delta`: `theme.css` holds only what differs from base. `complete`: it stands alone. */
+  readonly mode: "delta" | "complete";
+  readonly supportsLight: boolean;
+  readonly colors: ManifestColors;
+  /** The theme's overrides of the base stacks (a preset's `font-mono`, typically). */
+  readonly fonts: Readonly<Partial<FontStacks>>;
+  readonly densities: ManifestDensities;
+  readonly fontPairings: ManifestFontPairings;
+  readonly contrast: ManifestContrast;
+}
+//#endregion
+//#region src/validate.d.ts
+/** One thing wrong with a manifest, where it is. */
+interface ManifestProblem {
+  /** Dotted path from the root, `$` for the root itself. */
+  path: string;
+  message: string;
+}
+/**
+ * Every problem with a manifest, in document order.
+ *
+ * Hand-written rather than run through a JSON Schema library because this
+ * executes inside `ThemeProvider` in development and a schema engine is not a
+ * dependency a component library should carry for a check that runs once. The
+ * schema file beside it says the same rules in the language other tools read,
+ * and `test/validate.test.ts` holds the two to identical verdicts — on the six
+ * fixtures, and on a few hundred generated mutations of the valid one.
+ *
+ * Every rule is a sentence a theme author can act on: the message names the
+ * token that is missing, the rung that collides, the field that contradicts.
+ *
+ * The three names a theme brings — its own, its added rungs, its added pairings
+ * — are each held to {@link THEME_NAME_PATTERN}, because each one is written
+ * into an attribute selector (`[data-theme="…"]`, `[data-density="…"]`,
+ * `[data-font="…"]`) and a name that could close that quote is not a name. That
+ * pattern is case-insensitive, so a base rung or pairing is reserved in any
+ * case: `Compact` beside `compact` would be two rungs the CSS cannot tell apart.
+ */
+declare function validateManifest(value: unknown): ManifestProblem[];
+/** {@link validateManifest}, as a throw. */
+declare function assertManifest(value: unknown): asserts value is ThemeManifest;
+//#endregion
+//#region src/resolve.d.ts
+interface ResolveOptions {
+  mode: "dark" | "light";
+  density?: string;
+  font?: string;
+}
+interface ResolvedTheme {
+  colors: ColorBlock;
+  geometry: GeometryBlock;
+  fonts: Required<FontStacks>;
+  /** The rung actually used, after fallback. */
+  density: string;
+  /** The pairing actually used, after fallback. */
+  font: string;
+}
+declare function resolve(manifest: ThemeManifest | null, options: ResolveOptions): ResolvedTheme;
+interface DensityEntry {
+  name: string;
+  owner: "base" | string;
+  geometry: GeometryBlock;
+}
+/** The rungs an app may offer under the active theme: base first, then the theme's additions. */
+declare function resolveDensities(manifests: readonly ThemeManifest[], active: string | null): readonly DensityEntry[];
+interface FontEntry {
+  name: string;
+  owner: "base" | string;
+  stacks: Required<FontStacks>;
+}
+/** The pairings an app may offer under the active theme: the same rule, one axis over. */
+declare function resolveFonts(manifests: readonly ThemeManifest[], active: string | null): readonly FontEntry[];
+//#endregion
+export { COLOR_CONTRACT, ColorBlock, type ColorToken, DENSITIES, Density, type DensityEntry, DensityRegistry, FONTS, FONT_TOKENS, type FontEntry, FontName, FontRegistry, FontStacks, type FontToken, GEOMETRY_CONTRACT, GeometryBlock, GeometryPatch, type GeometryToken, MANIFEST_SCHEMA_VERSION, MODES, ManifestColors, ManifestContrast, ManifestDensities, ManifestFontPairings, type ManifestProblem, type Mode, PAIRING_MONO, RESOLVED_MONO, type ResolveOptions, type ResolvedTheme, THEME_MONO, THEME_NAME_PATTERN, ThemeManifest, ThemeName, ThemeRegistry, assertManifest, resolve, resolveDensities, resolveFonts, validateManifest };