@yahoo/uds-v5-wip 1.60.0 → 1.61.0

package/dist/config/dist/refs.d.ts

@@ -0,0 +1,85 @@
+import { TokenMarker } from "./component-config.js";
+
+//#region ../config/dist/refs.d.ts
+//#region src/refs.d.ts
+/**
+ * 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.
+ */
+declare function resolveTokenValue(value: string | TokenMarker, configPrefix: string | undefined): string;
+/**
+ * Object marker emitted by `darken()` / `lighten()` helpers. Codegen
+ * detects this shape on a per-value basis and resolves the inner
+ * `$token` to `var(--<prefix>-<ns>-<name>)`, then applies the modifier.
+ *
+ * Authored solely via the `darken` / `lighten` helpers — the object
+ * shape is internal and not meant to be hand-written. Serializes
+ * cleanly through JSON.stringify (unlike the legacy inline-string
+ * modifier syntax which the regex parser flagged as polynomial under
+ * adversarial input).
+ */
+interface TokenWithModifier {
+  /** Brace-stripped token ref, e.g. `'bg/brand'`. */
+  readonly $token: string;
+  readonly $modifier: {
+    readonly type: 'darken' | 'lighten'; /** Mix percentage, e.g. `10` → `10%`. */
+    readonly amount: number;
+  };
+}
+/**
+ * Type-guard: a value is a `TokenWithModifier` marker.
+ */
+declare function isTokenWithModifier(value: unknown): value is TokenWithModifier;
+/**
+ * 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.
+ */
+declare function resolveTokenWithModifier(marker: TokenWithModifier, configPrefix: string | undefined): string;
+/**
+ * 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.
+ */
+declare function darken(ref: TokenMarker, amount: number): TokenWithModifier;
+/**
+ * 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%)`.
+ */
+declare function lighten(ref: TokenMarker, amount: number): TokenWithModifier; //#endregion
+//#endregion
+export { TokenWithModifier, darken, isTokenWithModifier, lighten, resolveTokenValue, resolveTokenWithModifier };

package/dist/config/dist/refs.js

@@ -3,13 +3,12 @@ import { safeTokenName } from "../../utils/dist/string-utils/cssVar.js";
 import "../../utils/dist/index.js";
 //#region ../config/dist/refs.js
 /**
-* Token references — `'{namespace/key}'` braces in token values.
-*
-* Authors can point one token at another via a brace-wrapped path:
+* 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: '{spectrum/blue/500}' } },
+*     color:    { brand:      { value: token('spectrum/blue/500') } },
 *   })
 *
 * At CSS-declaration time this expands to a CSS variable alias:
@@ -17,61 +16,107 @@ import "../../utils/dist/index.js";
 *   --uds-spectrum-blue-500: #1167f4;
 *   --uds-color-brand: var(--uds-spectrum-blue-500);
 *
-* Refs are a purely syntactic transform — no graph walk, no cycle
+* Aliases are a purely syntactic transform — no graph walk, no cycle
 * detection. CSS handles aliasing (and any cascade cycles) at runtime.
-* Refs that don't match a declared token resolve to a `var(...)` that
-* has no `:root` declaration; the browser falls back to the property's
+* 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.
 *
-* Consumption is unchanged: `tokens.color.brand` in component configs
-* still resolves to `var(--uds-color-brand)`, regardless of whether the
-* brand value itself is a literal or a ref.
+* The CSS variable name follows `defineVars`'s `:root` declaration
+* convention: `kebabCase` on the namespace, `safeTokenName` on the
+* token name.
 */
