@yahoo/uds-v5-wip 1.52.1 → 1.54.0

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

@@ -1,4 +1,5 @@
 import { ComponentRef, CompositeRef, RegisteredComponents, StylePropRef } from "./component-refs.js";
+import * as React$1 from "react";
 import { ReactNode } from "react";
 
 //#region ../config/dist/component-config.d.ts
@@ -15,14 +16,28 @@ type HtmlTag = string;
 /**
  * Object form for a primitive (HTML-tag) layer that needs locked attrs
  * or default CSS-property values.
+ *
+ * Distributive mapped union over `keyof React.JSX.IntrinsicElements` so
+ * `attrs` is narrowed to the HTML props valid for the chosen `tag` at
+ * the call site — `{ tag: 'a', attrs: { href: '/x' } }` type-checks;
+ * `{ tag: 'div', attrs: { href: '/x' } }` does not. `defaultProps`
+ * stays loosely typed: it carries style-prop-keyed CSS declarations
+ * (incl. `_hover`/`_focus`/etc. modifier keys) that feed the @utility
+ * codegen, NOT HTML props.
  */
-interface PrimitiveLayer {
-  tag: HtmlTag;
-  /** HTML attributes always applied to this layer (e.g. `role="alert"`). */
-  attrs?: Record<string, unknown>;
-  /** Default style-prop values for this layer. */
+type PrimitiveLayer = { [T in keyof React$1.JSX.IntrinsicElements]: {
+  tag: T; /** HTML attributes always applied to this layer (e.g. `role="alert"`). */
+  attrs?: Partial<React$1.ComponentPropsWithoutRef<T>>;
+  /**
+   * Default per-layer CSS declarations. Keys are style-prop names (or
+   * raw CSS properties when no registered style prop applies); values
+   * are token refs (`'{spacing/4}'`), alias names, or literal CSS.
+   * Modifier keys (`_hover`, `_focus`, `_dataDisabled`, ...) nest the
+   * same shape recursively. Codegen compiles this into a single
+   * `@utility componentName-layerName { ... }` block.
+   */
   defaultProps?: Record<string, unknown>;
-}
+} }[keyof React$1.JSX.IntrinsicElements];
 /**
  * Object form for a layer that's a composed React component (registered
  * via `.registerComponents({...})`). The `component` field is a brace-ref
@@ -96,18 +111,38 @@ interface CompositeBinding {
 }
 /**
  * Forward a JSX prop value to one of the component's layers as an
- * existing surface key. If the target layer is a primitive, `from` is
- * an HTML attr / event name; if it's a composed component, `from` is
- * one of that component's existing props.
+ * 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.
  *
- * `from` is a bare string (no braces) — the absence of `styleProp` /
- * `composite` keys is how the framework discriminates this shape from
- * the registered-binding shapes.
+ * Authoring sites get the narrower `TypedForwardBinding<TLayers>`
+ * (below) via `VerbosePropBinding<TLayers>`, which structurally
+ * extends this loose form.
  */
-interface ForwardBinding {
-  layer: string;
-  from: string;
-}
+/**
+ * Authoring-site form of `ForwardBinding`, narrowed against the
+ * component's own layer map. Distributes over `keyof TLayers` so:
+ *
+ *  - `layer` is constrained to one of the declared layer names.
+ *  - `from` is constrained by the target layer's shape:
+ *      • **ComposedLayer** (`{ component: '{Box}' }`) → one of the
+ *        wrapped component's exposed JSX props (looked up against
+ *        `RegisteredComponents['Box']`), so `{ layer: 'label', from:
+ *        'variant' }` only type-checks if Text registers `variant`.
+ *      • **PrimitiveLayer / bare HTML tag** → any string (HTML attr or
+ *        event name; type-precision here would require pulling
+ *        `JSX.IntrinsicElements[tag]`, deferred).
+ *
+ * Structurally extends `ForwardBinding` so the runtime's type-guard
+ * (`isForwardBinding`) still recognizes typed entries.
+ */
+type TypedForwardBinding<TLayers extends Record<string, LayerInput>> = { [K in keyof TLayers & string]: {
+  layer: K;
+  from: TLayers[K] extends {
+    component: `{${infer C}}`;
+  } ? C extends keyof RegisteredComponents ? keyof RegisteredComponents[C] & string : string : string;
+} }[keyof TLayers & string];
 /**
  * Boolean prop — toggled on/off, no value beyond presence. Useful for
  * `loading`, `disabled`, `selected`. Each layer's bundle gets a
@@ -143,22 +178,28 @@ type StylePropShorthand = StylePropRef;
  * `{ layer, styleProp }` binding — no shorthand. The shorthand
  * `'{bg}'` is allowed only in the primitive form's props (see
  * `PrimitivePropBinding`).
+ *
+ * Generic over `TLayers` so `TypedForwardBinding` can narrow the
+ * `layer` + `from` fields against the component's own layer map.
+ * Consumers that don't know the layer map (read-side helpers,
+ * `bindRender`) parameterize with the wide default
+ * `Record<string, LayerInput>` and get the loose `ForwardBinding`.
  */
