@cdx-ui/components 0.2.3 → 0.2.4

package/docs/components/heading/content.md

@@ -0,0 +1,55 @@
+# Heading (https://design.candescent.com/docs/components/heading)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=399-3385), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-heading--default)
+
+`Heading` pairs Forge UI heading styles with the corresponding accessible heading level.
+
+```tsx
+import { Heading } from '@cdx-ui/components';
+```
+
+## Basic
+
+```tsx
+import { Heading } from '@cdx-ui/components';
+
+export default function HeadingBasicDemo() {
+  return <Heading>Account overview</Heading>;
+}
+```
+
+## Sizes
+
+Each `size` maps to a heading level: `xl` to level 1, `lg` to level 2, through `xs` at level 5.
+
+```tsx
+import { Box, Heading, type HeadingProps } from '@cdx-ui/components';
+
+const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const satisfies readonly NonNullable<
+  HeadingProps['size']
+>[];
+
+export default function HeadingSizesDemo() {
+  return (
+    <Box className="gap-4">
+      {SIZES.map((size) => (
+        <Heading key={size} size={size}>
+          {size} heading
+        </Heading>
+      ))}
+    </Box>
+  );
+}
+```
+
+## API
+
+### Heading
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the heading's own styles. |
+| `children?` | `React.ReactNode` | — | Heading text. |
+| `size?` | `'xl' \| 'lg' \| 'md' \| 'sm' \| 'xs' \| null` | `'lg'` | Heading typography style. Also sets the accessibility heading level: `xl` is level 1 through `xs` at level 5. |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props). The default `size` is `lg`, which uses heading level 2.

package/docs/components/icon/content.md

