@yahoo/uds-v5-wip 1.60.0 → 1.62.0

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

@@ -1,349 +0,0 @@
-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
-//#region src/component-config.d.ts
-/**
- * HTML tag literal. The TypeScript type is `string` (any tag name);
- * runtime renders it via `React.createElement(tag, ...)`.
- *
- * Kept as `string` instead of `keyof JSX.IntrinsicElements` so the type
- * doesn't pull a 200-key union into every layer position. Editors still
- * autocomplete tag names from JSX.
- */
-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.
- */
-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
- * narrowed against `RegisteredComponents`. `defaultProps` is narrowed
- * per-component so authors can only pass props the referenced component
- * actually accepts.
- *
- * Codegen emits `RegisteredComponents[K]` as the component's resolved
- * prop shape (e.g. `{ backgroundColor: RegisteredStyleProps['bg']; … }`).
- * `Partial<RegisteredComponents[K]>` lets `defaultProps` narrow against
- * that shape. Without registered components, the union is `never` (so
- * package-internal authoring sites don't have to deal with this shape).
- */
-type ComposedLayer = { [K in keyof RegisteredComponents & string]: {
-  component: `{${K}}`;
-  defaultProps?: Partial<RegisteredComponents[K]>;
-} }[keyof RegisteredComponents & string];
-/**
- * Allowed forms for a single layer's value. Authors usually pick the
- * shorthand (a bare tag string or a brace-ref); the object forms exist
- * for the cases that need `attrs` or `defaultProps`.
- */
-type LayerInput = HtmlTag | ComponentRef | PrimitiveLayer | ComposedLayer;
-/**
- * Bind a registered style prop to a specific layer. The style prop's
- * resolved class name is added to that layer's `className` bundle at
- * render time.
- *
- * `styleProp` is narrowed against `RegisteredStyleProps`. `layer` is a
- * string at this level — the consuming type (`ComponentConfig.props`)
- * narrows it against the component's own `layers` keys.
- */
-interface StylePropBinding {
-  layer: string;
-  styleProp: StylePropRef;
-}
-/**
- * Extract the root tag literal from a `layers` map when it can be read
- * statically. Returns the string literal `'a' | 'div' | …` when:
- *
- *  - `layers.root` is a bare tag string (`'a'`), or
- *  - `layers.root` is `{ tag: 'a', attrs?: … }`.
- *
- * Returns `undefined` when `layers.root` is a brace-ref (`'{Box}'`), a
- * `{ component: '{Box}' }` form, or not present. `Props<TConfig>` reads
- * this and substitutes `React.ComponentPropsWithoutRef<TTag>` for the
- * generic `HTMLAttributes<HTMLElement>` when narrowable.
- */
-type RootTag<TLayers> = TLayers extends {
-  root: infer R;
-} ? R extends HtmlTag ? R extends `{${string}}` ? undefined : R : R extends {
-  tag: infer T extends HtmlTag;
-} ? T : undefined : undefined;
-/**
- * Bind a registered composite to a single layer. Multi-layer composites
- * use the `CompositeBinding` shape instead (see below).
- */
-interface SingleLayerCompositeBinding {
-  layer: string;
-  composite: CompositeRef;
-}
-/**
- * Multi-layer composite binding — explicit composite-layer → component-
- * layer mapping. The composite declares its own internal layer names
- * (`default`, `label`, …) and this binding tells the framework which
- * component layer each one maps to.
- */
-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:
- *
- *  - `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
- * data-attribute (`data-loading="true"`) the consumer can target.
- */
-interface BoolMarker {
-  readonly __kind: 'bool';
-}
-/**
- * Enum prop — the value picks one entry from a map. Each entry can
- * declare per-layer style overrides. Mirrors today's `variants.X`
- * surface but co-located with other prop bindings.
- */
-interface EnumMarker<TValues extends Record<string, unknown>> {
-  readonly __kind: 'enum';
-  readonly values: TValues;
-}
-/**
- * Shorthand binding form — a brace-ref string standing in for the
- * verbose object. `'{bg}'` means "bind the registered style prop `bg`
- * to the *root* layer".
- *
- * Only legal in the primitive form `defineComponent('div', { props: { bg: '{bg}' } })`,
- * where the root layer is unambiguous. In the verbose form
- * `defineComponent({ layers: {...}, props: {...} })` authors must use
- * the explicit long-form `{ layer, styleProp: '{bg}' }` binding so
- * the target layer is named at the call site.
- */
-type StylePropShorthand = StylePropRef;
-/**
- * All allowed shapes for a single entry in the verbose form's `props`
- * block. Verbose form (with explicit `layers`) requires the long-form
- * `{ 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<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<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<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
- * (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
- * downstream type-only imports (`import type { AlertConfig } from
- * './alert.config'`) thread the full shape through to
- * `Props<typeof config>` — per-prop literal binding values (e.g.
- * `'{bg}'`) survive for `Props<TConfig>` to resolve against
- * `RegisteredStyleProps`, and the root tag survives for HTML-attribute
- * narrowing via `React.ComponentPropsWithoutRef<TTag>`.
- *
- * `__tag` is a *phantom* type slot — there is no runtime field. It's
- * derived from either the primitive-form first arg (`defineComponent('a',
- * …)`) or from `layers.root` via `RootTag<TLayers>` for the verbose form.
- * When the root isn't a literal tag (brace-ref / composed layer), it's
- * `undefined` and `Props<TConfig>` falls back to `HTMLAttributes<HTMLElement>`.
- *
- * `__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-
- * 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,98 +0,0 @@
-//#region ../config/dist/component-refs.d.ts
-//#region src/component-refs.d.ts
-/**
- * Augmentable registries + template-literal ref types for the
- * component-API surface.
- *
- * Codegen runs `uds build` and populates the four interfaces below in
- * each consumer app's `.uds/uds-env.d.ts`. The template-literal types
- * derived from them narrow brace-ref strings against what's actually
- * registered — `'{Box}'` typechecks only if `Box` is a real
- * `RegisteredComponents` key, `'{bg}'` only if `bg` is a real
- * `RegisteredStyleProps` key, etc.
- *
- * Without the augmentation loaded (e.g. inside `@uds/config`'s own
- * test files), each registry is `{}` and the corresponding ref type
- * collapses to `never`. Helpers downstream are expected to fail open
- * in that case so package-internal authoring sites don't all error.
- */
-/**
- * Registered components. Each key is the component name (the brace-ref
- * identifier — `'{Box}'`); each value is the component's resolved prop
- * shape, e.g.
- *
- *     export interface RegisteredComponents {
- *       Box2: {
- *         backgroundColor: RegisteredStyleProps['bg'];
- *         color: RegisteredStyleProps['color'];
- *       };
- *       Spinner: {};
- *     }
- *
- * Composed layers use `Partial<RegisteredComponents[K]>` on
- * `defaultProps` for type-safe completion when nesting components
- * inside other components' configs.
- *
- * Populated by codegen from `uds.config.ts`'s `.registerComponents({...})`
- * call.
- */
-interface RegisteredComponents {}
-/**
- * Registered style props. Key is the JSX prop name (the brace-ref
- * identifier — `'{bg}'`); value is the string-literal union of
- * allowed token names for that prop, e.g.
- *
- *     export interface RegisteredStyleProps {
- *       bg: 'brand' | 'accent' | 'primary';
- *       color: 'brand' | 'on-brand';
- *     }
- *
- * Components reference these directly when wiring JSX-prop types:
- * `bg?: RegisteredStyleProps['bg']`. Downstream `Props<TConfig>`
- * resolves the shorthand `'{bg}'` against this map.
- *
- * Populated by codegen from `uds.config.ts`'s `.registerStyleProps({...})`
- * call. A `never` value means the prop registered no tokens
- * (arbitrary-only); the consumer should widen those to `string`.
- */
-interface RegisteredStyleProps {}
-/**
- * Registered composite-style names. Each key is the composite identifier
- * (the brace-ref — `'{elevation}'`, `'{severity}'`); value is `void`.
- *
- * Populated by codegen from `uds.config.ts`'s `.registerComposites({...})`
- * 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
- * `@uds/config`'s own tests, where codegen hasn't populated the
- * interface). Consumer apps load the codegen-emitted augmentation and
- * get narrow `'{Box}' | '{Text}' | …` autocomplete.
- */
-type ComponentRef = [keyof RegisteredComponents] extends [never] ? `{${string}}` : `{${Extract<keyof RegisteredComponents, string>}}`;
-/**
- * Brace-wrapped reference to a registered style prop. Falls open when
- * unaugmented (see {@link ComponentRef}).
- */
-type StylePropRef = [keyof RegisteredStyleProps] extends [never] ? `{${string}}` : `{${Extract<keyof RegisteredStyleProps, string>}}`;
-/**
- * Brace-wrapped reference to a registered composite style. Falls open
- * 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.js

@@ -1,78 +0,0 @@
-import { propMappings } from "../../core/dist/style-prop-data.js";
-import "../../core/dist/index.js";
-//#region ../config/dist/component-resolution.js
-/**
-* Build a motion reference object for use in defineComponents callback.
-* Each key maps to the preset name string, so component configs can
-* reference presets by name: `motion: motion.fadeIn` → `motion: "fadeIn"`
-*/
-function buildMotionReference(motion) {
-	const result = {};
-	for (const name of Object.keys(motion)) result[name] = name;
-	return result;
-}
-function resolveMotionAlias(value, motion) {
-	const alias = value.trim();
-	if (!alias) return null;
-	return motion[alias] ?? null;
-}
-function isSlotMotionConfigObject(value) {
-	return typeof value === "object" && value !== null;
-}
-function resolveComponentMotionAliases(components, motionPresets) {
-	const resolved = {};
-	for (const [componentName, componentConfig] of Object.entries(components)) {
-		const resolvedMotion = {};
-		let strippedBase = componentConfig.base;
-		if (componentConfig.base) {
-			const newBase = {};
-			for (const [slotName, slotStyles] of Object.entries(componentConfig.base)) if (slotStyles && typeof slotStyles === "object" && "motion" in slotStyles) {
-				const { motion: slotMotion, ...rest } = slotStyles;
-				newBase[slotName] = rest;
-				if (isSlotMotionConfigObject(slotMotion)) resolvedMotion[slotName] = slotMotion;
-			} else newBase[slotName] = slotStyles;
-			strippedBase = newBase;
-		}
-		if (componentConfig.motion) for (const [slot, motionValue] of Object.entries(componentConfig.motion)) {
-			if (resolvedMotion[slot]) continue;
-			if (typeof motionValue === "string") {
-				const preset = resolveMotionAlias(motionValue, motionPresets);
-				if (!preset) throw new Error(`Component "${componentName}" slot "${slot}" references unknown motion preset "${motionValue}".`);
-				if (preset.runtime !== "js") throw new Error(`Component "${componentName}" slot "${slot}" references "${motionValue}" which is CSS runtime. Component slot motion must reference JS presets.`);
-				resolvedMotion[slot] = {
-					initial: preset.initial,
-					animate: preset.animate,
-					exit: preset.exit,
-					transition: preset.transition,
-					whileHover: preset.whileHover,
-					whileTap: preset.whileTap
-				};
-			} else if (isSlotMotionConfigObject(motionValue)) resolvedMotion[slot] = motionValue;
-		}
-		if (Object.keys(resolvedMotion).length > 0) resolved[componentName] = {
-			...componentConfig,
-			...strippedBase !== void 0 && { base: strippedBase },
-			motion: resolvedMotion
-		};
-		else resolved[componentName] = {
-			...componentConfig,
-			...strippedBase !== void 0 && { base: strippedBase }
-		};
-	}
-	return resolved;
-}
-/** Set of all style prop names — variant axis names must not collide with these */
-const stylePropNames = new Set(Object.keys(propMappings));
-/**
-* Validate that component variant axis names don't collide with style prop names.
-* When a collision exists, processStyleProps consumes the prop before variant
-* classification can use it, silently breaking the variant.
-*/
-function validateComponentVariants(components) {
-	for (const [componentName, componentConfig] of Object.entries(components)) {
-		if (!componentConfig.variants) continue;
-		for (const axisName of Object.keys(componentConfig.variants)) if (stylePropNames.has(axisName)) throw new Error(`Component "${componentName}" has a variant axis named "${axisName}" which collides with the style prop "${axisName}". Style props are consumed before variant classification, so this variant will never be applied. Rename the variant axis to avoid the collision.`);
-	}
-}
-//#endregion
-export { buildMotionReference, resolveComponentMotionAliases, validateComponentVariants };