@yahoo/uds-v5-wip 1.55.0 → 1.56.0

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

@@ -3,6 +3,7 @@ import { ComponentConfigValue, HtmlTag, LayerInput, PropBinding } from "./compon
 import { ComponentPropsWithoutRef, HTMLAttributes, JSX } 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.
  *
@@ -65,5 +66,9 @@ interface DataAttrs {
 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.
+ */
 //#endregion
 export { Props };

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

@@ -3,6 +3,7 @@ import * as React$1 from "react";
 import { ReactNode } from "react";
 
 //#region ../config/dist/component-config.d.ts
+//#region src/component-config.d.ts
 /**
  * HTML tag literal. The TypeScript type is `string` (any tag name);
  * runtime renders it via `React.createElement(tag, ...)`.
@@ -108,6 +109,17 @@ interface CompositeBinding {
   composite: CompositeRef;
   layers: Record<string, string>;
 }
+/**
+ * Forward a JSX prop value to one of the component's layers as an
+ * existing surface key. The runtime-side / read-side shape — `layer`
+ * and `from` are bare strings. Type-guards in `bindRender` use the
+ * absence of `styleProp` / `composite` keys to discriminate this shape
+ * from the registered-binding shapes.
+ *
+ * Authoring sites get the narrower `TypedForwardBinding<TLayers>`
+ * (below) via `VerbosePropBinding<TLayers>`, which structurally
+ * extends this loose form.
+ */
 /**
  * Authoring-site form of `ForwardBinding`, narrowed against the
  * component's own layer map. Distributes over `keyof TLayers` so:
@@ -188,6 +200,14 @@ type PrimitivePropBinding<TLayers extends Record<string, LayerInput> = Record<st
  * tighter `VerbosePropBinding`.
  */
 type PropBinding<TLayers extends Record<string, LayerInput> = Record<string, LayerInput>> = PrimitivePropBinding<TLayers>;
+/**
+ * Marker for a boolean JSX prop. Use inside the `props` block:
+ *
+ *     props: {
+ *       loading: bool(),
+ *       disabled: bool(),
+ *     }
+ */
 /**
  * Names of prop bindings that participate in matrix/strip iteration —
  * i.e. props authored as `enums({...})` or `bool()`. Other prop bindings
@@ -275,6 +295,15 @@ interface CompoundVariant {
   conditions: Record<string, string>;
   styles: Record<string, Record<string, unknown>>;
 }
+/**
+ * The architecture-doc-target component config. Distinct from today's
+ * `SingleComponentDef` (`base` + `variants` shape) — this is the
+ * pure-data, layers-first shape the new `defineComponent` accepts.
+ *
+ * `TLayers` is inferred from the `layers` block so prop bindings can
+ * narrow their `layer` field against the component's actual layer
+ * names; typos surface at the authoring site.
+ */
 /**
  * Branded shape returned by `defineComponent({...})`. Carries `layers`,
  * `props`, AND a phantom `__tag` slot as const-narrowed types so
@@ -311,5 +340,10 @@ interface ComponentConfigValue<TLayers extends Record<string, LayerInput>, TProp
    */
   readonly examples?: Examples<TProps>;
 }
+/**
+ * The bundle passed to the render function for each layer — a ready-to-
+ * spread object with `className` and any forwarded attrs. The render
+ * function destructures `props.<layerName>` into the JSX position.
+ */
 //#endregion
 export { BoolMarker, ComponentConfigValue, ComposedLayer, CompositeBinding, CompoundVariant, EnumMarker, HtmlTag, LayerInput, PrimitiveLayer, PrimitivePropBinding, PropBinding, RootTag, SingleLayerCompositeBinding, StylePropBinding, StylePropShorthand, VerbosePropBinding };

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

@@ -1,4 +1,5 @@
 //#region ../config/dist/component-refs.d.ts
+//#region src/component-refs.d.ts
 /**
  * Augmentable registries + template-literal ref types for the
  * component-API surface.
@@ -63,6 +64,14 @@ interface RegisteredStyleProps {}
  * call.
  */
 interface RegisteredComposites {}
+/**
+ * Registered motion-preset names. Each key is the preset identifier
+ * (`'{fadeIn}'`); value is `void`.
+ *
+ * Populated by codegen from `uds.config.ts`'s `.defineMotion({...})`
+ * (motion has no separate `.registerMotion` step today; the entries
+ * come directly from `defineMotion` keys).
+ */
 /**
  * Brace-wrapped reference to a registered React component. Falls open
  * to `'{${string}}'` when the registry is unaugmented (e.g. inside
@@ -81,5 +90,9 @@ type StylePropRef = [keyof RegisteredStyleProps] extends [never] ? `{${string}}`
  * when unaugmented.
  */
 type CompositeRef = [keyof RegisteredComposites] extends [never] ? `{${string}}` : `{${Extract<keyof RegisteredComposites, string>}}`;
