@pitlane/theme 0.2.0 → 0.3.1

package/dist/dtcg.d.mts

@@ -0,0 +1,127 @@
+import { i as SchemaTag } from "./schema-CRP607Pg.mjs";
+import { l as ThemeInit, r as ThemeResult, t as ThemeComponent } from "./theme-CaHfWYnM.mjs";
+//#region src/dtcg.d.ts
+/**
+ * A JSON-compatible W3C Design Tokens Community Group document.
+ *
+ * The DTCG specification permits arbitrary extension keys, so this
+ * deliberately remains open rather than attempting to model every
+ * standardized and vendor extension.
+ */
+type DTCGDocument = Record<string, unknown>;
+/**
+ * The runtime-shaped init {@link fromDTCG} derives from a DTCG document.
+ *
+ * Its `schema` and `tokens` use the broad {@link ThemeInit} member types: a
+ * JSON document cannot produce the literal information required to brand a
+ * token accessor. Generate a checked-in schema and token module from the
+ * document when a typed accessor is required.
+ */
+interface DTCGThemeInit {
+  /** The derived runtime schema tree. */
+  schema: object;
+  /** The bare token values described by {@link schema}. */
+  tokens: object;
+}
+/**
+ * Pitlane's extension payload for a value DTCG cannot represent.
+ *
+ * The extension is stored at `$extensions["tools.pitlane"]`. The surrounding
+ * node deliberately has no `$value`, making it a valid DTCG group that a
+ * strict consumer can ignore rather than a token carrying an invalid surrogate
+ * value.
+ */
+interface PitlaneDTCGExtension {
+  /** The source schema tag, including Pitlane-only `any` and `scale`. */
+  type: SchemaTag;
+  /** The original authoring value, with exact accessor references reversed. */
+  value: unknown;
+  /** Why the value has no standard DTCG representation. */
+  reason: string;
+}
+/**
+ * DTCG documents exported from a theme.
+ */
+interface DTCGExport {
+  /** The theme's base document. */
+  document: DTCGDocument;
+  /** One partial document of token overrides for each theme mode. */
+  modes: Record<string, DTCGDocument>;
+  /** The number of base and mode values preserved only in Pitlane extensions. */
+  inexpressible: number;
+}
+/**
+ * Converts a W3C DTCG 2025.10 document into the schema tree and bare token
+ * tree {@link createTheme} accepts.
+ *
+ * A token resolves its type in DTCG order: its own `$type`, the resolved type
+ * of a whole-value `{reference}`, then the nearest ancestor group's `$type`.
+ * `$description`, `$deprecated`, and `$extensions` are intentionally discarded
+ * until schema factories gain a metadata options bag. Typography tokens are not
+ * supported because one typography value would need several custom properties.
+ *
+ * Runtime JSON cannot preserve literal paths, so using this init with
+ * {@link createTheme} produces an unbranded accessor. Generate TypeScript from
+ * the result for the typed path.
+ *
+ * @param document - A DTCG document using `$value`, `$type`, and dotted references
+ * @returns A runtime {@link ThemeInit}-shaped schema and token tree
+ * @throws ThemeError for malformed groups, unsupported typography, unknown types,
+ * unresolvable references, cycles, or malformed structured DTCG values
+ *
+ * @example
+ * ```ts
+ * import { createTheme } from "@pitlane/theme";
+ * import { fromDTCG } from "@pitlane/theme/dtcg";
+ *
+ * let imported = fromDTCG({
+ *     color: {
+ *         $type: "color",
+ *         white: { $value: "#fff" },
+ *         page: { $value: "{color.white}" },
+ *     },
+ * });
+ * let theme = createTheme(imported);
+ * ```
+ */
+declare function fromDTCG(document: DTCGDocument): DTCGThemeInit;
+/**
+ * Exports a compiled theme, a published theme component, or the init behind
+ * either one to W3C DTCG 2025.10 documents.
+ *
+ * An export places `$type` on the lowest group whose complete descendant set
+ * has one expressible type; standard tokens below that group omit the redundant
+ * `$type`. Mixed groups put `$type` on their standard token leaves instead.
+ * Exact `var(--token-name)` values are converted back to `{token.path}` using
+ * the collector's variable-name map.
+ *
+ * DTCG cannot represent all CSS values this package accepts. Inexpressible
+ * values are preserved in `$extensions["tools.pitlane"]` as
+ * `{ type, value, reason }`, on an extension-only node with no `$value`; this
+ * keeps the standard document valid while preserving the original value for a
+ * caller that reports or handles the loss. `inexpressible` counts those nodes in
+ * the base document and every mode document.
+ *
+ * DTCG descriptions, deprecation metadata, and unrelated extensions are not in
+ * the authoring format and cannot be recovered.
+ *
+ * @param theme - A {@link ThemeResult}, its {@link ThemeComponent}, or its init
+ * @returns The base document, one partial document per mode, and the lossy-value count
+ * @throws ThemeError when the supplied init has an invalid token/schema structure
+ *
+ * @example
+ * ```ts
+ * import { createTheme } from "@pitlane/theme";
+ * import { toDTCG } from "@pitlane/theme/dtcg";
+ * import * as s from "@pitlane/theme/schema";
+ *
+ * let theme = createTheme({
+ *     schema: { color: s.color() },
+ *     tokens: { color: { white: "#fff" } },
+ * });
+ * let { document, inexpressible } = toDTCG(theme);
+ * ```
+ */
+declare function toDTCG<T>(theme: ThemeInit | ThemeComponent<T> | ThemeResult<T>): DTCGExport;
+//#endregion
+export { DTCGDocument, DTCGExport, DTCGThemeInit, PitlaneDTCGExtension, fromDTCG, toDTCG };

