@yahoo/uds-v5-wip 1.60.0 → 1.61.0

package/dist/codegen/dist/loader/getLoaderArtifacts.js

@@ -0,0 +1,2 @@
+import "../../../utils/dist/index.js";
+import "../../../config/dist/index.js";

package/dist/config/dist/Props.d.ts

@@ -1,6 +1,6 @@
-import { RegisteredStyleProps } from "./component-refs.js";
+import { RegisteredComposites, RegisteredModifiers, RegisteredStyleProps } from "./component-refs.js";
 import { ComponentConfigValue, HtmlTag, LayerInput, PropBinding } from "./component-config.js";
-import { ComponentPropsWithoutRef, HTMLAttributes, JSX } from "react";
+import { ComponentPropsWithRef, HTMLAttributes, JSX, ReactNode } from "react";
 
 //#region ../config/dist/Props.d.ts
 //#region src/Props.d.ts
@@ -8,13 +8,38 @@ import { ComponentPropsWithoutRef, HTMLAttributes, JSX } from "react";
  * Resolve the native HTML-attribute surface for the config's root tag.
  *
  *  - When `TTag` is a known `JSX.IntrinsicElements` key (`'a'`, `'div'`,
- *    `'button'`, …), use `ComponentPropsWithoutRef<TTag>` so element-
- *    specific attrs land in the prop type (`href` on `'a'`, `disabled`
- *    on `'button'`, etc.).
+ *    `'button'`, …), use `ComponentPropsWithRef<TTag>` so element-
+ *    specific attrs *and* the React 19 `ref` prop both land in the prop
+ *    type (`href` on `'a'`, `disabled` on `'button'`, `ref` on every
+ *    intrinsic).
  *  - Otherwise (no tag captured — e.g. the root is a brace-ref or
  *    composed-layer), fall back to the generic `HTMLAttributes<HTMLElement>`.
  */
-type ElementProps<TTag extends HtmlTag | undefined> = TTag extends keyof JSX.IntrinsicElements ? ComponentPropsWithoutRef<TTag> : HTMLAttributes<HTMLElement>;
+type ElementProps<TTag extends HtmlTag | undefined> = TTag extends keyof JSX.IntrinsicElements ? ComponentPropsWithRef<TTag> : HTMLAttributes<HTMLElement>;
+/**
+ * Props inherited from the wrapped component when the root layer is a
+ * component value or a `ComposedLayer` `{ component, defaultProps }`
+ * form. Returns the wrapped component's own resolved `Props<...>`
+ * shape so a wrapper's JSX surface inherits everything the wrapped
+ * component accepts. Returns `{}` when the root isn't composed.
+ *
+ * Reads the `__config` slot off the layer value (or the
+ * `ComposedLayer`'s `component` field) and recursively resolves
+ * `Props<TInnerConfig>`. Falls back to the legacy
+ * `RegisteredComponents[name]` lookup when the layer is the
+ * shape so a wrapper's JSX surface inherits everything the wrapped
+ * component accepts. Returns `{}` when the root isn't composed.
+ *
+ * Reads the `__config` slot off the layer value directly. Authoring
+ * uses bare `defineComponent`-produced values (`layers: { root: Box }`)
+ * — there's no longer a `{ component, defaultProps }` wrapper layer
+ * to walk through.
+ */
+type ComposedRootProps<TLayers> = TLayers extends {
+  root: infer R;
+} ? R extends {
+  readonly __config: infer TInnerConfig extends ComponentConfigValue<Record<string, LayerInput>, Record<string, PropBinding>, HtmlTag | undefined>;
+} ? Props<TInnerConfig> : {} : {};
 /**
  * Resolve the allowed-value union for one registered style prop.
  * Falls back to `string` when the prop registered no tokens (codegen
@@ -22,26 +47,104 @@ type ElementProps<TTag extends HtmlTag | undefined> = TTag extends keyof JSX.Int
  */
 type StylePropValue<K extends keyof RegisteredStyleProps> = [RegisteredStyleProps[K]] extends [never] ? string : RegisteredStyleProps[K];
 /**
- * Extract the registered style-prop name from a binding value:
- *  - `'{bg}'` → `'bg'`
- *  - `{ styleProp: '{bg}' }` → `'bg'`
+ * Extract the registered style-prop name from a `StylePropMarker`
+ * binding — `{ __kind: 'styleProp', ref: 'bg', layer }` → `'bg'`.
  * Returns `never` for non-matching forms.
  */
