@yahoo/uds-v5-wip 1.61.0 → 1.62.0

package/dist/config/dist/refs.js

@@ -1,122 +1,104 @@
-import { kebabCase } from "../../utils/dist/string-utils/kebabCase.js";
-import { safeTokenName } from "../../utils/dist/string-utils/cssVar.js";
-import "../../utils/dist/index.js";
 //#region ../config/dist/refs.js
-/**
-* Token references inside `defineVars` token values + downstream CSS
-* emission. Authors point one token at another via the `token()` helper:
-*
-*   defineVars({
-*     spectrum: { 'blue/500': { value: '#1167f4' } },
-*     color:    { brand:      { value: token('spectrum/blue/500') } },
-*   })
-*
-* At CSS-declaration time this expands to a CSS variable alias:
-*
-*   --uds-spectrum-blue-500: #1167f4;
-*   --uds-color-brand: var(--uds-spectrum-blue-500);
-*
-* Aliases are a purely syntactic transform — no graph walk, no cycle
-* detection. CSS handles aliasing (and any cascade cycles) at runtime.
-* Aliases pointing at unknown tokens resolve to a `var(...)` with no
-* `:root` declaration; the browser falls back to the property's
-* initial value.
-*/
-/**
-* Resolve a token value to its CSS form. `TokenMarker` from
-* `token('ns/name')` becomes `var(--<prefix>-<ns>-<name>)`; string
-* literals pass through unchanged.
-*
-* The CSS variable name follows `defineVars`'s `:root` declaration
-* convention: `kebabCase` on the namespace, `safeTokenName` on the
-* token name.
-*/
-function resolveTokenValue(value, configPrefix) {
-	if (typeof value === "string") return value;
-	const ref = value.ref;
-	const slashIdx = ref.indexOf("/");
-	if (slashIdx <= 0 || slashIdx >= ref.length - 1) return ref;
-	return refToVar(ref.slice(0, slashIdx), ref.slice(slashIdx + 1), configPrefix);
-}
-function refToVar(namespace, name, configPrefix) {
-	const cssPrefix = kebabCase(namespace);
-	const cssName = safeTokenName(name);
-	return `var(${configPrefix ? `--${configPrefix}-${cssPrefix}-${cssName}` : `--${cssPrefix}-${cssName}`})`;
-}
-/**
-* Type-guard: a value is a `TokenWithModifier` marker.
-*/
-function isTokenWithModifier(value) {
-	return typeof value === "object" && value !== null && "$token" in value && "$modifier" in value;
-}
-/**
-* Resolve a `TokenWithModifier` marker to its CSS value:
-*  - `darken(N)`  → `color-mix(in oklch, var(...), light-dark(black, white) N%)`
-*  - `lighten(N)` → `color-mix(in oklch, var(...), light-dark(white, black) N%)`
-*
-* Output matches the runtime helpers `darker` / `lighter` in
-* `createConfig.ts` byte-for-byte so mechanical conversion of legacy
-* callback-form components preserves compiled CSS.
-*/
-function resolveTokenWithModifier(marker, configPrefix) {
-	const slashIdx = marker.$token.indexOf("/");
-	if (slashIdx <= 0 || slashIdx >= marker.$token.length - 1) return marker.$token;
-	const resolved = refToVar(marker.$token.slice(0, slashIdx), marker.$token.slice(slashIdx + 1), configPrefix);
-	const amount = marker.$modifier.amount;
-	if (marker.$modifier.type === "darken") return `color-mix(in oklch, ${resolved}, light-dark(black, white) ${amount}%)`;
-	return `color-mix(in oklch, ${resolved}, light-dark(white, black) ${amount}%)`;
-}
-/**
-* Author-time helper that produces a darkened color-token reference for
-* use in component-config style blocks. Takes a `TokenMarker` (from
-* `token('ns/name')`) plus a mix amount, and returns a structured
-* marker (`{ $token, $modifier }`) that codegen resolves at build
-* time to:
-*
-*     color-mix(in oklch, var(--<prefix>-<ns>-<name>),
-*               light-dark(black, white) <amount>%)
-*
-*     defineComponent
-*       .layers({ root: 'div' })
-*       .config(({ enums, token }) => ({
-*         props: {
-*           variant: enums({
-*             brand: {
-*               root: {
-*                 backgroundColor: token('bg/brand'),
-*                 _hover: { backgroundColor: darken(token('bg/brand'), 10) },
-*               },
-*             },
-*           }),
-*         },
-*       }));
-*
-* The token reference stays portable across configs with different
-* prefixes because the prefix is supplied at codegen time, not at
-* author time.
-*/
-function darken(ref, amount) {
+function token(ref) {
 	return {
-		$token: ref.ref,
-		$modifier: {
-			type: "darken",
-			amount
-		}
+		__kind: "token",
+		ref
 	};
 }
-/**
-* Author-time helper that produces a lightened color-token reference.
-* Mirror of `darken()` — see its JSDoc. Resolves at codegen time to
-* `color-mix(in oklch, var(--<prefix>-<ns>-<name>), light-dark(white, black) N%)`.
-*/
-function lighten(ref, amount) {
+function tokenGroup(ref) {
 	return {
-		$token: ref.ref,
-		$modifier: {
-			type: "lighten",
-			amount
+		__kind: "tokenGroup",
+		ref
+	};
+}
+function composite(ref) {
+	return Object.assign({
+		__kind: "composite",
+		ref
+	}, { on(layer) {
+		return {
+			__kind: "composite",
+			ref,
+			layer
+		};
+	} });
+}
+function mode(ref) {
+	return {
+		__kind: "mode",
+		ref
+	};
+}
+function styleProp(ref) {
+	const marker = {
+		__kind: "styleProp",
+		ref
+	};
+	Object.defineProperty(marker, "on", {
+		enumerable: false,
+		configurable: true,
+		writable: true,
+		value(layer) {
+			const next = {
+				__kind: "styleProp",
+				ref,
+				layer
+			};
+			Object.defineProperty(next, "on", {
+				enumerable: false,
+				configurable: true,
+				writable: true,
+				value: marker.on
+			});
+			return next;
 		}
+	});
+	return marker;
+}
+function tag(ref) {
+	return {
+		__kind: "tag",
+		ref
+	};
+}
+function component(ref) {
+	return {
+		__kind: "component",
+		ref
 	};
 }
+function assetGroup(ref) {
+	return {
+		__kind: "assetGroup",
+		ref
+	};
+}
+function isRefOf(value, kind) {
+	return typeof value === "object" && value !== null && value.__kind === kind;
+}
+function isTokenRef(value) {
+	return isRefOf(value, "token");
+}
+function isTokenGroupRef(value) {
+	return isRefOf(value, "tokenGroup");
+}
+function isCompositeRef(value) {
+	return isRefOf(value, "composite");
+}
+function isModeRef(value) {
+	return isRefOf(value, "mode");
+}
+function isStylePropRef(value) {
+	return isRefOf(value, "styleProp");
+}
+function isTagRef(value) {
+	return isRefOf(value, "tag");
+}
+function isComponentRef(value) {
+	return isRefOf(value, "component");
+}
+function isAssetGroupRef(value) {
+	return isRefOf(value, "assetGroup");
+}
 //#endregion
-export { darken, isTokenWithModifier, lighten, resolveTokenValue, resolveTokenWithModifier };
+export { assetGroup, component, composite, isAssetGroupRef, isComponentRef, isCompositeRef, isModeRef, isStylePropRef, isTagRef, isTokenGroupRef, isTokenRef, mode, styleProp, tag, token, tokenGroup };

package/dist/config/dist/token-override-rows.d.ts

@@ -0,0 +1,67 @@
+import { TokenModifierKey } from "./types.js";
+
+//#region ../config/dist/token-override-rows.d.ts
+//#region src/token-override-rows.d.ts
+type OverrideModeRef = `${string}.${string}`;
+type ModifierTreeValue<TValue> = TValue | {
+  value?: TValue;
+  [modifier: TokenModifierKey]: ModifierTreeValue<TValue> | undefined;
+};
+type ModifierTree<TValue> = Partial<Record<TokenModifierKey, ModifierTreeValue<TValue>>>;
+type ModifierUpdateValue<TValue> = TValue | null | ModifierUpdateObject<TValue>;
+interface ModifierUpdateObject<TValue> {
+  value?: TValue | null;
+  [key: string]: ModifierUpdateValue<TValue> | undefined;
+  [modifier: TokenModifierKey]: ModifierUpdateValue<TValue> | undefined;
+}
+type ModifierUpdate<TValue> = Record<string, ModifierUpdateValue<TValue> | undefined>;
+interface ModeBackedModifierInput {
+  modifier: TokenModifierKey;
+  mode: string;
+  option: string;
+  label?: string;
+  modeOrder: number;
+  optionOrder: number;
+}
+interface ModeBackedModifierDefinition extends ModeBackedModifierInput {
+  modeRef: OverrideModeRef;
+}
+interface ModeBackedModifierLookup {
+  byModifier: ReadonlyMap<TokenModifierKey, ModeBackedModifierDefinition>;
+  byModeRef: ReadonlyMap<OverrideModeRef, ModeBackedModifierDefinition>;
+}
+interface OverrideRow<TValue = string> {
+  modes: OverrideModeRef[];
+  value: TValue;
+  sourceModifierPath: TokenModifierKey[];
+  sourceOrder: number;
+}
+interface ModeBackedModeMetadata {
+  name: string;
+  options: readonly {
+    name: string;
+    label?: string;
+  }[];
+}
+interface ModeBackedModifierMetadata {
+  modifier: TokenModifierKey;
+  selector?: unknown;
+}
+declare function createModeBackedModifierLookup(inputs: readonly ModeBackedModifierInput[]): ModeBackedModifierLookup;
+declare function buildModeBackedModifierLookup(modes: readonly ModeBackedModeMetadata[], modifiers: readonly ModeBackedModifierMetadata[]): ModeBackedModifierLookup;
+declare function modifierTreeToOverrideRows<TValue>(modifiers: ModifierTree<TValue> | undefined, lookup: ModeBackedModifierLookup): OverrideRow<TValue>[];
+declare function overrideRowsToModifierTree<TValue>(rows: readonly OverrideRow<TValue>[], lookup: ModeBackedModifierLookup): ModifierTree<TValue>;
+declare function resolveOverrideRowValue<TValue>(baseValue: TValue, rows: readonly Pick<OverrideRow<TValue>, 'modes' | 'value'>[], activeModes: Iterable<OverrideModeRef>): TValue;
+declare function modifierPathToId(path: readonly TokenModifierKey[]): string;
+declare function modifierIdToPath(id: string): TokenModifierKey[];
+declare function buildNestedModifierUpdate<TValue>(modifierPath: readonly TokenModifierKey[], value: ModifierUpdateValue<TValue>): Record<TokenModifierKey, ModifierUpdateValue<TValue>>;
+/**
+ * Combines multiple token-modifier update payloads into one patch
+ * object. Later updates win on scalar/null leaves; object branches
+ * deep-merge so swap operations can delete one nested row and set
+ * another nested row under the same parent modifier in a single
+ * patch.
+ */
+declare function mergeModifierUpdates<TValue>(...updates: readonly ModifierUpdate<TValue>[]): Record<string, ModifierUpdateValue<TValue>>; //#endregion
+//#endregion
+export { ModeBackedModifierDefinition, ModeBackedModifierInput, ModeBackedModifierLookup, OverrideModeRef, OverrideRow, buildModeBackedModifierLookup, buildNestedModifierUpdate, createModeBackedModifierLookup, mergeModifierUpdates, modifierIdToPath, modifierPathToId, modifierTreeToOverrideRows, overrideRowsToModifierTree, resolveOverrideRowValue };

package/dist/config/dist/token-override-rows.js

@@ -0,0 +1,223 @@
+//#region ../config/dist/token-override-rows.js
+function createModeBackedModifierLookup(inputs) {
+	const byModifier = /* @__PURE__ */ new Map();
+	const byModeRef = /* @__PURE__ */ new Map();
+	for (const input of inputs) {
+		const definition = {
+			...input,
+			modeRef: `${input.mode}.${input.option}`
+		};
+		byModifier.set(input.modifier, definition);
+		byModeRef.set(definition.modeRef, definition);
+	}
+	return {
+		byModifier,
+		byModeRef
+	};
+}
+function buildModeBackedModifierLookup(modes, modifiers) {
+	const optionMetadata = /* @__PURE__ */ new Map();
+	modes.forEach((mode, modeOrder) => {
+		mode.options.forEach((option, optionOrder) => {
+			optionMetadata.set(`${mode.name}/${option.name}`, {
+				mode: mode.name,
+				option: option.name,
+				label: option.label ?? option.name,
+				modeOrder,
+				optionOrder
+			});
+		});
+	});
+	const inputs = [];
+	for (const modifier of modifiers) {
+		const marker = getModeMarker(modifier.selector);
+		if (!marker) continue;
+		const metadata = optionMetadata.get(marker.ref);
+		if (!metadata) continue;
+		inputs.push({
+			...metadata,
+			modifier: modifier.modifier
+		});
+	}
+	return createModeBackedModifierLookup(inputs);
+}
+function modifierTreeToOverrideRows(modifiers, lookup) {
+	const rows = [];
+	let sourceOrder = 0;
+	const visit = (value, modifierPath) => {
+		const node = asModifierNode(value);
+		const modes = canonicalizeModifierPath(modifierPath, lookup);
+		if (!node) {
+			rows.push({
+				modes,
+				value,
+				sourceModifierPath: modifierPath,
+				sourceOrder
+			});
+			sourceOrder++;
+			return;
+		}
+		if (Object.hasOwn(node, "value") && node.value !== void 0) {
+			rows.push({
+				modes,
+				value: node.value,
+				sourceModifierPath: modifierPath,
+				sourceOrder
+			});
+			sourceOrder++;
+		}
+		for (const [key, nestedValue] of Object.entries(node)) {
+			if (key === "value" || nestedValue === void 0) continue;
+			if (!isModifierKey(key) || !lookup.byModifier.has(key)) continue;
+			visit(nestedValue, [...modifierPath, key]);
+		}
+	};
+	for (const [modifier, value] of Object.entries(modifiers ?? {})) {
+		if (value === void 0) continue;
+		if (!isModifierKey(modifier) || !lookup.byModifier.has(modifier)) continue;
+		visit(value, [modifier]);
+	}
+	return rows;
+}
+function overrideRowsToModifierTree(rows, lookup) {
+	const tree = {};
+	for (const row of rows) {
+		const path = resolveWritableModifierPath(row, lookup);
+		if (path.length === 0) continue;
+		assignModifierPath(tree, path, row.value);
+	}
+	return tree;
+}
+function resolveOverrideRowValue(baseValue, rows, activeModes) {
+	const active = new Set(activeModes);
+	let resolved = baseValue;
+	let bestSpecificity = -1;
+	let bestOrder = -1;
+	rows.forEach((row, order) => {
+		if (!row.modes.every((mode) => active.has(mode))) return;
+		const specificity = row.modes.length;
+		if (specificity < bestSpecificity) return;
+		if (specificity === bestSpecificity && order < bestOrder) return;
+		resolved = row.value;
+		bestSpecificity = specificity;
+		bestOrder = order;
+	});
+	return resolved;
+}
+function modifierPathToId(path) {
+	return path.join(".");
+}
+function modifierIdToPath(id) {
+	return id.split(".").filter(isModifierKey).map((part) => part);
+}
+function buildNestedModifierUpdate(modifierPath, value) {
+	if (modifierPath.length === 0) return {};
+	const [first, ...rest] = modifierPath;
+	if (!first) return {};
+	if (rest.length === 0) return { [first]: value };
+	return { [first]: buildNestedModifierUpdate(rest, value) };
+}
+/**
+* Combines multiple token-modifier update payloads into one patch
+* object. Later updates win on scalar/null leaves; object branches
+* deep-merge so swap operations can delete one nested row and set
+* another nested row under the same parent modifier in a single
+* patch.
+*/
+function mergeModifierUpdates(...updates) {
+	const merged = {};
+	for (const update of updates) mergeModifierUpdateInto(merged, update);
+	return merged;
+}
+function getModeMarker(selector) {
+	if (typeof selector !== "object" || selector === null) return null;
+	const marker = selector;
+	if (marker.__kind !== "mode" || typeof marker.ref !== "string") return null;
+	return {
+		__kind: "mode",
+		ref: marker.ref
+	};
+}
+function mergeModifierUpdateInto(target, update) {
+	for (const [key, value] of Object.entries(update)) {
+		if (value === void 0) continue;
+		const current = target[key];
+		if (isModifierUpdateObject(current) && isModifierUpdateObject(value)) {
+			target[key] = mergeModifierUpdateObjects(current, value);
+			continue;
+		}
+		target[key] = value;
+	}
+}
+function mergeModifierUpdateObjects(current, update) {
+	const merged = {};
+	for (const [key, value] of Object.entries(current)) if (value !== void 0) merged[key] = value;
+	mergeModifierUpdateInto(merged, update);
+	return merged;
+}
+function isModifierUpdateObject(value) {
+	return typeof value === "object" && value !== null;
+}
+function canonicalizeModifierPath(modifierPath, lookup) {
+	return modifierPath.map((modifier) => lookup.byModifier.get(modifier)).filter((definition) => definition !== void 0).sort(compareModeBackedModifiers).map((definition) => definition.modeRef);
+}
+function resolveWritableModifierPath(row, lookup) {
+	if (pathMatchesModes(row.sourceModifierPath, row.modes, lookup)) return row.sourceModifierPath;
+	return row.modes.map((modeRef) => lookup.byModeRef.get(modeRef)).filter((definition) => definition !== void 0).sort(compareModeBackedModifiers).map((definition) => definition.modifier);
+}
+function pathMatchesModes(path, modes, lookup) {
+	if (path.length !== modes.length) return false;
+	const pathModes = canonicalizeModifierPath(path, lookup);
+	const expectedModes = [...modes].sort((a, b) => compareModeBackedModifiersByRef(a, b, lookup));
+	return pathModes.length === expectedModes.length && pathModes.every((mode, index) => mode === expectedModes[index]);
+}
+function assignModifierPath(tree, path, value) {
+	const [modifier, ...rest] = path;
+	if (!modifier) return;
+	if (rest.length === 0) {
+		tree[modifier] = mergeLeafValue(tree[modifier], value);
+		return;
+	}
+	const current = tree[modifier];
+	const node = asWritableModifierNode(current);
+	tree[modifier] = node;
+	assignModifierPath(node, rest, value);
+}
+function mergeLeafValue(current, value) {
+	const node = asModifierNode(current);
+	if (!node) return value;
+	return {
+		...node,
+		value
+	};
+}
+function asWritableModifierNode(current) {
+	const node = asModifierNode(current);
+	if (node) return { ...node };
+	if (current !== void 0) return { value: current };
+	return {};
+}
+function asModifierNode(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+	if (Object.hasOwn(value, "value")) return value;
+	if (Object.keys(value).some(isModifierKey)) return value;
+	return null;
+}
+function isModifierKey(value) {
+	return value.startsWith("_");
+}
+function compareModeBackedModifiers(a, b) {
+	if (a.modeOrder !== b.modeOrder) return a.modeOrder - b.modeOrder;
+	if (a.optionOrder !== b.optionOrder) return a.optionOrder - b.optionOrder;
+	return a.modifier.localeCompare(b.modifier);
+}
+function compareModeBackedModifiersByRef(a, b, lookup) {
+	const aDefinition = lookup.byModeRef.get(a);
+	const bDefinition = lookup.byModeRef.get(b);
+	if (aDefinition && bDefinition) return compareModeBackedModifiers(aDefinition, bDefinition);
+	if (aDefinition) return -1;
+	if (bDefinition) return 1;
+	return a.localeCompare(b);
+}
+//#endregion
+export { buildModeBackedModifierLookup, buildNestedModifierUpdate, createModeBackedModifierLookup, mergeModifierUpdates, modifierIdToPath, modifierPathToId, modifierTreeToOverrideRows, overrideRowsToModifierTree, resolveOverrideRowValue };

package/dist/config/dist/tokenValueType.js

@@ -0,0 +1,138 @@
+//#region ../config/dist/tokenValueType.js
+const CSS_STRING_KEYWORDS = new Set([
+	"inherit",
+	"initial",
+	"unset",
+	"revert",
+	"revert-layer",
+	"auto",
+	"none",
+	"currentColor",
+	"currentcolor",
+	"transparent",
+	"min-content",
+	"max-content",
+	"fit-content"
+]);
+const HEX_COLOR_RE = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+const COLOR_FUNCTION_RE = /^(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color|color-mix|light-dark)\s*\(/i;
+const GRADIENT_FUNCTION_RE = /^(?:linear|radial|conic|repeating-linear|repeating-radial|repeating-conic)-gradient\s*\(/i;
+const EASING_FUNCTION_RE = /^(?:cubic-bezier|steps)\s*\(/i;
+const EASING_KEYWORDS = new Set([
+	"linear",
+	"ease",
+	"ease-in",
+	"ease-out",
+	"ease-in-out",
+	"step-start",
+	"step-end"
+]);
+const NAMED_COLOR_KEYWORDS = new Set([
+	"aliceblue",
+	"antiquewhite",
+	"aqua",
+	"aquamarine",
+	"azure",
+	"beige",
+	"bisque",
+	"black",
+	"blue",
+	"brown",
+	"crimson",
+	"cyan",
+	"fuchsia",
+	"gold",
+	"gray",
+	"grey",
+	"green",
+	"indigo",
+	"lavender",
+	"lime",
+	"magenta",
+	"maroon",
+	"navy",
+	"olive",
+	"orange",
+	"pink",
+	"purple",
+	"red",
+	"salmon",
+	"silver",
+	"teal",
+	"tomato",
+	"violet",
+	"white",
+	"yellow"
+]);
+const NUMBER_RE_SRC = "(?:\\d+(?:\\.\\d+)?|\\.\\d+)";
+const DIMENSION_RE = new RegExp(`^-?${NUMBER_RE_SRC}(?:px|rem|em|%|vh|vw|vmin|vmax|vi|vb|svh|svw|lvh|lvw|dvh|dvw|ch|ex|cap|ic|lh|rlh|pt|pc|in|cm|mm|q|fr|deg|turn|rad|grad)$`, "i");
+const DURATION_RE = new RegExp(`^-?${NUMBER_RE_SRC}(?:ms|s)$`, "i");
+const PURE_NUMBER_RE = new RegExp(`^-?${NUMBER_RE_SRC}$`);
+const RATIO_RE = /^\d+(?:\.\d+)?\s*\/\s*\d+(?:\.\d+)?$/;
+const SHADOW_LENGTH_RE = /(?:^|[\s,])-?\d+(?:\.\d+)?(?:px|rem|em|ch|ex)/i;
+const SHADOW_COLOR_RE = /(?:rgba?|hsla?|color|oklch|oklab|lch|lab|hwb)\(|#[0-9a-fA-F]{3,8}\b/;
+function looksLikeShadow(value) {
+	return SHADOW_LENGTH_RE.test(value) && SHADOW_COLOR_RE.test(value);
+}
+/**
+* Heuristic CSS-value classifier. Given a raw value string, returns the
+* best-guess type or `undefined` when no confident match is possible
+* (e.g. `var(...)` references). Used by `Token.sniffValueType` and as
+* the value-shape tier of {@link resolveTokenValueType}.
+*/
+function sniffTokenType(value) {
+	const v = value.trim();
+	if (v.length === 0) return void 0;
+	if (CSS_STRING_KEYWORDS.has(v)) return "string";
+	if (v.startsWith("var(")) return void 0;
+	if (COLOR_FUNCTION_RE.test(v)) return "color";
+	if (HEX_COLOR_RE.test(v)) return "color";
+	if (NAMED_COLOR_KEYWORDS.has(v.toLowerCase())) return "color";
+	if (GRADIENT_FUNCTION_RE.test(v)) return "gradient";
+	if (EASING_FUNCTION_RE.test(v)) return "easing-function";
+	if (EASING_KEYWORDS.has(v.toLowerCase())) return "easing-function";
+	if (DURATION_RE.test(v)) return "time";
+	if (DIMENSION_RE.test(v)) {
+		if (v.endsWith("%")) return "percentage";
+		if (/(deg|rad|grad|turn)$/i.test(v)) return "angle";
+		return "length";
+	}
+	if (PURE_NUMBER_RE.test(v)) return "number";
+	if (RATIO_RE.test(v)) return "ratio";
+	if (looksLikeShadow(v)) return "shadow";
+}
+/**
+* Resolve a token's effective {@link CssValueTypeName} using the
+* canonical 3-tier precedence:
+*
+*   1. Per-token explicit `type` — authored override always wins.
+*   2. Value-shape sniff — handles `'#1167f4' → color` even inside a
+*      `string` group, and `'transparent' → string` even inside a
+*      `color` group.
+*   3. Group `type` — least-specific fallback for legacy untyped
+*      values.
+*
+* `length-percentage` narrows to `length` / `percentage` / `angle` /
+* `time` based on the trailing suffix; `string` narrows to `shadow`
+* when the value looks like a CSS shadow declaration.
+*/
+function resolveTokenValueType(token, groupType) {
+	let resolved;
+	if (token.type) resolved = token.type;
+	else {
+		resolved = sniffTokenType(token.value);
+		if (resolved === void 0 && groupType) resolved = groupType;
+	}
+	if (resolved === void 0) return void 0;
+	const trimmed = token.value.trim();
+	if (resolved === "length-percentage") {
+		if (trimmed.endsWith("%")) return "percentage";
+		if (/(deg|rad|grad|turn)$/.test(trimmed)) return "angle";
+		if (/(ms|s)$/.test(trimmed)) return "time";
+		return "length";
+	}
+	if (resolved === "string" && looksLikeShadow(trimmed)) return "shadow";
+	return resolved;
+}
+//#endregion
+export { resolveTokenValueType, sniffTokenType };