@yahoo/uds 3.58.2-beta.1 → 3.59.0-beta.1

package/src/components/Text.tsx

@@ -0,0 +1,272 @@
+import type { UniversalTextProps } from '@yahoo/uds/tokens';
+import type { Ref } from 'react';
+import { forwardRef } from 'react';
+
+import { getStyles } from '../styles/styler';
+import { createSlot } from '../utils/createSlot';
+
+const Slot = createSlot<React.ComponentType<HtmlParagraphProps>>();
+
+type HtmlParagraphProps = Omit<React.HTMLAttributes<HTMLParagraphElement>, 'color'>;
+type TextElementTagName =
+  | 'h1'
+  | 'h2'
+  | 'h3'
+  | 'h4'
+  | 'h5'
+  | 'p'
+  | 'strong'
+  | 'span'
+  | 'label'
+  | 'li'
+  | 'sup';
+
+type ColorWithInherit = Exclude<UniversalTextProps['color'], undefined> | 'inherit';
+type VariantWithInherit = Exclude<UniversalTextProps['variant'], undefined> | 'inherit';
+
+type TextProps<TagName extends TextElementTagName = TextElementTagName> = {
+  /** Ref passed to the inner container. */
+  ref?: Ref<HTMLElement>;
+  /** Changes the HTML tag used to render text. Uses the most appropriate semantic tag based on the text style variant. */
+  as?: TagName;
+
+  // Add inherit option for configured component composition.
+  variant?: VariantWithInherit;
+  color?: ColorWithInherit;
+} & JSX.IntrinsicElements[TagName] &
+  Omit<UniversalTextProps, 'variant' | 'color'>;
+
+const asMap: Record<VariantWithInherit, TextElementTagName> = {
+  display1: 'h1',
+  display2: 'h1',
+  display3: 'h1',
+  title1: 'h1',
+  title2: 'h2',
+  title3: 'h3',
+  title4: 'h4',
+  headline1: 'h5',
+  body1: 'p',
+  label1: 'p',
+  label2: 'p',
+  label3: 'p',
+  label4: 'p',
+  caption1: 'p',
+  caption2: 'p',
+  legal1: 'p',
+  'display1/emphasized': 'h1',
+  'display2/emphasized': 'h1',
+  'display3/emphasized': 'h1',
+  'title1/emphasized': 'h1',
+  'title2/emphasized': 'h2',
+  'title3/emphasized': 'h3',
+  'title4/emphasized': 'h4',
+  'headline1/emphasized': 'h5',
+  'body1/emphasized': 'p',
+  'label1/emphasized': 'p',
+  'label2/emphasized': 'p',
+  'label3/emphasized': 'p',
+  'label4/emphasized': 'p',
+  'caption1/emphasized': 'p',
+  'caption2/emphasized': 'p',
+  'legal1/emphasized': 'p',
+  ui1: 'span',
+  ui2: 'span',
+  ui3: 'span',
+  ui4: 'span',
+  ui5: 'span',
+  ui6: 'span',
+  'ui1/emphasized': 'span',
+  'ui2/emphasized': 'span',
+  'ui3/emphasized': 'span',
+  'ui4/emphasized': 'span',
+  'ui5/emphasized': 'span',
+  'ui6/emphasized': 'span',
+  inherit: 'p',
+} as const;
+
+/**
+ * **💬 A text element that can be used to display text**
+ *
+ * @description
+ * By default, the `Text` component uses text primary color and selects the
+ * correct font, weight, and leading. It also choices appropriate semantic
+ * HTML element based on the `variant` prop. For example, `body1` will use a
+ * `<p>` tag, `title1` uses an `<h1>`, etc. This behavior can be overridden
+ * with the `as` prop.
+ *
+ *
+ * @example
+ * ```tsx
+ * import { Text } from '@yahoo/uds';
+ *
+ * <Text variant="body1" color="primary">
+ *   Text goes here
+ * </Text>
+ * ```
+ *
+ * @usage
+ * - Use `Text` to display text in your app.
+ * - Use `variant` to change the size and weight of the text.
+ * - Use `color` to change the color of the text.
+ * - Use `as` to change the HTML tag used to render the text.
+ *
+ * @see The {@link https://uds.build/docs/components/text Text Docs} for more info
+ */
+const Text = forwardRef(function Text(
+  {
+    className,
+    asChild,
+    // text props
+    color = 'primary',
+    variant = 'body1',
+    as = asMap[variant],
+    fontFamily,
+    fontSize,
+    fontWeight,
+    lineHeight,
+    textTransform,
+    textAlign,
+    // background
+    backgroundColor,
+    // border
+    borderRadius,
+    borderTopStartRadius,
+    borderTopEndRadius,
+    borderBottomStartRadius,
+    borderBottomEndRadius,
+    borderColor,
+    borderStartColor,
+    borderEndColor,
+    borderTopColor,
+    borderBottomColor,
+    borderWidth,
+    borderVerticalWidth,
+    borderHorizontalWidth,
+    borderStartWidth,
+    borderEndWidth,
+    borderTopWidth,
+    borderBottomWidth,
+    // flex
+    alignContent,
+    alignItems,
+    alignSelf,
+    flex,
+    flexDirection,
+    flexGrow,
+    flexShrink,
+    flexWrap,
+    justifyContent,
+    flexBasis,
+    // layout
+    display,
+    overflow,
+    overflowX,
+    overflowY,
+    position,
+    // spacing
+    spacing,
+    spacingHorizontal,
+    spacingVertical,
+    spacingBottom,
+    spacingEnd,
+    spacingStart,
+    spacingTop,
+    offset,
+    offsetVertical,
+    offsetHorizontal,
+    offsetBottom,
+    offsetEnd,
+    offsetStart,
+    offsetTop,
+    columnGap,
+    rowGap,
+    // rest
+    ...props
+  }: TextProps,
+  ref: React.ForwardedRef<HTMLElement>,
+) {
+  const textStyles: Parameters<typeof getStyles>[0] = {
+    ...(color && color !== 'inherit' ? { color } : {}),
+    ...(variant && variant !== 'inherit'
+      ? {
+          fontFamily: fontFamily ?? variant,
+          fontSize: fontSize ?? variant,
+          fontWeight: fontWeight ?? variant,
+          lineHeight: lineHeight ?? variant,
+          textTransform: textTransform ?? variant,
+        }
+      : {}),
+    textAlign,
+  };
+
+  const classNames = getStyles({
+    className,
+    // text styles
+    ...textStyles,
+    // background
+    backgroundColor,
+    // border
+    borderRadius,
+    borderTopStartRadius,
+    borderTopEndRadius,
+    borderBottomStartRadius,
+    borderBottomEndRadius,
+    borderColor,
+    borderStartColor,
+    borderEndColor,
+    borderTopColor,
+    borderBottomColor,
+    borderWidth,
+    borderVerticalWidth,
+    borderHorizontalWidth,
+    borderStartWidth,
+    borderEndWidth,
+    borderTopWidth,
+    borderBottomWidth,
+    // flex
+    alignContent,
+    alignItems,
+    alignSelf,
+    flex,
+    flexDirection,
+    flexGrow,
+    flexShrink,
+    flexWrap,
+    justifyContent,
+    flexBasis,
+    // layout
+    display,
+    overflow,
+    overflowX,
+    overflowY,
+    position,
+    // spacing
+    spacing,
+    spacingHorizontal,
+    spacingVertical,
+    spacingBottom,
+    spacingEnd,
+    spacingStart,
+    spacingTop,
+    offset,
+    offsetVertical,
+    offsetHorizontal,
+    offsetBottom,
+    offsetEnd,
+    offsetStart,
+    offsetTop,
+    columnGap,
+    rowGap,
+  });
+
+  const Comp = asChild ? Slot : as;
+
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore this is fine
+  return <Comp className={classNames} ref={ref} {...props} />;
+});
+
+// Need to re-set this because of the forwardRef wrapper
+Text.displayName = 'Text';
+
+export { Text, type TextProps };

