@valancex/style 0.0.0-stage → 0.15.0

package/dist/coverage.d.ts

@@ -0,0 +1,21 @@
+import { type Inputs } from "./check.js";
+import type { LoadedTheme } from "./types.js";
+export type Target = "web" | "desktop";
+export interface NotApplied {
+    readonly primitive: string;
+    readonly kind: "property" | "condition" | "state";
+    readonly name: string;
+    readonly support: "partial" | "unsupported";
+    readonly note?: string;
+}
+export interface Coverage {
+    readonly target: Target;
+    /** The primitives the target has a hook for, and a recipe styles. */
+    readonly styled: ReadonlyArray<string>;
+    /** The primitives the target has a hook for, and no recipe styles. */
+    readonly unstyled: ReadonlyArray<string>;
+    readonly notApplied: ReadonlyArray<NotApplied>;
+}
+/** The portable-core primitives: the ones a theme must be able to style (they carry the web's hook). */
+export declare const styleable: (inputs: Inputs) => ReadonlyArray<string>;
+export declare const coverageOf: (loaded: LoadedTheme, inputs: Inputs, target: Target) => Coverage;

package/dist/coverage.js

@@ -0,0 +1,60 @@
+// Which primitives a theme styles, and what it asks that a target does not apply. A target that cannot honor something says so here, instead of the theme silently doing less (decision S5: the Desktop
+// honors the viewport and the color scheme first, and reports the rest as unsupported).
+import { hookOf } from "./check.js";
+/** The portable-core primitives: the ones a theme must be able to style (they carry the web's hook). */
+export const styleable = (inputs) => Object.keys(inputs.primitives).filter((name) => hookOf(inputs, name) !== undefined && inputs.primitives[name].status === "portable");
+export const coverageOf = (loaded, inputs, target) => {
+    const recipes = new Map(loaded.recipes.map(({ recipe }) => [recipe.target.primitive, recipe]));
+    const all = styleable(inputs);
+    const notApplied = [];
+    if (target === "desktop") {
+        const note = inputs.contract.desktopNotes ?? {};
+        for (const name of all) {
+            const recipe = recipes.get(name);
+            if (recipe === undefined) {
+                continue;
+            }
+            const properties = new Set();
+            const add = (declarations) => Object.keys(declarations ?? {}).forEach((property) => properties.add(property));
+            add(recipe.base);
+            Object.values(recipe.variants ?? {}).forEach((values) => Object.values(values).forEach(add));
+            for (const property of properties) {
+                const support = inputs.contract.properties[property]?.desktop;
+                if (support !== undefined && support !== "supported") {
+                    notApplied.push({ primitive: name, kind: "property", name: property, support, ...(note[property] === undefined ? {} : { note: note[property] }) });
+                }
+            }
+            for (const [state, declarations] of Object.entries(recipe.states ?? {})) {
+                const support = inputs.contract.desktopStates?.[state] ?? "unsupported";
+                if (support !== "supported") {
+                    notApplied.push({ primitive: name, kind: "state", name: state, support, ...(note["states"] === undefined ? {} : { note: note["states"] }) });
+                }
+                else {
+                    // a supported state still applies only the properties the Desktop honors
+                    for (const property of Object.keys(declarations)) {
+                        const propertySupport = inputs.contract.properties[property]?.desktop;
+                        if (propertySupport !== undefined && propertySupport !== "supported") {
+                            notApplied.push({ primitive: name, kind: "property", name: `${state}: ${property}`, support: propertySupport });
+                        }
+                    }
+                }
+            }
+            for (const condition of Object.keys(recipe.when ?? {})) {
+                const [kind] = condition.split(":");
+                const support = inputs.contract.conditions[kind]?.desktop;
+                if (support === "unsupported") {
+                    notApplied.push({ primitive: name, kind: "condition", name: condition, support: "unsupported" });
+                }
+            }
+        }
+        // modes the Desktop cannot choose (it has light and dark; high contrast is the person's setting, not reported to it)
+        for (const mode of Object.keys(loaded.modes)) {
+            const condition = inputs.contract.modeConditions?.[mode];
+            const kind = condition?.split(":")[0];
+            if (kind !== undefined && inputs.contract.conditions[kind]?.desktop === "unsupported") {
+                notApplied.push({ primitive: "(theme)", kind: "condition", name: `mode ${mode}`, support: "unsupported" });
+            }
+        }
+    }
+    return { target, styled: all.filter((name) => recipes.has(name)), unstyled: all.filter((name) => !recipes.has(name)), notApplied };
+};

