@yahoo/uds-v5-wip 1.60.0 → 1.61.0

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

@@ -1,9 +1,24 @@
-import { ComponentRef, CompositeRef, RegisteredComponents, StylePropRef } from "./component-refs.js";
-import * as React$1 from "react";
-import { ReactNode } from "react";
+import { CompositeRef, RegisteredComposites, StylePropRef } from "./component-refs.js";
+import { SlotMotionConfig } from "./defineMotionConfig.js";
+import { Props } from "./Props.js";
+import * as _$react from "react";
+import { CSSProperties, ReactNode } from "react";
+import { ArbitraryValue, ModifierProp } from "@uds/types";
 
 //#region ../config/dist/component-config.d.ts
 //#region src/component-config.d.ts
+/**
+ * Style values for a component-config slot. Accepts every registered
+ * style-prop name (per-app `RegisteredStyleProps` augmentation provides
+ * autocomplete), standard CSS properties (camelCase), and modifier
+ * objects (e.g. `_hover: { ... }`). Values are raw CSS strings, token
+ * literals, or `token('ns/name')` markers — not typed token names.
+ */
+type ComponentSlotStyles = { [K in Exclude<string | keyof CSSProperties, 'motion'>]?: string | number | boolean | TokenMarker | undefined } & { [K in ModifierProp]?: ComponentSlotStyles } & {
+  /** Per-slot motion config (JS runtime): co-located with slot styles. */motion?: SlotMotionConfig;
+};
+/** Allowed values for component slot motion in config objects. */
+type ComponentMotionValue<TMotionAlias extends string = string> = SlotMotionConfig | TMotionAlias | ArbitraryValue;
 /**
  * HTML tag literal. The TypeScript type is `string` (any tag name);
  * runtime renders it via `React.createElement(tag, ...)`.
@@ -13,54 +28,78 @@ import { ReactNode } from "react";
  * autocomplete tag names from JSX.
  */
 type HtmlTag = string;
+/**
+ * Per-slot motion descriptor — same shape the legacy `base.<slot>.motion`
+ * carried, surfaced verbatim into the build-time manifest under
+ * `components.<Name>.motion.<slot>`. Codegen does not interpret the
+ * keys; the loader's `applySlotMotionToElement` reads them at JSX
+ * rewrite time, so adding a new field here automatically flows through
+ * once the loader picks it up.
+ *
+ * `runtime: 'css'` opts out — the loader's `getCustomSlotMotion` skips
+ * css-runtime entries (CSS keyframes are handled elsewhere).
+ */
+interface SlotMotion {
+  readonly runtime?: 'js' | 'css';
+  readonly initial?: unknown;
+  readonly animate?: unknown;
+  readonly exit?: unknown;
+  readonly transition?: unknown;
+  readonly whileHover?: unknown;
+  readonly whileTap?: unknown;
+  readonly drag?: unknown;
+  readonly dragConstraints?: unknown;
+  readonly dragElastic?: unknown;
+  readonly dragSnapToOrigin?: unknown;
+  readonly layout?: unknown;
+}
 /**
  * Object form for a primitive (HTML-tag) layer that needs locked attrs
- * or default CSS-property values.
+ * (e.g. `role`, `aria-*`, locked `href`).
  *
  * Distributive mapped union over `keyof React.JSX.IntrinsicElements` so
  * `attrs` is narrowed to the HTML props valid for the chosen `tag` at
  * the call site — `{ tag: 'a', attrs: { href: '/x' } }` type-checks;
- * `{ tag: 'div', attrs: { href: '/x' } }` does not. `defaultProps`
- * stays loosely typed: it carries style-prop-keyed CSS declarations
- * (incl. `_hover`/`_focus`/etc. modifier keys) that feed the @utility
- * codegen, NOT HTML props.
- */
-type PrimitiveLayer = { [T in keyof React$1.JSX.IntrinsicElements]: {
-  tag: T; /** HTML attributes always applied to this layer (e.g. `role="alert"`). */
-  attrs?: Partial<React$1.ComponentPropsWithoutRef<T>>;
-  /**
-   * Default per-layer CSS declarations. Keys are style-prop names (or
-   * raw CSS properties when no registered style prop applies); values
-   * are token refs (`'{spacing/4}'`), alias names, or literal CSS.
-   * Modifier keys (`_hover`, `_focus`, `_dataDisabled`, ...) nest the
-   * same shape recursively. Codegen compiles this into a single
-   * `@utility componentName-layerName { ... }` block.
-   */
-  defaultProps?: Record<string, unknown>;
-} }[keyof React$1.JSX.IntrinsicElements];
+ * `{ tag: 'div', attrs: { href: '/x' } }` does not.
+ *
+ * Per-layer base styles live in the config's top-level
+ * `base: { <layer>: {...} }` block — not inside this object.
+ */
+type PrimitiveLayer = { [T in keyof _$react.JSX.IntrinsicElements]: {
+  tag: T;
+  attrs?: Partial<_$react.ComponentPropsWithoutRef<T>>;
+} }[keyof _$react.JSX.IntrinsicElements];
 /**
- * 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.
+ * Structural shape of a `defineComponent` value as it appears in a
+ * `layers` slot. Mirrors `BoundComponent` from `defineComponent.ts` but
+ * defined locally to avoid the circular import (`defineComponent.ts`
+ * imports types from this file). Authors don't see this shape directly
+ * — they pass the actual `BoundComponent` value, which satisfies it.
  *
- * 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).
+ * The `__config` slot is the discriminator that distinguishes a
+ * composed-component layer from a plain function (which a layer can't
+ * be — guards on the layer position rely on this brand).
  */
