@yahoo/uds-v5-wip 1.60.0 → 1.62.0

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

@@ -1,45 +1,196 @@
-import { RegisteredStyleProps } from "./component-refs.js";
-import { ComponentConfigValue, HtmlTag, LayerInput, PropBinding } from "./component-config.js";
-import { ComponentPropsWithoutRef, HTMLAttributes, JSX } from "react";
+import { RegisteredCompositeStyles, RegisteredModifiers, RegisteredStyleProps, TagRef } from "./refs.js";
+import { ColorExpression } from "./colorExpressions.js";
+import { ComponentDefinition, LayerInput, PropBinding, RootTag } from "./types.js";
+import { ComponentPropsWithRef, HTMLAttributes, JSX, ReactNode } from "react";
 
 //#region ../config/dist/Props.d.ts
 //#region src/Props.d.ts
 /**
- * Resolve the native HTML-attribute surface for the config's root tag.
+ * Resolve the native HTML-attribute surface for the definition's root tag.
  *
  *  - When `TTag` is a known `JSX.IntrinsicElements` key (`'a'`, `'div'`,
- *    `'button'`, …), use `ComponentPropsWithoutRef<TTag>` so element-
- *    specific attrs land in the prop type (`href` on `'a'`, `disabled`
- *    on `'button'`, etc.).
- *  - Otherwise (no tag captured — e.g. the root is a brace-ref or
- *    composed-layer), fall back to the generic `HTMLAttributes<HTMLElement>`.
+ *    `'button'`, …), use `ComponentPropsWithRef<TTag>` so element-
+ *    specific attrs *and* the React 19 `ref` prop both land in the prop
+ *    type (`href` on `'a'`, `disabled` on `'button'`, `ref` on every
+ *    intrinsic).
+ *  - Otherwise (no tag captured — e.g. the root is a `ComponentRef`
+ *    or composed-layer), fall back to the generic
+ *    `HTMLAttributes<HTMLElement>`.
  */
-type ElementProps<TTag extends HtmlTag | undefined> = TTag extends keyof JSX.IntrinsicElements ? ComponentPropsWithoutRef<TTag> : HTMLAttributes<HTMLElement>;
+type ElementProps<TTag extends string | undefined> = TTag extends keyof JSX.IntrinsicElements ? ComponentPropsWithRef<TTag> : HTMLAttributes<HTMLElement>;
+/**
+ * Props inherited from the wrapped component when the root layer is a
+ * registered `ComponentDefinition` value (e.g. `layers: { root: Box }`).
+ * Returns the wrapped component's own resolved `Props<...>` shape so
+ * a wrapper's JSX surface inherits everything the wrapped component
+ * accepts. Returns `{}` when the root isn't composed.
+ *
+ * Recursion terminates because the inner `TInner` is constrained to
+ * `ComponentDefinition<infer L, infer P, infer T>` — three concrete
+ * inferred type variables, not the bare wide `ComponentDefinition`. TS
+ * unfolds one step at a time and the recursive `Props<TInner>` works
+ * on the already-narrowed shape rather than the open structural
+ * interface.
+ *
+ * The outer `[TLayers] extends [Record<string, LayerInput>]` guard
+ * (and the corresponding wide-`R` short-circuit below) prevent the
+ * type from blowing the complexity budget when `TLayers` is the bare
+ * structural default (`Record<string, LayerInput>`) — at that point
+ * `R` is the full `LayerInput` union, and recursing through it would
+ * try to enumerate every wrapped-component shape the union admits.
+ */
+/**
+ * One-level prop-shape extraction for a composed root layer. Mirrors
+ * `Props<TInner>` without re-invoking `Props` recursively — the
+ * recursion was the main culprit behind TS2590 "union too complex"
+ * during codegen typechecks, where dozens of `defineComponent` call
+ * sites with overlapping prop shapes pushed the inference budget
+ * over. One level of prop inheritance covers every real wrapper
+ * shape (Box → HStack, Box → Pressable, Box → Input); a deeper
+ * chain (Pressable → Button) still picks up Box's surface via the
+ * already-flattened intermediate, because each step's `props` field
+ * already carries the merged-and-flattened bindings from the chain
+ * methods' `MergeChainConfig`.
+ */
+type ComposedRootShape<TLayers extends Record<string, LayerInput>, TProps extends Record<string, PropBinding>, TTag extends string | undefined> = PropsFromBindings<TProps, TLayers> & Omit<ElementProps<EffectiveTagPlain<TTag, TLayers>>, keyof TProps> & DataAttrs;
+/**
+ * Plain tag computation for `ComposedRootShape` — no `defaultProps.as`
+ * override (the inner def's own `defaultProps.as` doesn't influence
+ * the outer JSX surface; only its layers + props + captured TTag do).
+ */
+type EffectiveTagPlain<TTag, TLayers> = string extends TTag ? RootTag<TLayers> : [TTag] extends [undefined] ? RootTag<TLayers> : TTag extends string ? TTag : RootTag<TLayers>;
+type ComposedRootProps<TLayers> = TLayers extends {
+  root: infer R;
+} ? LayerInput extends R ? {} : R extends ComponentDefinition<infer InnerLayers, infer InnerProps, infer InnerTag> ? ComposedRootShape<InnerLayers, InnerProps, InnerTag> : {} : {};
 /**
  * Resolve the allowed-value union for one registered style prop.
  * Falls back to `string` when the prop registered no tokens (codegen
- * emits `never` for that case).
+ * emits `never` for that case). Always widened with `ColorExpression`
+ * so the sanctioned `mix(...)` / `darken(...)` / `lighten(...)` color
+ * helpers type-check at every style-prop position.
  */
