@cdx-ui/components 0.2.3 → 0.2.4

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

@@ -0,0 +1,170 @@
+# Quick Action Button — Design (https://design.candescent.com/docs/components/quick-action-button)
+
+## Usage
+
+**Common alternative names**: Tile, Shortcut, Quick link, Navigation tile
+
+---
+
+## Anatomy
+
+Quick action button is a vertical stack inside a single interactive container. The whole tile is one tap target—not separate targets for icon and label.
+
+**Anatomy\_quick-action-button**
+
+1. **Stroke:** The outline that surrounds the icon. Used to provide visual emphasis and define the icon's shape.
+2. **Icon:** A single icon centered in the upper area of the container. Conveys the action at a glance. One icon per Quick action button.
+3. **Label:** Short text centered below the icon.
+
+---
+
+Usage
+
+### When to use
+
+**✅  Provide quick access to common tasks**
+
+- ex: Pay, Transfer, Deposit, Statements on an account home
+- ex: Send, Request, Scan on a payments hub
+
+> [!TIP]
+>
+> **Actions users recognize by icon but still need a short name**
+>
+> - ex: Mobile banking where icons speed scanning but labels remove ambiguity (**Zelle** vs generic send icon)
+
+> [!TIP]
+>
+> **Display a small group of related actions**
+>
+> - ex: Use quick actions to present a small set of related actions together. When displaying multiple quick actions, use the Quick action bar to create a consistent and easy-to-scan layout.
+
+> [!TIP]
+>
+> **Entry points to flows and destinations**
+>
+> - ex: Open account, Order checks, Find ATM as optional next steps below main content
+
+### When not to use
+
+> [!CAUTION]
+>
+> **One primary call to action for the screen**
+>
+> - ex: Continue, Submit application, Sign in
+
+> [!CAUTION]
+>
+> **Icon-only control with no visible label**
+>
+> - ex: Use an [Icon Button](https://design.candescent.com/docs/components/icon-button/content.md) when a visible text label is not needed.
+
+> [!CAUTION]
+>
+> **Primary or persistent navigation**
+>
+> - ex: Use dedicated Navigation components for moving between major sections of an application.
+
+> [!CAUTION]
+>
+> **Selecting between options**
+>
+> - ex: Use a Radio group, Segmented control, or other selection component when users need to choose and maintain a selected state.
+
+> [!CAUTION]
+>
+> **Actions that require lengthy labels or supporting content**
+>
+> - ex: Use a List row, or Card when additional text, descriptions, or supporting information is needed.
+
+### Quick action button vs Button and Icon button
+
+Quick action buttons share space as equals; Buttons express hierarchy (primary vs secondary). Icon buttons save space when the label is elsewhere or obvious.
+
+| Need                                                  | Use                     |
+| ----------------------------------------------------- | ----------------------- |
+| 3–8 peer shortcuts with icon + short label            | **Quick action button** |
+| Primary or secondary CTA, form footer, dialog actions | **Button**              |
+| Single icon, label in tooltip or adjacent heading     | **Icon button**         |
+
+### Layout patterns
+
+Quick action buttons are most effective when displayed as a group of related actions. Use a maximum of four quick actions per row. When more than four actions are needed, wrap the remaining items to a new row while maintaining consistent sizing, spacing, and alignment.
+
+#### Horizontal row
+
+Use a single row when up to four quick actions can fit comfortably within the available space. When displaying multiple quick actions, use the **Quick Action Bar** to maintain consistent sizing, spacing, and alignment across the group. For groups with fewer than four quick actions, center the actions within the row.
+
+**Usage\_layout\_01-ex\_**
+
+### Icon and label
+
+Every quick action button requires both an icon and a label. Icons help users identify actions quickly, while labels provide clarity and reduce ambiguity. Together, they create a recognizable and easy-to-scan experience.
+
+- **Do:** Pair each icon with a short, descriptive label that clearly communicates the action.
+- **Don't:** Don't rely on icons alone. If a visible label is not needed, use an Icon button instead.
+
+### Action count and prioritization
+
+Quick action buttons should highlight the most important and frequently used tasks. Avoid displaying too many actions at once, as this can make it harder for users to find the action they need.
+
+- **Do:** Prioritize the most frequently used or valuable actions and display them first within the group.
+- **Don't:** Don't display more than four quick actions in a single row. When additional actions are needed, move them to a new row or a secondary destination.
+
+---
+
+## Behavior
+
+### States
+
+- **Resting (default)**
+
+  Default state. User is not interacting with the button.
+- **isHovered: true**
+
+  When the user’s cursor is hovering over the button.
+- **isFocused: true**
+
+  Visible focus ring on the **container** (keyboard and assistive tech).
+
+### Disabled
+
+Quick action buttons can be disabled, which prevents users from selecting or interacting with the action.
+
+Using disabled quick action buttons can create accessibility and usability challenges because users may not understand why an action is unavailable. Keep quick action buttons enabled whenever possible and provide clear guidance or validation to help users complete the required task. Use disabled quick action buttons only when an action is temporarily unavailable and no alternative approach can be provided.
+
+- **isDisabled: true**
+
+  The user cannot interact with the button in this state.
+
+## Content
+
+## Labels
+
+Labels identify the action associated with a quick action button. Keep labels concise, descriptive, and easy to scan.
+
+- Prefer one to two words.
+- Use action-oriented language whenever possible.
+- Describe the outcome of the action, not the component or destination.
+- Use consistent grammar across a group of quick actions.
+
+### Capitalization
+
+Use sentence case for all labels and maintain consistency across the experience.
+
+- **Do:** Use sentence casing.
+- **Don't:** Don't use all caps or title casing.
+
+### Text truncation
+
+Quick action labels should be concise and easy to scan. Labels wrap to a second line when needed. When the label exceeds two lines, the text is truncated with an ellipsis to preserve a consistent layout.
+
+- **Do:** Allow labels to wrap to a second line before truncating.
+- **Caution:** Avoid labels exceeding two lines or overflow the available space.
+
+### Label length
+
+Quick action labels should be concise and easy to scan. Use the shortest label that clearly communicates the action while maintaining consistency across the group.
+
+- **Do:** Use short, descriptive labels that quickly communicate the action.
+- **Don't:** Don't use long or overly descriptive labels that reduce scannability.

package/docs/components/radio/content.md

@@ -0,0 +1,224 @@
+# Radio (https://design.candescent.com/docs/components/radio)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=2603-62), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-radio--default)
+
+A compound component with sub-components for the indicator, label, and grouping. A `Radio` must always be rendered inside a `Radio.Group`.
+
+```tsx
+import { Radio } from '@cdx-ui/components';
+```
+
+## Basic
+
+```tsx
+import { useState } from 'react';
+import { Radio } from '@cdx-ui/components';
+
+export default function RadioBasicDemo() {
+  const [accountType, setAccountType] = useState('checking');
+
+  return (
+    <Radio.Group value={accountType} onChange={setAccountType} aria-label="Account type">
+      <Radio value="checking">
+        <Radio.Label>Checking</Radio.Label>
+      </Radio>
+      <Radio value="savings">
+        <Radio.Label>Savings</Radio.Label>
+      </Radio>
+      <Radio value="money-market">
+        <Radio.Label>Money Market</Radio.Label>
+      </Radio>
+    </Radio.Group>
+  );
+}
+```
+
+## Horizontal
+
+```tsx
+import { Radio } from '@cdx-ui/components';
+
+export default function RadioHorizontalDemo() {
+  return (
+    <Radio.Group defaultValue="monthly" direction="row" aria-label="Billing cycle">
+      <Radio value="monthly">
+        <Radio.Label>Monthly</Radio.Label>
+      </Radio>
+      <Radio value="quarterly">
+        <Radio.Label>Quarterly</Radio.Label>
+      </Radio>
+      <Radio value="annual">
+        <Radio.Label>Annual</Radio.Label>
+      </Radio>
+    </Radio.Group>
+  );
+}
+```
+
+## States
+
+The group controls disabled, read-only, and invalid state for every radio.
+
+```tsx
+import { Box, Radio, Text } from '@cdx-ui/components';
+
+export default function RadioStatesDemo() {
+  return (
+    <Box className="w-full gap-4">
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Disabled
+        </Text>
+        <Radio.Group defaultValue="email" isDisabled aria-label="Disabled notification preference">
+          <Radio value="email">
+            <Radio.Label>Email</Radio.Label>
+          </Radio>
+          <Radio value="sms">
+            <Radio.Label>Text message</Radio.Label>
+          </Radio>
+        </Radio.Group>
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Read-only
+        </Text>
+        <Radio.Group defaultValue="email" isReadOnly aria-label="Read-only notification preference">
+          <Radio value="email">
+            <Radio.Label>Email</Radio.Label>
+          </Radio>
+          <Radio value="sms">
+            <Radio.Label>Text message</Radio.Label>
+          </Radio>
+        </Radio.Group>
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Invalid
+        </Text>
+        <Radio.Group isInvalid aria-label="Invalid payment method">
+          <Radio value="card">
+            <Radio.Label>Credit / debit card</Radio.Label>
+          </Radio>
+          <Radio value="ach">
+            <Radio.Label>Bank transfer (ACH)</Radio.Label>
+          </Radio>
+        </Radio.Group>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## With field
+
+```tsx
+import { useState } from 'react';
+import { Field, Radio } from '@cdx-ui/components';
+
+export default function RadioWithFieldDemo() {
+  const [value, setValue] = useState('');
+
+  return (
+    <Field isRequired isInvalid={!value}>
+      <Field.Label>Payment method</Field.Label>
+      <Radio.Group value={value} onChange={setValue}>
+        <Radio value="card">
+          <Radio.Label>Credit / debit card</Radio.Label>
+        </Radio>
+        <Radio value="ach">
+          <Radio.Label>Bank transfer (ACH)</Radio.Label>
+        </Radio>
+        <Radio value="wire">
+          <Radio.Label>Wire transfer</Radio.Label>
+        </Radio>
+      </Radio.Group>
+      <Field.Error>Please select a payment method.</Field.Error>
+    </Field>
+  );
+}
+```
+
+## API
+
+### Radio
+
+An individual radio item. Auto-renders its indicator internally — compose only `Radio.Label` (and other children) inside it. Must be rendered inside a `Radio.Group`.
+
+| 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. |
+| `value` | `string` | — | Required — identifies this item's value within a Radio.Group. |
+| `isDisabled?` | `boolean` | — | Disables this item without disabling the rest of the group. |
+| `isInvalid?` | `boolean` | — | — |
+| `isReadOnly?` | `boolean` | — | Focusable, but the selection cannot be changed. |
+| `isHovered?` | `boolean` | — | — |
+| `isFocused?` | `boolean` | — | — |
+| `isPressed?` | `boolean` | — | — |
+| `isFocusVisible?` | `boolean` | — | — |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props).
+
+## Sub-components
+
+### Radio.Label
+
+Text label rendered alongside the radio indicator. Automatically receives disabled and checked state from context.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Radio.Indicator
+
+The visual circle that displays the checked/unchecked state — an outer ring with an inner filled dot when selected. Auto-rendered by the root; exposed for deep customization but not composed in standard usage.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Radio.Group
+
+Manages single-selection state for a set of radio items with consistent spacing. Enforces single-select — there is no `type` or `max` prop.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `value?` | `string` | — | — |
+| `defaultValue?` | `string` | — | — |
+| `onChange?` | `((value: string) => void)` | — | — |
+| `isDisabled?` | `boolean` | — | — |
+| `isInvalid?` | `boolean` | — | — |
+| `isRequired?` | `boolean` | — | — |
+| `isReadOnly?` | `boolean` | — | Makes every radio in the group read-only. Items stay focusable, but the selection cannot be changed. |
+| `direction?` | `'column' \| 'row'` | — | — |
+| `name?` | `string` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Prop           | Type                      | Default    | Description                                     |
+| -------------- | ------------------------- | ---------- | ----------------------------------------------- |
+| `value`        | `string`                  | —          | Currently selected radio value (controlled)     |
+| `defaultValue` | `string`                  | —          | Initially selected value (uncontrolled)         |
+| `onChange`     | `(value: string) => void` | —          | Called when the selection changes               |
+| `isDisabled`   | `boolean`                 | `false`    | Disables all radios in the group                |
+| `isInvalid`    | `boolean`                 | `false`    | Marks all radios as invalid                     |
+| `isRequired`   | `boolean`                 | `false`    | Marks the group as required for form validation |
+| `isReadOnly`   | `boolean`                 | `false`    | Makes all radios read-only                      |
+| `direction`    | `'column' \| 'row'`       | `'column'` | Layout direction of the group                   |
+| `name`         | `string`                  | —          | Form field name for web form integration        |
+
+## Accessibility
+
+The group exposes `radiogroup` and each item exposes `radio`. The selected item has `aria-checked` set to `true`; the others are `false`. `isDisabled` marks the affected items disabled (`aria-disabled` on web), whether it is set on the group or on a single item.
+
+On web, Tab moves focus into the group. Arrow keys change the selection, and Space selects the focused item. The focus ring is drawn on the indicator. The group name — from `aria-label`, `aria-labelledby`, or a `Field.Label` — is announced when focus enters. Each item announces its label, checked state, and position in the set.

package/docs/components/range-calendar/content.md

@@ -0,0 +1,123 @@
+# Range Calendar (https://design.candescent.com/docs/components/range-calendar)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=12118-58084), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/date-time-rangecalendar--default)
+
+`RangeCalendar` renders a day grid for selecting a start and end date. The start and end values are `DateId` strings in `YYYY-MM-DD` format.
+
+```tsx
+import { RangeCalendar } from '@cdx-ui/components';
+```
+
+## Basic
+
+Control the range with `startValue`, `endValue`, and `onRangeChange`. Tap once to set the start and again to set the end; taps in reverse order are normalized automatically.
+
+```tsx
+import { useState } from 'react';
+import { RangeCalendar } from '@cdx-ui/components';
+import { dateId, type DateId } from '@cdx-ui/formatters';
+
+export default function RangeCalendarBasicDemo() {
+  const [start, setStart] = useState<DateId | undefined>(dateId('2026-07-15'));
+  const [end, setEnd] = useState<DateId | undefined>(dateId('2026-07-20'));
+
+  return (
+    <RangeCalendar
+      startValue={start}
+      endValue={end}
+      onRangeChange={({ startId, endId }) => {
+        setStart(startId);
+        setEnd(endId);
+      }}
+      aria-label="Trip dates"
+      className="w-full max-w-sm"
+    />
+  );
+}
+```
+
+## Date limits
+
+Set `minValue` and `maxValue` to restrict which days can be selected.
+
+```tsx
+import { useState } from 'react';
+import { RangeCalendar } from '@cdx-ui/components';
+import { dateId, monthId, type DateId } from '@cdx-ui/formatters';
+
+export default function RangeCalendarMinMaxDemo() {
+  const [start, setStart] = useState<DateId | undefined>(dateId('2026-08-12'));
+  const [end, setEnd] = useState<DateId | undefined>(dateId('2026-08-18'));
+
+  return (
+    <RangeCalendar
+      startValue={start}
+      endValue={end}
+      onRangeChange={({ startId, endId }) => {
+        setStart(startId);
+        setEnd(endId);
+      }}
+      defaultMonthId={monthId('2026-08-01')}
+      minValue={dateId('2026-08-10')}
+      maxValue={dateId('2026-08-20')}
+      aria-label="Appointment dates"
+      className="w-full max-w-sm"
+    />
+  );
+}
+```
+
+## Disabled
+
+Set `disabled` to render a read-only grid that ignores day presses.
+
+```tsx
+import { RangeCalendar } from '@cdx-ui/components';
+import { dateId } from '@cdx-ui/formatters';
+
+export default function RangeCalendarDisabledDemo() {
+  return (
+    <RangeCalendar
+      startValue={dateId('2026-07-15')}
+      endValue={dateId('2026-07-20')}
+      disabled
+      aria-label="Trip dates"
+      className="w-full max-w-sm"
+    />
+  );
+}
+```
+
+## API
+
+### RangeCalendar
+
+By default, `RangeCalendar` renders a month header with previous/next navigation and a year drill-down, followed by the day grid. Selecting a day while a range is empty or complete starts a new range; the second tap completes it, and an inverted selection is normalized so the earlier day becomes the start. `locale` defaults to `en-US` and controls weekday and month formatting.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the calendar's own styles. |
+| `children?` | `ReactNode` | — | Custom calendar body. Omit to render the default header and month grid. |
+| `asChild?` | `boolean` | — | Render the consumer's child element in place of the default `View` host. |
+| `startValue?` | `DateId` | — | Controlled range start. Setting `startValue` or `endValue` makes the range controlled. |
+| `endValue?` | `DateId` | — | Controlled range end. Setting `startValue` or `endValue` makes the range controlled. |
+| `defaultStartValue?` | `DateId` | — | Initial range start when uncontrolled. |
+| `defaultEndValue?` | `DateId` | — | Initial range end when uncontrolled. |
+| `onRangeChange?` | `((range: { startId?: DateId; endId?: DateId; }) => void)` | — | Called when the user picks a day. The first pick starts a new range with no `endId`; the second completes it, with the two days in date order. |
+| `monthId?` | `MonthId` | — | Controlled visible month. When set, `defaultMonthId` has no effect. |
+| `defaultMonthId?` | `MonthId` | — | Initial visible month when uncontrolled. Defaults to the month of the range, or today. |
+| `onMonthIdChange?` | `((monthId: MonthId) => void)` | — | Called with the new visible month when the user navigates months. |
+| `focusedField?` | `'start' \| 'end'` | — | Controlled active field. The calendar moves it to `'end'` after the first day pick and back to `'start'` after the second. |
+| `defaultFocusedField?` | `'start' \| 'end'` | `'start'` | Initial active field when uncontrolled. |
+| `onFocusedFieldChange?` | `((field: RangeCalendarFocus) => void)` | — | Called with the new active field after each day pick. |
+| `minValue?` | `DateId` | — | Earliest selectable date. Build with `dateId(...)` from `@cdx-ui/formatters`. |
+| `maxValue?` | `DateId` | — | Latest selectable date. Build with `dateId(...)` from `@cdx-ui/formatters`. |
+| `disabled?` | `boolean` | `false` | Prevents day selection and month navigation. |
+| `locale?` | `string` | `'en-US'` | BCP 47 locale for month and weekday names. |
+| `labels?` | `Partial<DateComponentLabels>` | — | Overrides for the built-in UI copy, such as the previous- and next-month button labels. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Accessibility
+
+Pass `accessibilityLabel` to name the calendar for assistive technology; the root carries no landmark role of its own. Days outside the `minValue`–`maxValue` range, and every day while `disabled`, are not selectable.