@yahoo/uds-create-config 1.1.1

package/dist/spec/jsxToSpec.d.ts

@@ -0,0 +1,48 @@
+import { AssetNodeResolver } from "./asset-jsx.js";
+import { Spec } from "@json-render/core";
+
+//#region src/spec/jsxToSpec.d.ts
+/**
+ * Sentinel value used when a prop expression couldn't be statically resolved.
+ * Callers can check `hasUnresolvedProps(spec)` to detect this.
+ */
+declare const UNRESOLVED: unique symbol;
+/** Check if any element in the spec has prop values that couldn't be statically resolved. */
+declare function hasUnresolvedProps(spec: Spec): boolean;
+/** Return a copy of the spec with all UNRESOLVED and STATE_SETTER prop values removed. */
+declare function stripUnresolvedProps(spec: Spec): Spec;
+interface JsxToSpecOptions {
+  /**
+   * Full module source for scope resolution.
+   * When provided, top-level const declarations are resolved
+   * and local component functions are inlined.
+   */
+  moduleSource?: string;
+  /**
+   * Set of known component names in the registry. When provided, any
+   * PascalCase JSX element whose tag is NOT in this set (e.g. providers,
+   * wrappers) is treated as a transparent fragment — its children are
+   * flattened into the parent.
+   */
+  knownComponents?: Set<string>;
+  /**
+   * Reconstructs placed asset nodes from authoring-component tags —
+   * `<Icon name="Trophy" …/>` → type `yahoo-os:asset:icons/Trophy`. The
+   * exact inverse of `specToJsx`'s `assetComponents` mapping; without it an
+   * `<Icon name=…/>` round-trips as a literal `Icon` component node.
+   */
+  resolveAssetNode?: AssetNodeResolver;
+}
+/**
+ * Convert JSX source code into a json-render Spec.
+ *
+ * Accepts either a full JSX module or a JSX expression snippet.
+ * When `moduleSource` is provided, identifier references are resolved
+ * against the module's top-level const declarations, and local component
+ * functions are inlined.
+ *
+ * Returns `null` if no JSX element is found in the source.
+ */
+declare function jsxToSpec(source: string, options?: JsxToSpecOptions): Spec | null;
+//#endregion
+export { JsxToSpecOptions, UNRESOLVED, hasUnresolvedProps, jsxToSpec, stripUnresolvedProps };

package/dist/spec/jsxToSpec.js