package/src/components/VStack.tsx

@@ -0,0 +1,53 @@
+import type { UniversalStackProps } from '@yahoo/uds/tokens';
+import { forwardRef } from 'react';
+
+import { intersperseReactChildren } from '../utils/intersperse';
+import type { DivProps } from './Box';
+import { Box } from './Box';
+
+type VStackProps = UniversalStackProps & DivProps;
+
+/**
+ * **🥞 A layout component that arranges its children in rows using flexbox**
+ *
+ * @description
+ * VStack is a layout component that arranges its children in rows using [flexbox](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Flexbox)
+ * and can be used to compose larger layouts. VStack is similar to [Box](./box) but provides additional features like a `gap` property to
+ * add spacing between children.
+ *
+ * @example
+ * ```tsx
+ * import { VStack, Text } from '@yahoo/uds';
+ *
+ * <VStack gap="6">
+ *   <Text variant="body1" color="primary">First</Text>
+ *   <Text variant="body1" color="primary">Second</Text>
+ *   <Text variant="body1" color="primary">Third</Text>
+ * </VStack>
+ * ```
+ *
+ * @usage
+ * - Create a column of items, optionally with gaps between.
+ * - Create rows that are sized to their content (height only). By default each child will fill the width of the VStack.
+ * - Create rows that fill the available space within the parent container.
+ * - Create rows of proportionate size to each other (also known as a ratio-based layout).
+ *
+ * @see The {@link https://uds.build/docs/components/v-stack VStack Docs} for more info
+ *
+ * @related [Box](https://uds.build/docs/components/box), [HStack](https://uds.build/docs/components/h-stack)
+ **/
+const VStack = forwardRef<HTMLDivElement, VStackProps>(function VStack(
+  { gap, children, separator, ...props }: VStackProps,
+  ref,
+) {
+  return (
+    <Box ref={ref} flexDirection="column" columnGap={gap} rowGap={gap} {...props}>
+      {separator ? intersperseReactChildren(children, separator) : children}
+    </Box>
+  );
+});
+
+// Need to re-set this because of the forwardRef wrapper
+VStack.displayName = 'VStack';
+
+export { VStack, type VStackProps };