package/dist/css.d.ts

@@ -0,0 +1,9 @@
+import { type Inputs } from "./check.js";
+import type { LoadedTheme, RecipeValue, ResolvedToken } from "./types.js";
+export declare const propertyName: (path: string) => string;
+/** The custom properties a token is: one for most, five for a typography. */
+export declare const propertiesOf: (token: ResolvedToken) => ReadonlyArray<readonly [name: string, value: string]>;
+/** The CSS declarations of one property of the contract. */
+export declare const declarationOf: (property: string, value: RecipeValue) => ReadonlyArray<string>;
+/** The stylesheet of a theme whose problems are none. */
+export declare const compileWeb: (loaded: LoadedTheme, inputs: Inputs) => string;

package/dist/css.js

@@ -0,0 +1,201 @@
+// The web's realization of a theme: one static stylesheet, the same on the server and in the browser, so nothing is inserted at run time and nothing differs at hydration.
+//
+//   @layer vlx-library, vlx-theme, vlx-app;     the layers, library first: a library's styles lose to a theme's, and a theme's to the application's own (unlayered CSS beats any layer)
+//   @layer vlx-theme { … }                      the tokens as custom properties, per mode; then each recipe's rules
+//
+// A rule reaches a primitive only by what the contract names: its hook (`[data-vlx="button"]`), a variant's attribute (`[data-intent="primary"]`), a state's selector (`:hover`,
+// `[aria-invalid="true"]`) and a media condition. Never an element, a class, or a descendant.
+import { toCss } from "./color.js";
+import { hookOf, statesOf } from "./check.js";
+const GENERIC_FAMILIES = new Set([
+    "serif",
+    "sans-serif",
+    "monospace",
+    "cursive",
+    "fantasy",
+    "system-ui",
+    "ui-serif",
+    "ui-sans-serif",
+    "ui-monospace",
+    "ui-rounded",
+    "emoji",
+    "math",
+    "fangsong",
+]);
+export const propertyName = (path) => `--vlx-${path.replaceAll(".", "-")}`;
+const dimension = (value) => {
+    const { value: amount, unit } = value;
+    return `${amount}${unit}`;
+};
+const family = (value) => (Array.isArray(value) ? value : [value])
+    .map((name) => (GENERIC_FAMILIES.has(name) || /^[A-Za-z][A-Za-z0-9-]*$/.test(name) ? name : JSON.stringify(name)))
+    .join(", ");
+const shadow = (value) => (Array.isArray(value) ? value : [value])
+    .map((each) => {
+    const s = each;
+    return `${s.inset === true ? "inset " : ""}${dimension(s.offsetX)} ${dimension(s.offsetY)} ${dimension(s.blur)} ${dimension(s.spread)} ${toCss(s.color)}`;
+})
+    .join(", ");
+/** The custom properties a token is: one for most, five for a typography. */
+export const propertiesOf = (token) => {
+    const name = propertyName(token.path);
+    switch (token.type) {
+        case "color":
+            return [[name, toCss(token.value)]];
+        case "dimension":
+            return [[name, dimension(token.value)]];
+        case "number":
+            return [[name, String(token.value)]];
+        case "fontWeight":
+            return [[name, String(token.value)]];
+        case "fontFamily":
+            return [[name, family(token.value)]];
+        case "duration":
+            return [[name, dimension(token.value)]];
+        case "shadow":
+            return [[name, shadow(token.value)]];
+        case "typography": {
+            const t = token.value;
+            return [
+                [`${name}-family`, family(t.fontFamily)],
+                [`${name}-size`, dimension(t.fontSize)],
+                [`${name}-weight`, String(t.fontWeight)],
+                [`${name}-letter-spacing`, t.letterSpacing === undefined ? "normal" : dimension(t.letterSpacing)],
+                [`${name}-line-height`, t.lineHeight === undefined ? "normal" : String(t.lineHeight)],
+            ];
+        }
+        default:
+            return [];
+    }
+};
+const variable = (path) => `var(${propertyName(path)})`;
+const stroke = (value) => `${variable(value["width"])} ${value["style"] ?? "solid"} ${variable(value["color"])}`;
+/** The CSS declarations of one property of the contract. */
+export const declarationOf = (property, value) => {
+    switch (property) {
+        case "background":
+            return [`background-color: ${variable(value)}`];
+        case "text":
+            return [`color: ${variable(value)}`];
+        case "border":
+            return [value === "none" ? "border: none" : `border: ${stroke(value)}`];
+        case "radius":
+            return [`border-radius: ${value === "0" ? "0" : variable(value)}`];
+        case "padding":
+            return [`padding: ${(Array.isArray(value) ? value : [value]).map((each) => (each === "0" ? "0" : variable(each))).join(" ")}`];
+        case "gap":
+            return [`gap: ${value === "0" ? "0" : variable(value)}`];
+        case "min-size":
+            return [`min-height: ${variable(value)}`, `min-width: ${variable(value)}`];
+        case "type": {
+            const name = propertyName(value);
+            return [
+                `font-family: var(${name}-family)`,
+                `font-size: var(${name}-size)`,
+                `font-weight: var(${name}-weight)`,
+                `line-height: var(${name}-line-height)`,
+                `letter-spacing: var(${name}-letter-spacing)`,
+            ];
+        }
+        case "elevation":
+            return [value === "none" ? "box-shadow: none" : `box-shadow: ${variable(value)}`];
+        case "opacity":
+            return [`opacity: ${value}`];
+        case "outline": {
+            if (value === "none") {
+                return ["outline: none"];
+            }
+            const o = value;
+            return [`outline: ${stroke(o)}`, ...(typeof o["offset"] === "string" ? [`outline-offset: ${variable(o["offset"])}`] : [])];
+        }
+        case "align":
+            return [`align-items: ${value}`];
+        default:
+            throw new Error(`no CSS for the property "${property}"`);
+    }
+};
+const declarations = (properties) => Object.entries(properties).flatMap(([property, value]) => declarationOf(property, value));
+const block = (selector, lines, indent = "  ") => lines.length === 0 ? "" : `${indent}${selector} {\n${lines.map((line) => `${indent}  ${line};`).join("\n")}\n${indent}}\n`;
+const same = (a, b) => JSON.stringify(a?.value) === JSON.stringify(b?.value);
+/** The stylesheet of a theme whose problems are none. */
+export const compileWeb = (loaded, inputs) => {
+    const out = [
+        `/* Generated by @valancex/style from the theme "${loaded.theme.name}". Do not edit: it is rewritten whenever the theme changes. */\n`,
+        "@layer vlx-library, vlx-theme, vlx-app;\n\n",
+        "@layer vlx-theme {\n",
+    ];
+    const modes = Object.keys(loaded.modes);
+    const light = loaded.modes["light"];
+    // tokens: those that are the same in every mode once, in :root; the others per mode
+    const varying = new Set([...light.keys()].filter((path) => modes.some((mode) => !same(light.get(path), loaded.modes[mode].get(path)))));
+    const props = (tokens, only) => [...tokens.values()].filter((token) => only(token.path)).flatMap((token) => propertiesOf(token).map(([name, value]) => `${name}: ${value}`));
+    out.push(block(":root", [...props(light, (path) => !varying.has(path)), ...props(light, (path) => varying.has(path))]));
+    for (const mode of modes.filter((each) => each !== "light")) {
+        const condition = inputs.contract.modeConditions?.[mode];
+        if (condition !== undefined) {
+            const [name, value] = condition.split(":");
+            const query = inputs.contract.conditions[name]?.web?.[value];
+            out.push(`  @media ${query} {\n${block(":root", props(loaded.modes[mode], (path) => varying.has(path)), "    ")}  }\n`);
+        }
+    }
+    for (const mode of modes) {
+        out.push(block(`[data-theme="${mode}"]`, props(loaded.modes[mode], (path) => varying.has(path))));
+    }
+    // the page under a modal layer (I14): it does not scroll behind it, and the scrollbar's width stays so the content does not shift; the layer itself does not chain its scroll to the page
+    out.push("}\n\n@layer vlx-library {\n");
+    out.push(block(":root:has(:modal)", ["overflow: hidden", "scrollbar-gutter: stable"]));
+    out.push(block(":modal", ["overscroll-behavior: contain"]));
+    out.push("}\n\n@layer vlx-theme {\n");
+    // recipes, by primitive
+    for (const { recipe } of [...loaded.recipes].sort((a, b) => a.recipe.target.primitive.localeCompare(b.recipe.target.primitive))) {
+        const primitive = recipe.target.primitive;
+        const hook = hookOf(inputs, primitive);
+        if (hook === undefined) {
+            continue;
+        }
+        const info = inputs.primitives[primitive];
+        out.push(`\n  /* ${primitive} */\n`);
+        out.push(block(hook, declarations(recipe.base ?? {})));
+        for (const [variant, values] of Object.entries(recipe.variants ?? {})) {
+            const name = info.variants.find((each) => each.name === variant).attribute;
+            const defaulted = inputs.contract.variants[variant].default;
+            for (const [value, properties] of Object.entries(values)) {
+                const selector = value === defaulted ? `${hook}:is([${name}="${value}"], :not([${name}]))` : `${hook}[${name}="${value}"]`;
+                out.push(block(selector, declarations(properties)));
+            }
+        }
+        const interaction = inputs.contract.interactionStates;
+        const states = statesOf(inputs, primitive);
+        const stateSelector = (state) => interaction[state] ?? info.stateSelectors[state] ?? "";
+        for (const state of states) {
+            const properties = recipe.states?.[state];
+            if (properties !== undefined) {
+                const media = inputs.contract.interactionMedia?.[state];
+                out.push(media === undefined
+                    ? block(`${hook}${stateSelector(state)}`, declarations(properties))
+                    : `  @media ${media} {\n${block(`${hook}${stateSelector(state)}`, declarations(properties), "    ")}  }\n`);
+            }
+        }
+        for (const [condition, properties] of Object.entries(recipe.when ?? {})) {
+            const [name, value] = condition.split(":");
+            if (name === "target") {
+                if (value === "web") {
+                    out.push(block(hook, declarations(properties)));
+                }
+                continue;
+            }
+            const query = inputs.contract.conditions[name]?.web?.[value];
+            if (query !== undefined) {
+                out.push(`  @media ${query} {\n${block(hook, declarations(properties), "    ")}  }\n`);
+            }
+        }
+        if (recipe.escape?.web !== undefined) {
+            out.push(block(hook, recipe.escape.web.css
+                .split(";")
+                .map((line) => line.trim())
+                .filter((line) => line !== "")));
+        }
+    }
+    out.push("}\n");
+    return out.join("").replace(/\n{3,}/g, "\n\n");
+};

