@cdx-ui/components 0.2.3 → 0.2.4

package/docs/components/avatar/content.md

@@ -0,0 +1,368 @@
+# Avatar (https://design.candescent.com/docs/components/avatar)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=449-377), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-avatar--default)
+
+A compound component that displays an image, initials, or an icon fallback.
+
+```tsx
+import { Avatar } from '@cdx-ui/components';
+```
+
+## Basic
+
+Include `Avatar.Text` alongside `Avatar.Image` to provide a fallback while the image loads or if it fails.
+
+```tsx
+import { Avatar } from '@cdx-ui/components';
+
+export default function AvatarBasicDemo() {
+  return (
+    <Avatar size="xl" accessibilityLabel="Alex Morgan">
+      <Avatar.Image src="https://www.loremfaces.net/128/id/1.jpg" />
+      <Avatar.Text>Alex Morgan</Avatar.Text>
+    </Avatar>
+  );
+}
+```
+
+## Variants
+
+```tsx
+import { Avatar, Box, Text, type AvatarProps } from '@cdx-ui/components';
+import { Person } from '@cdx-ui/icons';
+
+const shapes = ['circle', 'rounded'] as const satisfies readonly NonNullable<
+  AvatarProps['shape']
+>[];
+
+export default function AvatarVariantsDemo() {
+  return (
+    <Box className="gap-4">
+      {shapes.map((shape) => (
+        <Box key={shape} className="gap-2">
+          <Text size="sm" color="secondary">
+            {shape}
+          </Text>
+          <Box className="flex-row items-center gap-4">
+            <Avatar variant="subtle" shape={shape} accessibilityLabel={`Subtle ${shape} avatar`}>
+              <Avatar.Text>Alex Morgan</Avatar.Text>
+            </Avatar>
+            <Avatar variant="solid" shape={shape} accessibilityLabel={`Solid ${shape} avatar`}>
+              <Avatar.Text>Alex Morgan</Avatar.Text>
+            </Avatar>
+            <Avatar
+              variant="subtle"
+              shape={shape}
+              accessibilityLabel={`Subtle ${shape} icon avatar`}
+            >
+              <Avatar.Icon as={Person} />
+            </Avatar>
+            <Avatar variant="solid" shape={shape} accessibilityLabel={`Solid ${shape} icon avatar`}>
+              <Avatar.Icon as={Person} />
+            </Avatar>
+          </Box>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## Colors
+
+```tsx
+import { Avatar, Box, Text, type AvatarProps } from '@cdx-ui/components';
+import { Person } from '@cdx-ui/icons';
+
+const colors = [
+  'brand',
+  'neutral',
+  'danger',
+  'warning',
+  'success',
+  'info',
+] as const satisfies readonly NonNullable<AvatarProps['color']>[];
+
+const variants = ['subtle', 'solid'] as const satisfies readonly NonNullable<
+  AvatarProps['variant']
+>[];
+
+const shapes = ['circle', 'rounded'] as const satisfies readonly NonNullable<
+  AvatarProps['shape']
+>[];
+
+export default function AvatarColorsDemo() {
+  return (
+    <Box className="gap-4">
+      {variants.map((variant) => (
+        <Box key={variant} className="gap-3">
+          <Text size="sm" color="secondary">
+            {variant}
+          </Text>
+          {shapes.map((shape) => (
+            <Box key={shape} className="gap-2">
+              <Text size="sm" color="secondary">
+                {shape}
+              </Text>
+              <Box className="flex-row flex-wrap items-center gap-3">
+                {colors.map((color) => (
+                  <Box
+                    key={`${variant}-${shape}-${color}`}
+                    className="flex-row items-center gap-1.5"
+                  >
+                    <Avatar
+                      variant={variant}
+                      color={color}
+                      shape={shape}
+                      accessibilityLabel={`${variant} ${shape} ${color} initials`}
+                    >
+                      <Avatar.Text>Alex Morgan</Avatar.Text>
+                    </Avatar>
+                    <Avatar
+                      variant={variant}
+                      color={color}
+                      shape={shape}
+                      accessibilityLabel={`${variant} ${shape} ${color} icon`}
+                    >
+                      <Avatar.Icon as={Person} />
+                    </Avatar>
+                  </Box>
+                ))}
+              </Box>
+            </Box>
+          ))}
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## Shapes
+
+Use `shape` to render a circle or a rounded square. `Avatar.Image` clips to the same geometry.
+
+```tsx
+import { Avatar, Box, Text, type AvatarProps } from '@cdx-ui/components';
+import { Person } from '@cdx-ui/icons';
+
+const shapes = ['circle', 'rounded'] as const satisfies readonly NonNullable<
+  AvatarProps['shape']
+>[];
+
+export default function AvatarShapesDemo() {
+  return (
+    <Box className="flex-row flex-wrap items-end gap-6">
+      {shapes.map((shape) => (
+        <Box key={shape} className="items-center gap-2">
+          <Box className="flex-row items-center gap-3">
+            <Avatar shape={shape} accessibilityLabel={`${shape} initials`}>
+              <Avatar.Text>Alex Morgan</Avatar.Text>
+            </Avatar>
+            <Avatar shape={shape} accessibilityLabel={`${shape} icon`}>
+              <Avatar.Icon as={Person} />
+            </Avatar>
+            <Avatar shape={shape} accessibilityLabel={`${shape} image`}>
+              <Avatar.Image src="https://www.loremfaces.net/128/id/1.jpg" />
+              <Avatar.Text>Alex Morgan</Avatar.Text>
+            </Avatar>
+          </Box>
+          <Text size="sm" color="secondary">
+            {shape}
+          </Text>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## Sizes
+
+```tsx
+import { Avatar, Box, Text, type AvatarProps } from '@cdx-ui/components';
+
+const sizes = ['2xs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl'] as const satisfies readonly NonNullable<
+  AvatarProps['size']
+>[];
+
+const shapes = ['circle', 'rounded'] as const satisfies readonly NonNullable<
+  AvatarProps['shape']
+>[];
+
+export default function AvatarSizesDemo() {
+  return (
+    <Box className="gap-4">
+      {shapes.map((shape) => (
+        <Box key={shape} className="gap-2">
+          <Text size="sm" color="secondary">
+            {shape}
+          </Text>
+          <Box className="flex-row flex-wrap items-end gap-4">
+            {sizes.map((size) => (
+              <Box key={size} className="items-center gap-2">
+                <Avatar
+                  size={size}
+                  shape={shape}
+                  accessibilityLabel={`${shape} avatar size ${size}`}
+                >
+                  <Avatar.Text>Alex Morgan</Avatar.Text>
+                </Avatar>
+                <Text size="sm" color="secondary">
+                  {size}
+                </Text>
+              </Box>
+            ))}
+          </Box>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## Fallbacks
+
+`Avatar.Text` derives up to two initials from a name. Use `Avatar.Icon` for a generic fallback.
+
+```tsx
+import { Avatar, Box, Text, type AvatarProps } from '@cdx-ui/components';
+import { Person } from '@cdx-ui/icons';
+
+const shapes = ['circle', 'rounded'] as const satisfies readonly NonNullable<
+  AvatarProps['shape']
+>[];
+
+export default function AvatarFallbacksDemo() {
+  return (
+    <Box className="gap-4">
+      {shapes.map((shape) => (
+        <Box key={shape} className="gap-2">
+          <Text size="sm" color="secondary">
+            {shape}
+          </Text>
+          <Box className="flex-row items-center gap-4">
+            <Avatar size="lg" shape={shape} accessibilityLabel={`${shape} initials fallback`}>
+              <Avatar.Text>Alex Morgan</Avatar.Text>
+            </Avatar>
+            <Avatar size="lg" shape={shape} accessibilityLabel={`${shape} icon fallback`}>
+              <Avatar.Icon as={Person} />
+            </Avatar>
+          </Box>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## With badge
+
+Wrap an avatar with `Badge` to display a status indicator or notification count.
+
+```tsx
+import { Avatar, Badge, Box, Text, type AvatarProps } from '@cdx-ui/components';
+
+const shapes = ['circle', 'rounded'] as const satisfies readonly NonNullable<
+  AvatarProps['shape']
+>[];
+
+export default function AvatarStatusDemo() {
+  return (
+    <Box className="gap-4">
+      {shapes.map((shape) => {
+        const overlap = shape === 'circle' ? 'circular' : 'rectangular';
+
+        return (
+          <Box key={shape} className="gap-2">
+            <Text size="sm" color="secondary">
+              {shape}
+            </Text>
+            <Box className="flex-row items-center gap-6">
+              <Badge variant="dot" color="success" placement="bottom-end" overlap={overlap}>
+                <Avatar
+                  size="xl"
+                  shape={shape}
+                  accessibilityLabel={`Alex Morgan, online, ${shape}`}
+                >
+                  <Avatar.Image src="https://www.loremfaces.net/128/id/2.jpg" />
+                  <Avatar.Text>Alex Morgan</Avatar.Text>
+                </Avatar>
+              </Badge>
+              <Badge
+                label={3}
+                color="danger"
+                placement="top-end"
+                overlap={overlap}
+                accessibilityLabel="3 notifications"
+              >
+                <Avatar size="xl" shape={shape} accessibilityLabel={`Sofia Rivera, ${shape}`}>
+                  <Avatar.Image src="https://www.loremfaces.net/128/id/4.jpg" />
+                  <Avatar.Text>Sofia Rivera</Avatar.Text>
+                </Avatar>
+              </Badge>
+            </Box>
+          </Box>
+        );
+      })}
+    </Box>
+  );
+}
+```
+
+## API
+
+### Avatar
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `size?` | `'2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| null` | — | — |
+| `variant?` | `'subtle' \| 'solid'` | `'subtle'` | Visual style variant. |
+| `color?` | `'neutral' \| 'brand' \| 'danger' \| 'warning' \| 'success' \| 'info'` | `'brand'` | Color theme applied to the avatar surface and fallback content. |
+| `shape?` | `'circle' \| 'rounded'` | `'circle'` | Geometry of the avatar root and loaded image. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props). Defaults to an image accessibility role; provide an `accessibilityLabel` that identifies the person or entity.
+
+## Sub-components
+
+### Avatar.Image
+
+Displays an image when it loads successfully. If the image is unavailable or fails to load, the fallback content remains visible.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `src?` | `string` | — | A string representing the resource identifier for the image. Similar to src from HTML. See https://reactnative.dev/docs/image#src |
+| `source?` | `ImageSourcePropType` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ImageProps`](https://reactnative.dev/docs/image#props). Pass either a URI string to `src` or an `ImageSourcePropType` to `source`.
+
+### Avatar.Text
+
+Text fallback shown until an image loads successfully or when no image is available. A one- or two-character string is uppercased as-is; longer names become the first letter of each word, up to two characters.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | Name or initials. One or two characters are uppercased as-is. Longer text uses the first letter of each word, up to two characters. |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Avatar.Icon
+
+Icon fallback shown until an image loads successfully or when no image is available.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Utility classes for size (`size-*`) and placement, merged after the defaults. |
+| `filled?` | `boolean` | — | When `true`, renders the filled variant of the icon (if available). Defaults to `false` (outlined). |
+| `size?` | `string \| number` | — | Width and height of the icon, in pixels or any SVG length. The bare icon renders at 24 when omitted. |
+| `data-testid?` | `string` | — | Test identifier forwarded to the rendered SVG. |
+| `as` | `ForgeIcon` | — | The `@cdx-ui/icons` component to render. |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all `ForgeIconProps` (react-native-svg `SvgProps` plus `filled` and `size`).

package/docs/components/avatar/design.md

@@ -0,0 +1,202 @@
+# Avatar — Design (https://design.candescent.com/docs/components/avatar)
+
+## Usage
+
+**Common alternative names**: Profile photo
+
+---
+
+## Anatomy
+
+An avatar is a shaped container with content inside – an image, letters, or an icon.
+
+**Anatomy\_avatar**
+
+1. **Container**: The avatar’s container can be a circle or a square with rounded corners.
+2. **Image**: The user’s profile picture or other image. When an image is provided, it fills the container.
+3. **Background fill**: When an image is not provided, the avatar should have a solid background color.
+4. **Text**: Text can be provided instead of an image, or as a fallback for when no image is available for the user. Commonly the user’s initials.
+5. **Icon**: An icon can be provided instead of an image. Useful for categorizing or emphasizing an icon.
+
+### Variant
+
+The **variant** property controls the shape of the avatar’s container. The avatar comes in 2 variants: **Circular**, and **Rounded**.
+
+- **Circular**
+
+  The avatar’s container is a perfect circle. This is our recommended variant for most use cases.
+- **Rounded**
+
+  The avatar’s container is a square with rounded corners.
+
+### Type
+
+An avatar supports 3 types of content: an **Image**, **Text**, or an **Icon**. The **Type** property does not exist in code, but is included in Figma as a shortcut for swapping out the content types.
+
+- **Type: Image**
+
+  The user’s profile picture or other image. When an image is provided, it fills the container.
+- **Type: Text**
+
+  Text content centered inside the container, typically one or two characters. Must have a solid background color.
+- **Type: Icon**
+
+  A single icon centered inside the container. Must have a solid background color.
+
+### **Size**
+
+Avatars are available in 7 sizes: 2XS, XS, Small, Medium, Large, XL, and 2XL. Size should be considered for visual balance and layout needs; larger avatars will draw more attention while smaller sizes support denser views. The default avatar size is Medium (32 × 32 px).
+
+- **Size: 2xs**
+
+  2XS avatars are 12 × 12 px. This size is typically used in compact components such as chips.
+- **Size: Xs**
+
+  XS avatars are 18 × 18 px. This size is commonly used in components like chips and other compact patterns.
+- **Size: Small**
+
+  Small avatars are 24 × 24 px. This size works well in dense layouts where a slightly larger presence than XS is needed without drawing too much attention.
+- **Size: Medium**
+
+  Medium avatars are 32 × 32 px. This is the default size and works well for most layouts.
+- **Size: Large**
+
+  Large avatars are 40 × 40 px. This size increases visibility and draws more attention.
+- **Size: Xlarge**
+
+  XL avatars are 48 × 48 px. This size is useful in layouts where the avatar plays a more prominent role.
+- **Size: 2xl**
+
+  2XL avatars are 56 × 56 px. This size is used in high-emphasis contexts such as profile headers.
+
+### Color
+
+When an image is not provided, a solid background color is required to display the fallback content (text or icon) on top of. By default, the avatar will use a light background with dark text. However, any colors can be utilized as long as the content meets a **≥ 4.5:1** color contrast ratio with the background.
+
+- **Default**
+
+  Light background (`color.surface.tertiary`) with dark content (`color.content.primary`).
+
+#### **Preferred color combinations**
+
+Below are our preferred color combinations for avatars.
+
+- **Strong**
+
+  Strong background color with contrasting content.
+
+  Example: `color.content.danger-on-strong` on `color.surface.danger.strong`
+- **Subtle**
+
+  Subtle background color with contrasting content.
+
+  Example: `color.content.danger-on-subtle` on `color.surface.danger.subtle`
+
+**⭐ Tip:** Each of these suggestions will work with the following palettes: `neutral`, `action`, `danger`, `warning`, `success`, and `info`.
+
+---
+
+Usage
+
+### When to use
+
+> [!TIP]
+>
+> **Represent the active user or business**
+>
+> - ex: In the top bar of an app, an avatar can indicate what account is currently logged in to the app
+> - ex: In an organization selector, an avatar can indicate which organization is selected
+
+> [!TIP]
+>
+> **Anchor content to a specific user, account, business, or entity**
+>
+> - ex: In a social media app, an avatar helps identify the user who posted the content
+> - ex: In a chat or messaging setting, an avatar helps identify who is speaking in the conversation
+
+> [!TIP]
+>
+> **Associate an item with a category, classification, or status**
+>
+> - ex: In a banking app, avatars can be used to identify the merchant associated with each transaction
+> - ex: In a budgeting app, icon avatars can be used to show what category each transaction belongs to
+
+### When not to use
+
+> [!CAUTION]
+>
+> **Decorations or illustrations**
+>
+> - ex: Wrapping a decorative icon inside an avatar just to add extra visual emphasis
+
+### Examples
+
+#### **Account entry points**
+
+Avatars can serve as entry points to an account menus, account pages, or user profiles.
+
+_usage\_examples\_account\_01-ex_
+
+#### **Conversations**
+
+In realtime conversations such as a chat, phone call, or video chat, an avatar helps identify the user or business who is currently speaking.
+
+_usage\_examples\_conversations\_01-ex_
+
+In asynchronous conversations such as an email or forum post, an avatar helps identify the sender or author of the message.
+
+_usage\_examples\_conversations\_02-ex_
+
+#### **Lists and tables**
+
+Avatars are also commonly found in lists and tables. They can help distinguish between users, businesses, or categories.
+
+_usage\_examples\_lists\_01-ex_
+
+### **Choosing colors**
+
+#### **Use a consistent color combo**
+
+Choose a color palette for your avatars and use it consistently across your experience. We recommend choosing one of our [preferred color combinations](https://design.candescent.com/docs/components/avatar/content.md). If using multiple colors, keep them within the same palette, such as all strong or all subtle options. Mixing palettes may create visual inconsistency or make some avatars feel more prominent than others.
+
+- **Do:** Use the same color combination throughout your app, and especially within the same section.
+- **Don't:** Don’t mix color combinations within the same section. In this example, the email from Malachi ends up looking more important than the others.
+
+---
+
+## **Behavior**
+
+### **Fallback rendering**
+
+When using image avatars, there may be instances where an image is not available for every avatar. This could be because a user has not uploaded a profile picture, or because there was an error retrieving the image from the server. As a fallback, **text** or an **icon** should be provided.
+
+- **Text fallback**
+
+  `<Avatar.Text>John Smith</Avatar.Text>`
+- **Icon fallback**
+
+  `<Avatar.Icon as={Person} />`
+- **No fallback specified**
+
+  When no fallback is specified, the avatar will be empty. Avoid this scenario.
+
+A [study from Yale University](https://cyberpsychology.eu/article/view/6281) found that users are more likely to interpret the typical “person” icon as a man than a woman. As such, we recommend always defining fallback text instead of using an icon when representing people.
+
+### Text rendering
+
+Avatar text will show **initials** that are derived from the string of text. For example:
+
+- "John Smith" ➡️ **JS**
+- "John" ➡️ **J**
+- "John Smith Jr." ➡️ **JS**
+- "John Michael Smith" ➡️ **JM**
+
+## Content
+
+## **Initials**
+
+When an image is not available for the user, use a text avatar. The text should either be the beginning letter of their first name, or the beginning letter of their first and last name. For example, “John Smith” would either be “J” or “JS”.
+
+- **Do:** Use a single initial or double initials. Be consistent, unless the user only has a first name.
+- **Don't:** Don’t include a third letter, even if the user has a middle name.
+- **Don't:** Don’t spell out names inside the avatar, even if some fit within the space.