@@ -0,0 +1,190 @@
+# Icon (https://design.candescent.com/docs/components/icon)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=397-33), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-icon--default)
+
+A wrapper around Forge UI icons that adds Uniwind `className` support and themed defaults.
+
+```tsx
+import { Icon } from '@cdx-ui/components';
+import { Home } from '@cdx-ui/icons';
+```
+
+Browse the complete set of available glyphs in the [icon explorer](https://design.candescent.com/docs/foundations/expressions/icons/content.md).
+
+## Basic
+
+Pass an icon component from `@cdx-ui/icons` to the required `as` prop.
+
+```tsx
+import { Icon } from '@cdx-ui/components';
+import { Home } from '@cdx-ui/icons';
+
+export default function IconBasicDemo() {
+  return <Icon as={Home} className="size-6" accessibilityLabel="Home" />;
+}
+```
+
+## Sizes
+
+Use `size-*` utilities to set both SVG dimensions. The default `size-5` renders at 20 pixels.
+
+```tsx
+import { Box, Icon, Text } from '@cdx-ui/components';
+import { Home } from '@cdx-ui/icons';
+
+export default function IconSizesDemo() {
+  return (
+    <Box className="flex-row items-end gap-5">
+      <Box className="items-center gap-2">
+        <Icon as={Home} className="size-4" />
+        <Text size="sm" color="secondary">
+          16
+        </Text>
+      </Box>
+      <Box className="items-center gap-2">
+        <Icon as={Home} className="size-5" />
+        <Text size="sm" color="secondary">
+          20
+        </Text>
+      </Box>
+      <Box className="items-center gap-2">
+        <Icon as={Home} className="size-6" />
+        <Text size="sm" color="secondary">
+          24
+        </Text>
+      </Box>
+      <Box className="items-center gap-2">
+        <Icon as={Home} className="size-8" />
+        <Text size="sm" color="secondary">
+          32
+        </Text>
+      </Box>
+      <Box className="items-center gap-2">
+        <Icon as={Home} className="size-10" />
+        <Text size="sm" color="secondary">
+          40
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Colors
+
+Use `color` to select a semantic content color. It maps to the matching theme-aware `text-content-*` token, so prefer it over a color class.
+
+```tsx
+import { Box, Icon, Text, type IconProps } from '@cdx-ui/components';
+import { Favorite } from '@cdx-ui/icons';
+
+const COLORS = [
+  'primary',
+  'secondary',
+  'tertiary',
+  'action',
+  'danger',
+  'warning',
+  'success',
+  'info',
+] as const satisfies readonly NonNullable<IconProps['color']>[];
+
+export default function IconColorsDemo() {
+  return (
+    <Box className="flex-row flex-wrap gap-5">
+      {COLORS.map((color) => (
+        <Box key={color} className="items-center gap-2">
+          <Icon as={Favorite} color={color} className="size-6" />
+          <Text size="sm" color="secondary">
+            {color}
+          </Text>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## Outlined and filled
+
+Icons render their outlined variant by default. Set `filled` when the selected icon provides filled path data; icons without a filled variant fall back to their outline.
+
+```tsx
+import { Box, Icon, Text } from '@cdx-ui/components';
+import { Favorite } from '@cdx-ui/icons';
+
+export default function IconFilledDemo() {
+  return (
+    <Box className="flex-row gap-8">
+      <Box className="items-center gap-2">
+        <Icon as={Favorite} color="action" className="size-8" />
+        <Text size="sm" color="secondary">
+          Outlined
+        </Text>
+      </Box>
+      <Box className="items-center gap-2">
+        <Icon as={Favorite} filled color="action" className="size-8" />
+        <Text size="sm" color="secondary">
+          Filled
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Accessibility
+
+Omit `accessibilityLabel` when an icon is decorative or repeats adjacent text. Provide a concise label when the icon conveys information that is not available elsewhere.
+
+```tsx
+import { Box, Icon, Text } from '@cdx-ui/components';
+import { ArrowForward, Lock } from '@cdx-ui/icons';
+
+export default function IconAccessibilityDemo() {
+  return (
+    <Box className="gap-5">
+      <Box className="flex-row items-center gap-3">
+        <Icon as={Lock} color="success" className="size-6" accessibilityLabel="Account protected" />
+        <Text>Informative icon with a screen reader label</Text>
+      </Box>
+      <Box className="flex-row items-center gap-3">
+        <Icon as={ArrowForward} color="secondary" className="size-6" />
+        <Text>Decorative icon next to visible text</Text>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## API
+
+### Icon
+
+Renders the Forge icon supplied through `as`. `className` supports Uniwind utilities for dimensions, spacing, and positioning.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Utility classes for size (`size-*`) and placement, merged after the defaults. |
+| `children?` | `React.ReactNode` | — | — |
+| `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. |
+
+Inherits all `ForgeIconProps` except the SVG `color`: [`SvgProps`](https://github.com/software-mansion/react-native-svg#common-props) plus `filled`, `size`, and `accessibilityLabel`.
+
+## Defaults and styling
+
+- `color` defaults to `primary`.
+- A raw `color` value, such as a hex string, is deprecated. It is passed to the SVG unchanged and logs a one-time warning in development. Use a semantic color instead.
+- `className` defaults to `size-5 shrink-0`, so an icon keeps its size in a row of text on web.
+- Consumer classes are merged after the defaults, so `size-*` and `shrink` utilities override them.
+- The inherited `size` prop can set the SVG dimensions directly when a `size-*` class is not appropriate.
+- `filled` defaults to `false`.
+
+## Accessibility
+
+- Without `accessibilityLabel`, the underlying SVG is decorative and hidden from assistive technology.
+- With `accessibilityLabel`, the SVG is exposed with the image role and announced using that label.
+- `Icon` is not interactive. Use `IconButton` for an icon-only action, or place a decorative icon inside another control that already has an accessible name.

package/docs/components/icon-button/content.md

@@ -0,0 +1,200 @@
+# Icon Button (https://design.candescent.com/docs/components/icon-button)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=427-5235), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/actions-iconbutton--default)
+
+A single-icon button for compact actions in toolbars, table rows, and inline controls.
+
+```tsx
+import { IconButton } from '@cdx-ui/components';
+```
+
+## Variants
+
+```tsx
+import { IconButton, Box } from '@cdx-ui/components';
+import { ArrowCircleUp } from '@cdx-ui/icons';
+
+export default function IconButtonVariantsDemo() {
+  return (
+    <Box className="flex-row gap-4">
+      <IconButton as={ArrowCircleUp} variant="solid" accessibilityLabel="Solid" />
+      <IconButton as={ArrowCircleUp} variant="subtle" accessibilityLabel="Subtle" />
+      <IconButton as={ArrowCircleUp} variant="ghost" accessibilityLabel="Ghost" />
+    </Box>
+  );
+}
+```
+
+### Solid
+
+```tsx
+import { IconButton, Box } from '@cdx-ui/components';
+import { ArrowCircleUp } from '@cdx-ui/icons';
+
+export default function IconButtonSolidDemo() {
+  return (
+    <Box className="flex-row gap-4">
+      <IconButton as={ArrowCircleUp} variant="solid" color="neutral" accessibilityLabel="Neutral" />
+      <IconButton as={ArrowCircleUp} variant="solid" color="action" accessibilityLabel="Action" />
+      <IconButton as={ArrowCircleUp} variant="solid" color="danger" accessibilityLabel="Danger" />
+    </Box>
+  );
+}
+```
+
+### Subtle
+
+```tsx
+import { IconButton, Box } from '@cdx-ui/components';
+import { ArrowCircleUp } from '@cdx-ui/icons';
+
+export default function IconButtonSubtleDemo() {
+  return (
+    <Box className="flex-row gap-4">
+      <IconButton
+        as={ArrowCircleUp}
+        variant="subtle"
+        color="neutral"
+        accessibilityLabel="Neutral"
+      />
+      <IconButton as={ArrowCircleUp} variant="subtle" color="action" accessibilityLabel="Action" />
+      <IconButton as={ArrowCircleUp} variant="subtle" color="danger" accessibilityLabel="Danger" />
+    </Box>
+  );
+}
+```
+
+### Ghost
+
+```tsx
+import { IconButton, Box } from '@cdx-ui/components';
+import { ArrowCircleUp } from '@cdx-ui/icons';
+
+export default function IconButtonGhostDemo() {
+  return (
+    <Box className="flex-row gap-4">
+      <IconButton as={ArrowCircleUp} variant="ghost" color="neutral" accessibilityLabel="Neutral" />
+      <IconButton as={ArrowCircleUp} variant="ghost" color="action" accessibilityLabel="Action" />
+      <IconButton as={ArrowCircleUp} variant="ghost" color="danger" accessibilityLabel="Danger" />
+    </Box>
+  );
+}
+```
+
+## Colors
+
+```tsx
+import { IconButton, Box } from '@cdx-ui/components';
+import { ArrowCircleUp } from '@cdx-ui/icons';
+
+export default function IconButtonColorsDemo() {
+  return (
+    <Box className="flex-row gap-4">
+      <IconButton as={ArrowCircleUp} color="neutral" accessibilityLabel="Neutral" />
+      <IconButton as={ArrowCircleUp} color="action" accessibilityLabel="Action" />
+      <IconButton as={ArrowCircleUp} color="danger" accessibilityLabel="Danger" />
+    </Box>
+  );
+}
+```
+
+## Sizes
+
+```tsx
+import { IconButton, Box } from '@cdx-ui/components';
+import { ArrowCircleUp } from '@cdx-ui/icons';
+
+export default function IconButtonSizesDemo() {
+  return (
+    <Box className="flex-row items-center gap-4">
+      <IconButton as={ArrowCircleUp} size="default" accessibilityLabel="Default size" />
+      <IconButton as={ArrowCircleUp} size="small" accessibilityLabel="Small size" />
+    </Box>
+  );
+}
+```
+
+## Disabled
+
+```tsx
+import { IconButton, Box } from '@cdx-ui/components';
+import { ArrowCircleUp } from '@cdx-ui/icons';
+
+export default function IconButtonDisabledDemo() {
+  return (
+    <Box className="flex-row gap-4">
+      <IconButton
+        as={ArrowCircleUp}
+        variant="solid"
+        color="action"
+        isDisabled
+        accessibilityLabel="Disabled solid"
+      />
+      <IconButton
+        as={ArrowCircleUp}
+        variant="subtle"
+        color="action"
+        isDisabled
+        accessibilityLabel="Disabled subtle"
+      />
+      <IconButton
+        as={ArrowCircleUp}
+        variant="ghost"
+        color="action"
+        isDisabled
+        accessibilityLabel="Disabled ghost"
+      />
+    </Box>
+  );
+}
+```
+
+## As link
+
+Use `Link` with `asChild` to merge navigation behavior onto the icon button.
+
+```tsx
+import { IconButton, Link } from '@cdx-ui/components';
+import { ArrowCircleUp } from '@cdx-ui/icons';
+
+export default function IconButtonAsLinkDemo() {
+  return (
+    <Link href="https://example.com" asChild webProps={{ target: '_blank', rel: 'noopener' }}>
+      <IconButton as={ArrowCircleUp} accessibilityLabel="Open link" />
+    </Link>
+  );
+}
+```
+
+## API
+
+### IconButton
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode \| ((state: PressableStateCallbackType) => React.ReactNode)` | — | Either children or a render prop that receives a boolean reflecting whether the component is currently pressed. |
+| `size?` | `'default' \| 'small' \| null` | — | — |
+| `variant?` | `'solid' \| 'subtle' \| 'ghost' \| 'tint'` | `'solid'` | Visual style variant. |
+| `color?` | `'neutral' \| 'action' \| 'danger' \| null` | — | — |
+| `as` | `ForgeIcon` | — | Forge icon component to render (icon-only control). |
+| `iconClassName?` | `string` | — | Passed through to the underlying `Icon`. |
+| `isDisabled?` | `boolean` | — | If true, the button will be disabled. |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props) (including `onPress`).
+
+## Accessibility
+
+Because there is no visible text label, every `IconButton` **must** have an explicit `accessibilityLabel` for screen readers.
+
+| Attribute            | Value                                                         |
+| -------------------- | ------------------------------------------------------------- |
+| `accessibilityRole`  | `button` (default)                                            |
+| `accessibilityLabel` | **Required** — describes the action (e.g., "Close", "Delete") |
+
+## When to use
+
+| Use `Button` when…                                   | Use `IconButton` when…                                             |
+| ---------------------------------------------------- | ------------------------------------------------------------------ |
+| The action needs a visible text label                | The icon alone communicates the action                             |
+| An icon should sit beside that label (`Button.Icon`) | The control stands alone, such as a toolbar action or close button |

package/docs/components/icon-button/design.md

@@ -0,0 +1,165 @@
+# Icon Button — Design (https://design.candescent.com/docs/components/icon-button)
+
+## Usage
+
+**Common alternative names**: Icon-only button
+
+---
+
+## **Anatomy**
+
+**Anatomy\_icon-button**
+
+1. **Icon**: A single graphic that represents the icon button’s action. Follow the icon affordance guidelines below.
+2. **Outline (optional):** A visible border that defines the icon button’s shape and boundary, helping it stand out against the background while maintaining a lightweight visual presence.
+3. **State layer**: A translucent background color that appears when the icon button is hovered over or focused on.
+
+### Variant
+
+Icon buttons are available in 2 variants: **solid** and **ghost**.
+
+- **Outline**
+
+  Medium‑emphasis icon buttons used for actions that are important but not the primary action. The outline provides clear affordance while keeping visual weight lower than primary controls.
+- **Ghost**
+
+  Low‑emphasis icon buttons used for secondary or supporting actions. With no outline, this variant relies on placement and state feedback.
+
+### **Size**
+
+Icon Buttons are available in 2 sizes: **Default** and **Small**. Size should be considered for visual balance and user focus; larger buttons will draw greater attention.
+
+- **size: default**
+
+  Default icon buttons have a icon size of 24x24 px, plus 10 px of padding, resulting in a 44x44 px icon button.
+- **size: small**
+
+  Small icon buttons have a default icon size of 20x20 px, plus 6 px of padding, resulting in a 32x32 px icon button.
+
+### **Color**
+
+Icon Buttons are currently only available in a neutral color. Other colors will be added in future versions.
+
+- **color: neutral**
+
+  Neutral, most common, less visual prominence
+
+---
+
+Usage
+
+### When to use
+
+> [!TIP]
+>
+> **Provide a small, clickable icon that represents an action or a link**
+>
+> - ex. Search, refresh, print
+
+> [!TIP]
+>
+> **For secondary or less important actions that may not require a lot of emphasis**
+>
+> - ex. Settings, more options
+
+> [!TIP]
+>
+> **For actions that users frequently use**
+>
+> - ex. Add, delete, hide
+
+### When not to use
+
+> [!CAUTION]
+>
+> **As the primary call-to-action on a page**
+>
+> - ex: The submit button on a form
+> - ex: The confirm button on a modal
+
+### Layout and placement
+
+Icon buttons are typically placed in areas of the interface where users expect to find actions, such as in toolbars or near form fields.
+
+When using icon buttons in a toolbar, consider grouping related buttons together to improve the user's ability to quickly scan and identify them.
+
+_usage\_layout\_01-ex_
+
+### **Consistency**
+
+Icon buttons should look and feel consistent with other buttons on the page, especially ones that are directly next to each other. That includes standard buttons, button groups, toggle buttons, etc.
+
+- **Do:** When using buttons and icon buttons in the same row, use the same value for the size property so that the button heights align.
+- **Don't:** Don’t mix and match button sizes.
+- **Do:** Icon buttons in a row should generally be the same color.
+- **Do:** Make an exception for icon buttons that represent destructive actions.
+- **Don't:** Don’t mix and match colors without a good reason.
+
+---
+
+## **Behavior**
+
+### **Interaction states**
+
+The default state of an icon button is clickable. The appearance of the button will respond as the user interacts with it.
+
+- **Resting (default)**
+
+  Default state. The user is not interacting with the icon button.
+- **isHovered**
+
+  When the user’s cursor is hovering over the icon button.
+- **isFocused**
+
+  When the user focuses on the icon button using tab navigation controls on their keyboard.
+
+### **Disabled**
+
+Icon buttons can be disabled, which prevents the user from clicking on or interacting with the button.
+
+Using disabled buttons can cause accessibility issues so try and avoid them, as they often create more problems than they solve. Keep buttons active and use clear error messaging to guide users whenever possible. Use disabled buttons only in rare edge cases.
+
+- **isDisabled**
+
+  The user cannot interact with the icon button in this state.
+
+### **Click**
+
+When a user clicks an icon button, it should perform the intended action and provide feedback to the user to indicate that the action has been taken. Do not leave the user to guess if the action was successful or not.
+
+For more information about providing feedback, see our Notifications pattern.
+
+### **Destructive actions**
+
+Just like standard buttons, icon buttons can be used for destructive actions. Destructive actions are **actions that cause permanent data loss**, such as discarding a draft email, deleting a user account, or closing a credit card. In most cases, these actions can’t be undone.
+
+#### **Preventing user error**
+
+In flows that contain destructive actions, **users should be prompted before the action is executed**, as it is possible they pressed the button by mistake. This is especially important when using an icon button, since there is no visible label to help the user.
+
+- **Do:** Use a destructive icon button to open the confirmation prompt, and then a high-emphasis destructive button in the prompt to complete the action.
+- **Don't:** Don’t complete a destructive action without prompting the user. The user must confirm their intent in order to avoid mistakes.
+
+## Content
+
+## Recognition over recall
+
+When using an icon button, make sure that the icon is **highly recognizable** and has a clear **affordance**. In other words, the meaning of the symbol should be easily understood even without a visible label. If there is no unambiguous icon available, use a standard button instead.
+
+- **Do:** Use icon buttons for actions with icons that are highly recognizable.
+- **Don't:** Don’t use icon buttons with icons that are not highly recognizable to most users.
+
+## Context and meaning
+
+Sometimes, the context of an icon button makes the meaning of its icon more recognizable to the user. The same icon may have a very obvious meaning in one context, and be completely unclear in another. When choosing an icon for an icon button, consider the context of the current page, the current flow, the type of application, and/or the device type.
+
+- **Do:** In the context of a timer app, the ⏹︎ stop and ⏸︎ pause icons will have very obvious meanings to the user.
+- **Don't:** In the context of a table containing employee names & roles, the ⏹︎ stop and ⏸︎ pause icons will have no obvious meaning to the user.
+
+## **Represent the action**
+
+The icon inside of an icon button can dynamically change. However, the **icon should always represent the button’s action**, not the state of another element.
+
+As an example, think about the play/pause button on a music player. When the user wants to pause the music, they will look for the **⏸ pause icon**, because the want to take the **pause action**. They would interpret the **▶ play icon** as the **play action**, the opposite of what they want.
+
+- **Do:** Use an icon that represents the button’s action, not the current state of the parent component.