@cdx-ui/components 0.2.2 → 0.2.4

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

@@ -0,0 +1,505 @@
+# Toggle Button (https://design.candescent.com/docs/components/toggle-button)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/actions-togglebutton--default)
+
+A compound component with sub-components for label, icon, and grouping. Use a toggle button when the pressed state should persist — not a [Switch](https://design.candescent.com/docs/components/switch/content.md) (a settings on/off control) and not a [Tile](https://design.candescent.com/docs/components/tile/content.md) (a pick-from-a-list card).
+
+```tsx
+import { ToggleButton } from '@cdx-ui/components';
+```
+
+## Basic
+
+A standalone toggle. Selection is controlled here with `isSelected` and `onSelectedChange`.
+
+```tsx
+import { useState } from 'react';
+import { ToggleButton } from '@cdx-ui/components';
+import { Star } from '@cdx-ui/icons';
+
+export default function ToggleButtonBasicDemo() {
+  const [favorite, setFavorite] = useState(false);
+
+  return (
+    <ToggleButton value="favorite-payee" isSelected={favorite} onSelectedChange={setFavorite}>
+      <ToggleButton.Icon as={Star} position="leading" />
+      <ToggleButton.Label>Favorite payee</ToggleButton.Label>
+    </ToggleButton>
+  );
+}
+```
+
+## Variants
+
+```tsx
+import { ToggleButton, VStack } from '@cdx-ui/components';
+import { BarChart, PieChart, ShowChart } from '@cdx-ui/icons';
+
+export default function ToggleButtonVariantsDemo() {
+  return (
+    <VStack space="lg">
+      {(['default', 'outline', 'ghost'] as const).map((variant) => (
+        <ToggleButton.Group
+          key={variant}
+          type="single"
+          defaultValue="bar"
+          aria-label={`Spending chart type, ${variant} variant`}
+        >
+          <ToggleButton value="bar" variant={variant} accessibilityLabel="Bar chart">
+            <ToggleButton.Icon as={BarChart} />
+          </ToggleButton>
+          <ToggleButton value="line" variant={variant} accessibilityLabel="Line chart">
+            <ToggleButton.Icon as={ShowChart} />
+          </ToggleButton>
+          <ToggleButton value="pie" variant={variant} accessibilityLabel="Pie chart">
+            <ToggleButton.Icon as={PieChart} />
+          </ToggleButton>
+        </ToggleButton.Group>
+      ))}
+    </VStack>
+  );
+}
+```
+
+## Sizes
+
+```tsx
+import { HStack, ToggleButton } from '@cdx-ui/components';
+import { Star } from '@cdx-ui/icons';
+
+const SIZES = [
+  { size: 'small', label: 'Small' },
+  { size: 'default', label: 'Default' },
+  { size: 'large', label: 'Large' },
+] as const;
+
+export default function ToggleButtonSizesDemo() {
+  return (
+    <HStack space="lg">
+      {SIZES.map(({ size, label }) => (
+        <ToggleButton
+          key={size}
+          value={size}
+          defaultSelected={size === 'default'}
+          size={size}
+          className="self-center"
+        >
+          <ToggleButton.Icon as={Star} position="leading" />
+          <ToggleButton.Label>{label}</ToggleButton.Label>
+        </ToggleButton>
+      ))}
+    </HStack>
+  );
+}
+```
+
+## Shapes
+
+`shape="circle"` is a pill; `shape="rounded"` uses the default corner radius.
+
+```tsx
+import { HStack, ToggleButton, VStack } from '@cdx-ui/components';
+import { BarChart, ShowChart, Star } from '@cdx-ui/icons';
+
+export default function ToggleButtonShapesDemo() {
+  return (
+    <VStack space="2xl">
+      <HStack space="md">
+        <ToggleButton value="circle" defaultSelected shape="circle">
+          <ToggleButton.Icon as={Star} position="leading" />
+          <ToggleButton.Label>Circle</ToggleButton.Label>
+        </ToggleButton>
+        <ToggleButton value="rounded" shape="rounded">
+          <ToggleButton.Icon as={Star} position="leading" />
+          <ToggleButton.Label>Rounded</ToggleButton.Label>
+        </ToggleButton>
+      </HStack>
+      <ToggleButton.Group type="single" defaultValue="bar" aria-label="Spending chart type">
+        <ToggleButton value="bar" shape="circle" accessibilityLabel="Bar chart">
+          <ToggleButton.Icon as={BarChart} />
+        </ToggleButton>
+        <ToggleButton value="line" shape="rounded" accessibilityLabel="Line chart">
+          <ToggleButton.Icon as={ShowChart} />
+        </ToggleButton>
+      </ToggleButton.Group>
+    </VStack>
+  );
+}
+```
+
+## Icon only
+
+A toggle whose only child is `ToggleButton.Icon` renders square, so `shape="circle"` is a true circle. Icon-only toggles need an `accessibilityLabel` because there is no visible text.
+
+```tsx
+import { useState } from 'react';
+import { ToggleButton } from '@cdx-ui/components';
+import { Notifications } from '@cdx-ui/icons';
+
+export default function ToggleButtonIconOnlyDemo() {
+  const [selected, setSelected] = useState(false);
+
+  return (
+    <ToggleButton
+      value="balance-alerts"
+      isSelected={selected}
+      onSelectedChange={setSelected}
+      accessibilityLabel="Low balance alerts"
+      variant="outline"
+    >
+      <ToggleButton.Icon as={Notifications} />
+    </ToggleButton>
+  );
+}
+```
+
+## Icon and label
+
+Use `ToggleButton.Icon` with `position="leading"` or `position="trailing"` next to `ToggleButton.Label`. The toggle's size sets the gap between them. While the toggle is selected, the icon uses its filled variant.
+
+```tsx
+import { useState } from 'react';
+import { ToggleButton } from '@cdx-ui/components';
+import { Bookmark } from '@cdx-ui/icons';
+
+export default function ToggleButtonIconAndLabelDemo() {
+  const [selected, setSelected] = useState(true);
+
+  return (
+    <ToggleButton
+      value="watchlist"
+      isSelected={selected}
+      onSelectedChange={setSelected}
+      variant="outline"
+    >
+      <ToggleButton.Icon as={Bookmark} position="leading" />
+      <ToggleButton.Label>Watchlist</ToggleButton.Label>
+    </ToggleButton>
+  );
+}
+```
+
+## Single selection
+
+`ToggleButton.Group` with `type="single"` behaves like a radio group: one selected item at a time, such as an activity period. Pressing the already-selected item does not clear it. The group's `value` is the selected button's `value`.
+
+```tsx
+import { useState } from 'react';
+import { ToggleButton } from '@cdx-ui/components';
+
+const PERIODS = [
+  { value: '1m', label: '1M', accessibilityLabel: '1 month' },
+  { value: '3m', label: '3M', accessibilityLabel: '3 months' },
+  { value: '6m', label: '6M', accessibilityLabel: '6 months' },
+  { value: '1y', label: '1Y', accessibilityLabel: '1 year' },
+];
+
+export default function ToggleButtonSingleDemo() {
+  const [period, setPeriod] = useState('3m');
+
+  return (
+    <ToggleButton.Group
+      type="single"
+      value={period}
+      onValueChange={setPeriod}
+      aria-label="Activity period"
+    >
+      {PERIODS.map(({ value, label, accessibilityLabel }) => (
+        <ToggleButton key={value} value={value} accessibilityLabel={accessibilityLabel}>
+          <ToggleButton.Label>{label}</ToggleButton.Label>
+        </ToggleButton>
+      ))}
+    </ToggleButton.Group>
+  );
+}
+```
+
+## Multiple selection
+
+`type="multiple"` lets several buttons stay pressed, such as independent text formats in a secure message. The group's `value` is an array of selected button `value`s.
+
+```tsx
+import { useState } from 'react';
+import { ToggleButton } from '@cdx-ui/components';
+import { FormatBold, FormatItalic, FormatUnderlined } from '@cdx-ui/icons';
+
+export default function ToggleButtonMultipleDemo() {
+  const [value, setValue] = useState<string[]>(['bold', 'underline']);
+
+  return (
+    <ToggleButton.Group
+      type="multiple"
+      value={value}
+      onValueChange={setValue}
+      aria-label="Message formatting"
+    >
+      <ToggleButton value="bold" accessibilityLabel="Bold">
+        <ToggleButton.Icon as={FormatBold} />
+      </ToggleButton>
+      <ToggleButton value="italic" accessibilityLabel="Italic">
+        <ToggleButton.Icon as={FormatItalic} />
+      </ToggleButton>
+      <ToggleButton value="underline" accessibilityLabel="Underline">
+        <ToggleButton.Icon as={FormatUnderlined} />
+      </ToggleButton>
+    </ToggleButton.Group>
+  );
+}
+```
+
+## Attached
+
+Groups are a single segmented control by default (`isAttached`). Set `isAttached={false}` to render separate buttons with a gap.
+
+```tsx
+import { Text, ToggleButton, VStack } from '@cdx-ui/components';
+
+function FrequencyGroup({ isAttached }: { isAttached: boolean }) {
+  return (
+    <ToggleButton.Group
+      type="single"
+      defaultValue="once"
+      isAttached={isAttached}
+      aria-label="Transfer frequency"
+    >
+      <ToggleButton value="once">
+        <ToggleButton.Label>One time</ToggleButton.Label>
+      </ToggleButton>
+      <ToggleButton value="weekly">
+        <ToggleButton.Label>Weekly</ToggleButton.Label>
+      </ToggleButton>
+      <ToggleButton value="monthly">
+        <ToggleButton.Label>Monthly</ToggleButton.Label>
+      </ToggleButton>
+    </ToggleButton.Group>
+  );
+}
+
+export default function ToggleButtonAttachedDemo() {
+  return (
+    <VStack space="lg">
+      <VStack space="sm">
+        <Text size="sm" color="secondary">
+          Attached (default)
+        </Text>
+        <FrequencyGroup isAttached />
+      </VStack>
+      <VStack space="sm">
+        <Text size="sm" color="secondary">
+          Detached
+        </Text>
+        <FrequencyGroup isAttached={false} />
+      </VStack>
+    </VStack>
+  );
+}
+```
+
+## Controlled
+
+Drive selection from parent state with `isSelected` and `onSelectedChange` when the toggle affects other UI, such as masking an account balance. Keep the label constant; the selected state already tells assistive technology whether it is on.
+
+```tsx
+import { useState } from 'react';
+import { CurrencyInput, Heading, Text, ToggleButton, VStack } from '@cdx-ui/components';
+import { VisibilityOff } from '@cdx-ui/icons';
+
+export default function ToggleButtonControlledDemo() {
+  const [hideBalance, setHideBalance] = useState(false);
+
+  return (
+    <VStack space="md" className="items-center">
+      <VStack space="xs" className="items-center">
+        <Text size="sm" color="secondary">
+          Everyday Checking ••4821
+        </Text>
+        {hideBalance ? (
+          <Heading size="lg" accessibilityLabel="Balance hidden" className="py-0.5">
+            $•,•••.••
+          </Heading>
+        ) : (
+          <CurrencyInput
+            accessibilityLabel="Everyday Checking balance"
+            isReadOnly
+            size="small"
+            value={4218.53}
+          />
+        )}
+      </VStack>
+      <ToggleButton
+        value="hide-balance"
+        isSelected={hideBalance}
+        onSelectedChange={setHideBalance}
+        variant="outline"
+        size="small"
+        className="self-center"
+      >
+        <ToggleButton.Icon as={VisibilityOff} position="leading" />
+        <ToggleButton.Label>Hide balance</ToggleButton.Label>
+      </ToggleButton>
+    </VStack>
+  );
+}
+```
+
+## Vertical
+
+Set `orientation="vertical"` to stack the group and map arrow keys to up/down.
+
+```tsx
+import { ToggleButton } from '@cdx-ui/components';
+
+export default function ToggleButtonVerticalDemo() {
+  return (
+    <ToggleButton.Group
+      type="single"
+      orientation="vertical"
+      defaultValue="statement"
+      aria-label="Payment amount"
+    >
+      <ToggleButton value="minimum" shape="rounded">
+        <ToggleButton.Label>Minimum due · $35.00</ToggleButton.Label>
+      </ToggleButton>
+      <ToggleButton value="statement" shape="rounded">
+        <ToggleButton.Label>Statement balance · $1,284.62</ToggleButton.Label>
+      </ToggleButton>
+      <ToggleButton value="current" shape="rounded">
+        <ToggleButton.Label>Current balance · $1,402.19</ToggleButton.Label>
+      </ToggleButton>
+    </ToggleButton.Group>
+  );
+}
+```
+
+## Disabled
+
+Set `isDisabled` on `ToggleButton.Group` to disable every item, or on a single `ToggleButton`.
+
+```tsx
+import { ToggleButton, VStack } from '@cdx-ui/components';
+
+export default function ToggleButtonDisabledDemo() {
+  return (
+    <VStack space="lg">
+      <ToggleButton.Group type="single" value="monthly" aria-label="Transfer frequency" isDisabled>
+        <ToggleButton value="once">
+          <ToggleButton.Label>One time</ToggleButton.Label>
+        </ToggleButton>
+        <ToggleButton value="weekly">
+          <ToggleButton.Label>Weekly</ToggleButton.Label>
+        </ToggleButton>
+        <ToggleButton value="monthly">
+          <ToggleButton.Label>Monthly</ToggleButton.Label>
+        </ToggleButton>
+      </ToggleButton.Group>
+      <ToggleButton.Group type="single" defaultValue="3m" aria-label="Activity period">
+        <ToggleButton value="1m" accessibilityLabel="1 month">
+          <ToggleButton.Label>1M</ToggleButton.Label>
+        </ToggleButton>
+        <ToggleButton value="3m" accessibilityLabel="3 months">
+          <ToggleButton.Label>3M</ToggleButton.Label>
+        </ToggleButton>
+        <ToggleButton value="1y" isDisabled accessibilityLabel="1 year">
+          <ToggleButton.Label>1Y</ToggleButton.Label>
+        </ToggleButton>
+      </ToggleButton.Group>
+    </VStack>
+  );
+}
+```
+
+## API
+
+### ToggleButton
+
+Pressable root that toggles a persisted selected state. Requires a unique `value`. Inside a `ToggleButton.Group`, selection is owned by the group (`value` / `defaultValue` match each button's `value`); standalone usage supports `isSelected` / `defaultSelected` / `onSelectedChange`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | Either children or a render prop that receives a boolean reflecting whether the component is currently pressed. |
+| `variant?` | `'default' \| 'outline' \| 'ghost'` | `'default'` | Visual style. `default` is a muted filled surface; `outline` adds a border; `ghost` is transparent. |
+| `shape?` | `'circle' \| 'rounded'` | `'circle'` | Corner geometry — mirrors `Avatar.shape`. |
+| `size?` | `'default' \| 'small' \| 'large'` | `'default'` | Height and padding scale. |
+| `asChild?` | `boolean` | — | Render the consumer's child in place of the default `Pressable` host. |
+| `value` | `string` | — | Identifies this button within a `ToggleButtonGroup`. Must be unique within the group. Standalone buttons still require a value. |
+| `isSelected?` | `boolean` | — | Controlled selected state (standalone only; ignored inside `ToggleButtonGroup`). |
+| `defaultSelected?` | `boolean` | `false` | Uncontrolled initial selected state (standalone only). |
+| `onSelectedChange?` | `((isSelected: boolean) => void)` | — | Called when standalone selected state changes. |
+| `isDisabled?` | `boolean` | `false` | — |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props) (including `onPress`).
+
+## Sub-components
+
+### ToggleButton.Label
+
+Text label inside the toggle. Inherits size from the parent and selected/hover/press color from toggle state.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+| `asChild?` | `boolean` | — | Render the consumer's child in place of the default `Text` host. |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### ToggleButton.Icon
+
+Renders a Forge icon. Inherits size and selected/hover/press color from the parent. While the toggle is selected, the icon uses its filled variant; pass `filled` to override. Icon-only usage must pass `accessibilityLabel` on `ToggleButton`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Utility classes for size (`size-*`) and placement, merged after the defaults. |
+| `filled?` | `boolean` | — | Render the filled icon variant. Defaults to the toggle's selected state. Icons without filled path data stay 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` | — | Forge icon component to render. |
+| `asChild?` | `boolean` | — | Render a custom element instead of the default icon. |
+| `position?` | `'leading' \| 'trailing'` | — | Leading or trailing placement relative to the label. |
+
+Inherits all `ForgeIconProps` (react-native-svg `SvgProps` plus `filled` and `size`).
+
+### ToggleButton.Group
+
+Selection state container and layout. `type="single"` uses radio semantics (group `value` is the selected button's `value`); `type="multiple"` uses pressed-button semantics (group `value` is an array of selected `value`s). `isAttached` defaults to `true` (segmented).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `(React.ReactNode & (React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>[]))` | — | — |
+| `orientation?` | `'horizontal' \| 'vertical'` | — | — |
+| `isAttached?` | `boolean` | — | — |
+| `type?` | `'single' \| 'multiple'` | — | — |
+| `value?` | `string \| string[]` | — | — |
+| `defaultValue?` | `string \| string[]` | — | — |
+| `onValueChange?` | `((value: string) => void) \| ((value: string[]) => void)` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `isDisabled?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props). `ToggleButton.Group` is a discriminated union on `type`.
+
+| `type`             | `value` shape | Item role                    |
+| ------------------ | ------------- | ---------------------------- |
+| `single` (default) | `string`      | `radio` in a `radiogroup`    |
+| `multiple`         | `string[]`    | `button` with `aria-pressed` |
+
+## Anatomy
+
+| `data-slot`           | Element         |
+| --------------------- | --------------- |
+| `toggle-button`       | Root pressable  |
+| `toggle-button-label` | Text label      |
+| `toggle-button-icon`  | Icon            |
+| `toggle-button-group` | Selection group |
+
+## Accessibility
+
+| Attribute                   | Behavior                                                                                                                                                                                                                                                               |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Standalone role**         | `button` with `aria-pressed` reflecting selected state.                                                                                                                                                                                                                |
+| **Group `type="single"`**   | Group is `radiogroup`; each item is `radio` with `aria-checked`.                                                                                                                                                                                                       |
+| **Group `type="multiple"`** | Group is `group`; each item is `button` with `aria-pressed`.                                                                                                                                                                                                           |
+| **`aria-label`**            | Required on the group when there is no visible group label. Required on icon-only buttons.                                                                                                                                                                             |
+| **Keyboard**                | Standalone: Space/Enter toggles. Grouped (web): the group is a single tab stop; arrow keys (following `orientation`) and Home/End move focus, skipping disabled items. With `type="single"`, moving focus also selects the item. Space/Enter toggles the focused item. |
+| **Disabled**                | `isDisabled` on an item or the group sets `aria-disabled` and blocks press.                                                                                                                                                                                            |