design-token-library 0.3.1 → 0.4.0

package/dist/lib/parse-resolve.js

@@ -0,0 +1,281 @@
+import { isChildName, isGroupNode, isObject, isReference, isTokenNode, label, referencePath, setOwn, } from "./parse-document.js";
+import { EXTENSION } from "./parse-extension.js";
+/**
+ * Parses a JSON Pointer in URI fragment form (RFC 6901), such as
+ * `#/color/blue/$value`.
+ */
+const parsePointer = (pointer) => {
+    if (!pointer.startsWith("#")) {
+        return undefined;
+    }
+    const rest = pointer.slice(1);
+    if (rest === "") {
+        return [];
+    }
+    if (!rest.startsWith("/")) {
+        return undefined;
+    }
+    try {
+        return rest
+            .slice(1)
+            .split("/")
+            .map((segment) => decodeURIComponent(segment)
+            .replaceAll("~1", "/")
+            .replaceAll("~0", "~"));
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The most nodes a document may have once `$extends` and `$ref` are resolved.
+ * Both copy what they name, so a chain of them grows exponentially: 22 groups
+ * that each hold two `$ref`s to the one before are four million tokens. The
+ * time to read a document is linear in its expanded size, so this bounds the
+ * time, and a real document is a small part of it.
+ */
+const MAX_EXPANDED_NODES = 1_000_000;
+/**
+ * Thrown to stop expanding a document that is too large.
+ */
+export class TooLarge extends Error {
+}
+export const tooLarge = () => ({
+    path: "",
+    message: `is more than ${MAX_EXPANDED_NODES} nodes once $extends and $ref are resolved. Each one copies what it names, so a chain of them grows exponentially.`,
+});
+/**
+ * The number of nodes of a document, counting a node that is shared as many
+ * times as it's used. That is what the document expands to.
+ */
+const expandedSize = (root) => {
+    const known = new WeakMap();
+    const size = (node) => {
+        if (typeof node !== "object" || node === null) {
+            return 0;
+        }
+        const cached = known.get(node);
+        if (cached !== undefined) {
+            return cached;
+        }
+        let total = 1;
+        for (const child of Object.values(node)) {
+            total += size(child);
+        }
+        known.set(node, total);
+        return total;
+    };
+    return size(root);
+};
+/**
+ * Applies `$extends`: a group takes the tokens and groups of the group it
+ * extends, and its own override them. Groups at the same path are merged
+ * deeply; a token replaces a token in full.
+ */
+const resolveExtends = (doc, report) => {
+    const done = new Map();
+    const active = [];
+    const merge = (base, over) => {
+        const result = { ...base };
+        for (const key of Object.keys(over)) {
+            setOwn(result, key, isChildName(key) &&
+                isGroupNode(base[key]) &&
+                isGroupNode(over[key])
+                ? merge(base[key], over[key])
+                : over[key]);
+        }
+        return result;
+    };
+    const targetOf = (extended, here) => {
+        if (isReference(extended)) {
+            return referencePath(extended);
+        }
+        if (isObject(extended) && typeof extended.$ref === "string") {
+            const path = parsePointer(extended.$ref);
+            if (path) {
+                return path;
+            }
+        }
+        report(here, `$extends must be a reference to a group, such as "{color.brand}" or { "$ref": "#/color/brand" }, but found ${JSON.stringify(extended)}.`);
+        return undefined;
+    };
+    const resolveNode = (node, path) => {
+        if (!isGroupNode(node)) {
+            return node;
+        }
+        const key = label(path);
+        if (done.has(key)) {
+            return done.get(key);
+        }
+        if (active.includes(key)) {
+            report(key, `$extends forms a cycle: ${[...active.slice(active.indexOf(key)), key].join(" → ")}.`);
+            const { $extends, ...rest } = node;
+            return rest;
+        }
+        active.push(key);
+        const local = {};
+        for (const property of Object.keys(node)) {
+            if (property !== "$extends") {
+                setOwn(local, property, isChildName(property)
+                    ? resolveNode(node[property], [...path, property])
+                    : node[property]);
+            }
+        }
+        let result = local;
+        if ("$extends" in node) {
+            const target = targetOf(node.$extends, key);
+            if (target) {
+                const base = lookup(target);
+                if (base === undefined) {
+                    report(key, `$extends names "${label(target)}", which does not exist.`);
+                }
+                else if (!isGroupNode(base)) {
+                    report(key, `$extends names "${label(target)}", which is a token. It must name a group.`);
+                }
+                else {
+                    result = merge(base, local);
+                }
+            }
+        }
+        active.pop();
+        done.set(key, result);
+        return result;
+    };
+    // Finds a group or token by path, seeing the children a group inherits.
+    const lookup = (path) => {
+        let node = doc;
+        const walked = [];
+        for (const segment of path) {
+            if (!isGroupNode(node)) {
+                return undefined;
+            }
+            if ("$extends" in node) {
+                node = resolveNode(node, walked);
+            }
+            if (!isChildName(segment) || !Object.hasOwn(node, segment)) {
+                return undefined;
+            }
+            node = node[segment];
+            walked.push(segment);
+        }
+        return resolveNode(node, walked);
+    };
+    return resolveNode(doc, []);
+};
+/**
+ * Resolves `{ "$ref": "#/json/pointer" }`. A pointer to a token's `$value`
+ * becomes a reference, so the value stays live; a pointer to anything else is
+ * replaced by a copy of what it points at.
+ */
+const resolvePointers = (doc, report) => {
+    const active = [];
+    const pointerGet = (path, here) => {
+        let node = doc;
+        for (const segment of path) {
+            if (isObject(node) && "$ref" in node) {
+                node = refObject(node, here);
+                // A reference to a token stands for its $value, so a pointer
+                // can go on through it.
+                if (isReference(node)) {
+                    node = pointerGet([...referencePath(node), "$value"], here);
+                }
+            }
+            if (Array.isArray(node)) {
+                node = node[Number(segment)];
+            }
+            else if (isObject(node) && Object.hasOwn(node, segment)) {
+                node = node[segment];
+            }
+            else {
+                return undefined;
+            }
+        }
+        return node;
+    };
+    const refObject = (node, here) => {
+        const where = label(here);
+        if (typeof node.$ref !== "string" || Object.keys(node).length !== 1) {
+            report(where, `a $ref must be the only property, and a string.`);
+            return node;
+        }
+        const path = parsePointer(node.$ref);
+        if (!path) {
+            report(where, `$ref "${node.$ref}" is not a JSON Pointer into this document, such as "#/color/blue/$value".`);
+            return node;
+        }
+        if (active.includes(node.$ref)) {
+            report(where, `$ref "${node.$ref}" is circular: ${[...active.slice(active.indexOf(node.$ref)), node.$ref].join(" → ")}.`);
+            return node;
+        }
+        active.push(node.$ref);
+        try {
+            const target = pointerGet(path, here);
+            if (target === undefined) {
+                report(where, `$ref "${node.$ref}" does not exist.`);
+                return node;
+            }
+            const parent = path.slice(0, -1);
+            if (path[path.length - 1] === "$value" &&
+                isTokenNode(pointerGet(parent, here))) {
+                return `{${parent.join(".")}}`;
+            }
+            if (isTokenNode(target)) {
+                return `{${path.join(".")}}`;
+            }
+            return walk(target, here);
+        }
+        finally {
+            active.pop();
+        }
+    };
+    let visited = 0;
+    // Extensions are vendor data, and a "$ref" in one is theirs, except in
+    // this library's own: it holds the library's form of the token, which
+    // the hand-written form's "$ref" reads in.
+    const extensionsOf = (extensions, here) => {
+        if (!isObject(extensions) || !Object.hasOwn(extensions, EXTENSION)) {
+            return extensions;
+        }
+        const result = { ...extensions };
+        setOwn(result, EXTENSION, walk(extensions[EXTENSION], [...here, EXTENSION]));
+        return result;
+    };
+    const walk = (node, here) => {
+        // A node is an object or an array, as `expandedSize()` counts them.
+        if (typeof node !== "object" || node === null) {
+            return node;
+        }
+        if (++visited > MAX_EXPANDED_NODES) {
+            throw new TooLarge();
+        }
+        if (Array.isArray(node)) {
+            return node.map((item, index) => walk(item, [...here, `${index}`]));
+        }
+        if ("$ref" in node) {
+            return refObject(node, here);
+        }
+        const result = {};
+        for (const key of Object.keys(node)) {
+            setOwn(result, key, key === "$extensions"
+                ? extensionsOf(node[key], [...here, key])
+                : walk(node[key], [...here, key]));
+        }
+        return result;
+    };
+    return walk(doc, []);
+};
+/**
+ * Resolves `$extends` and `$ref`.
+ *
+ * @throws TooLarge when they expand the document past what is allowed.
+ */
+export const resolveReferences = (doc, report) => {
+    const extended = resolveExtends(doc, report);
+    // `$extends` shares what it copies, so it is cheap itself, and what it
+    // expands to is what the passes after it must visit.
+    if (expandedSize(extended) > MAX_EXPANDED_NODES) {
+        throw new TooLarge();
+    }
+    return resolvePointers(extended, report);
+};
+//# sourceMappingURL=parse-resolve.js.map

package/dist/lib/parse-resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-resolve.js","sourceRoot":"","sources":["../../src/lib/parse-resolve.ts"],"names":[],"mappings":"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"}

package/dist/lib/parse-value.d.ts

@@ -0,0 +1,35 @@
+import { DesignToken } from "./design-token.js";
+/**
+ * What reading a value needs from the document it's in.
+ *
+ * @internal
+ */
+export interface ValueContext {
+    /**
+     * Reports a problem with the value at `path`.
+     */
+    report(path: string, message: string): void;
+    /**
+     * Reads a value where the format allows a reference to a token of
+     * `type`: a reference, or a recipe call. Returns the ref or computed
+     * value it stands for, or `undefined` when it's neither.
+     */
+    reference(value: unknown, type: string, path: string): unknown;
+}
+type StandardType = keyof DesignToken.ValueByType;
+/**
+ * Tests whether a type is one of the standard types, defined by the DTCG
+ * format.
+ *
+ * @internal
+ */
+export declare const isStandardType: (type: string) => type is StandardType;
+/**
+ * Reads the `$value` of a token of a standard type, in the shapes of the
+ * 2025.10 format and color module. A reference inside a composite value is
+ * checked to name a token of the type the position needs.
+ *
+ * @internal
+ */
+export declare const readValue: (type: StandardType, value: unknown, path: string, context: ValueContext) => unknown;
+export {};

package/dist/lib/parse-value.js

@@ -0,0 +1,330 @@
+import { DesignToken } from "./design-token.js";
+import { DIMENSION_UNITS, DURATION_UNITS, FONT_WEIGHTS, isKeyOf, LINE_CAPS, STROKE_STYLES, } from "./standard-values.js";
+const STANDARD_TYPES = new Set(Object.values(DesignToken.Type));
+/**
+ * Tests whether a type is one of the standard types, defined by the DTCG
+ * format.
+ *
+ * @internal
+ */
+export const isStandardType = (type) => STANDARD_TYPES.has(type);
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const unit = { min: 0, max: 1 };
+const hue = { min: 0, max: 360, exclusive: true };
+const percentage = { min: 0, max: 100 };
+const open = { min: -Infinity, max: Infinity };
+const positive = { min: 0, max: Infinity };
+/**
+ * The components of each color space, in order, with their ranges.
+ *
+ * @see {@link https://www.designtokens.org/tr/2025.10/color/}
+ */
+const COLOR_SPACES = {
+    srgb: [unit, unit, unit],
+    "srgb-linear": [unit, unit, unit],
+    hsl: [hue, percentage, percentage],
+    hwb: [hue, percentage, percentage],
+    lab: [percentage, open, open],
+    lch: [percentage, positive, hue],
+    oklab: [unit, open, open],
+    oklch: [unit, positive, hue],
+    "display-p3": [unit, unit, unit],
+    "a98-rgb": [unit, unit, unit],
+    "prophoto-rgb": [unit, unit, unit],
+    rec2020: [unit, unit, unit],
+    "xyz-d65": [unit, unit, unit],
+    "xyz-d50": [unit, unit, unit],
+};
+/**
+ * Rejects a key the format does not define, so a typo is an error instead of
+ * being ignored.
+ */
+const onlyKeys = (value, allowed, path, context) => {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key)) {
+            context.report(path, `has an unsupported property "${key}". Expected ${allowed.join(", ")}.`);
+        }
+    }
+};
+const describe = (value) => {
+    return JSON.stringify(value) ?? String(value);
+};
+/**
+ * The keys of a table as alternatives, like `"a", "b" or "c"`.
+ */
+const oneOf = (table) => {
+    const keys = Object.keys(table).map((key) => `"${key}"`);
+    const last = keys.pop();
+    return keys.length > 0 ? `${keys.join(", ")} or ${last}` : `${last}`;
+};
+/**
+ * Reads a position that holds a value of `type`, or a reference to a token of
+ * that type.
+ */
+const at = (type, value, path, context) => context.reference(value, type, path) ?? READERS[type](value, path, context);
+const inRange = (value, range) => {
+    return (value >= range.min &&
+        (range.exclusive ? value < range.max : value <= range.max));
+};
+const color = (value, path, context) => {
+    if (!isObject(value)) {
+        context.report(path, `is not a color. A color is an object with a colorSpace and components, but found ${describe(value)}.`);
+        return value;
+    }
+    onlyKeys(value, ["colorSpace", "components", "alpha", "hex"], path, context);
+    const result = { ...value };
+    const space = value.colorSpace;
+    const ranges = isKeyOf(COLOR_SPACES, space)
+        ? COLOR_SPACES[space]
+        : undefined;
+    if (!ranges) {
+        context.report(`${path}.colorSpace`, `is ${describe(space)}, which is not a color space. Expected one of ${Object.keys(COLOR_SPACES).join(", ")}.`);
+    }
+    if (!Array.isArray(value.components)) {
+        context.report(`${path}.components`, "must be an array.");
+    }
+    else {
+        if (ranges && value.components.length !== ranges.length) {
+            context.report(`${path}.components`, `must have ${ranges.length} components for ${space}, but has ${value.components.length}.`);
+        }
+        result.components = value.components.map((component, index) => {
+            const where = `${path}.components[${index}]`;
+            if (component === "none") {
+                return component;
+            }
+            const ref = context.reference(component, "number", where);
+            if (ref !== undefined) {
+                return ref;
+            }
+            if (!isNumber(component)) {
+                context.report(where, `must be a number or "none", but found ${describe(component)}.`);
+            }
+            else if (ranges?.[index] &&
+                !inRange(component, ranges[index])) {
+                const range = ranges[index];
+                context.report(where, `is ${component}, outside the range of ${space} component ${index + 1}: ${range.min} to ${range.max}${range.exclusive ? " (exclusive)" : ""}.`);
+            }
+            return component;
+        });
+    }
+    if (value.alpha !== undefined) {
+        const where = `${path}.alpha`;
+        const ref = context.reference(value.alpha, "number", where);
+        if (ref !== undefined) {
+            result.alpha = ref;
+        }
+        else if (!(isNumber(value.alpha) && inRange(value.alpha, unit))) {
+            context.report(where, `must be a number from 0 to 1, but found ${describe(value.alpha)}.`);
+        }
+    }
+    if (value.hex !== undefined &&
+        !(typeof value.hex === "string" && /^#[0-9a-fA-F]{6}$/.test(value.hex))) {
+        context.report(`${path}.hex`, `must be six digit hex notation like "#ff00ff", but found ${describe(value.hex)}.`);
+    }
+    return result;
+};
+const withUnit = (name, units) => (value, path, context) => {
+    if (!isObject(value)) {
+        context.report(path, `is not a ${name}. A ${name} is an object with a value and a unit, but found ${describe(value)}.`);
+        return value;
+    }
+    onlyKeys(value, ["value", "unit"], path, context);
+    if (!isKeyOf(units, value.unit)) {
+        context.report(`${path}.unit`, `must be ${oneOf(units)}, but found ${describe(value.unit)}.`);
+    }
+    return {
+        ...value,
+        value: at("number", value.value, `${path}.value`, context),
+    };
+};
+const fontFamily = (value, path, context) => {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (Array.isArray(value) &&
+        value.length > 0 &&
+        value.every((name) => typeof name === "string")) {
+        return [...value];
+    }
+    context.report(path, `must be a string or an array of strings, but found ${describe(value)}.`);
+    return value;
+};
+const fontWeight = (value, path, context) => {
+    const ok = (isNumber(value) && value >= 1 && value <= 1000) ||
+        isKeyOf(FONT_WEIGHTS, value);
+    if (!ok) {
+        context.report(path, `must be a number from 1 to 1000 or a font weight keyword, but found ${describe(value)}.`);
+    }
+    return value;
+};
+const cubicBezier = (value, path, context) => {
+    if (!Array.isArray(value) || value.length !== 4 || !value.every(isNumber)) {
+        context.report(path, `must be an array of four numbers, but found ${describe(value)}.`);
+        return value;
+    }
+    for (const index of [0, 2]) {
+        if (!inRange(value[index], unit)) {
+            context.report(`${path}[${index}]`, `is ${value[index]}, but the x coordinates of a cubic Bézier must be from 0 to 1.`);
+        }
+    }
+    return [...value];
+};
+const number = (value, path, context) => {
+    if (!isNumber(value)) {
+        context.report(path, `must be a number, but found ${describe(value)}.`);
+    }
+    return value;
+};
+const strokeStyle = (value, path, context) => {
+    if (typeof value === "string") {
+        if (!isKeyOf(STROKE_STYLES, value)) {
+            context.report(path, `is "${value}", which is not a stroke style. Expected one of ${Object.keys(STROKE_STYLES).join(", ")}, or a dashArray and lineCap.`);
+        }
+        return value;
+    }
+    if (!isObject(value)) {
+        context.report(path, `must be a stroke style keyword or an object, but found ${describe(value)}.`);
+        return value;
+    }
+    onlyKeys(value, ["dashArray", "lineCap"], path, context);
+    const result = { ...value };
+    if (!Array.isArray(value.dashArray) || value.dashArray.length === 0) {
+        context.report(`${path}.dashArray`, "must be an array of dimensions.");
+    }
+    else {
+        result.dashArray = value.dashArray.map((dash, index) => at("dimension", dash, `${path}.dashArray[${index}]`, context));
+    }
+    if (!isKeyOf(LINE_CAPS, value.lineCap)) {
+        context.report(`${path}.lineCap`, `must be ${oneOf(LINE_CAPS)}, but found ${describe(value.lineCap)}.`);
+    }
+    return result;
+};
+/**
+ * Reads the required properties of an object that have a type, each of which
+ * may be a reference to a token of its type.
+ */
+const properties = (value, types, path, context) => {
+    const result = { ...value };
+    for (const [property, type] of Object.entries(types)) {
+        if (value[property] === undefined) {
+            context.report(`${path}.${property}`, "is required.");
+        }
+        else {
+            result[property] = at(type, value[property], `${path}.${property}`, context);
+        }
+    }
+    return result;
+};
+/**
+ * A reader of an object whose every property is required and has a type.
+ */
+const composite = (name, types) => (value, path, context) => {
+    if (!isObject(value)) {
+        context.report(path, `is not a ${name}. A ${name} is an object, but found ${describe(value)}.`);
+        return value;
+    }
+    onlyKeys(value, Object.keys(types), path, context);
+    return properties(value, types, path, context);
+};
+const shadowLayer = (value, path, context) => {
+    if (!isObject(value)) {
+        context.report(path, `is not a shadow. A shadow is an object, but found ${describe(value)}.`);
+        return value;
+    }
+    onlyKeys(value, ["color", "offsetX", "offsetY", "blur", "spread", "inset"], path, context);
+    if (value.inset !== undefined && typeof value.inset !== "boolean") {
+        context.report(`${path}.inset`, `must be true or false, but found ${describe(value.inset)}.`);
+    }
+    return properties(value, {
+        color: "color",
+        offsetX: "dimension",
+        offsetY: "dimension",
+        blur: "dimension",
+        spread: "dimension",
+    }, path, context);
+};
+const shadow = (value, path, context) => {
+    if (!Array.isArray(value)) {
+        return shadowLayer(value, path, context);
+    }
+    if (value.length === 0) {
+        context.report(path, "must have at least one shadow.");
+    }
+    return value.map((layer, index) => {
+        const where = `${path}[${index}]`;
+        return (context.reference(layer, "shadow", where) ??
+            shadowLayer(layer, where, context));
+    });
+};
+const gradient = (value, path, context) => {
+    if (!Array.isArray(value) || value.length === 0) {
+        context.report(path, `must be an array of gradient stops, but found ${describe(value)}.`);
+        return value;
+    }
+    return value.map((stop, index) => {
+        const where = `${path}[${index}]`;
+        const ref = context.reference(stop, "gradient", where);
+        if (ref !== undefined) {
+            return ref;
+        }
+        if (!isObject(stop)) {
+            context.report(where, `is not a gradient stop. A stop is an object with a color and a position, but found ${describe(stop)}.`);
+            return stop;
+        }
+        onlyKeys(stop, ["color", "position"], where, context);
+        const result = properties(stop, { color: "color" }, where, context);
+        const position = `${where}.position`;
+        if (stop.position === undefined) {
+            context.report(position, "is required.");
+        }
+        else {
+            const ref = context.reference(stop.position, "number", position);
+            if (ref !== undefined) {
+                result.position = ref;
+            }
+            else if (!isNumber(stop.position)) {
+                context.report(position, `must be a number from 0 to 1, but found ${describe(stop.position)}.`);
+            }
+        }
+        return result;
+    });
+};
+const READERS = {
+    border: composite("border", {
+        color: "color",
+        width: "dimension",
+        style: "strokeStyle",
+    }),
+    color,
+    cubicBezier,
+    dimension: withUnit("dimension", DIMENSION_UNITS),
+    duration: withUnit("duration", DURATION_UNITS),
+    fontFamily,
+    fontWeight,
+    gradient,
+    number,
+    shadow,
+    strokeStyle,
+    transition: composite("transition", {
+        duration: "duration",
+        delay: "duration",
+        timingFunction: "cubicBezier",
+    }),
+    typography: composite("typography", {
+        fontFamily: "fontFamily",
+        fontSize: "dimension",
+        fontWeight: "fontWeight",
+        letterSpacing: "dimension",
+        lineHeight: "number",
+    }),
+};
+/**
+ * Reads the `$value` of a token of a standard type, in the shapes of the
+ * 2025.10 format and color module. A reference inside a composite value is
+ * checked to name a token of the type the position needs.
+ *
+ * @internal
+ */
+export const readValue = (type, value, path, context) => READERS[type](value, path, context);
+//# sourceMappingURL=parse-value.js.map