-type ComposedLayer = { [K in keyof RegisteredComponents & string]: {
-  component: `{${K}}`;
-  defaultProps?: Partial<RegisteredComponents[K]>;
-} }[keyof RegisteredComponents & string];
+type ComposedComponentValue = _$react.FC< // biome-ignore lint/suspicious/noExplicitAny: any registered component
+any> & {
+  readonly __config: ComponentConfigValue<Record<string, LayerInput>, any, HtmlTag | undefined>;
+};
 /**
- * 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`.
+ * Allowed forms for a single layer's value:
+ *
+ *  - **`HtmlTag`** — bare string (`'div'`, `'span'`, `'a'`, …) for
+ *    plain HTML elements.
+ *  - **`PrimitiveLayer`** — `{ tag, attrs }` object form for HTML
+ *    layers that need locked attributes (`role`, `aria-*`, etc.).
+ *  - **`ComposedComponentValue`** — a `defineComponent`-produced
+ *    value (`Box`, `Pressable`, `Text`, …) used directly as the
+ *    layer value.
+ *
+ * Per-layer base styles always live in the config's top-level
+ * `base: { <layer>: {...} }` block; consumer-facing JSX defaults go
+ * in `defaultProps: { <prop>: value }`.
  */
-type LayerInput = HtmlTag | ComponentRef | PrimitiveLayer | ComposedLayer;
+type LayerInput = HtmlTag | PrimitiveLayer | ComposedComponentValue;
 /**
  * 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
@@ -78,19 +117,24 @@ interface StylePropBinding {
  * 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?: … }`.
+ *  - `layers.root` is a bare tag string (`'a'`),
+ *  - `layers.root` is `{ tag: 'a', attrs?: … }`, or
+ *  - `layers.root` is a component value whose `__config` carries its
+ *    own captured root tag (recurses one level so a wrapper of
+ *    `defineComponent('button', …)` inherits `'button'`).
  *
- * 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.
+ * Returns `undefined` when `layers.root` is a composed-component layer
+ * without a captured tag, or not present. `Props<TConfig>` reads this
+ * and substitutes `React.ComponentPropsWithRef<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;
+} ? T : R extends {
+  readonly __config: ComponentConfigValue<Record<string, LayerInput>, any, infer TInnerTag extends HtmlTag | undefined>;
+} ? TInnerTag : undefined : undefined;
 /**
  * Bind a registered composite to a single layer. Multi-layer composites
  * use the `CompositeBinding` shape instead (see below).
@@ -110,46 +154,168 @@ interface CompositeBinding {
   layers: Record<string, string>;
 }
 /**
- * Forward a JSX prop value to one of the component's layers as an
- * existing surface key. The runtime-side / read-side shape — `layer`
- * and `from` are bare strings. Type-guards in `bindRender` use the
- * absence of `styleProp` / `composite` keys to discriminate this shape
- * from the registered-binding shapes.
+ * 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';
+}
+/**
+ * String-valued prop — parallel to `bool()` but the JSX value is a
+ * string. Each layer's bundle gets `data-<kebab-name>="<value>"` at
+ * render time so CSS can target it (`[data-kind="primary"]`).
  *
- * Authoring sites get the narrower `TypedForwardBinding<TLayers>`
- * (below) via `VerbosePropBinding<TLayers>`, which structurally
- * extends this loose form.
+ * Authored via `string()` in the `props` block — surfaces as a typed
+ * `string` prop at the JSX call site and as a text-input control in
+ * the Studio design panel (driven by the `__kind` discriminator).
  */
+interface StringMarker {
+  readonly __kind: 'string';
+}
 /**
- * Authoring-site form of `ForwardBinding`, narrowed against the
- * component's own layer map. Distributes over `keyof TLayers` so:
+ * Style-prop binding marker — JSX value contributes one resolved
+ * utility class to a layer's bundle, looked up by `ref` in the
+ * registered style-prop registry. The `__kind` discriminator lets
+ * the design panel and codegen branch on prop kind by reading the
+ * marker shape directly.
  *
- *  - `layer` is constrained to one of the declared layer names.
- *  - `from` is constrained by the target layer's shape:
- *      • **ComposedLayer** (`{ component: '{Box}' }`) → one of the
- *        wrapped component's exposed JSX props (looked up against
- *        `RegisteredComponents['Box']`), so `{ layer: 'label', from:
- *        'variant' }` only type-checks if Text registers `variant`.
- *      • **PrimitiveLayer / bare HTML tag** → any string (HTML attr or
- *        event name; type-precision here would require pulling
- *        `JSX.IntrinsicElements[tag]`, deferred).
+ * Authored via the `styleProp` helper passed into the
+ * `defineComponent` callback. Two forms:
  *
- * Structurally extends `ForwardBinding` so the runtime's type-guard
- * (`isForwardBinding`) still recognizes typed entries.
+ *   styleProp('bg')                  // root layer, shorthand
+ *   styleProp('label', 'color')      // explicit layer
  */
-type TypedForwardBinding<TLayers extends Record<string, LayerInput>> = { [K in keyof TLayers & string]: {
-  layer: K;
-  from: TLayers[K] extends {
-    component: `{${infer C}}`;
-  } ? C extends keyof RegisteredComponents ? keyof RegisteredComponents[C] & string : string : string;
-} }[keyof TLayers & string];
+interface StylePropMarker<TLayer extends string = string, TRef extends string = string> {
+  readonly __kind: 'styleProp';
+  readonly layer: TLayer;
+  readonly ref: TRef;
+  /**
+   * Re-target the marker to a different layer. Returns a fresh marker
+   * carrying the same `ref` but with `layer` set to `name`:
+   *
+   *     styleProp('color').on('label')
+   *     // → { __kind: 'styleProp', ref: 'color', layer: 'label' }
+   */
+  on<TNewLayer extends string>(name: TNewLayer): StylePropMarker<TNewLayer, TRef>;
+}
 /**
- * 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.
+ * Token-reference marker for use inside style values (`base`, `enums`,
+ * `compoundProps`). The value tells codegen "look up the token at
+ * path `<namespace>/<name>`" — it resolves to `var(--<prefix>-<ns>-<name>)`
+ * at build time. The `__kind` discriminator lets the design panel
+ * detect a token reference and offer a token picker.
+ *
+ * Authored via the `token(...)` helper:
+ *
+ *   base: { root: { bg: token('bg/brand') } }
  */
