@valancex/style 0.0.0-stage → 0.14.0

package/dist/tokens.js

@@ -0,0 +1,257 @@
+// Design Tokens Community Group documents (format 2025.10): validated against the group's own JSON Schemas (vendored unchanged in schema/dtcg-2025.10/, see its NOTICE.md), then the graph pass
+// the schemas cannot make. A schema checks one document's shape; it cannot follow an alias to its target, so a cycle, a reference to nothing, a `$extends` of a group that is not there, and an alias
+// whose target has another type are found here.
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { root } from "./load.js";
+const BASE = "https://www.designtokens.org/schemas/2025.10/";
+const directory = join(root, "schema", "dtcg-2025.10");
+let validator;
+const files = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((entry) => (entry.isDirectory() ? files(join(dir, entry.name)) : entry.name.endsWith(".json") ? [join(dir, entry.name)] : []));
+/** The validator for a whole token document: the group's `format.json` with every schema it references. */
+export const dtcgValidator = () => {
+    if (validator === undefined) {
+        const ajv = new Ajv.default({ strict: false, allErrors: false });
+        addFormats(ajv);
+        for (const file of files(directory)) {
+            ajv.addSchema(JSON.parse(readFileSync(file, "utf8")), BASE + relative(directory, file).split("\\").join("/"));
+        }
+        validator = ajv.getSchema(`${BASE}format.json`);
+    }
+    return validator;
+};
+/** Whether `document` is a valid token document, and the first error if not. */
+export const validateDocument = (document) => {
+    const validate = dtcgValidator();
+    if (validate(document)) {
+        return { valid: true };
+    }
+    const first = validate.errors?.[0];
+    return { valid: false, error: first === undefined ? "invalid" : `${first.instancePath === "" ? "(document)" : first.instancePath} ${first.message ?? ""}`.trim() };
+};
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A token has a `$value`, or is defined by a JSON Pointer `$ref` to a value (the format allows both). */
+const isToken = (value) => isObject(value) && ("$value" in value || typeof value["$ref"] === "string");
+const valueOf = (token) => (token["$value"] !== undefined ? token["$value"] : { $ref: token["$ref"] });
+const ALIAS = /^\{([^{}]+)\}$/;
+const lookup = (document, path) => {
+    let at = document;
+    for (const part of path.split(".")) {
+        at = isObject(at) ? at[part] : undefined;
+        if (at === undefined) {
+            return undefined;
+        }
+    }
+    return at;
+};
+const merge = (base, over) => {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(over)) {
+        const was = out[key];
+        out[key] = isObject(value) && isObject(was) && !isToken(value) && !isToken(was) ? merge(was, value) : value;
+    }
+    return out;
+};
+/** Every `$extends` replaced by what it extends (a group's own members win). Reports an `$extends` that points at nothing or loops. */
+const expand = (document, problems, file) => {
+    const expanding = [];
+    const visit = (node, path) => {
+        let result = {};
+        const extended = node["$extends"];
+        if (typeof extended === "string") {
+            const match = ALIAS.exec(extended);
+            const target = match === null ? undefined : lookup(document, match[1]);
+            if (match === null || !isObject(target) || isToken(target)) {
+                problems.push({ file, path, code: "extends-unresolved", message: `${path === "" ? "the document" : path} extends ${extended}, which is not a group` });
+            }
+            else if (expanding.includes(match[1]) || match[1] === path) {
+                problems.push({
+                    file,
+                    path,
+                    code: "extends-cycle",
+                    message: `${path === "" ? "the document" : path} extends ${extended}, which leads back to it (${[...expanding, match[1]].join(" -> ")})`,
+                });
+            }
+            else {
+                expanding.push(match[1]);
+                result = visit(target, match[1]);
+                expanding.pop();
+            }
+        }
+        const own = {};
+        for (const [key, value] of Object.entries(node)) {
+            if (key !== "$extends") {
+                own[key] = isObject(value) && !isToken(value) ? visit(value, path === "" ? key : `${path}.${key}`) : value;
+            }
+        }
+        return merge(result, own);
+    };
+    return visit(document, "");
+};
+const flatten = (document) => {
+    const flat = new Map();
+    const visit = (node, path, inherited) => {
+        const type = typeof node["$type"] === "string" ? node["$type"] : inherited;
+        for (const [key, value] of Object.entries(node)) {
+            if (key === "$root" && isToken(value)) {
+                flat.set(path, { type: typeof value["$type"] === "string" ? value["$type"] : type, value: valueOf(value) });
+            }
+            else if (!key.startsWith("$") && isObject(value)) {
+                const here = path === "" ? key : `${path}.${key}`;
+                if (isToken(value)) {
+                    flat.set(here, { type: typeof value["$type"] === "string" ? value["$type"] : type, value: valueOf(value) });
+                }
+                else {
+                    visit(value, here, type);
+                }
+            }
+        }
+    };
+    visit(document, "", undefined);
+    return flat;
+};
+const pointer = (document, reference) => {
+    if (!reference.startsWith("#/")) {
+        return undefined;
+    }
+    const parts = reference.slice(2).split("/");
+    // a pointer reaches into a token's value (the format: it points at a part of `$value`), never at a group, a description or other metadata
+    if (!parts.includes("$value")) {
+        return undefined;
+    }
+    let at = document;
+    for (const part of parts) {
+        const key = decodeURIComponent(part).replaceAll("~1", "/").replaceAll("~0", "~");
+        at = isObject(at) ? at[key] : Array.isArray(at) && /^(0|[1-9]\d*)$/.test(key) ? at[Number(key)] : undefined;
+        if (at === undefined) {
+            return undefined;
+        }
+    }
+    return at;
+};
+/** The pass over one document that has already been checked against the schemas: follows `$extends`, curly-brace aliases and JSON Pointer `$ref`s to their ends. */
+export const resolveDocument = (document, file) => {
+    const problems = [];
+    if (!isObject(document)) {
+        return { tokens: new Map(), problems: [{ file, code: "token-document", message: "a token document is an object" }], resolved: null };
+    }
+    const expanded = expand(document, problems, file);
+    const flat = flatten(expanded);
+    const tokens = new Map();
+    const resolving = [];
+    const failed = new Set();
+    const resolveToken = (path) => {
+        const done = tokens.get(path);
+        if (done !== undefined) {
+            return done;
+        }
+        const entry = flat.get(path);
+        if (entry === undefined || failed.has(path)) {
+            return undefined;
+        }
+        if (resolving.includes(path)) {
+            problems.push({ file, path, code: "token-cycle", message: `${path} refers to itself through ${[...resolving.slice(resolving.indexOf(path)), path].join(" -> ")}` });
+            failed.add(path);
+            return undefined;
+        }
+        resolving.push(path);
+        const value = resolveValue(entry.value, path, entry.type);
+        resolving.pop();
+        if (value === undefined) {
+            failed.add(path);
+            return undefined;
+        }
+        const type = entry.type ?? value.type;
+        if (type === undefined) {
+            problems.push({ file, path, code: "token-no-type", message: `${path} has no type: give it \`$type\`, or put it in a group that has one` });
+            failed.add(path);
+            return undefined;
+        }
+        const resolved = { path, type: type, value: value.value };
+        tokens.set(path, resolved);
+        return resolved;
+    };
+    /** The value with its aliases and pointers followed, and the type of the alias it ended at, if the whole value is one. */
+    const resolveValue = (value, path, declared) => {
+        if (typeof value === "string") {
+            const match = ALIAS.exec(value);
+            if (match === null) {
+                return { value };
+            }
+            const target = match[1];
+            const end = resolveToken(target);
+            if (end === undefined) {
+                if (!failed.has(target) && !flat.has(target)) {
+                    problems.push({ file, path, code: "token-unresolved", message: `${path} refers to {${target}}, which is not a token` });
+                }
+                return undefined;
+            }
+            if (declared !== undefined && declared !== end.type) {
+                problems.push({ file, path, code: "token-type-mismatch", message: `${path} is a ${declared} but refers to {${target}}, which is a ${end.type}` });
+                return undefined;
+            }
+            return { value: end.value, type: end.type };
+        }
+        if (Array.isArray(value)) {
+            const items = value.map((each) => resolveValue(each, path, undefined));
+            return items.some((each) => each === undefined) ? undefined : { value: items.map((each) => each.value) };
+        }
+        if (isObject(value)) {
+            const reference = value["$ref"];
+            if (typeof reference === "string") {
+                const target = pointer(expanded, reference);
+                if (target === undefined) {
+                    problems.push({ file, path, code: "token-unresolved", message: `${path} points at ${reference}, which is nothing in the document` });
+                    return undefined;
+                }
+                if (resolving.includes(`ref:${reference}`)) {
+                    problems.push({ file, path, code: "token-cycle", message: `${path} points at ${reference}, which leads back to it` });
+                    return undefined;
+                }
+                resolving.push(`ref:${reference}`);
+                const end = resolveValue(target, path, undefined);
+                resolving.pop();
+                return end;
+            }
+            const out = {};
+            for (const [key, each] of Object.entries(value)) {
+                const resolved = resolveValue(each, path, undefined);
+                if (resolved === undefined) {
+                    return undefined;
+                }
+                out[key] = resolved.value;
+            }
+            return { value: out };
+        }
+        return { value };
+    };
+    for (const path of flat.keys()) {
+        resolveToken(path);
+    }
+    const withValue = (token, end) => {
+        const { $ref: _ref, ...rest } = token;
+        return { ...rest, $type: end.type, $value: end.value };
+    };
+    // the document again, with each token's value and type as resolved
+    const substitute = (node, path) => {
+        const out = {};
+        for (const [key, value] of Object.entries(node)) {
+            if (key === "$root" && isToken(value)) {
+                const end = tokens.get(path);
+                out[key] = end === undefined ? value : withValue(value, end);
+            }
+            else if (!key.startsWith("$") && isObject(value)) {
+                const here = path === "" ? key : `${path}.${key}`;
+                const end = isToken(value) ? tokens.get(here) : undefined;
+                out[key] = isToken(value) ? (end === undefined ? value : withValue(value, end)) : substitute(value, here);
+            }
+            else {
+                out[key] = value;
+            }
+        }
+        return out;
+    };
+    return { tokens, problems, resolved: substitute(expanded, "") };
+};

