
import { CSSProperties, ElementType, HTMLAttributes, PropsWithChildren, ReactElement, ReactNode, Ref } from "react";
import { IntRange } from "type-fest";

//#region ../types/dist/index.d.ts
//#region src/index.d.ts
/**
 * Icon pixel sizes
 */
type IconPixelSize = 12 | 16 | 24 | 32;
/**
 * Icon size tokens
 */
type IconSize = 'xs' | 'sm' | 'md' | 'lg';
/**
 * Icon variant (fill, outline, multicolor)
 */
type IconVariant = 'fill' | 'outline' | 'multicolor';
/**
 * Generic icon component type. Platforms should provide their own concrete type.
 * - Web: SvgIcon from @yahoo/uds-icons
 * - Mobile: Component from @yahoo/uds-icons/svgMap
 */
type GenericIconComponent = React.ComponentType<any>;
/** Ensure an array has a max length of N */
type MaxLengthArray<T, N extends number, A extends T[] = []> = A['length'] extends N ? A : T[] extends A ? T[] : A | MaxLengthArray<T, N, [...A, T]>;
type ExtractUrlFromFontFaceRule<T extends string> = T extends `url('${infer U}') format('woff2')` ? U : never;
type Percentage = IntRange<0, 101>;
type PixelsUnit = {
  value: number;
  type: 'px';
};
type RemsUnit = {
  value: number;
  type: 'rem';
};
type UnitlessUnit = {
  value: number;
  type: 'unitless';
};
type PercentageUnit = {
  value: Percentage;
  type: 'percentage';
};
type Hue = 'gray' | 'purple' | 'indigo' | 'blue' | 'cyan' | 'teal' | 'mint' | 'green' | 'lime' | 'citron' | 'yellow' | 'brown' | 'nude' | 'orange' | 'sunset' | 'red' | 'rose' | 'pink' | 'magenta' | 'carbon';
type HueStep = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | '11' | '12' | '13' | '14' | '15';
type SpectrumColor = `${Hue}-${HueStep}`;
type SharedPrimaryPaletteAlias = 'brand' | 'alert' | 'positive' | 'warning' | 'info';
type SharedSecondaryPaletteAlias = `${SharedPrimaryPaletteAlias}-secondary`;
type SharedPaletteAlias = SharedPrimaryPaletteAlias | SharedSecondaryPaletteAlias;
type DeprecatedAccentAlias = 'accent';
type OpacityStep = `${Percentage}`;
type BackgroundPaletteAlias = 'primary' | 'secondary' | DeprecatedAccentAlias | SharedPaletteAlias;
type BackgroundPalette = Record<BackgroundPaletteAlias, PaletteValue>;
type ForegroundPaletteAlias = 'primary' | 'secondary' | 'tertiary' | 'muted' | 'on-color' | DeprecatedAccentAlias | SharedPaletteAlias;
type ForegroundPalette = Record<ForegroundPaletteAlias, PaletteValue>;
type LinePaletteAlias = 'primary' | 'secondary' | 'tertiary' | 'muted' | DeprecatedAccentAlias | SharedPaletteAlias;
type LinePalette = Record<LinePaletteAlias, PaletteValue>;
type ShadowPaletteAlias = 'primary' | 'secondary';
type ShadowPalette = Record<ShadowPaletteAlias, PaletteValue>;
/** Always palette aliases with 'always/' prefix */
type AlwaysPaletteAliasWithPrefix = 'always/white' | 'always/black' | 'always/transparent' | 'always/current' | 'always/brand' | 'always/accent';
/** Deprecated always palette aliases (without prefix) */
type DeprecatedAlwaysPaletteAlias = 'white' | 'black' | 'transparent' | 'current';
type AlwaysPaletteAlias = DeprecatedAlwaysPaletteAlias | AlwaysPaletteAliasWithPrefix;
type LinkableValue<T extends Record<string, unknown> = Record<string, unknown>> = T & {
  $ref?: string | null;
};
type PaletteType = keyof PaletteConfig;
type PaletteValue = LinkableValue<{
  hue: Hue;
  step: HueStep;
  opacity?: OpacityStep;
}>;
type Palette = { [key in PaletteType]: keyof PaletteConfig[key] };
type PaletteConfig = {
  background: BackgroundPalette;
  foreground: ForegroundPalette;
  line: LinePalette;
  shadow: ShadowPalette;
};
type ForegroundColor = ForegroundPaletteAlias | AlwaysPaletteAlias;
type LineColor = LinePaletteAlias | AlwaysPaletteAlias | ElevationAlias;
type BackgroundColor = BackgroundPaletteAlias | AlwaysPaletteAlias | ElevationAlias;
type ShadowColor = ShadowPaletteAlias | SpectrumColor | AlwaysPaletteAlias | ElevationAlias;
type PropertyToPaletteAliasMap = {
  backgroundColor: BackgroundColor;
  borderColor: LineColor;
  color: ForegroundColor;
};
type ShadowSpectrumColor = {
  type: 'spectrum';
  value: SpectrumColor;
};
type ShadowPaletteColor = {
  type: 'palette';
  value: ShadowColor;
};
type ShadowAlwaysColor = {
  type: 'always';
  value: AlwaysPaletteAlias;
};
type ShadowColorConfig = ShadowPaletteColor | ShadowSpectrumColor | ShadowAlwaysColor;
type ShadowOffset = `-${Exclude<SpacingAlias, '0'>}` | SpacingAlias;
type ShadowOpacity = OpacityStep;
type ShadowSpreadRadius = `-${Exclude<SpacingAlias, '0'>}` | SpacingAlias;
type ShadowPreset = {
  offsetX: ShadowOffset;
  offsetY: ShadowOffset;
  blur: SpacingAlias;
  spread: ShadowSpreadRadius;
  color: ShadowColorConfig;
  opacity: ShadowOpacity;
};
type ShadowVariant = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
type ShadowVariantWithElevation = ShadowVariant | ElevationAlias;
type ShadowVariantInvert = `${Exclude<ShadowVariant, 'none'>}-invert`;
type ShadowVariantWithInvert = ShadowVariant | ShadowVariantInvert;
type ShadowVariantConfig = MaxLengthArray<ShadowPreset, 3>;
type BannerInnerShadowOption = 'none' | 'subtle';
type ShadowType = 'drop' | 'inset';
type ShadowTypeConfig = Record<ShadowVariant, ShadowVariantConfig>;
type ShadowConfig = {
  drop: Record<ShadowVariant, ShadowVariantConfig>;
  inset: Record<ShadowVariant | ShadowVariantInvert, ShadowVariantConfig>;
};
type BreakpointValue = PixelsUnit;
type BreakpointsConfig = {
  sm: BreakpointValue;
  md: BreakpointValue;
  lg: BreakpointValue;
  xl: BreakpointValue;
  '2xl': BreakpointValue;
};
type Breakpoint = keyof BreakpointsConfig;
type BreakpointWithBase = Breakpoint | 'base';
type TextVariantTypography = 'display1' | 'display2' | 'display3' | 'title1' | 'title2' | 'title3' | 'title4' | 'headline1' | 'body1' | 'label1' | 'label2' | 'label3' | 'label4' | 'caption1' | 'caption2' | 'legal1';
type TextVariantUi = 'ui1' | 'ui2' | 'ui3' | 'ui4' | 'ui5' | 'ui6';
type TextVariantWithoutEmphasized = TextVariantTypography | TextVariantUi;
type TextVariant = TextVariantWithoutEmphasized | `${TextVariantWithoutEmphasized}/emphasized`;
type FontAlias = 'sans' | 'sans-alt' | 'serif' | 'serif-alt' | 'mono';
type FontType = 'sans' | 'serif' | 'mono';
type FontWeightNumeric = `${IntRange<100, 901, 100>}`;
type FontWeightDescriptive = 'thin' | 'extralight' | 'light' | 'regular' | 'medium' | 'semibold' | 'bold' | 'extrabold' | 'black';
type TextTransform = 'none' | 'uppercase' | 'lowercase' | 'capitalize';
type TextDecorationLine = 'none' | 'underline';
type LineClampAlias = `${IntRange<1, 7>}`;
type LineHeight = number;
type FontSize = number;
type TextTransformConfig = Record<TextVariantWithoutEmphasized, TextTransform>;
type FontSizeConfig = Record<TextVariantWithoutEmphasized, FontSize>;
type FontFamilyConfig = Record<TextVariantWithoutEmphasized, FontAlias>;
type FontWeightConfig = Record<TextVariantWithoutEmphasized, number>;
type FontSlantConfig = Record<TextVariantWithoutEmphasized, number>;
type FontWidthConfig = Record<TextVariantWithoutEmphasized, number>;
type LineHeightConfig = Record<TextVariantWithoutEmphasized, LineHeight>;
type TextProperty = 'fontFamily' | 'fontSize' | 'fontWeight' | 'lineHeight' | 'textTransform' | 'letterSpacing';
type TypographyUnitValue = PixelsUnit | UnitlessUnit;
type TypographyResponsiveProperty<T> = {
  base: T;
  breakpoints: Record<Breakpoint, T>;
};
type TypographyStyleProperty = keyof TypographyStyle;
type TypographyStyle = {
  fontFamily: TypographyResponsiveProperty<FontAlias>;
  textTransform: TypographyResponsiveProperty<TextTransform>;
  fontSize: TypographyResponsiveProperty<TypographyUnitValue>;
  fontWeight: TypographyResponsiveProperty<TypographyUnitValue>;
  lineHeight: TypographyResponsiveProperty<TypographyUnitValue>;
  fontSlant: TypographyResponsiveProperty<TypographyUnitValue>;
  fontWidth: TypographyResponsiveProperty<TypographyUnitValue>;
  letterSpacing: TypographyResponsiveProperty<PixelsUnit>;
};
type TypographyConfig = Record<TextVariant, TypographyStyle>;
type FontConfig = Record<FontAlias, string>;
type TShirtSize = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
type TShirtSizeCommon = Extract<TShirtSize, 'sm' | 'md' | 'lg'>;
type AvatarSize = '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
type AvatarSizeConfig = Record<AvatarSize, number>;
type AvatarShape = BorderRadius;
type IconSizeConfig = Record<IconSize, number>;
type SpacingAlias = '0' | 'px' | '0.5' | '1' | '1.5' | '2' | '2.5' | '3' | '3.5' | '4' | '4.5' | '5' | '5.5' | '6' | '7' | '8' | '9' | '10' | '11' | '12' | '14' | '16' | '20' | '24' | '28' | '32' | '36' | '40' | '44' | '48' | '52' | '56' | '60' | '64' | '72' | '80' | '96';
type SpacingConfig = Record<SpacingAlias, number>;
type AlwaysPaletteColor<T> = {
  type: 'always';
  value: T;
};
type ElevationSurfaceColor = AlwaysPaletteColor<AlwaysPaletteAlias> | {
  type: 'spectrum';
  value: {
    hue: Hue;
    step: HueStep;
  };
};
type ElevationBackgroundFillColor = {
  type: 'background';
  value: BackgroundPaletteAlias;
} | ElevationSurfaceColor;
type ElevationBorderColor = {
  type: 'line';
  value: LinePaletteAlias;
} | ElevationSurfaceColor;
type RGBColorValue = `${IntRange<0, 256>}`;
type RGBAUnit = {
  type: 'rgba';
  r: RGBColorValue;
  g: RGBColorValue;
  b: RGBColorValue;
  a: OpacityStep;
};
type ElevationCustomShadows = [ShadowPreset, ShadowPreset, ShadowPreset, ShadowPreset];
type ElevationCustomInsetShadows = [ShadowPreset, ShadowPreset];
type RGBUnit = {
  type: 'rgb';
  r: RGBColorValue;
  g: RGBColorValue;
  b: RGBColorValue;
};
type ElevationPreset = {
  surfaceColor: ElevationSurfaceColor & {
    opacity: OpacityStep;
  };
  layerWithBackgroundFill: boolean;
  backgroundFill: ElevationBackgroundFillColor;
  backgroundBlurRadius: number;
  finalBackgroundOpacity: OpacityStep;
  finalBackgroundValue: RGBAUnit;
  fallbackBlurredBackgroundValue: RGBUnit;
  borderColor: ElevationBorderColor;
  borderWidth: BorderWidth;
  dropShadow: ShadowVariant | ElevationCustomShadows;
  insetShadow: ShadowVariantWithInvert | ElevationCustomInsetShadows;
};
type ElevationLevel = '0' | '1' | '2' | '3' | '4' | '5';
type ElevationAlias = `elevation-${ElevationLevel}`;
type ElevationConfig = Record<ElevationLevel, Record<ColorMode, ElevationPreset>>;
type ElevationGlobalRampSettings = {
  progression: Percentage;
  ambientLight: Percentage;
  surfaceColor: ElevationSurfaceColor;
  borderColor: ElevationBorderColor;
  shadowDistance: Percentage;
  shadowOpacity: Percentage;
  shadowColor: ShadowColorConfig;
  backgroundOpacity: Percentage;
  backgroundBlurRadius: Percentage;
};
type ElevationGlobalRampConfig = {
  isAdvancedModeEnabled: boolean;
  colorMode: Record<ColorMode, ElevationGlobalRampSettings>;
};
type FocusRingWidth = 1 | 2 | 3 | 4;
type FocusRingOffset = 0 | 1 | 2 | 3 | 4;
type FocusRingColor = {
  type: 'line';
  value: LinePaletteAlias;
} | {
  type: 'spectrum';
  value: {
    hue: Hue;
    step: HueStep;
  };
} | {
  type: 'always';
  value: AlwaysPaletteAlias;
};
type FocusRingConfig = {
  width: FocusRingWidth;
  offset: FocusRingOffset;
  color: FocusRingColor;
};
type FocusRingModeConfig = Record<ColorMode, FocusRingConfig>;
type BorderRadius = TShirtSize;
type BorderRadiusConfig = Record<BorderRadius, number>;
type BorderWidth = 'none' | 'thin' | 'medium' | 'thick';
type BorderWidthWithElevation = BorderWidth | ElevationAlias;
type BorderWidthConfig = Record<BorderWidth, number>;
type ColorMode = 'light' | 'dark';
type ColorModeForApp = ColorMode | 'system';
type ColorModeConfig = Record<ColorMode, ColorsConfig>;
type ColorsConfig = {
  palette: PaletteConfig;
  spectrum: SpectrumConfig;
};
type SpectrumRGB = {
  type: 'rgb';
  r: number;
  g: number;
  b: number;
};
type SpectrumValueEntry = LinkableValue<{
  rgb: SpectrumRGB;
}>;
type SpectrumValue = Record<HueStep, SpectrumValueEntry>;
type SpectrumConfig = Record<Hue, SpectrumValue>;
type ScaleMode = 'xSmall' | 'small' | 'medium' | 'large' | 'xLarge' | 'xxLarge' | 'xxxLarge';
type ScaleModeForApp = ScaleMode | 'system';
type ScaleConfig = {
  avatarSizes: AvatarSizeConfig;
  iconSizes: IconSizeConfig;
  borderRadius: BorderRadiusConfig;
  borderWidth: BorderWidthConfig;
};
type ScaleModeConfig = Record<ScaleMode, ScaleConfig>;
type ButtonSize = Extract<TShirtSize, 'xs' | 'sm' | 'md' | 'lg'>;
type ButtonPalette = 'brand' | 'accent' | 'alert' | 'positive' | 'warning' | 'info';
type ButtonVariant = 'primary' | 'secondary' | 'tertiary';
type ButtonContrastVariant = 'contrast-high' | 'contrast-medium' | 'contrast-low';
type ScaleEffect = 'none' | 'up' | 'down';
type ButtonVariantFlat = ButtonVariant | ButtonContrastVariant | `${Exclude<ButtonPalette, 'accent'>}` | `${Exclude<ButtonPalette, 'accent'>}-${Exclude<ButtonVariant, 'primary'>}`;
type ButtonSpectrumColor = {
  type: 'spectrum';
  value: SpectrumColor;
};
type ButtonPaletteColor<T> = {
  type: 'palette';
  value: T;
};
type IconButtonSize = Extract<TShirtSize, 'xs' | TShirtSizeCommon | 'xl'>;
type InputSize = Extract<TShirtSizeCommon, 'md' | 'lg'>;
type PlatformMode = 'web' | 'ios' | 'android';
type HighContrastMode = boolean;
type RegionMode = '🇺🇸 US' | '🇩🇪 DE' | '🇫🇷 FR' | '🇨🇳 CN';
interface Modes {
  colorMode: ColorMode;
  scaleMode: ScaleMode;
}
type Animation = 'none' | 'spin' | 'ping' | 'pulse' | 'bounce';
type TransitionDelay = '0' | '75' | '100' | '150' | '200' | '300' | '500' | '700' | '1000';
type TransitionDuration = '0' | '75' | '100' | '150' | '200' | '300' | '500' | '700' | '1000';
type TransitionTiming = 'linear' | 'in' | 'out' | 'in-out';
type MotionVariant = 'damped' | 'smooth' | 'subtle' | 'bouncy' | 'veryBouncy';
type MotionVariantSpeed = '1' | '2' | '3' | '4';
type MotionSpringConfigOptions = 'damping' | 'stiffness';
type MotionSpringConfig = {
  damping: number;
  stiffness: number;
};
type MotionVariantValues = { [key in MotionVariantSpeed]: MotionSpringConfig };
type MotionConfig = Record<MotionVariant, MotionVariantValues>;
type FontCssVar = `--uds-font-${FontAlias}`;
type MotionCssVar = `--uds-motion-${MotionVariant}-${MotionVariantSpeed}-${keyof MotionSpringConfig}`;
type UdsCssVar = FontCssVar;
type AriaAttribute = 'busy' | 'checked' | 'disabled' | 'expanded' | 'hidden' | 'pressed' | 'readonly' | 'required' | 'selected' | 'invalid';
type DataAttribute = 'active' | 'active-item' | 'autofill' | 'backdrop' | 'enter' | 'leave' | 'focus-visible';
type Flex = '1' | 'auto' | 'initial' | 'none';
type FlexGrow = '0' | '1' | '2' | '3';
type FlexShrink = '0' | '1';
type FlexAlignContent = 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'space-between' | 'space-around';
type FlexAlignItems = 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline';
type FlexAlignSelf = 'auto' | 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline';
type FlexDirection = 'row' | 'column' | 'row-reverse' | 'column-reverse';
type FlexWrap = 'wrap' | 'nowrap' | 'wrap-reverse';
type FlexJustifyContent = 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly';
type FlexBasis = 'min-content';
type Display = 'block' | 'inline-block' | 'inline' | 'flex' | 'inline-flex' | 'table' | 'inline-table' | 'table-caption' | 'table-cell' | 'table-column' | 'table-column-group' | 'table-footer-group' | 'table-header-group' | 'table-row-group' | 'table-row' | 'flow-root' | 'grid' | 'contents' | 'none';
type Overflow = 'auto' | 'hidden' | 'clip' | 'visible' | 'scroll';
type Position = 'static' | 'fixed' | 'absolute' | 'relative' | 'sticky';
type ImageStyleProps = {
  contentFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
};
interface BorderStyleProps {
  borderRadius?: BorderRadius;
  borderTopStartRadius?: BorderRadius;
  borderTopEndRadius?: BorderRadius;
  borderBottomStartRadius?: BorderRadius;
  borderBottomEndRadius?: BorderRadius;
  borderColor?: LineColor;
  borderStartColor?: LineColor;
  borderEndColor?: LineColor;
  borderTopColor?: LineColor;
  borderBottomColor?: LineColor;
  borderWidth?: BorderWidthWithElevation;
  borderVerticalWidth?: BorderWidthWithElevation;
  borderHorizontalWidth?: BorderWidthWithElevation;
  borderStartWidth?: BorderWidthWithElevation;
  borderEndWidth?: BorderWidthWithElevation;
  borderTopWidth?: BorderWidthWithElevation;
  borderBottomWidth?: BorderWidthWithElevation;
}
interface NestedBorderRadiusStyleProps {
  nestedBorderRadius?: boolean | 'first' | 'last';
  nestedBorderRadiusSize?: BorderRadius;
  nestedBorderRadiusSpacing?: SpacingAlias;
  nestedBorderRadiusWidth?: BorderWidthWithElevation;
}
interface ShadowStyleProps {
  dropShadow?: ShadowVariantWithElevation;
  insetShadow?: ShadowVariantWithInvert | ElevationAlias;
}
interface LayoutStyleProps {
  display?: Display;
  overflow?: Overflow;
  overflowX?: Overflow;
  overflowY?: Overflow;
  position?: Position;
}
interface SpacingStyleProps {
  spacing?: SpacingAlias;
  spacingHorizontal?: SpacingAlias;
  spacingVertical?: SpacingAlias;
  spacingBottom?: SpacingAlias;
  spacingEnd?: SpacingAlias;
  spacingStart?: SpacingAlias;
  spacingTop?: SpacingAlias;
  offset?: SpacingAlias;
  offsetVertical?: SpacingAlias;
  offsetHorizontal?: SpacingAlias;
  offsetBottom?: SpacingAlias;
  offsetEnd?: SpacingAlias;
  offsetStart?: SpacingAlias;
  offsetTop?: SpacingAlias;
  columnGap?: SpacingAlias;
  rowGap?: SpacingAlias;
}
interface FlexStyleProps {
  alignContent?: FlexAlignContent;
  alignItems?: FlexAlignItems;
  alignSelf?: FlexAlignSelf;
  flex?: Flex;
  flexDirection?: FlexDirection;
  flexGrow?: FlexGrow;
  flexShrink?: FlexShrink;
  flexWrap?: FlexWrap;
  justifyContent?: FlexJustifyContent;
  flexBasis?: FlexBasis;
}
interface StateStyleProps {
  interactable?: boolean;
  focusable?: boolean;
}
interface TextStyleProps {
  color?: ForegroundColor;
  placeholderColor?: ForegroundColor;
  fontFamily?: TextVariant | FontAlias;
  fontSize?: TextVariant;
  letterSpacing?: TextVariant;
  /** @deprecated Consider using an `emphasized` text variant instead. */
  fontWeight?: TextVariant | FontWeightDescriptive;
  lineHeight?: TextVariant;
  textAlign?: 'center' | 'justify' | 'start' | 'end';
  textTransform?: TextVariant | TextTransform;
}
interface BackgroundStyleProps {
  backgroundColor?: BackgroundColor;
}
type CustomSizingStyleProps = {
  iconSize?: IconSize;
  avatarSize?: AvatarSize;
};
interface SizeStyleProps {
  width?: 'full' | 'fit' | 'screen';
  height?: 'full' | 'fit' | 'screen';
}
type StyleProps = BackgroundStyleProps & BorderStyleProps & LayoutStyleProps & FlexStyleProps & SpacingStyleProps & TextStyleProps & ImageStyleProps & CustomSizingStyleProps & ShadowStyleProps & SizeStyleProps & NestedBorderRadiusStyleProps;
interface UniversalBoxProps extends PropsWithChildren, BackgroundStyleProps, BorderStyleProps, FlexStyleProps, LayoutStyleProps, SpacingStyleProps, SizeStyleProps, ShadowStyleProps, NestedBorderRadiusStyleProps {
  /** Merge props onto the immediate child element instead of rendering a wrapper. */
  asChild?: boolean;
  /** The HTML element type to render. @default 'div' */
  as?: ElementType;
  /** Shorthand that sets backgroundColor, borderColor, borderWidth, and dropShadow to the given elevation level ('0'–'5'). Individual props override the shorthand. */
  elevation?: ElevationLevel;
}
interface UniversalStackProps extends Omit<UniversalBoxProps, 'flexDirection'> {
  /** The spacing between child elements. */
  gap?: SpacingAlias;
  /** Element or render function inserted between each child. */
  separator?: ReactNode | ((index: number) => ReactNode);
}
interface UniversalTextProps extends PropsWithChildren, TextStyleProps, UniversalBoxProps {
  /** Typography variant — sets fontSize, lineHeight, letterSpacing, and fontFamily together. @default 'body1' */
  variant?: TextVariant;
  /** Text color from the theme palette. @default 'primary' */
  color?: ForegroundColor;
}
/**
 * Universal icon props with generic icon type.
 * @template Icon - The icon component type. Defaults to GenericIconComponent.
 */