-interface BoolMarker {
-  readonly __kind: 'bool';
+interface TokenMarker<TRef extends string = string> {
+  readonly __kind: 'token';
+  readonly ref: TRef;
+}
+/**
+ * Token-group reference marker for `defineStyleProp({ values: [...] })`
+ * entries. Tells the resolver "every token in this namespace is a
+ * valid value for this style prop" — so `tokenGroup('spacing')` on a
+ * `padding` prop pulls in `spacing/1`, `spacing/2`, … as accepted
+ * values that map to `p-1`, `p-2`, … utility classes.
+ *
+ * Authored via the `tokenGroup(...)` helper.
+ */
+interface TokenGroupMarker<TGroup extends string = string> {
+  readonly __kind: 'tokenGroup';
+  readonly group: TGroup;
+}
+/**
+ * Slot prop — JSX-prop that accepts a `ReactNode` and routes it onto a
+ * named layer's bundle. Authored via `slot('layerName')` in the
+ * `props` block:
+ *
+ *     defineComponent({
+ *       layers: { root: 'div', title: 'div', content: 'div' },
+ *       props: {
+ *         title: slot('title'),
+ *         content: slot('content'),
+ *       },
+ *     }).render(({ props, children }) => (
+ *       <div {...props.root}>
+ *         <div {...props.title} />     // renders the `title` JSX prop
+ *         <div {...props.content} />   // renders the `content` JSX prop
+ *         {children}
+ *       </div>
+ *     ));
+ *
+ * **Children routing (default).** Without `as`, the runtime puts the
+ * incoming value on `bundles[layer].children`, so spreading the layer
+ * bundle places the children automatically.
+ *
+ * **Named-prop routing (`{ as }`).** With `as: 'propName'`, the runtime
+ * puts the value on `bundles[layer][propName]` instead — useful when
+ * the layer is a composed component that already exposes its own
+ * named slots (`startContent`, `endContent`, …). Lets a wrapper like
+ * `EnhancedCard` declare its own JSX prop that forwards into the
+ * wrapped `Card`'s slot surface:
+ *
+ *     const EnhancedCard = defineComponent({
+ *       layers: { root: Card },                       // Card as a layer
+ *       props: {
+ *         headline: slot('root', { as: 'startContent' }),  // → Card.startContent
+ *         cta:      slot('root', { as: 'endContent' }),    // → Card.endContent
+ *       },
+ *     });
+ *
+ * Codegen treats slot props as the canonical signal of named slots:
+ * each `slot()` entry in a `props` block becomes both a `ReactNode`
+ * prop in the catalog (typed as `string | { $slot: elementKey }` in
+ * json-render) AND adds the JSX-prop key to the prompt's
+ * `[slots: ...]` tag. Replaces the verbose `{ layer, from: 'children' }`
+ * forward binding for the common ReactNode-into-layer case.
+ */
+interface SlotMarker<TLayer extends string = '', TProp extends string = 'children'> {
+  readonly __kind: 'slot';
+  /**
+   * Target layer the incoming JSX value routes onto. Empty string
+   * (`slot()` with no path) means the value is *not* routed — the
+   * marker just declares the JSX-prop key + types it as
+   * `ReactNode`; the render function receives the value verbatim in
+   * its args.
+   */
+  readonly layer: TLayer;
+  /**
+   * Target prop name on the layer's bundle. Defaults to `'children'`,
+   * which is what most slots want (the value lands as the layer
+   * element's children). Set to a different name to route into
+   * arbitrary props on the target layer's surface (`onClick`,
+   * `aria-label`, `startContent`, …).
+   */
+  readonly prop?: TProp;
+}
+/**
+ * Composite-style prop — the JSX value picks one entry from a
+ * registered composite group's `styles` map. The runtime expands
+ * the matched style bag into the layer's bundle and emits a marker
+ * class. Implicit `'root'` layer target.
+ *
+ * Authored via `composite('textVariant')` (bare name — narrowed
+ * against the registered composite names) in the `props` block:
+ *
+ *     defineComponent(Box, {
+ *       defaultProps: { as: 'p' },
+ *       props: {
+ *         variant: composite('textVariant'),
+ *       },
+ *     });
+ *
+ * For multi-layer composites or non-root layer targets, use the
+ * verbose `{ composite: '{ref}', layers: {...} }` /
+ * `{ layer: 'X', composite: '{ref}' }` binding shapes directly (the
+ * verbose forms keep the brace-ref shape for consistency with
+ * style-prop refs).
+ */
+interface CompositeMarker<TRef extends string = string> {
+  readonly __kind: 'composite';
+  readonly ref: TRef;
 }
 /**
  * Enum prop — the value picks one entry from a map. Each entry can
@@ -173,19 +339,14 @@ interface EnumMarker<TValues extends Record<string, unknown>> {
  */
 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`).
- *
- * Generic over `TLayers` so `TypedForwardBinding` can narrow the
- * `layer` + `from` fields against the component's own layer map.
- * Consumers that don't know the layer map (read-side helpers,
- * `bindRender`) parameterize with the wide default
- * `Record<string, LayerInput>` and get the loose `ForwardBinding`.
+ * Every allowed shape for a single entry in a `props` block. Each
+ * shape comes from a marker helper (`styleProp`, `slot`, `bool`,
+ * `string`, `enums`, `composite`) and carries an introspectable
+ * `__kind` discriminator. `TLayers` parameterizes the layer-bound
+ * markers (`slot('layer/prop')`, `styleProp('bg').on('layer')`) so
+ * typos in layer names surface at the authoring site.
  */
-type VerbosePropBinding<TLayers extends Record<string, LayerInput> = Record<string, LayerInput>> = StylePropBinding | SingleLayerCompositeBinding | CompositeBinding | TypedForwardBinding<TLayers> | BoolMarker | EnumMarker<any>;
+type VerbosePropBinding<TLayers extends Record<string, LayerInput> = Record<string, LayerInput>> = StylePropMarker<keyof TLayers & string, string> | StylePropBinding | SingleLayerCompositeBinding | CompositeBinding | CompositeMarker | BoolMarker | StringMarker | EnumMarker<any> | SlotMarker<(keyof TLayers & string) | '', string>;
 /**
  * All allowed shapes for a single entry in the primitive form's `props`
  * block. Primitive form adds the `StylePropShorthand` brace-ref
@@ -207,93 +368,259 @@ type PropBinding<TLayers extends Record<string, LayerInput> = Record<string, Lay
  *       loading: bool(),
  *       disabled: bool(),
  *     }
+ *
+ * Drives both the TS type (consumer sees `loading?: boolean`) and the
+ * Studio design panel control (toggle).
  */
+declare function bool(): BoolMarker;
 /**
- * Names of prop bindings that participate in matrix/strip iteration —
- * i.e. props authored as `enums({...})` or `bool()`. Other prop bindings
- * (style props, forwards, composites) don't have a fixed enumerable
- * set of values to iterate over and so aren't valid axes.
+ * Marker for a string-valued JSX prop. Parallel to `bool()` — emits
+ * `data-<kebab-name>="<value>"` on each layer's bundle so CSS can
+ * target the rendered value. Use inside the `props` block:
  *
- * Resolves to `never` when `TProps` declares no enum/bool bindings.
+ *     props: {
+ *       kind: string(),
+ *       tone: string(),
+ *     }
+ *
+ * Drives both the TS type (consumer sees `kind?: string`) and the
+ * Studio design panel control (text input).
  */
-type IterableAxisOf<TProps> = { [K in keyof TProps]: TProps[K] extends EnumMarker<Record<string, unknown>> | BoolMarker ? K : never }[keyof TProps] & string;
+declare function string(): StringMarker;
 /**
- * A single example entry — describes one cell, one row, or one matrix.
+ * Bind a registered style prop. Single string arg defaults to the
+ * root layer; chain `.on(layerName)` to target a non-root layer:
  *
- * Three iteration shapes are supported, distinguished by which fields
- * are present:
+ *     props: {
+ *       bg:        styleProp('bg'),                  // root layer
+ *       textColor: styleProp('color').on('label'),   // label layer
+ *     }
  *
- * - Static: only `props`. Renders one cell with `props` as the consumer-
- *   facing prop values.
- * - 1D strip: `axis` plus `props`. Iterates the named enum/bool prop and
- *   renders one cell per value.
- * - 2D matrix: `rows` and `cols` plus `props`. Iterates both and renders
- *   the Cartesian product as a labeled grid.
+ * The `__kind: 'styleProp'` discriminator lets the design panel render
+ * a color/token picker (driven by the registered style prop's value
+ * space) and lets codegen scan props uniformly off the marker shape.
+ */
+declare function styleProp<TRef extends string>(ref: TRef): StylePropMarker<'root', TRef>;
+/**
+ * Token-reference marker for style values. Use inside `base`, enum
+ * entries, and `compoundProps` overrides:
  *
- * `axis` and `rows`/`cols` are mutually exclusive; `rows` and `cols`
- * must appear together. The runtime validator enforces both.
+ *     base: { root: { bg: token('bg/brand') } }
+ *     props: {
+ *       variant: enums({
+ *         brand: { root: { color: token('color/on-brand') } },
+ *       }),
+ *     }
  *
- * `props` is keyed by *consumer-facing prop name* — the same names a
- * caller of `<Link href='#'>` would pass — not by internal layer name.
- * The renderer maps consumer props to layer bundles using the
- * component's own `props` bindings.
+ * Codegen and runtime detect the `__kind: 'token'` discriminator and
+ * resolve the `ref` to `var(--<prefix>-<ns>-<name>)`. The design
+ * panel uses the same discriminator to offer a token picker.
+ */
+declare function token<TRef extends string>(ref: TRef): TokenMarker<TRef>;
+/**
+ * Token-group reference for `defineStyleProp({ values: [...] })`. Pulls
+ * every token in the named namespace into the style prop's accepted
+ * value set. The resolver expands the group at registration time:
+ *
+ *     defineStyleProp({
+ *       cssProperty: 'padding',
+ *       classPrefix: 'p',
+ *       values: [tokenGroup('spacing')],   // → p-1, p-2, p-3, …
+ *     })
  *
- * Authors don't control wrapper layout (gaps, padding, alignment) — the
- * renderer (Studio / docs) owns those decisions so the matrix surface
- * stays consistent across components.
+ * The `__kind: 'tokenGroup'` discriminator lets codegen and the design
+ * panel branch on group references without parsing strings.
  */
-interface ExampleEntry<TAxis extends string = string> {
-  /** 1D iteration — one cell per value of this enum/bool prop. */
-  axis?: TAxis;
-  /** 2D iteration — rows × cols matrix. Mutually exclusive with `axis`. */
-  rows?: TAxis;
-  cols?: TAxis;
-  /**
-   * Consumer-facing prop values used by every cell. For 1D / 2D entries,
-   * the cell's axis coords are overlaid on top of these (axis values win
-   * on collision with `props.<axis>`).
-   */
-  props?: Record<string, unknown>;
-}
+declare function tokenGroup<TGroup extends string>(group: TGroup): TokenGroupMarker<TGroup>;
+/**
+ * Marker for an enum-valued JSX prop. Each value maps to a per-layer
+ * style override. Use inside the `props` block:
+ *
+ *     props: {
+ *       variant: enums({
+ *         brand: { root: { bg: '{bg/brand}', color: '{color/on-brand}' } },
+ *         ghost: { root: { color: '{color/on-primary}' } },
+ *       }),
+ *     }
+ *
+ * The shape of each value mirrors a partial layer-style map keyed by
+ * the component's own layer names.
+ */
+declare function enums<const TValues extends Record<string, unknown>>(values: TValues): EnumMarker<TValues>;
+/**
+ * Marker for a composite-style JSX prop. The JSX value picks one
+ * entry from the referenced composite group's `styles` map; the
+ * runtime expands the matched style bag onto the root layer's bundle
+ * and emits a marker class.
+ *
+ *     // packages/.../text-variant.ts
+ *     export const textVariant = defineCompositeStyle({
+ *       label: 'Text Variant',
+ *       styles: {
+ *         body: { fontSize: '[1rem]', fontWeight: 'normal' },
+ *         heading: { fontSize: '[1.5rem]', fontWeight: 'bold' },
+ *       },
+ *     });
+ *
+ *     // apps/<consumer>/uds.config.ts
+ *     udsBuilder.registerComposites({ textVariant });
+ *
+ *     // The component:
+ *     export const Text = defineComponent(Box, {
+ *       defaultProps: { as: 'p' },
+ *       props: {
+ *         variant: composite('textVariant'),
+ *       },
+ *     });
+ *
+ * Argument is the bare composite name (no `{...}` brace wrapping) —
+ * the `composite()` function's position already establishes the
+ * composite-ref context, so the braces would be redundant. Authoring
+ * sites type-narrow `ref` against `keyof RegisteredComposites` so
+ * typos surface as compile errors.
+ *
+ * Layer target is implicit `'root'`. For multi-layer composite
+ * bindings or non-root layer targets, drop down to the verbose
+ * `{ layer: 'X', composite: '{ref}' }` /
+ * `{ composite: '{ref}', layers: {...} }` shapes (those keep the
+ * brace-ref form for consistency with style-prop refs).
+ */
+type CompositeName = [keyof RegisteredComposites] extends [never] ? string : keyof RegisteredComposites & string;
+declare function composite<TRef extends CompositeName>(ref: TRef): CompositeMarker<TRef>;
 /**
- * Component examples — required `default` plus any number of additional
- * named entries. `default` is the canonical single-instance showcase
- * Studio + docs fall back to when no specific example is requested.
+ * Splits a `'layer/prop'` slot path into its two segments. Mirrors the
+ * `{namespace/name}` token-ref convention — the slash is the delimiter
+ * and the second segment is the target prop on the layer's bundle.
+ * When no slash is present, the path is a bare layer name and the
+ * target prop defaults to `'children'`.
+ */
+type SplitSlotPath<T extends string> = T extends `${infer L}/${infer A}` ? [L, A] : [T, 'children'];
+/**
+ * Marker for a layer-targeted JSX-prop binding. Routes the incoming
+ * JSX value into `bundles[layer][prop]` at render time. The prop's
+ * TS value type is inferred from the target layer's surface — see
+ * `SlotPropValue` in `Props.ts`.
+ *
+ * Authoring forms:
  *
- * `default` is distinct from `defaultProps`: `defaultProps` is the
- * runtime API default applied when a consumer omits a prop; `examples.default`
- * is the showcase content (label, icons, href) used by tooling. A
- * component can declare both without conflict.
+ * - **Canonical: `slot('layer/prop')`** — slash-separated path. The
+ *   first segment names a declared layer; the second names the prop
+ *   on that layer's bundle where the JSX value lands.
  *
- * Axis types narrow to `IterableAxisOf<TProps>` so referencing a non-
- * enum/bool prop name in `axis` / `rows` / `cols` is a type error.
+ *       props: {
+ *         title:    slot('triggerText/children'),  // → Text.children
+ *         onClick:  slot('button/onClick'),        // → button's onClick
+ *         headline: slot('root/startContent'),     // → Card.startContent
+ *       }
+ *
+ * - **Sugar: `slot('layer')`** — equivalent to `slot('layer/children')`.
+ *
+ * - **Object form: `slot('layer', { prop: 'name' })`** — same as
+ *   `slot('layer/name')` but reads better when `name` is a long
+ *   identifier or contains characters the slash form can't carry.
+ *
+ * - **No-arg: `slot()`** — type-only declaration. The JSX value is
+ *   typed as `ReactNode` and flows through to the render fn's args
+ *   verbatim (no layer routing). Use for `children: slot()` to
+ *   declare children without routing them to a specific layer.
+ *
+ * The marker is the canonical signal — to codegen and to json-render
+ * — that this JSX prop is a named slot.
  */
-type Examples<TProps extends Record<string, unknown> = Record<string, unknown>> = {
-  default: ExampleEntry<IterableAxisOf<TProps>>;
-} & Record<string, ExampleEntry<IterableAxisOf<TProps>>>;
+declare function slot(): SlotMarker<'', 'children'>;
+declare function slot<const TPath extends string>(path: TPath): SlotMarker<SplitSlotPath<TPath>[0], SplitSlotPath<TPath>[1]>;
+declare function slot<const TLayer extends string, const TProp extends string>(layer: TLayer, options: {
+  prop: TProp;
+}): SlotMarker<TLayer, TProp>;
 /**
- * A compound-variant entry — applies a per-layer style override when
- * *all* `conditions` match the incoming JSX props. Mirrors the legacy
- * `compoundVariants: [{ conditions, styles }]` shape (see
- * `componentCompoundClass()` for the emitted class name).
+ * Per-layer override shape, narrowed by the layer's declared form.
+ *
+ * Same shape as a single enum-value's per-layer style map — registered
+ * style props, CSS properties, and `_hover`/`_focus`/etc. modifier
+ * keys. Uniform across all layer forms (HTML tag, PrimitiveLayer, and
+ * ComposedLayer) because `ComposedLayer.defaultProps` is also
+ * `Record<string, unknown>` and narrowing here would over-constrain
+ * authoring relative to the layer's own surface.
  *
- *     compoundVariants: [
+ * Authors use `hidden()` (a sibling marker) to hide a layer entirely;
+ * style-map values never carry the `hidden` flag inline.
+ */
+type LayerOverride = ComponentSlotStyles;
+/**
+ * Marker that hides an entire layer when the parent `compoundProps`
+ * entry matches. Separated from the style-map shape so authors don't
+ * mix structural visibility with style overrides inline.
+ *
+ * V1 `applyCompoundProps` translates a hidden layer to `display: none`
+ * on the resolved bundle — the DOM node still renders; see UDS-1631's
+ * open questions for the "strip entirely" follow-up.
+ */
+interface HiddenMarker {
+  readonly __kind: 'hidden';
+}
+/**
+ * Marker factory — use inside `compoundProps[].layers.<layer>` to hide
+ * a layer entirely when the entry's `when` clause matches.
+ *
+ *     compoundProps: [
  *       {
- *         conditions: { size: 'sm', variant: 'brand' },
- *         styles: { root: { boxShadow: '{shadow/sm}' } },
+ *         when: { variant: 'compact' },
+ *         layers: { endIcon: hidden() },
  *       },
  *     ]
+ */
+declare function hidden(): HiddenMarker;
+/**
+ * Names of prop bindings that participate in `when` clauses — i.e.
+ * props authored as `enums({...})` or `bool()`. Other bindings (style
+ * props, forwards, composites) don't have a fixed enumerable value set
+ * and so aren't valid `when` keys. File-private — re-inlined here
+ * after the original `IterableAxisOf` was removed from the public
+ * surface along with the matrix-examples API.
+ */
+type IterableAxisOf<TProps> = { [K in keyof TProps]: TProps[K] extends EnumMarker<Record<string, unknown>> | BoolMarker ? K : never }[keyof TProps] & string;
+/**
+ * Resolve the legal value set for an iteration axis. `enums({...})` →
+ * the union of value keys; `bool()` → `boolean`. Used to narrow per-
+ * coord values in `compoundProps.when`. File-private (see `IterableAxisOf`).
+ */
+type PropValuesOf<TBinding> = TBinding extends EnumMarker<infer TValues> ? keyof TValues & string : TBinding extends BoolMarker ? boolean : never;
+/**
+ * A `compoundProps` `when` clause: partial map of iterable-axis prop
+ * names → required value. All listed keys must match the active props
+ * for the entry to apply. Keys narrow to enum/bool bindings only — so
+ * non-enum/non-bool props (style props, forwards, composites) are a
+ * type error at the authoring site. Values narrow to declared enum
+ * keys or `boolean`.
+ */
+type WhenClause<TProps> = { [K in IterableAxisOf<TProps>]?: K extends keyof TProps ? PropValuesOf<TProps[K]> : never };
+/**
+ * A single `compoundProps` entry — applies per-layer overrides when
+ * *all* `when` keys match the active prop values.
  *
- * `conditions` keys are JSX-prop names that resolve to `enums()` /
- * `bool()` markers in the `props` block; values are the variant values
- * (or `'true'` / `'false'` for bools) that must all match for the entry
- * to apply. Codegen emits one `@utility componentName-layerName--<sorted
- * conditions>` block per (layer); runtime appends that class when
- * conditions match.
+ *     compoundProps: [
+ *       {
+ *         when: { variant: 'secondary', textVariant: 'legal1' },
+ *         layers: {
+ *           root:    { color: '{color/tertiary}' },
+ *           endIcon: hidden(),
+ *         },
+ *       },
+ *     ]
+ *
+ * Multiple entries can match a given combination — specificity (number
+ * of keys in `when`) decides who wins per layer-property pair; ties
+ * break by source order (later wins).
  */
-interface CompoundVariant {
-  conditions: Record<string, string>;
-  styles: Record<string, Record<string, unknown>>;
+interface CompoundPropsEntry<TLayers extends Record<string, LayerInput>, TProps extends Record<string, unknown> = Record<string, unknown>> {
+  when: WhenClause<TProps>;
+  /**
+   * Per-layer overrides. Style maps narrow against `ComponentSlotStyles`
+   * (registered style props + CSS properties + modifier keys); use
+   * `hidden()` to hide a layer entirely. Layer keys narrow to the
+   * component's declared layer names.
+   */
+  layers: { [K in keyof TLayers & string]?: LayerOverride | HiddenMarker };
 }
 /**
  * The architecture-doc-target component config. Distinct from today's
@@ -304,6 +631,149 @@ interface CompoundVariant {
  * narrow their `layer` field against the component's actual layer
  * names; typos surface at the authoring site.
  */
+/**
+ * Static, always-on per-layer styles + props for verbose-form
+ * `defineComponent({...})`. Keyed by layer name — each value is
+ * `Partial<Props<TLayer>>` where `TLayer` is the layer's resolved
+ * component (Box / Pressable / Text / …). Mirrors the legacy
+ * `defineComponents({ <Name>: { base: { <slot>: {...} } } })`
+ * shape — `base` styles are unconditional, contrasted with the
+ * `props` block where `enums()` / `composite()` / style-prop
+ * bindings associate styles with consumer-controllable values.
+ *
+ *     defineComponent({
+ *       layers: { trigger: { component: Pressable } },
+ *       base: {
+ *         trigger: { padding: '4' },  // ✗ ERROR — Pressable exposes `spacing`, not `padding`
+ *         trigger: { spacing: '4' },  // ✓
+ *       },
+ *     });
+ *
+ * Composed-component layers narrow to the wrapped component's prop
+ * surface via `Props<TLayer['__config']>` — catches style-prop typos
+ * at the authoring site. Bare-tag layers (`'div'`) fall back to
+ * `Record<string, unknown>` since they don't have a component-side
+ * prop registry; those layers' styles go through `prepareCss` as
+ * `@utility` CSS rules instead.
+ *
+ * `base[<layer>].as` on a composed layer overrides the layer's
+ * rendered tag (mirroring the existing primitive-form behavior).
+ */
+/**
+ * Resolves the accepted JSX-value shape for a single prop binding —
+ * what `defaultProps` for that binding should be typed as.
+ *
+ *  - `EnumMarker` → the union of declared value keys.
+ *  - `BoolMarker` → `boolean`.
+ *  - `CompositeMarker` → registered composite-value keys (loosely
+ *    typed `string` here; consumer apps' augmentation refines it).
+ *  - `SlotMarker` → `ReactNode` (slot-position values).
+ *  - `BoolMarker` etc. follow.
+ *  - Style-prop bindings (`'{bg}'` shorthand or
+ *    `{ layer, styleProp: '{bg}' }`) → string (the resolved token
+ *    or alias name; precise narrowing happens at the consumer's
+ *    augmented-types boundary).
+ *  - Everything else → `unknown`.
+ */
+type BindingValueType<T> = T extends EnumMarker<infer V> ? keyof V & string : T extends BoolMarker ? boolean : T extends StringMarker ? string : T extends StylePropMarker ? string : T extends CompositeMarker ? string : T extends SlotMarker ? _$react.ReactNode : T extends string ? string : T extends {
+  readonly styleProp: string;
+} ? string : unknown;
+/**
+ * `defaultProps` for verbose-form `defineComponent({...})` —
+ * type-narrowed against the keys + binding values declared in the
+ * `props` block. Catches typos / wrong-value assignments at the
+ * authoring site:
+ *
+ *     props: {
+ *       variant: enums({ brand: {...}, ghost: {...} }),
+ *       loading: bool(),
+ *     },
+ *     defaultProps: {
+ *       variant: 'brand',  // ✓
+ *       variant: 'extra',  // ✗ — not a declared enum value
+ *       loading: false,    // ✓
+ *       typo: 'foo',       // ✗ — not a declared prop key
+ *     }
+ */
+type BindingValueDefaults<TProps> = { [K in keyof TProps]?: BindingValueType<TProps[K]> };
+type LayerBaseStyles<TLayers extends Record<string, LayerInput>> = { [K in keyof TLayers]?: TLayers[K] extends {
+  readonly __config: infer TLayerConfig;
+} ? TLayerConfig extends ComponentConfigValue<Record<string, LayerInput>, any, HtmlTag | undefined> ? Partial<Props<TLayerConfig>> : Record<string, unknown> : Record<string, unknown> };
+/**
+ * Per-layer motion descriptors for verbose-form
+ * `defineComponent({...})`. Keyed by layer name; each value is a
+ * {@link SlotMotion} (framer-motion `initial`/`animate`/`exit`/
+ * `transition`/etc. shape). Codegen surfaces these into the manifest
+ * under `components.<Name>.motion.<slot>` and uses them to rewrite
+ * the slot's JSX into a motion-wrapped element at build time —
+ * `<Box {...props.icon}>` becomes `<motion.create(Box) ...>` and
+ * conditional renders are wrapped in `<AnimatePresence>` when
+ * `exit` is set.
+ */
+type LayerMotion<TLayers extends Record<string, LayerInput>> = { [K in keyof TLayers]?: SlotMotion };
+interface ComponentConfigInput<TLayers extends Record<string, LayerInput>, TProps extends Record<string, VerbosePropBinding<TLayers>> = Record<string, VerbosePropBinding<TLayers>>> {
+  layers: TLayers;
+  props?: TProps;
+  /**
+   * Static per-layer styles + props applied unconditionally to every
+   * render. Each key is a layer name from `layers`; each value is
+   * `Partial<Props<that-layer's-component>>`. See {@link LayerBaseStyles}.
+   *
+   *     base: {
+   *       root: { borderWidth: 'thin', bg: 'primary' },
+   *       trigger: { spacing: '4', _hover: { bg: 'tertiary' } },
+   *     }
+   *
+   * Variant-controlled styles (per consumer JSX value) go through
+   * `enums()` / `composite()` / style-prop bindings in the `props`
+   * block. `base` is the always-on foundation; `props` adds
+   * value-driven overrides on top.
+   *
+   * Type-checked per layer — typos on composed layers surface as TS
+   * errors at the authoring site.
+   */
+  base?: LayerBaseStyles<TLayers>;
+  /**
+   * Default values for the consumer-controllable JSX props declared
+   * in the `props` block. Keys narrow against `keyof TProps`; values
+   * narrow against each binding's accepted shape (enum keys for
+   * `enums()`, composite values for `composite()`, registered tokens
+   * for style-prop bindings, `boolean` for `bool()`).
+   *
+   *     props: {
+   *       variant: enums({ brand: {...}, ghost: {...} }),
+   *       loading: bool(),
+   *     },
+   *     defaultProps: {
+   *       variant: 'brand',   // narrows to `keyof enum.values`
+   *       loading: false,
+   *       typo: '...',        // ✗ ERROR — not a declared prop
+   *     }
+   */
+  defaultProps?: BindingValueDefaults<TProps>;
+  /**
+   * Per-layer motion descriptors. Keyed by layer name; each value is
+   * a {@link SlotMotion} (framer-motion shape). See {@link LayerMotion}.
+   *
+   *     motion: {
+   *       icon: {
+   *         animate: { 'data-state': { open: { rotate: 180 }, closed: { rotate: 0 } } },
+   *         transition: { duration: 0.2 },
+   *       },
+   *       content: {
+   *         initial: { height: 0, opacity: 0 },
+   *         animate: { height: 'auto', opacity: 1 },
+   *         exit: { height: 0, opacity: 0 },
+   *       },
+   *     }
+   */
+  motion?: LayerMotion<TLayers>;
+  /**
+   * Per-combination layer overrides keyed on enum/bool prop values.
+   * See {@link CompoundPropsEntry}.
+   */
+  compoundProps?: CompoundPropsEntry<TLayers, TProps>[];
+}
 /**
  * Branded shape returned by `defineComponent({...})`. Carries `layers`,
  * `props`, AND a phantom `__tag` slot as const-narrowed types so
@@ -332,18 +802,61 @@ interface ComponentConfigValue<TLayers extends Record<string, LayerInput>, TProp
   readonly __componentName?: string;
   readonly layers: TLayers;
   readonly props?: TProps;
+  /**
+   * Static per-layer styles, keyed by layer name. Codegen's
+   * downleveler spreads each entry into the layer's runtime bundle.
+   * Distinct from `defaultProps`, which carries declared-prop
+   * defaults.
+   */
+  readonly base?: Record<string, Record<string, unknown>>;
+  /**
+   * Per-layer motion descriptors keyed by layer name. Same shape as
+   * `LayerMotion<TLayers>` (loosened here so the read-side type
+   * doesn't require parameterizing against TLayers' Props).
+   */
+  readonly motion?: Record<string, SlotMotion>;
   readonly defaultProps?: Record<string, unknown>;
