@yahoo/uds-v5-wip 1.37.1 → 1.39.0

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

@@ -0,0 +1,74 @@
+import { RegisteredStyleProps } from "./component-refs.js";
+import { ComponentConfigValue, HtmlTag, LayerInput, PropBinding } from "./component-config.js";
+import { ComponentPropsWithoutRef, HTMLAttributes, JSX } from "react";
+
+//#region ../config/dist/Props.d.ts
+//#region src/Props.d.ts
+/**
+ * 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.).
+ *  - 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>;
+/**
+ * Resolve the allowed-value union for one registered style prop.
+ * Falls back to `string` when the prop registered no tokens (codegen
+ * emits `never` for that case).
+ */
+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'`
+ * 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}}`;
+} ? N extends keyof RegisteredStyleProps & string ? N : never : never;
+/**
+ * Walk the config's `props` block and produce one optional JSX prop
+ * per entry.
+ */
+type PropsFromConfig<TProps> = { [K in keyof TProps]?: StylePropRefName<TProps[K]> extends never ? unknown : 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}' }>`).
+ */
+type Prettify<T> = { [K in keyof T]: T[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
+ * we add one here — keeps `<Box data-test="x" />` valid without forcing
+ * authors to register every test attribute as a config-declared prop.
+ */
+interface DataAttrs {
+  [key: `data-${string}`]: unknown;
+}
+/**
+ * Public derived-props type.
+ *
+ * Four layers:
+ *  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).
+ */
+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;
+/**
+ * `Props<typeof boxConfig>` for the common 'use the config's inferred
+ * type' invocation. Keeps `box.tsx` from having to repeat the generic.
+ */
+//#endregion
+export { Props };

package/dist/config/dist/component-config.d.ts

@@ -0,0 +1,201 @@
+import { ComponentRef, CompositeRef, RegisteredComponents, StylePropRef } from "./component-refs.js";
+import { ReactNode } from "react";
+
+//#region ../config/dist/component-config.d.ts
+//#region src/component-config.d.ts
+/**
+ * HTML tag literal. The TypeScript type is `string` (any tag name);
+ * runtime renders it via `React.createElement(tag, ...)`.
+ *
+ * Kept as `string` instead of `keyof JSX.IntrinsicElements` so the type
+ * doesn't pull a 200-key union into every layer position. Editors still
+ * autocomplete tag names from JSX.
+ */
+type HtmlTag = string;
+/**
+ * Object form for a primitive (HTML-tag) layer that needs locked attrs
+ * or default CSS-property values.
+ */
+interface PrimitiveLayer {
+  tag: HtmlTag;
+  /** HTML attributes always applied to this layer (e.g. `role="alert"`). */
+  attrs?: Record<string, unknown>;
+  /** Default style-prop values for this layer. */
+  defaultProps?: Record<string, unknown>;
+}
+/**
+ * Object form for a layer that's a composed React component (registered
+ * via `.registerComponents({...})`). The `component` field is a brace-ref
+ * narrowed against `RegisteredComponents`. `defaultProps` is narrowed
+ * per-component so authors can only pass props the referenced component
+ * actually accepts.
+ *
+ * Codegen emits `RegisteredComponents[K]` as the component's resolved
+ * prop shape (e.g. `{ backgroundColor: RegisteredStyleProps['bg']; … }`).
+ * `Partial<RegisteredComponents[K]>` lets `defaultProps` narrow against
+ * that shape. Without registered components, the union is `never` (so
+ * package-internal authoring sites don't have to deal with this shape).
+ */
+type ComposedLayer = { [K in keyof RegisteredComponents & string]: {
+  component: `{${K}}`;
+  defaultProps?: Partial<RegisteredComponents[K]>;
+} }[keyof RegisteredComponents & string];
+/**
+ * Allowed forms for a single layer's value. Authors usually pick the
+ * shorthand (a bare tag string or a brace-ref); the object forms exist
+ * for the cases that need `attrs` or `defaultProps`.
+ */
+type LayerInput = HtmlTag | ComponentRef | PrimitiveLayer | ComposedLayer;
+/**
+ * Bind a registered style prop to a specific layer. The style prop's
+ * resolved class name is added to that layer's `className` bundle at
+ * render time.
+ *
+ * `styleProp` is narrowed against `RegisteredStyleProps`. `layer` is a
+ * string at this level — the consuming type (`ComponentConfig.props`)
+ * narrows it against the component's own `layers` keys.
+ */
+interface StylePropBinding {
+  layer: string;
+  styleProp: StylePropRef;
+}
+/**
+ * Extract the root tag literal from a `layers` map when it can be read
+ * statically. Returns the string literal `'a' | 'div' | …` when:
+ *
+ *  - `layers.root` is a bare tag string (`'a'`), or
+ *  - `layers.root` is `{ tag: 'a', attrs?: … }`.
+ *
+ * Returns `undefined` when `layers.root` is a brace-ref (`'{Box}'`), a
+ * `{ component: '{Box}' }` form, or not present. `Props<TConfig>` reads
+ * this and substitutes `React.ComponentPropsWithoutRef<TTag>` for the
+ * generic `HTMLAttributes<HTMLElement>` when narrowable.
+ */
+type RootTag<TLayers> = TLayers extends {
+  root: infer R;
+} ? R extends HtmlTag ? R extends `{${string}}` ? undefined : R : R extends {
+  tag: infer T extends HtmlTag;
+} ? T : undefined : undefined;
+/**
+ * Bind a registered composite to a single layer. Multi-layer composites
+ * use the `CompositeBinding` shape instead (see below).
+ */
+interface SingleLayerCompositeBinding {
+  layer: string;
+  composite: CompositeRef;
+}
+/**
+ * Multi-layer composite binding — explicit composite-layer → component-
+ * layer mapping. The composite declares its own internal layer names
+ * (`default`, `label`, …) and this binding tells the framework which
+ * component layer each one maps to.
+ */
+interface CompositeBinding {
+  composite: CompositeRef;
+  layers: Record<string, string>;
+}
+/**
+ * Forward an existing surface key from one of the component's layers as
+ * a public JSX prop. If the target layer is a primitive, `from` is an
+ * HTML attr / event name; if it's a composed component, `from` is one
+ * of that component's existing props.
+ *
+ * `from` is a bare string (no braces) — the leading-brace check on the
+ * binding shape's `from` is how the framework dispatches "bind a
+ * registered thing" vs "forward an existing surface key".
+ */
+interface SurfaceForward {
+  layer: string;
+  from: string;
+}
+/**
+ * Boolean prop — toggled on/off, no value beyond presence. Useful for
+ * `loading`, `disabled`, `selected`. Each layer's bundle gets a
+ * data-attribute (`data-loading="true"`) the consumer can target.
+ */
+interface BoolMarker {
+  readonly __kind: 'bool';
+}
+/**
+ * Enum prop — the value picks one entry from a map. Each entry can
+ * declare per-layer style overrides. Mirrors today's `variants.X`
+ * surface but co-located with other prop bindings.
+ */
+interface EnumMarker<TValues extends Record<string, unknown>> {
+  readonly __kind: 'enum';
+  readonly values: TValues;
+}
+/**
+ * Shorthand binding form — a brace-ref string standing in for the
+ * verbose object. `'{bg}'` means "bind the registered style prop `bg`
+ * to the *root* layer".
+ *
+ * Only legal in the primitive form `defineComponent('div', { props: { bg: '{bg}' } })`,
+ * where the root layer is unambiguous. In the verbose form
+ * `defineComponent({ layers: {...}, props: {...} })` authors must use
+ * the explicit long-form `{ layer, styleProp: '{bg}' }` binding so
+ * the target layer is named at the call site.
+ */
+type StylePropShorthand = StylePropRef;
+/**
+ * All allowed shapes for a single entry in the verbose form's `props`
+ * block. Verbose form (with explicit `layers`) requires the long-form
+ * `{ layer, styleProp }` binding — no shorthand. The shorthand
+ * `'{bg}'` is allowed only in the primitive form's props (see
+ * `PrimitivePropBinding`).
+ */
+type VerbosePropBinding = StylePropBinding | SingleLayerCompositeBinding | CompositeBinding | SurfaceForward | BoolMarker | EnumMarker<any>;
+/**
+ * All allowed shapes for a single entry in the primitive form's `props`
+ * block. Primitive form adds the `StylePropShorthand` brace-ref
+ * (`'{bg}'`) on top of every verbose form — the root layer is
+ * unambiguous so the shorthand resolves trivially.
+ */
+type PrimitivePropBinding = StylePropShorthand | VerbosePropBinding;
+/**
+ * Union of every legal prop-binding shape across both forms. Read-side
+ * helpers (`Props<TConfig>`, runtime resolution) accept this widest
+ * union; authoring-side input types (`ComponentConfigInput`) take the
+ * tighter `VerbosePropBinding`.
+ */
+type PropBinding = PrimitivePropBinding;
+/**
+ * Marker for a boolean JSX prop. Use inside the `props` block:
+ *
+ *     props: {
+ *       loading: bool(),
+ *       disabled: bool(),
+ *     }
+ */
+/**
+ * Branded shape returned by `defineComponent({...})`. Carries `layers`,
+ * `props`, AND a phantom `__tag` slot as const-narrowed types so
+ * downstream type-only imports (`import type { AlertConfig } from
+ * './alert.config'`) thread the full shape through to
+ * `Props<typeof config>` — per-prop literal binding values (e.g.
+ * `'{bg}'`) survive for `Props<TConfig>` to resolve against
+ * `RegisteredStyleProps`, and the root tag survives for HTML-attribute
+ * narrowing via `React.ComponentPropsWithoutRef<TTag>`.
+ *
+ * `__tag` is a *phantom* type slot — there is no runtime field. It's
+ * derived from either the primitive-form first arg (`defineComponent('a',
+ * …)`) or from `layers.root` via `RootTag<TLayers>` for the verbose form.
+ * When the root isn't a literal tag (brace-ref / composed layer), it's
+ * `undefined` and `Props<TConfig>` falls back to `HTMLAttributes<HTMLElement>`.
+ *
+ * The component's name is supplied at registration time, not here.
+ */
+interface ComponentConfigValue<TLayers extends Record<string, LayerInput>, TProps extends Record<string, PropBinding> = Record<string, PropBinding>, TTag extends HtmlTag | undefined = RootTag<TLayers>> {
+  readonly __kind: 'componentConfig';
+  readonly __tag?: TTag;
+  readonly layers: TLayers;
+  readonly props?: TProps;
+  readonly defaultProps?: Record<string, unknown>;
+}
+/**
+ * The bundle passed to the render function for each layer — a ready-to-
+ * spread object with `className` and any forwarded attrs. The render
+ * function destructures `props.<layerName>` into the JSX position.
+ */
+//#endregion
+export { BoolMarker, ComponentConfigValue, ComposedLayer, CompositeBinding, EnumMarker, HtmlTag, LayerInput, PrimitiveLayer, PrimitivePropBinding, PropBinding, RootTag, SingleLayerCompositeBinding, StylePropBinding, StylePropShorthand, SurfaceForward, VerbosePropBinding };

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

@@ -0,0 +1,98 @@
+//#region ../config/dist/component-refs.d.ts
+//#region src/component-refs.d.ts
+/**
+ * Augmentable registries + template-literal ref types for the
+ * component-API surface.
+ *
+ * Codegen runs `uds build` and populates the four interfaces below in
+ * each consumer app's `.uds/uds-env.d.ts`. The template-literal types
+ * derived from them narrow brace-ref strings against what's actually
+ * registered — `'{Box}'` typechecks only if `Box` is a real
+ * `RegisteredComponents` key, `'{bg}'` only if `bg` is a real
+ * `RegisteredStyleProps` key, etc.
+ *
+ * Without the augmentation loaded (e.g. inside `@uds/config`'s own
+ * test files), each registry is `{}` and the corresponding ref type
+ * collapses to `never`. Helpers downstream are expected to fail open
+ * in that case so package-internal authoring sites don't all error.
+ */
+/**
+ * Registered components. Each key is the component name (the brace-ref
+ * identifier — `'{Box}'`); each value is the component's resolved prop
+ * shape, e.g.
+ *
+ *     export interface RegisteredComponents {
+ *       Box2: {
+ *         backgroundColor: RegisteredStyleProps['bg'];
+ *         color: RegisteredStyleProps['color'];
+ *       };
+ *       Spinner: {};
+ *     }
+ *
+ * Composed layers use `Partial<RegisteredComponents[K]>` on
+ * `defaultProps` for type-safe completion when nesting components
+ * inside other components' configs.
+ *
+ * Populated by codegen from `uds.config.ts`'s `.registerComponents({...})`
+ * call.
+ */
+interface RegisteredComponents {}
+/**
+ * Registered style props. Key is the JSX prop name (the brace-ref
+ * identifier — `'{bg}'`); value is the string-literal union of
+ * allowed token names for that prop, e.g.
+ *
+ *     export interface RegisteredStyleProps {
+ *       bg: 'brand' | 'accent' | 'primary';
+ *       color: 'brand' | 'on-brand';
+ *     }
+ *
+ * Components reference these directly when wiring JSX-prop types:
+ * `bg?: RegisteredStyleProps['bg']`. Downstream `Props<TConfig>`
+ * resolves the shorthand `'{bg}'` against this map.
+ *
+ * Populated by codegen from `uds.config.ts`'s `.registerStyleProps({...})`
+ * call. A `never` value means the prop registered no tokens
+ * (arbitrary-only); the consumer should widen those to `string`.
+ */
+interface RegisteredStyleProps {}
+/**
+ * Registered composite-style names. Each key is the composite identifier
+ * (the brace-ref — `'{elevation}'`, `'{severity}'`); value is `void`.
+ *
+ * Populated by codegen from `uds.config.ts`'s `.registerComposites({...})`
+ * call.
+ */
+interface RegisteredComposites {}
+/**
+ * Registered motion-preset names. Each key is the preset identifier
+ * (`'{fadeIn}'`); value is `void`.
+ *
+ * Populated by codegen from `uds.config.ts`'s `.defineMotion({...})`
+ * (motion has no separate `.registerMotion` step today; the entries
+ * come directly from `defineMotion` keys).
+ */
+/**
+ * Brace-wrapped reference to a registered React component. Falls open
+ * to `'{${string}}'` when the registry is unaugmented (e.g. inside
+ * `@uds/config`'s own tests, where codegen hasn't populated the
+ * interface). Consumer apps load the codegen-emitted augmentation and
+ * get narrow `'{Box}' | '{Text}' | …` autocomplete.
+ */
+type ComponentRef = [keyof RegisteredComponents] extends [never] ? `{${string}}` : `{${Extract<keyof RegisteredComponents, string>}}`;
+/**
+ * Brace-wrapped reference to a registered style prop. Falls open when
+ * unaugmented (see {@link ComponentRef}).
+ */
+type StylePropRef = [keyof RegisteredStyleProps] extends [never] ? `{${string}}` : `{${Extract<keyof RegisteredStyleProps, string>}}`;
+/**
+ * Brace-wrapped reference to a registered composite style. Falls open
+ * when unaugmented.
+ */
+type CompositeRef = [keyof RegisteredComposites] extends [never] ? `{${string}}` : `{${Extract<keyof RegisteredComposites, string>}}`;
+/**
+ * Brace-wrapped reference to a registered motion preset. Falls open
+ * when unaugmented.
+ */
+//#endregion
+export { ComponentRef, CompositeRef, RegisteredComponents, RegisteredComposites, RegisteredStyleProps, StylePropRef };

package/dist/config/dist/component-resolution.d.ts

@@ -1 +1 @@
-import { ComponentsConfig } from "@uds/types";
+export { };

package/dist/config/dist/consts/defaultColors.d.ts

@@ -1,4 +1,5 @@
 //#region ../config/dist/consts/defaultColors.d.ts
+//#region src/consts/defaultColors.d.ts
 declare const defaultColors: {
   inherit: string;
   current: string;
@@ -247,6 +248,6 @@ declare const defaultColors: {
   'rose-800': string;
   'rose-900': string;
   'rose-950': string;
-};
+}; //#endregion
 //#endregion
 export { defaultColors };

package/dist/config/dist/createComponent.d.ts

@@ -0,0 +1 @@
+import { ReactNode } from "react";

package/dist/config/dist/createComponent.js

@@ -0,0 +1 @@
+import "react";

package/dist/config/dist/createConfig.d.ts

@@ -1,9 +1,12 @@
+import { ComponentConfigValue } from "./component-config.js";
+import { BoundComponent } from "./defineComponent.js";
 import { AnyStyleProp } from "./defineStyleProp.js";
-import { ResolvedStyleProp } from "./resolveStyleProp.js";
 import { TokenType, VarsConfig } from "./types.js";
+import { ResolvedStyleProp } from "./resolveStyleProp.js";
 import { BaseModifierProp, ComponentsConfig, CompositeStylesConfig, ConfigurableProp, ModifierProp, MotionPreset, RemotionComponentDef, RemotionConfig, RemotionTransitionDef } from "@uds/types";
 
 //#region ../config/dist/createConfig.d.ts
+//#region src/createConfig.d.ts
 type MotionPresetsDef = Record<string, MotionPreset>;
 type MotionAliasValue<TMotion> = TMotion extends Record<string, infer V> ? Extract<V, string> : never;
 type EmptyMotion = {};
@@ -76,6 +79,12 @@ type GetModifierFromInput<I extends ModesInput> = { [SetKey in keyof I]: { [OptK
 } ? M extends ModifierNameShape ? M : never : OptKey extends string ? `_${OptKey}` : never }[keyof I[SetKey]['options']] }[keyof I];
 /** Reject any input whose derived/explicit modifiers collide with reserved names. */
 type CheckForReservedModifiersInput<I extends ModesInput> = true extends HasReservedModifier<GetModifierFromInput<I>> ? 'ERROR: Cannot use reserved modifier names from ModifierProp. Please use a different modifier name.' : I;
+/**
+ * Convert the authored object-keyed input into the internal `ModeGroup[]` shape.
+ * Derives `_${optionKey}` modifiers when no explicit `modifier` is provided.
+ * Never sets `default: true` — the new API has no concept of a default option;
+ * downstream consumers treat "no option active" as the implicit default.
+ */
 interface ModifierDef {
   modifier: ModifierNameShape;
   selector: string;
@@ -155,6 +164,7 @@ type VarsToTokens<TVars extends VarsConfig> = { [K in keyof TVars]: { [T in Excl
 type MergeTokens<A, B> = { [K in keyof A | keyof B]: K extends keyof B ? K extends keyof A ? A[K] & B[K] : B[K] : K extends keyof A ? A[K] : never };
 /** Build a structured token reference object from atomic tokens */
 declare function buildTokenReference(atomic: AtomicToken<ModifierNameShape>[], configPrefix: string): Record<string, Record<string, string>>;
+/** Build a structured composite-styles reference object for use in defineModifiers context */
 /** Global styles definition — CSS selector → style props */
 type GlobalStylesDef = Record<string, Record<string, any>>;
 /** CSS properties for the example wrapper element */
@@ -217,6 +227,17 @@ interface UdsConfigData {
    * of walking the raw style-prop records.
    */
   resolvedStyleProps?: ResolvedStyleProp[];
+  /**
+   * Components registered via `.registerComponents({...})`. Authored
+   * elsewhere via `defineComponent('Name', config)` and imported into
+   * the config. The canonical input for codegen + runtime in the new
+   * layers-shape architecture.
+   *
+   * Map keyed by component name (e.g. `Box`, `Alert`); each value is the
+   * `ComponentConfigValue` branded record carrying `layers`, `props`,
+   * `defaultProps`.
+   */
+  componentConfigs?: Record<string, ComponentConfigValue<any, any, any>>;
 }
 interface ComponentConfig<TComponents extends ComponentsConfig<string> = ComponentsConfig<string>, TMotion extends MotionPresetsDef | undefined = MotionPresetsDef | undefined> {
   name?: string;
@@ -283,6 +304,29 @@ interface UdsConfig<TModifier extends ModifierNameShape = ModifierProp, TTokens
    * ```
    */
   registerStyleProps<const Props extends Record<string, AnyStyleProp>>(props: Props): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
+  /**
+   * Register components authored with `defineComponent(...)`. Calls
+   * accumulate — later `.registerComponents({...})` calls merge into
+   * the existing map (later keys overwrite earlier ones with the same
+   * name).
+   *
+   * Accepts either form returned by `defineComponent`:
+   *  - The pure-data config value from the bare verbose form
+   *    (`defineComponent({ layers, props })`).
+   *  - A bound component from the primitive form
+   *    (`defineComponent('div', { props })`) or the chained
+   *    `.render(fn)` builder — the framework extracts the underlying
+   *    config from the non-enumerable `__config` slot.
+   *
+   * @example
+   * ```ts
+   * import { Box } from './src/uds/components/box';      // primitive
+   * import { alertConfig } from './src/uds/components/alert.config'; // verbose pure-data
+   *
+   * uds.registerComponents({ Box, Alert: alertConfig });
+   * ```
+   */
+  registerComponents<const TConfigs extends Record<string, ComponentConfigValue<any, any, any> | BoundComponent<ComponentConfigValue<any, any, any>, any>>>(configs: TConfigs): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
   defineMotion<const M extends MotionPresetsDef>(presets: M | ((tokens: TTokens) => M)): ConfigResult<TModifier, TTokens, { [K in keyof M]: string }, TExt, TCompositeStyles, TModeModifiers, TVars>;
   defineComponents(params: ComponentsConfig<MotionAliasValue<TMotion> | string> | ((ctx: {
     tokens: TTokens;
@@ -313,6 +357,10 @@ interface UdsConfig<TModifier extends ModifierNameShape = ModifierProp, TTokens
 type AnyUdsConfig = UdsConfig<ModifierNameShape, any, any, any, any, any, any>;
 /** Extract the raw config data from a builder instance */
 declare function resolveConfig(config: AnyUdsConfig): UdsConfigData;
+/**
+ * Resolve configuration with all token references replaced by their raw values.
+ * Useful for tools that need the actual values (e.g. anatomy generation).
+ */
 declare function createConfigBuilder<TModifier extends ModifierNameShape = ModifierProp, TTokens = EmptyTokens, TMotion = EmptyMotion, TExt extends Record<string, any> = {}, TCompositeStyles = EmptyCompositeStyles, TModeModifiers extends ModifierNameShape = never, TVars extends VarsConfig = EmptyVars>(data: UdsConfigData, extensions?: TExt): UdsConfig<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars> & TExt;
 interface InterpolateMarker {
   __type: 'interpolate';
@@ -322,4 +370,4 @@ interface InterpolateMarker {
 declare function darker(color: string, amount: number): string;
 declare function lighter(color: string, amount: number): string;
 //#endregion
-export { AtomicToken, BuildOptions, CheckForReservedModifiersInput, ComponentConfig, DefineComponentInput, DefineComponentMotionInput, ExampleDef, ExampleEntryDef, ExampleLayoutStyles, GetModifierFromInput, GlobalStylesDef, InterpolateMarker, ModeGroup, ModeOption, ModeOptionInput, ModeSetInput, ModesInput, ModifierDef, MotionPresetsDef, UdsConfig, UdsConfigData, buildTokenReference, createConfigBuilder, darker, lighter, resolveConfig };
+export { AtomicToken, BuildOptions, CheckForReservedModifiersInput, ComponentConfig, DefineComponentInput, DefineComponentMotionInput, ExampleDef, ExampleEntryDef, ExampleLayoutStyles, GetModifierFromInput, GlobalStylesDef, InterpolateMarker, ModeGroup, ModeOption, ModeOptionInput, ModeSetInput, ModesInput, ModifierDef, MotionPresetsDef, SingleComponentDef, UdsConfig, UdsConfigData, buildTokenReference, createConfigBuilder, darker, lighter, resolveConfig };

package/dist/config/dist/createConfig.js

@@ -427,6 +427,15 @@ function createConfigBuilder(data, extensions) {
 			if (data.vars) updates.atomic = mergeAtomic([], synthesizeAtomicFromVarsAndStyleProps(data.vars, mergedStyleProps, data.modes ?? []), "override");
 			return next(updates);
 		},
+		registerComponents(configs) {
+			const normalized = {};
+			for (const [name, entry] of Object.entries(configs)) if (typeof entry === "function" && "__config" in entry) normalized[name] = entry.__config;
+			else normalized[name] = entry;
+			return next({ componentConfigs: {
+				...data.componentConfigs ?? {},
+				...normalized
+			} });
+		},
 		defineMotion(presets) {
 			const tokenReference = buildTokenReference(data.atomic, data.prefix);
 			const resolved = typeof presets === "function" ? presets(tokenReference) : presets;

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

@@ -1 +1,24 @@
-export { };
+import { ComponentConfigValue, HtmlTag, LayerInput } from "./component-config.js";
+import { Props } from "./Props.js";
+import { ReactNode } from "react";
+
+//#region ../config/dist/defineComponent.d.ts
+//#region src/defineComponent.d.ts
+/**
+ * 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']>`.
+ */
+type BoundComponent<TConfig extends ComponentConfigValue<Record<string, LayerInput>, any, HtmlTag | undefined>, TExtra extends Record<string, unknown> = {}> = React.FC<Props<TConfig> & TExtra> & {
+  readonly __config: TConfig;
+};
+/**
+ * A `defineComponent({...})` config value with a `.render(fn)` builder
+ * method bolted on. The builder is non-enumerable so JSON serialization
+ * still produces pure data — codegen can read `__kind`, `layers`,
+ * `props`, and `defaultProps` without seeing the render hook.
+ */
+//#endregion
+export { BoundComponent };

package/dist/config/dist/defineComponent.js

@@ -0,0 +1,2 @@
+import "./createComponent.js";
+import "react";

package/dist/config/dist/defineStyleProp.d.ts

@@ -1,4 +1,4 @@
-import { CssValue, CssValueTypeName } from "./types/css-values.js";
+import { CssValueTypeName } from "./types/css-values.js";
 
 //#region ../config/dist/defineStyleProp.d.ts
 /** Runtime input type for `toCss` based on the entry's `type`. */
@@ -22,10 +22,20 @@ type ArbitraryEntry = { [T in CssValueTypeName]: {
  *  - An array of {@link ArbitraryEntry} for multi-shape acceptance.
  */
 type ArbitrarySpec = CssValueTypeName | readonly ArbitraryEntry[];
+/**
+ * The literal-keyword subset of values a property accepts, derived from
+ * {@link CssPropertyValues}[P]. For custom CSS properties (`--*`) the value
+ * type is governed by the required `cssType` field instead, so any string
+ * is accepted at the type level.
+ */
 type StylePropMetadata = {
   label?: string;
   description?: string;
 };
+/**
+ * A finalized style prop. Returned by `defineStyleProp(spec).metadata(meta)`.
+ * Consumers wrap these in `uds.registerStyleProps({ <propName>: ... })`.
+ */
 /**
  * Structurally-loose form of {@link StyleProp}. Any concrete `StyleProp<P>`
  * is assignable to this. Used at registration / resolution boundaries where
@@ -41,5 +51,6 @@ interface AnyStyleProp {
   readonly cssType?: CssValueTypeName;
   readonly metadata: StylePropMetadata;
 }
+/** Intermediate builder — the only callable method is `.metadata()`. */
 //#endregion
 export { AnyStyleProp, ArbitraryEntry, ArbitrarySpec, StylePropMetadata };

package/dist/config/dist/index.d.ts

@@ -1,9 +1,13 @@
-import { defaultColors } from "./consts/defaultColors.js";
+import { ComponentRef, CompositeRef, RegisteredComponents, RegisteredComposites, RegisteredStyleProps, StylePropRef } from "./component-refs.js";
+import { BoolMarker, ComponentConfigValue, ComposedLayer, CompositeBinding, EnumMarker, HtmlTag, LayerInput, PrimitiveLayer, PrimitivePropBinding, PropBinding, RootTag, SingleLayerCompositeBinding, StylePropBinding, StylePropShorthand, SurfaceForward, VerbosePropBinding } from "./component-config.js";
+import { Props } from "./Props.js";
+import { BoundComponent } from "./defineComponent.js";
 import { ColorFn, ColorKeyword, CssAngle, CssColor, CssLength, CssPercentage, CssRatio, CssTime, CssValue, CssValueTypeName, HexColor, HslColor, RgbColor } from "./types/css-values.js";
 import { AnyStyleProp, ArbitraryEntry, ArbitrarySpec, StylePropMetadata } from "./defineStyleProp.js";
-import { ResolvedStyleProp, ResolvedToken } from "./resolveStyleProp.js";
 import { TokenType, VarGroupDef, VarTokenDef, VarsConfig } from "./types.js";
-import { AtomicToken, BuildOptions, CheckForReservedModifiersInput, ComponentConfig, DefineComponentInput, DefineComponentMotionInput, ExampleDef, ExampleEntryDef, ExampleLayoutStyles, GetModifierFromInput, GlobalStylesDef, InterpolateMarker, ModeGroup, ModeOption, ModeOptionInput, ModeSetInput, ModesInput, ModifierDef, MotionPresetsDef, UdsConfig, UdsConfigData, buildTokenReference, createConfigBuilder, darker, lighter, resolveConfig } from "./createConfig.js";
+import { AtomicToken, BuildOptions, CheckForReservedModifiersInput, ComponentConfig, DefineComponentInput, DefineComponentMotionInput, ExampleDef, ExampleEntryDef, ExampleLayoutStyles, GetModifierFromInput, GlobalStylesDef, InterpolateMarker, ModeGroup, ModeOption, ModeOptionInput, ModeSetInput, ModesInput, ModifierDef, MotionPresetsDef, SingleComponentDef, UdsConfig, UdsConfigData, buildTokenReference, createConfigBuilder, darker, lighter, resolveConfig } from "./createConfig.js";
+import { ResolvedStyleProp, ResolvedToken } from "./resolveStyleProp.js";
+import { defaultColors } from "./consts/defaultColors.js";
 import { SerializedConfig, TokenRef, buildReverseMap, deserializeConfig, serializeConfig } from "./serialize.js";
 import { ComponentsConfig as ComponentsConfig$1 } from "@uds/types";
 export { type ComponentsConfig$1 as ComponentsConfig };

package/dist/config/dist/index.js

@@ -1,9 +1,11 @@
-import "./consts/defaultColors.js";
 import "./component-resolution.js";
+import "./consts/defaultColors.js";
+import "./createComponent.js";
 import "./propertyAcceptedTypes.js";
 import "./resolveTokenTypes.js";
 import "./resolveStyleProp.js";
 import "./createConfig.js";
+import "./defineComponent.js";
 import "./defineStyleProp.js";
 import "./propertyGroups.js";
 import "./refs.js";

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

@@ -1,6 +1,7 @@
 import { CssValueTypeName } from "./types/css-values.js";
 import { ArbitrarySpec, StylePropMetadata } from "./defineStyleProp.js";
 //#region ../config/dist/resolveStyleProp.d.ts
+//#region src/resolveStyleProp.d.ts
 interface ResolvedToken {
   /** The token's raw key, e.g. `'brand'`. */
   readonly name: string;
@@ -47,9 +48,22 @@ interface ResolvedStyleProp {
   readonly cssProperty: string;
   readonly classPrefix: string;
   readonly tokens: readonly ResolvedToken[];
-  readonly literals: readonly string[];
+  readonly literals: readonly (string | number | boolean)[];
+  /** Alias → CSS-value map for `{ alias, value }` entries in `values`.
+   *  When an author writes `flexDirection='col'`, the CSS emitter looks
+   *  this up to write `flex-direction: column` instead of `flex-direction: col`.
+   *  Object values represent composite styles (`truncate=true` mapping to
+   *  three CSS properties at once). Only populated when at least one
+   *  entry used the alias form. */
+  readonly literalAliases?: Readonly<Record<string, string | Readonly<Record<string, string>>>>;
   readonly arbitrary: ArbitrarySpec | undefined;
   readonly metadata: StylePropMetadata;
 }
+/**
+ * Structurally-loose input shape for the resolver. Any `StyleProp<P>` from
+ * `defineStyleProp` is assignable to this. Defined locally so the
+ * resolver's signature doesn't expand `ValuesEntry<P>` over the full CSS
+ * property union (TS2590).
+ */
 //#endregion
 export { ResolvedStyleProp, ResolvedToken };