package/dist/desktop.d.ts

@@ -0,0 +1,33 @@
+import { type Inputs } from "./check.js";
+import type { LoadedTheme } from "./types.js";
+export interface DesktopStyle {
+    background?: string;
+    text?: string;
+    border?: {
+        width: number;
+        color: string;
+    } | "none";
+    radius?: number;
+    /** Top, right, bottom, left. */
+    padding?: [number, number, number, number];
+    gap?: number;
+    minSize?: number;
+    fontSize?: number;
+    fontWeight?: number;
+}
+export interface DesktopRecipe {
+    base?: DesktopStyle;
+    variants?: Record<string, Record<string, DesktopStyle>>;
+    states?: Record<string, DesktopStyle>;
+    when?: Record<string, DesktopStyle>;
+}
+export interface DesktopTheme {
+    readonly version: 1;
+    readonly name: string;
+    /** Each variant's default value (the one that applies when a template does not say). */
+    readonly defaults: Record<string, string>;
+    /** Mode name to primitive name to its recipe. */
+    readonly modes: Record<string, Record<string, DesktopRecipe>>;
+}
+/** The theme as the Desktop is told it. */
+export declare const resolveForDesktop: (loaded: LoadedTheme, inputs: Inputs) => DesktopTheme;

package/dist/desktop.js