-type StylePropRefName<TBinding> = TBinding extends `{${infer N}}` ? N extends keyof RegisteredStyleProps & string ? N : never : TBinding extends {
-  styleProp: `{${infer N}}`;
+type StylePropRefName<TBinding> = TBinding extends {
+  readonly __kind: 'styleProp';
+  readonly ref: infer N;
 } ? N extends keyof RegisteredStyleProps & string ? N : never : never;
+/**
+ * Extract the registered composite-group name from a `composite()`
+ * marker binding:
+ *  - `{ __kind: 'composite', ref: 'textVariant' }` → `'textVariant'`
+ *    (the marker stores the bare name — no brace-ref wrapping; the
+ *    `composite()` call's position already establishes the
+ *    composite-ref context.)
+ * Returns `never` for non-matching forms.
+ */
+type CompositeRefName<TBinding> = TBinding extends {
+  readonly __kind: 'composite';
+  readonly ref: infer N;
+} ? N extends keyof RegisteredComposites & string ? N : never : never;
+/**
+ * Resolve the allowed-value union for a registered composite group —
+ * the union of `styles` keys. Falls back to `string` when the
+ * registry isn't populated (e.g. inside `@uds/config`'s own tests
+ * where codegen-emitted augmentation isn't loaded).
+ */
+type CompositeValue<K extends keyof RegisteredComposites> = RegisteredComposites[K] extends {
+  styles: infer S;
+} ? keyof S & string : string;
+/**
+ * Detect a `slot('layer')` / `slot('layer/prop')` marker. Authoring
+ * surface stamps `__kind: 'slot'` on the value so the render-fn
+ * arg can be typed as `ReactNode` — slot props always route their
+ * value into a layer's children (or named slot prop), so a node is
+ * the only thing they can legally carry.
+ */
+/**
+ * Resolve the JSX-value type for a `slot('layer/prop')` marker by
+ * looking up `prop` on the target layer's surface:
+ *
+ *  - **Composed-component layer** — read `Props<TInnerConfig>[prop]`,
+ *    so `slot('button/onClick')` types as the click-handler the
+ *    wrapped component declares.
+ *  - **HTML-tag layer** (bare-tag `'div'` or `{ tag: 'a', attrs }`) —
+ *    read `ComponentPropsWithRef<tag>[prop]`, so `slot('link/href')`
+ *    types as `string | undefined`.
+ *  - Unknown layer / unknown prop falls back to `ReactNode` (the
+ *    common case for slots and a safe default when the type system
+ *    can't pinpoint).
+ */
+type SlotTargetKey<A> = [A] extends [string] ? A : 'children';
+type SlotPropValue<TBinding, TLayers> = TBinding extends {
+  readonly __kind: 'slot';
+  readonly layer: infer L extends keyof TLayers & string;
+  readonly prop?: infer A;
+} ? TLayers[L] extends {
+  readonly __config: infer TInner extends ComponentConfigValue<Record<string, LayerInput>, Record<string, PropBinding>, HtmlTag | undefined>;
+} ? SlotTargetKey<A> extends keyof Props<TInner> ? Props<TInner>[SlotTargetKey<A> & keyof Props<TInner>] : ReactNode : TLayers[L] extends keyof JSX.IntrinsicElements ? SlotTargetKey<A> extends keyof ComponentPropsWithRef<TLayers[L]> ? ComponentPropsWithRef<TLayers[L]>[SlotTargetKey<A> & keyof ComponentPropsWithRef<TLayers[L]>] : ReactNode : TLayers[L] extends {
+  readonly tag: infer T extends keyof JSX.IntrinsicElements;
+} ? SlotTargetKey<A> extends keyof ComponentPropsWithRef<T> ? ComponentPropsWithRef<T>[SlotTargetKey<A> & keyof ComponentPropsWithRef<T>] : ReactNode : ReactNode : ReactNode;
+type IsSlotMarker<TBinding> = TBinding extends {
+  readonly __kind: 'slot';
+} ? true : false;
 /**
  * Walk the config's `props` block and produce one optional JSX prop
- * per entry.
+ * per entry:
+ *
+ *  - `slot('layer/prop')` markers narrow to the value type the target
+ *    layer exposes under `prop` — see {@link SlotPropValue}.
+ *  - `styleProp(ref)` markers narrow to the registered token union.
+ *  - `composite(ref)` markers narrow to the composite group's `styles`
+ *    keys union.
+ *  - Anything unrecognized stays open as `unknown`.
  */
-type PropsFromConfig<TProps> = { [K in keyof TProps]?: StylePropRefName<TProps[K]> extends never ? unknown : StylePropValue<Extract<StylePropRefName<TProps[K]>, keyof RegisteredStyleProps>> };
+type PropsFromConfig<TProps, TLayers> = { [K in keyof TProps]?: IsSlotMarker<TProps[K]> extends true ? SlotPropValue<TProps[K], TLayers> : StylePropRefName<TProps[K]> extends never ? CompositeRefName<TProps[K]> extends never ? unknown : CompositeValue<Extract<CompositeRefName<TProps[K]>, keyof RegisteredComposites>> : StylePropValue<Extract<StylePropRefName<TProps[K]>, keyof RegisteredStyleProps>> };
 /**
  * Force TypeScript to fully evaluate a mapped/conditional type so the
  * hover display shows the resolved shape (`bg?: 'brand' | 'accent'`)
  * instead of the unevaluated type expression
- * (`PropsFromConfig<{ readonly bg: '{bg}' }>`).
+ * (`PropsFromConfig<{ readonly bg: StylePropMarker<'root', 'bg'> }>`).
  */
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
+/**
+ * `layerProps={{ overlay: { bg: '...' }, panel: { width: '...' } }}` — the
+ * value-type for one layer. If the layer is a defined component (carries a
+ * `__config` slot), use that component's full `Props<...>` surface so style
+ * props, modifiers, and HTML attrs all autocomplete. Otherwise (a bare
+ * HTML-tag string layer), widen to a permissive style-prop bag.
+ */
+type LayerPropsValue<TLayer> = TLayer extends {
+  readonly __config: infer TInner extends ComponentConfigValue<Record<string, LayerInput>, Record<string, PropBinding>, HtmlTag | undefined>;
+} ? Partial<Props<TInner>> : Partial<HTMLAttributes<HTMLElement>> & { [K in keyof RegisteredStyleProps]?: StylePropValue<K> };
+/**
+ * `{ overlay?: ..., panel?: ..., dismiss?: ..., ... }` — every layer in
+ * `TLayers` is reachable.
+ */
+type LayerPropsMap<TLayers extends Record<string, LayerInput>> = { [K in keyof TLayers]?: LayerPropsValue<TLayers[K]> };
 /**
  * Standard `data-*` attributes are valid on every HTML element by spec.
  * React 19's bundled types don't carry an index signature for them, so
@@ -51,24 +154,57 @@ type Prettify<T> = { [K in keyof T]: T[K] } & {};
 interface DataAttrs {
   [key: `data-${string}`]: unknown;
 }
+/**
+ * Component prop surface without modifiers — the "base" type that
+ * `Props<TConfig>` wraps with `RegisteredModifiers<PropsBase<TConfig>>`.
+ *
+ * Splitting the modifier layer out breaks a self-reference cycle:
+ * TS can resolve `RegisteredModifiers<PropsBase<TConfig>>` because
+ * PropsBase doesn't reference itself, but
+ * `RegisteredModifiers<Props<TConfig>>` directly inside `Props<TConfig>`
+ * leaves TS unable to materialize the recursive shape and the
+ * modifier keys collapse to nothing at consumer call sites.
+ *
+ * Modifier values consequently autocomplete against the component's
+ * full top-level surface but don't carry recursive modifier nesting
+ * (`_hover={{ _focus: { ... } }}` won't typecheck through this path).
+ * Codegen-emitted `Registered${Name}Props` keeps the recursive shape
+ * because it self-references through a *named* alias the compiler
+ * can name-resolve lazily — `Props<TConfig>` can't replicate that.
+ */
+type PropsBase<TConfig extends ComponentConfigValue<Record<string, LayerInput>, Record<string, PropBinding>, HtmlTag | undefined>> = TConfig extends ComponentConfigValue<infer TLayers extends Record<string, LayerInput>, infer TProps extends Record<string, PropBinding>, infer TTag extends HtmlTag | undefined> ? PropsFromConfig<TProps, TLayers> & Omit<ComposedRootProps<TLayers>, keyof TProps> & Omit<ElementProps<TTag>, keyof TProps | keyof ComposedRootProps<TLayers>> & DataAttrs & {
+  as?: keyof JSX.IntrinsicElements;
+  layerProps?: LayerPropsMap<TLayers>;
+} : never;
 /**
  * Public derived-props type.
  *
- * Four layers:
+ * Layers — same shape codegen emits for `Registered${Name}Props` in
+ * `uds-env.d.ts` so `React.ComponentProps<typeof Box>` resolves to a
+ * type structurally equivalent to `RegisteredBoxProps<'div'>`:
+ *
  *  1. `PropsFromConfig<TConfig['props']>` — the config's declared props.
- *  2. `ElementProps<TTag>` — native attrs narrowed to the root tag when
- *     statically known (e.g. `href` on `'a'`), otherwise generic
- *     `HTMLAttributes<HTMLElement>`. Anything colliding with (1) is
- *     stripped out so custom props' value unions don't get widened.
- *  3. `DataAttrs` — permissive `data-*` index signature.
- *  4. Polymorphic `as` prop (open-ended `string` for now).
+ *  2. `ComposedRootProps<TLayers>` — the wrapped component's registered
+ *     prop shape when the root layer is a ComposedLayer
+ *     (`{ component: '{Box}' }`). Falls back to `{}` otherwise.
+ *  3. `Omit<ComponentPropsWithRef<TTag>, ...>` — native attrs narrowed
+ *     to the root tag (or the wrapper's `defaultProps.as` for value-
+ *     extends — captured as TTag at defineComponent time). Anything
+ *     colliding with (1) or (2) is stripped out.
+ *  4. `DataAttrs` — permissive `data-*` index signature (React's
+ *     `ComponentPropsWithRef` doesn't carry this).
+ *  5. `RegisteredModifiers<PropsBase<TConfig>>` — narrowed
+ *     `_<modifier>` keys with `Partial<...>` values. Augmented by
+ *     codegen from `BUILT_IN_PSEUDO` + config-defined modes + custom
+ *     modifiers.
+ *  6. Polymorphic `as` prop — `keyof JSX.IntrinsicElements` so the
+ *     value is a real tag name, matching codegen's emission.
  */
-type Props<TConfig extends ComponentConfigValue<Record<string, LayerInput>, Record<string, PropBinding>, HtmlTag | undefined>> = TConfig extends ComponentConfigValue<Record<string, LayerInput>, infer TProps extends Record<string, PropBinding>, infer TTag extends HtmlTag | undefined> ? Prettify<PropsFromConfig<TProps> & Omit<ElementProps<TTag>, keyof TProps> & DataAttrs & {
-  as?: string;
-}> : never;
+type Props<TConfig extends ComponentConfigValue<Record<string, LayerInput>, Record<string, PropBinding>, HtmlTag | undefined>> = Prettify<PropsBase<TConfig> & RegisteredModifiers<PropsBase<TConfig>>>;
 /**
  * `Props<typeof boxConfig>` for the common 'use the config's inferred
  * type' invocation. Keeps `box.tsx` from having to repeat the generic.
  */
+type PropsOf<TConfig> = TConfig extends ComponentConfigValue<Record<string, LayerInput>, Record<string, PropBinding>, HtmlTag | undefined> ? Props<TConfig> : never; //#endregion
 //#endregion
-export { Props };
+export { Props, PropsOf };

package/dist/config/dist/bindRender.d.ts

@@ -0,0 +1,16 @@
+import { LayerBundle, LayerInput } from "./component-config.js";
+
+//#region ../config/dist/bindRender.d.ts
+//#region src/bindRender.d.ts
+/**
+ * Arguments handed to the user's render function. `props` is keyed by
+ * the component's layer names; `children` is React's standard
+ * children. Extra incoming props that aren't claimed by the config
+ * arrive on the same object.
+ */
+interface CreateComponentRenderArgs<TLayers extends Record<string, LayerInput>> {
+  props: { [K in keyof TLayers]: LayerBundle };
+  [key: string]: unknown;
+} //#endregion
+//#endregion
+export { CreateComponentRenderArgs };

package/dist/config/dist/bindRender.js

@@ -0,0 +1,310 @@
+import { buildStylePropClassName } from "./className.js";
+import { kebabCase } from "../../utils/dist/string-utils/kebabCase.js";
+import { componentCompoundClass, componentSlotClass, componentVariantClass } from "../../utils/dist/string-utils/componentClassName.js";
+import "../../utils/dist/index.js";
+import { getRegisteredComposite, getRegisteredStyleProp } from "./runtime-registry.js";
+//#region ../config/dist/bindRender.js
+/**
+* **NEW-API ONLY** — internal runtime for `defineComponent`-authored
+* configs. Binds a config to a React render function and walks the
+* `layers` / `props` blocks on every render to produce `LayerBundle`s.
+*
+* Does NOT touch any legacy `createComponent` / `defineComponents`
+* code path. The legacy `createComponent` factory lives in
+* `@uds/components` and has its own runtime (className composition
+* via `getStyles` / `processStyleProps`).
+*
+* Render-time behavior:
+*
+*  1. The framework walks each entry in `config.layers` and builds a
+*     `LayerBundle` per layer — a `className` string plus any HTML
+*     attrs / forwarded props. Primitive layers with `defaultProps`
+*     pick up the deterministic `componentName-layerName` @utility
+*     class (the same one codegen emits from those defaults).
+*
+*  2. Incoming JSX props are partitioned per the `props` config:
+*     style-prop bindings → contribute classes to a specific layer's
+*     bundle; composite bindings → expand to multiple layers' bundles;
+*     surface forwards → land verbatim on the target layer's bundle;
+*     bool/enum markers → contribute data-attrs or per-layer overrides.
+*
+*  3. The render function receives `{ props, children, ...rest }` where
+*     `props.<layer>` is the computed bundle for that layer and
+*     `...rest` carries any props that weren't claimed by the config.
+*
+* Exported surface: `bindRender` (consumed by `defineComponent.ts`).
+*/
+/**
+* Type-guard: a `StylePropMarker` is the helper-emitted binding with
+* `__kind: 'styleProp'`, `layer`, and `ref` (bare registered style-
+* prop name). Authored via `styleProp(ref).on(layer)`.
+*/
+function isStylePropMarker(binding) {
+	return typeof binding === "object" && binding !== null && binding.__kind === "styleProp" && typeof binding.ref === "string" && typeof binding.layer === "string";
+}
+/**
+* Type-guard: a `StringMarker` carries only `__kind: 'string'`.
+* Authored via `string()` — parallel to `bool()`, but the JSX value
+* is a string written verbatim into `data-<kebab-name>="<value>"` on
+* every layer's bundle.
+*/
+function isStringMarker(binding) {
+	return typeof binding === "object" && binding !== null && binding.__kind === "string";
+}
+/**
+* Type-guard: an `EnumMarker` carries the `__kind: 'enum'` brand and a
+* `values` map (axis-value → per-layer style map). Authored via
+* `enums({...})` in the `props` block of a verbose-form
+* `defineComponent` call.
+*/
+function isEnumMarker(binding) {
+	return typeof binding === "object" && binding !== null && binding.__kind === "enum";
+}
+/**
+* Type-guard: a `BoolMarker` carries only the `__kind: 'bool'` brand.
+* Authored via `bool()` in the `props` block (e.g. `loading: bool()`).
+*/
+function isBoolMarker(binding) {
+	return typeof binding === "object" && binding !== null && binding.__kind === "bool";
+}
+/**
+* Type-guard: a `SlotMarker` carries `__kind: 'slot'`, a `layer` name,
+* and optionally an `as` target. Authored via `slot('layer')` or
+* `slot('layer', { as: 'propName' })`.
+*/
+function isSlotMarker(binding) {
+	return typeof binding === "object" && binding !== null && binding.__kind === "slot" && typeof binding.layer === "string";
+}
+/**
+* Type-guard: a `CompositeMarker` carries `__kind: 'composite'` and a
+* brace-ref `ref` field pointing at a registered composite group.
+* Authored via `composite('{textVariant}')` in the `props` block —
+* the implicit-root-layer shorthand for composite bindings.
+*/
+function isCompositeMarker(binding) {
+	return typeof binding === "object" && binding !== null && binding.__kind === "composite" && typeof binding.ref === "string";
+}
+/**
+* Type-guard: a layer value is a component value (a `defineComponent`
+* result). Recognized by the `__config` brand attached to every bound
+* component. Stand-alone primitives (a `string` tag, `{ tag, attrs }`)
+* never carry `__config` so the discriminator is unambiguous.
+*/
+function isComposedComponentValue(value) {
+	return typeof value === "function" && "__config" in value;
+}
+/**
+* Append a className to a layer bundle, joining with a space if a class
+* was already accumulated. Empty / falsy contributions are dropped.
+*/
+function appendClassName(bundle, className) {
+	if (!className) return;
+	const existing = bundle.className;
+	bundle.className = existing ? `${existing} ${className}` : className;
+}
+/**
+* Build an initial `LayerBundle` for a layer.
+*
+*  - `PrimitiveLayer.attrs` — locked HTML attrs (`role="alert"`,
+*    `aria-live="polite"`, …) seeded onto the bundle so the rendered
+*    element carries them.
+*  - Bare-tag string layers (`'div'`), bare component-value layers
+*    (`{ root: Card }`) — bundle starts empty; per-layer base styles
+*    come from the config's top-level `base: { <layer>: {...} }`
+*    block in a later pass.
+*/
+function buildLayerBundle(layer, _layerName, _componentName) {
+	const bundle = {};
+	if (layer === null || layer === void 0) return bundle;
+	if (isComposedComponentValue(layer)) return bundle;
+	if (typeof layer !== "object") return bundle;
+	if ("tag" in layer) {
+		const { attrs } = layer;
+		if (attrs) for (const [key, value] of Object.entries(attrs)) bundle[key] = value;
+	}
+	return bundle;
+}
+/**
+* Internal: bind a config to a render function and return a React.FC.
+* Shared by `createComponent` (public, type-explicit two-arg form) and
+* `defineComponent` (primitive auto-render + chained `.render()`).
+*/
+function bindRender(config, render, options) {
+	const Component = (incomingProps) => {
+		const componentName = config.__componentName;
+		const configDefaults = config.defaultProps;
+		const effectiveProps = configDefaults ? {
+			...configDefaults,
+			...incomingProps
+		} : incomingProps;
+		const bundles = {};
+		for (const [layerName, layerValue] of Object.entries(config.layers)) bundles[layerName] = buildLayerBundle(layerValue, layerName, componentName);
+		const baseBlock = config.base;
+		if (baseBlock && componentName) for (const layerName of Object.keys(baseBlock)) {
+			const target = bundles[layerName];
+			if (!target) continue;
+			appendClassName(target, componentSlotClass(componentName, layerName));
+		}
+		const claimedKeys = /* @__PURE__ */ new Set();
+		const propsBlock = config.props;
+		if (propsBlock) for (const [jsxPropKey, binding] of Object.entries(propsBlock)) {
+			const incoming = effectiveProps[jsxPropKey];
+			if (isStylePropMarker(binding)) {
+				claimedKeys.add(jsxPropKey);
+				if (incoming === void 0 || incoming === null || incoming === false) continue;
+				const styleProp = getRegisteredStyleProp(binding.ref);
+				if (!styleProp) continue;
+				const target = bundles[binding.layer];
+				if (!target) continue;
+				const className = buildStylePropClassName(styleProp, incoming);
+				if (className) appendClassName(target, className);
+				continue;
+			}
+			if (isEnumMarker(binding)) {
+				claimedKeys.add(jsxPropKey);
+				if (incoming === void 0 || incoming === null || !componentName) continue;
+				const valueKey = String(incoming);
+				const perLayerStyles = binding.values[valueKey];
+				if (typeof perLayerStyles !== "object" || perLayerStyles === null) continue;
+				for (const layerName of Object.keys(perLayerStyles)) {
+					const target = bundles[layerName];
+					if (!target) continue;
+					appendClassName(target, componentVariantClass(componentName, layerName, jsxPropKey, valueKey));
+				}
+				continue;
+			}
+			if (isSlotMarker(binding)) {
+				if (!binding.layer) continue;
+				claimedKeys.add(jsxPropKey);
+				if (incoming === void 0 || incoming === null) continue;
+				const target = bundles[binding.layer];
+				if (!target) continue;
+				target[binding.prop ?? "children"] = incoming;
+				continue;
+			}
+			if (isCompositeMarker(binding)) {
+				claimedKeys.add(jsxPropKey);
+				if (incoming === void 0 || incoming === null) continue;
+				const refName = binding.ref;
+				if (!refName) continue;
+				const composite = getRegisteredComposite(refName);
+				if (!composite) continue;
+				const valueKey = String(incoming);
+				if (!composite.styles[valueKey]) continue;
+				const rootBundle = bundles.root;
+				if (!rootBundle) continue;
+				appendClassName(rootBundle, `${refName}-${valueKey.replace(/\./g, "_").replace(/\//g, "-")}`);
+				continue;
+			}
+			if (isBoolMarker(binding)) {
+				claimedKeys.add(jsxPropKey);
+				if (!incoming) continue;
+				const attrName = `data-${kebabCase(jsxPropKey)}`;
+				for (const layerName of Object.keys(bundles)) {
+					const target = bundles[layerName];
+					if (target) target[attrName] = "true";
+				}
+				continue;
+			}
+			if (isStringMarker(binding)) {
+				claimedKeys.add(jsxPropKey);
+				if (incoming === void 0 || incoming === null || incoming === "") continue;
+				const attrName = `data-${kebabCase(jsxPropKey)}`;
+				const attrValue = String(incoming);
+				for (const layerName of Object.keys(bundles)) {
+					const target = bundles[layerName];
+					if (target) target[attrName] = attrValue;
+				}
+			}
+		}
+		const compoundProps = config.compoundProps;
+		if (compoundProps && componentName) for (const entry of compoundProps) {
+			const conditions = {};
+			let match = true;
+			for (const [conditionKey, conditionValue] of Object.entries(entry.when)) {
+				const incoming = effectiveProps[conditionKey];
+				if (incoming === void 0 || incoming === null) {
+					match = false;
+					break;
+				}
+				const incomingStr = String(incoming);
+				if (incomingStr !== String(conditionValue)) {
+					match = false;
+					break;
+				}
+				conditions[conditionKey] = incomingStr;
+			}
+			if (!match) continue;
+			for (const [layerName, layerOverride] of Object.entries(entry.layers)) {
+				const target = bundles[layerName];
+				if (!target) continue;
+				if (layerOverride?.__kind === "hidden") {
+					target.__hidden = true;
+					continue;
+				}
+				appendClassName(target, componentCompoundClass(componentName, layerName, conditions));
+			}
+		}
+		const layerPropsValue = effectiveProps.layerProps;
+		if (typeof layerPropsValue === "object" && layerPropsValue !== null && !Array.isArray(layerPropsValue)) {
+			claimedKeys.add("layerProps");
+			for (const [layerName, overrides] of Object.entries(layerPropsValue)) {
+				if (typeof overrides !== "object" || overrides === null || Array.isArray(overrides)) continue;
+				const bundle = bundles[layerName];
+				if (!bundle) continue;
+				for (const [propKey, propValue] of Object.entries(overrides)) {
+					if (propKey.startsWith("_")) {
+						if (typeof propValue !== "object" || propValue === null) continue;
+						const variantName = propKey.slice(1);
+						for (const [innerKey, innerValue] of Object.entries(propValue)) {
+							const styleProp = getRegisteredStyleProp(innerKey);
+							if (!styleProp) continue;
+							const className = buildStylePropClassName(styleProp, innerValue);
+							if (className) appendClassName(bundle, `${variantName}:${className}`);
+						}
+						continue;
+					}
+					const styleProp = getRegisteredStyleProp(propKey);
+					if (styleProp) {
+						if (propValue === void 0 || propValue === null || propValue === false) continue;
+						const className = buildStylePropClassName(styleProp, propValue);
+						if (className) appendClassName(bundle, className);
+						continue;
+					}
+					if (propKey === "className" && typeof propValue === "string") {
+						appendClassName(bundle, propValue);
+						continue;
+					}
+					bundle[propKey] = propValue;
+				}
+			}
+		}
+		const rootBundleForMods = bundles.root;
+		for (const [key, value] of Object.entries(effectiveProps)) {
+			if (!key.startsWith("_")) continue;
+			if (claimedKeys.has(key)) continue;
+			claimedKeys.add(key);
+			if (!rootBundleForMods) continue;
+			if (typeof value !== "object" || value === null) continue;
+			const variantName = key.slice(1);
+			for (const [innerKey, innerValue] of Object.entries(value)) {
+				const styleProp = getRegisteredStyleProp(innerKey);
+				if (!styleProp) continue;
+				const baseClass = buildStylePropClassName(styleProp, innerValue);
+				if (!baseClass) continue;
+				appendClassName(rootBundleForMods, `${variantName}:${baseClass}`);
+			}
+		}
+		const passthrough = {};
+		for (const [key, value] of Object.entries(effectiveProps)) if (!claimedKeys.has(key)) passthrough[key] = value;
+		return render({
+			...passthrough,
+			props: bundles
+		});
+	};
+	const displayName = options?.displayName || render.displayName || render.name?.trim() || void 0;
+	if (displayName) Component.displayName = displayName;
+	return Component;
+}
+//#endregion
+export { bindRender };

package/dist/config/dist/className.d.ts

@@ -0,0 +1,54 @@
+//#region ../config/dist/className.d.ts
+//#region src/className.d.ts
+/**
+ * **NEW-API ONLY** — shared utility-class derivation for
+ * `defineComponent`-authored components.
+ *
+ * Single source of truth for `(prop, value, styleProp) → class`.
+ * Consumed by:
+ *
+ *   - `bindRender.ts` (runtime) — emits the per-layer className
+ *     bundle as JSX renders.
+ *   - `getStylesForConfig.ts` (build-time) — derives the same
+ *     className list for the CSS scanner's safelist so the purger
+ *     keeps every class the runtime can produce.
+ *
+ * Both paths MUST agree on the className shape. Centralising the
+ * derivation here is the contract: any change to the convention
+ * (e.g. boolean-alias handling) updates one place and both paths
+ * stay in lockstep.
+ *
+ * Does NOT touch the legacy `@uds/core`'s `getStyles` /
+ * `propMappings` — that's the legacy `createComponent` factory's
+ * world and lives in a different package.
+ */
+/**
+ * Build the utility-class name a style prop emits for a given
+ * JSX-level value. Mirrors the codegen convention in
+ * `prepareCss.ts`'s @utility emission:
+ *
+ *   - `classPrefix === ''` — the value IS the class (e.g.
+ *     `<Box display="block">` → `.block`).
+ *   - Boolean `true` — the class IS the bare `classPrefix`
+ *     (`<Box border>` / `<Box border={true}>` → `.border`, never
+ *     `.border-true`). Falsy (`undefined` / `null` / `false`) →
+ *     `undefined`, so the caller omits the class entirely. The "no
+ *     border" state is the default; adding a class to undo one that
+ *     was never applied is pointless.
+ *   - Bracketed arbitrary values (`'[#abc]'`, `'[100px]'`) keep
+ *     their brackets verbatim: `bg-[#abc]`, `w-[100px]`.
+ *   - Otherwise: `${classPrefix}-${safeTokenName(value)}`. Authors
+ *     write the original token name (`'1.5'`); the @utility block
+ *     is keyed by the class-name-safe form (`'1_5'`), so apply the
+ *     conversion at emit time. Bracketed arbitrary values are left
+ *     alone — Tailwind's wildcard utility expansion expects them
+ *     verbatim.
+ *
+ * Returns `undefined` when no class should be emitted — callers
+ * skip the contribution rather than push a malformed token.
+ */
+declare function buildStylePropClassName(styleProp: {
+  classPrefix: string;
+}, value: unknown): string | undefined; //#endregion
+//#endregion
+export { buildStylePropClassName };