@yahoo/uds-v5-wip 1.60.0 → 1.61.0

package/dist/config/dist/createConfig.js

@@ -1,15 +1,11 @@
 import { kebabCase } from "../../utils/dist/string-utils/kebabCase.js";
 import { safeTokenName } from "../../utils/dist/string-utils/cssVar.js";
 import "../../utils/dist/index.js";
-import { getConfigurablePropMapping } from "../../core/dist/configurable-prop-helpers.js";
-import "../../core/dist/index.js";
-import { buildMotionReference, resolveComponentMotionAliases, validateComponentVariants } from "./component-resolution.js";
-import { applyPresetToData, deepMerge, mergeAtomic } from "./preset-merge.js";
-import { resolveTokenType, sniffTokenTypeFromValue } from "./resolveTokenTypes.js";
+import { sniffTokenTypeFromValue } from "./sniffTokenType.js";
 import { resolveStyleProp } from "./resolveStyleProp.js";
-import { setRegisteredStyleProps } from "./runtime-registry.js";
+import { mergeAtomic } from "./merge-utils.js";
+import { setRegisteredComposites, setRegisteredStyleProps } from "./runtime-registry.js";
 //#region ../config/dist/createConfig.js
-/** biome-ignore-all lint/suspicious/noExplicitAny: necessary for dynamic builder to work correctly */
 /**
 * Convert the authored object-keyed input into the internal `ModeGroup[]` shape.
 * Derives `_${optionKey}` modifiers when no explicit `modifier` is provided.
@@ -43,7 +39,7 @@ function convertModesInputToGroups(input) {
 function buildTokenReference(atomic, configPrefix) {
 	const result = Object.create(null);
 	for (const token of atomic) {
-		const varPrefix = token.cssPrefix ?? getConfigurablePropMapping(token.properties[0])?.defaultVarPrefix;
+		const varPrefix = token.cssPrefix ?? token.properties[0];
 		const tokenEntries = Object.create(null);
 		for (const t of token.tokens) {
 			const safeName = safeTokenName(t.name);
@@ -95,27 +91,6 @@ function resolveCompositeRefsInSelector(selector, compositeStyles) {
 	});
 }
 /**
-* Migrate legacy `macros` JSON (the pre-rename shape) into the new
-* `compositeStyles` shape. Each old key (`elevation`) becomes a `{ label,
-* styles }` def so older serialized configs (in `uds.config.json`,
-* `draft_base_configs.baseConfig`) keep loading until they're rewritten.
-*
-* Returns `undefined` when no legacy data is present so callers can chain
-* a fallback (`?? {}`).
-*/
-function upgradeLegacyMacros(legacy) {
-	if (!legacy || typeof legacy !== "object") return void 0;
-	const out = {};
-	for (const [name, variants] of Object.entries(legacy)) {
-		if (!variants || typeof variants !== "object") continue;
-		out[name] = {
-			label: name,
-			styles: variants
-		};
-	}
-	return Object.keys(out).length > 0 ? out : void 0;
-}
-/**
 * Convert a VarGroupDef into AtomicToken tokens, extracting modifier overrides.
 *
 * Also extracts group-level metadata:
@@ -129,15 +104,10 @@ function varGroupToTokens(varGroup, knownModifiers) {
 	let groupType;
 	let groupDescription;
 	const tokens = [];
+	for (const [tokenName, rawDef] of Object.entries(varGroup)) if (tokenName === "$type" && typeof rawDef === "string") groupType = rawDef;
+	else if (tokenName === "$description" && typeof rawDef === "string") groupDescription = rawDef;
 	for (const [tokenName, rawDef] of Object.entries(varGroup)) {
-		if (tokenName === "$type") {
-			if (typeof rawDef === "string") groupType = rawDef;
-			continue;
-		}
-		if (tokenName === "$description") {
-			if (typeof rawDef === "string") groupDescription = rawDef;
-			continue;
-		}
+		if (tokenName === "$type" || tokenName === "$description") continue;
 		if (rawDef == null || typeof rawDef !== "object") continue;
 		const tokenDef = rawDef;
 		const modifiers = {};
@@ -145,10 +115,16 @@ function varGroupToTokens(varGroup, knownModifiers) {
 			if (key === "value" || key === "$type" || val === void 0) continue;
 			if (key.startsWith("_") && knownModifiers.has(key)) modifiers[key] = val;
 		}
+		const value = tokenDef.value;
+		let perTokenType = tokenDef.$type;
+		if (!perTokenType && groupType && typeof value === "string") {
+			const sniffed = sniffTokenTypeFromValue(value);
+			if (sniffed && sniffed !== groupType) perTokenType = sniffed;
+		}
 		tokens.push({
 			name: tokenName,
-			value: tokenDef.value,
-			...tokenDef.$type ? { type: tokenDef.$type } : {},
+			value,
+			...perTokenType ? { type: perTokenType } : {},
 			...Object.keys(modifiers).length > 0 ? { modifiers } : {}
 		});
 	}
@@ -168,7 +144,6 @@ function varGroupToTokens(varGroup, knownModifiers) {
 function buildNamespaceConsumers(styleProps) {
 	const result = /* @__PURE__ */ new Map();
 	if (!styleProps) return result;
