@yahoo/uds-create-config 2.44.0 → 3.0.0

package/dist/Props.d.ts

@@ -1,332 +0,0 @@
-import { MotionName, RegisteredCompositeStyles, RegisteredModifiers, RegisteredStyleProps, TagRef } from "./refs.js";
-import { ColorExpression } from "./colorExpressions.js";
-import { ComponentDefinition, LayerInput, PropBinding, RefElement, RootTag, SlotMotion } from "./types.js";
-import { ComponentPropsWithRef, ElementType, HTMLAttributes, JSX, ReactNode, Ref } from "react";
-
-//#region src/Props.d.ts
-/**
- * Resolve the native HTML-attribute surface for the definition's root tag.
- *
- *  - When `TTag` is a known `JSX.IntrinsicElements` key (`'a'`, `'div'`,
- *    `'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 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). 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 | ColorExpression : RegisteredStyleProps[K] | ColorExpression;
-/**
- * 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 {
-  readonly __kind: 'styleProp';
-  readonly ref: infer N;
-} ? N extends keyof RegisteredStyleProps & string ? N : never : never;
-/**
- * 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 `@yahoo/uds-create-config`'s own
- * tests where codegen-emitted augmentation isn't loaded).
- */
-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: 'motion';
-} ? SlotMotion | MotionName : 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.
- */
-type Prettify<T> = { [K in keyof T]: T[K] } & {};
-/**
- * Standard `data-*` attributes are valid on every HTML element by spec.
- * React 19's bundled types don't carry an index signature for them, so
- * we add one here — keeps `<Box data-test="x" />` valid without forcing
- * authors to register every test attribute as a config-declared prop.
- */
-interface DataAttrs {
-  [key: `data-${string}`]: unknown;
-}
-/**
- * `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
- *    `@yahoo/uds-create-config` / `@yahoo/uds-create-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?: ElementType;
-  layerProps?: LayerPropsMap<TLayers>;
-} : never;
-/**
- * Public derived-props type.
- *
- * 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 (`@yahoo/uds-create-codegen` builds saw this
- * at `factories.ts:853`).
- */
-/**
- * Opt-in forwarded-ref prop. A component declares its ref target via
- * `.config({ ref: 'button' })`; that tag is captured on the definition's `ref`
- * field and mapped here to `ref?: Ref<HTMLButtonElement>`. When declared and
- * resolvable, it *overrides* the element's natural ref (see `Props`, which omits
- * exactly `keyof RefProp` before re-adding this). When it can't resolve to a
- * tag, it contributes nothing and the natural ref is left intact.
- */
-type RefProp<TDef> = TDef extends {
-  ref: infer Tag extends string;
-} ? {
-  ref?: Ref<RefElement<Tag>>;
-} : Record<never, never>;
-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<Omit<PropsBase<TDef> & RegisteredModifiers<PropsBase<TDef>>, keyof RefProp<TDef>> & RefProp<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?: ElementType;
-};
-/**
- * `Props<typeof boxConfig>` for the common 'use the definition's inferred
- * type' invocation. Keeps consumers from having to repeat the generic.
- */
-//#endregion
-export { BaseLayerStyles, DataAttrs, LayerPropsMap, LayerTag, Props, PropsFromBindings, SlotPropValue };

package/dist/Props.js

