@cdx-ui/components 0.3.2 → 0.3.4

package/docs/components/insight-stack/content.md

@@ -0,0 +1,231 @@
+# Insight Stack (https://design.candescent.com/docs/components/insight-stack)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=13652-32306), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/surfaces-insightstack--default)
+
+`InsightStack` wraps a summary [`Insight`](https://design.candescent.com/docs/components/insight/content.md) and draws up to two cards behind it, so a single card on Home can stand for a list of insights. The layers are decorative and never interactive.
+
+```tsx
+import { InsightStack } from '@cdx-ui/components';
+```
+
+## Basic
+
+Pass the number of insights as `count`. The layers don't announce it, so include the count in the front Insight's accessible label.
+
+```tsx
+import { Box, Insight, InsightStack } from '@cdx-ui/components';
+
+const insightCount = 3;
+const summary = 'Your spending this month is 12% lower than last month.';
+
+export default function InsightStackBasicDemo() {
+  return (
+    <Box className="w-full max-w-md">
+      <InsightStack count={insightCount}>
+        <Insight
+          aiGenerated
+          onPress={() => {}}
+          accessibilityLabel={`${summary} ${insightCount} insights.`}
+        >
+          <Insight.Description>{summary}</Insight.Description>
+        </Insight>
+      </InsightStack>
+    </Box>
+  );
+}
+```
+
+## Item count
+
+A `count` of 1 draws no layers, 2 draws one, and 3 or more draws two. When pressed, only the front Insight scales; the layers stay still.
+
+```tsx
+import { Box, Insight, InsightStack } from '@cdx-ui/components';
+
+const counts = [1, 2, 3] as const;
+
+export default function InsightStackCountsDemo() {
+  return (
+    <Box className="w-full max-w-md gap-4">
+      {counts.map((count) => {
+        const summary = count === 1 ? 'You have 1 new insight.' : `You have ${count} new insights.`;
+
+        return (
+          <InsightStack key={count} count={count}>
+            <Insight onPress={() => {}}>
+              <Insight.Description>{summary}</Insight.Description>
+            </Insight>
+          </InsightStack>
+        );
+      })}
+    </Box>
+  );
+}
+```
+
+## Colors
+
+The layers are always neutral. The front Insight's `color` and `aiGenerated` tint only the front card.
+
+```tsx
+import { Box, Insight, InsightStack } from '@cdx-ui/components';
+
+const stacks = [
+  { key: 'warning', color: 'warning', count: 2, copy: 'You have 2 bills due before payday.' },
+  { key: 'danger', color: 'danger', count: 3, copy: 'You have 3 overdue payments.' },
+  { key: 'ai', color: 'info', count: 3, copy: 'You have 3 new ways to save.', aiGenerated: true },
+] as const;
+
+export default function InsightStackColorsDemo() {
+  return (
+    <Box className="w-full max-w-md gap-4">
+      {stacks.map((stack) => (
+        <InsightStack key={stack.key} count={stack.count}>
+          <Insight color={stack.color} aiGenerated={'aiGenerated' in stack} onPress={() => {}}>
+            <Insight.Description>{stack.copy}</Insight.Description>
+          </Insight>
+        </InsightStack>
+      ))}
+    </Box>
+  );
+}
+```
+
+## Dismissible
+
+Pass the number of insights left as `count`, so the layers drop away as the user dismisses cards. Keep rendering the same front Insight and swap its copy, so `ref.current?.focus()` returns focus to it after each dismissal. When none is left, remove the stack and move focus elsewhere, here to the button below it.
+
+```tsx
+import { useRef, useState, type ComponentRef } from 'react';
+import { Box, Button, Insight, InsightStack, Text } from '@cdx-ui/components';
+
+const insights = [
+  { id: 'spending', copy: 'Your spending this month is 12% lower than last month.' },
+  { id: 'subscriptions', copy: 'You have three subscriptions renewing in the next seven days.' },
+  { id: 'savings', copy: 'You could save $45.00 a month with annual billing.' },
+  { id: 'paycheck', copy: 'Your paycheck arrived a day early.' },
+];
+
+export default function InsightStackDismissibleDemo() {
+  const [remaining, setRemaining] = useState(insights);
+  const insightRef = useRef<ComponentRef<typeof Insight>>(null);
+  const restoreRef = useRef<ComponentRef<typeof Button>>(null);
+  const front = remaining.at(0);
+  const count = remaining.length;
+
+  const dismiss = () => {
+    setRemaining((current) => current.slice(1));
+    if (count > 1) {
+      insightRef.current?.focus();
+    } else {
+      restoreRef.current?.focus();
+    }
+  };
+
+  return (
+    <Box className="w-full max-w-md gap-4">
+      {front ? (
+        <InsightStack count={count}>
+          <Insight
+            ref={insightRef}
+            aiGenerated
+            onPress={() => {}}
+            onClose={dismiss}
+            accessibilityLabel={`${front.copy} ${count} ${count === 1 ? 'insight' : 'insights'}.`}
+          >
+            <Insight.Description>{front.copy}</Insight.Description>
+          </Insight>
+        </InsightStack>
+      ) : (
+        <Box className="min-h-14 justify-center">
+          <Text color="secondary">{"You're all caught up."}</Text>
+        </Box>
+      )}
+      <Box className="items-start">
+        <Button
+          ref={restoreRef}
+          variant="outline"
+          size="small"
+          onPress={() => setRemaining(insights)}
+        >
+          <Button.Label>Restore insights</Button.Label>
+        </Button>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Detail
+
+The front card can also be a detail Insight. The layers follow its height, so they peek below it however tall it grows.
+
+```tsx
+import { Box, Button, Insight, InsightStack } from '@cdx-ui/components';
+
+export default function InsightStackDetailDemo() {
+  return (
+    <Box className="w-full max-w-md gap-6">
+      <InsightStack count={3}>
+        <Insight layout="detail" onClose={() => {}}>
+          <Insight.Tag>Spending</Insight.Tag>
+          <Insight.Header>
+            <Insight.Title>Dining is trending higher</Insight.Title>
+            <Insight.Description>
+              You have spent $320.00 of your $400.00 dining budget, with 10 days left this month.
+            </Insight.Description>
+          </Insight.Header>
+          <Insight.Footer>
+            <Button variant="outline" size="small">
+              <Button.Label>View transactions</Button.Label>
+            </Button>
+            <Button size="small">
+              <Button.Label>Adjust budget</Button.Label>
+            </Button>
+          </Insight.Footer>
+        </Insight>
+      </InsightStack>
+      <InsightStack count={2}>
+        <Insight layout="detail" aiGenerated onClose={() => {}}>
+          <Insight.Tag>Savings</Insight.Tag>
+          <Insight.Header>
+            <Insight.Title>Grow your emergency fund</Insight.Title>
+            <Insight.Description>
+              Setting aside $150.00 each payday would reach your savings goal by June.
+            </Insight.Description>
+          </Insight.Header>
+          <Insight.Footer>
+            <Button size="small">
+              <Button.Label>Set up transfer</Button.Label>
+            </Button>
+          </Insight.Footer>
+        </Insight>
+      </InsightStack>
+    </Box>
+  );
+}
+```
+
+## API
+
+### InsightStack
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | The front card, usually a summary `Insight`. |
+| `count` | `number` | — | How many insights the stack stands for. `1` or less draws no layers, `2` draws one, and `3` or more draws two. The layers are decorative, so put the count in the front Insight's accessible label or hint. |
+| `asChild?` | `boolean` | — | Merges the root props onto a single child element instead of rendering a `View`. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Anatomy
+
+| `data-slot`           | Element                                  |
+| --------------------- | ---------------------------------------- |
+| `insight-stack`       | Root                                     |
+| `insight-stack-layer` | Decorative card behind the front Insight |
+
+## Accessibility
+
+The root adds no role, so the front Insight stays the only interactive element. The layers are hidden from assistive tech, so `count` is not announced. Include the count in the front Insight's accessible label, for example by appending "3 insights" to its copy in `accessibilityLabel`, or in its `accessibilityHint`.

package/docs/components/insurance-disclosure/content.md

@@ -1,4 +1,4 @@
-# FDIC Digital Sign (https://design.candescent.com/docs/components/insurance-disclosure)
+# Insurance Disclosure (https://design.candescent.com/docs/components/insurance-disclosure)
 
 Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=8550-3291), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/domain-insurancedisclosure--default)
 

package/docs/components/otp-input/content.md

@@ -1,4 +1,4 @@
-# OTP Input Field (https://design.candescent.com/docs/components/otp-input)
+# OTP Input (https://design.candescent.com/docs/components/otp-input)
 
 Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=5653-5035), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-otpinput--default)
 
@@ -298,7 +298,7 @@ Styled cell chrome built on `Input`. Inherits variant and size from the parent `
 | --- | --- | --- | --- |
 | `className?` | `string` | — | — |
 | `children?` | `React.ReactNode` | — | — |
-| `variant?` | `'outline' \| null` | — | — |
+| `variant?` | `'outline'` | — | — |
 | `size?` | `'default' \| 'small' \| null` | — | — |
 | `isInvalid?` | `boolean` | — | — |
 | `isReadOnly?` | `boolean` | — | — |

package/docs/components/select/content.md

@@ -107,6 +107,120 @@ export default function SelectWithFieldDemo() {
 }
 ```
 
+## Multiple selection
+
+Set `type="multiple"` to let users pick several options. `value` becomes a `string[]`, each press toggles an option and keeps the dropdown open, and every toggle calls `onValueChange` with the full array. Add `Select.ItemControl` for a leading checkbox. Without custom children, `Select.Value` shows the selected labels on one line.
+
+```tsx
+import { useState } from 'react';
+import { Field, Select } from '@cdx-ui/components';
+import { teams } from './_data';
+
+export default function SelectMultipleDemo() {
+  const [teamIds, setTeamIds] = useState<string[]>([]);
+
+  return (
+    <Field className="w-full" isRequired>
+      <Field.Label>Assign teams</Field.Label>
+      <Select type="multiple" items={teams} value={teamIds} onValueChange={setTeamIds} isRequired>
+        <Select.Trigger>
+          <Select.Value placeholder="Select teams">
+            {({ isPlaceholder, selectedItems }) =>
+              isPlaceholder ? null : `${selectedItems.length} teams selected`
+            }
+          </Select.Value>
+        </Select.Trigger>
+        <Select.Content>
+          {teams.map((team) => (
+            <Select.Item key={team.value} value={team.value}>
+              <Select.ItemControl />
+              <Select.ItemLabel>{team.label}</Select.ItemLabel>
+            </Select.Item>
+          ))}
+        </Select.Content>
+      </Select>
+      <Field.Helper>Each change applies immediately.</Field.Helper>
+    </Field>
+  );
+}
+```
+
+## With search
+
+Add `Select.Search` as the first child of `Select.Content` to build a searchable select, the pattern other libraries call an autocomplete. Typing filters the options in both `single` and `multiple` mode, and `Select.Empty` shows when nothing matches. Selected options that the query hides stay selected and still count in `Select.Value`. The default filter is a case- and accent-insensitive "contains" on each option's `label`; pass `filter` to replace it, or control `inputValue` and `onInputChange` to swap `items` for server results. The query clears when the dropdown closes.
+
+In `Select.Content` on iOS and Android, the search input renders inside the anchored dropdown and the on-screen keyboard can cover the options. Use `Select.BottomSheet` for native search.
+
+```tsx
+import { useState } from 'react';
+import { Field, Select } from '@cdx-ui/components';
+import { teams } from './_data';
+
+export default function SelectWithSearchDemo() {
+  const [teamIds, setTeamIds] = useState<string[]>([]);
+
+  return (
+    <Field className="w-full" isRequired>
+      <Field.Label>Assign teams</Field.Label>
+      <Select type="multiple" items={teams} value={teamIds} onValueChange={setTeamIds}>
+        <Select.Trigger>
+          <Select.Value placeholder="Select teams you want to assign to this user">
+            {({ isPlaceholder, selectedItems }) =>
+              isPlaceholder ? null : `${String(selectedItems.length)} teams selected`
+            }
+          </Select.Value>
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Search placeholder="Search Teams" accessibilityLabel="Search teams" />
+          {teams.map((t) => (
+            <Select.Item key={t.value} value={t.value} disabled={t.disabled}>
+              <Select.ItemControl />
+              <Select.ItemLabel>{t.label}</Select.ItemLabel>
+            </Select.Item>
+          ))}
+          <Select.Empty>No teams found</Select.Empty>
+        </Select.Content>
+      </Select>
+    </Field>
+  );
+}
+```
+
+## Bottom sheet
+
+Use `Select.BottomSheet` in place of `Select.Content` to present the options in a sheet that slides up from the bottom — the preferred surface on native, especially with `Select.Search`. It takes the same children: `Select.Search`, the options, and `Select.Empty`. The sheet keeps the search input and the results above the on-screen keyboard, and swiping it down, pressing the backdrop, or pressing Android back closes it without changing the value. On web it renders the same dropdown as `Select.Content`, so one composition serves every platform. On native it requires `BottomSheet.Provider` at the app root.
+
+```tsx
+import { useState } from 'react';
+import { Field, Select } from '@cdx-ui/components';
+import { teams } from './_data';
+
+export default function SelectBottomSheetDemo() {
+  const [teamIds, setTeamIds] = useState<string[]>([]);
+
+  return (
+    <Field className="w-full">
+      <Field.Label>Assign teams</Field.Label>
+      <Select type="multiple" items={teams} value={teamIds} onValueChange={setTeamIds}>
+        <Select.Trigger>
+          <Select.Value placeholder="Select teams" />
+        </Select.Trigger>
+        <Select.BottomSheet>
+          <Select.Search placeholder="Search Teams" accessibilityLabel="Search teams" />
+          {teams.map((t) => (
+            <Select.Item key={t.value} value={t.value} disabled={t.disabled}>
+              <Select.ItemControl />
+              <Select.ItemLabel>{t.label}</Select.ItemLabel>
+            </Select.Item>
+          ))}
+          <Select.Empty>No teams found</Select.Empty>
+        </Select.BottomSheet>
+      </Select>
+    </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.
@@ -145,7 +259,7 @@ export default function SelectCustomTriggerDemo() {
 
 ## 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.
+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. A function child receives `isPlaceholder`, `selectedItems`, and `selectedText`; return `null` to fall back to the default.
 
 ```tsx
 import { useState } from 'react';
@@ -295,7 +409,7 @@ export default function SelectPlacementDemo() {
 
 ### Select
 
-The root manages the selected value, open state, options, and form-control state.
+The root manages the selected value, open state, options, and form-control state. `type` sets the selection mode: `single` (the default) takes a `string` value, and `multiple` takes a `string[]`, where an empty array means no selection.
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -303,18 +417,23 @@ The root manages the selected value, open state, options, and form-control state
 | `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. |
+| `type?` | `'single' \| 'multiple'` | — | — |
+| `value?` | `string \| string[]` | — | — |
+| `defaultValue?` | `string \| string[]` | — | — |
+| `onValueChange?` | `((value: string) => void) \| ((value: string[]) => void)` | — | — |
+| `items?` | `SelectItemData[]` | — | — |
+| `isOpen?` | `boolean` | — | — |
 | `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. |
+| `native?` | `boolean` | — | — |
+| `inputValue?` | `string` | — | — |
+| `defaultInputValue?` | `string` | — | — |
+| `onInputChange?` | `((inputValue: string) => void)` | — | — |
+| `filter?` | `SelectFilter` | — | — |
 
 Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
 
@@ -361,12 +480,12 @@ Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props).
 
 ### Select.Value
 
-Displays the label from `items` that matches the selected value, or the placeholder when no value is selected.
+Displays the label from `items` that matches the selected value, or the placeholder when no value is selected. In multiple mode it shows the selected labels joined with commas, truncated to one line. A function child receives `{ isPlaceholder, selectedItems, selectedText }`.
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `className?` | `string` | — | — |
-| `children?` | `ReactNode` | — | — |
+| `children?` | `ReactNode \| ((state: SelectValueRenderProps) => ReactNode)` | — | Replaces the default display. A function child receives the selection state; return `null` or `undefined` to fall back to the default (placeholder or `selectedText`). |
 | `asChild?` | `boolean` | — | — |
 | `placeholder?` | `string` | — | — |
 
@@ -394,7 +513,7 @@ Inherits all `ForgeIconProps` (react-native-svg `SvgProps` plus `filled` and `si
 
 ### Select.Content
 
-Dropdown panel that positions itself around the trigger, scrolls long option lists, and closes when dismissed.
+Dropdown panel that positions itself around the trigger, scrolls long option lists, and closes when dismissed. Dismissing never changes the value.
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -406,12 +525,65 @@ Dropdown panel that positions itself around the trigger, scrolls long option lis
 | `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. |
+| `dismissAccessibilityLabel?` | `string` | `'Dismiss'` | Accessible name of the visually hidden button that lets screen-reader users close the popup on web. |
 
 Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
 
+### Select.BottomSheet
+
+Presents the options in a bottom sheet on iOS and Android, in place of `Select.Content`. Compose exactly one of `Select.Content` or `Select.BottomSheet` per select. It sorts its direct children into the same regions as `Select.Content`: `Select.Search` stays above the scrolling options and `Select.Empty` follows them. On web it renders the `Select.Content` dropdown, and `dismissAccessibilityLabel` names its hidden dismiss button. With `Select.Search`, keyboard avoidance applies to the default search input; an `asChild` input does not move the sheet.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the sheet body's own styles. |
+| `children?` | `ReactNode` | — | `Select.Search`, `Select.Item` elements, and `Select.Empty`, as in `Select.Content`. |
+| `asChild?` | `boolean` | — | Render the consumer's child as the sheet body, skipping the region split. |
+| `dismissAccessibilityLabel?` | `string` | `'Dismiss'` | Accessible name of the visually hidden dismiss button on web, where the surface is the `Select.Content` dropdown. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute    | Values                | Description                     |
+| ------------ | --------------------- | ------------------------------- |
+| `data-slot`  | `select-bottom-sheet` | Sheet body on native            |
+| `data-state` | `open`                | Present while the sheet is open |
+
+### Select.Search
+
+A search input for the top of `Select.Content` or `Select.BottomSheet`, with a leading search icon. Its query filters the options through the root `filter`, and it takes focus when the dropdown opens on web. Place it as a direct child of the surface; a wrapped `Select.Search` is not recognized and renders among the options.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the search container's own styles. |
+| `children?` | `ReactNode` | — | The text input to render when `asChild` is set. Otherwise not rendered. |
+| `asChild?` | `boolean` | — | Merge the search wiring onto the single child text input instead of rendering the default `Input` with a search icon. |
+| `variant?` | `'outline' \| 'subtle'` | `'subtle'` | `Input` variant of the default search field. Ignored when `asChild` is set. |
+| `getResultCountLabel?` | `((count: number) => string)` | — | Text the polite live region announces when the result count changes, such as `"3 results"` (the English default). When nothing matches, the `Select.Empty` text is announced instead. |
+
+Inherits [`TextInputProps`](https://reactnative.dev/docs/textinput#props) except `value`, `defaultValue`, and `onChangeText`, which the root owns through `inputValue`, `defaultInputValue`, and `onInputChange`.
+
+| Attribute   | Values          | Description      |
+| ----------- | --------------- | ---------------- |
+| `data-slot` | `select-search` | Search container |
+
+### Select.Empty
+
+Content shown below the options only when no option matches the query. Plain text children are styled to match the options. Place it as a direct child of `Select.Content` or `Select.BottomSheet`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the empty state's own styles. |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute   | Values         | Description |
+| ----------- | -------------- | ----------- |
+| `data-slot` | `select-empty` | Empty state |
+
 ### 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.
+An individual option. Its `value` must match an entry in the root `items` array. Disable an option with `disabled` here or on its `items` entry. The `indicator` prop replaces the default selected-item checkmark, and `indicator={null}` suppresses it. The default checkmark is omitted when the item contains a `Select.ItemControl`.
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -419,7 +591,7 @@ An individual option. Its `value` must match an entry in the root `items` array.
 | `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. |
+| `indicator?` | `ReactNode` | — | Replaces the default selected-item checkmark. The replacement is rendered only while the item is selected. Pass `null` to suppress the indicator. The default checkmark is omitted when the item contains a `Select.ItemControl`. |
 | `value` | `string` | — | — |
 | `isHovered?` | `boolean` | — | — |
 | `isActive?` | `boolean` | — | — |
@@ -452,22 +624,49 @@ Text label rendered inside a `Select.Item`.
 
 Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
 
+### Select.ItemControl
+
+A leading checkbox that mirrors the item's selected state. It is presentational: the option itself carries the selected state for assistive technology.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the control's own styles. |
+| `children?` | `ReactNode` | — | The element to render when `asChild` is set. Otherwise not rendered. |
+| `asChild?` | `boolean` | — | Render the consumer's child element in place of the default checkbox glyph. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute      | Values                | Description     |
+| -------------- | --------------------- | --------------- |
+| `data-slot`    | `select-item-control` | Checkbox glyph  |
+| `data-checked` | `true` \| `false`     | Selection state |
+
 ## 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                  |
+| `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-bottom-sheet` | Sheet body (native)           |
+| `select-search`       | Search input                  |
+| `select-empty`        | No-results message            |
+| `select-item`         | Option                        |
+| `select-item-label`   | Option label                  |
+| `select-item-control` | Option checkbox               |
 
 ## 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.
+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. In multiple mode the listbox sets `aria-multiselectable="true"`, and `Select.ItemControl` is hidden from assistive technology.
 
 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.
+With `Select.Search`, the dropdown becomes a `role="dialog"` named by the field label that contains the search input (`role="searchbox"`) and the `role="listbox"`. The trigger keeps `aria-haspopup="listbox"`. On web, focus stays in the search input while Arrow Up and Arrow Down move the highlight through the visible, enabled options, announced through `aria-activedescendant`. Enter selects and closes, or toggles in multiple mode, and Space types a space. The highlight moves to the first match each time the query changes, and a polite live region announces the number of results, or the `Select.Empty` text when nothing matches. Escape and Tab close the dropdown, keep the value, and clear the query. Inside a `Drawer`, closing returns focus to the trigger and leaves the drawer open.
+
+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 and closes, or toggles in multiple mode; Escape closes; and Tab closes while continuing focus navigation. Focus returns to the trigger when the dropdown closes.
+
+Screen-reader users can close the dropdown without a keyboard. On web, a visually hidden button labelled by `dismissAccessibilityLabel` on `Select.Content` closes it. On iOS, the VoiceOver escape gesture closes it, and on Android the back button does. Closing never changes the value.
+
+In `Select.BottomSheet` on iOS and Android, VoiceOver and TalkBack move through the search input and each option directly, with no virtual focus, and each option announces its selected state. The sheet takes the same role and name as the dropdown. The VoiceOver escape gesture, Android back, a swipe down, and the backdrop close it, keep the value, and clear the query.