@yahoo/uds-v5-wip 1.60.0 → 1.61.0

package/dist/config/dist/defineComponent.d.ts

@@ -1,18 +1,135 @@
-import { ComponentConfigValue, HtmlTag, LayerInput } from "./component-config.js";
+import { BoolMarker, ComponentConfigInput, ComponentConfigValue, EnumMarker, HiddenMarker, HtmlTag, LayerInput, PrimitivePropBinding, RootTag, SlotMarker, SplitSlotPath, StringMarker, StylePropMarker, TokenMarker, VerbosePropBinding, composite } from "./component-config.js";
 import { Props } from "./Props.js";
-import { ReactNode } from "react";
+import { CreateComponentRenderArgs } from "./bindRender.js";
+import { JSX, ReactNode } from "react";
 
 //#region ../config/dist/defineComponent.d.ts
 //#region src/defineComponent.d.ts
+/**
+ * Helpers injected into a `defineComponent` callback. Carries
+ * factories for every prop-binding marker shape so:
+ *
+ *  - Prop bindings are introspectable at runtime (each helper stamps
+ *    a `__kind` discriminator) — drives both auto-generated TS types
+ *    and the Studio design-panel control selection.
+ *  - Layer-bound helpers (`styleProp`, `slot`) narrow against the
+ *    component's own declared layers — typo'd layer names surface
+ *    at the authoring site instead of as silent no-ops at runtime.
+ *  - Authors can't reach for bare-string brace-refs; the helper
+ *    shape is the only path through.
+ *
+ * The `TLayers` parameter is inferred from the callback's return
+ * value (`layers: {...}`) via contextual typing — the helpers are
+ * typed against the same layer map the consumer is currently
+ * authoring.
+ */
+interface DefineHelpers<TLayers extends Record<string, LayerInput> = Record<string, LayerInput>> {
+  bool: () => BoolMarker;
+  string: () => StringMarker;
+  styleProp: <TRef extends string>(ref: TRef) => StylePropMarker<'root', TRef>;
+  slot: {
+    (): SlotMarker<'', 'children'>;
+    <const TPath extends string>(path: TPath): SlotMarker<SplitSlotPath<TPath>[0], SplitSlotPath<TPath>[1]>;
+    <const TLayer extends keyof TLayers & string, const TProp extends string>(layer: TLayer, options: {
+      prop: TProp;
+    }): SlotMarker<TLayer, TProp>;
+  };
+  enums: <const TValues extends Record<string, unknown>>(values: TValues) => EnumMarker<TValues>;
+  composite: typeof composite;
+  token: <TRef extends string>(ref: TRef) => TokenMarker<TRef>;
+  hidden: () => HiddenMarker;
+}
+/**
+ * Authoring-side metadata that drives the codegen-emitted AI prompt
+ * (`apps/<app>/.uds/react-prompt.ts`) and any future doc tooling.
+ *
+ * Authored via the chainable `.metadata({...})` on a bound component:
+ *
+ *     const Grid = defineComponent('div', { ... }).metadata({
+ *       description: 'CSS grid container — pair with `<GridItem>` ...',
+ *       acceptsChildren: true,
+ *     });
+ *
+ * Stored as a non-enumerable slot on the component's `__config` so
+ * `JSON.stringify(config)` still round-trips clean. Codegen's
+ * `synthesizeComponentExportInfo` reads from this map to populate
+ * `description`, `acceptsChildren`, and `events` on the catalog entry
+ * the prompt generator iterates.
+ *
+ * All fields are optional — unset fields read `undefined` and the
+ * prompt-generator falls back to its existing defaults (event list,
+ * children-detection from layer shape, etc.).
+ */
+interface ComponentMetadata {
+  /**
+   * Short human-readable summary the AI prompt shows next to the
+   * component name. Plain prose — no markdown.
+   */
+  readonly description?: string;
+  /**
+   * React/HTML event handler names the component supports
+   * (`'focus'`, `'press'`, etc.). The prompt's `[events: ...]` tag
+   * lists these. When unset, the synthesizer falls back to the
+   * standard React event roster for primitives.
+   *
+   * `acceptsChildren` is intentionally NOT a field here — the
+   * synthesizer derives it from the config shape (primitive +
+   * value-extend forms always accept children; verbose form derives
+   * from `ForwardBinding { from: 'children' }` presence).
+   */
+  readonly events?: readonly string[];
+}
 /**
  * A React component bound to a `defineComponent` config, with the
  * source config attached as a phantom type slot. Tools (codegen,
  * devtools) recover the config at runtime via the non-enumerable
  * `__config` property; the type slot lets consumers read it at the
  * type level too — `Props<typeof Box['__config']>`.
+ *
+ * The runtime value also carries a chainable `.metadata({...})`
+ * method (typed via `BoundComponentWithBuilder` at definition sites).
+ * Calling it returns a NEW bound component value with the metadata
+ * attached non-enumerably to its `__config`.
  */