package/src/components/client/AnimateHeightChange.tsx

@@ -0,0 +1,50 @@
+import type { MotionConfigProps } from 'motion/react';
+import { m } from 'motion/react';
+import type { PropsWithChildren } from 'react';
+import { useEffect, useRef, useState } from 'react';
+
+import type { SpringMotionConfigProps } from './SpringMotionConfig';
+import { SpringMotionConfig } from './SpringMotionConfig';
+
+interface AnimateHeightChangeProps extends PropsWithChildren {
+  reduceMotion?: MotionConfigProps['reducedMotion'];
+  layoutVariant?: SpringMotionConfigProps['layoutVariant'];
+}
+
+const AnimateHeightChange = ({
+  children,
+  reduceMotion,
+  layoutVariant,
+}: AnimateHeightChangeProps) => {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const [height, setHeight] = useState<number | 'auto'>('auto');
+
+  useEffect(() => {
+    if (ref.current) {
+      const observer = new ResizeObserver((entries) => {
+        setHeight(entries[0].contentRect.height);
+      });
+      observer.observe(ref.current);
+
+      return () => {
+        observer.disconnect();
+      };
+    }
+  }, []);
+
+  return (
+    <SpringMotionConfig reducedMotion={reduceMotion} layoutSpeed="4" layoutVariant={layoutVariant}>
+      <m.div
+        className="overflow-hidden"
+        style={{ height, opacity: 0 }}
+        animate={{ height, opacity: 1 }}
+      >
+        <div ref={ref}>{children}</div>
+      </m.div>
+    </SpringMotionConfig>
+  );
+};
+
+AnimateHeightChange.displayName = 'AnimateHeightChange';
+
+export { AnimateHeightChange, type AnimateHeightChangeProps };

package/src/components/client/Avatar/Avatar.tsx