-const REF_PATTERN = /^\{([^{}]+)\}$/;
+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;
+}
 /**
-* Parse a value as a token ref. Returns `null` when the value isn't a
-* brace-wrapped ref of the form `{namespace/name}`. The `name` portion
-* may contain additional slashes — only the first slash is treated as
-* the namespace separator.
+* 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%)`
 *
-* Color-modifier values (`darken` / `lighten`) are a structured object
-* form, not a string-encoded suffix. See {@link TokenWithModifier}.
+* 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 parseTokenRef(value) {
-	const outer = REF_PATTERN.exec(value);
-	if (!outer) return null;
-	const body = outer[1];
-	if (!body) return null;
-	return parseRefBody(body);
+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}%)`;
 }
-function parseRefBody(body) {
-	if (body.includes("{") || body.includes("}")) return null;
-	const slashIdx = body.indexOf("/");
-	if (slashIdx <= 0 || slashIdx >= body.length - 1) return null;
+/**
+* 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) {
 	return {
-		namespace: body.slice(0, slashIdx),
-		name: body.slice(slashIdx + 1)
+		$token: ref.ref,
+		$modifier: {
+			type: "darken",
+			amount
+		}
 	};
 }
 /**
-* Resolve a token value to its CSS form. If `value` is a token ref, returns
-* the corresponding `var(--<prefix>-<namespace>-<name>)` string. Otherwise
-* returns the value unchanged.
-*
-* The CSS variable name is built the same way `defineVars` builds its `:root`
-* declarations: `kebabCase` on the namespace, `safeTokenName` on the token
-* name. So `{spectrum/blue/500}` resolves to `var(--uds-spectrum-blue-500)`
-* (matching the namespace's own emitted variable name).
+* 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 resolveTokenRef(value, configPrefix) {
-	const ref = parseTokenRef(value);
-	if (!ref) return value;
-	return refToVar(ref.namespace, ref.name, configPrefix);
-}
-function refToVar(namespace, name, configPrefix) {
-	const cssPrefix = kebabCase(namespace);
-	const cssName = safeTokenName(name);
-	return `var(${configPrefix ? `--${configPrefix}-${cssPrefix}-${cssName}` : `--${cssPrefix}-${cssName}`})`;
+function lighten(ref, amount) {
+	return {
+		$token: ref.ref,
+		$modifier: {
+			type: "lighten",
+			amount
+		}
+	};
 }
 //#endregion
-export { parseTokenRef, resolveTokenRef };
+export { darken, isTokenWithModifier, lighten, resolveTokenValue, resolveTokenWithModifier };

package/dist/config/dist/resolveCompoundProps.d.ts

@@ -0,0 +1,65 @@
+import { CompoundPropsEntry, HiddenMarker, LayerInput } from "./component-config.js";
+
+//#region ../config/dist/resolveCompoundProps.d.ts
+//#region src/resolveCompoundProps.d.ts
+/**
+ * Per-layer entry on the resolved overrides map. Either a flat style/
+ * prop bag (for style overrides) or the hide marker. Downstream
+ * consumers can branch on `__kind === 'hidden'` to pick between
+ * `display: none` and stripping the layer from the rendered tree.
+ */
+type ResolvedLayerOverride = HiddenMarker | Record<string, unknown>;
+/**
+ * Per-layer map of overrides that should win at the given active-prop
+ * combination.
+ */
+type ResolvedCompoundOverrides = Record<string, ResolvedLayerOverride>;
+/**
+ * Find every `compoundProps` entry whose `when` clause is satisfied by
+ * the active props and merge them into a single per-layer override map.
+ *
+ * Conflict resolution:
+ *  - For style-map overrides, per-property: higher `specificity(when)`
+ *    wins; tie-break is later position in source order.
+ *  - For a `hidden()` layer marker, the layer-level decision: most-
+ *    specific hidden marker wins; tie-break is later source order. The
+ *    marker takes precedence over style overrides at the same layer,
+ *    since a hidden layer's styles are moot anyway.
+ *
+ * Returns an empty object when nothing matches — callers can treat it
+ * as a no-op without a separate `undefined` check.
+ */
+declare function resolveCompoundProps<TLayers extends Record<string, LayerInput>, TProps extends Record<string, any> = Record<string, any>>(compoundProps: readonly CompoundPropsEntry<TLayers, TProps>[] | undefined, activeProps: Record<string, unknown>): ResolvedCompoundOverrides;
+/**
+ * Fold a `resolveCompoundProps` result into an existing per-layer
+ * bundle of resolved style-prop values (the output of the enum/bool
+ * merge for the active prop combination).
+ *
+ * A `HiddenMarker` on a layer rewrites that layer's bundle to
+ * `{ __hidden: true }` — a sentinel the render fn checks at the JSX
+ * site to skip rendering the layer entirely, rather than emitting a
+ * `display: none` declaration that would leave a layout-occupying
+ * DOM node. Use {@link isLayerHidden} for the check:
+ *
+ *     .render(({ props }) => (
+ *       <a {...props.root}>
+ *         {!isLayerHidden(props.endIcon) && <span {...props.endIcon} />}
+ *       </a>
+ *     ))
+ *
+ * Style-map overrides merge per-key into the existing bundle. The
+ * input bundles are not mutated — every layer that receives any
+ * override is copied first.
+ */
+declare function applyCompoundProps(layerBundles: Record<string, Record<string, unknown>>, overrides: ResolvedCompoundOverrides): Record<string, Record<string, unknown>>;
+/**
+ * Type guard used by render fns to skip rendering a hidden layer:
+ *
+ *     {!isLayerHidden(props.endIcon) && <span {...props.endIcon} />}
+ *
+ * Returns `true` when the bundle carries the `__hidden: true`
+ * sentinel written by `applyCompoundProps`.
+ */
+declare function isLayerHidden(bundle: Record<string, unknown> | undefined): boolean; //#endregion
+//#endregion
+export { ResolvedCompoundOverrides, ResolvedLayerOverride, applyCompoundProps, isLayerHidden, resolveCompoundProps };