@@ -0,0 +1,506 @@
+import { parse } from "@babel/parser";
+//#region src/spec/jsxToSpec.ts
+/**
+* Sentinel value for useState setter functions.
+* When a prop value resolves to this, the prop is a state setter (e.g. onChange={setValue})
+* and should be stripped — $bindState handles write-back automatically.
+*/
+const STATE_SETTER = Symbol.for("jsxToSpec.stateSetter");
+function buildModuleScope(ast) {
+	const scope = {
+		values: /* @__PURE__ */ new Map(),
+		valueNodes: /* @__PURE__ */ new Map(),
+		components: /* @__PURE__ */ new Map(),
+		stateBindings: /* @__PURE__ */ new Map(),
+		stateSetters: /* @__PURE__ */ new Map()
+	};
+	const body = getModuleBody(ast);
+	if (!body) return scope;
+	collectUseStateBindings(body, scope);
+	for (const stmt of body) {
+		if (stmt.type === "VariableDeclaration") {
+			const decl = stmt;
+			if (decl.kind !== "const") continue;
+			for (const declarator of decl.declarations) {
+				const d = declarator;
+				if (d.id.type !== "Identifier" || !d.init) continue;
+				const name = d.id.name;
+				const value = evaluateExpression(d.init, scope);
+				if (value !== UNRESOLVED) scope.values.set(name, value);
+				scope.valueNodes.set(name, d.init);
+				if (name[0] === name[0].toUpperCase()) {
+					const jsx = findJsxInFunctionBody(d.init);
+					if (jsx) scope.components.set(name, jsx);
+				}
+			}
+		}
+		if (stmt.type === "FunctionDeclaration") {
+			const fn = stmt;
+			if (!fn.id || fn.id.type !== "Identifier") continue;
+			const name = fn.id.name;
+			if (name[0] === name[0].toUpperCase()) {
+				const jsx = findJsxInFunctionBody(fn);
+				if (jsx) scope.components.set(name, jsx);
+			}
+		}
+	}
+	return scope;
+}
+/**
+* Detect `const [x, setX] = useState(initialValue)` patterns in function
+* bodies and register them in the scope's stateBindings / stateSetters maps.
+*
+* Scans all function declarations and arrow function expressions at any
+* nesting level (top-level functions, component functions, etc.).
+*/
+function collectUseStateBindings(stmts, scope) {
+	for (const stmt of stmts) {
+		if (stmt.type === "FunctionDeclaration") {
+			const body = stmt.body;
+			if (body.type === "BlockStatement") collectUseStateFromBlock(body.body, scope);
+		}
+		if (stmt.type === "VariableDeclaration") {
+			const decl = stmt;
+			for (const declarator of decl.declarations) {
+				const d = declarator;
+				if (!d.init) continue;
+				if (d.init.type === "ArrowFunctionExpression" || d.init.type === "FunctionExpression") {
+					const body = d.init.body;
+					if (body.type === "BlockStatement") collectUseStateFromBlock(body.body, scope);
+				}
+			}
+		}
+	}
+}
+/**
+* Scan statements in a block for `const [x, setX] = useState(init)` patterns.
+*/
+function collectUseStateFromBlock(stmts, scope) {
+	for (const stmt of stmts) {
+		if (stmt.type !== "VariableDeclaration") continue;
+		const decl = stmt;
+		if (decl.kind !== "const") continue;
+		for (const declarator of decl.declarations) {
+			const d = declarator;
+			if (d.id.type !== "ArrayPattern" || !d.init) continue;
+			if (d.init.type !== "CallExpression") continue;
+			const call = d.init;
+			const callee = call.callee;
+			if (callee.type !== "Identifier") continue;
+			if (callee.name !== "useState") continue;
+			const elements = d.id.elements;
+			if (elements.length < 2) continue;
+			if (elements[0].type !== "Identifier" || elements[1].type !== "Identifier") continue;
+			const stateVarName = elements[0].name;
+			const setterName = elements[1].name;
+			const initArg = call.arguments[0];
+			const initialValue = initArg ? evaluateExpression(initArg, scope) : void 0;
+			scope.stateBindings.set(stateVarName, initialValue !== UNRESOLVED ? initialValue : null);
+			scope.stateSetters.set(setterName, stateVarName);
+			scope.values.set(stateVarName, { $bindState: `/${stateVarName}` });
+			scope.values.set(setterName, STATE_SETTER);
+		}
+	}
+}
+function getModuleBody(ast) {
+	if (ast.type === "File") return ast.program.body;
+	if (ast.type === "Program") return ast.body;
+	return null;
+}
+/**
+* Extract JSX from a function body (arrow function or function declaration).
+*/
+function findJsxInFunctionBody(node) {
+	if (node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression") {
+		const body = node.body;
+		return extractJsxFromBody(body);
+	}
+	if (node.type === "FunctionDeclaration") {
+		const body = node.body;
+		return extractJsxFromBody(body);
+	}
+	return null;
+}
+function extractJsxFromBody(body) {
+	if (body.type === "JSXElement") return body;
+	if (body.type === "JSXFragment") return body;
+	if (body.type === "ParenthesizedExpression") return extractJsxFromBody(body.expression);
+	if (body.type === "BlockStatement") {
+		const stmts = body.body;
+		for (const stmt of stmts) if (stmt.type === "ReturnStatement") {
+			const arg = stmt.argument;
+			if (arg) return extractJsxFromBody(arg);
+		}
+	}
+	return null;
+}
+/**
+* Sentinel value used when a prop expression couldn't be statically resolved.
+* Callers can check `hasUnresolvedProps(spec)` to detect this.
+*/
+const UNRESOLVED = Symbol.for("jsxToSpec.unresolved");
+/** Check if any element in the spec has prop values that couldn't be statically resolved. */
+function hasUnresolvedProps(spec) {
+	for (const el of Object.values(spec.elements)) if (el.props) {
+		for (const value of Object.values(el.props)) if (value === UNRESOLVED || value === STATE_SETTER) return true;
+	}
+	return false;
+}
+/** Return a copy of the spec with all UNRESOLVED and STATE_SETTER prop values removed. */
+function stripUnresolvedProps(spec) {
+	const elements = {};
+	for (const [key, el] of Object.entries(spec.elements)) {
+		if (!el.props) {
+			elements[key] = { ...el };
+			continue;
+		}
+		const cleanProps = {};
+		for (const [k, v] of Object.entries(el.props)) if (v !== UNRESOLVED && v !== STATE_SETTER) cleanProps[k] = v;
+		elements[key] = {
+			...el,
+			props: cleanProps
+		};
+	}
+	return {
+		...spec,
+		elements
+	};
+}
+function evaluateExpression(node, scope) {
+	switch (node.type) {
+		case "StringLiteral": return node.value;
+		case "NumericLiteral": return node.value;
+		case "BooleanLiteral": return node.value;
+		case "NullLiteral": return null;
+		case "Identifier": {
+			const name = node.name;
+			if (name === "undefined") return UNRESOLVED;
+			if (scope.values.has(name)) return scope.values.get(name);
+			const initNode = scope.valueNodes.get(name);
+			if (initNode) {
+				const value = evaluateExpression(initNode, scope);
+				if (value !== UNRESOLVED) {
+					scope.values.set(name, value);
+					return value;
+				}
+			}
+			return UNRESOLVED;
+		}
+		case "TemplateLiteral": {
+			const quasis = node.quasis;
+			const expressions = node.expressions;
+			if (expressions.length === 0) return quasis[0].value.cooked;
+			let result = "";
+			for (let i = 0; i < quasis.length; i++) {
+				result += quasis[i].value.cooked;
+				if (i < expressions.length) {
+					const val = evaluateExpression(expressions[i], scope);
+					if (val === UNRESOLVED) return UNRESOLVED;
+					result += String(val);
+				}
+			}
+			return result;
+		}
+		case "ObjectExpression": return evaluateObjectExpression(node, scope);
+		case "ArrayExpression": return evaluateArrayExpression(node, scope);
+		case "UnaryExpression": {
+			const unary = node;
+			if (unary.operator === "-") {
+				const arg = evaluateExpression(unary.argument, scope);
+				if (typeof arg === "number") return -arg;
+			}
+			if (unary.operator === "!") {
+				const arg = evaluateExpression(unary.argument, scope);
+				if (arg !== UNRESOLVED) return !arg;
+			}
+			return UNRESOLVED;
+		}
+		default: return UNRESOLVED;
+	}
+}
+function evaluateObjectExpression(node, scope) {
+	const result = {};
+	for (const prop of node.properties) {
+		if (prop.type === "SpreadElement") {
+			const arg = prop.argument;
+			const val = evaluateExpression(arg, scope);
+			if (val === UNRESOLVED || typeof val !== "object" || val === null) return UNRESOLVED;
+			Object.assign(result, val);
+			continue;
+		}
+		if (prop.type !== "ObjectProperty") return UNRESOLVED;
+		const objProp = prop;
+		if (objProp.computed) return UNRESOLVED;
+		let key;
+		if (objProp.key.type === "Identifier") key = objProp.key.name;
+		else if (objProp.key.type === "StringLiteral") key = objProp.key.value;
+		else return UNRESOLVED;
+		const value = evaluateExpression(objProp.value, scope);
+		if (value !== UNRESOLVED) result[key] = value;
+	}
+	return result;
+}
+function evaluateArrayExpression(node, scope) {
+	const result = [];
+	for (const element of node.elements) {
+		if (!element) return UNRESOLVED;
+		if (element.type === "SpreadElement") {
+			const arg = element.argument;
+			const val = evaluateExpression(arg, scope);
+			if (val === UNRESOLVED || !Array.isArray(val)) return UNRESOLVED;
+			result.push(...val);
+			continue;
+		}
+		const value = evaluateExpression(element, scope);
+		if (value === UNRESOLVED) return UNRESOLVED;
+		result.push(value);
+	}
+	return result;
+}
+function getTagName(element) {
+	const { name } = element.openingElement;
+	if (name.type === "JSXIdentifier") return name.name;
+	return null;
+}
+function getAttributeValue(valueNode, scope, ctx) {
+	if (valueNode === null) return true;
+	switch (valueNode.type) {
+		case "StringLiteral": return valueNode.value;
+		case "JSXExpressionContainer": {
+			const expr = valueNode.expression;
+			if (ctx && (expr.type === "JSXElement" || expr.type === "JSXFragment")) {
+				const slotKey = convertJsxNode(expr, ctx);
+				if (slotKey) return { $slot: slotKey };
+				return UNRESOLVED;
+			}
+			return evaluateExpression(expr, scope);
+		}
+		default: return UNRESOLVED;
+	}
+}
+function collectTextChildren(children) {
+	const textParts = [];
+	for (const child of children) if (child.type === "JSXText") {
+		const trimmed = child.value.replace(/\n\s*/g, " ").trim();
+		if (trimmed) textParts.push(trimmed);
+	} else if (child.type === "JSXExpressionContainer") {
+		const expr = child.expression;
+		if (expr.type === "StringLiteral") textParts.push(expr.value);
+		else return null;
+	} else if (child.type === "JSXElement" || child.type === "JSXFragment") return null;
+	return textParts.length > 0 ? textParts.join(" ") : null;
+}
+function hasElementChildren(children) {
+	return children.some((c) => c.type === "JSXElement" || c.type === "JSXFragment");
+}
+function nextKey(ctx) {
+	return `el${ctx.counter++}`;
+}
+/** Map React event prop names to json-render event names */
+const EVENT_PROP_MAP = {
+	onClick: "press",
+	onPress: "press",
+	onSubmit: "submit"
+};
+/**
+* Try to extract a json-render `on` binding from an event handler prop.
+*
+* Detects patterns like:
+*   onClick={() => setSetter(value)}    → { action: "setState", params: { statePath, value } }
+*   onClick={() => setter(value)}       → same (setter is a known state setter)
+*
+* Returns null if the prop is not a recognized event handler pattern.
+*/
+function tryExtractOnBinding(propName, valueNode, scope) {
+	const eventName = EVENT_PROP_MAP[propName];
+	if (!eventName || !valueNode) return null;
+	if (valueNode.type !== "JSXExpressionContainer") return null;
+	const expr = valueNode.expression;
+	if (expr.type !== "ArrowFunctionExpression") return null;
+	const arrow = expr;
+	let callExpr = null;
+	if (arrow.body.type === "CallExpression") callExpr = arrow.body;
+	else if (arrow.body.type === "BlockStatement") {
+		const stmts = arrow.body.body;
+		if (stmts.length === 1 && stmts[0].type === "ExpressionStatement") {
+			const innerExpr = stmts[0].expression;
+			if (innerExpr.type === "CallExpression") callExpr = innerExpr;
+		}
+	}
+	if (!callExpr) return null;
+	const call = callExpr;
+	if (call.callee.type !== "Identifier") return null;
+	const calleeName = call.callee.name;
+	const stateVarName = scope.stateSetters.get(calleeName);
+	if (!stateVarName) return null;
+	const arg = call.arguments[0];
+	const value = arg ? evaluateExpression(arg, scope) : null;
+	if (value === UNRESOLVED) return null;
+	return {
+		event: eventName,
+		action: {
+			action: "setState",
+			params: {
+				statePath: `/${stateVarName}`,
+				value
+			}
+		}
+	};
+}
+function convertElement(node, ctx) {
+	const tagName = getTagName(node);
+	if (!tagName) return null;
+	if (ctx.scope.components.has(tagName) && !ctx.inlining.has(tagName)) {
+		const componentJsx = ctx.scope.components.get(tagName);
+		ctx.inlining.add(tagName);
+		const result = convertJsxNode(componentJsx, ctx);
+		ctx.inlining.delete(tagName);
+		return result;
+	}
+	if (ctx.knownComponents && tagName[0] === tagName[0].toUpperCase() && !ctx.knownComponents.has(tagName)) return flattenChildrenAsFragment(node.children, ctx);
+	const key = nextKey(ctx);
+	const props = {};
+	const onBindings = {};
+	for (const attr of node.openingElement.attributes) if (attr.type === "JSXAttribute") {
+		const jsxAttr = attr;
+		const propName = jsxAttr.name.name;
+		const binding = tryExtractOnBinding(propName, jsxAttr.value, ctx.scope);
+		if (binding) {
+			onBindings[binding.event] = binding.action;
+			continue;
+		}
+		props[propName] = getAttributeValue(jsxAttr.value, ctx.scope, ctx);
+	} else if (attr.type === "JSXSpreadAttribute") props.__spread__ = UNRESOLVED;
+	const childKeys = [];
+	const textContent = collectTextChildren(node.children);
+	if (textContent !== null && !hasElementChildren(node.children)) props.children = textContent;
+	else for (const child of node.children) {
+		const childKey = convertJsxNode(child, ctx);
+		if (childKey) childKeys.push(childKey);
+	}
+	const assetType = ctx.resolveAssetNode?.(tagName, props) ?? null;
+	if (assetType) delete props.name;
+	const element = {
+		type: assetType ?? tagName,
+		props
+	};
+	if (childKeys.length > 0) element.children = childKeys;
+	if (Object.keys(onBindings).length > 0) element.on = onBindings;
+	ctx.elements[key] = element;
+	return key;
+}
+/**
+* Flatten a list of JSX children as if they were inside a fragment.
+* Returns a single key if there's one child, a Fragment element for
+* multiple, or null for none.
+*/
+function flattenChildrenAsFragment(children, ctx) {
+	const childKeys = [];
+	for (const child of children) {
+		const childKey = convertJsxNode(child, ctx);
+		if (childKey) childKeys.push(childKey);
+	}
+	if (childKeys.length === 1) return childKeys[0];
+	if (childKeys.length > 1) {
+		const fragKey = nextKey(ctx);
+		ctx.elements[fragKey] = {
+			type: "Fragment",
+			props: {},
+			children: childKeys
+		};
+		return fragKey;
+	}
+	return null;
+}
+function convertJsxNode(node, ctx) {
+	if (node.type === "JSXElement") return convertElement(node, ctx);
+	if (node.type === "JSXFragment") return flattenChildrenAsFragment(node.children, ctx);
+	return null;
+}
+function findJsxRoot(node) {
+	if (node.type === "JSXElement") return node;
+	if (node.type === "JSXFragment") return node;
+	if (node.type === "ParenthesizedExpression") return findJsxRoot(node.expression);
+	if (node.type === "ReturnStatement") {
+		const arg = node.argument;
+		return arg ? findJsxRoot(arg) : null;
+	}
+	if (node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression") {
+		const body = node.body;
+		return extractJsxFromBody(body);
+	}
+	if (node.type === "ExpressionStatement") return findJsxRoot(node.expression);
+	if (node.type === "VariableDeclaration") {
+		const declarations = node.declarations;
+		for (const decl of declarations) if (decl.type === "VariableDeclarator") {
+			const init = decl.init;
+			if (init) {
+				const found = findJsxRoot(init);
+				if (found) return found;
+			}
+		}
+		return null;
+	}
+	if (node.type === "FunctionDeclaration") {
+		const body = node.body;
+		if (body.type === "BlockStatement") {
+			const stmts = body.body;
+			for (const stmt of stmts) if (stmt.type === "ReturnStatement") return findJsxRoot(stmt);
+		}
+		return null;
+	}
+	if (node.type === "Program" || node.type === "File") {
+		const body = node.type === "File" ? node.program.body : node.body;
+		for (const stmt of body) {
+			const found = findJsxRoot(stmt);
+			if (found) return found;
+		}
+	}
+	return null;
+}
+/**
+* Convert JSX source code into a json-render Spec.
+*
+* Accepts either a full JSX module or a JSX expression snippet.
+* When `moduleSource` is provided, identifier references are resolved
+* against the module's top-level const declarations, and local component
+* functions are inlined.
+*
+* Returns `null` if no JSX element is found in the source.
+*/
+function jsxToSpec(source, options) {
+	const ast = parse(source, {
+		sourceType: "module",
+		plugins: ["jsx", "typescript"],
+		errorRecovery: true
+	});
+	const scope = buildModuleScope(options?.moduleSource ? parse(options.moduleSource, {
+		sourceType: "module",
+		plugins: ["jsx", "typescript"],
+		errorRecovery: true
+	}) : ast);
+	const jsxRoot = findJsxRoot(ast);
+	if (!jsxRoot) return null;
+	const ctx = {
+		elements: {},
+		counter: 0,
+		scope,
+		inlining: /* @__PURE__ */ new Set(),
+		knownComponents: options?.knownComponents ?? null,
+		resolveAssetNode: options?.resolveAssetNode ?? null
+	};
+	const rootKey = convertJsxNode(jsxRoot, ctx);
+	if (!rootKey) return null;
+	const spec = {
+		root: rootKey,
+		elements: ctx.elements
+	};
+	if (scope.stateBindings.size > 0) {
+		const state = {};
+		for (const [name, initialValue] of scope.stateBindings) state[name] = initialValue;
+		spec.state = state;
+	}
+	return spec;
+}
+//#endregion
+export { UNRESOLVED, hasUnresolvedProps, jsxToSpec, stripUnresolvedProps };