-type BoundComponent<TConfig extends ComponentConfigValue<Record<string, LayerInput>, any, HtmlTag | undefined>, TExtra extends Record<string, unknown> = {}> = React.FC<Props<TConfig> & TExtra> & {
+type BoundComponent<TConfig extends ComponentConfigValue<Record<string, LayerInput>, any, HtmlTag | undefined>, TExtra extends Record<string, unknown> = {}> = React.FC<Omit<Props<TConfig>, keyof TExtra> & TExtra> & {
   readonly __config: TConfig;
+  /**
+   * The user-authored render function attached to verbose-form
+   * (`.render(fn)`) bound components. Codegen's downleveled
+   * `#uds/components` emitter reads this so it can call the render
+   * fn directly with pre-resolved per-layer bundles, instead of
+   * routing through the runtime `bindRender` closure.
+   *
+   * Non-enumerable at runtime. Absent on primitive-form components
+   * (`defineComponent('div', {...})`) and on value-extend-form
+   * components (`defineComponent(Box, {...})`) — those have an
+   * auto-generated render fn that the downleveler doesn't need to
+   * import; their config alone is enough to emit a working FC.
+   */
+  readonly __renderFn?: (args: any) => React.ReactNode;
+  /**
+   * Chainable: attach authoring metadata (`description`,
+   * `acceptsChildren`, `events`) read by codegen's prompt + catalog
+   * generators. Mutates the underlying config's `metadata` slot
+   * non-enumerably and returns the same bound-component value:
+   *
+   *     export const Grid = defineComponent('div', { ... }).metadata({
+   *       description: 'CSS grid container ...',
+   *       acceptsChildren: true,
+   *     });
+   *
+   * The return type is intentionally widened to a permissive
+   * bound-component shape so the recursive `BoundComponent<TConfig>`
+   * referenced inside `metadata`'s signature doesn't cause variance
+   * issues at consumer call sites (`registerComponents` accepts
+   * `BoundComponent<any, any>` and is fine with the looser shape).
+   * For tooling that needs the precise `__config`, read it off the
+   * pre-`.metadata()` value or off `(Grid as any).__config`.
+   */
+  metadata(meta: ComponentMetadata): // biome-ignore lint/suspicious/noExplicitAny: see docblock — loose return to avoid recursive-variance issues
+  React.FC<any> & {
+    readonly __config: ComponentConfigValue<any, any, any>;
+  };
 };
 /**
  * A `defineComponent({...})` config value with a `.render(fn)` builder
@@ -20,5 +137,181 @@ type BoundComponent<TConfig extends ComponentConfigValue<Record<string, LayerInp
  * still produces pure data — codegen can read `__kind`, `layers`,
  * `props`, and `defaultProps` without seeing the render hook.
  */
+interface DefinedComponent<TLayers extends Record<string, LayerInput>, TProps extends Record<string, VerbosePropBinding>> extends ComponentConfigValue<TLayers, TProps, RootTag<TLayers>> {
+  /**
+   * Bind this config to a React render function and produce a component.
+   * The render fn receives `{ props, children, ...rest }` where
+   * `props.<layer>` is the computed bundle for that layer.
+   *
+   * Pass `TExtra` to declare custom JSX props the render fn consumes
+   * (event handlers, controlled state, etc.) that aren't part of the
+   * style/layer config. The args type widens to include `TExtra`, and
+   * the resulting component's Props become `Props<TConfig> & TExtra`.
+   *
+   * @example
+   *     defineComponent({
+   *       layers: { root: 'div' },
+   *     }).render<{ onDismiss?: () => void; loading?: boolean }>(
+   *       ({ props, onDismiss, loading }) => (...)
+   *     );
+   */
+  render<TExtra extends Record<string, unknown> = {}>(fn: (args: CreateComponentRenderArgs<TLayers> & SlotPropsFromConfig<TProps> & TExtra) => ReactNode): BoundComponent<ComponentConfigValue<TLayers, TProps, RootTag<TLayers>>, TExtra>;
+}
+/**
+ * Per-config slot-prop map: walk the `props` block, pick out every
+ * `slot()`-marked entry, and surface it as `ReactNode | undefined` on
+ * the render-fn args. The render fn can conditionally use the value
+ * (`title ? <Text>...</Text> : null`); the runtime *also* routes the
+ * value into the matching layer's bundle (`props.<layer>.children`)
+ * so the typical render-fn shape (`<Text {...props.title} />`) keeps
+ * working without manual wiring.
+ */
+type SlotPropsFromConfig<TProps> = { [K in keyof TProps as TProps[K] extends {
+  readonly __kind: 'slot';
+} ? K : never]?: ReactNode };
+/**
+ * Single-layer config used by the primitive form. No `layers` key
+ * (the root tag comes from the first arg). `props` entries use
+ * `styleProp(ref)` markers that target the implicit root layer.
+ */
+interface PrimitiveComponentInput<TProps extends Record<string, PrimitivePropBinding>> {
+  props?: TProps;
+  defaultProps?: Record<string, unknown>;
+}
+/**
+ * Single-layer config used by the **value-extend form**
+ * (`defineComponent(Box, { defaultProps: {...} })`). The wrapped
+ * component is passed in directly as a `BoundComponent` value (its
+ * `__config` carries the parent's props + tag); `defaultProps` is
+ * narrowed against the parent's exposed prop surface and merged
+ * underneath the wrapper's JSX-site props at render time.
+ *
+ * Replaces the deprecated `'{Name}'` brace-ref syntax. The brace-ref
+ * relied on a module-level runtime registry to resolve the parent
+ * component by name; the value-import form eliminates that
+ * indirection — the parent is a regular import, the bundler tree-
+ * shakes it normally, and there is no registry lookup at render time.
+ *
+ * `TAs` is captured from the literal `defaultProps.as` value when set
+ * (`{ as: 'button' }` → `TAs = 'button'`). The value-extend
+ * overload threads this through as the synthesized config's TTag slot
+ * so `Props<typeof Pressable['__config']>` resolves to
+ * `ComponentPropsWithRef<'button'>` (button-specific HTML attrs land
+ * on the JSX type) without any manual `Pick<ButtonHTMLAttributes,
+ * 'type' | 'disabled' | ...>` shim at the call site.
+ */
+interface ExtendComponentInput<TParentConfig extends ComponentConfigValue<any, any, any>, TAs extends keyof JSX.IntrinsicElements & string> {
+  /**
+   * Additional prop bindings layered on top of the parent's bindings.
+   * Same shape as primitive form's `props`.
+   */
+  props?: Record<string, PrimitivePropBinding>;
+  /**
+   * Default values for the parent's JSX-prop surface PLUS any extra
+   * wrapper-declared props (the keys in `this.props`). Defaults to
+   * `Partial<Props<TParentConfig>>` here; the function overload
+   * tightens the type to also include the wrapper's `TExtraProps`
+   * key set so e.g. `Anchor`'s `defaultProps: { variant: 'body' }`
+   * typechecks against the `composite('textVariant')` binding the
+   * same `config.props` block declares.
+   *
+   * The `as` slot is the polymorphic-element override the runtime /
+   * auto-render reads to switch the rendered tag.
+   */
+  defaultProps?: Partial<Omit<Props<TParentConfig>, 'as'>> & {
+    as?: TAs;
+    [key: string]: any;
+  };
+}
+/**
+ * Value-extend form — `defineComponent(Box, { defaultProps: {...} })`.
+ *
+ * Takes another `defineComponent` value as the first argument and
+ * produces a new bound component whose config is the parent's config
+ * flattened with the wrapper's options merged in:
+ *
+ *   - `layers` and `props` carry over from the parent (so VStack
+ *     accepts all of Box's style props).
+ *   - `defaultProps` becomes `{ ...parent.defaultProps, ...input.defaultProps }`.
+ *   - `defaultProps.as` (when set as a literal) becomes the synthesized
+ *     config's TTag slot so JSX-site element attrs narrow accordingly
+ *     (`<Pressable type="button" disabled>` picks up button HTML attrs).
+ *
+ * No runtime registry lookup: the parent is a normal imported value
+ * the bundler tree-shakes alongside the wrapper. Replaces the
+ * deprecated `'{Name}'` brace-ref form.
+ */
+declare function defineComponent<TParentConfig extends ComponentConfigValue<any, any, any>, const TAs extends keyof JSX.IntrinsicElements & string = 'div', const TExtraProps extends Record<string, PrimitivePropBinding> = {}>(parent: BoundComponent<TParentConfig>, config?: ExtendComponentInput<TParentConfig, TAs> & {
+  props?: TExtraProps;
+}): BoundComponent<ComponentConfigValue<TParentConfig['layers'], Omit<Exclude<TParentConfig['props'], undefined>, keyof TExtraProps> & TExtraProps, TAs>> & {
+  /**
+   * Attach wrapper-side defaults / extra props via a helper-driven
+   * callback. Returns a fresh bound component carrying the merged
+   * config.
+   */
+  config<const TAs2 extends keyof JSX.IntrinsicElements & string = 'div', const TExtraProps2 extends Record<string, VerbosePropBinding> = {}>(cb: (h: DefineHelpers) => ExtendComponentInput<TParentConfig, TAs2> & {
+    props?: TExtraProps2;
+  }): BoundComponent<ComponentConfigValue<TParentConfig['layers'], Omit<Exclude<TParentConfig['props'], undefined>, keyof TExtraProps2> & TExtraProps2, TAs2>>;
+};
+/**
+ * Primitive shorthand — `defineComponent('div', { props: {...} })`.
+ *
+ * The returned bound component also carries a `.config((h) => ({...}))`
+ * method so authors can declare style-prop bindings / default props
+ * fluently:
+ *
+ *     export const Spacer = defineComponent('div');
+ *     export const Box = defineComponent('div').config(({ styleProp }) => ({
+ *       props: { bg: styleProp('bg') },
+ *     }));
+ */
+declare function defineComponent<const TTag extends HtmlTag, const TProps extends Record<string, PrimitivePropBinding> = {}>(tag: TTag, config?: PrimitiveComponentInput<TProps>): BoundComponent<ComponentConfigValue<{
+  root: TTag;
+}, TProps, TTag>> & {
+  config<const TProps2 extends Record<string, VerbosePropBinding<{
+    root: TTag;
+  }>> = {}>(cb: (h: DefineHelpers<{
+    root: TTag;
+  }>) => PrimitiveComponentInput<TProps2>): BoundComponent<ComponentConfigValue<{
+    root: TTag;
+  }, TProps2, TTag>>;
+};
+/**
+ * Verbose form — `defineComponent({ layers, props, defaultProps })`.
+ * Returns the pure-data config value with a `.render(fn)` builder.
+ */
+declare function defineComponent<const TLayers extends Record<string, LayerInput>, const TProps extends Record<string, VerbosePropBinding<TLayers>> = {}>(config: ComponentConfigInput<TLayers, TProps>): DefinedComponent<TLayers, TProps>;
+/**
+ * Two-step authoring API for multi-layer components: declare layers
+ * up-front so the `.config((h) => ({...}))` callback's helpers can
+ * narrow against the declared layer keys.
+ *
+ *     defineComponent
+ *       .layers({ root: 'div', label: 'strong' })
+ *       .config(({ slot, styleProp, token, bool, enums }) => ({
+ *         props: {
+ *           title: slot('label/children'),    // 'label' narrows
+ *           bg:    styleProp('bg').on('root'),
+ *           loading: bool(),
+ *         },
+ *         base: { root: { bg: token('bg/brand') } },
+ *         defaultProps: { loading: false },
+ *       }))
+ *       .render(({ props }) => ...);   // optional
+ *
+ * Single-layer primitive and value-extend components use the direct
+ * call form: `defineComponent('div').config(...)` and
+ * `defineComponent(Parent).config(...)`. Only multi-layer authoring
+ * goes through `defineComponent.layers({...})`.
+ */
+declare namespace defineComponent {
+  /**
+   * `defineComponent.layers({...})` — first step of the multi-layer
+   * builder. Returns an object with a `.config((h) => ({...}))` method.
+   */
+  function layers<const TLayers extends Record<string, LayerInput>>(layersMap: TLayers): {
+    config<const TProps extends Record<string, VerbosePropBinding<TLayers>> = {}>(cb: (h: DefineHelpers<TLayers>) => Omit<ComponentConfigInput<TLayers, TProps>, 'layers'>): DefinedComponent<TLayers, TProps>;
+  };
+} //#endregion
 //#endregion
-export { BoundComponent };
+export { BoundComponent, DefineHelpers, DefinedComponent, PrimitiveComponentInput, defineComponent };

package/dist/config/dist/defineComponent.js

@@ -1,2 +1,264 @@
-import "./createComponent.js";
-import "react";
+import { bool, composite, enums, hidden, slot, string, styleProp, token } from "./component-config.js";
+import { bindRender } from "./bindRender.js";
+import { createElement } from "react";
+//#region ../config/dist/defineComponent.js
+/**
+* `defineComponent(...)` — author a component config.
+*
+* Three call shapes:
+*
+* **1. Primitive** — first arg is an HTML tag string. The returned
+*    value is a working bound component (auto-rendered) with a
+*    chainable `.config((h) => ({...}))` for declaring style-prop
+*    bindings + default props:
+*
+*        export const Spacer = defineComponent('div');
+*        export const Box = defineComponent('div').config(({ styleProp }) => ({
+*          props: { bg: styleProp('bg'), padding: styleProp('spacing') },
+*        }));
+*
+* **2. Value-extend** — first arg is another `defineComponent`-produced
+*    bound component. Inherits the parent's layers + prop surface; chain
+*    `.config((h) => ({...}))` to merge wrapper-side defaults / extra
+*    props:
+*
+*        export const Pressable = defineComponent(Box).config(() => ({
+*          defaultProps: { as: 'button' },
+*        }));
+*
+* **3. Multi-layer** — `defineComponent.layers({...}).config(({ ... }) => ({...}))`.
+*    Returns a pure-data config value with a chainable `.render(fn)`
+*    method that binds the config to a React render function. Helpers
+*    narrow against the declared layer keys:
+*
+*        export const Alert = defineComponent
+*          .layers({ root: 'div', label: 'strong' })
+*          .config(({ slot, enums }) => ({
+*            props: {
+*              children: slot('label/children'),
+*              severity: enums({ info: {…}, warning: {…} }),
+*            },
+*          }))
+*          .render(({ props }) => (
+*            <div {...props.root}>
+*              <strong {...props.label} />
+*            </div>
+*          ));
+*
+*    A slot binding routes its incoming JSX value onto the named layer's
+*    bundle — the render fn just spreads the bundle; no manual
+*    `{children}` re-placement.
+*
+*    Need custom non-config props (event handlers, controlled state)?
+*    Declare them via the `.render<TExtra>(fn)` generic. The render fn
+*    args widen to include `TExtra`; the component's Props become
+*    `Props<TConfig> & TExtra`:
+*
+*        export const Alert = defineComponent
+*          .layers({ root: 'div', label: 'strong' })
+*          .config(({ slot }) => ({
+*            props: { children: slot('label/children') },
+*          }))
+*          .render<{ onDismiss?: () => void; loading?: boolean }>(
+*            ({ props, onDismiss, loading }) => (
+*              <div {...props.root}>
+*                <strong {...props.label} />
+*                {onDismiss && <button onClick={onDismiss}>×</button>}
+*              </div>
+*            ),
+*          );
+*
+* The component's name is *not* part of any shape — it's supplied by
+* the key the consumer uses in `.registerComponents({ Alert })`,
+* mirroring how `defineStyleProp({...})` is keyed by
+* `.registerStyleProps({ bg })`.
+*
+* The returned value carries `layers`, `props`, and the root-tag literal
+* as const-narrowed types so downstream `import type { AlertConfig }`
+* threads the full shape through to `Props<typeof config>`.
+*/
+const HELPERS = {
+	bool,
+	string,
+	styleProp,
+	slot,
+	enums,
+	composite,
+	token,
+	hidden
+};
+function defineComponent(tagOrConfigOrParent, optionsOrConfig) {
+	if (typeof tagOrConfigOrParent === "function" && "__config" in tagOrConfigOrParent) {
+		const parentConfig = tagOrConfigOrParent.__config;
+		const input = optionsOrConfig;
+		const parentDefaults = parentConfig.defaultProps;
+		const inputDefaults = input?.defaultProps;
+		const mergedDefaults = parentDefaults || inputDefaults ? {
+			...parentDefaults ?? {},
+			...inputDefaults ?? {}
+		} : void 0;
+		const mergedProps = parentConfig.props || input?.props ? {
+			...parentConfig.props ?? {},
+			...input?.props ?? {}
+		} : void 0;
+		const synthesized = {
+			__kind: "componentConfig",
+			layers: parentConfig.layers,
+			props: mergedProps,
+			defaultProps: mergedDefaults
+		};
+		Object.defineProperty(synthesized, "__parentConfig", {
+			enumerable: false,
+			configurable: true,
+			writable: true,
+			value: parentConfig
+		});
+		const parentRoot = parentConfig.layers.root;
+		const inferredTag = typeof parentRoot === "string" ? parentRoot : typeof parentRoot === "object" && parentRoot !== null && "tag" in parentRoot ? parentRoot.tag : "div";
+		const autoRender = (args) => {
+			const { props, children, as, ...rest } = args;
+			const rootBundle = props.root;
+			const merged = {
+				...rootBundle,
+				...rest,
+				children: rootBundle.children ?? children
+			};
+			return createElement(as ?? inferredTag, merged);
+		};
+		const Component = bindRender(synthesized, autoRender);
+		attachConfig(Component, synthesized);
+		attachExtendConfig(Component, parentConfig);
+		return Component;
+	}
+	if (typeof tagOrConfigOrParent === "string") {
+		const tag = tagOrConfigOrParent;
+		const primitiveInput = optionsOrConfig;
+		const synthesized = {
+			__kind: "componentConfig",
+			layers: { root: tag },
+			props: primitiveInput?.props,
+			defaultProps: primitiveInput?.defaultProps
+		};
+		const autoRender = (args) => {
+			const { props, children, as, ...rest } = args;
+			const rootBundle = props.root;
+			const merged = {
+				...rootBundle,
+				...rest,
+				children: rootBundle.children ?? children
+			};
+			return createElement(as ?? tag, merged);
+		};
+		const Component = bindRender(synthesized, autoRender);
+		attachConfig(Component, synthesized);
+		attachPrimitiveConfig(Component, tag);
+		return Component;
+	}
+	const config = {
+		__kind: "componentConfig",
+		layers: tagOrConfigOrParent.layers,
+		props: tagOrConfigOrParent.props,
+		base: tagOrConfigOrParent.base,
+		motion: tagOrConfigOrParent.motion,
+		defaultProps: tagOrConfigOrParent.defaultProps,
+		compoundProps: tagOrConfigOrParent.compoundProps
+	};
+	Object.defineProperty(config, "render", {
+		enumerable: false,
+		value: function render(fn) {
+			const Component = bindRender(config, fn);
+			attachConfig(Component, config);
+			Object.defineProperty(Component, "__renderFn", {
+				enumerable: false,
+				value: fn
+			});
+			Object.defineProperty(config, "__hasRenderFn", {
+				enumerable: false,
+				value: true
+			});
+			return Component;
+		}
+	});
+	return config;
+}
+/**
+* Attach the underlying config + the chainable `.metadata({...})`
+* method to a bound component. Both slots are non-enumerable so
+* tooling (codegen, devtools) can recover the source shape without
+* polluting JSX prop spreads or `JSON.stringify` output.
+*
+* `.metadata(meta)` produces a fresh bound component whose `__config`
+* carries the metadata under a non-enumerable `metadata` slot. The
+* synthesized config object is shared by reference (mutation isolates
+* to the metadata slot via `Object.defineProperty`), so reads from the
+* original Component still see the new metadata once attached — useful
+* for downstream tooling that walks the registered map after
+* authoring.
+*/
+function attachConfig(Component, config) {
+	Object.defineProperty(Component, "__config", {
+		enumerable: false,
+		value: config
+	});
+	Object.defineProperty(Component, "metadata", {
+		enumerable: false,
+		value: (meta) => {
+			Object.defineProperty(config, "metadata", {
+				enumerable: false,
+				configurable: true,
+				writable: true,
+				value: meta
+			});
+			return Component;
+		}
+	});
+}
+/**
+* Graft a `.config((h) => ({...}))` method onto a primitive-form bound
+* component. The method invokes the callback with the shared HELPERS
+* bag and re-runs `defineComponent(tag, config)` with the resolved
+* options, producing a fresh bound component with the new bindings.
+*/
+function attachPrimitiveConfig(Component, tag) {
+	Object.defineProperty(Component, "config", {
+		enumerable: false,
+		value: (cb) => {
+			const config = cb(HELPERS);
+			return defineComponent(tag, config);
+		}
+	});
+}
+/**
+* Graft a `.config((h) => ({...}))` method onto a value-extend bound
+* component. Same shape as `attachPrimitiveConfig` but routes through
+* the value-extend overload so wrapper-side `defaultProps` / extra
+* `props` flow into the synthesized config.
+*/
+function attachExtendConfig(Component, parentConfig) {
+	Object.defineProperty(Component, "config", {
+		enumerable: false,
+		value: (cb) => {
+			const config = cb(HELPERS);
+			const parentShell = (() => null);
+			Object.defineProperty(parentShell, "__config", {
+				enumerable: false,
+				value: parentConfig
+			});
+			return defineComponent(parentShell, config);
+		}
+	});
+}
+(function(_defineComponent) {
+	function layers(layersMap) {
+		return { config(cb) {
+			const rest = cb(HELPERS);
+			return defineComponent({
+				layers: layersMap,
+				...rest
+			});
+		} };
+	}
+	_defineComponent.layers = layers;
+})(defineComponent || (defineComponent = {}));
+//#endregion
+export { defineComponent };

package/dist/config/dist/defineCompositeStyle.d.ts

@@ -0,0 +1,93 @@
+//#region ../config/dist/defineCompositeStyle.d.ts
+//#region src/defineCompositeStyle.d.ts
+/**
+ * `defineCompositeStyle(...)` — author a single composite style.
+ *
+ * Mirrors the factory + registry pattern used by `defineStyleProp` +
+ * `.registerStyleProps({...})` and `defineComponent` + `.registerComponents({...})`.
+ * One composite per file is the canonical authoring shape; consumers
+ * import the value and pass it to `.registerComposites({...})` on the
+ * UDS builder.
+ *
+ *     // packages/.../text-variant.ts
+ *     export const textVariant = defineCompositeStyle({
+ *       label: 'Text Variant',
+ *       description: 'Typography presets',
+ *       styles: {
+ *         heading1: { fontSize: '[2.5rem]', fontWeight: 'bold' },
+ *         body:     { fontSize: 'base',     fontWeight: 'normal' },
+ *       },
+ *     });
+ *
+ *     // apps/<consumer>/uds.config.ts
+ *     udsBuilder.registerComposites({ textVariant });
+ *
+ * The returned value is pure data with a `__kind: 'compositeStyle'`
+ * brand so the builder's `.registerComposites` can distinguish it from
+ * a plain object. `.metadata({...})` is a no-op stub for now — symmetry
+ * with `defineStyleProp`'s chain — and can grow new fields without
+ * breaking the surface.
+ *
+ * Authors reference tokens via the `token('namespace/name')` helper,
+ * write inline CSS literals (`'1rem'`, `'450'`), or opt into arbitrary
+ * values with the `'[2.5rem]'` bracket syntax. The resolver walks
+ * each entry at registration time and emits the matching style-prop
+ * declarations into the composite's `@utility` block.
+ */
+/**
+ * One entry inside a composite's `styles[variantId]` map — a bag of
+ * style-prop keys to values. Values are `TokenMarker` instances from
+ * `token('ns/name')`, inline CSS literals, or arbitrary-value brackets
+ * (`'[2.5rem]'`); the resolver expands them like any style-prop value
+ * at registration time.
+ */
+interface CompositeStyleObject {
+  [styleProp: string]: unknown;
+}
+/**
+ * The shape `defineCompositeStyle({...})` accepts and the resolver
+ * stores under `config.compositeStyles[<name>]`. Each entry exposes a
+ * `<name>` JSX prop on components whose values are the keys of `styles`.
+ */
+interface CompositeStyleDef {
+  /** Human-readable display name surfaced in Studio. */
+  label: string;
+  /** Optional long-form description surfaced in Studio. */
+  description?: string;
+  /** Variant id -> style bag. Variant ids become JSX prop values. */
+  styles: Record<string, CompositeStyleObject>;
+}
+type CompositeStylesConfig = Record<string, CompositeStyleDef>;
+/**
+ * Branded composite-style value returned by `defineCompositeStyle`.
+ * Adds a `__kind` brand so the builder can distinguish factory-authored
+ * composites from plain object literals.
+ */
+interface DefinedCompositeStyle extends CompositeStyleDef {
+  readonly __kind: 'compositeStyle';
+}
+/**
+ * Compile-time shape input to `defineCompositeStyle`. Carries a
+ * `label`, an optional `description`, and a `styles` map keyed by
+ * variant id.
+ *
+ * `styles[variantId]` is a `CompositeStyleObject` (one style-prop key
+ * → one value); values are `TokenMarker` instances from
+ * `token('ns/name')`, inline CSS literals (`'1rem'`), or arbitrary
+ * brackets (`'[2.5rem]'`).
+ */
+interface CompositeStyleInput {
+  label: string;
+  description?: string;
+  styles: Record<string, CompositeStyleObject>;
+}
+/**
+ * Author a composite style. Returns a branded value the consumer
+ * passes to `.registerComposites({...})` on the UDS builder.
+ *
+ * Pure — no global registration happens here; the builder's
+ * `.registerComposites({...})` is the registration step.
+ */
+declare function defineCompositeStyle(input: CompositeStyleInput): DefinedCompositeStyle; //#endregion
+//#endregion
+export { CompositeStyleDef, CompositeStyleInput, CompositeStyleObject, CompositeStylesConfig, DefinedCompositeStyle, defineCompositeStyle };