@yahoo/uds 3.97.0 → 3.98.0

package/dist/types/dist/index.d.ts

@@ -417,15 +417,21 @@ interface SizeStyleProps {
 }
 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;
 }
 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;
 }
 /**
@@ -433,9 +439,13 @@ interface UniversalTextProps extends PropsWithChildren, TextStyleProps, Universa
  * @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'>;
@@ -448,188 +458,308 @@ type BackwardsCompatibleReactElement = null | undefined | ReactElement;
  */
 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;
 }
 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 value submitted with form data. @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 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' | 'layerClassNames'> {
+  /** 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' | 'layerClassNames'> {
+  /** 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 Omit<UniversalChipBaseProps, 'layerClassNames'> {
+  /** 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 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;
+  /** Render prop slots for customizing internal elements. */
   slots?: {
     root?: (props: HTMLAttributes<any> & {
       ref?: Ref<any>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@yahoo/uds",
   "description": "Yahoo Universal System",
-  "version": "3.97.0",
+  "version": "3.98.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",