@@ -1,35 +0,0 @@
-/**
- * `Props<TDef>` — derive a React component's prop type from a
- * `defineComponent(...)` definition.
- *
- * Walks the definition's `props` block. For each entry:
- *
- *  - `styleProp(ref)` marker (`StylePropRef`) → JSX-prop name is the
- *    entry key; value type is `RegisteredStyleProps[ref]` (the allowed
- *    token-name union for that registered style prop). When the
- *    registered union is `never` (the prop registered no tokens —
- *    arbitrary-only), the value type widens to `string`.
- *
- *  - `boolean()` / `string()` markers → `boolean` / `string`.
- *
- *  - `variant({...})` marker → string-literal union of the declared keys.
- *
- *  - `composite(ref)` marker (`CompositeRef`) → keys of the registered
- *    composite group's `styles` map.
- *
- *  - `slot(...)` marker / ref → `ReactNode` (or the resolved layer-prop
- *    type when the slot targets a specific `layer/prop`).
- *
- * Plus the standard React affordances, with the native `HTMLAttributes`
- * surface narrowed to omit any key that collides with a config-declared
- * prop — so a config-declared `color` prop with a token-name union
- * doesn't get widened to `string` by `HTMLAttributes`' own
- * `color?: string`.
- *
- * Port of `@yahoo/uds-create-config`'s `Props.ts`, adapted to config's marker
- * + ref naming:
- *  - Slot's target layer-prop name is `layerProp` (was `prop`).
- *  - Composite registry is `RegisteredCompositeStyles` (was
- *    `RegisteredComposites`).
- *  - `RegisteredModifiers<T>` matches main's generic form.
- */

package/dist/Provider.d.ts

@@ -1,20 +0,0 @@
-import { FC, ReactNode } from "react";
-
-//#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
-export { Provider };

package/dist/Provider.js

@@ -1,14 +0,0 @@
-//#region src/Provider.ts
-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/StyleProp.d.ts

@@ -1,145 +0,0 @@
-import { AnyStylePropDefinition, ArbitraryEntry, ArbitrarySpec, OpacityPairSpec, StylePropMetadata, StylePropProperty, TokenType } from "./types.js";
-import { Token } from "./Token.js";
-
-//#region src/StyleProp.d.ts
-type StorageValuesEntry = NonNullable<AnyStylePropDefinition['values']>[number];
-type StyleTokenLookup = (groupName: string) => Iterable<Token>;
-/**
- * Whether a raw CSS value is safe to feed through {@link StyleProp.classNameFor}
- * and get back a syntactically valid class-name body. `classNameFor`'s own
- * substitution only escapes `.` and `/` — anything else (parens, commas,
- * spaces) passes through unchanged and would produce an invalid CSS selector.
- *
- * Not every `{ alias, value }` entry's `value` is meant to be authored
- * directly at a JSX/spec site: a short alias (`in-out`) can resolve to a
- * multi-argument function expression (`transitionTiming`'s
- * `cubic-bezier(0.4, 0, 0.2, 1)`) that no one would ever type as a raw prop
- * value and that can never form a valid class name. A resolved keyword like
- * `justifyContent`'s `space-between`, by contrast, is exactly the kind of
- * value a design element can (and does) carry directly. Callers that derive
- * an *additional* class keyed by the resolved value (rather than the alias)
- * must gate on this first.
- */
-declare function isSafeClassNameValue(value: string): boolean;
-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, and canonicalizes a resolved CSS keyword back
-   *  to its authored alias ({@link canonicalKeyword}) so a spec that carries
-   *  either spelling resolves to the one class the alias declared. Without
-   *  this, a no-prefix prop's resolved spelling collides across props —
-   *  `textTransform: 'none'` (alias `normal-case`) and `display: 'none'` both
-   *  produced `.uds-none`, and whichever the CSS emitter wrote last silently
-   *  redefined the other's rule, leaving `display="none"` painting
-   *  `text-transform: none` (UDS-2708). */
-  classNameFor(value: unknown): string | undefined;
-  /**
-   * Map a resolved CSS keyword back to the alias that authors it, when the
-   * value isn't directly writable itself. A value that IS a keyword key
-   * (passthrough or alias key) is already canonical and passes through; only
-   * a value reachable solely as some alias's resolved form (`'none'` on a
-   * prop authored `{ alias: 'normal-case', value: 'none' }`) rewrites to that
-   * alias. Non-keyword values (tokens, brackets) pass through untouched.
-   */
-  canonicalKeyword(value: unknown): unknown;
-  /** 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
-export { StyleProp, isSafeClassNameValue };