@@ -0,0 +1,112 @@
+// The Desktop's realization of a theme: resolved values, not references. The Desktop draws its own pixels (egui) and keeps a typed map; it is told it once, in the `appearance` message it already has.
+// Colors are `#rrggbb[aa]`, lengths are points (a rem is 16), and only what the Desktop honors is in it: a property it does not apply is left out here and listed in the coverage report, so the window never
+// has to guess. A mode the Desktop cannot choose (high contrast is the person's setting; the window is not told it) is left out too.
+import { toRgb } from "./color.js";
+import { hookOf, statesOf } from "./check.js";
+const byte = (value) => Math.round(Math.min(1, Math.max(0, value)) * 255)
+    .toString(16)
+    .padStart(2, "0");
+const color = (token) => {
+    const rgb = toRgb(token.value);
+    return `#${byte(rgb.r)}${byte(rgb.g)}${byte(rgb.b)}${rgb.a === 1 ? "" : byte(rgb.a)}`;
+};
+const length = (token) => {
+    const { value, unit } = token.value;
+    return unit === "rem" ? value * 16 : value;
+};
+const resolveStyle = (declarations, tokens, inputs) => {
+    const out = {};
+    const token = (path) => tokens.get(path);
+    for (const [property, value] of Object.entries(declarations ?? {})) {
+        if (inputs.contract.properties[property]?.desktop === "unsupported") {
+            continue;
+        }
+        switch (property) {
+            case "background":
+                out.background = color(token(value));
+                break;
+            case "text":
+                out.text = color(token(value));
+                break;
+            case "border": {
+                const stroke = value;
+                out.border = stroke === "none" ? "none" : { width: length(token(stroke.width)), color: color(token(stroke.color)) };
+                break;
+            }
+            case "radius":
+                out.radius = value === "0" ? 0 : length(token(value));
+                break;
+            case "padding": {
+                const list = (Array.isArray(value) ? value : [value]).map((each) => (each === "0" ? 0 : length(token(each))));
+                const [a = 0, b = a, c = a, d = b] = list;
+                out.padding = [a, b, c, d];
+                break;
+            }
+            case "gap":
+                out.gap = value === "0" ? 0 : length(token(value));
+                break;
+            case "min-size":
+                out.minSize = length(token(value));
+                break;
+            case "type": {
+                const type = token(value).value;
+                out.fontSize = type.fontSize.unit === "rem" ? type.fontSize.value * 16 : type.fontSize.value;
+                if (typeof type.fontWeight === "number") {
+                    out.fontWeight = type.fontWeight;
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return out;
+};
+/** The theme as the Desktop is told it. */
+export const resolveForDesktop = (loaded, inputs) => {
+    const modes = {};
+    for (const [mode, tokens] of Object.entries(loaded.modes)) {
+        const condition = inputs.contract.modeConditions?.[mode];
+        const kind = condition?.split(":")[0];
+        if (kind !== undefined && inputs.contract.conditions[kind]?.desktop === "unsupported") {
+            continue;
+        }
+        const recipes = {};
+        for (const { recipe } of loaded.recipes) {
+            const primitive = recipe.target.primitive;
+            if (hookOf(inputs, primitive) === undefined) {
+                continue;
+            }
+            const out = {};
+            const base = resolveStyle(recipe.base, tokens, inputs);
+            // `target:desktop` is the Desktop's own refinement of the base; `target:web` is not for it
+            Object.assign(base, resolveStyle(recipe.when?.["target:desktop"], tokens, inputs));
+            out.base = base;
+            for (const [variant, values] of Object.entries(recipe.variants ?? {})) {
+                out.variants = {
+                    ...out.variants,
+                    [variant]: Object.fromEntries(Object.entries(values).map(([value, declarations]) => [value, resolveStyle(declarations, tokens, inputs)])),
+                };
+            }
+            for (const state of statesOf(inputs, primitive)) {
+                const style = inputs.contract.desktopStates?.[state] === "supported" ? resolveStyle(recipe.states?.[state], tokens, inputs) : {};
+                if (Object.keys(style).length > 0) {
+                    out.states = { ...out.states, [state]: style };
+                }
+            }
+            for (const [condition, declarations] of Object.entries(recipe.when ?? {})) {
+                if (condition.startsWith("viewport:")) {
+                    out.when = { ...out.when, [condition]: resolveStyle(declarations, tokens, inputs) };
+                }
+            }
+            recipes[primitive] = out;
+        }
+        modes[mode] = recipes;
+    }
+    return {
+        version: 1,
+        name: loaded.theme.name,
+        defaults: Object.fromEntries(Object.entries(inputs.contract.variants).map(([name, definition]) => [name, definition.default])),
+        modes,
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export type * from "./types.js";
+export { loadContract, loadSchema, readJson, root } from "./load.js";
+export { dtcgValidator, resolveDocument, validateDocument } from "./tokens.js";
+export type { Resolved } from "./tokens.js";
+export { toCss, toRgb } from "./color.js";
+export type { DtcgColor, Rgb } from "./color.js";
+export { composite, luminance, ratio } from "./contrast.js";
+export { loadTheme, validateRecipe } from "./theme.js";
+export { checkRecipe, checkTheme, contrastOf, defaultInputs, hookOf, statesOf } from "./check.js";
+export { primitives } from "./primitives.js";
+export type { Checked, ContrastResult, Inputs } from "./check.js";
+export { didYouMean, nearest } from "./suggest.js";
+export { compileWeb, declarationOf, propertiesOf, propertyName } from "./css.js";
+export { coverageOf, styleable } from "./coverage.js";
+export type { Coverage, NotApplied, Target } from "./coverage.js";
+export { resolveForDesktop } from "./desktop.js";
+export type { DesktopRecipe, DesktopStyle, DesktopTheme } from "./desktop.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+export { loadContract, loadSchema, readJson, root } from "./load.js";
+export { dtcgValidator, resolveDocument, validateDocument } from "./tokens.js";
+export { toCss, toRgb } from "./color.js";
+export { composite, luminance, ratio } from "./contrast.js";
+export { loadTheme, validateRecipe } from "./theme.js";
+export { checkRecipe, checkTheme, contrastOf, defaultInputs, hookOf, statesOf } from "./check.js";
+export { primitives } from "./primitives.js";
+export { didYouMean, nearest } from "./suggest.js";
+export { compileWeb, declarationOf, propertiesOf, propertyName } from "./css.js";
+export { coverageOf, styleable } from "./coverage.js";
+export { resolveForDesktop } from "./desktop.js";

package/dist/load.d.ts

@@ -0,0 +1,5 @@
+import type { Contract } from "./types.js";
+export declare const root: string;
+export declare const readJson: (path: string) => unknown;
+export declare const loadContract: () => Contract;
+export declare const loadSchema: (name: string) => object;

package/dist/load.js

@@ -0,0 +1,8 @@
+// Where the package's data is: the directory that holds `contract/`, `schema/` and `themes/` (one level above `dist/` or `src/`).
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+export const readJson = (path) => JSON.parse(readFileSync(path, "utf8"));
+export const loadContract = () => readJson(join(root, "contract", "style-contract-v1.json"));
+export const loadSchema = (name) => readJson(join(root, "schema", name));

package/dist/primitives.d.ts

@@ -0,0 +1,2 @@
+import type { PrimitiveInfo } from "./types.js";
+export declare const primitives: Readonly<Record<string, PrimitiveInfo>>;