package/dist/config/dist/resolveCompoundProps.js

@@ -0,0 +1,120 @@
+//#region ../config/dist/resolveCompoundProps.js
+function whenMatches(when, activeProps) {
+	for (const key in when) {
+		if (!Object.hasOwn(when, key)) continue;
+		if (activeProps[key] !== when[key]) return false;
+	}
+	return true;
+}
+function specificity(when) {
+	let count = 0;
+	for (const key in when) if (Object.hasOwn(when, key)) count++;
+	return count;
+}
+function isHiddenMarker(value) {
+	return typeof value === "object" && value !== null && value.__kind === "hidden";
+}
+/**
+* Find every `compoundProps` entry whose `when` clause is satisfied by
+* the active props and merge them into a single per-layer override map.
+*
+* Conflict resolution:
+*  - For style-map overrides, per-property: higher `specificity(when)`
+*    wins; tie-break is later position in source order.
+*  - For a `hidden()` layer marker, the layer-level decision: most-
+*    specific hidden marker wins; tie-break is later source order. The
+*    marker takes precedence over style overrides at the same layer,
+*    since a hidden layer's styles are moot anyway.
+*
+* Returns an empty object when nothing matches — callers can treat it
+* as a no-op without a separate `undefined` check.
+*/
+function resolveCompoundProps(compoundProps, activeProps) {
+	if (!compoundProps || compoundProps.length === 0) return {};
+	const styleResolved = {};
+	const stylePropSpecificity = {};
+	const hiddenSpecificity = {};
+	for (const entry of compoundProps) {
+		if (!whenMatches(entry.when, activeProps)) continue;
+		const entrySpecificity = specificity(entry.when);
+		for (const layerName in entry.layers) {
+			if (!Object.hasOwn(entry.layers, layerName)) continue;
+			const layerOverride = entry.layers[layerName];
+			if (!layerOverride) continue;
+			if (isHiddenMarker(layerOverride)) {
+				const prev = hiddenSpecificity[layerName];
+				if (prev === void 0 || entrySpecificity >= prev) hiddenSpecificity[layerName] = entrySpecificity;
+				continue;
+			}
+			const styleMap = layerOverride;
+			styleResolved[layerName] ??= {};
+			stylePropSpecificity[layerName] ??= {};
+			for (const propKey in styleMap) {
+				if (!Object.hasOwn(styleMap, propKey)) continue;
+				const prevSpecificity = stylePropSpecificity[layerName][propKey];
+				if (prevSpecificity === void 0 || entrySpecificity >= prevSpecificity) {
+					styleResolved[layerName][propKey] = styleMap[propKey];
+					stylePropSpecificity[layerName][propKey] = entrySpecificity;
+				}
+			}
+		}
+	}
+	const resolved = {};
+	for (const layerName in styleResolved) resolved[layerName] = styleResolved[layerName];
+	for (const layerName in hiddenSpecificity) resolved[layerName] = { __kind: "hidden" };
+	return resolved;
+}
+/**
+* Fold a `resolveCompoundProps` result into an existing per-layer
+* bundle of resolved style-prop values (the output of the enum/bool
+* merge for the active prop combination).
+*
+* A `HiddenMarker` on a layer rewrites that layer's bundle to
+* `{ __hidden: true }` — a sentinel the render fn checks at the JSX
+* site to skip rendering the layer entirely, rather than emitting a
+* `display: none` declaration that would leave a layout-occupying
+* DOM node. Use {@link isLayerHidden} for the check:
+*
+*     .render(({ props }) => (
+*       <a {...props.root}>
+*         {!isLayerHidden(props.endIcon) && <span {...props.endIcon} />}
+*       </a>
+*     ))
+*
+* Style-map overrides merge per-key into the existing bundle. The
+* input bundles are not mutated — every layer that receives any
+* override is copied first.
+*/
+function applyCompoundProps(layerBundles, overrides) {
+	if (Object.keys(overrides).length === 0) return layerBundles;
+	const result = { ...layerBundles };
+	for (const layerName in overrides) {
+		if (!Object.hasOwn(overrides, layerName)) continue;
+		const override = overrides[layerName];
+		if (!override) continue;
+		if (isHiddenMarker(override)) {
+			result[layerName] = { __hidden: true };
+			continue;
+		}
+		const merged = { ...result[layerName] ?? {} };
+		for (const propKey in override) {
+			if (!Object.hasOwn(override, propKey)) continue;
+			merged[propKey] = override[propKey];
+		}
+		result[layerName] = merged;
+	}
+	return result;
+}
+/**
+* Type guard used by render fns to skip rendering a hidden layer:
+*
+*     {!isLayerHidden(props.endIcon) && <span {...props.endIcon} />}
+*
+* Returns `true` when the bundle carries the `__hidden: true`
+* sentinel written by `applyCompoundProps`.
+*/
+function isLayerHidden(bundle) {
+	return bundle?.__hidden === true;
+}
+//#endregion
+export { applyCompoundProps, isLayerHidden, resolveCompoundProps };