interface UniversalIconProps<Icon = GenericIconComponent> {
  /** The icon component to render. */
  name: Icon;
  /** Icon size. @default 'md' */
  size?: IconSize;
  /** Icon style variant. @default 'outline' */
  variant?: IconVariant;
  /** Icon color from the theme palette. @default 'primary' */
  color?: ForegroundColor | 'inherit';
}
type SVGElementProps = Omit<HTMLAttributes<SVGSVGElement>, 'color'>;
interface IconPropsWithSVGProps extends UniversalIconProps, SVGElementProps {}
type IconSlotRenderProps = Omit<IconPropsWithSVGProps, 'name'>;
type BackwardsCompatibleReactElement = null | undefined | ReactElement;
/**
 * Universal icon slot type with generic icon type.
 * @template Icon - The icon component type.
 */
type UniversalIconSlot<Icon = GenericIconComponent> = Icon | BackwardsCompatibleReactElement | ((iconProps: IconSlotRenderProps) => BackwardsCompatibleReactElement);
interface UniversalPressableProps extends Omit<UniversalBoxProps, 'as'> {
  /** Callback fired when the element is pressed. */
  onPress?: () => void;
}
interface UniversalIconButtonProps<Icon = GenericIconComponent> {
  /** The visual style variant of the button. */
  variant?: ButtonVariantFlat;
  /** The size of the button. */
  size?: IconButtonSize;
  /** The icon style variant. @default 'outline' */
  iconVariant?: IconVariant;
  /** The icon to render. */
  name: Icon;
  /** HTML name attribute for form submission. */
  htmlName?: string;
  /** Shows a loading spinner and disables the button. */
  loading?: boolean;
  /** Disable motion effects (scale on press, icon animations). @default false */
  disableEffects?: boolean;
  /** Merge props onto the immediate child element instead of rendering a wrapper. @default false */
  asChild?: boolean;
}
interface UniversalButtonProps<IconSlotType = UniversalIconSlot> extends Pick<SizeStyleProps, 'width'> {
  /** The visual style variant of the button. */
  variant?: ButtonVariantFlat;
  /** The size of the button. */
  size?: ButtonSize;
  /** The icon style variant. */
  iconVariant?: IconVariant;
  /** Icon displayed before the button label. */
  startIcon?: IconSlotType;
  /** Icon displayed after the button label. */
  endIcon?: IconSlotType;
  /** Shows a loading spinner and disables the button. @default false */
  loading?: boolean;
  /** Disable motion effects (scale on press, icon animations). @default false */
  disableEffects?: boolean;
  /** Merge props onto the immediate child element instead of rendering a wrapper. @default false */
  asChild?: boolean;
}
interface UniversalImageProps extends Omit<UniversalBoxProps, 'width' | 'height'>, ImageStyleProps {
  /** Image source URL. */
  src: string;
  /** Alt text for accessibility. */
  alt?: string;
  /** Image width in pixels. */
  width?: number;
  /** Image height in pixels. */
  height?: number;
}
type ImgElementProps = Omit<React.ImgHTMLAttributes<HTMLImageElement>, 'size' | 'color' | 'height' | 'width' | 'alt' | 'src'>;
interface ImagePropsWithImgProps extends UniversalImageProps, ImgElementProps {}
interface UniversalFormLabelProps extends Omit<UniversalTextProps, 'variant' | 'color'> {
  /** The HTML element type to render. */
  as?: ElementType;
  /** Typography variant for the label text. */
  variant?: UniversalTextProps['variant'] | 'inherit';
  /** Whether the field is required (shows asterisk). */
  required?: boolean;
  /** Label text color. */
  color?: ForegroundColor | 'inherit';
  /** Whether the associated field has a validation error. */
  hasError?: boolean;
  /** Whether to display a required asterisk (*) next to the label. */
  showRequiredAsterisk?: boolean;
  /** The label content. */
  label?: string | ReactNode | (() => ReactNode);
}
interface UniversalInputProps<IconSlotType = UniversalIconSlot> {
  /** The label displayed above the input. */
  label?: string | ReactNode | (() => ReactNode);
  /** Whether the input is disabled. */
  disabled?: boolean;
  /** Whether the input is required. */
  required?: boolean;
  /** Helper text displayed below the input. */
  helpText?: string | ReactNode | (() => ReactNode);
  /** Icon displayed alongside the helper text. */
  helperTextIcon?: IconSlotType;
  /** Whether the input has a validation error. */
  hasError?: boolean;
  /** The size of the input. @default 'md' */
  size?: InputSize;
  /** Icon displayed at the start of the input. */
  startIcon?: IconSlotType;
  /** Icon displayed at the end of the input. */
  endIcon?: IconSlotType;
  /** Disable motion and transition effects. */
  reduceMotion?: boolean;
  /** Whether the input is read-only. */
  readOnly?: boolean;
  /** The width of the input container. @default 'full' */
  width?: UniversalBoxProps['width'];
}
type DividerVariant = 'primary' | 'secondary' | 'tertiary' | 'muted';
interface UniversalDividerProps {
  /** The visual style variant of the divider. @default 'primary' */
  variant?: DividerVariant;
  /** Whether to render as a vertical divider. @default false */
  vertical?: boolean;
  /** Position of content within the divider. @default 'center' */
  contentPosition?: 'start' | 'center' | 'end';
}
type LinkVariant = 'primary' | 'secondary' | 'tertiary' | 'on-color';
type LinkTextVariant = TextVariantWithoutEmphasized;
interface UniversalLinkProps<IconSlotType = UniversalIconSlot> {
  /** Typography variant for the link text. */
  textVariant?: LinkTextVariant;
  /** The visual style variant of the link. @default 'primary' */
  variant?: LinkVariant;
  /** Icon displayed before the link text. */
  startIcon?: IconSlotType;
  /** Icon displayed after the link text. */
  endIcon?: IconSlotType;
  /** Always show an underline, not just on hover. @default false */
  alwaysUnderline?: boolean;
}
type CheckboxValue = boolean | 'indeterminate';
type CheckboxVariant = 'primary' | 'secondary';
type CheckboxSize = 'sm' | 'md';
interface UniversalCheckboxProps {
  /** The visual style variant of the checkbox. @default 'primary' */
  variant?: CheckboxVariant;
  /** The size of the checkbox. @default 'md' */
  size?: CheckboxSize;
  /** The label content displayed alongside the checkbox. */
  label?: string | ReactNode | (() => ReactNode);
  /** The controlled checked state. */
  checked?: CheckboxValue;
  /** Whether the checkbox has a validation error. */
  hasError?: boolean;
  /** Disable motion and transition effects. */
  reduceMotion?: boolean;
  /** Position of the label relative to the checkbox. @default 'start' */
  labelPosition?: 'start' | 'end';
}
type RadioValue = boolean;
type RadioVariant = 'primary' | 'secondary';
type RadioSize = 'sm' | 'md';
interface UniversalRadioProps {
  /** The visual style variant of the radio. @default 'primary' */
  variant?: RadioVariant;
  /** The size of the radio. @default 'md' */
  size?: RadioSize;
  /** The label content displayed alongside the radio. */
  label?: string | ReactNode | (() => ReactNode);
  /** The option value for this radio. Required when used inside a RadioGroup. @default '' */
  value?: string;
  /** The controlled checked state. */
  checked?: boolean;
  /** Whether the radio has a validation error. */
  hasError?: boolean;
  /** Disable motion and transition effects. */
  reduceMotion?: boolean;
  /** Position of the label relative to the radio. @default 'start' */
  labelPosition?: 'start' | 'end';
}
interface UniversalRadioGroupProps {
  /** The name shared by all radios in the group (for form submission). */
  name?: string;
  /** The controlled selected option value. */
  value?: string;
  /** The initial selected value for uncontrolled mode. */
  defaultValue?: string;
  /** Callback fired when the selected value changes. */
  onChange?: (value: string | undefined) => void;
  /** Merge props onto the immediate child element instead of rendering a wrapper. */
  asChild?: boolean;
}
type SwitchSize = 'sm' | 'md';
interface UniversalSwitchProps<IconSlotType = UniversalIconSlot> {
  /** The size of the switch. @default 'md' */
  size?: SwitchSize;
  /** The label content displayed alongside the switch. */
  label?: string | ReactNode | (() => ReactNode);
  /** The controlled on/off state. */
  isOn?: boolean;
  /** The initial on/off state for uncontrolled mode. */
  defaultIsOn?: boolean;
  /** Icon displayed inside the switch when on. */
  onIcon?: IconSlotType;
  /** Icon displayed inside the switch when off. */
  offIcon?: IconSlotType;
  /** Disable motion and transition effects. */
  reduceMotion?: boolean;
  /** Position of the label relative to the switch. @default 'start' */
  labelPosition?: 'start' | 'end';
}
type ChipVariant = 'primary' | 'secondary' | 'brand' | 'brand-secondary';
type ChipSize = 'sm' | 'md';
interface UniversalChipBaseProps<IconSlotType = UniversalIconSlot> extends PropsWithChildren {
  /** The visual style variant of the chip. */
  variant?: ChipVariant;
  /** The size of the chip. @default 'md' */
  size?: ChipSize;
  /** Icon displayed at the start of the chip. */
  startIcon?: IconSlotType;
  /** Icon displayed at the end of the chip. */
  endIcon?: IconSlotType;
  /** Minimum width of the chip in pixels. */
  minWidth?: number;
  /** Maximum width of the chip in pixels. @default 200 */
  maxWidth?: number;
  /** The HTML element type to render. */
  as?: ElementType;
  /** Disable motion and transition effects. */
  reduceMotion?: boolean;
  /** Whether the chip is disabled. @default false */
  disabled?: boolean;
}
interface UniversalChipDismissibleProps<IconSlotType = UniversalIconSlot> extends Omit<UniversalChipBaseProps, 'endIcon' | 'asChild'> {
  /** Callback fired when the dismiss button is pressed. Shows a dismiss icon. */
  onDismiss?: () => void;
  /** Accessibility label for the dismiss button. */
  dismissButtonAriaLabel?: string;
  /** Custom icon for the dismiss button. */
  dismissIcon?: IconSlotType;
}
interface UniversalChipToggleProps extends Omit<UniversalChipBaseProps, 'asChild'> {
  /** Whether the chip is toggled/selected. */
  isToggled?: boolean;
  /** Callback fired when the chip toggle state changes. */
  onToggle?: (isToggled: boolean) => void;
}
type UniversalChipButtonProps = Omit<UniversalChipToggleProps, 'isToggled' | 'onToggle' | 'asChild'>;
interface UniversalChipLinkProps extends UniversalChipBaseProps {
  /** The URL the chip links to. */
  href?: string;
}
interface UniversalChipProps extends UniversalChipToggleProps, UniversalChipLinkProps, UniversalChipButtonProps, UniversalChipDismissibleProps {}
type BadgeVariant = 'primary' | 'secondary' | 'brand' | 'brand-secondary' | 'alert' | 'alert-secondary' | 'positive' | 'positive-secondary' | 'warning' | 'warning-secondary' | 'info' | 'info-secondary';
type BadgeSize = 'xs' | 'sm' | 'md' | 'lg';
interface UniversalBadgeProps<IconSlotType = UniversalIconSlot> extends PropsWithChildren {
  /** The HTML element type to render. */
  as?: ElementType;
  /** The visual style variant of the badge. @default 'primary' */
  variant?: BadgeVariant;
  /** The size of the badge. @default 'md' */
  size?: BadgeSize;
  /** Override the background color. */
  backgroundColor?: string;
  /** Override the text color. */
  color?: string;
  /** Override the icon color. */
  iconColor?: string;
  /** Override the border color. */
  borderColor?: string;
  /** Icon displayed at the start of the badge. */
  startIcon?: IconSlotType;
  /** Icon displayed at the end of the badge. */
  endIcon?: IconSlotType;
  /** Minimum width of the badge in pixels. */
  minWidth?: number;
  /** Maximum width of the badge in pixels. @default 200 */
  maxWidth?: number | 'full';
}
type BannerVariant = 'primary' | 'secondary' | 'brand' | 'brand-secondary' | 'alert' | 'alert-secondary' | 'warning' | 'warning-secondary' | 'success' | 'success-secondary' | 'info' | 'info-secondary';
type BannerSize = 'default';
interface UniversalBannerProps<IconSlotType = UniversalIconSlot> {
  /** The visual style variant of the banner. @default 'primary' */
  variant?: BannerVariant;
  /** The size of the banner. @default 'default' */
  size?: BannerSize;
  /** Icon displayed at the start of the banner. */
  startIcon?: IconSlotType;
  /** Banner title. Ignored when BannerContent is used. */
  title?: ReactNode;
  /** Banner description. Truncated to 3 lines. Ignored when BannerContent is used. */
  description?: ReactNode;
  /** Dismiss button handler. The dismiss button is only rendered when this is provided. */
  onDismiss?: () => void;
  /** Actions (Button, Link) or BannerContent + actions. */
  children?: ReactNode;
}
type AvatarVariant = 'primary' | 'secondary';
type AvatarAbbreviationStrategy = 'first' | 'last' | 'firstAndLast' | 'firstTwo' | 'firstThree' | 'firstOfEach' | ((name: string) => string);
interface UniversalAvatarBaseProps {
  /** The size of the avatar. @default 'md' */
  size?: AvatarSize;
  /** The visual style variant of the avatar. @default 'primary' */
  variant?: 'primary' | 'secondary';
  /** Custom size in pixels, overriding the size token. */
  customSize?: number;
  /** Strategy for generating initials from a name. */
  abbreviationStrategy?: AvatarAbbreviationStrategy;
  /** Alt text for accessibility. */
  alt?: string;
  /** Additional CSS class name. */
  className?: string;
}
interface UniversalAvatarImageProps extends UniversalAvatarBaseProps {
  /** Image source URL. */
  src: string;
  /** Responsive image source set. */
  srcSet?: string;
  /** Fallback name or initials displayed when the image fails to load. */
  fallback?: string;
}
interface UniversalAvatarTextProps extends UniversalAvatarBaseProps {
  /** Full name used to generate initials. */
  name?: string;
  /** Explicit initials to display (overrides auto-generated from name). */
  initials?: string;
}
interface UniversalAvatarIconProps<IconSlotType = UniversalIconSlot> extends Omit<UniversalAvatarBaseProps, 'abbreviationStrategy'> {
  /** Custom icon to display in the avatar. */
  icon?: IconSlotType;
}
type UniversalAvatarProps = UniversalAvatarImageProps;
interface UniversalMenuItemProps<IconSlotType = UniversalIconSlot> extends Omit<UniversalPressableProps, 'asChild'>, PropsWithChildren {
  /** Icon displayed at the end of the menu item. */
  endIcon?: IconSlotType;
  /** Icon displayed at the start of the menu item. */
  startIcon?: IconSlotType;
  /** Typography variant for the menu item text. */
  textVariant?: TextVariant;
  /** The value identifying this menu item. */
  name?: string;
  /** Whether this menu item is currently active/highlighted. */
  active?: boolean;
  /** Whether the menu item is disabled. */
  disabled?: boolean;
  /** Whether the menu item text should wrap to multiple lines instead of being truncated. */
  multiline?: boolean;
  /** Render prop slots for customizing internal elements. */
  slots?: {
    root?: (props: HTMLAttributes<any> & {
      ref?: Ref<any>;
    }) => ReactNode;
  };
}
type ToastSize = 'default';
type ToastVariant = 'info' | 'success' | 'warning' | 'error' | 'loading';
type ToastPosition = 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'top-center' | 'bottom-center';
interface UniversalToastProps {
  /**
   * The size of the toast.
   */
  size?: ToastSize;
  /**
   * The variant of the toast.
   */
  variant?: ToastVariant;
  /**
   * The contents of the toast.
   */
  message: ReactNode;
  /**
   * An optional action button to display within the toast.
   */
  actionButton?: ReactNode;
  /**
   * Callback function to be called when the action button is clicked.
   */
  onClickActionButton?: () => void;
  /**
   * Optional icon displayed at the start of the toast.
   */
  startIcon?: UniversalIconSlot | false;
  /**
   * Optional icon displayed at the start of the toast.
   */
  closeIcon?: UniversalIconSlot | false;
  /**
   * Callback function to be called when the close button is clicked.
   */
  onClickCloseButton?: (id?: string) => void;
  /**
   * Optional class name for custom styling.
   */
  className?: string;
  /**
   * Remove animation and transition effects for users who prefer reduced motion.
   */
  reduceMotion?: boolean;
}
type VerticalPlacement = 'top' | 'bottom';
type HorizontalPlacement = 'start' | 'end';
type TooltipPlacement = VerticalPlacement | HorizontalPlacement | `${VerticalPlacement}-${HorizontalPlacement}` | `${HorizontalPlacement}-${VerticalPlacement}`;
type TooltipSize = 'default';
type TooltipVariant = 'default';
type UniversalTabsVariant = 'primary' | 'secondary';
interface UniversalTooltipProps {
  /** The TooltipTrigger and TooltipContent elements */
  children: ReactNode;
  /** The preferred placement of the tooltip relative to the trigger element @default 'top' */
  placement?: TooltipPlacement;
  /** Hiding and showing should usually be controlled internally by the component, but this prop is here for special use cases. */
  open?: boolean;
  /** Whether to render the tooltip content in a portal @default true */
  portal?: boolean;
}
interface UniversalTooltipTriggerProps {
  /** The content to display inside the tooltip trigger. This is what the tooltip will be anchored to. */
  children: ReactNode;
}
interface UniversalTooltipContentProps {
  /** The body content of the tooltip. */
  children: ReactNode;
  /** The maximum width of the tooltip content. Accepts a number in pixels or a string in CSS units. */
  maxWidth?: string | number;
  /** An icon displayed at the start of the tooltip title. */
  startTitleIcon?: UniversalIconSlot;
  /** An optional title rendered above the body content. */
  title?: ReactNode;
  /** Additional content rendered at the end of the tooltip (e.g. a keyboard shortcut). */
  endContent?: ReactNode;
  /** A custom CSS class name applied to the tooltip content container. */
  className?: string;
  /** A custom `id` attribute for the tooltip content element, useful for accessibility linking. */
  id?: string;
}
interface UniversalTabsProps {
  /** The TabList and TabPanel elements. */
  children: ReactNode;
  /** Visual style variant for the tab list and indicators. @default 'primary' */
  variant?: UniversalTabsVariant;
  /**
   * When true, the sliding selection indicator motion is reduced and selection chrome is
   * applied per tab without sliding motion. When false (default), the underline / pill is a single
   * layer that slides between tabs (240ms, same easing as the design reference). @default false
   */
  reduceMotion?: boolean;
  /** The id of the tab selected by default (uncontrolled). */
  defaultSelectedId?: string;
  /** The controlled selected tab id. `null` represents no selected tab. */
  selectedId?: string | null;
  /** Callback when the selected tab changes. */
  onSelectionChange?: (selectedId: string | null | undefined) => void;
}
interface UniversalTabListProps extends React.AriaAttributes {
  /** Tab items rendered within the list. */
  children: ReactNode;
  /** Enables horizontal scrolling when tabs overflow. */
  scrollable?: boolean;
  /** Optional class name for custom styling. */
  className?: string;
}
interface UniversalTabPanelProps {
  /** The id of the associated tab. */
  tabId: string;
  /** Content shown when the associated tab is selected. */
  children: ReactNode;
  /** Optional class name for custom styling. */
  className?: string;
}
interface UniversalTabProps {
  /** Unique identifier for this tab, used to connect with a TabPanel. When omitted, one is auto-generated. */
  value?: string;
  /** Tab content, typically a text label. */
  children: ReactNode;
  /** Icon rendered before the label. */
  startIcon?: UniversalIconSlot;
  /** Icon rendered after the label. */
  endIcon?: UniversalIconSlot;
  /** Disables the tab. */
  disabled?: boolean;
  /** Merge props onto the immediate child element instead of rendering a wrapper. */
  asChild?: boolean;
  /** Optional class name for custom styling. */
  className?: string;
}
type PaddleNavOrientation = 'horizontal' | 'vertical' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
type PaddleNavVariant = 'primary' | 'secondary' | 'tertiary';
type PaddleNavSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
interface UniversalPaddleNavProps {
  /** Main content (image, strip of tiles, etc.) and `PaddleButtonPrevious` / `PaddleButtonNext` components. */
  children: ReactNode;
  /**
   * Maps to chevron choice + placement.
   * @default 'horizontal'
   */
  orientation?: PaddleNavOrientation;
  /**
   * `false` = paddles overlay (absolute layer). `true` = paddles in gutters (no overlap).
   * @default false
   */
  outsideContent?: boolean;
  /**
   * The visual style variant of the paddle buttons.
   * @default 'primary'
   */
  variant?: PaddleNavVariant;
  /**
   * The size of the paddle buttons.
   * @default 'md'
   */
  size?: PaddleNavSize;
}
interface UniversalPaddleButtonProps<IconSlot = GenericIconComponent> {
  /** Wire to decrement/increment index, scroll, etc. */
  onClick?: () => void;
  /** Disables button. @default false */
  disabled?: boolean;
  /**
   * Hides the paddle while preserving its layout slot in `PaddleNav` (e.g. next stays on the right).
   * @default false
   */
  hidden?: boolean;
  /**
   * Optional custom icon. `PaddleButtonPrevious` defaults to ChevronLeft (ChevronUp when vertical);
   * `PaddleButtonNext` defaults to ChevronRight (ChevronDown when vertical).
   */
  icon?: IconSlot;
}
interface UniversalPaddleNavContentProps {
  /** Merge props onto the immediate child element instead of rendering a wrapper. @default false */
  asChild?: boolean;
  /** The content to wrap. */
  children?: ReactNode;
}
type PaginationSize = 'sm' | 'md';
type PaginationVariant = 'default';
type PaginationVisibleItem = number | 'ellipsis';
type PaginationEllipsisPlacement = 'default' | 'none' | ((params: {
  activePage: number;
  totalPages: number;
  maxVisiblePageNumbers: number;
}) => PaginationVisibleItem[]);
interface UniversalPaginationProps {
  /** Current page (1-indexed). Consumer-controlled. */
  activePage: number;
  /** Total number of pages. */
  totalPages: number;
  /**
   * Max numeric page controls rendered (ellipses excluded).
   * @default 7
   */
  maxVisiblePageNumbers?: number;
  /**
   * How to truncate page numbers when `totalPages` exceeds `maxVisiblePageNumbers`.
   * @default 'default'
   */
  ellipsisPlacement?: PaginationEllipsisPlacement;
  /**
   * @default 'md'
   */
  size?: PaginationSize;
  /**
   * @default 'default'
   */
  variant?: PaginationVariant;
  /** Main content: `PaginationPrev`, `PaginationNumbers`, `PaginationNext`, etc. */
  children: ReactNode;
  /** Optional href factory for link-based page controls. */
  getPageHref?: (page: number) => string;
  /**
   * Optional factory for the accessible label of each page control, used for
   * localization. Receives the page number and whether it is the active page.
   * @default page => isActive ? `Page ${page}, current page` : `Go to page ${page}`
   */
  getItemAriaLabel?: (page: number, isActive: boolean) => string;
  /** Called when a page control is activated (e.g. page number click). */
  onPageChange?: (page: number) => void;
  className?: string;
}
interface UniversalPaginationItemProps {
  /** Page number (1-indexed). */
  page: number;
  /** @default false */
  asChild?: boolean;
  children?: ReactNode;
  className?: string;
}
interface UniversalPaginationLinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
  page: number;
  href: string;
  /** @default false */
  asChild?: boolean;
  children?: ReactNode;
  className?: string;
}
interface UniversalPaginationPrevProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'color'> {
  /** @default 'Previous' on web, 'Prev' on mobile */
  label?: string;
  /** @default false */
  asChild?: boolean;
  className?: string;
}
interface UniversalPaginationNextProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'color'> {
  /** @default 'Next' */
  label?: string;
  /** @default false */
  asChild?: boolean;
  className?: string;
}
interface UniversalPaginationNumbersProps {
  /** Custom render for each page number. */
  renderItem?: (page: number, state: {
    isActive: boolean;
  }) => ReactNode;
  className?: string;
}
type BottomSheetVariant = 'default';
type BottomSheetHeight = `${number}%` | `${number}px`;
type BottomSheetSnapPoints = BottomSheetHeight[];
interface UniversalBottomSheetProps extends PropsWithChildren {
  /** Optional class name for custom styling. */
  className?: string;
  /**
   * Token-driven visual variant.
   * @remarks Maps to `bottomSheet.variants.variant` in config.
   * @default 'default'
   */
  variant?: BottomSheetVariant;
  /**
   * Snap points for the sheet (low → high).
   * @default [height ?? '40%']
   */
  snapPoints?: BottomSheetSnapPoints;
  /**
   * Which snap point index to open to when the sheet is shown.
   * @default 0
   */
  defaultSnapPointIndex?: number;
  /**
   * Controlled snap point index.
   */
  snapPointIndex?: number;
  /**
   * Called when the active snap point changes (via drag or programmatic update).
   * @param index Active snap point index.
   * @param height Resolved snap point height value.
   */
  onSnapPointChange?: (index: number, height: BottomSheetHeight) => void;
  /**
   * Convenience alias for a single snap point.
   * @remarks Ignored when `snapPoints` is provided.
   * @default '40%'
   */
  height?: BottomSheetHeight;
  /**
   * Enable built-in dismissal interactions (Escape/scrim on web, drag-to-dismiss).
   * @default true
   */
  dismissible?: boolean;
  /**
   * Enable drag gestures (snap points + dismiss).
   * @default true
   */
  enableDrag?: boolean;
  /**
   * Show a handle indicator affordance (communicates "draggable/resizable").
   * @remarks Ignored when `enableDrag` is `false`.
   * @default true
   */
  showHandleIndicator?: boolean;
  /**
   * Animate horizontal/bottom margins to `0` at the highest snap point.
   * @remarks Requires 2 or more snap points.
   * @default false
   */
  fullWidthAtMaxSnap?: boolean;
}
interface UniversalBottomSheetHeaderProps extends PropsWithChildren {
  /** Content rendered on the start side of the header. */
  start?: ReactNode;
  /** Content rendered on the end side of the header. */
  end?: ReactNode;
  /** Variant of the bottom sheet header. */
  variant?: BottomSheetVariant;
  /** Optional class name for custom styling. */
  className?: string;
}
interface UniversalBottomSheetContentProps extends PropsWithChildren {
  /** Optional class name for custom styling. */
  className?: string;
}
type PopoverPlacement = TooltipPlacement;
type PopoverSize = 'default';
type PopoverVariant = 'default';
/** Shared props for the web Popover root component. */
interface UniversalPopoverProps {
  /** The PopoverTrigger and PopoverContent elements */
  children: ReactNode;
  /** The preferred placement of the popover relative to the trigger element @default 'top' */
  placement?: PopoverPlacement;
  /** Whether to render the popover content in a portal @default true */
  portal?: boolean;
  /** Whether to hide the popover arrow @default false */
  hideArrow?: boolean;
  /** Whether to hide the popover dismiss button @default false */
  hideDismissButton?: boolean;
  /** If left undefined, the popover will be toggled by clicking the trigger element. Otherwise, it can be controlled with this prop. */
  open?: boolean;
  /** Sets the initial open state of the popover @default false */
  defaultOpen?: boolean;
  /** Callback function to be called when the popover is closed. */
  onClose?: (event: Event) => void;
  /** Callback function to be called when the popover is opened. */
  onOpen?: () => void;
  /** Reduce motion and transition effects. */
  reduceMotion?: boolean;
  /** Disable auto-focus behavior when showing/hiding the popover @default false */
  disableAutoFocus?: boolean;
  /** Turns off padding at the top and bottom of the popover content. Useful for when you need contents to go all the way to the edge. @default false */
  disableVerticalSpacing?: boolean;
  /** Turns off padding at the sides of the popover content. Useful for when you need contents to go all the way to the edge. @default false */
  disableHorizontalSpacing?: boolean;
  /** Whether to make the popover content the same width as the trigger. @default false */
  sameWidth?: boolean;
  /** The gap between the popover content and the trigger. @default 4 */
  gutter?: number;
}
/** Shared props for the web PopoverTrigger component. */
interface UniversalPopoverTriggerProps {
  /** The content to display inside the popover trigger. This is what the popover will be anchored to. */
  children: ReactNode;
}
/** Shared props for the web PopoverContent component. */
interface UniversalPopoverContentProps {
  /** The content of the popover. */
  children: ReactNode;
  /** Custom CSS classes applied to the popover content container. */
  className?: string;
  /** Optional icon displayed at the end of the popover content. */
  closeIcon?: UniversalIconSlot;
  /** The maximum width of the popover content. Accepts a number in pixels or a string in CSS units. Keywords like 'none', 'auto', 'max-content', 'min-content', 'fit-content', 'inherit', 'initial', 'unset', 'revert', 'revert-layer' are not allowed. */
  maxWidth?: string | number;
  /** The maximum height of the popover content. Accepts a number in pixels or a string in CSS units. Keywords like 'none', 'auto', 'max-content', 'min-content', 'fit-content', 'inherit', 'initial', 'unset', 'revert', 'revert-layer' are not allowed. */
  maxHeight?: string | number;
}
type ModalSize = 'default';
type ModalVariant = 'default';
interface UniversalModalProps {
  /** The content of the modal. */
  children?: ReactNode;
  /** Whether the modal is open. */
  open: boolean;
  /** Callback function to be called when the modal is closed (dismiss button clicked, a click is registered outside, escape button pressed) */
  onClose?: (event: Event) => void;
  /** Callback function to be called when the modal is opened (i.e. `open` prop is set to true) */
  onOpen?: () => void;
  /** Whether to render the modal content in a portal @default true */
  portal?: boolean;
  /** When false, disables focus trapping and body scroll prevention. @default true */
  modal?: boolean;
  /** Overrides whether the backdrop scrim is rendered. When unset, the scrim is rendered unless `modal` is set to `false`. */
  includeScrim?: boolean;
  /** Whether to hide the modal dismiss button @default false */
  hideDismissButton?: boolean;
  /** Reduce motion and transition effects @default false */
  reduceMotion?: boolean;
  /** Icon displayed inside the modal dismiss button */
  closeIcon?: UniversalIconSlot;
  /** Number (px) or CSS value that constrains the width of the modal @default "auto" */
  maxWidth?: string | number;
  /** Number (px) or CSS value that constrains the height of the modal. Once this height is reached, the modal will scroll internally. This value is ignored when `scrollBehavior` is set to "outside". @default "auto" */
  maxHeight?: string | number;
  /** When false, modal will expand to fit the content within. When true, modal will expand horizontally until it reaches the defined `maxWidth` prop or hits the gutter defined in your component config. @default false */
  fullWidth?: boolean;
  /** When false, modal will expand to fit the content within. When true, modal will expand vertically until it reaches the defined `maxHeight` prop or hits the gutter defined in your component config. This value is ignored when `scrollBehavior` is set to "outside". @default false */
  fullHeight?: boolean;
  /** Determines how the modal will scroll if its height is larger than the space available in the current viewport @default "outside" */
  scrollBehavior?: 'inside' | 'outside';
  /** The title of the modal. Gets ignored if `<ModalTitle />` is used. */
  title?: ReactNode;
  /** The description of the modal. Gets ignored if `<ModalDescription />` is used. */
  description?: ReactNode;
  /** The main content of the modal. Gets ignored if `<ModalContent />` is used. */
  content?: ReactNode;
  /** Actions to be displayed at the bottom of the modal. Gets ignored if `<ModalActions />` is used. */
  actions?: ReactNode;
  /** Accessible label for the close button. @default "Close" */
  closeAriaLabel?: string;
  /** Additional CSS class name applied to the modal surface. */
  className?: string;
  /** Additional inline styles applied to the modal surface. */
  style?: CSSProperties;
}
interface UniversalModalTitleProps {
  /** The title content. */
  children: ReactNode;
}
interface UniversalModalDescriptionProps {
  /** The description content. */
  children: ReactNode;
}
interface UniversalModalContentProps extends Pick<UniversalBoxProps, 'asChild'> {
  /** The main content of the modal. */
  children: ReactNode;
}
interface UniversalModalActionsProps extends Pick<UniversalBoxProps, 'asChild'> {
  /** The action content. */
  children: ReactNode;
  /** Additional content to be displayed at the start of the actions footer */
  startContent?: ReactNode;
}
/**
 * Base interface for configurable component names.
 * The full list is: avatar, badge, button, checkbox, chip, divider, iconButton, input, link, menu, radio, switch
 */