-type VerbosePropBinding = StylePropBinding | SingleLayerCompositeBinding | CompositeBinding | ForwardBinding | BoolMarker | EnumMarker<any>;
+type VerbosePropBinding<TLayers extends Record<string, LayerInput> = Record<string, LayerInput>> = StylePropBinding | SingleLayerCompositeBinding | CompositeBinding | TypedForwardBinding<TLayers> | BoolMarker | EnumMarker<any>;
 /**
  * All allowed shapes for a single entry in the primitive form's `props`
  * block. Primitive form adds the `StylePropShorthand` brace-ref
  * (`'{bg}'`) on top of every verbose form — the root layer is
  * unambiguous so the shorthand resolves trivially.
  */
-type PrimitivePropBinding = StylePropShorthand | VerbosePropBinding;
+type PrimitivePropBinding<TLayers extends Record<string, LayerInput> = Record<string, LayerInput>> = StylePropShorthand | VerbosePropBinding<TLayers>;
 /**
  * Union of every legal prop-binding shape across both forms. Read-side
  * helpers (`Props<TConfig>`, runtime resolution) accept this widest
  * union; authoring-side input types (`ComponentConfigInput`) take the
  * tighter `VerbosePropBinding`.
  */
-type PropBinding = PrimitivePropBinding;
+type PropBinding<TLayers extends Record<string, LayerInput> = Record<string, LayerInput>> = PrimitivePropBinding<TLayers>;
 /**
  * Marker for a boolean JSX prop. Use inside the `props` block:
  *
@@ -167,6 +208,102 @@ type PropBinding = PrimitivePropBinding;
  *       disabled: bool(),
  *     }
  */
