@cdx-ui/components 0.2.3 → 0.2.5

package/docs/components/progress-bar/content.md

@@ -0,0 +1,87 @@
+# Progress Bar (https://design.candescent.com/docs/components/progress-bar)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=4927-541), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/feedback-progressbar--default)
+
+A compound component: the root acts as the track, and `ProgressBar.Indicator` fills proportionally to the current value.
+
+```tsx
+import { ProgressBar } from '@cdx-ui/components';
+```
+
+## Basic
+
+```tsx
+import { ProgressBar } from '@cdx-ui/components';
+
+export default function ProgressBarBasicDemo() {
+  return (
+    <ProgressBar value={45} max={100} accessibilityLabel="Upload progress">
+      <ProgressBar.Indicator />
+    </ProgressBar>
+  );
+}
+```
+
+## Values
+
+```tsx
+import { Box, ProgressBar, Text } from '@cdx-ui/components';
+
+const values = [0, 25, 70, 100] as const;
+
+export default function ProgressBarValuesDemo() {
+  return (
+    <Box className="w-full max-w-md gap-4">
+      {values.map((value) => (
+        <Box key={value} className="gap-1.5">
+          <Text size="sm" color="secondary">
+            {value}%
+          </Text>
+          <ProgressBar value={value} max={100} accessibilityLabel={`${value}% complete`}>
+            <ProgressBar.Indicator />
+          </ProgressBar>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## API
+
+### ProgressBar
+
+Sets `role="progressbar"` and `accessibilityRole="progressbar"`. Pass `value={null}` for indeterminate state. Provide an `accessibilityLabel` that names the progress being measured.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+| `value?` | `number \| null` | `0` | Current value in the range `[0, max]`, or `null` for indeterminate progress. Values below `0` clamp to `0`; values above `max` clamp to `max`. Non-finite values (such as `NaN`) are treated as `0`. |
+| `max?` | `number` | `100` | Maximum value. The minimum is always `0`. A `max` of `0` or less is treated as complete. |
+| `getValueLabel?` | `((value: number, max: number) => string)` | — | Screen-reader text for determinate progress (`accessibilityValue.text`). Defaults to a rounded percentage of `max`, such as `"45%"`. No effect when `value` is `null`, or when `accessibilityValue` is set. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute    | Values                                     | Description                                                                                                         |
+| ------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `data-state` | `loading` \| `complete` \| `indeterminate` | `loading` while `0 ≤ value < max`; `complete` at `value ≥ max` or `max ≤ 0`; `indeterminate` when `value` is `null` |
+| `data-value` | string (absent when indeterminate)         | Clamped numeric value                                                                                               |
+| `data-max`   | string                                     | Maximum value                                                                                                       |
+
+## Sub-components
+
+### ProgressBar.Indicator
+
+The filled portion of the track. Width is set automatically from `value / max`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Accessibility
+
+The root is a progressbar. Determinate values announce `accessibilityValue` with `min`, `max`, `now`, and `text`. The default `text` is a rounded percentage of `max`; pass `getValueLabel` to replace it. Indeterminate (`value={null}`) omits `now` and announces `"Indeterminate"`. Pass `accessibilityValue` to replace that announcement, including a localized indeterminate label.

package/docs/components/progress-circle/content.md

@@ -0,0 +1,176 @@
+# Progress Circle (https://design.candescent.com/docs/components/progress-circle)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=2616-182), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/feedback-progresscircle--default)
+
+A compound component: the root sizes the ring, and `ProgressCircle.Indicator` draws the arc fill.
+
+```tsx
+import { ProgressCircle } from '@cdx-ui/components';
+```
+
+## Basic
+
+```tsx
+import { ProgressCircle } from '@cdx-ui/components';
+
+export default function ProgressCircleBasicDemo() {
+  return (
+    <ProgressCircle value={45} max={100} accessibilityLabel="Upload progress">
+      <ProgressCircle.Indicator />
+    </ProgressCircle>
+  );
+}
+```
+
+## Values
+
+```tsx
+import { Box, ProgressCircle, Text } from '@cdx-ui/components';
+
+const values = [0, 25, 70, 100] as const;
+
+export default function ProgressCircleValuesDemo() {
+  return (
+    <Box className="flex-row flex-wrap items-center gap-6">
+      {values.map((value) => (
+        <Box key={value} className="items-center gap-1.5">
+          <ProgressCircle value={value} max={100} accessibilityLabel={`${value}% complete`}>
+            <ProgressCircle.Indicator />
+          </ProgressCircle>
+          <Text size="sm" color="secondary">
+            {value}%
+          </Text>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## Sizes
+
+Size is inherited by `ProgressCircle.Indicator` unless overridden.
+
+```tsx
+import { Box, ProgressCircle, Text } from '@cdx-ui/components';
+
+export default function ProgressCircleSizesDemo() {
+  return (
+    <Box className="flex-row items-end gap-6">
+      <Box className="items-center gap-1.5">
+        <ProgressCircle value={60} size="large" accessibilityLabel="Large progress">
+          <ProgressCircle.Indicator />
+        </ProgressCircle>
+        <Text size="sm" color="secondary">
+          large
+        </Text>
+      </Box>
+      <Box className="items-center gap-1.5">
+        <ProgressCircle value={60} size="small" accessibilityLabel="Small progress">
+          <ProgressCircle.Indicator />
+        </ProgressCircle>
+        <Text size="sm" color="secondary">
+          small
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Colors
+
+`inherit` uses `currentColor` so the ring follows the surrounding text color.
+
+```tsx
+import { Box, ProgressCircle, Text } from '@cdx-ui/components';
+
+export default function ProgressCircleColorsDemo() {
+  return (
+    <Box className="flex-row items-end gap-6">
+      <Box className="items-center gap-1.5">
+        <ProgressCircle value={60} color="default" accessibilityLabel="Default color">
+          <ProgressCircle.Indicator />
+        </ProgressCircle>
+        <Text size="sm" color="secondary">
+          default
+        </Text>
+      </Box>
+      <Box className="items-center gap-1.5 text-content-danger">
+        <ProgressCircle value={60} color="inherit" accessibilityLabel="Inherit color">
+          <ProgressCircle.Indicator />
+        </ProgressCircle>
+        <Text size="sm" color="secondary">
+          inherit
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Indeterminate
+
+Pass `value={null}` for an infinite spinning loader.
+
+```tsx
+import { ProgressCircle } from '@cdx-ui/components';
+
+export default function ProgressCircleIndeterminateDemo() {
+  return (
+    <ProgressCircle value={null} accessibilityLabel="Loading">
+      <ProgressCircle.Indicator />
+    </ProgressCircle>
+  );
+}
+```
+
+## API
+
+### ProgressCircle
+
+Sets `role="progressbar"` and `accessibilityRole="progressbar"`. Pass `value={null}` for indeterminate state. Provide an `accessibilityLabel` that names the progress being measured.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+| `size?` | `'large' \| 'small' \| null` | — | — |
+| `color?` | `'default' \| 'inherit' \| null` | `'default'` | Stroke color. `inherit` uses `currentColor` with the track at 24% opacity. Inherited by `ProgressCircle.Indicator` unless overridden. |
+| `value?` | `number \| null` | `0` | Current value in the range `[0, max]`, or `null` for indeterminate progress. Values below `0` clamp to `0`; values above `max` clamp to `max`. Non-finite values (such as `NaN`) are treated as `0`. |
+| `max?` | `number` | `100` | Maximum value. The minimum is always `0`. A `max` of `0` or less is treated as complete. |
+| `getValueLabel?` | `((value: number, max: number) => string)` | — | Screen-reader text for determinate progress (`accessibilityValue.text`). Defaults to a rounded percentage of `max`, such as `"45%"`. No effect when `value` is `null`, or when `accessibilityValue` is set. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute    | Values                                     | Description            |
+| ------------ | ------------------------------------------ | ---------------------- |
+| `data-state` | `loading` \| `complete` \| `indeterminate` | Current progress state |
+| `data-value` | string (absent when indeterminate)         | Clamped numeric value  |
+| `data-max`   | string                                     | Maximum value          |
+
+## Sub-components
+
+### ProgressCircle.Indicator
+
+The SVG ring. Arc length is set automatically from `value / max`. In indeterminate mode the ring spins a partial arc.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+| `size?` | `'large' \| 'small' \| null` | — | Overrides the size inherited from `ProgressCircle`. |
+| `color?` | `'default' \| 'inherit' \| null` | — | Overrides the color inherited from `ProgressCircle`. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Anatomy
+
+| `data-slot`                 | Element           |
+| --------------------------- | ----------------- |
+| `progress-circle`           | Root              |
+| `progress-circle-indicator` | Indicator wrapper |
+
+## Accessibility
+
+The root is a progressbar. Determinate values announce `accessibilityValue` with `min`, `max`, `now`, and `text` (default English percentage). Indeterminate (`value={null}`) omits `now` and announces `"Indeterminate"`. Use `getValueLabel` for i18n.

package/docs/components/progress-segmented/content.md

@@ -0,0 +1,119 @@
+# Progress Segmented (https://design.candescent.com/docs/components/progress-segmented)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=449-449), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/feedback-progresssegmented--default)
+
+A single (non-compound) component for step-based progress. Pair with a visible step label when WCAG 1.4.1 color-independence is required.
+
+```tsx
+import { ProgressSegmented } from '@cdx-ui/components';
+```
+
+## Basic
+
+Mid-step in-progress state (`step={2}` of `segments={5}`).
+
+```tsx
+import { ProgressSegmented } from '@cdx-ui/components';
+
+export default function ProgressSegmentedBasicDemo() {
+  return (
+    <ProgressSegmented
+      step={2}
+      segments={5}
+      accessibilityLabel="Onboarding progress"
+      className="max-w-md"
+    />
+  );
+}
+```
+
+## States
+
+Steps `0` through `N`, plus `isStepComplete` on the final step. Visible labels accompany each bar so progress is not conveyed by color alone.
+
+```tsx
+import { Box, ProgressSegmented, Text, VStack } from '@cdx-ui/components';
+
+const segments = 4;
+
+const rows = [
+  { step: 0, isStepComplete: false, label: 'Not started' },
+  { step: 1, isStepComplete: false, label: 'Step 1 of 4' },
+  { step: 2, isStepComplete: false, label: 'Step 2 of 4' },
+  { step: 3, isStepComplete: false, label: 'Step 3 of 4' },
+  { step: 4, isStepComplete: false, label: 'Step 4 of 4' },
+  { step: 4, isStepComplete: true, label: 'Step 4 of 4, completed' },
+] as const;
+
+export default function ProgressSegmentedStatesDemo() {
+  return (
+    <VStack space="lg" className="w-full max-w-md">
+      {rows.map(({ step, isStepComplete, label }) => (
+        <Box key={label} className="gap-1.5">
+          <Text size="sm" color="secondary">
+            {label}
+          </Text>
+          <ProgressSegmented
+            step={step}
+            segments={segments}
+            isStepComplete={isStepComplete}
+            accessibilityLabel={label}
+          />
+        </Box>
+      ))}
+    </VStack>
+  );
+}
+```
+
+## Segment counts
+
+Custom `segments` values (for example 3 and 6).
+
+```tsx
+import { Box, ProgressSegmented, Text, VStack } from '@cdx-ui/components';
+
+export default function ProgressSegmentedSegmentsDemo() {
+  return (
+    <VStack space="lg" className="w-full max-w-md">
+      <Box className="gap-1.5">
+        <Text size="sm" color="secondary">
+          3 segments
+        </Text>
+        <ProgressSegmented step={2} segments={3} accessibilityLabel="3-segment progress" />
+      </Box>
+      <Box className="gap-1.5">
+        <Text size="sm" color="secondary">
+          6 segments
+        </Text>
+        <ProgressSegmented step={4} segments={6} accessibilityLabel="6-segment progress" />
+      </Box>
+    </VStack>
+  );
+}
+```
+
+## API
+
+### ProgressSegmented
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+| `step` | `number` | — | Current step (1-based index into the segment count). Clamped to `[0, segments]` (`0` leaves every segment incomplete). |
+| `segments?` | `number` | `5` | Number of segments in the bar. Matches the Figma `segments` variant (2–6 in the design system file); the prop accepts any positive integer for backward compatibility. |
+| `isStepComplete?` | `boolean` | `false` | When true, the current step segment is marked as complete rather than in-progress. |
+| `getAccessibilityText?` | `((step: number, segmentCount: number, isStepComplete: boolean) => string)` | — | Returns the accessibility value text announced by screen readers. Receives the clamped step, segment count, and whether the step is complete. Replaces the English default. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| State        | Visual                                                          | Condition                                                         |
+| ------------ | --------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `complete`   | Solid fill (`bg-surface-action-strong`)                         | Step index \< current step, or current step when `isStepComplete` |
+| `inprogress` | Half-filled (`surface-action-strong` → `surface-action-subtle`) | Current step when `isStepComplete` is `false`                     |
+| `incomplete` | Light fill (`bg-surface-action-subtle`)                         | Step index > current step                                         |
+
+## Accessibility
+
+Sets `accessibilityRole="progressbar"` and reports `accessibilityValue` with `min: 0`, `max` equal to the segment count, `now` equal to the clamped step, and `text`. Default value text is English (`"Step 2 of 5"`, or `"Step 2 of 5, completed"` when `isStepComplete` is true). Use `getAccessibilityText` for other locales or domain-specific labels. `accessibilityLabel` defaults to `"Progress"`.

package/docs/components/quick-action-button/content.md

@@ -0,0 +1,154 @@
+# Quick Action Button (https://design.candescent.com/docs/components/quick-action-button)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=5283-1723), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/actions-quickactionbutton--default)
+
+A compound button for common actions such as transfers, payments, and deposits.
+
+```tsx
+import { QuickActionButton } from '@cdx-ui/components';
+```
+
+## Basic
+
+Compose the icon and visible label inside the root button.
+
+```tsx
+import { QuickActionButton } from '@cdx-ui/components';
+import { Send } from '@cdx-ui/icons';
+
+export default function QuickActionButtonBasicDemo() {
+  return (
+    <QuickActionButton>
+      <QuickActionButton.Icon as={Send} />
+      <QuickActionButton.Label>Transfer</QuickActionButton.Label>
+    </QuickActionButton>
+  );
+}
+```
+
+## Action group
+
+Arrange related quick actions in a row or wrapping grid.
+
+```tsx
+import { Box, QuickActionButton } from '@cdx-ui/components';
+import { AccountBalance, MoreHoriz, Payments, Send } from '@cdx-ui/icons';
+
+export default function QuickActionButtonActionGroupDemo() {
+  return (
+    <Box className="flex-row flex-wrap justify-center gap-4">
+      <QuickActionButton>
+        <QuickActionButton.Icon as={Send} />
+        <QuickActionButton.Label>Transfer</QuickActionButton.Label>
+      </QuickActionButton>
+      <QuickActionButton>
+        <QuickActionButton.Icon as={Payments} />
+        <QuickActionButton.Label>Pay</QuickActionButton.Label>
+      </QuickActionButton>
+      <QuickActionButton>
+        <QuickActionButton.Icon as={AccountBalance} />
+        <QuickActionButton.Label>Deposit</QuickActionButton.Label>
+      </QuickActionButton>
+      <QuickActionButton>
+        <QuickActionButton.Icon as={MoreHoriz} />
+        <QuickActionButton.Label>More</QuickActionButton.Label>
+      </QuickActionButton>
+    </Box>
+  );
+}
+```
+
+## Disabled
+
+Set `isDisabled` on the root to disable interaction and apply disabled styling to the indicator and label.
+
+```tsx
+import { QuickActionButton } from '@cdx-ui/components';
+import { Send } from '@cdx-ui/icons';
+
+export default function QuickActionButtonDisabledDemo() {
+  return (
+    <QuickActionButton isDisabled>
+      <QuickActionButton.Icon as={Send} />
+      <QuickActionButton.Label>Transfer</QuickActionButton.Label>
+    </QuickActionButton>
+  );
+}
+```
+
+## Long labels
+
+Labels display up to two lines and truncate overflowing text. Provide the full action name with `accessibilityLabel` when truncation is likely.
+
+```tsx
+import { QuickActionButton } from '@cdx-ui/components';
+import { AccountBalance } from '@cdx-ui/icons';
+
+export default function QuickActionButtonLongLabelDemo() {
+  return (
+    <QuickActionButton accessibilityLabel="International wire transfer abroad">
+      <QuickActionButton.Icon as={AccountBalance} />
+      <QuickActionButton.Label>International wire transfer abroad</QuickActionButton.Label>
+    </QuickActionButton>
+  );
+}
+```
+
+## API
+
+### QuickActionButton
+
+The pressable root that lays out the circular indicator and label vertically.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | Either children or a render prop that receives a boolean reflecting whether the component is currently pressed. |
+| `isDisabled?` | `boolean` | — | If true, the button will be disabled. |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props) (including `onPress`).
+
+## Sub-components
+
+### QuickActionButton.Icon
+
+The primary icon slot. It renders the Forge icon inside `QuickActionButton.Indicator`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `as` | `ForgeIcon` | — | Forge icon component to render inside the circular indicator. |
+| `className?` | `string` | — | Applied to the icon glyph, not the indicator circle. |
+| `indicatorClassName?` | `string` | — | Applied to the indicator circle wrapper. |
+
+### QuickActionButton.Indicator
+
+The circular container around the icon. It is rendered automatically by `QuickActionButton.Icon` and exposed for custom compositions.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### QuickActionButton.Label
+
+The text beneath the indicator. Labels are centered and limited to two lines with tail truncation.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props). `numberOfLines` and `ellipsizeMode` are fixed to `2` and `"tail"`.
+
+## Accessibility
+
+| Attribute                  | Behavior                                                        |
+| -------------------------- | --------------------------------------------------------------- |
+| `accessibilityRole`        | Defaults to `button` on the root                                |
+| Accessible name            | Derived from `QuickActionButton.Label` text                     |
+| Truncated or omitted label | Provide a descriptive `accessibilityLabel` on the root          |
+| Disabled                   | `isDisabled` prevents activation and exposes the disabled state |
+
+The button supports Space and Enter activation on web and displays a focus-visible ring around the indicator.