@@ -0,0 +1,31 @@
+import type { AvatarImageProps } from './AvatarImage';
+import { AvatarImage } from './AvatarImage';
+
+type AvatarProps = AvatarImageProps;
+
+/**
+ * **👤 Avatar Component**
+ *
+ * @description The avatar component visually represents a person or an organization within an interface. It helps users quickly identify individuals or entities through images, icons, or text. Commonly used in user profiles, comments, and activity feeds, avatars create a recognizable and consistent visual identity across the system. With standardized sizes, variants, and configurable options, the component ensures flexibility while maintaining design cohesion and accessibility.
+ * @usage The Avatar component should be used whenever you need to visually represent a user's identity in your application. This includes places like profile headers, user lists, chat messages, and comment sections. It's ideal for providing a consistent visual cue for users, whether by displaying a profile image, generating initials from a name, or falling back to a default icon when no image is available.
+ * @param props - Combined Avatar props.
+ * @returns The Avatar element.
+ * @componentType Client component
+ * @example ```tsx
+ * import { Avatar } from '@yahoo/uds';
+ *
+ * <Avatar
+ *    src="https://images.unsplash.com/photo-1438761681033-6461ffad8d80?w=400"
+ *    alt="Jane Doe"
+ *    fallback="J"
+ * />
+ * ```
+ *
+ */
+const Avatar = (props: AvatarProps) => {
+  return <AvatarImage {...props} />;
+};
+
+Avatar.displayName = 'Avatar';
+
+export { Avatar, type AvatarProps };

package/src/components/client/Avatar/AvatarIcon.tsx

@@ -0,0 +1,103 @@
+import { Building, Person } from '@yahoo/uds-icons';
+import type { SvgIcon } from '@yahoo/uds-icons/types';
+import { useMemo } from 'react';
+
+import { cx, getStyles } from '../../../styles/styler';
+import type {
+  AvatarVariant,
+  IconPropsWithSVGProps,
+  UniversalAvatarIconProps,
+} from '../../../tokens';
+import { Box } from '../../Box';
+import { IconSlot } from '../../IconSlot';
+import {
+  buildAvatarRootClasses,
+  buildInlineSizeStyles,
+  DEFAULT_AVATAR_SIZE,
+  DEFAULT_AVATAR_VARIANT,
+} from './utils';
+
+/** Maps avatar variant to icon */
+// TODO: This should be configurable in the future
+const mapVariantToIcon: Record<AvatarVariant, SvgIcon> = {
+  primary: Person,
+  secondary: Building,
+};
+
+// Required because of: https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/69864
+type DataAttributes = {
+  [name: `data-${string}`]: string;
+};
+
+interface AvatarIconProps extends UniversalAvatarIconProps {
+  /** Props to be passed into various slots within the component. */
+  slotProps?: {
+    icon?: Partial<IconPropsWithSVGProps & DataAttributes>;
+  };
+}
+
+/**
+ * **AvatarIcon Component**
+ *
+ * Renders an Avatar with an icon representation.
+ *
+ * @param props - Props for icon variant.
+ * @returns The AvatarIcon element.
+ */
+const AvatarIcon = ({
+  size = DEFAULT_AVATAR_SIZE,
+  variant = DEFAULT_AVATAR_VARIANT,
+  customSize,
+  icon,
+  slotProps,
+  className,
+  ...props
+}: AvatarIconProps) => {
+  const classNames = useMemo(
+    () => ({
+      root: buildAvatarRootClasses(size, {
+        avatarIconVariantRoot: variant,
+        overflow: 'hidden',
+        className: cx('overflow-hidden', className),
+      }),
+
+      iconContainer: cx(
+        'w-full',
+        'h-full',
+        'shrink-0',
+        'overflow-hidden',
+        'text-center',
+        'inline-flex',
+        'justify-center',
+        'items-center',
+      ),
+
+      icon: getStyles({ avatarSizeIcon: size }),
+    }),
+    [className, size, variant],
+  );
+
+  const inlineStyles = useMemo(() => buildInlineSizeStyles(customSize), [customSize]);
+
+  const iconSvg = icon ?? mapVariantToIcon[variant ?? 'primary'];
+
+  return (
+    <Box className={classNames.root} style={inlineStyles.root} {...props}>
+      <Box className={classNames.iconContainer} style={inlineStyles.contents}>
+        <IconSlot
+          icon={iconSvg}
+          iconProps={{
+            variant: 'fill',
+            color: 'current',
+            ...slotProps?.icon,
+          }}
+          className={classNames.icon}
+        />
+      </Box>
+    </Box>
+  );
+};
+
+AvatarIcon.displayName = 'AvatarIcon';
+
+export { AvatarIcon, type AvatarIconProps };

package/src/components/client/Avatar/AvatarImage.tsx

