@cdx-ui/components 0.2.3 → 0.2.5

package/docs/components/select/content.md

@@ -0,0 +1,473 @@
+# Select (https://design.candescent.com/docs/components/select)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=427-2296), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-select--default)
+
+`Select` provides a compound interface for a trigger, selected value, dropdown content, and options.
+
+```tsx
+import { Button, Icon, Select } from '@cdx-ui/components';
+import { CheckCircle, KeyboardArrowDown } from '@cdx-ui/icons';
+```
+
+## Basic
+
+Provide the same options to `items` and render them as `Select.Item` children so value labels and keyboard navigation stay in sync.
+
+```tsx
+import { Select } from '@cdx-ui/components';
+import { accounts } from './_data';
+
+export default function SelectBasicDemo() {
+  return (
+    <Select items={accounts} className="w-full" accessibilityLabel="Account type">
+      <Select.Trigger>
+        <Select.Value placeholder="Select an account…" />
+      </Select.Trigger>
+      <Select.Content>
+        {accounts.map((account) => (
+          <Select.Item key={account.value} value={account.value}>
+            <Select.ItemLabel>{account.label}</Select.ItemLabel>
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select>
+  );
+}
+```
+
+## Sizes
+
+Use the default size for most forms and `small` for compact layouts.
+
+```tsx
+import { Box, Select, Text, type SelectProps } from '@cdx-ui/components';
+import { accounts } from './_data';
+
+const sizes = ['default', 'small'] as const satisfies readonly NonNullable<SelectProps['size']>[];
+
+export default function SelectSizesDemo() {
+  return (
+    <Box className="w-full gap-4">
+      {sizes.map((size) => (
+        <Box key={size} className="gap-2">
+          <Text size="sm" color="secondary">
+            {size}
+          </Text>
+          <Select
+            items={accounts}
+            size={size}
+            defaultValue="savings"
+            accessibilityLabel={`${size} account type`}
+          >
+            <Select.Trigger>
+              <Select.Value placeholder="Select an account…" />
+            </Select.Trigger>
+            <Select.Content>
+              {accounts.map((account) => (
+                <Select.Item key={account.value} value={account.value}>
+                  <Select.ItemLabel>{account.label}</Select.ItemLabel>
+                </Select.Item>
+              ))}
+            </Select.Content>
+          </Select>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## With field
+
+Compose with `Field` to provide a visible label, helper text, and shared required or validation state.
+
+```tsx
+import { Field, Select } from '@cdx-ui/components';
+import { accounts } from './_data';
+
+export default function SelectWithFieldDemo() {
+  return (
+    <Field className="w-full" isRequired>
+      <Field.Label>Account type</Field.Label>
+      <Select items={accounts} isRequired>
+        <Select.Trigger>
+          <Select.Value placeholder="Select an account…" />
+        </Select.Trigger>
+        <Select.Content>
+          {accounts.map((account) => (
+            <Select.Item key={account.value} value={account.value}>
+              <Select.ItemLabel>{account.label}</Select.ItemLabel>
+            </Select.Item>
+          ))}
+        </Select.Content>
+      </Select>
+      <Field.Helper>Choose the account type to open.</Field.Helper>
+    </Field>
+  );
+}
+```
+
+## Custom trigger
+
+Set `asChild` on `Select.Trigger` to use a Forge pressable such as `Button`, `IconButton`, or `Chip`. Use the trigger and item `indicator` props to replace their default icons, or pass `null` to suppress an indicator.
+
+```tsx
+import { Button, Icon, Select } from '@cdx-ui/components';
+import { CheckCircle, KeyboardArrowDown } from '@cdx-ui/icons';
+import { accounts } from './_data';
+
+export default function SelectCustomTriggerDemo() {
+  return (
+    <Select items={accounts} accessibilityLabel="Filter accounts">
+      <Select.Trigger
+        asChild
+        indicator={<Button.Icon as={KeyboardArrowDown} position="trailing" />}
+      >
+        <Button variant="outline">
+          <Button.Label>Filter accounts</Button.Label>
+        </Button>
+      </Select.Trigger>
+      <Select.Content className="min-w-64">
+        {accounts.map((account) => (
+          <Select.Item
+            key={account.value}
+            value={account.value}
+            indicator={<Icon as={CheckCircle} color="action" />}
+          >
+            <Select.ItemLabel>{account.label}</Select.ItemLabel>
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select>
+  );
+}
+```
+
+## Custom value display
+
+Pass children to `Select.Value` to replace the default label. Read the selected option from your own state, and render the placeholder by leaving the children empty when nothing is selected.
+
+```tsx
+import { useState } from 'react';
+import { Select, Text } from '@cdx-ui/components';
+import { accountDetails } from './_data';
+
+export default function SelectCustomValueDemo() {
+  const [value, setValue] = useState<string>();
+  const selected = accountDetails.find((account) => account.value === value);
+
+  return (
+    <Select
+      items={accountDetails}
+      value={value}
+      onValueChange={setValue}
+      accessibilityLabel="Account"
+      className="w-full"
+    >
+      <Select.Trigger>
+        <Select.Value placeholder="Select an account…">
+          {selected && (
+            <>
+              {selected.label} <Text color="secondary">{selected.mask}</Text>
+            </>
+          )}
+        </Select.Value>
+      </Select.Trigger>
+      <Select.Content>
+        {accountDetails.map((account) => (
+          <Select.Item key={account.value} value={account.value}>
+            <Select.ItemLabel>{account.label}</Select.ItemLabel>
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select>
+  );
+}
+```
+
+## Custom item display
+
+Compose any content inside `Select.Item` to show more than a label, such as a secondary line. Keep `Select.ItemLabel` for the primary text so the selected state and keyboard navigation stay in sync.
+
+```tsx
+import { Select, Text, VStack } from '@cdx-ui/components';
+import { accountDetails } from './_data';
+
+export default function SelectCustomItemDemo() {
+  return (
+    <Select items={accountDetails} accessibilityLabel="Account" className="w-full">
+      <Select.Trigger>
+        <Select.Value placeholder="Select an account…" />
+      </Select.Trigger>
+      <Select.Content>
+        {accountDetails.map((account) => (
+          <Select.Item key={account.value} value={account.value}>
+            <VStack className="flex-1">
+              <Select.ItemLabel>{account.label}</Select.ItemLabel>
+              <Text size="sm" color="secondary">
+                {account.mask} · {account.balance}
+              </Text>
+            </VStack>
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select>
+  );
+}
+```
+
+## Placement
+
+The default placement is `bottom-start`. Choose a side alone to center the overlay, or append `-start` or `-end` to align it with the corresponding edge of the trigger. The requested side is preferred rather than guaranteed: when the overlay would overflow the viewport it still flips to the opposite side and shifts along the cross axis.
+
+```tsx
+import { Box, Select, Text, type SelectContentProps } from '@cdx-ui/components';
+import { accounts } from './_data';
+
+interface PlacementSelectProps {
+  placement: NonNullable<SelectContentProps['placement']>;
+}
+
+const PLACEMENT_GROUPS = [
+  {
+    label: 'Top',
+    placements: ['top-start', 'top', 'top-end'],
+  },
+  {
+    label: 'Right',
+    placements: ['right-start', 'right', 'right-end'],
+  },
+  {
+    label: 'Bottom',
+    placements: ['bottom-start', 'bottom', 'bottom-end'],
+  },
+  {
+    label: 'Left',
+    placements: ['left-start', 'left', 'left-end'],
+  },
+] as const satisfies readonly {
+  label: string;
+  placements: readonly PlacementSelectProps['placement'][];
+}[];
+
+function PlacementSelect({ placement }: PlacementSelectProps) {
+  return (
+    <Select
+      items={accounts}
+      className="min-w-0 flex-1"
+      accessibilityLabel={`${placement} account type`}
+    >
+      <Select.Trigger>
+        <Select.Value placeholder={placement} />
+      </Select.Trigger>
+      <Select.Content placement={placement}>
+        {accounts.map((account) => (
+          <Select.Item key={account.value} value={account.value}>
+            <Select.ItemLabel>{account.label}</Select.ItemLabel>
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select>
+  );
+}
+
+export default function SelectPlacementDemo() {
+  return (
+    <Box className="w-full max-w-140 gap-6">
+      {PLACEMENT_GROUPS.map(({ label, placements }) => (
+        <Box key={label} className="w-full items-center gap-2">
+          <Text size="sm" color="secondary">
+            {label}
+          </Text>
+          <Box className="w-full flex-row gap-2">
+            {placements.map((placement) => (
+              <PlacementSelect key={placement} placement={placement} />
+            ))}
+          </Box>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## API
+
+### Select
+
+The root manages the selected value, open state, options, and form-control state.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `variant?` | `'outline' \| null` | — | — |
+| `size?` | `'default' \| 'small' \| null` | — | — |
+| `items` | `SelectItemData[]` | — | Options used to resolve `Select.Value` labels and drive keyboard navigation. Render matching `Select.Item` elements inside `Select.Content`. |
+| `value?` | `string` | — | — |
+| `defaultValue?` | `string` | — | — |
+| `onValueChange?` | `((value: string) => void)` | — | — |
+| `isOpen?` | `boolean` | — | Controlled open state. Use `defaultOpen` for the uncontrolled variant. |
+| `defaultOpen?` | `boolean` | — | — |
+| `onOpenChange?` | `((open: boolean) => void)` | — | — |
+| `disabled?` | `boolean` | — | — |
+| `isRequired?` | `boolean` | — | — |
+| `isInvalid?` | `boolean` | — | — |
+| `isReadOnly?` | `boolean` | — | — |
+| `native?` | `boolean` | — | Prevents `Select.Content` from rendering. Reserved for native picker integration. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute       | Values            | Description     |
+| --------------- | ----------------- | --------------- |
+| `data-slot`     | `select`          | Root container  |
+| `data-disabled` | `true` \| `false` | Disabled state  |
+| `data-required` | `true` \| `false` | Required state  |
+| `data-invalid`  | `true` \| `false` | Invalid state   |
+| `data-readonly` | `true` \| `false` | Read-only state |
+
+## Sub-components
+
+### Select.Trigger
+
+Pressable that opens and closes the dropdown. By default it appends a chevron that reflects the open state. The `indicator` prop replaces that chevron, and `indicator={null}` suppresses it. An `asChild` trigger keeps its existing children unless an indicator is explicitly provided.
+
+| 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. |
+| `asChild?` | `boolean` | — | Substitute the rendered trigger element with the single child. The child must be another Forge primitive (IconButton, Chip, Button) — anything whose underlying Pressable accepts Pressable-shaped handlers. When set, the auto-injected arrow indicator is skipped and `selectTriggerVariants` is not applied so the substituted component's own appearance wins. On web, `<label htmlFor>` association is preserved via a `focus()` bridge registered by the primitive. NOTE — `data-slot` overlap: the substituted component's own `data-slot` (e.g. `button`, `icon-button`, `chip`) may win on the merged element. Selectors that need guaranteed `select-trigger` access should wrap the trigger instead of relying on `data-slot`. |
+| `indicator?` | `ReactNode` | — | Replaces the default open/closed chevron. Pass `null` to suppress the indicator. When `asChild` is set, only an explicitly provided indicator is appended to the substituted child. |
+| `isHovered?` | `boolean` | — | — |
+| `isActive?` | `boolean` | — | — |
+| `isFocused?` | `boolean` | — | — |
+| `isFocusVisible?` | `boolean` | — | — |
+| `isDisabled?` | `boolean` | — | — |
+| `aria-describedby?` | `string` | — | — |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props).
+
+| Attribute          | Values                                                | Description                                                                              |
+| ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `data-slot`        | `select-trigger`                                      | Trigger element; a substituted child's own slot may take precedence when using `asChild` |
+| `data-state`       | `open` \| `closed`                                    | Dropdown state                                                                           |
+| `data-focus`       | `true` \| `false`                                     | Focus state                                                                              |
+| `data-active`      | `true` \| `false`                                     | Pressed state                                                                            |
+| `data-disabled`    | `true` \| `false`                                     | Disabled state                                                                           |
+| `data-required`    | `true` \| `false`                                     | Required state                                                                           |
+| `data-invalid`     | `true` \| `false`                                     | Invalid state                                                                            |
+| `data-readonly`    | `true` \| `false`                                     | Read-only state                                                                          |
+| `data-field-state` | `idle` \| `invalid` \| `focused` \| `focused-invalid` | Combined focus and validation state                                                      |
+
+### Select.Value
+
+Displays the label from `items` that matches the selected value, or the placeholder when no value is selected.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `placeholder?` | `string` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+On web viewports below 600px, value text renders at 16px (`text-base`) for both sizes so it matches
+`Input` and `Textarea` and iOS Safari does not auto-zoom the page when the trigger is focused. At
+600px and above, web matches native sizes (14px default, 12px small).
+
+### Select.Icon
+
+Renders a Forge icon sized to the select. Use it as the `indicator` value when a replacement should retain Select icon sizing and state styling.
+
+| 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` | — | Forge icon component to render. Required unless `asChild` is set, in which case the consumer's substituted element is rendered instead. |
+| `asChild?` | `boolean` | — | — |
+| `position?` | `'leading' \| 'trailing'` | — | Position hint that emits `data-icon="inline-start"` or `data-icon="inline-end"`. CVA uses this attribute to apply leading/trailing padding logically (RTL-aware). Omit to apply the symmetric baseline gap. |
+
+Inherits all `ForgeIconProps` (react-native-svg `SvgProps` plus `filled` and `size`).
+
+### Select.Content
+
+Dropdown panel that positions itself around the trigger, scrolls long option lists, and closes when dismissed.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `placement?` | `'auto' \| 'auto-start' \| 'auto-end' \| 'top' \| 'top-start' \| 'top-end' \| 'right' \| 'right-start' \| 'right-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end'` | — | Preferred dropdown placement relative to the trigger. Defaults to `bottom-start`. |
+| `offset?` | `number` | — | Distance between the trigger and dropdown in pixels. Defaults to 4. |
+| `crossOffset?` | `number` | — | Cross-axis adjustment from the aligned dropdown position in pixels. Defaults to 0. |
+| `enteringAnimation?` | `EntryOrExitLayoutType` | — | Enter animation for the dropdown. Defaults to a 150ms fade. |
+| `exitingAnimation?` | `EntryOrExitLayoutType` | — | Exit animation for the dropdown. Defaults to a 100ms fade. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Select.Item
+
+An individual option. Its `value` must match an entry in the root `items` array. The `indicator` prop replaces the default selected-item checkmark, and `indicator={null}` suppresses it.
+
+| 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. |
+| `disabled?` | `boolean` | — | Whether the press behavior is disabled. |
+| `asChild?` | `boolean` | — | — |
+| `indicator?` | `ReactNode` | — | Replaces the default selected-item checkmark. The replacement is rendered only while the item is selected. Pass `null` to suppress the indicator. |
+| `value` | `string` | — | — |
+| `isHovered?` | `boolean` | — | — |
+| `isActive?` | `boolean` | — | — |
+| `isFocused?` | `boolean` | — | — |
+| `isFocusVisible?` | `boolean` | — | — |
+| `isDisabled?` | `boolean` | — | — |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props).
+
+| Attribute            | Values                   | Description                        |
+| -------------------- | ------------------------ | ---------------------------------- |
+| `data-slot`          | `select-item`            | Option element                     |
+| `data-state`         | `checked` \| `unchecked` | Selection state                    |
+| `data-highlighted`   | `true` \| `false`        | Current keyboard-navigation target |
+| `data-hover`         | `true` \| `false`        | Hover state                        |
+| `data-focus`         | `true` \| `false`        | Focus state                        |
+| `data-active`        | `true` \| `false`        | Pressed state                      |
+| `data-disabled`      | `true` \| `false`        | Disabled state                     |
+| `data-focus-visible` | `true` \| `false`        | Keyboard focus ring                |
+
+### Select.ItemLabel
+
+Text label rendered inside a `Select.Item`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+## Anatomy
+
+| `data-slot`         | Element                       |
+| ------------------- | ----------------------------- |
+| `select`            | Root container                |
+| `select-trigger`    | Dropdown trigger              |
+| `select-value`      | Selected label or placeholder |
+| `select-icon`       | Dropdown indicator            |
+| `select-content`    | Dropdown panel                |
+| `select-item`       | Option                        |
+| `select-item-label` | Option label                  |
+
+## Accessibility
+
+The trigger uses `role="combobox"` with `aria-haspopup="listbox"`, reflects open, required, invalid, and read-only state, and points to the dropdown content. The content uses `role="listbox"` and each item uses `role="option"` with selected and disabled state.
+
+Compose with `Field.Label` for a visible associated label. When no visible label is present, provide `accessibilityLabel` on `Select`.
+
+On web, Enter, Space, Arrow Down, or Arrow Up opens the dropdown. Arrow keys, Home, and End move through enabled options; Enter or Space selects; Escape closes; and Tab closes while continuing focus navigation.