+/**
+ * Brace-wrapped reference to a registered motion preset. Falls open
+ * when unaugmented.
+ */
 //#endregion
 export { ComponentRef, CompositeRef, RegisteredComponents, RegisteredComposites, RegisteredStyleProps, StylePropRef };

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

@@ -1 +1 @@
-import { ComponentsConfig } from "@uds/types";
+export { };

package/dist/config/dist/consts/defaultColors.d.ts

@@ -1,4 +1,5 @@
 //#region ../config/dist/consts/defaultColors.d.ts
+//#region src/consts/defaultColors.d.ts
 declare const defaultColors: {
   inherit: string;
   current: string;
@@ -247,6 +248,6 @@ declare const defaultColors: {
   'rose-800': string;
   'rose-900': string;
   'rose-950': string;
-};
+}; //#endregion
 //#endregion
 export { defaultColors };

package/dist/config/dist/createConfig.d.ts

@@ -6,14 +6,27 @@ import { ResolvedStyleProp } from "./resolveStyleProp.js";
 import { BaseModifierProp, ComponentsConfig, CompositeStylesConfig, ConfigurableProp, ModifierProp, MotionPreset, RemotionComponentDef, RemotionConfig, RemotionTransitionDef } from "@uds/types";
 
 //#region ../config/dist/createConfig.d.ts