type ConfigurableComponentName = 'avatar' | 'badge' | 'button' | 'checkbox' | 'chip' | 'divider' | 'iconButton' | 'input' | 'link' | 'menu' | 'radio' | 'switch' | 'toast' | 'tooltip';
/**
 * Base interface for UniversalTokensConfigAuto.
 * This is extended by @yahoo/uds with the full generated config.
 */
interface UniversalTokensConfigAutoBase {
  [key: string]: unknown;
}
/**
 * Base universal tokens configuration interface.
 * This contains the core config properties that all platforms need.
 */
interface UniversalTokensConfigBase {
  $defs?: {
    links: {
      systems: Record<string, string>;
    };
  };
  version: string;
  colorMode: ColorModeConfig;
  scaleMode: ScaleModeConfig;
  font: FontConfig;
  motion: MotionConfig;
  shadow: ShadowConfig;
  breakpoints: BreakpointsConfig;
  typography: TypographyConfig;
  elevation: ElevationConfig;
  elevationGlobalRamp: ElevationGlobalRampConfig;
  focusRing: FocusRingModeConfig;
  globalDefaults: GlobalDefaultsConfig;
}
/**
 * Universal tokens configuration type.
 * Combines base config with auto-generated component config.
 * @template ConfigAuto - The auto-generated component config type. Defaults to UniversalTokensConfigAutoBase.
 */