+/**
+ * Names of prop bindings that participate in matrix/strip iteration —
+ * i.e. props authored as `enums({...})` or `bool()`. Other prop bindings
+ * (style props, forwards, composites) don't have a fixed enumerable
+ * set of values to iterate over and so aren't valid axes.
+ *
+ * Resolves to `never` when `TProps` declares no enum/bool bindings.
+ */
+type IterableAxisOf<TProps> = { [K in keyof TProps]: TProps[K] extends EnumMarker<Record<string, unknown>> | BoolMarker ? K : never }[keyof TProps] & string;
+/**
+ * A single example entry — describes one cell, one row, or one matrix.
+ *
+ * Three iteration shapes are supported, distinguished by which fields
+ * are present:
+ *
+ * - Static: only `props`. Renders one cell with `props` as the consumer-
+ *   facing prop values.
+ * - 1D strip: `axis` plus `props`. Iterates the named enum/bool prop and
+ *   renders one cell per value.
+ * - 2D matrix: `rows` and `cols` plus `props`. Iterates both and renders
+ *   the Cartesian product as a labeled grid.
+ *
+ * `axis` and `rows`/`cols` are mutually exclusive; `rows` and `cols`
+ * must appear together. The runtime validator enforces both.
+ *
+ * `props` is keyed by *consumer-facing prop name* — the same names a
+ * caller of `<Link href='#'>` would pass — not by internal layer name.
+ * The renderer maps consumer props to layer bundles using the
+ * component's own `props` bindings.
+ *
+ * Authors don't control wrapper layout (gaps, padding, alignment) — the
+ * renderer (Studio / docs) owns those decisions so the matrix surface
+ * stays consistent across components.
+ */
+interface ExampleEntry<TAxis extends string = string> {
+  /** 1D iteration — one cell per value of this enum/bool prop. */
+  axis?: TAxis;
+  /** 2D iteration — rows × cols matrix. Mutually exclusive with `axis`. */
+  rows?: TAxis;
+  cols?: TAxis;
+  /**
+   * Consumer-facing prop values used by every cell. For 1D / 2D entries,
+   * the cell's axis coords are overlaid on top of these (axis values win
+   * on collision with `props.<axis>`).
+   */
+  props?: Record<string, unknown>;
+}
+/**
+ * Component examples — required `default` plus any number of additional
+ * named entries. `default` is the canonical single-instance showcase
+ * Studio + docs fall back to when no specific example is requested.
+ *
+ * `default` is distinct from `defaultProps`: `defaultProps` is the
+ * runtime API default applied when a consumer omits a prop; `examples.default`
+ * is the showcase content (label, icons, href) used by tooling. A
+ * component can declare both without conflict.
+ *
+ * Axis types narrow to `IterableAxisOf<TProps>` so referencing a non-
+ * enum/bool prop name in `axis` / `rows` / `cols` is a type error.
+ */
+type Examples<TProps extends Record<string, unknown> = Record<string, unknown>> = {
+  default: ExampleEntry<IterableAxisOf<TProps>>;
+} & Record<string, ExampleEntry<IterableAxisOf<TProps>>>;
+/**
+ * A compound-variant entry — applies a per-layer style override when
+ * *all* `conditions` match the incoming JSX props. Mirrors the legacy
+ * `compoundVariants: [{ conditions, styles }]` shape (see
+ * `componentCompoundClass()` for the emitted class name).
+ *
+ *     compoundVariants: [
+ *       {
+ *         conditions: { size: 'sm', variant: 'brand' },
+ *         styles: { root: { boxShadow: '{shadow/sm}' } },
+ *       },
+ *     ]
+ *
+ * `conditions` keys are JSX-prop names that resolve to `enums()` /
+ * `bool()` markers in the `props` block; values are the variant values
+ * (or `'true'` / `'false'` for bools) that must all match for the entry
+ * to apply. Codegen emits one `@utility componentName-layerName--<sorted
+ * conditions>` block per (layer); runtime appends that class when
+ * conditions match.
+ */
+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
@@ -183,14 +320,25 @@ type PropBinding = PrimitivePropBinding;
  * When the root isn't a literal tag (brace-ref / composed layer), it's
  * `undefined` and `Props<TConfig>` falls back to `HTMLAttributes<HTMLElement>`.
  *
- * The component's name is supplied at registration time, not here.
+ * `__componentName` is a non-enumerable runtime slot assigned by
+ * `.registerComponents({ Name: config })` — the key becomes the name.
+ * The renderer reads it to emit `componentName-layerName` @utility
+ * classes onto each layer's bundle (matching the classes codegen emits
+ * from the same `defaultProps`). Absent until registered.
  */
 interface ComponentConfigValue<TLayers extends Record<string, LayerInput>, TProps extends Record<string, PropBinding> = Record<string, PropBinding>, TTag extends HtmlTag | undefined = RootTag<TLayers>> {
   readonly __kind: 'componentConfig';
   readonly __tag?: TTag;
+  readonly __componentName?: string;
   readonly layers: TLayers;
   readonly props?: TProps;
   readonly defaultProps?: Record<string, unknown>;
+  readonly compoundVariants?: CompoundVariant[];
+  /**
+   * Component examples — see {@link Examples}. Carried through from
+   * `ComponentConfigInput.examples`.
+   */
+  readonly examples?: Examples<TProps>;
 }
 /**
  * The bundle passed to the render function for each layer — a ready-to-
@@ -198,4 +346,4 @@ interface ComponentConfigValue<TLayers extends Record<string, LayerInput>, TProp
  * function destructures `props.<layerName>` into the JSX position.
  */
 //#endregion
-export { BoolMarker, ComponentConfigValue, ComposedLayer, CompositeBinding, EnumMarker, ForwardBinding, HtmlTag, LayerInput, PrimitiveLayer, PrimitivePropBinding, PropBinding, RootTag, SingleLayerCompositeBinding, StylePropBinding, StylePropShorthand, VerbosePropBinding };
+export { BoolMarker, ComponentConfigValue, ComposedLayer, CompositeBinding, CompoundVariant, EnumMarker, HtmlTag, LayerInput, PrimitiveLayer, PrimitivePropBinding, PropBinding, RootTag, SingleLayerCompositeBinding, StylePropBinding, StylePropShorthand, VerbosePropBinding };

