@yahoo/uds-v5-wip 1.60.0 → 1.62.0

package/dist/config/dist/factories.d.ts

@@ -0,0 +1,707 @@
+import { RegisteredModifiers, TagRef, TokenGroupRef, composite, styleProp, token } from "./refs.js";
+import { darken, lighten } from "./colorExpressions.js";
+import { ComponentDefinition, ComponentGroupDefinition, ComponentMetadata, CompositeStyleDefinition, LayerInput, ModeDefinition, ModifierDefinition, MotionDefinitionInput, PreviewDefinition, StylePropDefinition, StylePropMetadata, StylePropProperty, TokenDefinition } from "./types.js";
+import { BooleanMarker, ComponentSlotMarker, LayerMarker, NumberMarker, PreviewAxisMarker, PreviewPropsRule, RequiredBrand, SlotMarker, SlotRef, SlotValueType, StringMarker, VariantMarkerArray, VariantMarkerObject } from "./markers.js";
+import { BaseLayerStyles, LayerPropsMap, LayerTag, Props, PropsFromBindings, SlotPropValue } from "./Props.js";
+import { ComponentPropsWithRef, ComponentType, FC, HTMLAttributes, JSX, ReactNode } from "react";
+
+//#region ../config/dist/factories.d.ts
+//#region src/factories.d.ts
+/**
+ * Author-side metadata for a token group — `label` and `description`
+ * land on Studio's UI when the group is registered. Kept open
+ * (`Readonly<Record<string, unknown>>` superset) so consumers can
+ * thread arbitrary fields through to codegen without a schema change.
+ */
+interface TokenGroupMetadata {
+  readonly label?: string;
+  readonly description?: string;
+}
+/**
+ * `defineTokenGroup` return shape — the authored tokens record plus a
+ * non-enumerable `.metadata({...})` chain that stashes the supplied
+ * `{ label?, description? }` under a hidden `__metadata` slot.
+ * `Config.registerTokenGroups` reads the slot to back-fill the
+ * `TokenGroup` instance's `label` / `description` fields.
+ *
+ * The data is non-enumerable so `JSON.stringify(group)` still produces
+ * the bare tokens record — same wire format that lands in
+ * `.uds/config.json`.
+ */
+/**
+ * Authored token-group value returned by `defineTokenGroup({...})`.
+ * Wraps the input tokens record under `tokens` and exposes a
+ * `.metadata({...})` chain that sets `label` / `description` on the
+ * same object. Shape-compatible with `TokenGroupDefinition` so the
+ * authored value round-trips through `Config.toJSON` /
+ * `Config.fromJSON` without reshape.
+ */
+type DefinedTokenGroup<T extends Record<string, TokenDefinition>> = {
+  tokens: T;
+  label?: string;
+  description?: string;
+  metadata(meta: TokenGroupMetadata): DefinedTokenGroup<T>;
+};
+declare function defineTokenGroup<const T extends Record<string, TokenDefinition>>(t: T): DefinedTokenGroup<T>;
+declare function defineModifier<const T extends ModifierDefinition>(t: T): T;
+declare function defineMode<const T extends ModeDefinition>(t: T): T;
+declare function defineCompositeStyle<const T extends CompositeStyleDefinition>(t: T): T;
+declare function defineMotion<const T extends MotionDefinitionInput>(t: T): T;
+declare function defineComponentGroup<const T extends ComponentGroupDefinition>(t: T): T;
+/**
+ * Style-prop spec with chainable `.metadata({...})` (label/description/
+ * arbitrary author-side metadata) and `.withOpacity({...})` (declares
+ * a paired opacity sibling). Both chains mutate the underlying spec
+ * in place and return it so chains can be appended or saved as a value.
+ */
+type DefinedStyleProp<P extends StylePropProperty> = StylePropDefinition<P> & {
+  metadata(meta: StylePropMetadata): DefinedStyleProp<P>;
+  withOpacity(spec: {
+    as: string;
+    values: TokenGroupRef;
+    separator?: string;
+  }): DefinedStyleProp<P>;
+};
+/**
+ * Author a style-prop spec. `P` is inferred from `cssProperty` so the
+ * `values` array narrows against the chosen CSS property's accepted
+ * keyword union (`'transparent'` is OK for `border-color`, errors for
+ * `padding`). For custom properties (`--foo`), `values` accepts open
+ * strings — `cssType` constrains the runtime value space instead.
+ *
+ * Returns the spec with a non-enumerable `.metadata({...})` chain;
+ * the chain merges the supplied bag into `spec.metadata` so multiple
+ * `.metadata({...})` calls accumulate.
+ */
+declare function defineStyleProp<const P extends StylePropProperty>(spec: StylePropDefinition<P>): DefinedStyleProp<P>;
+/**
+ * Slot binding. `slot()` is an open slot — codegen treats it as
+ * `ReactNode` accepted at the component's own children. `slot('layer/prop')`
+ * routes a JSX prop into the named layer's `layerProp` (defaults to
+ * `'children'` when only a layer name is provided).
+ *
+ * Open form returns `SlotMarker` (no cross-reference). The
+ * layer-targeting forms return `SlotRef` (the `layer` field is the
+ * cross-reference — points at a layer's prop).
+ *
+ * `.required()` makes the prop mandatory in the codegen-emitted types.
+ * `.accepts(...)` constrains the accepted children to one or more
+ * registered components.
+ */
+declare function slot(): SlotMarker;
+declare function slot(options: {
+  type: 'component';
+}): ComponentSlotMarker;
+declare function slot(options: {
+  type: SlotValueType;
+}): SlotMarker;
+declare function slot<TPath extends string>(path: TPath): TPath extends `${infer L}/${infer A}` ? SlotRef<L, A> : SlotRef<TPath, 'children'>;
+declare function slot<L extends string, A extends string>(layer: L, options: {
+  prop: A;
+  type?: SlotValueType;
+}): SlotRef<L, A>;
+declare function slot<TPath extends string>(path: TPath, options: {
+  type: SlotValueType;
+}): TPath extends `${infer L}/${infer A}` ? SlotRef<L, A> : SlotRef<TPath, 'children'>;
+/**
+ * The factory return type — same marker plus a guaranteed `required()`
+ * method that returns the same chainable shape. The marker interface
+ * declares `required?()` as optional so raw `{ __kind: ... }` object
+ * literals (test fixtures, JSON-hydrated configs) still satisfy the
+ * interface; factories override that with a definite version so authoring
+ * sites can call `string().required()` without a `?.` guard.
+ *
+ * `.required()` does two things:
+ *  - Consumer MUST pass the prop at the JSX site (runtime + emitted
+ *    `Props<T>` shape carry the constraint).
+ *  - Render-fn destructure sees the value as non-optional (`T` rather
+ *    than `T | undefined`). The default render-arg type *is* optional
+ *    because consumers may omit the prop and `defaultProps` is just a
+ *    runtime convenience — `.required()` is the explicit "I promise
+ *    this is always defined" knob.
+ */
+type Chainable<T extends {
+  __required?: boolean;
+}> = T & {
+  required(): T & RequiredBrand;
+};
+/**
+ * Boolean-prop binding. Codegen emits the prop as `<name>?: boolean`
+ * and routes presence/absence into a per-layer `data-${name}` attribute
+ * the runtime selects on. Mirrors the old `@uds/config` `helpers.boolean()`.
+ *
+ * The optional `values` argument carries per-state per-layer styles
+ * (`{ true: { root: {...} }, false: { root: {...} } }`) — codegen emits
+ * one variant CSS class per layer per state, same as `variant({...})`.
+ *
+ * `.required()` flips the prop to mandatory at JSX call sites.
+ */
+declare function boolean(values?: {
+  true?: Record<string, Record<string, unknown>>;
+  false?: Record<string, Record<string, unknown>>;
+}): Chainable<BooleanMarker>;
+/**
+ * Cross-layer style override — `_hover: layer('close', { opacity: 1 })`
+ * declares "when this layer is hovered, apply these styles to the
+ * named layer". Codegen emits a descendant-combinator rule pointing
+ * from the source layer's selector to the target layer's selector.
+ * Mirrors the old `@uds/config` `helpers.layer()`.
+ */
+declare function layer(layerName: string, styles: Record<string, unknown>): LayerMarker;
+/**
+ * Variant-prop binding — two authoring shapes, one normalized marker.
+ *
+ *  1. **Object form** — `variant({ a: { root: {...} }, b: {} })`. Keys
+ *     are accepted values, values are per-layer style maps. Empty `{}`
+ *     leaves a value styleless, so mixed-styling is supported in a
+ *     single call.
+ *  2. **Array form** — `variant(['a','b','c'] as const)`. Typed list with
+ *     no styles. Required for numeric variant (`variant([12, 16, 24] as
+ *     const)`) since JS object keys can't preserve numeric literal
+ *     types; also a nicer shorthand for "typed list, no styles."
+ *
+ * Both forms share the runtime tag `__kind: 'variant'`; `Array.isArray(values)`
+ * is the single discriminator. The `defaultValue` second argument seeds
+ * `defaultProps[<prop>]`.
+ *
+ * `.required()` flips the prop to mandatory at JSX call sites.
+ */
+declare function variant<const V extends readonly (string | number)[]>(values: V, defaultValue?: V[number]): Chainable<VariantMarkerArray<V>>;
+declare function variant<const V extends Record<string, Record<string, unknown>>>(values: V, defaultValue?: keyof V & string): Chainable<VariantMarkerObject<V>>;
+/**
+ * Wide-string prop binding. Codegen emits the prop as `<name>?: string`
+ * (or required when chained with `.required()`). No CSS effect — use
+ * this for free-form text props (URLs, labels). When you want a
+ * constrained list of accepted strings, reach for the array form of
+ * `variant(...)` instead.
+ */
+declare function string(): Chainable<StringMarker>;
+/**
+ * Wide-number prop binding. Codegen emits the prop as `<name>?: number`
+ * (or required when chained with `.required()`). No CSS effect — use
+ * this for free-form numeric props (tabIndex, count). When you want a
+ * constrained list of accepted numbers, reach for the array form of
+ * `variant(...)` instead.
+ */
+declare function number(): Chainable<NumberMarker>;
+/**
+ * Helpers passed to `defineComponent(...).config(cb)` callbacks. Same
+ * shape regardless of single-layer (`defineComponent('div')`) or
+ * multi-layer (`defineComponent.layers({...})`) entry — destructure
+ * whichever subset the prop bindings need.
+ *
+ * Wide form (no layer narrowing) — kept for the runtime helper bundle
+ * and back-compat with consumers that imported the type by name.
+ * `.config(cb)` callbacks see the narrower `TypedConfigHelpers<T>` so
+ * authoring sites get layer-aware autocomplete.
+ */
+interface ConfigCallbackHelpers {
+  readonly slot: typeof slot;
+  readonly variant: typeof variant;
+  readonly boolean: typeof boolean;
+  readonly string: typeof string;
+  readonly number: typeof number;
+  readonly layer: typeof layer;
+  readonly composite: typeof composite;
+  readonly styleProp: typeof styleProp;
+  readonly token: typeof token;
+  readonly darken: typeof darken;
+  readonly lighten: typeof lighten;
+}
+/**
+ * Per-layer styles map, keyed by layer name. Each value narrows to
+ * the layer target's own prop surface via `BaseLayerStyles<TLayers[K]>`
+ * — same mapping used by `base: { <layer>: {...} }`. Reused by
+ * `variant({...})` variant bodies, `boolean({...})` true/false bodies,
+ * and the cross-layer `layer(target, styles)` helper.
+ */
+type LayerStylesFor<TLayers> = { [K in keyof TLayers]?: BaseLayerStyles<TLayers[K]> };
+/**
+ * Layer-aware overload of `variant(...)` exposed to `.config(cb)`
+ * callbacks. Array form is unchanged (no styles); object form narrows
+ * each variant's body to a layer-keyed style map. The layer name and
+ * its declared style props autocomplete; non-layer keys land in the
+ * `unknown`-typed fallback (no autocomplete) since the inner record
+ * permits arbitrary keys for back-compat with raw author bags.
+ */
+interface TypedVariantHelper<TLayers> {
+  <const V extends Record<string, LayerStylesFor<TLayers>>>(values: V, defaultValue?: keyof V & string): Chainable<VariantMarkerObject<V>>;
+  <const V extends readonly (string | number)[]>(values: V, defaultValue?: V[number]): Chainable<VariantMarkerArray<V>>;
+}
+/**
+ * Layer-aware overload of `boolean(...)` exposed to `.config(cb)`
+ * callbacks. The optional `true` / `false` per-state bodies narrow to
+ * a layer-keyed style map — same shape as `variant({...})` variant
+ * bodies.
+ */
+interface TypedBooleanHelper<TLayers> {
+  (): Chainable<BooleanMarker>;
+  (values: {
+    true?: LayerStylesFor<TLayers>;
+    false?: LayerStylesFor<TLayers>;
+  }): Chainable<BooleanMarker>;
+}
+/**
+ * Layer-aware `layer(target, styles)` cross-layer style helper. The
+ * `target` arg narrows to declared layer names; `styles` narrows to
+ * the target layer's own prop surface (modifiers included, same as
+ * the `base[<layer>]` shape).
+ */
+type TypedLayerHelper<TLayers> = <L extends keyof TLayers & string>(layerName: L, styles: BaseLayerStyles<TLayers[L]>) => LayerMarker;
+/**
+ * Per-layer JSX prop keys — the names a `slot('layer/prop')` ref can
+ * point at. Composed-component layers expose their `Props<...>` keys
+ * (the same surface the rendered child accepts at JSX call sites);
+ * tag layers expose the React `HTMLAttributes` key set (children,
+ * onClick, aria-*, ...). Used to compute the `slot()` path union.
+ */
+type LayerPropNames<TLayer> = TLayer extends ((props: infer P) => unknown) ? keyof P & string : TLayer extends ComponentDefinition<infer InnerLayers, infer InnerProps, infer InnerTag> ? keyof Props<ComponentDefinition<InnerLayers, InnerProps, InnerTag>> & string : LayerTag<TLayer> extends infer TT extends keyof JSX.IntrinsicElements ? keyof ComponentPropsWithRef<TT> & string : keyof HTMLAttributes<HTMLElement> & string;
+/**
+ * Per-layer prop union, lazily computed at the slot call site.
+ * Wrapped in a single-key conditional so TS only materializes the
+ * inner `Props<...>` once, when the layer literal is known —
+ * precomputing all layers eagerly via a mapped type blew the
+ * instantiation-depth budget on multi-layer components whose
+ * inner layers are themselves composed (Modal, Sheet, EmptyState).
+ */
+type LayerPropNamesAt<TLayers, L extends keyof TLayers & string> = LayerPropNames<TLayers[L]>;
+/**
+ * `true` when `TLayers` declares exactly one layer (single-layer
+ * primitives like Box / Text). The empty `slot()` form returns an
+ * open `SlotMarker` that routes to the component's own children —
+ * unambiguous only when there's a single layer to route to.
+ * Multi-layer components must use the explicit `slot('layer/prop')`
+ * path form so the render fn knows where the slot lands.
+ *
+ * Implementation: standard "is-union" probe. `K extends K` distributes
+ * over the union; `[U] extends [K]` checks whether the original
+ * union still equals the now-distributed single member — only true
+ * for a single-element union.
+ */
+type SingleLayer<TLayers, K extends keyof TLayers = keyof TLayers> = [keyof TLayers] extends [never] ? false : K extends K ? [keyof TLayers] extends [K] ? true : false : never;
+/**
+ * Layer-aware `slot(...)` helper. Two forms with *different* runtime
+ * semantics — pick based on intent, not layer count:
+ *
+ *  - `slot()` — open slot (returns `SlotMarker`). Codegen surfaces
+ *    the prop as a free render-fn arg (`({ children, ... }) => ...`)
+ *    so the render fn places it explicitly between siblings. Right
+ *    for sequenced positioning (`{startIcon}{children}{endIcon}`).
+ *  - `slot('layer/prop')` — typed slot ref (returns `SlotRef<L, A>`).
+ *    Codegen bundles the value into `props.<layer>.<prop>` so it
+ *    spreads onto the named layer's JSX (`<X {...props.<layer>} />`).
+ *    Right for forwarding into a wrapped component's own prop.
+ *
+ * The single-arg `slot('layer')` and the object-options form
+ * `slot('layer', { prop })` were removed — always write the explicit
+ * `'layer/prop'` path so codegen / Studio / readers see one syntax
+ * for the routed form.
+ */
+/** First parameter of a function-typed layer prop (the value a callback
+ *  hands back — e.g. the change event for an input's `onChange`). Falls
+ *  back to `any` when the prop doesn't resolve to a function type (some
+ *  composed-component props don't surface their handler signature), so
+ *  the transform is precisely typed where possible and unconstrained
+ *  otherwise — never stricter than the old untyped form.
+ *
+ *  `NonNullable<V>` strips the `| undefined` an optional layer prop
+ *  carries (`onChange?: ChangeEventHandler`). Without it the bare
+ *  conditional distributes over the `Handler | undefined` union: the
+ *  `undefined` arm takes the `any` fallback and `any` absorbs the whole
+ *  union, collapsing the transform arg to `any` for every optional prop. */
+type UnresolvedArg = any;
+type ArgOf<V> = NonNullable<V> extends ((arg: infer A, ...rest: never[]) => unknown) ? A : UnresolvedArg;
+/**
+ * Layer-aware `SlotRef` whose `.transform(fn)` types `fn`'s argument as
+ * the targeted layer prop's value (e.g. `slot('field/onChange')`'s
+ * transform receives the input's change event). The consumer-facing
+ * prop then resolves to `(value: ReturnType<fn>) => void`.
+ */
+interface TypedSlotRef<TLayer extends string, TAs extends string, TArg> extends Omit<SlotRef<TLayer, TAs>, 'transform'> {
+  transform<Out>(fn: (arg: TArg) => Out): SlotRef<TLayer, TAs> & {
+    readonly __transformOut: Out;
+  };
+}
+interface TypedSlotHelper<TLayers> {
+  (): SlotMarker;
+  (options: {
+    type: 'component';
+  }): ComponentSlotMarker;
+  (options: {
+    type: SlotValueType;
+  }): SlotMarker;
+  <L extends keyof TLayers & string, A extends LayerPropNamesAt<TLayers, L>>(path: `${L}/${A}`): TypedSlotRef<L, A, ArgOf<SlotPropValue<SlotRef<L, A>, TLayers>>>;
+  <L extends keyof TLayers & string, A extends LayerPropNamesAt<TLayers, L>>(path: `${L}/${A}`, options: {
+    type: SlotValueType;
+  }): TypedSlotRef<L, A, ArgOf<SlotPropValue<SlotRef<L, A>, TLayers>>>;
+}
+/**
+ * `.config(cb)` callback helpers narrowed against the chain seed `T`.
+ * `slot` / `variant` / `boolean` / `layer` know the declared layer names
+ * and per-layer prop surfaces so authoring sites get layer-aware
+ * autocomplete without changing the runtime helper bundle. The
+ * remaining helpers (`string`, `number`, `composite`, `styleProp`,
+ * `token`) don't depend on `T`, so they pass through as the wide
+ * module-level fns.
+ */
+type TypedConfigHelpers<T extends ComponentDefinition> = T extends ComponentDefinition<infer TLayers, infer _P, infer _Tag> ? {
+  readonly slot: TypedSlotHelper<TLayers>;
+  readonly variant: TypedVariantHelper<TLayers>;
+  readonly boolean: TypedBooleanHelper<TLayers>;
+  readonly layer: TypedLayerHelper<TLayers>;
+  readonly string: typeof string;
+  readonly number: typeof number;
+  readonly composite: typeof composite;
+  readonly styleProp: typeof styleProp;
+  readonly token: typeof token;
+  readonly darken: typeof darken;
+  readonly lighten: typeof lighten;
+} : ConfigCallbackHelpers;
+/**
+ * Helpers passed to `defineComponent(...).preview(cb)` callbacks.
+ * `prop(name)` produces a row/column axis spec for the `matrix` field
+ * — Studio + codegen consume the marker to expand the prop's variant
+ * values into the preview grid.
+ *
+ * Wide form (no narrowing) — kept for the runtime bundle and external
+ * consumers. `.preview(cb)` callbacks see the narrower
+ * `TypedPreviewHelpers<T>` so axis names autocomplete to declared
+ * props / registered modifiers.
+ */
+interface PreviewCallbackHelpers {
+  readonly prop: (name: string) => PreviewAxisMarker;
+  readonly modifier: (name: string) => PreviewAxisMarker;
+  /**
+   * Per-cell prop-override axis. Pass a flat bag (applied to every cell)
+   * or a list of `{ when?, props }` rules guarded against other axes —
+   * the way to vary render-extra data per cell without a config prop.
+   */
+  readonly props: (arg: Record<string, unknown> | readonly PreviewPropsRule[]) => PreviewAxisMarker;
+}
+/**
+ * `.preview(cb)` callback helpers narrowed against the resolved
+ * component definition `T`. `prop(name)` narrows `name` to declared
+ * prop keys; `modifier(name)` narrows to the codegen-augmented
+ * `RegisteredModifiers` registry. Falls back to the wide
+ * `PreviewCallbackHelpers` when `T` isn't a concrete definition.
+ */
+type TypedPreviewHelpers<T extends ComponentDefinition> = T extends ComponentDefinition<infer _L, infer TProps, infer _Tag> ? {
+  readonly prop: <K extends keyof TProps & string>(name: K) => PreviewAxisMarker;
+  readonly modifier: <K extends keyof RegisteredModifiers<unknown> & string>(name: K) => PreviewAxisMarker;
+  readonly props: (arg: Record<string, unknown> | readonly PreviewPropsRule[]) => PreviewAxisMarker;
+} : PreviewCallbackHelpers;
+type ConfigCallbackResult = Partial<ComponentDefinition>;
+/**
+ * Per-layer `base` shape derived from the chain seed `T`. Each declared
+ * layer key narrows to the layer target's own prop surface (style props
+ * + HTML attrs for tag layers, `Partial<Props<...>>` for composed
+ * component layers) — same `LayerPropsValue<TLayer>` mapping the JSX
+ * `layerProps` prop already exposes. Lets the `.config(cb)` callback
+ * catch typos like `base: { root: { invalidProp: '...' } }` at the
+ * authoring site.
+ */
+type BaseStylesFor<T extends ComponentDefinition> = T extends ComponentDefinition<infer TLayers, infer _P, infer _Tag> ? { [K in keyof TLayers]?: BaseLayerStyles<TLayers[K]> } : never;
+/**
+ * Per-T `defaultProps` shape. Splits on layer count:
+ *
+ *  - **Multi-layer** components (`{root, text, ...}`) — narrow to
+ *    the component's *own declared props* (`PropsFromBindings`).
+ *    Without the narrowing, `Partial<Props<T>>` bleeds the root
+ *    layer's whole prop surface through `ComposedRootProps<TLayers>`
+ *    so multi-layer authoring sites see hundreds of irrelevant Box
+ *    style props in autocomplete.
+ *  - **Single-layer** components (`defineComponent('div')`,
+ *    `defineComponent(Box)`) — keep `Partial<Props<T>>` so value-
+ *    extend chains can still default inherited style props
+ *    (`bg: 'tertiary'`, `as: 'button'`, `cursor: 'pointer'`).
+ *
+ * Props declared in the same `.config()` call don't appear here —
+ * the seed `T` reflects the chain state *before* the current call.
+ * Default a freshly-declared prop in a follow-up `.config()` step
+ * (or in a future `.defaultProps({...})` chain method).
+ */
+type DefaultPropsFor<T extends ComponentDefinition> = T extends ComponentDefinition<infer TLayers, infer TProps, infer _Tag> ? SingleLayer<TLayers> extends true ? Partial<Props<T>> : Partial<PropsFromBindings<TProps, TLayers> & RegisteredModifiers<PropsFromBindings<TProps, TLayers>> & {
+  layerProps?: LayerPropsMap<TLayers>;
+}> : never;
+/**
+ * `.config(cb)` callback result narrowed against the chain seed `T`.
+ * Overrides `base` with `BaseStylesFor<T>` and `defaultProps` with
+ * `DefaultPropsFor<T>` so authoring sites get autocomplete on
+ * per-layer style blocks and on the right prop surface (own declared
+ * props for multi-layer, inherited Props<T> for single-layer
+ * value-extends). Other fields stay on the wide `ComponentDefinition`
+ * shape.
+ */
+type ConfigCallbackResultFor<T extends ComponentDefinition> = Omit<ConfigCallbackResult, 'base' | 'defaultProps'> & {
+  base?: BaseStylesFor<T>;
+  defaultProps?: DefaultPropsFor<T>;
+};
+/**
+ * Per-nested-field override: when `C` carries `K`, the merged shape's
+ * `K` is `Omit<T[K], keyof C[K]> & C[K]` so newly-bound keys *replace*
+ * the parent's binding rather than intersect with it. When only one
+ * side carries `K`, that side's shape wins; when neither does, the
+ * key is omitted.
+ */
+type MergeNested<T, C, K extends string> = C extends Record<K, infer CV> ? T extends Record<K, infer TV> ? Record<K, Omit<TV, keyof CV> & CV> : Record<K, CV> : T extends Record<K, infer TV> ? Record<K, TV> : {};
+/**
+ * Merge a `.config(cb)` callback result `C` over the chain seed `T`.
+ * Nested fields (`props`, `defaultProps`, `base`) merge per-key (C
+ * overrides T at the leaf level); other fields fall back to the
+ * historic `T & C` intersection.
+ */
+type MergeChainConfig<T, C> = Omit<T, 'props' | 'defaultProps' | 'base'> & Omit<C, 'props' | 'defaultProps' | 'base'> & MergeNested<T, C, 'props'> & MergeNested<T, C, 'defaultProps'> & MergeNested<T, C, 'base'>;
+/**
+ * Per-config slot-prop map: walk a `props` block, pick out every
+ * `slot()`-marked entry, and surface it as `ReactNode | undefined` on
+ * the render-fn args. Each entry resolves to one JSX-callable name
+ * (`title?`, `icon?`, `actions?`) the render fn can read directly.
+ *
+ * Mirrors main's `SlotPropsFromConfig`. Slot markers carry
+ * `__kind: 'slot'`; non-slot entries (style props, variant, booleans)
+ * map to `never` and drop out of the key set.
+ */
+/**
+ * Resolve a marker to the value type the consumer passes via JSX
+ * and the render fn destructures. Mirrors the runtime contract:
+ * `slot` → `ReactNode`, primitive markers → their primitive,
+ * `variant` → the literal union of values/keys, `composite` → key
+ * union of the registered composite's styles, `styleProp` →
+ * `string` (token name OR bracketed arbitrary — the styler picks).
+ */
+type ResolveMarker<M> = M extends {
+  readonly __kind: 'slot';
+  readonly __valueType: 'component';
+} ? ComponentType : M extends {
+  readonly __kind: 'slot';
+} ? ReactNode : M extends {
+  readonly __kind: 'string';
+} ? string : M extends {
+  readonly __kind: 'number';
+} ? number : M extends {
+  readonly __kind: 'boolean';
+} ? boolean : M extends {
+  readonly __kind: 'variant';
+  readonly values: infer V;
+} ? V extends readonly (infer E)[] ? E : V extends Record<string, unknown> ? keyof V & string : string : M extends {
+  readonly __kind: 'composite';
+} ? string : M extends {
+  readonly __kind: 'styleProp';
+} ? string : unknown;
+/**
+ * Render-fn arg map: every entry in `.config({ props })` surfaces on
+ * the render callback. Slots resolve to `ReactNode`; other markers
+ * resolve to their value type. Optionality is driven by `.required()`:
+ *
+ *  - default → optional (`T | undefined`). The author has to guard.
+ *  - `.required()` → non-optional (`T`). Consumer must pass at the JSX
+ *    site (or `defaultProps` covers it), so render destructure is safe
+ *    to use the value directly without an `as T` cast.
+ *
+ * This is what wires `.config({ props: { checked: boolean() } })` →
+ * `.render(({ checked }) => …)` without forcing authors to repeat the
+ * type declaration on `.render<T>`.
+ */
+type RenderPropsFromConfig<TProps, TDefaultKeys extends PropertyKey = never> = { [K in keyof TProps as TProps[K] extends RequiredBrand ? K : K extends TDefaultKeys ? K : never]-?: ResolveMarker<TProps[K]> } & { [K in keyof TProps as TProps[K] extends RequiredBrand ? never : K extends TDefaultKeys ? never : K]?: ResolveMarker<TProps[K]> };
+/**
+ * Per-layer prop bundle the codegen-emitted FC hands to the render
+ * function. One key per layer declared on `.layers({...})`, each
+ * carrying the spread-into-JSX bag (`className`, `data-uds-*`,
+ * forwarded native attrs). Typed as `Record<string, unknown>` per
+ * entry — the runtime contents vary by layer base component and the
+ * render fn just spreads them with `{...props.<layer>}`.
+ */
+type LayerPropsBundle<TLayers> = { [K in keyof TLayers]: Record<string, unknown> };
+/**
+ * Shape of the render fn passed to `.render<TExtra>(fn)`. `props` is
+ * the per-layer bundle injected by the codegen-emitted wrapper FC,
+ * keyed by the layers declared on `.layers({...})`. `TConfigProps`
+ * adds every config-declared prop (slots, variant, booleans, etc.) at
+ * the call site — required when `defaultProps` covers them, optional
+ * otherwise. `TExtra` is the consumer-declared extra JSX-prop shape
+ * (function-typed handlers, complex object pass-throughs) that the
+ * marker system doesn't express yet.
+ */
+type ComponentRenderFn<TExtra = unknown, TConfigProps = unknown, TLayers = Record<string, unknown>> = (args: {
+  props: LayerPropsBundle<TLayers>;
+  children?: ReactNode;
+} & TConfigProps & TExtra) => ReactNode;
+/**
+ * Chain methods attached to every `defineComponent` result. The
+ * builder type intersects with the underlying `ComponentDefinition`
+ * (`T`) so the value is directly assignable to
+ * `Config.registerComponents({...})`. All chain methods are
+ * non-enumerable, so `JSON.stringify` over a builder still produces
+ * the plain authored shape.
+ */
+interface ComponentBuilderMethods<T extends ComponentDefinition> {
+  /**
+   * Resolve prop bindings, base styles, defaults, and motion from a
+   * callback. Helpers (`slot`, `variant`, `composite`, `styleProp`,
+   * `token`) emit the marker shapes codegen consumes.
+   *
+   * The result `C` *overrides* matching `T` fields rather than
+   * intersecting — bare `T & C` would intersect literal-typed marker
+   * fields (`gap: StylePropRef<'gap'> & StylePropRef<'gapX'>`) into
+   * `never`, and `Props<T>`'s walker can't recover from that.
+   */
+  config<const C extends ConfigCallbackResultFor<T>>(cb: (helpers: TypedConfigHelpers<T>) => C): ComponentBuilder<MergeChainConfig<T, C>>;
+  /**
+   * Attach the React render fn. Stored on non-enumerable `__renderFn`
+   * + `__hasRenderFn: true` so codegen's `transformAuthoringSource`
+   * downleveler picks it up while the JSON-safe builder shape stays
+   * clean. `TExtra` is the consumer-declared extra JSX-prop shape;
+   * slot-bound JSX props (declared via `slot()` in `.config()`)
+   * appear automatically alongside `props`/`children`.
+   */
+  render<TExtra extends Record<string, unknown> = {}>(fn: ComponentRenderFn<TExtra, T extends {
+    props: infer P;
+  } ? RenderPropsFromConfig<P, T extends {
+    defaultProps: infer D;
+  } ? keyof D : never> : unknown, T extends {
+    layers: infer L;
+  } ? L : Record<string, unknown>>): BoundComponent<T, TExtra>;
+  /**
+   * Attach a declarative preview spec — stored under non-enumerable
+   * `__preview` so the authored builder stays JSON-clean. Callback
+   * form receives `{ prop }` for axis markers and is invoked
+   * immediately; the resolved spec is the value used downstream.
+   *
+   * `defaultProps` is narrowed against the component's resolved
+   * `Props<T>` so callback parameters (`onSubmit: (event) => ...`)
+   * infer their event type from the component's declared JSX surface.
+   */
+  preview(spec: PreviewDefinition<DefaultPropsFor<T>> | ((helpers: TypedPreviewHelpers<T>) => PreviewDefinition<DefaultPropsFor<T>>)): ComponentBuilder<T>;
+  /**
+   * Declare child components owned by this one. Children flatten into
+   * `Config.components` at registration time and carry
+   * `derived.subcomponentOf`.
+   */
+  subcomponents(children: Record<string, ComponentDefinition>): ComponentBuilder<T>;
+  /**
+   * Attach author-side metadata for codegen's AI prompt artifact +
+   * Studio's UI. Merged into `definition.metadata` (multiple
+   * `.metadata({...})` calls accumulate). Returns the builder so the
+   * chain continues.
+   */
+  metadata(meta: ComponentMetadata): ComponentBuilder<T>;
+}
+/**
+ * Authored builder value returned by `defineComponent(...).config(...)`.
+ *
+ * Three roles in one shape:
+ *
+ *  1. **Data** — the underlying `ComponentDefinition` fields (`layers`,
+ *     `props`, `base`, `defaultProps`, `motion`, `compoundProps`) live
+ *     on enumerable properties so `Config.registerComponents({Text})`
+ *     and `JSON.stringify(Text)` both see the authored shape.
+ *  2. **Chain methods** — `.config`, `.render`, `.preview`, and
+ *     `.subcomponents` are non-enumerable methods on the same value
+ *     (see `ComponentBuilderMethods<T>`).
+ *  3. **JSX callable** — `& FC<any>` lets consumers reference the
+ *     builder directly in JSX (`<Text variant="body">`). The builder
+ *     isn't *actually* a React FC at runtime — the UDS loader rewrites
+ *     `@/uds/components/<seg>` to the codegen-emitted
+ *     `.uds/components/<seg>` artifact (a real FC) before the runtime
+ *     ever sees it. The FC intersection here is the type-only
+ *     concession that keeps source files typechecking against this
+ *     value as if it were the rewritten artifact.
+ */
+type ComponentBuilder<T extends ComponentDefinition> = T & ComponentBuilderMethods<T> & FC<Props<T>>;
+/**
+ * Bound component returned by `.render<TExtra>(fn)`. Mirrors main's
+ * `BoundComponent`: an `FC` whose JSX props are
+ * `TExtra & Record<string, unknown>` so the consumer-declared extras
+ * (`open`, `onOpenChange`, etc.) typecheck precisely at JSX call sites
+ * while the rest of the prop surface (slot/style/HTML attrs) stays
+ * permissively-typed — matching how the codegen-emitted wrapper FC
+ * actually accepts props at runtime.
+ *
+ * The builder-chain methods stay attached so `.preview()` /
+ * `.metadata()` / `.subcomponents()` can follow `.render(...)`.
+ */
+/**
+ * Chain methods exposed on a `BoundComponent` (post-`.render<TExtra>()`).
+ * Mirrors the pre-render `ComponentBuilderMethods` minus `render` (you
+ * only render once), with `.preview` / `.metadata` / `.subcomponents`
+ * preserving the `TExtra` narrowing so chained authors keep their
+ * TExtra-typed JSX surface at consumer call sites.
+ */
+interface BoundComponentMethods<T extends ComponentDefinition, TExtra extends Record<string, unknown>> {
+  config(cb: (helpers: TypedConfigHelpers<T>) => ConfigCallbackResultFor<T>): BoundComponent<T, TExtra>;
+  preview(spec: PreviewDefinition<Omit<DefaultPropsFor<T>, keyof TExtra> & TExtra> | ((helpers: TypedPreviewHelpers<T>) => PreviewDefinition<Omit<DefaultPropsFor<T>, keyof TExtra> & TExtra>)): BoundComponent<T, TExtra>;
+  subcomponents(children: Record<string, ComponentDefinition>): BoundComponent<T, TExtra>;
+  metadata(meta: ComponentMetadata): BoundComponent<T, TExtra>;
+}
+type BoundComponent<T extends ComponentDefinition, TExtra extends Record<string, unknown> = {}> = T & FC<Omit<Props<T>, keyof TExtra> & TExtra> & BoundComponentMethods<T, TExtra> & {
+  readonly __config: T;
+};
+/** Doc-alignment alias kept for callers that imported the older name. */
+type DefinedComponent<T extends ComponentDefinition> = ComponentBuilder<T>;
+/**
+ * Overloaded `defineComponent`:
+ *
+ *  - `defineComponent(tag)` — single-layer seed `{ layers: { root: tag(tag) } }`.
+ *  - `defineComponent(source)` — value-extend an existing component
+ *    builder. The new seed is a fresh object spread from the source so
+ *    the source's identity stays intact; non-enumerable
+ *    `__extendsFrom` carries the source reference for codegen's
+ *    identity-keyed reverse-lookup (consumed by `Component.extendsFrom`
+ *    via the `__componentName` stamped at register time).
+ *  - `defineComponent({...})` — direct static `ComponentDefinition`
+ *    (literal authored shape). Mutated in place — same surface as the
+ *    earlier identity factory.
+ *  - `defineComponent.layers({...})` — multi-layer authoring entry.
+ *    Returns a builder seeded with the named layers; chain `.config`,
+ *    `.render`, and `.preview` from there.
+ */
+interface DefineComponentFn {
+  <const TTag extends string>(htmlTag: TTag): ComponentBuilder<{
+    layers: {
+      root: TagRef<TTag>;
+    };
+  }>;
+  <const T extends ComponentDefinition>(definitionOrParent: T): ComponentBuilder<T>;
+  layers<const L extends Record<string, LayerInput>>(layers: L): ComponentBuilder<{
+    layers: L;
+  }>;
+}
+declare const defineComponent: DefineComponentFn;
+/**
+ * Mutable marker the Provider FC carries on `__udsProvider`. `name`
+ * starts unset; `.registerProviders({ ToastProvider })` writes it to
+ * the registration key so the Provider's `displayName` and the hook's
+ * error message both pick up a meaningful label.
+ */
+interface ProviderMarker {
+  name?: string;
+}
+/**
+ * Render-callback shape `defineProvider` accepts. Returns the context
+ * value and the JSX to render inside the auto-built `Context.Provider`.
+ */
+type ProviderRenderFn<TContext, TProps = Record<never, never>> = (props: {
+  children: ReactNode;
+} & TProps) => {
+  context: TContext;
+  render: ReactNode;
+};
+/**
+ * The Provider FC returned by `defineProvider`. Carries a
+ * non-enumerable `__udsProvider` slot so `.registerProviders({...})`
+ * consumers can identify provider values and back-fill the
+ * registration name.
+ */
+type ProviderComponent<TProps = Record<never, never>> = FC<{
+  children: ReactNode;
+} & TProps> & {
+  readonly __udsProvider: ProviderMarker;
+};
+/**
+ * Legacy alias for the tuple shape `defineProvider` returns. Kept so
+ * existing consumers reaching for `DefinedProvider<TContext, TProps>`
+ * keep compiling.
+ */
+type DefinedProvider<TContext = unknown, TProps = Record<never, never>> = readonly [ProviderComponent<TProps>, () => TContext]; //#endregion
+//#endregion
+export { BoundComponent, ComponentBuilder, ComponentBuilderMethods, ComponentRenderFn, ConfigCallbackHelpers, DefineComponentFn, DefinedComponent, DefinedProvider, DefinedStyleProp, DefinedTokenGroup, PreviewCallbackHelpers, ProviderComponent, ProviderRenderFn, TokenGroupMetadata, TypedSlotRef, boolean, defineComponent, defineComponentGroup, defineCompositeStyle, defineMode, defineModifier, defineMotion, defineStyleProp, defineTokenGroup, number, slot, string, variant };