@yahoo/uds-v5-wip 1.60.0 → 1.62.0

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

@@ -1,375 +0,0 @@
-import { ComponentConfigValue } from "./component-config.js";
-import { BoundComponent } from "./defineComponent.js";
-import { AnyStyleProp } from "./defineStyleProp.js";
-import { TokenType, VarsConfig } from "./types.js";
-import { ResolvedStyleProp } from "./resolveStyleProp.js";
-import { BaseModifierProp, ComponentsConfig, CompositeStylesConfig, ConfigurableProp, ModifierProp, MotionPreset } from "@uds/types";
-
-//#region ../config/dist/createConfig.d.ts
-//#region src/createConfig.d.ts
-type MotionPresetsDef = Record<string, MotionPreset>;
-type MotionAliasValue<TMotion> = TMotion extends Record<string, infer V> ? Extract<V, string> : never;
-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.
- */
-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;
-  value: 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: ConfigurableProp[];
-  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 */
-/** 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: ComponentsConfig<string>;
-  globalStyles: GlobalStylesDef;
-  preflight: boolean;
-  prefix: string;
-  buildOptions?: BuildOptions;
-  examples?: Record<string, ExampleDef>;
-  designPrinciples?: string[];
-  vars?: VarsConfig;
-  /**
-   * Token names contributed by any composed preset, keyed by namespace.
-   *
-   * Populated during `.compose()` — every token seen in the preset's `vars`
-   * or `atomic` is added to the set. A later local `.defineVars()` does NOT
-   * remove entries, so preset-overridden tokens remain marked as preset.
-   *
-   * Read by the rename path (MCP tool, canvas preview, CLI pull) to reject
-   * renames of preset tokens — they are read-only from the consumer's
-   * perspective.
-   */
-  presetTokenNames?: Record<string, string[]>;
-  /**
-   * 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[];
-  /**
-   * Components registered via `.registerComponents({...})`. Authored
-   * elsewhere via `defineComponent('Name', config)` and imported into
-   * the config. The canonical input for codegen + runtime in the new
-   * layers-shape architecture.
-   *
-   * Map keyed by component name (e.g. `Box`, `Alert`); each value is the
-   * `ComponentConfigValue` branded record carrying `layers`, `props`,
-   * `defaultProps`.
-   */
-  componentConfigs?: Record<string, ComponentConfigValue<any, any, any>>;
-}
-interface ComponentConfig<TComponents extends ComponentsConfig<string> = ComponentsConfig<string>, TMotion extends MotionPresetsDef | undefined = MotionPresetsDef | undefined> {
-  name?: string;
-  requiredTokens: string[];
-  components: TComponents;
-  motion?: TMotion;
-}
-type SingleComponentDef<TMotionAlias extends string = string> = ComponentsConfig<TMotionAlias>[string];
-type EmptyMotionPresetsDef = Record<never, never>;
-type SingleComponentDefinitionRecord<TName extends string, TComponent extends SingleComponentDef<string>> = { [K in TName]: TComponent };
-type DefineComponentInput<TTokens, TMotion, TComponent extends SingleComponentDef<MotionAliasValue<TMotion> | string> = SingleComponentDef<MotionAliasValue<TMotion> | string>> = TComponent | ((ctx: {
-  tokens: TTokens;
-  motion: TMotion;
-  components: Record<string, any>;
-}) => TComponent);
-type DefineComponentMotionInput<TTokens, TMotion extends MotionPresetsDef = MotionPresetsDef> = TMotion | ((tokens: TTokens) => TMotion);
-/** 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: ComponentsConfig;
-  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 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>>>(configs: TConfigs): 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>;
-  defineComponents(params: ComponentsConfig<MotionAliasValue<TMotion> | string> | ((ctx: {
-    tokens: TTokens;
-    motion: TMotion;
-    components: Record<string, any>;
-  }) => ComponentsConfig<MotionAliasValue<TMotion> | string>)): ConfigResult<TModifier, TTokens, TMotion, 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>;
-  defineExample(name: string, examples: ExampleDef): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
-  compose(...presets: (ComponentConfig | UdsConfig | Partial<UdsConfigData>)[]): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
-  defineComponent<const TName extends string, const TComponent extends SingleComponentDef<MotionAliasValue<TMotion> | string>, const TPresetMotion extends MotionPresetsDef = EmptyMotionPresetsDef>(name: TName, component: DefineComponentInput<TTokens, TMotion, TComponent>, motion?: DefineComponentMotionInput<TTokens, TPresetMotion>): ComponentConfig<SingleComponentDefinitionRecord<TName, TComponent>, TPresetMotion>;
-  from(data: Partial<UdsConfigData>): 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;
-/**
- * Resolve configuration with all token references replaced by their raw values.
- * Useful for tools that need the actual values (e.g. anatomy generation).
- */
-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;
-interface InterpolateMarker {
-  __type: 'interpolate';
-  output: number[];
-  extrapolate: 'clamp' | 'extend' | 'identity';
-}
-declare function darker(color: string, amount: number): string;
-declare function lighter(color: string, amount: number): string;
-//#endregion
-export { AtomicToken, BuildOptions, CheckForReservedModifiersInput, ComponentConfig, DefineComponentInput, DefineComponentMotionInput, ExampleDef, ExampleEntryDef, ExampleLayoutStyles, GetModifierFromInput, GlobalStylesDef, InterpolateMarker, ModeGroup, ModeOption, ModeOptionInput, ModeSetInput, ModesInput, ModifierDef, MotionPresetsDef, SingleComponentDef, UdsConfig, UdsConfigData, buildTokenReference, createConfigBuilder, darker, lighter, resolveConfig };