-type StylePropValue<K extends keyof RegisteredStyleProps> = [RegisteredStyleProps[K]] extends [never] ? string : RegisteredStyleProps[K];
+type StylePropValue<K extends keyof RegisteredStyleProps> = [RegisteredStyleProps[K]] extends [never] ? string | ColorExpression : RegisteredStyleProps[K] | ColorExpression;
 /**
- * Extract the registered style-prop name from a binding value:
- *  - `'{bg}'` → `'bg'`
- *  - `{ styleProp: '{bg}' }` → `'bg'`
- * Returns `never` for non-matching forms.
+ * Extract the registered style-prop name from a `StylePropRef` binding —
+ * `{ __kind: 'styleProp', ref: 'bg', layer? }` → `'bg'`. Returns `never`
+ * for non-matching forms.
  */
-type StylePropRefName<TBinding> = TBinding extends `{${infer N}}` ? N extends keyof RegisteredStyleProps & string ? N : never : TBinding extends {
-  styleProp: `{${infer N}}`;
+type StylePropRefName<TBinding> = TBinding extends {
+  readonly __kind: 'styleProp';
+  readonly ref: infer N;
 } ? N extends keyof RegisteredStyleProps & string ? N : never : never;
 /**
- * Walk the config's `props` block and produce one optional JSX prop
- * per entry.
+ * Extract the registered composite-group name from a `CompositeRef`
+ * binding — `{ __kind: 'composite', ref: 'textVariant' }` → `'textVariant'`.
+ * Returns `never` for non-matching forms.
+ */
+type CompositeRefName<TBinding> = TBinding extends {
+  readonly __kind: 'composite';
+  readonly ref: infer N;
+} ? N extends keyof RegisteredCompositeStyles & string ? N : never : never;
+/**
+ * Resolve the allowed-value union for a registered composite group —
+ * the union of `styles` keys. Falls back to `string` when the
+ * registry isn't populated (e.g. inside `@uds/config`'s own
+ * tests where codegen-emitted augmentation isn't loaded).
  */
-type PropsFromConfig<TProps> = { [K in keyof TProps]?: StylePropRefName<TProps[K]> extends never ? unknown : StylePropValue<Extract<StylePropRefName<TProps[K]>, keyof RegisteredStyleProps>> };
+type CompositeValue<K extends keyof RegisteredCompositeStyles> = RegisteredCompositeStyles[K] extends {
+  styles: infer S;
+} ? keyof S & string : string;
+/**
+ * Resolve the JSX-value type for a slot ref by looking up the target
+ * layer's prop. Mirrors main's `SlotPropValue` but reads
+ * `layerProp` instead of `prop` (the config slot ref carries
+ * `layerProp` as the target prop name).
+ *
+ *  - **Composed-component layer** — read
+ *    `Props<TInnerDef>[layerProp]`, so `slot('button/onClick')` types
+ *    as the click-handler the wrapped component declares.
+ *  - **HTML-tag layer** (bare-tag `'div'`, `TagRef<'a'>`, or
+ *    `{ tag: 'a', attrs }`) — read
+ *    `ComponentPropsWithRef<tag>[layerProp]`, so `slot('link/href')`
+ *    types as `string | undefined`.
+ *  - Unknown layer / unknown prop falls back to `ReactNode`.
+ */
+type SlotTargetKey<A> = [A] extends [string] ? A : 'children';
+/** Resolve a layer's HTML tag literal (`'a' | 'div' | ...`) when statically readable. */
+type LayerTag<L> = L extends string ? L : L extends TagRef<infer T> ? T : L extends {
+  tag: infer T extends string;
+} ? T : L extends {
+  tag: TagRef<infer T>;
+} ? T : never;
+/**
+ * Read prop `K` off `T` if present, else fall back to `ReactNode`. Used
+ * to look up a slot's target-layer prop without crashing on
+ * mismatched keys.
+ */
+type ReadOrNode<T, K> = K extends keyof T ? T[K] : ReactNode;
+type SlotPropValue<TBinding, TLayers> = TBinding extends {
+  readonly __kind: 'slot';
+  readonly layer: infer L extends keyof TLayers & string;
+  readonly layerProp?: infer A;
+} ? TLayers[L] extends ((props: infer P) => unknown) ? ReadOrNode<P, SlotTargetKey<A>> : TLayers[L] extends ComponentDefinition<infer InnerLayers, infer InnerProps, infer InnerTag> ? ReadOrNode<ComposedRootShape<InnerLayers, InnerProps, InnerTag>, SlotTargetKey<A>> : LayerTag<TLayers[L]> extends infer TT extends keyof JSX.IntrinsicElements ? ReadOrNode<ComponentPropsWithRef<TT>, SlotTargetKey<A>> : ReactNode : ReactNode;
+type IsSlotMarker<TBinding> = TBinding extends {
+  readonly __kind: 'slot';
+} ? true : false;
+/**
+ * Resolve the JSX value type for one prop binding. Pulled out so
+ * `PropsFromBindings` can apply it twice — once for required keys
+ * (no `?`) and once for optional keys.
+ */
+type ResolveBindingValue<TBinding, TLayers> = TBinding extends {
+  readonly __transformOut: infer Out;
+} ? (value: Out) => void : IsSlotMarker<TBinding> extends true ? SlotPropValue<TBinding, TLayers> : StylePropRefName<TBinding> extends never ? CompositeRefName<TBinding> extends never ? TBinding extends {
+  readonly __kind: 'boolean';
+} ? boolean : TBinding extends {
+  readonly __kind: 'string';
+} ? string : TBinding extends {
+  readonly __kind: 'number';
+} ? number : TBinding extends {
+  readonly __kind: 'variant';
+  readonly values: infer V;
+} ? V extends readonly (string | number)[] ? V[number] : keyof V & string : unknown : CompositeValue<Extract<CompositeRefName<TBinding>, keyof RegisteredCompositeStyles>> : StylePropValue<Extract<StylePropRefName<TBinding>, keyof RegisteredStyleProps>>;
+/**
+ * Keys of `TProps` whose binding carries `__required: true` — these
+ * surface on the JSX side without the trailing `?` so callers must
+ * pass a value.
+ */
+type RequiredBindingKeys<TProps> = { [K in keyof TProps]: TProps[K] extends {
+  readonly __required: true;
+} ? K : never }[keyof TProps];
+/**
+ * Style-prop names bound by the definition — the `ref` of every
+ * `styleProp(...)` entry in the `props` block (`never` for non-style
+ * bindings, which drop out of the union).
+ */
+type BoundStylePropNames<TProps> = { [K in keyof TProps]: StylePropRefName<TProps[K]> }[keyof TProps] & string;
+/**
+ * Opacity companions for the bound color props. `defineStyleProp(...)
+ * .withOpacity({ as })` registers a `${base}Opacity` sibling in
+ * `RegisteredStyleProps` that pairs with its base color prop at the same
+ * style position (`borderColor` → `borderColorOpacity`). A component that
+ * binds the base prop should accept the companion too — both on its JSX
+ * surface and inside modifier bodies (`_hover: { borderColorOpacity }`),
+ * which read their key set from this binding-derived bag rather than from
+ * the full `RegisteredStyleProps` map that tag layers get.
+ *
+ * The `& keyof RegisteredStyleProps` intersection keeps only siblings that
+ * were actually registered, so a bound base prop without a `.withOpacity()`
+ * pair (e.g. `borderTopColor`) contributes nothing.
+ */
+type OpacityCompanionProps<TProps> = { [O in `${BoundStylePropNames<TProps>}Opacity` & keyof RegisteredStyleProps]?: StylePropValue<O> };
+/**
+ * Walk the definition's `props` block and produce a JSX prop per entry.
+ * Bindings carry `__required: true` when the author chained
+ * `.required()`; those keys land in the required half of the resulting
+ * prop bag. Every other key stays optional. The opacity companions of any
+ * bound color prop ride along via `OpacityCompanionProps`.
+ */
+type PropsFromBindings<TProps, TLayers> = { [K in keyof TProps as K extends RequiredBindingKeys<TProps> ? K : never]: ResolveBindingValue<TProps[K], TLayers> } & { [K in keyof TProps as K extends RequiredBindingKeys<TProps> ? never : K]?: ResolveBindingValue<TProps[K], TLayers> } & OpacityCompanionProps<TProps>;
 /**
  * Force TypeScript to fully evaluate a mapped/conditional type so the
  * hover display shows the resolved shape (`bg?: 'brand' | 'accent'`)
- * instead of the unevaluated type expression
- * (`PropsFromConfig<{ readonly bg: '{bg}' }>`).
+ * instead of the unevaluated type expression.
  */
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
 /**
@@ -51,24 +202,118 @@ type Prettify<T> = { [K in keyof T]: T[K] } & {};
 interface DataAttrs {
   [key: `data-${string}`]: unknown;
 }
+/**
+ * `layerProps={{ root: { bg: '...' }, ... }}` — per-layer JSX prop
+ * overrides. Same shape main exposes: each value is the layer
+ * component's own `Props<...>` (when the layer is a composed
+ * component) or a wide style+attr bag (when the layer is a bare HTML
+ * tag).
+ */
+type LayerPropsValue<TLayer> = TLayer extends ComponentDefinition<infer InnerLayers, infer InnerProps, infer InnerTag> ? Partial<Props<ComponentDefinition<InnerLayers, InnerProps, InnerTag>>> : Partial<HTMLAttributes<HTMLElement>> & { [K in keyof RegisteredStyleProps]?: StylePropValue<K> };
+type LayerPropsMap<TLayers extends Record<string, LayerInput>> = { [K in keyof TLayers]?: LayerPropsValue<TLayers[K]> };
+/**
+ * Per-layer `base` styles. Same target-narrowing as `LayerPropsValue`
+ * but adds `_<modifier>` keys for tag layers — `base: { root: { _hover:
+ * {...} } }` is a common authoring pattern and modifiers aren't part
+ * of the JSX `layerProps` shape, so we expose them here only.
+ *
+ * Composed-component layers already carry modifiers via `Props<...>`
+ * (see `PropsBase`'s wrapping `RegisteredModifiers`), so that branch
+ * passes through unchanged.
+ */
+/**
+ * Per-tag-layer styles bag. Combines:
+ *  - HTML attrs valid on every element
+ *  - Each registered style prop with its token-union value (plus
+ *    `[bracket]` literals and an open-string escape so unregistered
+ *    runtime values still typecheck — autocomplete still shows the
+ *    token union via the `string & {}` hint pattern)
+ *  - Each registered composite-style binding (e.g. `variant`,
+ *    `elevation`) so layers that wrap a composite-bound component
+ *    can set the composite value
+ *  - A `Record<string, unknown>` index signature that only kicks in
+ *    when the augmentable registries are empty (consumer tests in
+ *    `@uds/config` / `@uds/codegen` run without codegen-emitted
+ *    augmentation). Detected via the `[keyof X] extends [never]`
+ *    "empty registry" probe; in real consumer apps the registries
+ *    are populated and the open index signature drops out.
+ */
+type TagLayerStylesBag = [keyof RegisteredStyleProps] extends [never] ? Record<string, unknown> : Partial<HTMLAttributes<HTMLElement>> & { [K in keyof RegisteredStyleProps]?: StylePropValue<K> | `[${string}]` | (string & {}) } & { [K in keyof RegisteredCompositeStyles]?: CompositeValue<K> };
+type BaseLayerStyles<TLayer> = TLayer extends ComponentDefinition<infer InnerLayers, infer InnerProps, infer InnerTag> ? Partial<Props<ComponentDefinition<InnerLayers, InnerProps, InnerTag>>> : TagLayerStylesBag & RegisteredModifiers<TagLayerStylesBag>;
+/**
+ * Component prop surface without modifiers — the "base" type that
+ * `Props<TDef>` wraps with `RegisteredModifiers<PropsBase<TDef>>`.
+ *
+ * Splitting the modifier layer out breaks a self-reference cycle: TS
+ * can resolve `RegisteredModifiers<PropsBase<TDef>>` because
+ * PropsBase doesn't reference itself, but
+ * `RegisteredModifiers<Props<TDef>>` directly inside `Props<TDef>`
+ * leaves TS unable to materialize the recursive shape and the
+ * modifier keys collapse to nothing at consumer call sites.
+ */
+/**
+ * Effective root tag for `PropsBase`. Resolution order:
+ *
+ *  1. `defaultProps.as` — value-extend chains thread the polymorphic
+ *     tag here (`defineComponent(Box).config({ defaultProps: { as:
+ *     'input' } })` makes `Input`'s JSX surface `<input>`-shaped).
+ *  2. Explicit `TTag` from the def's third generic — set when a chain
+ *     captures the tag literal directly into the synthesized
+ *     `ComponentDefinition<..., ..., TTag>`. Falls back when the def's
+ *     `TTag` is the wide default `string | undefined`.
+ *  3. `RootTag<TLayers>` — derived from the root layer (bare-tag string
+ *     `'div'`, `TagRef<'a'>`, `{ tag: 'a', ... }`, or an inner
+ *     definition's captured tag).
+ */
+type EffectiveTag<TDef, TTag, TLayers> = TDef extends {
+  defaultProps: {
+    as: infer A extends keyof JSX.IntrinsicElements;
+  };
+} ? A : string extends TTag ? RootTag<TLayers> : [TTag] extends [undefined] ? RootTag<TLayers> : TTag extends string ? TTag : RootTag<TLayers>;
+type PropsBase<TDef extends ComponentDefinition<Record<string, LayerInput>, Record<string, PropBinding>, string | undefined>> = TDef extends ComponentDefinition<infer TLayers extends Record<string, LayerInput>, infer TProps extends Record<string, PropBinding>, infer TTag extends string | undefined> ? PropsFromBindings<TProps, TLayers> & Omit<ComposedRootProps<TLayers>, keyof TProps | 'children'> & Omit<ElementProps<EffectiveTag<TDef, TTag, TLayers>>, keyof TProps | keyof ComposedRootProps<TLayers>> & DataAttrs & {
+  as?: keyof JSX.IntrinsicElements;
+  layerProps?: LayerPropsMap<TLayers>;
+} : never;
 /**
  * Public derived-props type.
  *
- * Four layers:
- *  1. `PropsFromConfig<TConfig['props']>` — the config's declared props.
- *  2. `ElementProps<TTag>` — native attrs narrowed to the root tag when
- *     statically known (e.g. `href` on `'a'`), otherwise generic
- *     `HTMLAttributes<HTMLElement>`. Anything colliding with (1) is
- *     stripped out so custom props' value unions don't get widened.
- *  3. `DataAttrs` — permissive `data-*` index signature.
- *  4. Polymorphic `as` prop (open-ended `string` for now).
- */
-type Props<TConfig extends ComponentConfigValue<Record<string, LayerInput>, Record<string, PropBinding>, HtmlTag | undefined>> = TConfig extends ComponentConfigValue<Record<string, LayerInput>, infer TProps extends Record<string, PropBinding>, infer TTag extends HtmlTag | undefined> ? Prettify<PropsFromConfig<TProps> & Omit<ElementProps<TTag>, keyof TProps> & DataAttrs & {
-  as?: string;
-}> : never;
-/**
- * `Props<typeof boxConfig>` for the common 'use the config's inferred
- * type' invocation. Keeps `box.tsx` from having to repeat the generic.
+ * Layers:
+ *  1. `PropsFromBindings<TProps, TLayers>` — config-declared props.
+ *  2. `ComposedRootProps<TLayers>` — the wrapped component's prop
+ *     surface when the root layer is a `ComponentDefinition` value,
+ *     minus `children` (a multi-layer component must declare its own
+ *     content slot rather than inherit the root's).
+ *  3. `ElementProps<TTag>` — native HTML attrs narrowed to the root
+ *     tag (or the wrapper's `defaultProps.as` for value-extends).
+ *     Anything colliding with (1) or (2) is stripped out.
+ *  4. `DataAttrs` — permissive `data-*` index signature.
+ *  5. `RegisteredModifiers<PropsBase<TDef>>` — narrowed `_<modifier>`
+ *     keys with `Partial<...>` values. Augmented by codegen.
+ *  6. Polymorphic `as` prop.
+ *
+ * The first conditional short-circuits to a permissive shape when
+ * `TDef` is too wide (no concrete `layers` map yet). Without this,
+ * the eagerly-evaluated `ComponentBuilder<{layers: L}>` at the
+ * `defineComponent.layers` static-method declaration sometimes
+ * pushes the TS inference budget over the "union too complex" wall
+ * during package-wide typechecks (`@uds/codegen` builds saw this
+ * at `factories.ts:853`).
  */
+type Props<TDef extends ComponentDefinition<Record<string, LayerInput>, Record<string, PropBinding>, string | undefined>> = TDef extends {
+  layers: Record<string, LayerInput>;
+} ? Record<string, LayerInput> extends TDef['layers'] ? PermissiveProps : Prettify<PropsBase<TDef> & RegisteredModifiers<PropsBase<TDef>>> : PermissiveProps;
+/**
+ * Permissive prop bag used as the bail-out shape when `Props<TDef>`
+ * can't narrow against a concrete `layers` map (mirrors the
+ * `FC<any>` slot the pre-Props builder used to carry).
+ */
+type PermissiveProps = HTMLAttributes<HTMLElement> & DataAttrs & Record<string, any> & {
+  as?: keyof JSX.IntrinsicElements;
+};
+/**
+ * `Props<typeof boxConfig>` for the common 'use the definition's inferred
+ * type' invocation. Keeps consumers from having to repeat the generic.
+ */
+//#endregion
 //#endregion
-export { Props };
+export { BaseLayerStyles, DataAttrs, LayerPropsMap, LayerTag, Props, PropsFromBindings, SlotPropValue };

package/dist/config/dist/Provider.d.ts

@@ -0,0 +1,21 @@
+import { FC, ReactNode } from "react";
+
+//#region ../config/dist/Provider.d.ts
+//#region src/Provider.d.ts
+declare class Provider {
+  readonly name: string;
+  readonly component: FC<{
+    children: ReactNode;
+  }>;
+  constructor(args: {
+    name: string;
+    component: FC<{
+      children: ReactNode;
+    }>;
+  });
+  toJSON(): {
+    name: string;
+  };
+} //#endregion
+//#endregion
+export { Provider };

package/dist/config/dist/Provider.js

@@ -0,0 +1,14 @@
+//#region ../config/dist/Provider.js
+var Provider = class {
+	name;
+	component;
+	constructor(args) {
+		this.name = args.name;
+		this.component = args.component;
+	}
+	toJSON() {
+		return { name: this.name };
+	}
+};
+//#endregion
+export { Provider };

package/dist/config/dist/StyleProp.d.ts

@@ -0,0 +1,113 @@
+import { AnyStylePropDefinition, ArbitraryEntry, ArbitrarySpec, OpacityPairSpec, StylePropMetadata, StylePropProperty, TokenType } from "./types.js";
+import { Token } from "./Token.js";
+
+//#region ../config/dist/StyleProp.d.ts
+//#region src/StyleProp.d.ts
+type StorageValuesEntry = NonNullable<AnyStylePropDefinition['values']>[number];
+type StyleTokenLookup = (groupName: string) => Iterable<Token>;
+declare class StyleProp {
+  #private;
+  readonly name: string;
+  readonly cssProperty: StylePropProperty | readonly StylePropProperty[];
+  readonly classPrefix: string;
+  readonly values: readonly StorageValuesEntry[];
+  readonly arbitrary?: ArbitrarySpec | readonly ArbitraryEntry[];
+  /**
+   * When true, the prop emits its value negated (`calc(<value> * -1)`) — the
+   * single source of negativity, read by the emitter, the runtime injector,
+   * and the MCP/guidance/lint. See {@link StylePropDefinition.negative}.
+   */
+  readonly negative: boolean;
+  readonly cssType?: TokenType;
+  readonly metadata: StylePropMetadata;
+  readonly opacityPair?: OpacityPairSpec;
+  /**
+   * Optional value→CSS adapter (`gridTemplateColumns`'s `4` →
+   * `repeat(4, minmax(0, 1fr))`). Applied to enumerated `values` when deriving
+   * the utility-class body, so the native emitter produces real CSS without a
+   * Tailwind built-in. Keyword strings (`'none'`) pass through unchanged.
+   */
+  readonly transform?: (value: string | number) => string;
+  /**
+   * Build the utility-class name a style prop emits for a given
+   * JSX-level value. Single source of truth shared by codegen
+   * (`@utility` emission), loader (build-time class derivation), and
+   * the runtime renderer — all three must agree byte-for-byte.
+   *
+   * Conventions (the `prefix` namespaces the whole utility body the same
+   * way component classes and CSS variables are namespaced; empty prefix
+   * yields the bare form):
+   *  - `classPrefix === ''` → the value IS the class body (`display="block"`
+   *    → `.yos-block`).
+   *  - Boolean `true` → bare `classPrefix` body (`<Box border>` →
+   *    `.yos-border`, never `.border-true`). Falsy → `undefined` (caller
+   *    omits the class).
+   *  - Bracketed arbitrary values (`'[#abc]'`) pass through verbatim.
+   *  - Otherwise `${classPrefix}-${safeTokenName(value)}` where
+   *    safeTokenName maps `.` → `_` and `/` → `-`.
+   *
+   * Static so callers without a StyleProp instance (loader's
+   * className builder, codegen's safelist scanner) can derive a class
+   * from just the prefix + value pair. Instance callers reach
+   * `styleProp.classNameFor(value)`, which supplies the owning Config's
+   * prefix automatically.
+   */
+  static classNameFor(styleProp: {
+    classPrefix: string;
+  }, value: unknown, prefix?: string): string | undefined;
+  /** Instance form of {@link StyleProp.classNameFor} — supplies the owning
+   *  Config's class-name prefix. */
+  classNameFor(value: unknown): string | undefined;
+  /** The `classPrefix` namespaced with the owning Config's prefix
+   *  (`bg` → `yos-bg`). The wildcard `@utility` emitter needs the
+   *  prefixed stem (`yos-bg-*`) since it has no concrete value to run
+   *  through {@link classNameFor}. Empty when this prop has no class
+   *  prefix (value-as-class props emit no wildcard utility). */
+  get prefixedClassPrefix(): string;
+  constructor(args: {
+    name: string;
+    definition: AnyStylePropDefinition;
+    tokenLookup: StyleTokenLookup;
+    prefixGetter?: () => string;
+  });
+  get derived(): {
+    readonly keywords: ReadonlyMap<string | number | boolean, string | Record<string, string>>;
+    readonly tokens: readonly Token[];
+  };
+  /**
+   * Token-group namespaces this prop consumes. Used by
+   * `TokenGroup.derived.styleProperties` to answer the reverse question.
+   */
+  consumedTokenGroups(): readonly string[];
+  /**
+   * The values this prop accepts, split by how each is written at the JSX site:
+   *  - `tokens` — token names from the prop's token groups (`gap="2"`).
+   *  - `keywords` — literal CSS keywords written verbatim (`display="flex"`).
+   *  - `aliases` — short keys resolving to a CSS keyword (`flexDirection="col"`
+   *    → `column`).
+   * A bracketed `[...]` arbitrary literal is governed by `this.arbitrary`, not
+   * enumerated here. Rendered by `uds_get_style_prop` / `uds_list_style_props`;
+   * `accepts()` validates against the same set.
+   */
+  allowedValues(): {
+    tokens: readonly string[];
+    keywords: readonly string[];
+    aliases: readonly {
+      alias: string;
+      value: string;
+    }[];
+  };
+  /**
+   * Whether a JSX-site value is accepted: a token name, a literal keyword, an
+   * alias key, or a bracketed `[...]` literal when the prop enables `arbitrary`
+   * values. The validation primitive behind `uds_validate_props` — a non-token
+   * keyword prop (`display`) and an arbitrary-only prop (`fontSize`) both work,
+   * not just token-group props.
+   */
+  accepts(value: string): boolean;
+  toJSON(): AnyStylePropDefinition & {
+    name: string;
+  };
+} //#endregion
+//#endregion
+export { StyleProp };