package/dist/types.d.ts

@@ -0,0 +1,114 @@
+export type TokenType = "color" | "dimension" | "fontFamily" | "fontWeight" | "duration" | "cubicBezier" | "number" | "shadow" | "typography" | "border" | "transition" | "gradient" | "strokeStyle";
+export type Accepts = "color" | "stroke" | "dimension" | "space-list" | "typography" | "shadow" | "opacity" | "alignment";
+export interface PropertyDefinition {
+    readonly accepts: Accepts;
+    /** The CSS properties the web compiles it to. */
+    readonly web: ReadonlyArray<string>;
+    /** Whether the Desktop honors it. */
+    readonly desktop: "supported" | "partial" | "unsupported";
+}
+/** What the contract needs of a primitive; generated from the primitive's specification and the web's realization (see primitives.ts), so this package reads no specification file. */
+export interface PrimitiveInfo {
+    readonly status: "portable" | "web-only" | "desktop-only";
+    /** A person acts on it (it has keys), so the interaction states apply. */
+    readonly interactive: boolean;
+    /** The semantic states its specification declares. */
+    readonly states: ReadonlyArray<string>;
+    /** The style variants it takes, each with the attribute the web realizes it as. */
+    readonly variants: ReadonlyArray<{
+        readonly name: string;
+        readonly attribute: string;
+    }>;
+    /** The value of its `data-vlx` hook on the web: how a stylesheet reaches its root. Absent where the web has no hook for it. */
+    readonly hook?: string;
+    /** The CSS selector of each of its semantic states on the web. */
+    readonly stateSelectors: Readonly<Record<string, string>>;
+}
+export interface Contract {
+    readonly version: 1;
+    readonly parts: Readonly<Record<string, string>>;
+    /** Interaction states, each with the CSS pseudo-class that reaches it on the web. */
+    readonly interactionStates: Readonly<Record<string, string>>;
+    /** The media query an interaction state's rules sit in on the web: hover styling only where a pointer can hover (I15), so a touch screen's sticky `:hover` never paints. */
+    readonly interactionMedia?: Readonly<Record<string, string>>;
+    readonly semanticStates: ReadonlyArray<string>;
+    readonly variants: Readonly<Record<string, {
+        readonly values: ReadonlyArray<string>;
+        readonly default: string;
+    }>>;
+    readonly conditions: Readonly<Record<string, {
+        readonly values: ReadonlyArray<string>;
+        readonly web?: Readonly<Record<string, string>>;
+        readonly desktop?: "supported" | "unsupported";
+    }>>;
+    /** Whether the Desktop applies a recipe's styles for a state. */
+    readonly desktopStates?: Readonly<Record<string, "supported" | "partial" | "unsupported">>;
+    readonly properties: Readonly<Record<string, PropertyDefinition>>;
+    /** A mode named here is also the page's own whenever its condition holds (`dark` when the system prefers dark); any mode is reachable by `data-theme`. */
+    readonly modeConditions?: Readonly<Record<string, string>>;
+    readonly desktopNotes?: Readonly<Record<string, string>>;
+}
+/** A value in a recipe: a token path, a number, a keyword, a list of token paths, or a stroke (`width`, `color`, `style`, `offset`). */
+export type RecipeValue = string | number | ReadonlyArray<string> | {
+    readonly width?: string;
+    readonly color?: string;
+    readonly style?: "solid" | "dashed" | "dotted";
+    readonly offset?: string;
+};
+export type Declarations = Readonly<Record<string, RecipeValue>>;
+export interface Recipe {
+    readonly version: 1;
+    readonly target: {
+        readonly primitive: string;
+        readonly part: string;
+    };
+    readonly base?: Declarations;
+    readonly variants?: Readonly<Record<string, Readonly<Record<string, Declarations>>>>;
+    readonly states?: Readonly<Record<string, Declarations>>;
+    readonly when?: Readonly<Record<string, Declarations>>;
+    readonly escape?: {
+        readonly web?: {
+            readonly css: string;
+        };
+    };
+}
+export interface Theme {
+    readonly version: 1;
+    readonly name: string;
+    /** The tokens that do not change with the mode (space, radius, type), relative to the theme file. Optional. */
+    readonly base?: string;
+    /** Mode name to the token document that defines the tokens that do change (relative to the theme file). `light` is the mode a page has when it asks for none. */
+    readonly modes: Readonly<Record<string, string>>;
+    readonly recipes: ReadonlyArray<string>;
+    readonly contrast?: ReadonlyArray<{
+        readonly text: string;
+        readonly on: string;
+        readonly min: number;
+        readonly modes?: ReadonlyArray<string>;
+    }>;
+}
+/** A mistake in a theme: where (a file, and a path into it when there is one), which rule, and what is wrong. The same shape `vlx` prints. */
+export interface Problem {
+    readonly file: string;
+    readonly path?: string;
+    readonly code: string;
+    readonly message: string;
+}
+/** A token with its alias chain followed: the value is fully expanded. */
+export interface ResolvedToken {
+    readonly path: string;
+    readonly type: TokenType;
+    readonly value: unknown;
+}
+export interface LoadedTheme {
+    readonly theme: Theme;
+    /** The directory the theme file is in. */
+    readonly directory: string;
+    /** Mode name to its resolved tokens. */
+    readonly modes: Readonly<Record<string, ReadonlyMap<string, ResolvedToken>>>;
+    readonly recipes: ReadonlyArray<{
+        readonly file: string;
+        readonly recipe: Recipe;
+    }>;
+    readonly problems: ReadonlyArray<Problem>;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// The shapes of the style contract's data: the contract itself (style-contract-v1), a recipe (recipe-v1) and a theme (theme-v1). Tokens are Design Tokens Community Group documents (format 2025.10)
+// and keep that format's shapes; what this package adds to them is a graph pass and the resolved view.
+export {};

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@valancex/style",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.14.0",
+  "description": "The style contract for VALANCE: tokens (Design Tokens format), recipes for a primitive's root part, states, variants and conditions, as data; and what is generated or checked from them (a layered stylesheet for the web, resolved values for the Desktop, the contrast of declared pairs, the coverage of a theme).",
+  "keywords": [
+    "valance",
+    "theme",
+    "design-tokens",
+    "style"
+  ],
+  "homepage": "https://github.com/ValanceX/Valance/tree/main/packages/style#readme",
+  "bugs": {
+    "url": "https://github.com/ValanceX/Valance/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ValanceX/Valance.git",
+    "directory": "packages/style"
+  },
+  "license": "MIT",
+  "author": "Jack Miller <jackmiller0899@gmail.com>",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "contract",
+    "schema",
+    "themes"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@valancex/mesh-runtime": "^0.17.0",
+    "@valancex/port-web": "^0.14.0",
+    "@vitest/browser": "3.2.7",
+    "playwright": "1.56.1",
+    "stylelint": "^17.16.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.0",
+    "@valancex/common": "^0.14.0",
+    "@valancex/valance": "^0.14.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run",
+    "test:browser": "vitest run -c vitest.browser.config.ts"
+  }
 }