+//#region src/createConfig.d.ts
 type MotionPresetsDef = Record<string, MotionPreset>;
 type MotionAliasValue<TMotion> = TMotion extends Record<string, infer V> ? Extract<V, string> : never;
 type EmptyMotion = {};
 type EmptyCompositeStyles = {};
 /**
  * Transform composite-styles config type into the reference shape passed to
- * defineModifiers. Walks `T[K]['styles'][V]` so the modifier callback can
+ * `defineModifiers`. Walks `T[K]['styles'][V]` so the modifier callback can
  * write `compositeStyles.elevation['1'].className` (flat for ergonomics).
+ *
+ * Kept for the legacy callback API. New code should prefer the brace-ref
+ * form for selector authoring:
+ *
+ *   ```ts
+ *   .defineModifiers([
+ *     { modifier: '_onElevated', selector: '{composite/elevation/1}' },
+ *   ])
+ *   ```
+ *
+ * The `{composite/<group>/<value>}` ref expands to a container style query
+ * at `defineModifiers` time. See [[UDS-1644]].
  */
 type CompositeStylesReference<T> = { [K in keyof T]: T[K] extends {
   styles: infer S;
@@ -78,6 +91,12 @@ type GetModifierFromInput<I extends ModesInput> = { [SetKey in keyof I]: { [OptK
 } ? M extends ModifierNameShape ? M : never : OptKey extends string ? `_${OptKey}` : never }[keyof I[SetKey]['options']] }[keyof I];
 /** Reject any input whose derived/explicit modifiers collide with reserved names. */
 type CheckForReservedModifiersInput<I extends ModesInput> = true extends HasReservedModifier<GetModifierFromInput<I>> ? 'ERROR: Cannot use reserved modifier names from ModifierProp. Please use a different modifier name.' : I;
+/**
+ * Convert the authored object-keyed input into the internal `ModeGroup[]` shape.
+ * Derives `_${optionKey}` modifiers when no explicit `modifier` is provided.
+ * Never sets `default: true` — the new API has no concept of a default option;
+ * downstream consumers treat "no option active" as the implicit default.
+ */
 interface ModifierDef {
   modifier: ModifierNameShape;
   selector: string;
@@ -157,6 +176,7 @@ type VarsToTokens<TVars extends VarsConfig> = { [K in keyof TVars]: { [T in Excl
 type MergeTokens<A, B> = { [K in keyof A | keyof B]: K extends keyof B ? K extends keyof A ? A[K] & B[K] : B[K] : K extends keyof A ? A[K] : never };
 /** Build a structured token reference object from atomic tokens */
 declare function buildTokenReference(atomic: AtomicToken<ModifierNameShape>[], configPrefix: string): Record<string, Record<string, string>>;
+/** Build a structured composite-styles reference object for use in defineModifiers context */
 /** Global styles definition — CSS selector → style props */
 type GlobalStylesDef = Record<string, Record<string, any>>;
 /** CSS properties for the example wrapper element */
@@ -360,6 +380,10 @@ interface UdsConfig<TModifier extends ModifierNameShape = ModifierProp, TTokens
 type AnyUdsConfig = UdsConfig<ModifierNameShape, any, any, any, any, any, any>;
 /** Extract the raw config data from a builder instance */
 declare function resolveConfig(config: AnyUdsConfig): UdsConfigData;
+/**
+ * Resolve configuration with all token references replaced by their raw values.
+ * Useful for tools that need the actual values (e.g. anatomy generation).
+ */
 declare function createConfigBuilder<TModifier extends ModifierNameShape = ModifierProp, TTokens = EmptyTokens, TMotion = EmptyMotion, TExt extends Record<string, any> = {}, TCompositeStyles = EmptyCompositeStyles, TModeModifiers extends ModifierNameShape = never, TVars extends VarsConfig = EmptyVars>(data: UdsConfigData, extensions?: TExt): UdsConfig<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars> & TExt;
 interface InterpolateMarker {
   __type: 'interpolate';

package/dist/config/dist/createConfig.js

@@ -4,9 +4,9 @@ import "../../utils/dist/index.js";
 import { getConfigurablePropMapping } from "../../core/dist/configurable-prop-helpers.js";
 import "../../core/dist/index.js";
 import { buildMotionReference, resolveComponentMotionAliases, validateComponentVariants } from "./component-resolution.js";
-import { applyPresetToData, deepMerge, mergeAtomic } from "./preset-merge.js";
 import { resolveTokenType, sniffTokenTypeFromValue } from "./resolveTokenTypes.js";
 import { resolveStyleProp } from "./resolveStyleProp.js";
+import { applyPresetToData, deepMerge, mergeAtomic } from "./preset-merge.js";
 import { setRegisteredStyleProps } from "./runtime-registry.js";
 //#region ../config/dist/createConfig.js
 /** biome-ignore-all lint/suspicious/noExplicitAny: necessary for dynamic builder to work correctly */
@@ -75,6 +75,26 @@ function buildCompositeStylesReference(compositeStyles) {
 	return result;
 }
 /**
+* Resolve `{composite/<group>/<value>}` brace-refs in a modifier `selector`
+* string. Each ref expands to a CSS container style query targeting the
+* composite's custom-property marker:
+*
+*   `{composite/elevation/1}`
+*   →  `@container style(--uds-composite-elevation: 1)`
+*
+* Multiple refs in the same string are supported. Unknown refs (composite
+* group not in config, or value not in that group's styles) pass through
+* unchanged so the caller can spot the typo at use time. See [[UDS-1644]].
+*/
+const COMPOSITE_REF_PATTERN = /\{composite\/([^/{}]+)\/([^/{}]+)\}/g;
+function resolveCompositeRefsInSelector(selector, compositeStyles) {
+	return selector.replace(COMPOSITE_REF_PATTERN, (raw, groupName, valueName) => {
+		const def = compositeStyles[groupName];
+		if (!def || !def.styles[valueName]) return raw;
+		return `@container style(--uds-composite-${safeTokenName(groupName)}: ${safeTokenName(valueName)})`;
+	});
+}
+/**
 * Migrate legacy `macros` JSON (the pre-rename shape) into the new
 * `compositeStyles` shape. Each old key (`elevation`) becomes a `{ label,
 * styles }` def so older serialized configs (in `uds.config.json`,
@@ -370,13 +390,16 @@ function createConfigBuilder(data, extensions) {
 			}, extensions);
 		},
 		defineModifiers(params) {
-			const resolved = typeof params === "function" ? params({
+			const resolvedWithComposites = (typeof params === "function" ? params({
 				tokens: buildTokenReference(data.atomic, data.prefix),
 				compositeStyles: buildCompositeStylesReference(data.compositeStyles)
-			}) : params;
+			}) : params).map((def) => ({
+				...def,
+				selector: resolveCompositeRefsInSelector(def.selector, data.compositeStyles)
+			}));
 			return createConfigBuilder({
 				...data,
-				modifiers: [...data.modifiers, ...resolved]
+				modifiers: [...data.modifiers, ...resolvedWithComposites]
 			}, extensions);
 		},
 		defineCompositeStyles(params) {

package/dist/config/dist/defineComponent.d.ts

@@ -3,6 +3,7 @@ import { Props } from "./Props.js";
 import { ReactNode } from "react";
 
 //#region ../config/dist/defineComponent.d.ts
+//#region src/defineComponent.d.ts
 /**
  * A React component bound to a `defineComponent` config, with the
  * source config attached as a phantom type slot. Tools (codegen,
@@ -13,5 +14,11 @@ import { ReactNode } from "react";
 type BoundComponent<TConfig extends ComponentConfigValue<Record<string, LayerInput>, any, HtmlTag | undefined>, TExtra extends Record<string, unknown> = {}> = React.FC<Props<TConfig> & TExtra> & {
   readonly __config: TConfig;
 };
+/**
+ * A `defineComponent({...})` config value with a `.render(fn)` builder
+ * method bolted on. The builder is non-enumerable so JSON serialization
+ * still produces pure data — codegen can read `__kind`, `layers`,
+ * `props`, and `defaultProps` without seeing the render hook.
+ */
 //#endregion
 export { BoundComponent };

package/dist/config/dist/defineStyleProp.d.ts

@@ -1,4 +1,4 @@
-import { CssValue, CssValueTypeName } from "./types/css-values.js";
+import { CssValueTypeName } from "./types/css-values.js";
 
 //#region ../config/dist/defineStyleProp.d.ts
 /** Runtime input type for `toCss` based on the entry's `type`. */
@@ -22,10 +22,31 @@ type ArbitraryEntry = { [T in CssValueTypeName]: {
  *  - An array of {@link ArbitraryEntry} for multi-shape acceptance.
  */
 type ArbitrarySpec = CssValueTypeName | readonly ArbitraryEntry[];
+/**
+ * The literal-keyword subset of values a property accepts, derived from
+ * {@link CssPropertyValues}[P]. For custom CSS properties (`--*`) the value
+ * type is governed by the required `cssType` field instead, so any string
+ * is accepted at the type level.
+ */
 type StylePropMetadata = {
   label?: string;
   description?: string;
 };
+/**
+ * A finalized style prop. Returned by `defineStyleProp(spec)` (or the
+ * `.metadata({...})` chain). Consumers wrap these in
+ * `uds.registerStyleProps({ <propName>: ... })`.
+ *
+ * `cssProperty` is passed through verbatim from the authored input:
+ *  - **string** — a direct prop writing one CSS property.
+ *  - **`readonly string[]`** — a fan-out prop writing every CSS
+ *    property in the list (e.g. `borderRadiusStart` covering both
+ *    start-side corners).
+ *
+ * Readers that need iteration normalize at the call site
+ * (`Array.isArray(p) ? p : [p]`); readers that only need the primary
+ * use the string directly or `Array.isArray(p) ? p[0] : p`.
+ */
 /**
  * Internal shape attached to a {@link StyleProp} by `.withOpacity()`.
  * The resolver inspects this at `resolveConfig` time to synthesize a
@@ -59,5 +80,14 @@ interface AnyStyleProp {
   readonly metadata: StylePropMetadata;
   readonly opacityPair?: OpacityPairSpec;
 }
+/**
+ * Return shape of {@link defineStyleProp}. The `metadata` field doubles as
+ * a callable chain: read it to access `{ label?, description? }` (both
+ * optional, so an unset metadata reads `undefined` for either field) or
+ * call it as `.metadata({ label, description })` to attach metadata and
+ * get back a plain {@link StyleProp}. A function satisfies the
+ * {@link StylePropMetadata} structural shape because both fields are
+ * optional, so the dual nature is type-safe.
+ */
 //#endregion
 export { AnyStyleProp, ArbitraryEntry, ArbitrarySpec, StylePropMetadata };

package/dist/config/dist/index.d.ts

@@ -5,8 +5,8 @@ import { BoundComponent } from "./defineComponent.js";
 import { ColorFn, ColorKeyword, CssAngle, CssColor, CssLength, CssPercentage, CssRatio, CssTime, CssValue, CssValueTypeName, HexColor, HslColor, RgbColor } from "./types/css-values.js";
 import { AnyStyleProp, ArbitraryEntry, ArbitrarySpec, StylePropMetadata } from "./defineStyleProp.js";
 import { TokenType, VarGroupDef, VarTokenDef, VarsConfig } from "./types.js";
-import { ResolvedStyleProp, ResolvedToken } from "./resolveStyleProp.js";
 import { AtomicToken, BuildOptions, CheckForReservedModifiersInput, ComponentConfig, DefineComponentInput, DefineComponentMotionInput, ExampleDef, ExampleEntryDef, ExampleLayoutStyles, GetModifierFromInput, GlobalStylesDef, InterpolateMarker, ModeGroup, ModeOption, ModeOptionInput, ModeSetInput, ModesInput, ModifierDef, MotionPresetsDef, SingleComponentDef, UdsConfig, UdsConfigData, buildTokenReference, createConfigBuilder, darker, lighter, resolveConfig } from "./createConfig.js";
+import { ResolvedStyleProp, ResolvedToken } from "./resolveStyleProp.js";
 import { defaultColors } from "./consts/defaultColors.js";
 import { SerializedConfig, TokenRef, buildReverseMap, deserializeConfig, serializeConfig } from "./serialize.js";
 import { ComponentsConfig as ComponentsConfig$1 } from "@uds/types";

package/dist/config/dist/resolveStyleProp.d.ts

@@ -1,6 +1,7 @@
 import { CssValueTypeName } from "./types/css-values.js";
 import { ArbitrarySpec, StylePropMetadata } from "./defineStyleProp.js";
 //#region ../config/dist/resolveStyleProp.d.ts
+//#region src/resolveStyleProp.d.ts
 interface ResolvedToken {
   /** The token's raw key, e.g. `'brand'`. */
   readonly name: string;
@@ -77,5 +78,11 @@ interface ResolvedStyleProp {
   readonly arbitrary: ArbitrarySpec | undefined;
   readonly metadata: StylePropMetadata;
 }
+/**
+ * Structurally-loose input shape for the resolver. Any `StyleProp<P>` from
+ * `defineStyleProp` is assignable to this. Defined locally so the
+ * resolver's signature doesn't expand `ValuesEntry<P>` over the full CSS
+ * property union (TS2590).
+ */
 //#endregion
 export { ResolvedStyleProp, ResolvedToken };

package/dist/config/dist/serialize.d.ts

@@ -3,6 +3,7 @@ import { AtomicToken, ExampleDef, ModeGroup, ModifierDef, MotionPresetsDef, UdsC
 import { CompositeStylesConfig } from "@uds/types";
 
 //#region ../config/dist/serialize.d.ts
+//#region src/serialize.d.ts
 type ModifierNameShape = `_${string}`;
 type TokenRef = {
   $ref: string;
@@ -67,6 +68,6 @@ declare function serializeConfig(config: UdsConfig): SerializedConfig;
  * Resolves `$ref` markers back to `var()` strings using the atomic token
  * definitions, then reconstructs the builder chain.
  */
-declare function deserializeConfig(data: SerializedConfig): UdsConfig;
+declare function deserializeConfig(data: SerializedConfig): UdsConfig; //#endregion
 //#endregion
 export { SerializedConfig, TokenRef, buildReverseMap, deserializeConfig, serializeConfig };

package/dist/config/dist/types/css-values.d.ts

@@ -1,4 +1,5 @@
 //#region ../config/dist/types/css-values.d.ts
+//#region src/types/css-values.d.ts
 /**
  * CSS value-type primitives — building blocks used by {@link CssPropertyValues}
  * in `./css-properties` and by `defineStyleProp` to constrain authored values.
@@ -55,6 +56,6 @@ type CssValue = {
   ident: string;
   string: string;
 };
-type CssValueTypeName = keyof CssValue;
+type CssValueTypeName = keyof CssValue; //#endregion
 //#endregion
 export { ColorFn, ColorKeyword, CssAngle, CssColor, CssLength, CssPercentage, CssRatio, CssTime, CssValue, CssValueTypeName, HexColor, HslColor, RgbColor };

package/dist/config/dist/types.d.ts

@@ -1,4 +1,5 @@
 //#region ../config/dist/types.d.ts
+//#region src/types.d.ts
 /**
  * Scalar DTCG-aligned token types. Composite types (shadow, gradient,
  * typography, border, transition, cubicBezier) are intentionally deferred
@@ -66,6 +67,6 @@ type VarGroupDef<M extends `_${string}` = `_${string}`> = {
  *   spacing: { $type: 'dimension', 1: { value: '0.25rem' }, 2: { value: '0.5rem' } },
  * }
  */
-type VarsConfig<M extends `_${string}` = `_${string}`> = Record<string, VarGroupDef<M>>;
+type VarsConfig<M extends `_${string}` = `_${string}`> = Record<string, VarGroupDef<M>>; //#endregion
 //#endregion
 export { TokenType, VarGroupDef, VarTokenDef, VarsConfig };