@valancex/style 0.0.0-stage → 0.14.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @valancex/style
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The style contract of VALANCE (Bet 6; decisions S1 to S8): what a theme may depend on, as data, and what is generated or checked from it. You rarely import this package: `vlx` uses it. A project gets the default theme with nothing written.
+
+## What a theme depends on
+
+Five things, and nothing else (not an element, a class, or the order of wrappers):
+
+| Thing | Meaning |
+|---|---|
+| **Token** | A named design decision (a color role, a space step, a type role, a radius), in the [Design Tokens](https://www.designtokens.org/) format (2025.10), one document per **mode** (`light`, `dark`, `contrast`) over a base document |
+| **Part** | A named region of a primitive. Only `root` exists (S1) |
+| **State** | `hovered`, `pressed`, `focus-visible` (every interactive primitive) and the semantic states a primitive's specification declares (`checked`, `invalid`, `disabled`) |
+| **Variant** | A closed set a template chooses from: `intent` (`neutral`, `primary`, `danger`) and `size` (`sm`, `md`, `lg`) |
+| **Condition** | `viewport` (compact, medium, expanded), `scheme`, `contrast`, `forced-colors`, `reduced-motion`, `target` |
+
+A **recipe** (`recipes/<primitive>.json`) maps a part, a variant, a state and a condition to declarations from a closed set of properties: `background`, `text`, `border`, `radius`, `padding`, `gap`, `min-size`, `type`, `elevation`, `opacity`, `outline`, `align`. A value is a token path (or a keyword, or a number for `opacity`).
+
+## The three tiers
+
+1. **Tier 1, nothing to write.** The default theme styles the seven primitives of the portable core on the web and on the desktop.
+2. **Tier 2, opt in.** A `theme/` directory with a `theme.json` replaces the default, whole: your token documents and recipes. `vlx theme check` says what is wrong and what each target applies; `vlx check` and `vlx build` refuse a theme with a mistake in it. `intent` and `size` on a `button` choose a variant.
+3. **Tier 3, the marked way out.** A recipe's `escape.web.css` holds CSS for a property outside the contract, for the web only; a project's own stylesheet, in no layer, wins over every layer.
+
+## What is generated
+
+- **Web:** one static stylesheet, the same on the server and in the browser, in cascade layers (`vlx-library`, `vlx-theme`, `vlx-app`, later layers winning). It reaches a primitive only by its hook `[data-vlx="button"]`, a variant's attribute, a state's selector and a media query.
+- **Desktop:** the theme resolved (colors as hex, lengths in points, only what the window applies), given to the window once with `appearance`.
+
+## What is checked
+
+The tokens against the Design Tokens Community Group's own schemas and test suite (vendored unchanged in `schema/dtcg-2025.10/` and `test/fixtures/dtcg-2025.10/`) plus a graph pass (`$extends`, aliases, JSON Pointer references, cycles, the type of the target); every recipe against the contract and the primitives' specifications; the contrast of the pairs a theme declares, as WCAG 2.2 defines it; the compiled stylesheet with stylelint; and the default theme in Chromium against its tokens.
+
+Private data in `contract/` and `schema/`; the code is `src/`.

package/contract/style-contract-v1.json

@@ -0,0 +1,207 @@
+{
+  "version": 1,
+  "note": "The style contract (Bet 6; decisions S1 to S8, P3): the five things a theme may depend on. Everything else (the element, its class, the order of wrappers) is not part of it.",
+  "parts": {
+    "root": "The primitive itself: the one element or widget that is the primitive. The only part until a realization shows it needs another (S1)."
+  },
+  "interactionStates": {
+    "hovered": ":hover",
+    "pressed": ":active",
+    "focus-visible": ":focus-visible"
+  },
+  "interactionMedia": {
+    "hovered": "(any-hover: hover)"
+  },
+  "semanticStates": [
+    "checked",
+    "invalid",
+    "disabled",
+    "busy",
+    "selected"
+  ],
+  "variants": {
+    "intent": {
+      "values": [
+        "neutral",
+        "primary",
+        "danger"
+      ],
+      "default": "neutral"
+    },
+    "size": {
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    }
+  },
+  "conditions": {
+    "viewport": {
+      "values": [
+        "compact",
+        "medium",
+        "expanded"
+      ],
+      "web": {
+        "compact": "(width < 600px)",
+        "medium": "(600px <= width < 840px)",
+        "expanded": "(width >= 840px)"
+      },
+      "desktop": "supported"
+    },
+    "scheme": {
+      "values": [
+        "light",
+        "dark"
+      ],
+      "web": {
+        "light": "(prefers-color-scheme: light)",
+        "dark": "(prefers-color-scheme: dark)"
+      },
+      "desktop": "supported"
+    },
+    "contrast": {
+      "values": [
+        "more"
+      ],
+      "web": {
+        "more": "(prefers-contrast: more)"
+      },
+      "desktop": "unsupported"
+    },
+    "forced-colors": {
+      "values": [
+        "active"
+      ],
+      "web": {
+        "active": "(forced-colors: active)"
+      },
+      "desktop": "unsupported"
+    },
+    "reduced-motion": {
+      "values": [
+        "reduce"
+      ],
+      "web": {
+        "reduce": "(prefers-reduced-motion: reduce)"
+      },
+      "desktop": "unsupported"
+    },
+    "target": {
+      "values": [
+        "web",
+        "desktop"
+      ],
+      "desktop": "supported"
+    }
+  },
+  "properties": {
+    "background": {
+      "accepts": "color",
+      "web": [
+        "background-color"
+      ],
+      "desktop": "supported"
+    },
+    "text": {
+      "accepts": "color",
+      "web": [
+        "color"
+      ],
+      "desktop": "supported"
+    },
+    "border": {
+      "accepts": "stroke",
+      "web": [
+        "border"
+      ],
+      "desktop": "supported"
+    },
+    "radius": {
+      "accepts": "dimension",
+      "web": [
+        "border-radius"
+      ],
+      "desktop": "supported"
+    },
+    "padding": {
+      "accepts": "space-list",
+      "web": [
+        "padding"
+      ],
+      "desktop": "supported"
+    },
+    "gap": {
+      "accepts": "dimension",
+      "web": [
+        "gap"
+      ],
+      "desktop": "supported"
+    },
+    "min-size": {
+      "accepts": "dimension",
+      "web": [
+        "min-height",
+        "min-width"
+      ],
+      "desktop": "supported"
+    },
+    "type": {
+      "accepts": "typography",
+      "web": [
+        "font"
+      ],
+      "desktop": "partial"
+    },
+    "elevation": {
+      "accepts": "shadow",
+      "web": [
+        "box-shadow"
+      ],
+      "desktop": "unsupported"
+    },
+    "opacity": {
+      "accepts": "opacity",
+      "web": [
+        "opacity"
+      ],
+      "desktop": "unsupported"
+    },
+    "outline": {
+      "accepts": "stroke",
+      "web": [
+        "outline",
+        "outline-offset"
+      ],
+      "desktop": "partial"
+    },
+    "align": {
+      "accepts": "alignment",
+      "web": [
+        "align-items"
+      ],
+      "desktop": "unsupported"
+    }
+  },
+  "desktopNotes": {
+    "type": "The size of the type role; the family and weight are the toolkit's.",
+    "outline": "The focus ring's color and width; the toolkit draws its own ring.",
+    "states": "`hovered` and `pressed` are applied to a button (the pointer over it, and held down; the properties the Desktop honors). The toolkit draws its own focus ring, so `focus-visible` is web only. `invalid` and `disabled` are applied."
+  },
+  "modeConditions": {
+    "dark": "scheme:dark",
+    "contrast": "contrast:more"
+  },
+  "desktopStates": {
+    "hovered": "supported",
+    "pressed": "supported",
+    "focus-visible": "unsupported",
+    "invalid": "supported",
+    "disabled": "supported",
+    "checked": "unsupported",
+    "busy": "unsupported",
+    "selected": "unsupported"
+  }
+}

package/dist/check.d.ts

@@ -0,0 +1,31 @@
+import type { Contract, LoadedTheme, PrimitiveInfo, Problem, Recipe } from "./types.js";
+export interface Inputs {
+    readonly contract: Contract;
+    readonly primitives: Readonly<Record<string, PrimitiveInfo>>;
+}
+export declare const defaultInputs: () => Inputs;
+/** The selector that reaches a primitive's root on the web: its hook attribute, which names the primitive and nothing about its element. Undefined where the web has no hook for it. */
+export declare const hookOf: (inputs: Inputs, primitive: string) => string | undefined;
+/** The states a recipe for `primitive` may style: the interaction states if a person acts on it, and the semantic states its specification declares. */
+export declare const statesOf: (inputs: Inputs, primitive: string) => ReadonlyArray<string>;
+/** The problems in one recipe. */
+export declare const checkRecipe: (file: string, recipe: Recipe, modes: LoadedTheme["modes"], inputs: Inputs) => Problem[];
+/** The contrast of every pair a theme declares, in each mode it applies to. `ratio` is what WCAG 2.2 computes (see contrast.ts). */
+export interface ContrastResult {
+    readonly mode: string;
+    readonly text: string;
+    readonly on: string;
+    readonly min: number;
+    readonly ratio: number;
+    readonly passes: boolean;
+}
+export declare const contrastOf: (loaded: LoadedTheme) => {
+    readonly results: ReadonlyArray<ContrastResult>;
+    readonly problems: ReadonlyArray<Problem>;
+};
+export interface Checked {
+    readonly problems: ReadonlyArray<Problem>;
+    readonly contrast: ReadonlyArray<ContrastResult>;
+}
+/** Everything about a loaded theme that can be wrong: what loading found, each recipe, and the contrast. */
+export declare const checkTheme: (loaded: LoadedTheme, inputs?: Inputs) => Checked;

package/dist/check.js

@@ -0,0 +1,250 @@
+// The checks of a loaded theme that need the primitives' specifications: a recipe names a part, state, variant, property and token that exist, a value has the type the property takes, a focus indicator
+// is not removed, and the contrast of the declared pairs. Each is an error with a code, the file and a path into it; a suggestion where a near name exists.
+import { toRgb } from "./color.js";
+import { composite, ratio } from "./contrast.js";
+import { loadContract } from "./load.js";
+import { primitives } from "./primitives.js";
+import { didYouMean } from "./suggest.js";
+export const defaultInputs = () => ({ contract: loadContract(), primitives });
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The selector that reaches a primitive's root on the web: its hook attribute, which names the primitive and nothing about its element. Undefined where the web has no hook for it. */
+export const hookOf = (inputs, primitive) => {
+    const hook = inputs.primitives[primitive]?.hook;
+    return hook === undefined ? undefined : `[data-vlx="${hook}"]`;
+};
+/** The states a recipe for `primitive` may style: the interaction states if a person acts on it, and the semantic states its specification declares. */
+export const statesOf = (inputs, primitive) => {
+    const info = inputs.primitives[primitive];
+    if (info === undefined) {
+        return [];
+    }
+    return [...(info.interactive ? Object.keys(inputs.contract.interactionStates) : []), ...info.states.filter((state) => inputs.contract.semanticStates.includes(state))];
+};
+/** Whether `path` is a token of type `type` in every mode; the message of the first mode that is not. */
+const tokenProblem = (modes, path, types) => {
+    for (const [mode, tokens] of Object.entries(modes)) {
+        const token = tokens.get(path);
+        if (token === undefined) {
+            const near = didYouMean(path, [...tokens.keys()].filter((each) => types.includes(tokens.get(each).type)));
+            return `${path} is not a token${Object.keys(modes).length > 1 ? ` in the ${mode} mode` : ""}${near}`;
+        }
+        if (!types.includes(token.type)) {
+            return `${path} is a ${token.type} token, and ${types.length === 1 ? `a ${types[0]}` : `one of ${types.join(", ")}`} is needed here`;
+        }
+    }
+    return undefined;
+};
+const ALIGN = ["start", "center", "end", "stretch"];
+/** What is wrong with `value` as the value of a property that takes `accepts`, or undefined. */
+const valueProblem = (accepts, value, property, modes) => {
+    switch (accepts) {
+        case "color":
+            return typeof value === "string" ? tokenProblem(modes, value, ["color"]) : `${property} takes a color token`;
+        case "dimension":
+            return typeof value === "string" ? (value === "0" ? undefined : tokenProblem(modes, value, ["dimension"])) : `${property} takes a dimension token`;
+        case "space-list": {
+            const list = typeof value === "string" ? [value] : Array.isArray(value) ? value : undefined;
+            if (list === undefined) {
+                return `${property} takes a dimension token, or one to four of them`;
+            }
+            for (const each of list) {
+                const problem = each === "0" ? undefined : tokenProblem(modes, each, ["dimension"]);
+                if (problem !== undefined) {
+                    return problem;
+                }
+            }
+            return undefined;
+        }
+        case "stroke": {
+            if (value === "none") {
+                return undefined;
+            }
+            if (!isObject(value) || typeof value["width"] !== "string" || typeof value["color"] !== "string") {
+                return `${property} takes "none" or { width, color } (a dimension token and a color token)`;
+            }
+            return (tokenProblem(modes, value["width"], ["dimension"]) ??
+                tokenProblem(modes, value["color"], ["color"]) ??
+                (typeof value["offset"] === "string" ? tokenProblem(modes, value["offset"], ["dimension"]) : undefined));
+        }
+        case "typography":
+            return typeof value === "string" ? tokenProblem(modes, value, ["typography"]) : `${property} takes a typography token`;
+        case "shadow":
+            return value === "none" ? undefined : typeof value === "string" ? tokenProblem(modes, value, ["shadow"]) : `${property} takes "none" or a shadow token`;
+        case "opacity":
+            return typeof value === "number" && value >= 0 && value <= 1 ? undefined : `${property} takes a number from 0 to 1`;
+        case "alignment":
+            return typeof value === "string" && ALIGN.includes(value)
+                ? undefined
+                : `${property} takes one of ${ALIGN.join(", ")}${typeof value === "string" ? didYouMean(value, ALIGN) : ""}`;
+    }
+};
+const declarationProblems = (file, where, declarations, inputs, modes) => {
+    const problems = [];
+    for (const [property, value] of Object.entries(declarations)) {
+        const definition = inputs.contract.properties[property];
+        if (definition === undefined) {
+            problems.push({
+                file,
+                path: `${where}/${property}`,
+                code: "unknown-property",
+                message: `${property} is not a property of the style contract${didYouMean(property, Object.keys(inputs.contract.properties))}; a property outside it goes in \`escape\`, for one target`,
+            });
+            continue;
+        }
+        const problem = valueProblem(definition.accepts, value, property, modes);
+        if (problem !== undefined) {
+            problems.push({ file, path: `${where}/${property}`, code: problem.includes("is not a token") ? "unresolved-token" : "bad-value", message: problem });
+        }
+    }
+    return problems;
+};
+const removesFocus = (declarations) => declarations !== undefined && declarations["outline"] === "none";
+/** The problems in one recipe. */
+export const checkRecipe = (file, recipe, modes, inputs) => {
+    const problems = [];
+    const { primitive, part } = recipe.target;
+    const info = inputs.primitives[primitive];
+    if (info === undefined) {
+        return [
+            { file, path: "/target/primitive", code: "unknown-primitive", message: `there is no primitive "${primitive}"${didYouMean(primitive, Object.keys(inputs.primitives))}` },
+        ];
+    }
+    if (inputs.contract.parts[part] === undefined) {
+        problems.push({
+            file,
+            path: "/target/part",
+            code: "unknown-part",
+            message: `"${part}" is not a part${didYouMean(part, Object.keys(inputs.contract.parts))}; the parts are ${Object.keys(inputs.contract.parts).join(", ")}`,
+        });
+    }
+    if (info.status === "desktop-only") {
+        problems.push({ file, path: "/target/primitive", code: "not-on-the-web", message: `${primitive} is desktop-only; the web has no element for it` });
+    }
+    problems.push(...declarationProblems(file, "/base", recipe.base ?? {}, inputs, modes));
+    for (const [variant, values] of Object.entries(recipe.variants ?? {})) {
+        const definition = inputs.contract.variants[variant];
+        if (definition === undefined || !info.variants.some((each) => each.name === variant)) {
+            const known = info.variants.map((each) => each.name).filter((each) => inputs.contract.variants[each] !== undefined);
+            problems.push({
+                file,
+                path: `/variants/${variant}`,
+                code: "unknown-variant",
+                message: `${primitive} has no variant "${variant}"${didYouMean(variant, known)}${known.length === 0 ? "; it takes none" : `; it takes ${known.join(", ")}`}`,
+            });
+            continue;
+        }
+        for (const [value, declarations] of Object.entries(values)) {
+            if (!definition.values.includes(value)) {
+                problems.push({
+                    file,
+                    path: `/variants/${variant}/${value}`,
+                    code: "unknown-variant-value",
+                    message: `${variant} has no value "${value}"${didYouMean(value, definition.values)}; the values are ${definition.values.join(", ")}`,
+                });
+            }
+            problems.push(...declarationProblems(file, `/variants/${variant}/${value}`, declarations, inputs, modes));
+        }
+    }
+    const allowed = statesOf(inputs, primitive);
+    for (const [state, declarations] of Object.entries(recipe.states ?? {})) {
+        if (!allowed.includes(state)) {
+            problems.push({
+                file,
+                path: `/states/${state}`,
+                code: "unknown-state",
+                message: `${primitive} has no state "${state}"${didYouMean(state, allowed)}; its states are ${allowed.length === 0 ? "none" : allowed.join(", ")}`,
+            });
+        }
+        else if (!(state in inputs.contract.interactionStates) && info.stateSelectors[state] === undefined) {
+            problems.push({ file, path: `/states/${state}`, code: "state-unreachable", message: `the web has no selector for the state "${state}" of ${primitive}` });
+        }
+        problems.push(...declarationProblems(file, `/states/${state}`, declarations, inputs, modes));
+    }
+    for (const [condition, declarations] of Object.entries(recipe.when ?? {})) {
+        const [name, value] = condition.split(":");
+        const definition = inputs.contract.conditions[name];
+        if (definition === undefined) {
+            problems.push({
+                file,
+                path: `/when/${condition}`,
+                code: "unknown-condition",
+                message: `"${name}" is not a condition${didYouMean(name, Object.keys(inputs.contract.conditions))}; the conditions are ${Object.keys(inputs.contract.conditions).join(", ")}`,
+            });
+        }
+        else if (!definition.values.includes(value)) {
+            problems.push({
+                file,
+                path: `/when/${condition}`,
+                code: "unknown-condition-value",
+                message: `${name} has no value "${value}"${didYouMean(value, definition.values)}; the values are ${definition.values.join(", ")}`,
+            });
+        }
+        problems.push(...declarationProblems(file, `/when/${condition}`, declarations, inputs, modes));
+    }
+    // A recipe that removes the focus indicator must put another in its place: it is detectable in static data.
+    const focus = recipe.states?.["focus-visible"]?.["outline"];
+    const replaced = isObject(focus);
+    const removed = removesFocus(recipe.base) ||
+        Object.values(recipe.variants ?? {}).some((values) => Object.values(values).some(removesFocus)) ||
+        removesFocus(recipe.states?.["focus-visible"]) ||
+        Object.values(recipe.when ?? {}).some(removesFocus) ||
+        /outline(-style)?\s*:\s*(none|0)\b/.test(recipe.escape?.web?.css ?? "");
+    if (removed && !replaced) {
+        problems.push({
+            file,
+            path: "/states/focus-visible",
+            code: "focus-removed",
+            message: `${primitive}'s recipe removes the focus indicator and does not give another: set states.focus-visible.outline to a width and a color`,
+        });
+    }
+    return problems;
+};
+export const contrastOf = (loaded) => {
+    const results = [];
+    const problems = [];
+    const file = "theme.json";
+    for (const pair of loaded.theme.contrast ?? []) {
+        for (const [mode, tokens] of Object.entries(loaded.modes)) {
+            if (pair.modes !== undefined && !pair.modes.includes(mode)) {
+                continue;
+            }
+            const text = tokens.get(pair.text);
+            const on = tokens.get(pair.on);
+            if (text?.type !== "color" || on?.type !== "color") {
+                problems.push({
+                    file,
+                    path: `/contrast`,
+                    code: "contrast-unresolved",
+                    message: `${text?.type !== "color" ? pair.text : pair.on} is not a color token in the ${mode} mode`,
+                });
+                continue;
+            }
+            try {
+                const surface = toRgb(on.value);
+                const value = ratio(composite(toRgb(text.value), surface), surface);
+                const passes = value + 1e-9 >= pair.min;
+                results.push({ mode, text: pair.text, on: pair.on, min: pair.min, ratio: value, passes });
+                if (!passes) {
+                    problems.push({
+                        file,
+                        path: "/contrast",
+                        code: "contrast-below-minimum",
+                        message: `${pair.text} on ${pair.on} is ${value.toFixed(2)}:1 in the ${mode} mode, below the ${pair.min}:1 the theme declares`,
+                    });
+                }
+            }
+            catch (error) {
+                problems.push({ file, path: "/contrast", code: "contrast-unsupported", message: error instanceof Error ? error.message : String(error) });
+            }
+        }
+    }
+    return { results, problems };
+};
+/** Everything about a loaded theme that can be wrong: what loading found, each recipe, and the contrast. */
+export const checkTheme = (loaded, inputs = defaultInputs()) => {
+    const contrast = contrastOf(loaded);
+    return {
+        problems: [...loaded.problems, ...loaded.recipes.flatMap(({ file, recipe }) => checkRecipe(file, recipe, loaded.modes, inputs)), ...contrast.problems],
+        contrast: contrast.results,
+    };
+};

package/dist/color.d.ts

@@ -0,0 +1,17 @@
+export interface Rgb {
+    /** 0 to 1, gamma-encoded sRGB. */
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a: number;
+}
+export interface DtcgColor {
+    readonly colorSpace: string;
+    readonly components: ReadonlyArray<number | "none">;
+    readonly alpha?: number;
+    readonly hex?: string;
+}
+/** The color as gamma-encoded sRGB, clipped to the gamut. Throws for a color space this package does not convert. */
+export declare const toRgb: (color: DtcgColor) => Rgb;
+/** The color as CSS: `#rrggbb` (or `#rrggbbaa`) for sRGB, and the space's own function for the others, so a wide-gamut color is not narrowed on the web. */
+export declare const toCss: (color: DtcgColor) => string;

package/dist/color.js

@@ -0,0 +1,82 @@
+const clamp = (value) => Math.min(1, Math.max(0, value));
+const component = (value) => (value === "none" ? 0 : value);
+const encode = (linear) => (Math.abs(linear) <= 0.0031308 ? 12.92 * linear : Math.sign(linear) * (1.055 * Math.abs(linear) ** (1 / 2.4) - 0.055));
+const decode = (encoded) => (Math.abs(encoded) <= 0.04045 ? encoded / 12.92 : Math.sign(encoded) * ((Math.abs(encoded) + 0.055) / 1.055) ** 2.4);
+const fromOklab = (lightness, a, b) => {
+    const l = (lightness + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+    const m = (lightness - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+    const s = (lightness - 0.0894841775 * a - 1.291485548 * b) ** 3;
+    return [4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s, -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s, -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s];
+};
+const fromHsl = (hue, saturation, lightness) => {
+    const s = saturation / 100;
+    const l = lightness / 100;
+    const k = (n) => (n + hue / 30) % 12;
+    const a = s * Math.min(l, 1 - l);
+    const f = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+    return [f(0), f(8), f(4)];
+};
+/** Display P3 (gamma-encoded) to linear sRGB, through XYZ (D65). */
+const fromDisplayP3 = (r, g, b) => {
+    const [lr, lg, lb] = [decode(r), decode(g), decode(b)];
+    const x = 0.4865709486482162 * lr + 0.26566769316909306 * lg + 0.1982172852343625 * lb;
+    const y = 0.2289745640697488 * lr + 0.6917385218365064 * lg + 0.079286914093745 * lb;
+    const z = 0.04511338185890264 * lg + 1.043944368900976 * lb;
+    return [
+        3.2409699419045226 * x - 1.537383177570094 * y - 0.4986107602930034 * z,
+        -0.9692436362808796 * x + 1.8759675015077202 * y + 0.04155505740717559 * z,
+        0.05563007969699366 * x - 0.20397695888897652 * y + 1.0569715142428786 * z,
+    ];
+};
+/** The color as gamma-encoded sRGB, clipped to the gamut. Throws for a color space this package does not convert. */
+export const toRgb = (color) => {
+    const c = color.components.map(component);
+    const a = color.alpha ?? 1;
+    const [c0 = 0, c1 = 0, c2 = 0] = c;
+    switch (color.colorSpace) {
+        case "srgb":
+            return { r: clamp(c0), g: clamp(c1), b: clamp(c2), a };
+        case "srgb-linear":
+            return { r: clamp(encode(c0)), g: clamp(encode(c1)), b: clamp(encode(c2)), a };
+        case "hsl": {
+            const [r, g, b] = fromHsl(c0, c1, c2);
+            return { r: clamp(r), g: clamp(g), b: clamp(b), a };
+        }
+        case "oklab":
+        case "oklch": {
+            const [lr, lg, lb] = color.colorSpace === "oklab" ? fromOklab(c0, c1, c2) : fromOklab(c0, c1 * Math.cos((c2 * Math.PI) / 180), c1 * Math.sin((c2 * Math.PI) / 180));
+            return { r: clamp(encode(lr)), g: clamp(encode(lg)), b: clamp(encode(lb)), a };
+        }
+        case "display-p3": {
+            const [lr, lg, lb] = fromDisplayP3(c0, c1, c2);
+            return { r: clamp(encode(lr)), g: clamp(encode(lg)), b: clamp(encode(lb)), a };
+        }
+        default:
+            throw new Error(`the color space "${color.colorSpace}" is not one this package converts (srgb, srgb-linear, hsl, oklab, oklch, display-p3)`);
+    }
+};
+const byte = (value) => Math.round(clamp(value) * 255)
+    .toString(16)
+    .padStart(2, "0");
+const number = (value) => String(Math.round(value * 10000) / 10000);
+/** The color as CSS: `#rrggbb` (or `#rrggbbaa`) for sRGB, and the space's own function for the others, so a wide-gamut color is not narrowed on the web. */
+export const toCss = (color) => {
+    const c = color.components.map((each) => (each === "none" ? "none" : number(each)));
+    const alpha = color.alpha === undefined || color.alpha === 1 ? "" : ` / ${number(color.alpha)}`;
+    switch (color.colorSpace) {
+        case "srgb": {
+            const rgb = toRgb(color);
+            return `#${byte(rgb.r)}${byte(rgb.g)}${byte(rgb.b)}${rgb.a === 1 ? "" : byte(rgb.a)}`;
+        }
+        case "oklch":
+        case "oklab":
+            return `${color.colorSpace}(${c.join(" ")}${alpha})`;
+        case "hsl":
+            return `hsl(${c[0]} ${c[1]}% ${c[2]}%${alpha})`;
+        case "display-p3":
+        case "srgb-linear":
+            return `color(${color.colorSpace} ${c.join(" ")}${alpha})`;
+        default:
+            throw new Error(`the color space "${color.colorSpace}" is not one this package converts`);
+    }
+};

package/dist/contrast.d.ts

@@ -0,0 +1,5 @@
+import type { Rgb } from "./color.js";
+export declare const luminance: ({ r, g, b }: Rgb) => number;
+/** `over` composited on `under` (alpha compositing in gamma-encoded sRGB, as browsers do). */
+export declare const composite: (over: Rgb, under: Rgb) => Rgb;
+export declare const ratio: (a: Rgb, b: Rgb) => number;

package/dist/contrast.js

@@ -0,0 +1,13 @@
+const linear = (channel) => (channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4);
+export const luminance = ({ r, g, b }) => 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+/** `over` composited on `under` (alpha compositing in gamma-encoded sRGB, as browsers do). */
+export const composite = (over, under) => ({
+    r: over.r * over.a + under.r * (1 - over.a),
+    g: over.g * over.a + under.g * (1 - over.a),
+    b: over.b * over.a + under.b * (1 - over.a),
+    a: 1,
+});
+export const ratio = (a, b) => {
+    const [light, dark] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (light + 0.05) / (dark + 0.05);
+};