@@ -0,0 +1,147 @@
+import { useEffect, useMemo, useState } from 'react';
+
+import { cx } from '../../../styles/styler';
+import type { ImagePropsWithImgProps, UniversalAvatarImageProps } from '../../../tokens';
+import { Box } from '../../Box';
+import { Image as UDSImage } from '../../Image';
+import type { AvatarIconProps } from './AvatarIcon';
+import { AvatarIcon } from './AvatarIcon';
+import type { AvatarTextProps } from './AvatarText';
+import { AvatarText } from './AvatarText';
+import {
+  buildAvatarRootClasses,
+  buildInlineSizeStyles,
+  DEFAULT_AVATAR_SIZE,
+  DEFAULT_AVATAR_VARIANT,
+} from './utils';
+
+// Required because of: https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/69864
+type DataAttributes = {
+  [name: `data-${string}`]: string;
+};
+
+interface AvatarImageProps extends UniversalAvatarImageProps {
+  /** Props to be passed into various slots within the component. */
+  slotProps?: {
+    image?: Partial<
+      Omit<ImagePropsWithImgProps, 'src' | 'srcSet' | 'alt' | 'className' | 'height' | 'width'> &
+        DataAttributes
+    >;
+  } & AvatarIconProps['slotProps'] &
+    AvatarTextProps['slotProps'];
+}
+
+/**
+ * **AvatarImage Component**
+ *
+ * Renders an Avatar with an image. If the image fails to load, it falls back first to
+ * a text representation (if a name or initials are provided) and then to an icon.
+ *
+ * @param props - Props for image variant.
+ * @returns The AvatarImage element.
+ */
+const AvatarImage = ({
+  size = DEFAULT_AVATAR_SIZE,
+  variant = DEFAULT_AVATAR_VARIANT,
+  src,
+  srcSet,
+  customSize,
+  alt,
+  abbreviationStrategy,
+  fallback,
+  className,
+  imageProps,
+  slotProps,
+  ...props
+}: AvatarImageProps) => {
+  const [loadingState, setLoadingState] = useState<'loading' | 'loaded' | 'error'>('loading');
+
+  useEffect(() => {
+    let mounted = true;
+    if (src || srcSet) {
+      const img = new Image();
+      img.onload = () => {
+        if (mounted) {
+          setLoadingState('loaded');
+        }
+      };
+      img.onerror = () => {
+        if (mounted) {
+          setLoadingState('error');
+        }
+      };
+      if (src) {
+        img.src = src;
+      }
+      if (srcSet) {
+        img.srcset = srcSet;
+      }
+    } else {
+      setLoadingState('error');
+    }
+    return () => {
+      mounted = false;
+    };
+  }, [src, srcSet]);
+
+  const classNames = useMemo(
+    () => ({
+      root: buildAvatarRootClasses(size, {
+        avatarImageVariantRoot: variant,
+        className: cx('overflow-hidden', className),
+      }),
+
+      contents: cx(
+        'w-full',
+        'h-full',
+        'shrink-0',
+        'text-center',
+        'inline-flex',
+        'justify-center',
+        'items-center',
+        'object-cover',
+      ),
+    }),
+    [className, size, variant],
+  );
+
+  const inlineStyles = useMemo(() => buildInlineSizeStyles(customSize), [customSize]);
+
+  if (loadingState === 'loaded') {
+    return (
+      <Box className={classNames.root} style={inlineStyles.root}>
+        <UDSImage
+          src={src}
+          srcSet={srcSet}
+          alt={alt}
+          className={classNames.contents}
+          style={inlineStyles.contents}
+          {...imageProps} // Deprecated
+          {...slotProps?.image}
+        />
+      </Box>
+    );
+  }
+
+  const sharedProps = { ...props, size, customSize, variant };
+
+  // On image error, try to render text avatar
+  if (fallback || alt) {
+    return (
+      <AvatarText
+        name={alt}
+        initials={fallback}
+        abbreviationStrategy={abbreviationStrategy}
+        slotProps={{ text: slotProps?.text }}
+        {...sharedProps}
+      />
+    );
+  }
+
+  // If no text data is available, render icon
+  return <AvatarIcon {...sharedProps} slotProps={{ icon: slotProps?.icon }} />;
+};
+
+AvatarImage.displayName = 'AvatarImage';
+
+export { AvatarImage, type AvatarImageProps };