type UniversalTokensConfigGeneric<ConfigAuto = UniversalTokensConfigAutoBase> = UniversalTokensConfigBase & ConfigAuto;
type GlobalDefaultsConfig = {
  breakpoint: Breakpoint | 'base';
  enableResponsiveType: boolean;
}; //#endregion
//#endregion
export { type AlwaysPaletteAlias, type AlwaysPaletteAliasWithPrefix, type AlwaysPaletteColor, type Animation, type AriaAttribute, type AvatarAbbreviationStrategy, type AvatarShape, type AvatarSize, type AvatarSizeConfig, type AvatarVariant, type BackgroundColor, type BackgroundPalette, type BackgroundPaletteAlias, type BackgroundStyleProps, type BackwardsCompatibleReactElement, type BadgeSize, type BadgeVariant, type BannerInnerShadowOption, type BannerSize, type BannerVariant, type BorderRadius, type BorderRadiusConfig, type BorderStyleProps, type BorderWidth, type BorderWidthConfig, type BorderWidthWithElevation, type BottomSheetHeight, type BottomSheetSnapPoints, type BottomSheetVariant, type Breakpoint, type BreakpointValue, type BreakpointWithBase, type BreakpointsConfig, type ButtonPalette, type ButtonPaletteColor, type ButtonSize, type ButtonSpectrumColor, type ButtonVariant, type ButtonVariantFlat, type CheckboxSize, type CheckboxValue, type CheckboxVariant, type ChipSize, type ChipVariant, type ColorMode, type ColorModeConfig, type ColorModeForApp, type ColorsConfig, type ConfigurableComponentName, type CustomSizingStyleProps, type DataAttribute, type DeprecatedAlwaysPaletteAlias, type Display, type DividerVariant, type ElevationAlias, type ElevationBackgroundFillColor, type ElevationBorderColor, type ElevationConfig, type ElevationCustomInsetShadows, type ElevationCustomShadows, type ElevationGlobalRampConfig, type ElevationGlobalRampSettings, type ElevationLevel, type ElevationPreset, type ElevationSurfaceColor, type ExtractUrlFromFontFaceRule, type Flex, type FlexAlignContent, type FlexAlignItems, type FlexAlignSelf, type FlexBasis, type FlexDirection, type FlexGrow, type FlexJustifyContent, type FlexShrink, type FlexStyleProps, type FlexWrap, type FocusRingColor, type FocusRingConfig, type FocusRingModeConfig, type FocusRingOffset, type FocusRingWidth, type FontAlias, type FontConfig, type FontCssVar, type FontFamilyConfig, type FontSize, type FontSizeConfig, type FontSlantConfig, type FontType, type FontWeightConfig, type FontWeightDescriptive, type FontWeightNumeric, type FontWidthConfig, type ForegroundColor, type ForegroundPalette, type ForegroundPaletteAlias, type GenericIconComponent, type GlobalDefaultsConfig, type HighContrastMode, type Hue, type HueStep, type IconButtonSize, type IconPixelSize, type IconPropsWithSVGProps, type IconSize, type IconSizeConfig, type IconSlotRenderProps, type IconVariant, type ImagePropsWithImgProps, type ImageStyleProps, type ImgElementProps, type InputSize, type LayoutStyleProps, type LineClampAlias, type LineColor, type LineHeight, type LineHeightConfig, type LinePalette, type LinePaletteAlias, type LinkTextVariant, type LinkVariant, type LinkableValue, type MaxLengthArray, type ModalSize, type ModalVariant, type Modes, type MotionConfig, type MotionCssVar, type MotionSpringConfig, type MotionSpringConfigOptions, type MotionVariant, type MotionVariantSpeed, type MotionVariantValues, type NestedBorderRadiusStyleProps, type OpacityStep, type Overflow, type PaddleNavOrientation, type PaddleNavSize, type PaddleNavVariant, type PaginationEllipsisPlacement, type PaginationSize, type PaginationVariant, type PaginationVisibleItem, type Palette, type PaletteConfig, type PaletteType, type PaletteValue, type Percentage, type PercentageUnit, type PixelsUnit, type PlatformMode, type PopoverPlacement, type PopoverSize, type PopoverVariant, type Position, type PropertyToPaletteAliasMap, type RGBAUnit, type RGBColorValue, type RGBUnit, type RadioSize, type RadioValue, type RadioVariant, type RegionMode, type RemsUnit, type SVGElementProps, type ScaleConfig, type ScaleEffect, type ScaleMode, type ScaleModeConfig, type ScaleModeForApp, type ShadowAlwaysColor, type ShadowColor, type ShadowColorConfig, type ShadowConfig, type ShadowOffset, type ShadowOpacity, type ShadowPalette, type ShadowPaletteAlias, type ShadowPaletteColor, type ShadowPreset, type ShadowSpectrumColor, type ShadowSpreadRadius, type ShadowStyleProps, type ShadowType, type ShadowTypeConfig, type ShadowVariant, type ShadowVariantConfig, type ShadowVariantInvert, type ShadowVariantWithElevation, type ShadowVariantWithInvert, type SharedPaletteAlias, type SizeStyleProps, type SpacingAlias, type SpacingConfig, type SpacingStyleProps, type SpectrumColor, type SpectrumConfig, type SpectrumRGB, type SpectrumValue, type SpectrumValueEntry, type StateStyleProps, type StyleProps, type SwitchSize, type TShirtSize, type TShirtSizeCommon, type TextDecorationLine, type TextProperty, type TextStyleProps, type TextTransform, type TextTransformConfig, type TextVariant, type TextVariantTypography, type TextVariantUi, type TextVariantWithoutEmphasized, type ToastPosition, type ToastSize, type ToastVariant, type TooltipPlacement, type TooltipSize, type TooltipVariant, type TransitionDelay, type TransitionDuration, type TransitionTiming, type TypographyConfig, type TypographyResponsiveProperty, type TypographyStyle, type TypographyStyleProperty, type TypographyUnitValue, type UdsCssVar, type UnitlessUnit, type UniversalAvatarBaseProps, type UniversalAvatarIconProps, type UniversalAvatarImageProps, type UniversalAvatarProps, type UniversalAvatarTextProps, type UniversalBadgeProps, type UniversalBannerProps, type UniversalBottomSheetContentProps, type UniversalBottomSheetHeaderProps, type UniversalBottomSheetProps, type UniversalBoxProps, type UniversalButtonProps, type UniversalCheckboxProps, type UniversalChipBaseProps, type UniversalChipButtonProps, type UniversalChipDismissibleProps, type UniversalChipLinkProps, type UniversalChipProps, type UniversalChipToggleProps, type UniversalDividerProps, type UniversalFormLabelProps, type UniversalIconButtonProps, type UniversalIconProps, type UniversalIconSlot, type UniversalImageProps, type UniversalInputProps, type UniversalLinkProps, type UniversalMenuItemProps, type UniversalModalActionsProps, type UniversalModalContentProps, type UniversalModalDescriptionProps, type UniversalModalProps, type UniversalModalTitleProps, type UniversalPaddleButtonProps, type UniversalPaddleNavContentProps, type UniversalPaddleNavProps, type UniversalPaginationItemProps, type UniversalPaginationLinkProps, type UniversalPaginationNextProps, type UniversalPaginationNumbersProps, type UniversalPaginationPrevProps, type UniversalPaginationProps, type UniversalPopoverContentProps, type UniversalPopoverProps, type UniversalPopoverTriggerProps, type UniversalPressableProps, type UniversalRadioGroupProps, type UniversalRadioProps, type UniversalStackProps, type UniversalSwitchProps, type UniversalTabListProps, type UniversalTabPanelProps, type UniversalTabProps, type UniversalTabsProps, type UniversalTabsVariant, type UniversalTextProps, type UniversalToastProps, type UniversalTokensConfigAutoBase, type UniversalTokensConfigBase, type UniversalTokensConfigGeneric, type UniversalTooltipContentProps, type UniversalTooltipProps, type UniversalTooltipTriggerProps };