package/dist/config/dist/resolveStyleProp.d.ts

@@ -1,5 +1,8 @@
 import { CssValueTypeName } from "./types/css-values.js";
 import { ArbitrarySpec, StylePropMetadata } from "./defineStyleProp.js";
+import { TokenType } from "./types.js";
+import { UdsConfigData } from "./createConfig.js";
+
 //#region ../config/dist/resolveStyleProp.d.ts
 //#region src/resolveStyleProp.d.ts
 interface ResolvedToken {
@@ -13,8 +16,8 @@ interface ResolvedToken {
   readonly group: string;
   /**
    * Style-prop-local namespace, set only when the token was sourced via a
-   * {@link NamespacedGroupRef}. Used to disambiguate when two groups feed
-   * the same prop and share keys.
+   * `NamespacedTokenGroup` (`{ ref: tokenGroup('X'), namespace: 'Y' }`).
+   * Used to disambiguate when two groups feed the same prop and share keys.
    */
   readonly namespace?: string;
   /**
@@ -84,5 +87,71 @@ interface ResolvedStyleProp {
  * resolver's signature doesn't expand `ValuesEntry<P>` over the full CSS
  * property union (TS2590).
  */
+interface ResolveStylePropInput {
+  readonly kind?: 'styleProp';
+  readonly cssProperty: string | readonly string[];
+  readonly classPrefix: string;
+  readonly values?: readonly unknown[];
+  readonly arbitrary?: ArbitrarySpec;
+  readonly cssType?: CssValueTypeName;
+  readonly metadata?: StylePropMetadata;
+}
+/**
+ * Minimal input shapes for {@link detectTokenValueType} — see that
+ * function's docs for the algorithmic contract.
+ * `AtomicToken['tokens'][number]` and `AtomicToken` are structurally
+ * assignable to these, so codegen's existing call sites keep working
+ * unchanged.
+ */
+interface DetectTokenValueTypeInput {
+  readonly value: string;
+  readonly type?: TokenType;
+}
+interface DetectTokenValueTypeGroup {
+  readonly type?: TokenType;
+}
+/**
+ * Detect a token's CSS value type. Resolution order:
+ *  1. Per-token `type` override.
+ *  2. Group-level `type`.
+ *
+ * When the resolved type is `'length-percentage'` and the raw value ends in
+ * `%`, narrow to `'percentage'`; otherwise narrow to `'length'`. When the
+ * resolved type is `'string'`, narrow shadow-like values to `'shadow'` and
+ * ratio-shaped values to `'ratio'`.
+ *
+ * Exported so Studio (and any other runtime consumer) can resolve a cell's
+ * effective `CssValueTypeName`.
+ *
+ * The input shapes ({@link DetectTokenValueTypeInput} /
+ * {@link DetectTokenValueTypeGroup}) are intentionally minimal: the resolver
+ * reads only `token.value`, `token.type`, and `group.type` — never walks
+ * `group.tokens`, never checks that `token` is inside `group`. Typing them
+ * as full `AtomicToken` would force trimmed-shape consumers (Studio's
+ * `TokenEntry`) to either round-trip back to the source group or `as`-assert
+ * past the type system.
+ */
+declare function detectTokenValueType(token: DetectTokenValueTypeInput, group: DetectTokenValueTypeGroup): CssValueTypeName | undefined;
+/**
+ * Resolve a style prop against the given resolved UDS config. Unknown group
+ * refs are silently dropped from `tokens` (callers can detect this by
+ * comparing input refs vs. resolved tokens if they need to surface a
+ * config-build warning).
+ *
+ * @param propName - The JSX prop name (the map key from `registerStyleProps`).
+ */
+declare function resolveStyleProp(propName: string, styleProp: ResolveStylePropInput, config: UdsConfigData): ResolvedStyleProp;
+/**
+ * Walk a resolved config's `resolvedStyleProps` and return the
+ * color-prop → opacity-sibling-prop map. Built from each opacity
+ * sibling's `pairedWith` field (set by the resolver when expanding a
+ * `.withOpacity({ as })` parent). Returns an empty object when no
+ * pairings exist.
+ *
+ * Replaces the legacy `colorPropToOpacityProp` table that lived in
+ * `@uds/core` — consumers (codegen safelist generation, runtime
+ * `getStyles`, loader style-transform) should call this instead.
+ */
+declare function getColorOpacityMap(config: UdsConfigData): Record<string, string>; //#endregion
 //#endregion
-export { ResolvedStyleProp, ResolvedToken };
+export { DetectTokenValueTypeGroup, DetectTokenValueTypeInput, ResolvedStyleProp, ResolvedToken, detectTokenValueType, getColorOpacityMap, resolveStyleProp };