@yahoo/uds-v5-wip 1.52.0 → 1.53.0

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

@@ -167,6 +167,78 @@ 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>>>;
+/**
+ * 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
@@ -191,6 +263,11 @@ interface ComponentConfigValue<TLayers extends Record<string, LayerInput>, TProp
   readonly layers: TLayers;
   readonly props?: TProps;
   readonly defaultProps?: Record<string, unknown>;
+  /**
+   * 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-

package/dist/config.d.ts

@@ -35,50 +35,9 @@ declare const defaultPreset: UdsConfig<_$_uds_types0.ModifierProp | GetModifierF
     };
   };
 }>, {
-  opacity: {
-    0: string;
-    5: string;
-    10: string;
-    20: string;
-    40: string;
-    60: string;
-    80: string;
-    25: string;
-    30: string;
-    50: string;
-    70: string;
-    75: string;
-    90: string;
-    95: string;
-    100: string;
-  };
-  scale: {
-    0: string;
-    50: string;
-    75: string;
-    90: string;
-    95: string;
-    100: string;
-    105: string;
-    110: string;
-    125: string;
-    150: string;
-    200: string;
-  };
-  rotate: {
-    0: string;
-    1: string;
-    2: string;
-    3: string;
-    6: string;
-    12: string;
-    90: string;
-    45: string;
-    180: string;
-  };
   color: {
-    inherit: string;
     transparent: string;
+    inherit: string;
     current: string;
     "always/black": string;
     "always/white": string;
@@ -101,22 +60,16 @@ declare const defaultPreset: UdsConfig<_$_uds_types0.ModifierProp | GetModifierF
     inverse: string;
     "on-inverse": string;
   };
-  borderColor: {
-    brand: string;
-    accent: string;
-    alert: string;
-    positive: string;
-    warning: string;
-    primary: string;
-    secondary: string;
-    tertiary: string;
-    inverse: string;
-    surface: string;
-    "brand-wash": string;
-    "accent-wash": string;
-    "alert-wash": string;
-    "positive-wash": string;
-    "warning-wash": string;
+  shadow: {
+    none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    "2xl": string;
+    xs: string;
+    "2xs": string;
+    inner: string;
   };
   position: {
     auto: string;
@@ -128,17 +81,111 @@ declare const defaultPreset: UdsConfig<_$_uds_types0.ModifierProp | GetModifierF
     "2/4": string;
     "3/4": string;
   };
+  flex: {
+    1: string;
+    initial: string;
+    auto: string;
+    none: string;
+  };
+  rotate: {
+    0: string;
+    1: string;
+    2: string;
+    3: string;
+    6: string;
+    12: string;
+    90: string;
+    45: string;
+    180: string;
+  };
+  scale: {
+    0: string;
+    50: string;
+    75: string;
+    90: string;
+    95: string;
+    100: string;
+    105: string;
+    110: string;
+    125: string;
+    150: string;
+    200: string;
+  };
+  translate: {
+    0: string;
+    1: string;
+    2: string;
+    full: string;
+    "1/2": string;
+    "1/3": string;
+    "2/3": string;
+    "1/4": string;
+    "3/4": string;
+    4: string;
+    8: string;
+    0.5: string;
+    1.5: string;
+    2.5: string;
+    3: string;
+    3.5: string;
+    5: string;
+    6: string;
+    7: string;
+    9: string;
+    10: string;
+    11: string;
+    12: string;
+    14: string;
+    16: string;
+    20: string;
+    24: string;
+    28: string;
+    32: string;
+    36: string;
+    40: string;
+    44: string;
+    48: string;
+    52: string;
+    56: string;
+    60: string;
+    64: string;
+    72: string;
+    80: string;
+    96: string;
+  };
+  animation: {
+    none: string;
+    spin: string;
+    ping: string;
+  };
+  opacity: {
+    0: string;
+    5: string;
+    10: string;
+    20: string;
+    40: string;
+    60: string;
+    80: string;
+    25: string;
+    30: string;
+    50: string;
+    70: string;
+    75: string;
+    90: string;
+    95: string;
+    100: string;
+  };
   size: {
     auto: string;
     full: string;
-    max: string;
-    min: string;
     "1/2": string;
     "1/3": string;
     "2/3": string;
     "1/4": string;
     "2/4": string;
     "3/4": string;
+    min: string;
+    max: string;
     fit: string;
     "1/5": string;
     "2/5": string;
@@ -150,11 +197,6 @@ declare const defaultPreset: UdsConfig<_$_uds_types0.ModifierProp | GetModifierF
     "4/6": string;
     "5/6": string;
   };
-  animation: {
-    none: string;
-    ping: string;
-    spin: string;
-  };
   bg: {
     overlay: string;
     brand: string;
@@ -176,6 +218,32 @@ declare const defaultPreset: UdsConfig<_$_uds_types0.ModifierProp | GetModifierF
     "positive-wash": string;
     "warning-wash": string;
   };
+  radius: {
+    none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    full: string;
+    xs: string;
+  };
+  borderColor: {
+    brand: string;
+    accent: string;
+    alert: string;
+    positive: string;
+    warning: string;
+    primary: string;
+    secondary: string;
+    tertiary: string;
+    inverse: string;
+    surface: string;
+    "brand-wash": string;
+    "accent-wash": string;
+    "alert-wash": string;
+    "positive-wash": string;
+    "warning-wash": string;
+  };
   borderWidth: {
     none: string;
     thin: string;
@@ -184,16 +252,19 @@ declare const defaultPreset: UdsConfig<_$_uds_types0.ModifierProp | GetModifierF
   };
   divideWidth: {
     0: string;
-    4: string;
-    reverse: string;
     2: string;
+    reverse: string;
+    4: string;
     8: string;
   };
-  flex: {
+  blur: {
     none: string;
-    initial: string;
-    auto: string;
-    1: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    "2xl": string;
+    "3xl": string;
   };
   flexGrow: {
     0: string;
@@ -202,29 +273,12 @@ declare const defaultPreset: UdsConfig<_$_uds_types0.ModifierProp | GetModifierF
   flexShrink: {
     0: string;
   };
-  aspectRatio: {
-    square: string;
-    landscape: string;
-    portrait: string;
-    widescreen: string;
-    ultrawide: string;
-    golden: string;
-  };
-  zIndex: {
-    0: string;
-    auto: string;
-    10: string;
-    20: string;
-    40: string;
-    30: string;
-    50: string;
-  };
   spacing: {
     0: string;
-    4: string;
     1: string;
     2: string;
     px: string;
+    4: string;
     8: string;
     0.5: string;
     1.5: string;
@@ -256,57 +310,62 @@ declare const defaultPreset: UdsConfig<_$_uds_types0.ModifierProp | GetModifierF
     80: string;
     96: string;
   };
-  w: {
-    screen: string;
-    svw: string;
-    lvw: string;
-    dvw: string;
-  };
-  outlineWidth: {
+  zIndex: {
     0: string;
-    4: string;
-    1: string;
-    2: string;
-    8: string;
+    auto: string;
+    10: string;
+    20: string;
+    40: string;
+    30: string;
+    50: string;
   };
   outlineOffset: {
     0: string;
-    4: string;
     1: string;
     2: string;
+    4: string;
     8: string;
   };
   ringWidth: {
     0: string;
-    4: string;
-    inset: string;
     1: string;
+    inset: string;
     2: string;
+    4: string;
     8: string;
   };
   ringOffsetWidth: {
     0: string;
-    4: string;
     1: string;
     2: string;
+    4: string;
     8: string;
   };
-  shadow: {
-    none: string;
-    sm: string;
-    md: string;
-    lg: string;
-    xl: string;
-    "2xl": string;
-    "2xs": string;
-    xs: string;
-    inner: string;
+  h: {
+    screen: string;
+    svh: string;
+    lvh: string;
+    dvh: string;
+  };
+  w: {
+    screen: string;
+    svw: string;
+    lvw: string;
+    dvw: string;
   };
   strokeWidth: {
     0: string;
     1: string;
     2: string;
   };
+  skew: {
+    0: string;
+    1: string;
+    2: string;
+    3: string;
+    6: string;
+    12: string;
+  };
   fontFamily: {
     sans: string;
     serif: string;
@@ -314,8 +373,8 @@ declare const defaultPreset: UdsConfig<_$_uds_types0.ModifierProp | GetModifierF
   };
   fontWeight: {
     normal: string;
-    thin: string;
     bold: string;
+    thin: string;
     medium: string;
     extralight: string;
     light: string;
@@ -332,8 +391,8 @@ declare const defaultPreset: UdsConfig<_$_uds_types0.ModifierProp | GetModifierF
     widest: string;
   };
   lineHeight: {
-    none: string;
     normal: string;
+    none: string;
     tight: string;
     relaxed: string;
   };
@@ -342,82 +401,23 @@ declare const defaultPreset: UdsConfig<_$_uds_types0.ModifierProp | GetModifierF
     sm: string;
     md: string;
     lg: string;
-    "2xs": string;
     xs: string;
+    "2xs": string;
   };
-  blur: {
-    none: string;
-    sm: string;
-    md: string;
-    lg: string;
-    xl: string;
-    "2xl": string;
-    "3xl": string;
-  };
-  translate: {
+  outlineWidth: {
     0: string;
-    4: string;
-    full: string;
     1: string;
     2: string;
-    "1/2": string;
-    "1/3": string;
-    "2/3": string;
-    "1/4": string;
-    "3/4": string;
+    4: string;
     8: string;
-    0.5: string;
-    1.5: string;
-    2.5: string;
-    3: string;
-    3.5: string;
-    5: string;
-    6: string;
-    7: string;
-    9: string;
-    10: string;
-    11: string;
-    12: string;
-    14: string;
-    16: string;
-    20: string;
-    24: string;
-    28: string;
-    32: string;
-    36: string;
-    40: string;
-    44: string;
-    48: string;
-    52: string;
-    56: string;
-    60: string;
-    64: string;
-    72: string;
-    80: string;
-    96: string;
-  };
-  radius: {
-    none: string;
-    sm: string;
-    md: string;
-    lg: string;
-    xl: string;
-    xs: string;
-    full: string;
-  };
-  h: {
-    screen: string;
-    svh: string;
-    lvh: string;
-    dvh: string;
   };
-  skew: {
-    0: string;
-    1: string;
-    2: string;
-    3: string;
-    6: string;
-    12: string;
+  aspectRatio: {
+    square: string;
+    landscape: string;
+    portrait: string;
+    widescreen: string;
+    ultrawide: string;
+    golden: string;
   };
 }, {}, {}, {}, GetModifierFromInput<{
   readonly colorMode: {

package/dist/core/dist/createComponent.js

@@ -1,6 +1,6 @@
+import { applySlotOverrides, assertTransformedConfig, buildSlotProps, buildUntransformedSlotProps, inferComponentNameFromRenderFn, mergeMotionConfig, mergeRootClassName, mergeSlotMotionProps, partitionMergedProps } from "./createComponent.boundaries.js";
 import { processStyleProps } from "./getStyles.js";
 import { createComponentStyler } from "./getComponentStyles.js";
-import { applySlotOverrides, assertTransformedConfig, buildSlotProps, buildUntransformedSlotProps, inferComponentNameFromRenderFn, mergeMotionConfig, mergeRootClassName, mergeSlotMotionProps, partitionMergedProps } from "./createComponent.boundaries.js";
 import { createElement } from "react";
 //#region ../core/dist/createComponent.js
 function createPrimitiveRenderFn(tag) {

package/dist/core/dist/getStyles.js

@@ -3,8 +3,8 @@ import "../../utils/dist/index.js";
 import { expandCompositeStyles, getCompositeStylesConfig } from "./compositeStyles.js";
 import { propMappings } from "./style-prop-data.js";
 import { stylePropsTwMap } from "./generated/stylePropsTwMap.js";
-import { modifierMappings } from "./modifier-mappings.js";
 import { colorPropToOpacityProp } from "./color-opacity-map.js";
+import { modifierMappings } from "./modifier-mappings.js";
 import { clsx } from "clsx";
 //#region ../core/dist/getStyles.js
 /** Convert kebab-case CSS property to camelCase for React inline styles.