package/dist/dtcg.mjs

@@ -0,0 +1,468 @@
+import { D as referenceTarget, S as ThemeError, T as kebabSegment, b as transition, c as duration, d as gradient, f as group, i as border, l as easing, m as number, o as color, s as dimension, u as font, v as shadow, w as collectTokens, x as serializeValue, y as stroke } from "./schema-JmfNnMzr.mjs";
+//#region src/brands.ts
+/**
+* The twelve DTCG token types, in canonical order.
+*
+* @internal
+*/
+const TOKEN_TYPES = [
+	"color",
+	"dimension",
+	"duration",
+	"fontFamily",
+	"fontWeight",
+	"number",
+	"cubicBezier",
+	"shadow",
+	"border",
+	"transition",
+	"gradient",
+	"strokeStyle"
+];
+//#endregion
+//#region src/dtcg.ts
+const DTCG_ALIAS_RE = /^\{([^{}]+)\}$/;
+/** The token a DTCG `{a.b.c}` alias names, or `null`. */
+function dtcgAlias(value) {
+	if (typeof value !== "string") return null;
+	let match = DTCG_ALIAS_RE.exec(value);
+	return match ? match[1] : null;
+}
+/**
+* Rewrites every DTCG alias in a value to its `var()` reference, including the
+* ones inside a composite's sub-values. The authoring format has one reference
+* form, so braces must not survive past this module.
+*/
+function convertAliases(value, key, varNameFor) {
+	let alias = dtcgAlias(value);
+	if (alias !== null) {
+		let varName = varNameFor(alias);
+		if (varName === void 0) throw new ThemeError(`"${key}" references unknown token "${alias}"`);
+		return `var(${varName})`;
+	}
+	if (Array.isArray(value)) return value.map((item) => convertAliases(item, key, varNameFor));
+	if (typeof value === "object" && value !== null) {
+		let out = {};
+		for (let [field, item] of Object.entries(value)) out[field] = convertAliases(item, key, varNameFor);
+		return out;
+	}
+	return value;
+}
+const ACCESSOR_REFERENCE_RE = /^var\((--[a-z0-9-]+)\)$/;
+const DIMENSION_RE = /^([+-]?(?:\d+(?:\.\d+)?|\.\d+))(px|rem)$/;
+const DURATION_RE = /^([+-]?(?:\d+(?:\.\d+)?|\.\d+))(ms|s)$/;
+const CUBIC_BEZIER_RE = /^cubic-bezier\(\s*([+-]?(?:\d+(?:\.\d+)?|\.\d+))\s*,\s*([+-]?(?:\d+(?:\.\d+)?|\.\d+))\s*,\s*([+-]?(?:\d+(?:\.\d+)?|\.\d+))\s*,\s*([+-]?(?:\d+(?:\.\d+)?|\.\d+))\s*\)$/;
+const HEX_RE = /^#([\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/i;
+/**
+* Converts a W3C DTCG 2025.10 document into the schema tree and bare token
+* tree {@link createTheme} accepts.
+*
+* A token resolves its type in DTCG order: its own `$type`, the resolved type
+* of a whole-value `{reference}`, then the nearest ancestor group's `$type`.
+* `$description`, `$deprecated`, and `$extensions` are intentionally discarded
+* until schema factories gain a metadata options bag. Typography tokens are not
+* supported because one typography value would need several custom properties.
+*
+* Runtime JSON cannot preserve literal paths, so using this init with
+* {@link createTheme} produces an unbranded accessor. Generate TypeScript from
+* the result for the typed path.
+*
+* @param document - A DTCG document using `$value`, `$type`, and dotted references
+* @returns A runtime {@link ThemeInit}-shaped schema and token tree
+* @throws ThemeError for malformed groups, unsupported typography, unknown types,
+* unresolvable references, cycles, or malformed structured DTCG values
+*
+* @example
+* ```ts
+* import { createTheme } from "@pitlane/theme";
+* import { fromDTCG } from "@pitlane/theme/dtcg";
+*
+* let imported = fromDTCG({
+*     color: {
+*         $type: "color",
+*         white: { $value: "#fff" },
+*         page: { $value: "{color.white}" },
+*     },
+* });
+* let theme = createTheme(imported);
+* ```
+*/
+function fromDTCG(document) {
+	let entries = /* @__PURE__ */ new Map();
+	let root = walkDocument(record(document, "$root"), [], void 0, entries);
+	let tags = resolveTags(entries);
+	let varNames = variableNames(entries.values());
+	let context = importReferenceContext(entries, tags, varNames);
+	return {
+		schema: schemaTree(root, tags),
+		tokens: tokenTree(root, tags, context, (key) => varNames.get(key))
+	};
+}
+/**
+* Exports a compiled theme, a published theme component, or the init behind
+* either one to W3C DTCG 2025.10 documents.
+*
+* An export places `$type` on the lowest group whose complete descendant set
+* has one expressible type; standard tokens below that group omit the redundant
+* `$type`. Mixed groups put `$type` on their standard token leaves instead.
+* Exact `var(--token-name)` values are converted back to `{token.path}` using
+* the collector's variable-name map.
+*
+* DTCG cannot represent all CSS values this package accepts. Inexpressible
+* values are preserved in `$extensions["tools.pitlane"]` as
+* `{ type, value, reason }`, on an extension-only node with no `$value`; this
+* keeps the standard document valid while preserving the original value for a
+* caller that reports or handles the loss. `inexpressible` counts those nodes in
+* the base document and every mode document.
+*
+* DTCG descriptions, deprecation metadata, and unrelated extensions are not in
+* the authoring format and cannot be recovered.
+*
+* @param theme - A {@link ThemeResult}, its {@link ThemeComponent}, or its init
+* @returns The base document, one partial document per mode, and the lossy-value count
+* @throws ThemeError when the supplied init has an invalid token/schema structure
+*
+* @example
+* ```ts
+* import { createTheme } from "@pitlane/theme";
+* import { toDTCG } from "@pitlane/theme/dtcg";
+* import * as s from "@pitlane/theme/schema";
+*
+* let theme = createTheme({
+*     schema: { color: s.color() },
+*     tokens: { color: { white: "#fff" } },
+* });
+* let { document, inexpressible } = toDTCG(theme);
+* ```
+*/
+function toDTCG(theme) {
+	let init = themeInit(theme);
+	let schema = init.schema;
+	let baseEntries = collectTokens(init.tokens, schema);
+	let base = exportDocument(baseEntries, baseEntries);
+	let modes = {};
+	let inexpressible = base.inexpressible;
+	for (let [name, mode] of Object.entries(init.modes ?? {})) {
+		let exported = exportDocument(collectTokens(mode.tokens, schema), baseEntries);
+		modes[name] = exported.document;
+		inexpressible += exported.inexpressible;
+	}
+	return {
+		document: base.document,
+		modes,
+		inexpressible
+	};
+}
+function walkDocument(node, path, inheritedType, entries) {
+	let key = path.length === 0 ? "$root" : path.join(".");
+	let ownType = validateType(node.$type, key);
+	let effectiveType = ownType ?? inheritedType;
+	let group = {
+		ownType,
+		children: {}
+	};
+	for (let [childName, child] of Object.entries(node)) {
+		if (childName.startsWith("$")) continue;
+		let childPath = [...path, childName];
+		let childKey = childPath.join(".");
+		validateName(childName, childKey);
+		let childRecord = record(child, childKey);
+		if ("$value" in childRecord) {
+			let token = {
+				key: childKey,
+				path: childPath,
+				ownTag: validateType(childRecord.$type, childKey),
+				inheritedType: effectiveType,
+				value: childRecord.$value
+			};
+			group.children[childName] = token;
+			entries.set(childKey, token);
+			continue;
+		}
+		group.children[childName] = walkDocument(childRecord, childPath, effectiveType, entries);
+	}
+	return group;
+}
+function resolveTags(entries) {
+	let tags = /* @__PURE__ */ new Map();
+	for (let key of entries.keys()) tags.set(key, resolveTag(key, entries, []));
+	return tags;
+}
+function resolveTag(key, entries, chain) {
+	if (chain.includes(key)) throw new ThemeError(`Alias cycle: ${[...chain, key].join(" → ")}`);
+	let entry = entries.get(key);
+	if (entry === void 0) throw new ThemeError(`"${chain[chain.length - 1] ?? key}" references unknown token "${key}"`);
+	if (entry.ownTag !== void 0) return entry.ownTag;
+	let alias = dtcgAlias(entry.value);
+	if (alias !== null) return resolveTag(alias, entries, [...chain, key]);
+	if (entry.inheritedType !== void 0) return entry.inheritedType;
+	throw new ThemeError(`"${key}" has no resolvable $type`);
+}
+function variableNames(entries) {
+	let byVarName = /* @__PURE__ */ new Map();
+	let byKey = /* @__PURE__ */ new Map();
+	for (let entry of entries) {
+		let varName = `--${entry.path.map(kebabSegment).join("-")}`;
+		let existing = byVarName.get(varName);
+		if (existing !== void 0) throw new ThemeError(`Tokens "${existing.key}" and "${entry.key}" both produce the CSS variable ${varName}`);
+		byVarName.set(varName, entry);
+		byKey.set(entry.key, varName);
+	}
+	return byKey;
+}
+function importReferenceContext(entries, tags, varNameByKey) {
+	return { varRefFor(key, from, expected) {
+		let target = entries.get(key);
+		if (target === void 0) throw new ThemeError(`"${from}" references unknown token "${key}"`);
+		let type = tags.get(target.key);
+		if (type !== expected) throw new ThemeError(`"${from}" references "${key}" of type "${type}" where "${expected}" is required`);
+		return `var(${varNameByKey.get(target.key)})`;
+	} };
+}
+function schemaTree(root, tags) {
+	let schema = {};
+	for (let [key, child] of Object.entries(root.children)) {
+		if (isRawToken(child)) {
+			schema[key] = schemaFor(tags.get(child.key));
+			continue;
+		}
+		let childSchema = groupSchema(child, root.ownType, tags);
+		if (childSchema === void 0) {
+			if (root.ownType === void 0) continue;
+			schema[key] = schemaFor(root.ownType);
+		} else if (child.ownType === void 0 && root.ownType !== void 0) schema[key] = group(schemaFor(root.ownType), childSchema);
+		else schema[key] = childSchema;
+	}
+	return schema;
+}
+function groupSchema(group$1, inherited, tags) {
+	let effective = group$1.ownType ?? inherited;
+	let children = {};
+	for (let [key, child] of Object.entries(group$1.children)) {
+		if (isRawToken(child)) {
+			let tag = tags.get(child.key);
+			if (tag !== effective) children[key] = schemaFor(tag);
+			continue;
+		}
+		let childSchema = groupSchema(child, effective, tags);
+		if (childSchema !== void 0) children[key] = childSchema;
+	}
+	if (group$1.ownType === void 0) return Object.keys(children).length === 0 ? void 0 : children;
+	let self = schemaFor(group$1.ownType);
+	return Object.keys(children).length === 0 ? self : group(self, children);
+}
+function tokenTree(group, tags, context, varNameFor) {
+	let tokens = {};
+	for (let [key, child] of Object.entries(group.children)) if (isRawToken(child)) tokens[key] = authorValue(child, tags.get(child.key), context, varNameFor);
+	else tokens[key] = tokenTree(child, tags, context, varNameFor);
+	return tokens;
+}
+function authorValue(entry, tag, context, varNameFor) {
+	let value = convertAliases(entry.value, entry.key, varNameFor);
+	if (isTokenValue(value)) return value;
+	return serializeValue(tag, value, context, entry.key);
+}
+function schemaFor(tag) {
+	switch (tag) {
+		case "color": return color();
+		case "dimension": return dimension();
+		case "duration": return duration();
+		case "number": return number();
+		case "cubicBezier": return easing();
+		case "shadow": return shadow();
+		case "border": return border();
+		case "transition": return transition();
+		case "gradient": return gradient();
+		case "strokeStyle": return stroke();
+		case "fontFamily": return font.family();
+		case "fontWeight": return font.weight();
+	}
+}
+function exportDocument(entries, referenceEntries) {
+	let byVarName = new Map(referenceEntries.map((entry) => [entry.varName, entry]));
+	let root = { children: /* @__PURE__ */ new Map() };
+	let inexpressible = 0;
+	for (let entry of entries) {
+		let node = root;
+		for (let [index, key] of entry.path.entries()) {
+			let child = node.children.get(key);
+			if (child === void 0) {
+				child = { children: /* @__PURE__ */ new Map() };
+				node.children.set(key, child);
+			}
+			node = child;
+			if (index === entry.path.length - 1) {
+				let encoded = encodeToken(entry, byVarName);
+				node.token = encoded;
+				if (encoded.extension !== void 0) inexpressible += 1;
+			}
+		}
+	}
+	return {
+		document: emitDocument(root),
+		inexpressible
+	};
+}
+function encodeToken(entry, byVarName) {
+	let value = reverseAccessorReference(entry.value, byVarName);
+	if (entry.kind === "untyped") return extensionToken("any", value, "Tokens declared with s.any() have no DTCG type");
+	let type = entry.kind === "scale" ? "dimension" : entry.type;
+	let encoded = encodeValue(type, value);
+	if (encoded === void 0) return extensionToken(entry.kind === "scale" ? "scale" : entry.type, value, entry.kind === "scale" ? "A scale token exports only its base dimension, not multiplier results" : inexpressibleReason(type));
+	return {
+		type,
+		value: encoded
+	};
+}
+function encodeValue(type, value) {
+	if (referenceTarget(value) !== null || dtcgAlias(value) !== null) return value;
+	switch (type) {
+		case "color": return typeof value === "string" ? encodeHexColor(value) : void 0;
+		case "dimension": return typeof value === "string" ? encodeMeasure(value, DIMENSION_RE) : void 0;
+		case "duration": return typeof value === "string" ? encodeMeasure(value, DURATION_RE) : void 0;
+		case "fontFamily": return isFontFamily(value) ? value : void 0;
+		case "fontWeight": return typeof value === "number" || typeof value === "string" ? value : void 0;
+		case "number": return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+		case "cubicBezier": return encodeCubicBezier(value);
+		case "strokeStyle": return typeof value === "string" ? value : void 0;
+		case "shadow":
+		case "border":
+		case "transition":
+		case "gradient": return;
+	}
+}
+function encodeHexColor(value) {
+	let match = HEX_RE.exec(value);
+	if (match === null) return void 0;
+	let hex = match[1];
+	let pairs = hex.length <= 4 ? (hex.match(/./g) ?? []).map((part) => `${part}${part}`) : hex.match(/.{2}/g);
+	let components = pairs.slice(0, 3).map((part) => Number.parseInt(part, 16) / 255);
+	let alpha = pairs[3] === void 0 ? void 0 : Number.parseInt(pairs[3], 16) / 255;
+	return {
+		colorSpace: "srgb",
+		components,
+		...alpha === void 0 ? {} : { alpha },
+		hex: value
+	};
+}
+function encodeMeasure(value, expression) {
+	let match = expression.exec(value);
+	if (match === null) return void 0;
+	let amount = Number(match[1]);
+	return Number.isFinite(amount) ? {
+		value: amount,
+		unit: match[2]
+	} : void 0;
+}
+function encodeCubicBezier(value) {
+	if (Array.isArray(value) && value.length === 4 && value.every((part) => typeof part === "number" && Number.isFinite(part))) return value;
+	if (typeof value !== "string") return void 0;
+	let match = CUBIC_BEZIER_RE.exec(value);
+	if (match === null) return void 0;
+	let parts = match.slice(1).map(Number);
+	return parts.every(Number.isFinite) ? parts : void 0;
+}
+function extensionToken(type, value, reason) {
+	return { extension: {
+		type,
+		value,
+		reason
+	} };
+}
+function emitDocument(node, inheritedType) {
+	let type = uniformType(node);
+	let effectiveType = type ?? inheritedType;
+	let document = {};
+	if (type !== void 0 && type !== inheritedType) document.$type = type;
+	for (let [key, child] of node.children) {
+		if (child.token !== void 0) {
+			if (child.token.extension !== void 0) {
+				document[key] = { $extensions: { "tools.pitlane": child.token.extension } };
+				continue;
+			}
+			let token = { $value: child.token.value };
+			if (child.token.type !== effectiveType) token.$type = child.token.type;
+			document[key] = token;
+			continue;
+		}
+		document[key] = emitDocument(child, effectiveType);
+	}
+	return document;
+}
+function uniformType(node) {
+	let uniform;
+	let isUniform = true;
+	let found = false;
+	function visit(child) {
+		if (!isUniform) return;
+		if (child.token !== void 0) {
+			let type = child.token.type;
+			if (type === void 0) {
+				isUniform = false;
+				return;
+			}
+			if (uniform !== void 0 && uniform !== type) {
+				isUniform = false;
+				return;
+			}
+			uniform = type;
+			found = true;
+			return;
+		}
+		for (let nested of child.children.values()) visit(nested);
+	}
+	for (let child of node.children.values()) visit(child);
+	return isUniform && found ? uniform : void 0;
+}
+function reverseAccessorReference(value, byVarName) {
+	if (typeof value !== "string") return value;
+	let match = ACCESSOR_REFERENCE_RE.exec(value);
+	if (match === null) return value;
+	let target = byVarName.get(match[1]);
+	return target === void 0 ? value : `{${target.key}}`;
+}
+function themeInit(theme) {
+	if (typeof theme === "function") return theme.$theme;
+	if ("Theme" in theme) return theme.Theme.$theme;
+	return theme;
+}
+function validateType(value, key) {
+	if (value === void 0) return void 0;
+	if (value === "typography") throw new ThemeError(`"${key}": typography tokens are not supported in v1`);
+	if (!TOKEN_TYPES.includes(value)) throw new ThemeError(`"${key}" has unknown $type ${JSON.stringify(value)}`);
+	return value;
+}
+function validateName(name, key) {
+	if (/[.{}]/.test(name)) throw new ThemeError(`Token or group name "${key}" contains characters reserved by references (".", "{", "}")`);
+}
+function record(value, key) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new ThemeError(`"${key}" is neither a group nor a token`);
+	return value;
+}
+function isRawToken(value) {
+	return "key" in value;
+}
+function isTokenValue(value) {
+	return typeof value === "string" || typeof value === "number" || Array.isArray(value) && value.every((part) => typeof part === "string" || typeof part === "number");
+}
+function isFontFamily(value) {
+	return typeof value === "string" || Array.isArray(value) && value.every((part) => typeof part === "string");
+}
+function inexpressibleReason(type) {
+	switch (type) {
+		case "color": return "Only hexadecimal CSS colors can be represented as DTCG color values";
+		case "dimension": return "Only px and rem dimensions can be represented as DTCG dimension values";
+		case "duration": return "Only ms and s durations can be represented as DTCG duration values";
+		case "fontFamily":
+		case "fontWeight":
+		case "number":
+		case "cubicBezier":
+		case "strokeStyle": return "The value is outside the DTCG value grammar";
+		case "shadow":
+		case "border":
+		case "transition":
+		case "gradient": return "CSS composite text has no DTCG representation";
+	}
+}
+//#endregion
+export { fromDTCG, toDTCG };