-	const refRe = /^\{([^.{}]+)/;
 	const addConsumer = (namespace, propName) => {
 		const list = result.get(namespace);
 		if (!list) {
@@ -177,14 +152,17 @@ function buildNamespaceConsumers(styleProps) {
 		}
 		if (!list.includes(propName)) list.push(propName);
 	};
+	const namespaceOf = (entry) => {
+		if (typeof entry === "object" && entry !== null && entry.__kind === "tokenGroup" && typeof entry.group === "string") {
+			const group = entry.group;
+			const slash = group.indexOf("/");
+			return slash > 0 ? group.slice(0, slash) : group;
+		}
+		if (typeof entry === "object" && entry !== null && "ref" in entry && typeof entry.ref === "object") return namespaceOf(entry.ref);
+	};
 	for (const [propName, prop] of Object.entries(styleProps)) for (const entry of prop.values ?? []) {
-		let raw;
-		if (typeof entry === "string") raw = entry;
-		else if (entry !== null && typeof entry === "object" && "ref" in entry && typeof entry.ref === "string") raw = entry.ref;
-		if (!raw) continue;
-		const match = refRe.exec(raw);
-		if (!match || !match[1]) continue;
-		addConsumer(match[1], propName);
+		const ns = namespaceOf(entry);
+		if (ns) addConsumer(ns, propName);
 	}
 	return result;
 }
@@ -205,17 +183,12 @@ function synthesizeAtomicFromVarsAndStyleProps(vars, styleProps, modes) {
 		const { tokens, groupType, groupDescription } = varGroupToTokens(varGroup, knownModifiers);
 		const properties = consumers.get(namespace) ?? [];
 		const cssPfx = kebabCase(namespace);
-		const resolvedGroupType = resolveTokenType({ explicit: groupType });
-		if (resolvedGroupType && resolvedGroupType !== "string") for (const token of tokens) {
-			if (token.type) continue;
-			if (sniffTokenTypeFromValue(token.value) === "string") token.type = "string";
-		}
 		result.push({
 			properties,
 			tokens,
 			namespace,
 			cssPrefix: cssPfx,
-			...resolvedGroupType ? { type: resolvedGroupType } : {},
+			...groupType ? { type: groupType } : {},
 			...groupDescription ? { description: groupDescription } : {}
 		});
 	}
@@ -228,10 +201,10 @@ function resolveConfig(config) {
 	else configData = {
 		modes: config.modes ?? [],
 		modifiers: config.modifiers ?? [],
-		atomic: config.atomic ?? [],
-		compositeStyles: config.compositeStyles ?? upgradeLegacyMacros(config.macros) ?? {},
+		atomic: [],
+		compositeStyles: config.compositeStyles ?? {},
 		motion: config.motion ?? {},
-		components: config.components ?? {},
+		components: {},
 		globalStyles: config.globalStyles ?? {},
 		preflight: config.preflight ?? true,
 		prefix: config.prefix ?? "uds",
@@ -239,7 +212,6 @@ function resolveConfig(config) {
 		examples: config.examples,
 		designPrinciples: config.designPrinciples,
 		vars: config.vars,
-		presetTokenNames: config.presetTokenNames,
 		styleProps: config.styleProps
 	};
 	if (configData.vars) {
@@ -260,89 +232,10 @@ function resolveConfig(config) {
 			};
 		}
 		if (configData.styleProps) setRegisteredStyleProps(configData.styleProps);
+		if (configData.compositeStyles) setRegisteredComposites(configData.compositeStyles);
 	}
 	return configData;
 }
-function isComponentDefinition(input) {
-	return typeof input === "object" && input !== null && "requiredTokens" in input && "components" in input;
-}
-function resolvePresetData(input) {
-	if (isComponentDefinition(input)) return {
-		modes: [],
-		modifiers: [],
-		atomic: [],
-		compositeStyles: {},
-		motion: input.motion ?? {},
-		components: input.components,
-		globalStyles: {},
-		preflight: true,
-		prefix: "uds"
-	};
-	if ("defineVars" in input) return resolveConfig(input);
-	return {
-		modes: input.modes ?? [],
-		modifiers: input.modifiers ?? [],
-		atomic: input.atomic ?? [],
-		compositeStyles: input.compositeStyles ?? {},
-		motion: input.motion ?? {},
-		components: input.components ?? {},
-		globalStyles: input.globalStyles ?? {},
-		preflight: input.preflight ?? true,
-		prefix: input.prefix ?? "uds",
-		examples: input.examples,
-		designPrinciples: input.designPrinciples,
-		vars: input.vars,
-		presetTokenNames: input.presetTokenNames
-	};
-}
-function extractVarReferences(value) {
-	if (typeof value !== "string") return [];
-	return value.match(/var\([^()]+\)/g) ?? [];
-}
-function collectRequiredTokensFromObject(value, out) {
-	if (value == null) return;
-	if (typeof value === "string") {
-		const refs = extractVarReferences(value);
-		for (const ref of refs) out.add(ref);
-		return;
-	}
-	if (Array.isArray(value)) {
-		for (const item of value) collectRequiredTokensFromObject(item, out);
-		return;
-	}
-	if (typeof value === "object") for (const child of Object.values(value)) collectRequiredTokensFromObject(child, out);
-}
-/**
-* Collect the set of `var(--uds-X-Y)` references a component preset uses, so
-* downstream `compose()` calls can verify the target config emits those
-* variables. Storing raw var refs (instead of `propName.tokenKey` pairs)
-* decouples the check from prop/namespace association lookups — only the
-* actual CSS variable surface needs to be compatible.
-*/
-function collectRequiredTokens(_sourceData, components, motion) {
-	const out = /* @__PURE__ */ new Set();
-	collectRequiredTokensFromObject(components, out);
-	if (motion) collectRequiredTokensFromObject(motion, out);
-	return Array.from(out).sort();
-}
-function buildComponentsAccessor(components) {
-	const accessor = {};
-	for (const [name, config] of Object.entries(components)) {
-		const comp = {};
-		comp.base = { ...config.base?.root ?? {} };
-		for (const [slot, styles] of Object.entries(config.base ?? {})) if (slot !== "root") comp.base[slot] = styles;
-		if (config.variants) for (const [axis, values] of Object.entries(config.variants)) {
-			const axisAcc = {};
-			for (const [val, slots] of Object.entries(values)) {
-				axisAcc[val] = { ...slots.root ?? {} };
-				for (const [slot, styles] of Object.entries(slots)) if (slot !== "root") axisAcc[val][slot] = styles;
-			}
-			comp[axis] = axisAcc;
-		}
-		accessor[name] = comp;
-	}
-	return accessor;
-}
 function createConfigBuilder(data, extensions) {
 	const next = (overrides = {}) => createConfigBuilder({
 		...data,
@@ -424,6 +317,51 @@ function createConfigBuilder(data, extensions) {
 				}
 			}, extensions);
 		},
+		registerComposites(composites) {
+			const resolved = {};
+			for (const [name, value] of Object.entries(composites)) resolved[name] = {
+				label: value.label,
+				...value.description !== void 0 ? { description: value.description } : {},
+				styles: value.styles
+			};
+			const allCompositeStyles = {
+				...data.compositeStyles,
+				...resolved
+			};
+			const edges = /* @__PURE__ */ new Map();
+			for (const [groupName, def] of Object.entries(allCompositeStyles)) {
+				const targets = /* @__PURE__ */ new Set();
+				for (const bag of Object.values(def.styles)) if (bag && typeof bag === "object") {
+					for (const key of Object.keys(bag)) if (key in allCompositeStyles) targets.add(key);
+				}
+				if (targets.size > 0) edges.set(groupName, targets);
+			}
+			const visited = /* @__PURE__ */ new Set();
+			const stack = /* @__PURE__ */ new Set();
+			const path = [];
+			function dfs(node) {
+				if (stack.has(node)) {
+					const cycleStart = path.indexOf(node);
+					throw new Error(`Circular composite style reference: ${[...path.slice(cycleStart), node].join(" → ")}`);
+				}
+				if (visited.has(node)) return;
+				visited.add(node);
+				stack.add(node);
+				path.push(node);
+				const neighbors = edges.get(node);
+				if (neighbors) for (const neighbor of neighbors) dfs(neighbor);
+				path.pop();
+				stack.delete(node);
+			}
+			for (const node of edges.keys()) dfs(node);
+			return createConfigBuilder({
+				...data,
+				compositeStyles: {
+					...data.compositeStyles,
+					...resolved
+				}
+			}, extensions);
+		},
 		registerStyleProps(props) {
 			const expanded = {};
 			for (const [propName, prop] of Object.entries(props)) {
@@ -433,7 +371,7 @@ function createConfigBuilder(data, extensions) {
 						kind: "styleProp",
 						cssProperty: prop.cssProperty,
 						classPrefix: "",
-						values: prop.opacityPair.values,
+						values: [prop.opacityPair.values],
 						arbitrary: void 0,
 						cssType: prop.cssType,
 						metadata: { label: prop.metadata?.label ? `${prop.metadata.label} opacity` : void 0 },
@@ -453,8 +391,10 @@ function createConfigBuilder(data, extensions) {
 		},
 		registerComponents(configs) {
 			const normalized = {};
+			const instances = {};
 			for (const [name, entry] of Object.entries(configs)) {
-				const config = typeof entry === "function" && "__config" in entry ? entry.__config : entry;
+				const isBound = typeof entry === "function" && "__config" in entry;
+				const config = isBound ? entry.__config : entry;
 				Object.defineProperty(config, "__componentName", {
 					enumerable: false,
 					configurable: true,
@@ -462,10 +402,23 @@ function createConfigBuilder(data, extensions) {
 					value: name
 				});
 				normalized[name] = config;
+				if (isBound) instances[name] = entry;
 			}
-			return next({ componentConfigs: {
-				...data.componentConfigs ?? {},
-				...normalized
+			return next({
+				components: {
+					...data.components,
+					...normalized
+				},
+				componentInstances: {
+					...data.componentInstances ?? {},
+					...instances
+				}
+			});
+		},
+		registerPreviews(previews) {
+			return next({ previews: {
+				...data.previews ?? {},
+				...previews
 			} });
 		},
 		defineMotion(presets) {
@@ -479,24 +432,6 @@ function createConfigBuilder(data, extensions) {
 				}
 			}, extensions);
 		},
-		defineComponents(params) {
-			const tokenReference = buildTokenReference(data.atomic, data.prefix);
-			const motionReference = buildMotionReference(data.motion);
-			const componentsAccessor = buildComponentsAccessor(data.components);
-			const newComponents = resolveComponentMotionAliases(typeof params === "function" ? params({
-				tokens: tokenReference,
-				motion: motionReference,
-				components: componentsAccessor
-			}) : params, data.motion);
-			validateComponentVariants(newComponents);
-			const mergedComponents = { ...data.components };
-			for (const [name, def] of Object.entries(newComponents)) {
-				const existing = mergedComponents[name];
-				if (existing && typeof existing === "object" && typeof def === "object") mergedComponents[name] = deepMerge(existing, def);
-				else mergedComponents[name] = def;
-			}
-			return next({ components: mergedComponents });
-		},
 		defineGlobalStyles(params) {
 			const tokenReference = buildTokenReference(data.atomic, data.prefix);
 			const newGlobalStyles = typeof params === "function" ? params(tokenReference) : params;
@@ -508,63 +443,6 @@ function createConfigBuilder(data, extensions) {
 		defineDesignPrinciples(principles) {
 			return next({ designPrinciples: [...data.designPrinciples ?? [], ...principles] });
 		},
-		defineExample(name, examples) {
-			const componentConfig = data.components[name];
-			if (!componentConfig) throw new Error(`defineExample: component "${name}" not found. Available components: ${Object.keys(data.components).join(", ")}`);
-			const variantAxes = Object.keys(componentConfig.variants ?? {});
-			for (const [exampleKey, entry] of Object.entries(examples)) if (entry.each && !variantAxes.includes(entry.each)) throw new Error(`defineExample: "${name}" example "${exampleKey}" references unknown variant axis "${entry.each}". Available axes: ${variantAxes.join(", ") || "(none)"}`);
-			return next({ examples: {
-				...data.examples,
-				[name]: examples
-			} });
-		},
-		compose(...presets) {
-			return createConfigBuilder(presets.reduce((acc, preset) => {
-				return applyPresetToData(acc, resolvePresetData(preset));
-			}, data), extensions);
-		},
-		defineComponent(name, component, motion) {
-			const tokenReference = buildTokenReference(data.atomic, data.prefix);
-			const resolvedMotion = typeof motion === "function" ? motion(tokenReference) : motion;
-			const motionReference = buildMotionReference({
-				...data.motion,
-				...resolvedMotion ?? {}
-			});
-			const componentsAccessor = buildComponentsAccessor(data.components);
-			const inputComponent = typeof component === "function" ? component({
-				tokens: tokenReference,
-				motion: motionReference,
-				components: componentsAccessor
-			}) : component;
-			const resolvedComponents = resolveComponentMotionAliases({ [name]: inputComponent }, {
-				...data.motion,
-				...resolvedMotion ?? {}
-			});
-			validateComponentVariants(resolvedComponents);
-			return {
-				name,
-				requiredTokens: collectRequiredTokens(data, resolvedComponents, resolvedMotion),
-				components: resolvedComponents,
-				motion: resolvedMotion
-			};
-		},
-		from(input) {
-			return createConfigBuilder({
-				modes: input.modes ?? data.modes,
-				modifiers: input.modifiers ?? data.modifiers,
-				atomic: input.atomic ?? data.atomic,
-				compositeStyles: input.compositeStyles ?? data.compositeStyles,
-				motion: input.motion ?? data.motion,
-				components: input.components ?? data.components,
-				globalStyles: input.globalStyles ?? data.globalStyles,
-				preflight: input.preflight ?? data.preflight,
-				prefix: input.prefix ?? data.prefix,
-				examples: input.examples ?? data.examples,
-				designPrinciples: input.designPrinciples ?? data.designPrinciples,
-				vars: input.vars ?? data.vars,
-				presetTokenNames: input.presetTokenNames ?? data.presetTokenNames
-			}, extensions);
-		},
 		extend(ext) {
 			return createConfigBuilder(data, {
 				...extensions,

package/dist/config/dist/createStyler.d.ts

@@ -0,0 +1,35 @@
+import { UdsConfigData } from "./createConfig.js";
+
+//#region ../config/dist/createStyler.d.ts
+//#region src/createStyler.d.ts
+/**
+ * A styler bound to a resolved config's style-prop registry. Takes a
+ * props object and returns the className string. Empty string when
+ * no prop matches a registered style prop.
+ */
+type Styler = (props: Record<string, unknown>) => string;
+/**
+ * Bind a styler to a resolved config. Reads the registered style-
+ * prop registry once; the returned function does just per-call
+ * className composition.
+ *
+ *     // codegen / build pipeline
+ *     const getStyles = createStyler(resolveConfig(udsBuilder));
+ *     for (const site of scannedJsxSites) {
+ *       const merged = mergeComponentDefaults(site.config, site.props);
+ *       safelist.add(getStyles(merged));
+ *     }
+ *
+ * `resolvedConfig` is the output of `resolveConfig(udsBuilder)`. The
+ * styler closes over the registry under either of two fields:
+ *
+ *   - `resolvedStyleProps` — the canonical resolved registry the
+ *     codegen + runtime consume; entries carry `propName` +
+ *     `classPrefix`.
+ *   - `styleProps` — fallback to the unresolved map when
+ *     `resolvedStyleProps` isn't populated (test configs that skip
+ *     the full resolver).
+ */
+declare function createStyler(resolvedConfig: UdsConfigData): Styler; //#endregion
+//#endregion
+export { Styler, createStyler };

package/dist/config/dist/createStyler.js

@@ -0,0 +1,93 @@
+import { buildStylePropClassName } from "./className.js";
+//#region ../config/dist/createStyler.js
+/**
+* **NEW-API ONLY** — factory that produces a styler bound to a
+* resolved config's registered style props. The returned function
+* takes a props object and returns the className string for those
+* style-prop values.
+*
+*     const getStyles = createStyler(resolveConfig(udsBuilder));
+*     getStyles({ bg: 'brand', gap: '4' });
+*     // → 'bg-brand gap-4'
+*
+* Parity with the legacy `getStyles` from `@uds/core`, but the lookup
+* is sourced from the user's `.registerStyleProps({...})` registry
+* (via `resolveConfig`) instead of `@uds/core`'s hardcoded
+* `propMappings` table. Registering a style prop is enough to make
+* it work — no edits to `@uds/core`.
+*
+* Used by:
+*
+*   - `@uds/codegen/css/extractClasses` (build-time CSS scanner) —
+*     populates the Tailwind safelist with every class the runtime
+*     can produce. The scanner walks JSX call sites, merges the
+*     component's `defaultProps` into the JSX props, and passes the
+*     merged shape here.
+*   - Custom tooling that wants "what would the runtime render?"
+*     without going through React.
+*
+* Both the styler and `bindRender` (the runtime) call the same
+* `buildStylePropClassName` helper in `./className.ts` — that's the
+* load-bearing invariant: identical class strings for the same
+* inputs.
+*
+* Scope: only style-prop bindings the user registered. Markers
+* (`bool()` / `enums()`), `ForwardBinding`, compound variants, and
+* `_<modifier>` props don't flow through here — they're handled by
+* codegen via dedicated emission paths (component-utility classes,
+* modifier-prefixed @utility blocks).
+*/
+/**
+* Bind a styler to a resolved config. Reads the registered style-
+* prop registry once; the returned function does just per-call
+* className composition.
+*
+*     // codegen / build pipeline
+*     const getStyles = createStyler(resolveConfig(udsBuilder));
+*     for (const site of scannedJsxSites) {
+*       const merged = mergeComponentDefaults(site.config, site.props);
+*       safelist.add(getStyles(merged));
+*     }
+*
+* `resolvedConfig` is the output of `resolveConfig(udsBuilder)`. The
+* styler closes over the registry under either of two fields:
+*
+*   - `resolvedStyleProps` — the canonical resolved registry the
+*     codegen + runtime consume; entries carry `propName` +
+*     `classPrefix`.
+*   - `styleProps` — fallback to the unresolved map when
+*     `resolvedStyleProps` isn't populated (test configs that skip
+*     the full resolver).
+*/
+function createStyler(resolvedConfig) {
+	const classPrefixByPropName = buildClassPrefixLookup(resolvedConfig);
+	return (props) => classNameFor(props, classPrefixByPropName);
+}
+/**
+* Per-styler resolved style-prop lookup. Keys are JSX-prop names
+* (e.g. `bg`, `padding`); values are the `classPrefix` the style
+* prop registered with.
+*
+* `resolvedStyleProps` (the canonical shape) takes precedence;
+* `styleProps` (the unresolved map) is consulted only when a prop
+* isn't already present — that keeps test configs that skip the
+* full resolver working without overriding the canonical entries.
+*/
+function buildClassPrefixLookup(config) {
+	const out = {};
+	for (const entry of config.resolvedStyleProps ?? []) if (entry.propName) out[entry.propName] = entry.classPrefix ?? "";
+	for (const [propName, styleProp] of Object.entries(config.styleProps ?? {})) if (!(propName in out)) out[propName] = styleProp.classPrefix ?? "";
+	return out;
+}
+function classNameFor(props, classPrefixByPropName) {
+	const classNames = [];
+	for (const [propName, value] of Object.entries(props)) {
+		const classPrefix = classPrefixByPropName[propName];
+		if (classPrefix === void 0) continue;
+		const className = buildStylePropClassName({ classPrefix }, value);
+		if (className) classNames.push(className);
+	}
+	return classNames.join(" ");
+}
+//#endregion
+export { createStyler };