package/dist/spec/layer-props.d.ts

@@ -0,0 +1,52 @@
+import { BaseStyles, CompoundPropsEntry } from "../types.js";
+
+//#region src/spec/layer-props.d.ts
+type RenderedLayerProps = Record<string, Record<string, unknown>>;
+/**
+ * Structural view of the component fields style resolution reads. Satisfied by
+ * a real `@yahoo/uds-create-config` `Component` (Studio, playground) AND by codegen's
+ * capture-time `ProbeComponent` (`extractPreviewSpecs.buildRenderSpec`), so the
+ * same resolver bakes styles into the render spec at build time and resolves
+ * derived (non-render) values like the layers-panel `display` at render time.
+ */
+interface ResolvableComponent {
+  layers: ReadonlyMap<string, unknown>;
+  base?: BaseStyles;
+  props?: Record<string, unknown>;
+  compoundProps?: readonly CompoundPropsEntry[];
+}
+/**
+ * Resolve the styles a layer effectively has for a set of prop-axis values and
+ * (optionally) one forced interaction state, walking the authoring surfaces
+ * codegen reads:
+ *
+ *   1. `component.base[layer]` — the always-on baseline.
+ *   2. `component.props[axis].values[value][layer]` — per axis key in `propValues`.
+ *   3. `component.compoundProps[].layers[layer]` — for entries whose `when`
+ *       is a subset of `propValues` (multi-axis overrides).
+ *   4. State overlay — when `state` names a modifier sub-object (`_hover`) on
+ *       the merged surface, its props overlay the base so a static preview
+ *       shows that state.
+ *
+ * `propValues` are plain axis names → values (no reserved keys). `state` is a
+ * single forced interaction modifier (`'_hover'`); pass it directly rather than
+ * smuggling it into `propValues`. **Modes are intentionally not a parameter** —
+ * mode visuals ride a scoped wrapper class (`.dark &`) and flip live, so they
+ * are never folded into the static base here.
+ */
+declare function resolveAuthoredLayerProps(component: ResolvableComponent | undefined | null, layer: string, propValues: Record<string, unknown>, state?: string | null): Record<string, unknown>;
+/**
+ * Resolve per-layer style bags for a set of prop values, mirroring the config's
+ * variant resolution. `buildRenderSpec` calls this once per variant combo to
+ * bake the bags onto the render spec.
+ *
+ * `state` is left `null` by the bake path — modifier blocks ride through as
+ * nested style props and forced state is applied per cell (the render-spec
+ * consumers fold the active modifier into props), so folding it into the base
+ * here would be redundant. (Derived callers like the layers panel also pass no
+ * state.) `cssVarPrefix` resolves color expressions to a `var(...)`-referencing
+ * arbitrary value.
+ */
+declare function resolveRenderedLayerProps(component: ResolvableComponent | undefined, propValues: Record<string, unknown>, state?: string | null, cssVarPrefix?: string): RenderedLayerProps;
+//#endregion
+export { ResolvableComponent, resolveAuthoredLayerProps, resolveRenderedLayerProps };