@yahoo/uds-create-config 2.45.0 → 3.0.1

package/dist/factories.d.ts

@@ -1,863 +0,0 @@
-import { MotionName, RegisteredModifiers, TagRef, TokenGroupRef, TokenRawNameRegistry, composite, styleProp, token } from "./refs.js";
-import { darken, lighten } from "./colorExpressions.js";
-import { ComponentDefinition, ComponentGroupDefinition, ComponentMetadata, CompositeStyleDefinition, LayerInput, ModeDefinition, ModifierDefinition, MotionDefinitionInput, MotionMetadata, PreviewDefinition, RefElement, SlotMotion, StylePropDefinition, StylePropMetadata, StylePropProperty, TokenDefinition } from "./types.js";
-import { BooleanMarker, ComponentSlotMarker, LayerMarker, MotionMarker, NumberMarker, PreviewAxisMarker, PreviewPropsRule, RequiredBrand, SlotMarker, SlotRef, SlotValueType, StringMarker, VariantMarker, VariantMarkerArray, VariantMarkerObject } from "./markers.js";
-import { BaseLayerStyles, LayerPropsMap, LayerTag, Props, PropsFromBindings, SlotPropValue } from "./Props.js";
-import { defineProvider } from "./defineProvider.js";
-import { ComponentPropsWithRef, ComponentRef, ComponentType, ElementType, FC, HTMLAttributes, JSX, ReactElement, ReactNode, Ref } from "react";
-
-//#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>;
-};
-/** Shared implementation shape used by platform-specific token definitions. */
-type DefinedTokenGroupValue<T extends Record<string, {
-  value: unknown;
-}>> = {
-  tokens: T;
-  label?: string;
-  description?: string;
-  metadata(meta: TokenGroupMetadata): DefinedTokenGroupValue<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;
-/**
- * `defineMotion` return shape — the authored motion definition plus a
- * non-enumerable, chainable `.metadata({...})` that lands `label` /
- * `description` as top-level fields on the definition. Mirrors
- * {@link DefinedTokenGroup}: the method name never collides with the data keys,
- * so calls accumulate. `Config.registerMotion` reads `label` / `description`
- * into the `MotionDef`, round-tripping through `Config.toJSON` / `fromJSON`.
- */
-type DefinedMotion<T extends MotionDefinitionInput> = T & {
-  label?: string;
-  description?: string;
-  metadata(meta: MotionMetadata): DefinedMotion<T>;
-};
-/**
- * Author a motion preset. Accepts the same `{ runtime, ... }` shape passed to
- * `.registerMotion({...})`. Author-side `label` / `description` attach via the
- * chained `.metadata({...})`, mirroring `defineTokenGroup`.
- */
-declare function defineMotion<const T extends MotionDefinitionInput>(t: T): DefinedMotion<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 `@yahoo/uds-create-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>;
-/**
- * `asChild()` — opt a **single-layer** component into the polymorphic-child
- * Slot pattern. Declare it as a prop (`props: { asChild: asChild() }`); when a
- * consumer passes `asChild`, the component merges its computed props (className,
- * style props, handlers) onto its single child element instead of rendering its
- * own tag — codegen wires the `_renderAsChild` Slot. Typed as a boolean prop
- * (`asChild?: boolean`), so no extra type plumbing.
- *
- * Opt-in only and single-layer only: multi-layer composites render multiple
- * children and can't slot a single child, so the codegen Slot branch is emitted
- * solely for inline single-layer FCs.
- */
-declare function asChild(): 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 `@yahoo/uds-create-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>>;
-/** `string()`'s chain surface — `.required()` and `.toggle()`, chainable in
- *  either order. */
-type StringChainable = StringMarker & {
-  required(): StringChainable & RequiredBrand;
-  toggle(): StringChainable;
-};
-/**
- * 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. Chain `.toggle()` when the prop reads as an on/off
- * feature (e.g. `tooltip`) — editors show a switch that reveals the field.
- */
-declare function string(): StringChainable;
-/**
- * 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>;
-/**
- * JS-motion prop binding. Emits `<name>?: SlotMotion | MotionName` — either an
- * inline framer-motion config object (`{ initial, animate, whileHover,
- * transition, … }`) or the name of a `registerMotion({...})` preset
- * (`motion="fadeIn"`; `MotionName` narrows to the registered names in an
- * augmented config, else `string`). The loader routes both through
- * `_renderWithMotion` at runtime (preset name → registered JS/CSS motion;
- * object → inline config), so
- * it produces no CSS of its own — this is the JS-animation counterpart to the
- * CSS `animation`/`transition` style props, not a `styleProp`. Chain
- * `.required()` to force callers to pass it.
- */
-declare function motion(): Chainable<MotionMarker>;
-/**
- * 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 asChild: typeof asChild;
-  readonly string: typeof string;
-  readonly number: typeof number;
-  readonly motion: typeof motion;
-  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;
-  <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>>>;
-  (options: {
-    type: 'component';
-  }): ComponentSlotMarker;
-  (options: {
-    type: SlotValueType;
-  }): SlotMarker;
-}
-/**
- * `.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 asChild: typeof asChild;
-  readonly layer: TypedLayerHelper<TLayers>;
-  readonly string: typeof string;
-  readonly number: typeof number;
-  readonly motion: typeof motion;
-  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;
-  /**
-   * Whole interaction-state dimension at one chain level, in display order:
-   * `'rest'` (no modifier forced) plus registered `_${name}` modifiers.
-   * Values pass through verbatim — the author decides whether `'rest'` leads.
-   *
-   * Not to be confused with the matrix's `pinnedModifiers` field: `states()`
-   * is a *positional* axis level (part of the displayed arrangement, `'rest'`
-   * included); `pinnedModifiers` is the arrangement-independent registry of
-   * modifiers the preview keeps even while the state dimension is hidden
-   * (`'rest'` excluded — it's implicit).
-   */
-  readonly states: (values: readonly string[]) => 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;
-  readonly states: (values: readonly string[]) => 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> : {};
-/**
- * `ref` is a scalar tag, so a value-extend that re-declares it must *override*
- * the inherited tag (Pressable's `'button'` over Box's `'div'`). A plain
- * intersection would collapse `'div' & 'button'` to `never` — poisoning the
- * whole merged definition. C wins; falls back to T's tag when C omits `ref`.
- */
-type MergeRef<T, C> = C extends {
-  ref: infer CR;
-} ? {
-  ref: CR;
-} : T extends {
-  ref: infer TR;
-} ? {
-  ref: TR;
-} : Record<never, never>;
-/**
- * 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); `ref` overrides as a scalar; other fields
- * fall back to the historic `T & C` intersection.
- */
-type MergeChainConfig<T, C> = Omit<T, 'props' | 'defaultProps' | 'base' | 'ref'> & Omit<C, 'props' | 'defaultProps' | 'base' | 'ref'> & MergeRef<T, C> & 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: 'motion';
-} ? SlotMotion | MotionName : 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> };
-/**
- * Resolved value object for a single token. `value` is the
- * light-mode (or single-mode) CSS value string. Any `_${string}` key
- * (e.g. `_dark`) holds the override for that mode. `type` is an
- * optional token-category hint (e.g. `'color'`, `'dimension'`).
- *
- * The precise qualified-name union for `tokenRaw`'s `name` parameter
- * is layered on at the call site via codegen's `uds-env.d.ts`
- * augmentation — keep this type config-agnostic.
- */
-type RawToken = {
-  value: string;
-  type?: string;
-} & { [K in `_${string}`]?: string };
-/** The accepted `name` argument for `tokenRaw`. Narrows to the
- *  config's registered `'<group>/<token>'` union when codegen has
- *  augmented `TokenRawNameRegistry`; falls back to `string` in
- *  un-augmented contexts (this package's own tests, fresh consumers
- *  before the first build). */
-type TokenRawName = [keyof TokenRawNameRegistry] extends [never] ? string : keyof TokenRawNameRegistry;
-/**
- * Resolved return shape of `tokenRaw(name)` for a specific `name`. Once codegen
- * has augmented `TokenRawNameRegistry`, each registered name maps to its own
- * per-token shape — `{ value: string; _dark: string }` for a themed token,
- * `{ value: string }` for one with no mode overrides. A finite template/union
- * name (e.g. `` `spectrum/blue/${step}` `` with `step` a finite union) resolves
- * to the union of the matching tokens' shapes, which collapses to a single type
- * when they share one. Falls back to the open `RawToken` in un-augmented
- * contexts (this package's own tests, fresh consumers before the first build).
- *
- * Values are `string`, not literals: token values are indirection by design and
- * change with theming, so a baked-in literal would go stale — the stable,
- * useful information a name carries is which keys it has.
- */
-type TokenRawValue<N extends TokenRawName> = N extends keyof TokenRawNameRegistry ? TokenRawNameRegistry[N] : RawToken;
-/**
- * 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.
- */
-/**
- * The render fn's `ref` arg, present only when the component declares
- * `.config({ ref: 'tag' })`. The author attaches it to the real root element
- * (`<svg ref={ref} {...props.root} />`), so TS checks the attachment against
- * the declared element. No declaration → no `ref` arg (empty intersection).
- */
-type RefArgFor<TDef> = TDef extends {
-  ref: infer Tag extends string;
-} ? {
-  ref?: Ref<RefElement<Tag>>;
-} : Record<never, never>;
-type ComponentRenderFn<TExtra = unknown, TConfigProps = unknown, TLayers = Record<string, unknown>, TRefArg = Record<never, never>> = (args: {
-  props: LayerPropsBundle<TLayers>;
-  children?: ReactNode;
-  tokenRaw: <N extends TokenRawName>(name: N) => TokenRawValue<N>;
-} & TConfigProps & TExtra & TRefArg) => 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>, RefArgFor<T>>): 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.
- */
-interface UdsComponent<P> {
-  <C extends ElementType, TExtra = {}>(props: Omit<P, 'ref'> & {
-    as: C;
-    ref?: Ref<ComponentRef<C>>;
-  } & NoInfer<TExtra>): ReactElement | null;
-  <TExtra = {}>(props: P & NoInfer<TExtra>): ReactElement | null;
-  readonly displayName?: string;
-}
-type ComponentBuilder<T extends ComponentDefinition> = T & ComponentBuilderMethods<T> & UdsComponent<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>;
-  renderCanvas<TCanvasExtra extends Record<string, unknown> = TExtra>(fn: ComponentRenderFn<TCanvasExtra, 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>, RefArgFor<T>>): 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
-export { BoundComponent, ComponentBuilder, ComponentBuilderMethods, ComponentRenderFn, ConfigCallbackHelpers, DefineComponentFn, DefinedComponent, DefinedMotion, DefinedProvider, DefinedStyleProp, DefinedTokenGroup, DefinedTokenGroupValue, PreviewCallbackHelpers, ProviderComponent, ProviderRenderFn, RawToken, TokenGroupMetadata, TokenRawValue, TypedSlotRef, asChild, boolean, defineComponent, defineComponentGroup, defineCompositeStyle, defineMode, defineModifier, defineMotion, defineStyleProp, defineTokenGroup, motion, number, slot, string, variant };