@yahoo/uds-v5-wip 1.52.1 → 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/dist/createConfig.js

@@ -5,9 +5,9 @@ import { getConfigurablePropMapping } from "../../core/dist/configurable-prop-he
 import "../../core/dist/index.js";
 import { buildMotionReference, resolveComponentMotionAliases, validateComponentVariants } from "./component-resolution.js";
 import { setRegisteredStyleProps } from "./runtime-registry.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";
 //#region ../config/dist/createConfig.js
 /** biome-ignore-all lint/suspicious/noExplicitAny: necessary for dynamic builder to work correctly */
 /**

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.

package/dist/loader/dist/packages/core/dist/getStyles.js

@@ -2,8 +2,8 @@ import "../../../../../utils/dist/index.js";
 import "./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";
 //#region ../loader/dist/packages/core/dist/getStyles.js
 /** Convert kebab-case CSS property to camelCase for React inline styles.
 *  CSS custom properties (--*) are kept as-is since React supports them verbatim. */

package/dist/remotion/dist/components/image-slide.d.ts

@@ -2,7 +2,6 @@ import * as _$react from "react";
 import * as _$_uds_types0 from "@uds/types";
 
 //#region ../remotion/dist/components/image-slide.d.ts
-//#region src/components/image-slide.d.ts
 /**
  * @description Full-screen image slide with optional caption overlay
  */
@@ -15,6 +14,6 @@ declare const ImageSlide: _$react.FC<_$_uds_types0.CreateComponentProps<string,
   root: "div";
   image: "img";
   caption: "div";
-}>>; //#endregion
+}>>;
 //#endregion
 export { ImageSlide };

package/dist/remotion/dist/components/image-slide.js

@@ -5,15 +5,15 @@ import { jsx, jsxs } from "react/jsx-runtime";
 /**
 * @description Full-screen image slide with optional caption overlay
 */
