@yahoo/uds-v5-wip 1.61.0 → 1.62.1

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

@@ -1,456 +0,0 @@
-import { InterpolateMarker, MotionPreset } from "./defineMotionConfig.js";
-import { ComponentConfigValue } from "./component-config.js";
-import { DefinedPreview } from "./definePreview.js";
-import { CompositeStylesConfig, DefinedCompositeStyle } from "./defineCompositeStyle.js";
-import { BoundComponent } from "./defineComponent.js";
-import { AnyStyleProp } from "./defineStyleProp.js";
-import { TokenType, VarsConfig } from "./types.js";
-import { ResolvedStyleProp } from "./resolveStyleProp.js";
-import * as _$react from "react";
-import { BaseModifierProp, ModifierProp } from "@uds/types";
-
-//#region ../config/dist/createConfig.d.ts
-//#region src/createConfig.d.ts
-type MotionPresetsDef = Record<string, MotionPreset>;
-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
- * 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;
-} ? { [V in keyof S]: {
-  className: string;
-} } : never };
-type ModifierNameShape = `_${string}`;
-/**
- * Check if a modifier overlaps with base reserved modifiers (not including custom ones)
- * BaseModifierProp excludes CustomModifierNames to prevent circular dependency
- */
-type IsReservedModifier<T> = T extends BaseModifierProp ? true : false;
-/** Check if any modifier in the union is reserved */
-type HasReservedModifier<T> = T extends any ? IsReservedModifier<T> extends true ? true : never : never;
-interface ModeOption {
-  name: string;
-  /** Optional human-readable label for Studio. Falls back to `name`. */
-  label?: string;
-  modifier: ModifierNameShape;
-  /** Description for AI prompt generation (e.g. "Apply styles in dark mode") */
-  description?: string;
-  css?: string;
-  media?: string;
-  default?: true;
-}
-interface ModeGroup {
-  name: string;
-  /** Optional human-readable label for Studio. Falls back to `name`. */
-  label?: string;
-  options: ModeOption[];
-}
-/** Single option within a mode set, as authored. */
-interface ModeOptionInput {
-  /** Optional human-readable label for Studio. Falls back to the option key. */
-  label?: string;
-  /**
-   * Optional explicit modifier string. When omitted, derived as `_${optionKey}`.
-   * Use this when the option key and modifier must differ (e.g. `xxl` → `_2xl`).
-   */
-  modifier?: ModifierNameShape;
-  /** CSS selector applied when this option is active (e.g. `.dark`). */
-  css?: string;
-  /** Media query applied when this option is active. */
-  media?: string;
-}
-/** Single mode set, as authored. */
-interface ModeSetInput {
-  /** Optional human-readable label for Studio. Falls back to the set key. */
-  label?: string;
-  options: Record<string, ModeOptionInput>;
-}
-/** Object-keyed input shape accepted by `defineModes`. */
-type ModesInput = Record<string, ModeSetInput>;
-/**
- * Extract the union of modifier strings produced by an authored `ModesInput`.
- * Uses an explicit `modifier` when present; otherwise derives `_${optionKey}`.
- * Drives both the reserved-modifier guard and the modifier types that flow
- * through subsequent builder calls.
- */
-type GetModifierFromInput<I extends ModesInput> = { [SetKey in keyof I]: { [OptKey in keyof I[SetKey]['options']]: I[SetKey]['options'][OptKey] extends {
-  modifier: infer M;
-} ? 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.
- */
-declare function convertModesInputToGroups(input: ModesInput): ModeGroup[];
-interface ModifierDef {
-  modifier: ModifierNameShape;
-  selector: string;
-  /** Description for AI prompt generation (e.g. "Apply styles on elevation-1 surfaces") */
-  description?: string;
-}
-type AtomicTokenValue<M extends ModifierNameShape> = {
-  name: string;
-  /**
-   * The token's authored value. Either a CSS literal (`'#1167f4'`,
-   * `'1rem'`) or a `TokenMarker` from `token('ns/name')` pointing at
-   * another registered token. Downstream emitters resolve markers to
-   * `var(--<prefix>-<ns>-<name>)` aliases at CSS-generation time.
-   */
-  value: string | {
-    readonly __kind: 'token';
-    readonly ref: string;
-  };
-  /**
-   * Resolved DTCG-aligned token type. Populated per-token only when the
-   * token overrides the group-level `type` (e.g. a `'string'`-typed
-   * `transparent` sitting inside a `'color'` namespace).
-   */
-  type?: TokenType;
-  modifiers?: Partial<Record<M, string>>;
-};
-interface AtomicToken<M extends ModifierNameShape = ModifierNameShape> {
-  properties: string[];
-  tokens: AtomicTokenValue<M>[];
-  /**
-   * Resolved DTCG-aligned token type for the whole group. Set from
-   * `$type` on `defineVars`, or inferred from `defineScopes` / value sniff
-   * during config resolution.
-   */
-  type?: TokenType;
-  /**
-   * Free-form group description surfaced in Studio. Mirrors `$description`
-   * on the source `defineVars` namespace; not used by the runtime / CSS
-   * generator.
-   */
-  description?: string;
-  /**
-   * Original `defineVars` namespace key, verbatim — e.g. `borderColor`,
-   * `spectrum`, `fontSize`. Distinct from {@link cssPrefix}, which is
-   * the kebab-cased form used in CSS-variable names. The Studio uses
-   * this to label tokens with the same identifier the author wrote in
-   * their config (`borderColor/accent`, not `border-color/accent`).
-   *
-   * Optional for backwards compatibility — older serialized configs
-   * predate the field; consumers should fall back to {@link cssPrefix}
-   * (kebab-cased) when this is absent.
-   */
-  namespace?: string;
-  /**
-   * Optional CSS variable prefix override
-   *
-   * By default, the prefix is determined by the property type:
-   * - color/bg/borderColor → '--color-*'
-   * - spacing → '--spacing-*'
-   * - fontFamily → '--font-*'
-   *
-   * Use this to customize the namespace for specific tokens.
-   *
-   * @example
-   * ```ts
-   * {
-   *   properties: ['color'],
-   *   cssPrefix: 'text', // Creates '--text-*' instead of '--color-*'
-   *   tokens: [{ name: 'brand', value: '#3b82f6' }]
-   * }
-   * ```
-   */
-  cssPrefix?: string;
-}
-/** Empty tokens type for initial state */
-type EmptyTokens = {};
-/** Empty vars type for initial state */
-type EmptyVars = {};
-/**
- * Derive the runtime `tokens` accessor type from a `defineVars` map. Each
- * namespace becomes `tokens[ns][tokenName] = string`. `$type` /
- * `$description` keys are excluded — they're authoring metadata, not tokens.
- */
-type VarsToTokens<TVars extends VarsConfig> = { [K in keyof TVars]: { [T in Exclude<keyof TVars[K], '$type' | '$description'>]: string } };
-/** Shallow merge of two token-shape records (later wins on collisions). */
-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 */
-declare function buildCompositeStylesReference(compositeStyles: CompositeStylesConfig): Record<string, Record<string, {
-  className: string;
-}>>;
-/** Global styles definition — CSS selector → style props */
-type GlobalStylesDef = Record<string, Record<string, any>>;
-/** CSS properties for the example wrapper element */
-type ExampleLayoutStyles = Record<string, string>;
-/** Single example entry — either iterates a variant axis or shows a static example */
-interface ExampleEntryDef<TAxis extends string = string> {
-  each?: TAxis;
-  layout?: ExampleLayoutStyles;
-  props?: Record<string, Record<string, unknown>>;
-}
-/** Map of example keys (e.g. 'default', 'anatomy') to their definitions */
-type ExampleDef<TAxis extends string = string> = Record<string, ExampleEntryDef<TAxis>>;
-/** Build options that can be set in uds.config.ts via .buildOptions() */
-interface BuildOptions {
-  skipCssVariables?: boolean;
-  preflight?: boolean;
-  /**
-   * Scope every emitted CSS selector under this class name. The emitter's
-   * `:root` block becomes `.<cssScope>`; mode/theme blocks (e.g. `.dark` or
-   * `[data-theme="slate"]`) keep their ancestor selector and append `.<cssScope>`
-   * so they still apply when the attribute is on `<html>`. Utility classes
-   * are nested under `.<cssScope>` so two UDS-powered packages on the same
-   * page do not collide.
-   *
-   * Wrap the embedded UI in `<div className="<cssScope>">` to activate.
-   */
-  cssScope?: string;
-}
-/** Internal data shape — accessible via resolveConfig() */
-interface UdsConfigData {
-  modes: ModeGroup[];
-  modifiers: ModifierDef[];
-  atomic: AtomicToken<ModifierNameShape>[];
-  compositeStyles: CompositeStylesConfig;
-  motion: MotionPresetsDef;
-  /**
-   * Components registered via `.registerComponents({...})`. Authored
-   * elsewhere via `defineComponent('Name', config)` and imported into
-   * the config. The canonical input for codegen + runtime.
-   *
-   * Map keyed by component name (e.g. `Box`, `Alert`); each value is the
-   * `ComponentConfigValue` branded record carrying `layers`, `props`,
-   * `defaultProps`, `base`, `compoundProps`.
-   */
-  components: Record<string, ComponentConfigValue<any, any, any>>;
-  globalStyles: GlobalStylesDef;
-  preflight: boolean;
-  prefix: string;
-  buildOptions?: BuildOptions;
-  examples?: Record<string, ExampleDef>;
-  designPrinciples?: string[];
-  vars?: VarsConfig;
-  /**
-   * Style props registered via `.registerStyleProps([...])`. Authored
-   * elsewhere via `defineStyleProp(...)` and imported into the config.
-   * The canonical input for codegen + runtime in the new architecture.
-   *
-   * Map keyed by JSX prop name (e.g. `bg`, `padding`); each value is the
-   * style-prop record carrying `cssProperty`, `classPrefix`, `values`, etc.
-   */
-  styleProps?: Record<string, AnyStyleProp>;
-  /**
-   * Resolved style props — every registered style prop run through
-   * `resolveStyleProp(propName, prop, config)` at `resolveConfig` time.
-   * Each entry carries the prop's filtered token list, literal keywords,
-   * arbitrary spec, and metadata. Codegen + runtime consume this instead
-   * of walking the raw style-prop records.
-   */
-  resolvedStyleProps?: ResolvedStyleProp[];
-  /**
-   * Bound React component references for any registered entry that
-   * came in as a bound component (primitive shorthand result or
-   * `.render(fn)` output). Populated alongside `components` by
-   * `.registerComponents({...})` and read by `resolveConfig` to seed
-   * the module-level runtime registry so `defineComponent('{Box}', {})`
-   * shorthand authoring can look the component up at render time
-   * without a `.render(fn)` boilerplate.
-   *
-   * Raw-config entries (verbose-form `defineComponent({...})` values
-   * passed in without `.render()`) don't appear here — they have no FC
-   * to register.
-   */
-  componentInstances?: Record<string, _$react.ComponentType<any>>;
-  /**
-   * Previews registered via `.registerPreviews({ Name: definePreview(jsx) })`.
-   * Map keyed by component name (matching `components`); each value
-   * is a `DefinedPreview` carrying the authored JSX element and any
-   * metadata attached via the `.metadata({...})` chain.
-   *
-   * Codegen reads this map's call-site source (via ts-morph) and walks
-   * each JSX expression through `jsxToSpec` to populate
-   * `manifest.preview[name]`. The runtime value itself is mostly inert
-   * — Studio's catalog and docs's `[slug]` page consume the manifest,
-   * not this slot.
-   */
-  previews?: Record<string, DefinedPreview>;
-}
-type PresetMergeMode = 'preserve' | 'merge' | 'override';
-interface ComponentConfigMergeStrategy {
-  tokens?: PresetMergeMode;
-  modes?: PresetMergeMode;
-  modifiers?: PresetMergeMode;
-  motion?: PresetMergeMode;
-  components?: PresetMergeMode;
-  globalStyles?: PresetMergeMode;
-  examples?: PresetMergeMode;
-}
-/** Helper type: builder result includes both the UdsConfig interface and any extensions */
-type ConfigResult<TModifier extends ModifierNameShape, TTokens, TMotion, TExt extends Record<string, any> = {}, TCompositeStyles = EmptyCompositeStyles, TModeModifiers extends ModifierNameShape = never, TVars extends VarsConfig = EmptyVars> = UdsConfig<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars> & TExt;
-interface UdsConfig<TModifier extends ModifierNameShape = ModifierProp, TTokens = EmptyTokens, TMotion = EmptyMotion, TExt extends Record<string, any> = {}, TCompositeStyles = EmptyCompositeStyles, TModeModifiers extends ModifierNameShape = never, TVars extends VarsConfig = EmptyVars> {
-  modes: ModeGroup[];
-  atomic: AtomicToken<ModifierNameShape>[];
-  components: Record<string, ComponentConfigValue<any, any, any>>;
-  preflight(enabled?: boolean): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
-  prefix(value: string): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
-  buildOptions(options: BuildOptions): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
-  defineModes<const NewModes extends ModesInput>(params: CheckForReservedModifiersInput<NewModes>): ConfigResult<TModifier | GetModifierFromInput<NewModes>, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers | GetModifierFromInput<NewModes>, TVars>;
-  defineModifiers<const Defs extends readonly ModifierDef[]>(params: Defs | ((ctx: {
-    tokens: TTokens;
-    compositeStyles: CompositeStylesReference<TCompositeStyles>;
-  }) => Defs)): ConfigResult<TModifier | Defs[number]['modifier'], TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers | Defs[number]['modifier'], TVars>;
-  defineCompositeStyles<const M extends CompositeStylesConfig>(params: M | ((ctx: {
-    tokens: TTokens;
-  }) => M)): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles & M, TModeModifiers, TVars>;
-  /**
-   * Register composite styles authored via `defineCompositeStyle({...})`.
-   * Mirrors `.registerStyleProps({...})` and `.registerComponents({...})`:
-   * one factory call per composite, then a single registration step on
-   * the builder. Calls accumulate — later registrations merge into the
-   * same `compositeStyles` map that `.defineCompositeStyles({...})`
-   * populates.
-   *
-   * Composites authored this way don't see the `tokens` context the
-   * inline `defineCompositeStyles((ctx) => ...)` callback receives —
-   * authors reference tokens by name (`'brand'`, `'sm'`) or brace-ref
-   * (`'{spacing/4}'`). The resolver expands these the same way it does
-   * for any other style-prop value.
-   *
-   * @example
-   * ```ts
-   * // packages/.../text-variant.ts
-   * export const textVariant = defineCompositeStyle({
-   *   label: 'Text Variant',
-   *   styles: { body: { fontSize: '[1rem]', fontWeight: 'normal' } },
-   * });
-   *
-   * // apps/<consumer>/uds.config.ts
-   * udsBuilder.registerComposites({ textVariant });
-   * ```
-   */
-  registerComposites<const M extends Record<string, DefinedCompositeStyle>>(composites: M): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles & { [K in keyof M]: {
-    label: string;
-    styles: M[K]['styles'];
-  } }, TModeModifiers, TVars>;
-  /**
-   * Register style props, keyed by the JSX prop name consumers will use.
-   * Calls accumulate — later `.registerStyleProps({...})` calls merge into
-   * the existing map (later keys overwrite earlier ones with the same name).
-   *
-   * @example
-   * ```ts
-   * uds.registerStyleProps({
-   *   bg: {
-   *     cssProperty: 'background-color',
-   *     classPrefix: 'bg',
-   *     values: ['{global}', '{spectrum}', '{bg}'],
-   *     label: 'Background',
-   *   },
-   *   padding: {
-   *     cssProperty: 'padding',
-   *     classPrefix: 'p',
-   *     arbitrary: 'length-percentage',
-   *     values: ['{spacing}'],
-   *     label: 'Padding',
-   *   },
-   * });
-   * ```
-   */
-  registerStyleProps<const Props extends Record<string, AnyStyleProp>>(props: Props): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
-  /**
-   * Register components authored with `defineComponent(...)`. Calls
-   * accumulate — later `.registerComponents({...})` calls merge into
-   * the existing map (later keys overwrite earlier ones with the same
-   * name).
-   *
-   * Accepts either form returned by `defineComponent`:
-   *  - The pure-data config value from the bare verbose form
-   *    (`defineComponent({ layers, props })`).
-   *  - A bound component from the primitive form
-   *    (`defineComponent('div', { props })`) or the chained
-   *    `.render(fn)` builder — the framework extracts the underlying
-   *    config from the non-enumerable `__config` slot.
-   *
-   * @example
-   * ```ts
-   * import { Box } from './src/uds/components/box';      // primitive
-   * import { alertConfig } from './src/uds/components/alert.config'; // verbose pure-data
-   *
-   * uds.registerComponents({ Box, Alert: alertConfig });
-   * ```
-   */
-  registerComponents<const TConfigs extends Record<string, ComponentConfigValue<any, any, any> | BoundComponent<ComponentConfigValue<any, any, any>, any> | (_$react.FC<any> & {
-    readonly __config: ComponentConfigValue<any, any, any>;
-  })>>(configs: TConfigs): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
-  /**
-   * Register catalog / docs preview tiles. Each key must match a name
-   * registered via `.registerComponents({...})`; each value must be a
-   * `definePreview(jsx)` result.
-   *
-   * Calls accumulate. Later registrations merge into the existing map
-   * (later keys overwrite earlier ones with the same name). Codegen
-   * reads the call-site source via ts-morph and walks each JSX
-   * expression through `jsxToSpec` to populate `manifest.preview[name]`.
-   *
-   * @example
-   * ```ts
-   * import { Box, VStack } from './src/uds/components';
-   *
-   * const BoxPreview = definePreview(
-   *   <Box bg="tertiary" spacing="6">Box</Box>,
-   * );
-   *
-   * const VStackPreview = definePreview(
-   *   <VStack gap="3">
-   *     <Box>1</Box>
-   *     <Box>2</Box>
-   *   </VStack>,
-   * ).metadata({ description: 'Vertical stack' });
-   *
-   * uds.registerComponents({ Box, VStack }).registerPreviews({
-   *   Box: BoxPreview,
-   *   VStack: VStackPreview,
-   * });
-   * ```
-   */
-  registerPreviews<const TPreviews extends Record<string, DefinedPreview>>(previews: TPreviews): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
-  defineMotion<const M extends MotionPresetsDef>(presets: M | ((tokens: TTokens) => M)): ConfigResult<TModifier, TTokens, { [K in keyof M]: string }, TExt, TCompositeStyles, TModeModifiers, TVars>;
-  defineGlobalStyles(params: GlobalStylesDef | ((tokens: TTokens) => GlobalStylesDef)): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
-  defineDesignPrinciples(principles: string[]): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
-  extend<const NewExt extends Record<string, any>>(ext: NewExt): ConfigResult<TModifier, TTokens, TMotion, TExt & NewExt, TCompositeStyles, TModeModifiers, TVars>;
-  defineVars<const TVarsNew extends VarsConfig<[TModeModifiers] extends [never] ? `_${string}` : TModeModifiers>>(vars: TVarsNew): ConfigResult<TModifier, MergeTokens<TTokens, VarsToTokens<TVars & TVarsNew>>, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars & TVarsNew>;
-}
-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;
-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;
-declare function interpolate(config: {
-  output: number[];
-  extrapolate?: 'clamp' | 'extend' | 'identity';
-}): InterpolateMarker;
-/**
- * Convert a px value to rem (assuming 16px base).
- *
- * @example rem(14) // '0.875rem'
- */
-declare function rem(px: number): string;
-declare function darker(color: string, amount: number): string;
-declare function lighter(color: string, amount: number): string;
-declare const uds: UdsConfig<ModifierProp, EmptyTokens, EmptyMotion, {}, EmptyCompositeStyles, never, EmptyVars>; //#endregion
-//#endregion
-export { AtomicToken, BuildOptions, CheckForReservedModifiersInput, ComponentConfigMergeStrategy, ExampleDef, ExampleEntryDef, ExampleLayoutStyles, GetModifierFromInput, GlobalStylesDef, ModeGroup, ModeOption, ModeOptionInput, ModeSetInput, ModesInput, ModifierDef, MotionPresetsDef, PresetMergeMode, UdsConfig, UdsConfigData, buildCompositeStylesReference, buildTokenReference, convertModesInputToGroups, createConfigBuilder, darker, interpolate, lighter, rem, resolveConfig, uds };