-  readonly compoundVariants?: CompoundVariant[];
   /**
-   * Component examples — see {@link Examples}. Carried through from
-   * `ComponentConfigInput.examples`.
+   * Per-combination layer overrides — see {@link CompoundPropsEntry}.
+   * Carried through from `ComponentConfigInput.compoundProps`.
    */
-  readonly examples?: Examples<TProps>;
+  readonly compoundProps?: CompoundPropsEntry<TLayers, TProps>[];
+  /**
+   * Authoring metadata (description, events) attached via the bound
+   * component's `.metadata({...})` chain. Stored non-enumerably on
+   * the config object so `JSON.stringify` output stays clean. Read by
+   * codegen's prompt + catalog generators.
+   *
+   * `acceptsChildren` isn't stored here — codegen derives it from
+   * `layers` + `props` shape so authors don't have to declare what's
+   * already obvious from the config (primitive + value-extend forms
+   * accept children unconditionally; verbose form derives from
+   * `ForwardBinding { from: 'children' }`).
+   */
+  readonly metadata?: {
+    readonly description?: string;
+    readonly events?: readonly string[];
+  };
 }
 /**
  * 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.
  */
+interface LayerBundle {
+  /** Resolved CSS class names for this layer. Omitted when empty so the
+   *  rendered HTML doesn't carry a literal `class=""` attribute. */
+  className?: string;
+  [key: string]: unknown;
+}
+/**
+ * Derive the render-function argument shape from a component config
+ * type. The render fn receives `props: { <each layer>: LayerBundle }`
+ * plus `children` (always present at the React level).
+ */
+type RenderArgs<TConfig extends ComponentConfigValue<Record<string, LayerInput>>> = {
+  props: { [K in keyof TConfig['layers']]: LayerBundle };
+  children?: ReactNode;
+} & Record<string, unknown>; //#endregion
 //#endregion
-export { BoolMarker, ComponentConfigValue, ComposedLayer, CompositeBinding, CompoundVariant, EnumMarker, HtmlTag, LayerInput, PrimitiveLayer, PrimitivePropBinding, PropBinding, RootTag, SingleLayerCompositeBinding, StylePropBinding, StylePropShorthand, VerbosePropBinding };
+export { BoolMarker, ComponentConfigInput, ComponentConfigValue, ComponentMotionValue, ComponentSlotStyles, CompositeBinding, CompositeMarker, CompoundPropsEntry, EnumMarker, HiddenMarker, HtmlTag, LayerBundle, LayerInput, LayerOverride, PrimitiveLayer, PrimitivePropBinding, PropBinding, RenderArgs, RootTag, SingleLayerCompositeBinding, SlotMarker, SlotMotion, SplitSlotPath, StringMarker, StylePropBinding, StylePropMarker, StylePropShorthand, TokenGroupMarker, TokenMarker, VerbosePropBinding, WhenClause, bool, composite, enums, hidden, slot, string, styleProp, token, tokenGroup };