-const ImageSlide = createComponent(({ props, src, alt, caption, children }) => /* @__PURE__ */ jsxs("div", {
+const ImageSlide = createComponent(({ props, src, alt, caption, children }) => jsxs("div", {
 	...props.root,
 	children: [
-		/* @__PURE__ */ jsx("img", {
+		jsx("img", {
 			...props.image,
 			src,
 			alt: alt ?? ""
 		}),
-		caption && /* @__PURE__ */ jsx("div", {
+		caption && jsx("div", {
 			...props.caption,
 			children: caption
 		}),

package/dist/remotion/dist/components/index.js

@@ -1,16 +1,16 @@
 import "./image-slide.js";
-import "./lower-third.js";
-import "./quote-card.js";
-import "./split-screen.js";
-import "./stat-card.js";
-import "./text-overlay.js";
-import "./title-card.js";
-import "./typing-text.js";
 import "./image-slide.config.js";
+import "./lower-third.js";
 import "./lower-third.config.js";
+import "./quote-card.js";
 import "./quote-card.config.js";
+import "./split-screen.js";
 import "./split-screen.config.js";
+import "./stat-card.js";
 import "./stat-card.config.js";
+import "./text-overlay.js";
 import "./text-overlay.config.js";
+import "./title-card.js";
 import "./title-card.config.js";
+import "./typing-text.js";
 import "./typing-text.config.js";

package/dist/remotion/dist/components/lower-third.d.ts

@@ -2,7 +2,6 @@ import * as _$react from "react";
 import * as _$_uds_types0 from "@uds/types";
 
 //#region ../remotion/dist/components/lower-third.d.ts
-//#region src/components/lower-third.d.ts
 /**
  * @description Lower-third overlay with title and optional subtitle
  */
@@ -16,6 +15,6 @@ declare const LowerThird: _$react.FC<_$_uds_types0.CreateComponentProps<string,
   content: "div";
   title: "div";
   subtitle: "div";
-}>>; //#endregion
+}>>;
 //#endregion
 export { LowerThird };

package/dist/remotion/dist/components/lower-third.js

@@ -5,16 +5,16 @@ import { jsx, jsxs } from "react/jsx-runtime";
 /**
 * @description Lower-third overlay with title and optional subtitle
 */
-const LowerThird = createComponent(({ props, title, subtitle, children }) => /* @__PURE__ */ jsxs("div", {
+const LowerThird = createComponent(({ props, title, subtitle, children }) => jsxs("div", {
 	...props.root,
 	children: [
-		/* @__PURE__ */ jsx("div", { ...props.bar }),
-		/* @__PURE__ */ jsxs("div", {
+		jsx("div", { ...props.bar }),
+		jsxs("div", {
 			...props.content,
-			children: [/* @__PURE__ */ jsx("div", {
+			children: [jsx("div", {
 				...props.title,
 				children: title
-			}), subtitle && /* @__PURE__ */ jsx("div", {
+			}), subtitle && jsx("div", {
 				...props.subtitle,
 				children: subtitle
 			})]

package/dist/remotion/dist/components/quote-card.d.ts

@@ -2,7 +2,6 @@ import * as _$react from "react";
 import * as _$_uds_types0 from "@uds/types";
 
 //#region ../remotion/dist/components/quote-card.d.ts
-//#region src/components/quote-card.d.ts
 /**
  * @description Full-screen quote display with optional attribution
  */
@@ -16,6 +15,6 @@ declare const QuoteCard: _$react.FC<_$_uds_types0.CreateComponentProps<string, {
   quote: "div";
   divider: "div";
   attribution: "div";
-}>>; //#endregion
+}>>;
 //#endregion
 export { QuoteCard };

package/dist/remotion/dist/components/quote-card.js

@@ -5,18 +5,18 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 /**
 * @description Full-screen quote display with optional attribution
 */
-const QuoteCard = createComponent(({ props, quote, attribution, children }) => /* @__PURE__ */ jsxs("div", {
+const QuoteCard = createComponent(({ props, quote, attribution, children }) => jsxs("div", {
 	...props.root,
 	children: [
-		/* @__PURE__ */ jsx("div", {
+		jsx("div", {
 			...props.mark,
 			children: "“"
 		}),
-		/* @__PURE__ */ jsx("div", {
+		jsx("div", {
 			...props.quote,
 			children: quote
 		}),
-		attribution && /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("div", { ...props.divider }), /* @__PURE__ */ jsx("div", {
+		attribution && jsxs(Fragment, { children: [jsx("div", { ...props.divider }), jsx("div", {
 			...props.attribution,
 			children: attribution
 		})] }),

package/dist/remotion/dist/components/split-screen.d.ts

@@ -2,7 +2,6 @@ import * as _$react from "react";
 import * as _$_uds_types0 from "@uds/types";
 
 //#region ../remotion/dist/components/split-screen.d.ts
-//#region src/components/split-screen.d.ts
 /**
  * @description Side-by-side split screen layout for comparing content
  */
@@ -20,6 +19,6 @@ declare const SplitScreen: _$react.FC<_$_uds_types0.CreateComponentProps<string,
   leftBody: "div";
   rightTitle: "div";
   rightBody: "div";
-}>>; //#endregion
+}>>;
 //#endregion
 export { SplitScreen };

package/dist/remotion/dist/components/split-screen.js

@@ -5,25 +5,25 @@ import { jsx, jsxs } from "react/jsx-runtime";
 /**
 * @description Side-by-side split screen layout for comparing content
 */
-const SplitScreen = createComponent(({ props, leftTitle, leftBody, rightTitle, rightBody, children }) => /* @__PURE__ */ jsxs("div", {
+const SplitScreen = createComponent(({ props, leftTitle, leftBody, rightTitle, rightBody, children }) => jsxs("div", {
 	...props.root,
 	children: [
-		/* @__PURE__ */ jsxs("div", {
+		jsxs("div", {
 			...props.left,
-			children: [leftTitle && /* @__PURE__ */ jsx("div", {
+			children: [leftTitle && jsx("div", {
 				...props.leftTitle,
 				children: leftTitle
-			}), leftBody && /* @__PURE__ */ jsx("div", {
+			}), leftBody && jsx("div", {
 				...props.leftBody,
 				children: leftBody
 			})]
 		}),
-		/* @__PURE__ */ jsxs("div", {
+		jsxs("div", {
 			...props.right,
-			children: [rightTitle && /* @__PURE__ */ jsx("div", {
+			children: [rightTitle && jsx("div", {
 				...props.rightTitle,
 				children: rightTitle
-			}), rightBody && /* @__PURE__ */ jsx("div", {
+			}), rightBody && jsx("div", {
 				...props.rightBody,
 				children: rightBody
 			})]

package/dist/remotion/dist/components/stat-card.d.ts

@@ -2,7 +2,6 @@ import * as _$react from "react";
 import * as _$_uds_types0 from "@uds/types";
 
 //#region ../remotion/dist/components/stat-card.d.ts
-//#region src/components/stat-card.d.ts
 /**
  * @description Full-screen statistic display with large value and label
  */
@@ -14,6 +13,6 @@ declare const StatCard: _$react.FC<_$_uds_types0.CreateComponentProps<string, {
   root: "div";
   value: "div";
   label: "div";
-}>>; //#endregion
+}>>;
 //#endregion
 export { StatCard };

package/dist/remotion/dist/components/stat-card.js

@@ -5,14 +5,14 @@ import { jsx, jsxs } from "react/jsx-runtime";
 /**
 * @description Full-screen statistic display with large value and label
 */
-const StatCard = createComponent(({ props, value, label, children }) => /* @__PURE__ */ jsxs("div", {
+const StatCard = createComponent(({ props, value, label, children }) => jsxs("div", {
 	...props.root,
 	children: [
-		/* @__PURE__ */ jsx("div", {
+		jsx("div", {
 			...props.value,
 			children: value
 		}),
-		label && /* @__PURE__ */ jsx("div", {
+		label && jsx("div", {
 			...props.label,
 			children: label
 		}),

package/dist/remotion/dist/components/text-overlay.d.ts

@@ -2,7 +2,6 @@ import * as _$react from "react";
 import * as _$_uds_types0 from "@uds/types";
 
 //#region ../remotion/dist/components/text-overlay.d.ts
-//#region src/components/text-overlay.d.ts
 /**
  * @description Full-screen text overlay for displaying text over video or images
  */
@@ -12,6 +11,6 @@ declare const TextOverlay: _$react.FC<_$_uds_types0.CreateComponentProps<string,
 }, {
   root: "div";
   text: "div";
-}>>; //#endregion
+}>>;
 //#endregion
 export { TextOverlay };

package/dist/remotion/dist/components/text-overlay.js

@@ -5,9 +5,9 @@ import { jsx, jsxs } from "react/jsx-runtime";
 /**
 * @description Full-screen text overlay for displaying text over video or images
 */
-const TextOverlay = createComponent(({ props, text, children }) => /* @__PURE__ */ jsxs("div", {
+const TextOverlay = createComponent(({ props, text, children }) => jsxs("div", {
 	...props.root,
-	children: [/* @__PURE__ */ jsx("div", {
+	children: [jsx("div", {
 		...props.text,
 		children: text
 	}), children]

package/dist/remotion/dist/components/title-card.d.ts

@@ -2,7 +2,6 @@ import * as _$react from "react";
 import * as _$_uds_types0 from "@uds/types";
 
 //#region ../remotion/dist/components/title-card.d.ts
-//#region src/components/title-card.d.ts
 /**
  * @description Full-screen title card with optional subtitle for video scenes
  */
@@ -14,6 +13,6 @@ declare const TitleCard: _$react.FC<_$_uds_types0.CreateComponentProps<string, {
   root: "div";
   title: "div";
   subtitle: "div";
-}>>; //#endregion
+}>>;
 //#endregion
 export { TitleCard };

package/dist/remotion/dist/components/title-card.js

@@ -5,14 +5,14 @@ import { jsx, jsxs } from "react/jsx-runtime";
 /**
 * @description Full-screen title card with optional subtitle for video scenes
 */
-const TitleCard = createComponent(({ props, title, subtitle, children }) => /* @__PURE__ */ jsxs("div", {
+const TitleCard = createComponent(({ props, title, subtitle, children }) => jsxs("div", {
 	...props.root,
 	children: [
-		/* @__PURE__ */ jsx("div", {
+		jsx("div", {
 			...props.title,
 			children: title
 		}),
-		subtitle && /* @__PURE__ */ jsx("div", {
+		subtitle && jsx("div", {
 			...props.subtitle,
 			children: subtitle
 		}),

package/dist/remotion/dist/components/typing-text.d.ts

@@ -2,7 +2,6 @@ import * as _$react from "react";
 import * as _$_uds_types0 from "@uds/types";
 
 //#region ../remotion/dist/components/typing-text.d.ts
-//#region src/components/typing-text.d.ts
 /**
  * @description Typing text animation that reveals characters frame by frame
  */
@@ -16,6 +15,6 @@ declare const TypingText: _$react.FC<_$_uds_types0.CreateComponentProps<string,
   root: "div";
   text: "div";
   cursor: "div";
-}>>; //#endregion
+}>>;
 //#endregion
 export { TypingText };

package/dist/remotion/dist/components/typing-text.js

@@ -11,11 +11,11 @@ const TypingText = createComponent(({ props, text, speed = 1, delay = 0, frame,
 	const charsToShow = isAnimating ? Math.min(Math.floor(effectiveFrame * speed), text.length) : text.length;
 	const visibleText = text.slice(0, charsToShow);
 	const showCursor = isAnimating && charsToShow < text.length;
-	return /* @__PURE__ */ jsxs("div", {
+	return jsxs("div", {
 		...props.root,
-		children: [/* @__PURE__ */ jsxs("div", {
+		children: [jsxs("div", {
 			...props.text,
-			children: [visibleText, showCursor && /* @__PURE__ */ jsx("span", { ...props.cursor })]
+			children: [visibleText, showCursor && jsx("span", { ...props.cursor })]
 		}), children]
 	});
 });