package/schema/dtcg-2025.10/NOTICE.md

@@ -0,0 +1,6 @@
+# Design Tokens Community Group, format 2025.10: schemas and test suite
+
+Copied unchanged from https://github.com/design-tokens/community-group at commit 882ebd6716abef9a46d8ef5fb12e82009d6cee2e (`schemas/src/2025.10/` into `schema/dtcg-2025.10/`, `test-suite/tests/2025.10/format/` into `test/fixtures/dtcg-2025.10/`) by `scripts/vendor-dtcg.mjs`.
+18 schema files and 220 tests.
+
+The files are the group's. They are licensed under the [W3C Software and Document License](https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document), as the repository's LICENSE.md says for its Reports; the format is a Final Community Group Report, not a W3C Standard.

package/schema/dtcg-2025.10/format/group.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://www.designtokens.org/schemas/2025.10/format/group.json",
+  "title": "Group",
+  "description": "A group in the DTCG specification",
+  "type": "object",
+  "properties": {
+    "$type": {
+      "$ref": "https://www.designtokens.org/schemas/2025.10/format/tokenType.json",
+      "description": "The type for tokens in this group (inherited by nested tokens unless overridden)"
+    },
+    "$description": {
+      "type": "string",
+      "description": "A plain text description of the group"
+    },
+    "$extensions": {
+      "type": "object",
+      "description": "Vendor-specific extensions"
+    },
+    "$extends": {
+      "oneOf": [
+        {
+          "$ref": "https://www.designtokens.org/schemas/2025.10/format.json#/definitions/curlyBraceReference"
+        },
+        {
+          "$ref": "https://www.designtokens.org/schemas/2025.10/format.json#/definitions/jsonPointerReference"
+        }
+      ],
+      "description": "Reference to another group to inherit tokens and properties from"
+    },
+    "$deprecated": {
+      "oneOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Whether this group is deprecated"
+    },
+    "$root": {
+      "description": "Root token for this group. The $root token provides a base value for the group while allowing for variants or extensions.",
+      "$ref": "https://www.designtokens.org/schemas/2025.10/format/token.json"
+    }
+  },
+  "patternProperties": {
+    "^[^${}.][^{}.]*$": {
+      "description": "Nested groups and tokens (see ../format.json#/definitions/tokenOrGroupName for pattern definition)",
+      "$ref": "https://www.designtokens.org/schemas/2025.10/format/groupOrToken.json"
+    }
+  },
+  "additionalProperties": false
+}

package/schema/dtcg-2025.10/format/groupOrToken.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://www.designtokens.org/schemas/2025.10/format/groupOrToken.json",
+  "title": "Group or Token",
+  "description": "A group or a token in the DTCG specification. A token is identified by the presence of a $value property, while a group is any object without a $value property.",
+  "oneOf": [
+    {
+      "$ref": "https://www.designtokens.org/schemas/2025.10/format/group.json"
+    },
+    {
+      "$ref": "https://www.designtokens.org/schemas/2025.10/format/token.json"
+    }
+  ]
+}