package/dist/config/dist/createComponent.js

@@ -1 +1 @@
-import "react";
+import "../../utils/dist/index.js";

package/dist/config/dist/createConfig.js

@@ -4,10 +4,10 @@ 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 { setRegisteredStyleProps } from "./runtime-registry.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 */
 /**
@@ -449,8 +449,16 @@ function createConfigBuilder(data, extensions) {
 		},
 		registerComponents(configs) {
 			const normalized = {};
-			for (const [name, entry] of Object.entries(configs)) if (typeof entry === "function" && "__config" in entry) normalized[name] = entry.__config;
-			else normalized[name] = entry;
+			for (const [name, entry] of Object.entries(configs)) {
+				const config = typeof entry === "function" && "__config" in entry ? entry.__config : entry;
+				Object.defineProperty(config, "__componentName", {
+					enumerable: false,
+					configurable: true,
+					writable: true,
+					value: name
+				});
+				normalized[name] = config;
+			}
 			return next({ componentConfigs: {
 				...data.componentConfigs ?? {},
 				...normalized

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

@@ -1,5 +1,5 @@
 import { ComponentRef, CompositeRef, RegisteredComponents, RegisteredComposites, RegisteredStyleProps, StylePropRef } from "./component-refs.js";
-import { BoolMarker, ComponentConfigValue, ComposedLayer, CompositeBinding, EnumMarker, ForwardBinding, HtmlTag, LayerInput, PrimitiveLayer, PrimitivePropBinding, PropBinding, RootTag, SingleLayerCompositeBinding, StylePropBinding, StylePropShorthand, VerbosePropBinding } from "./component-config.js";
+import { BoolMarker, ComponentConfigValue, ComposedLayer, CompositeBinding, CompoundVariant, EnumMarker, HtmlTag, LayerInput, PrimitiveLayer, PrimitivePropBinding, PropBinding, RootTag, SingleLayerCompositeBinding, StylePropBinding, StylePropShorthand, VerbosePropBinding } from "./component-config.js";
 import { Props } from "./Props.js";
 import { BoundComponent } from "./defineComponent.js";
 import { ColorFn, ColorKeyword, CssAngle, CssColor, CssLength, CssPercentage, CssRatio, CssTime, CssValue, CssValueTypeName, HexColor, HslColor, RgbColor } from "./types/css-values.js";

package/dist/config/dist/index.js

@@ -1,6 +1,5 @@
 import "./component-resolution.js";
 import "./consts/defaultColors.js";
-import "./createComponent.js";
 import "./propertyAcceptedTypes.js";
 import "./refs.js";
 import "./resolveTokenTypes.js";

package/dist/config/dist/refs.js

@@ -27,22 +27,30 @@ import "../../utils/dist/index.js";
 * still resolves to `var(--uds-color-brand)`, regardless of whether the
 * brand value itself is a literal or a ref.
 */
-const REF_PATTERN = /^\{([^/{}]+)\/([^{}]+)\}$/;
+const REF_PATTERN = /^\{([^{}]+)\}$/;
 /**
 * Parse a value as a token ref. Returns `null` when the value isn't a
 * brace-wrapped ref of the form `{namespace/name}`. The `name` portion
 * may contain additional slashes — only the first slash is treated as
 * the namespace separator.
+*
+* Color-modifier values (`darken` / `lighten`) are a structured object
+* form, not a string-encoded suffix. See {@link TokenWithModifier}.
 */
 function parseTokenRef(value) {
-	const match = REF_PATTERN.exec(value);
-	if (!match) return null;
-	const namespace = match[1];
-	const name = match[2];
-	if (!namespace || !name) return null;
+	const outer = REF_PATTERN.exec(value);
+	if (!outer) return null;
+	const body = outer[1];
+	if (!body) return null;
+	return parseRefBody(body);
+}
+function parseRefBody(body) {
+	if (body.includes("{") || body.includes("}")) return null;
+	const slashIdx = body.indexOf("/");
+	if (slashIdx <= 0 || slashIdx >= body.length - 1) return null;
 	return {
-		namespace,
-		name
+		namespace: body.slice(0, slashIdx),
+		name: body.slice(slashIdx + 1)
 	};
 }
 /**