@cdx-ui/components 0.2.2 → 0.2.4

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

@@ -0,0 +1,84 @@
+# Month Calendar (https://design.candescent.com/docs/components/month-calendar)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=12010-27571), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/date-time-monthcalendar--default)
+
+`MonthCalendar` renders month and year grids for selecting a single month — there are no day cells. Values are `MonthId` strings in `YYYY-MM-01` format.
+
+```tsx
+import { MonthCalendar } from '@cdx-ui/components';
+```
+
+## Basic
+
+Control the selected month with `value` and `onValueChange`.
+
+```tsx
+import { useState } from 'react';
+import { MonthCalendar } from '@cdx-ui/components';
+import { monthId, type MonthId } from '@cdx-ui/formatters';
+
+export default function MonthCalendarBasicDemo() {
+  const [value, setValue] = useState<MonthId | undefined>(monthId('2026-07-01'));
+
+  return (
+    <MonthCalendar
+      value={value}
+      onValueChange={setValue}
+      aria-label="Statement month"
+      className="w-full max-w-sm"
+    />
+  );
+}
+```
+
+## Disabled
+
+Set `disabled` to render a read-only grid that ignores month presses.
+
+```tsx
+import { MonthCalendar } from '@cdx-ui/components';
+import { monthId } from '@cdx-ui/formatters';
+
+export default function MonthCalendarDisabledDemo() {
+  return (
+    <MonthCalendar
+      value={monthId('2026-07-01')}
+      disabled
+      aria-label="Statement month"
+      className="w-full max-w-sm"
+    />
+  );
+}
+```
+
+## API
+
+### MonthCalendar
+
+By default, `MonthCalendar` renders a year header — tap it to switch to the year picker, or use the previous/next controls to shift the visible year — followed by a twelve-month grid. `locale` defaults to `en-US` and controls month formatting.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `value?` | `MonthId` | — | — |
+| `defaultValue?` | `MonthId` | — | — |
+| `onValueChange?` | `((value: MonthId) => void)` | — | Called with the new `MonthId`, or `undefined` when the selection is cleared. |
+| `view?` | `'month' \| 'year'` | — | — |
+| `defaultView?` | `'month' \| 'year'` | — | — |
+| `onViewChange?` | `((view: MonthCalendarView) => void)` | — | — |
+| `visibleYear?` | `number` | — | — |
+| `defaultVisibleYear?` | `number` | — | — |
+| `onVisibleYearChange?` | `((year: number) => void)` | — | — |
+| `disabled?` | `boolean` | — | — |
+| `minValue?` | `MonthId` | — | Earliest selectable month. Build with `monthId(...)` from `@cdx-ui/formatters`. |
+| `maxValue?` | `MonthId` | — | Latest selectable month. Build with `monthId(...)` from `@cdx-ui/formatters`. |
+| `locale?` | `string` | — | — |
+| `labels?` | `Partial<DateComponentLabels>` | — | — |
+
+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. Every month and year is unselectable while `disabled`.

package/docs/components/month-picker/content.md

@@ -0,0 +1,273 @@
+# Month Picker (https://design.candescent.com/docs/components/month-picker)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/date-time-monthpicker--standalone)
+
+`MonthPicker` pairs a segmented `DateField` in month mode with a `MonthCalendar` and coordinates the surface that presents it. Values are `MonthId` strings in `YYYY-MM-01` format.
+
+```tsx
+import { DateField, Field, MonthPicker } from '@cdx-ui/components';
+```
+
+## Basic
+
+Wrap the whole `DateField.Group` — the input plus a decorative `MonthPicker.TriggerIndicator` in a `DateField.Suffix` — in a single `MonthPicker.Trigger` so the entire field is one large tap target. Because month selection is surface-driven, there is no typing to interrupt. `MonthPicker.Popover` anchors to the field and is the preferred surface on web.
+
+```tsx
+import { useState } from 'react';
+import { DateField, Field, MonthPicker } from '@cdx-ui/components';
+import type { MonthId } from '@cdx-ui/formatters';
+
+export default function MonthPickerBasicDemo() {
+  const [value, setValue] = useState<MonthId | undefined>();
+
+  return (
+    <Field className="w-full max-w-xs">
+      <MonthPicker value={value} onValueChange={setValue}>
+        <Field.Label>Statement month</Field.Label>
+        <MonthPicker.Trigger className="w-full">
+          <DateField.Group fullWidth>
+            <DateField.Input />
+            <DateField.Suffix>
+              <MonthPicker.TriggerIndicator />
+            </DateField.Suffix>
+          </DateField.Group>
+        </MonthPicker.Trigger>
+        <MonthPicker.Popover>
+          <MonthPicker.Calendar aria-label="Statement month" />
+        </MonthPicker.Popover>
+      </MonthPicker>
+    </Field>
+  );
+}
+```
+
+## Dialog
+
+Use `MonthPicker.Dialog` to present the calendar in a modal surface.
+
+```tsx
+import { useState } from 'react';
+import { DateField, Field, MonthPicker } from '@cdx-ui/components';
+import type { MonthId } from '@cdx-ui/formatters';
+
+export default function MonthPickerDialogDemo() {
+  const [value, setValue] = useState<MonthId | undefined>();
+
+  return (
+    <Field className="w-full max-w-xs">
+      <MonthPicker value={value} onValueChange={setValue}>
+        <Field.Label>Statement month</Field.Label>
+        <MonthPicker.Trigger className="w-full">
+          <DateField.Group fullWidth>
+            <DateField.Input />
+            <DateField.Suffix>
+              <MonthPicker.TriggerIndicator />
+            </DateField.Suffix>
+          </DateField.Group>
+        </MonthPicker.Trigger>
+        <MonthPicker.Dialog>
+          <MonthPicker.Calendar aria-label="Statement month" />
+        </MonthPicker.Dialog>
+      </MonthPicker>
+    </Field>
+  );
+}
+```
+
+## Bottom sheet
+
+Use `MonthPicker.BottomSheet` to present the calendar in a sheet that slides up from the bottom — the preferred surface on native. It wires open state only, so compose `BottomSheet.Header` and `BottomSheet.Content` as its children.
+
+```tsx
+import { useState } from 'react';
+import { BottomSheet, DateField, Field, MonthPicker } from '@cdx-ui/components';
+import type { MonthId } from '@cdx-ui/formatters';
+import { PickerBottomSheetFrame } from './_frame';
+
+export default function MonthPickerBottomSheetDemo() {
+  const [value, setValue] = useState<MonthId | undefined>();
+  const [open, setOpen] = useState(false);
+
+  return (
+    <PickerBottomSheetFrame>
+      <Field className="w-full max-w-xs">
+        <MonthPicker value={value} onValueChange={setValue} isOpen={open} onOpenChange={setOpen}>
+          <Field.Label>Statement month</Field.Label>
+          <MonthPicker.Trigger className="w-full">
+            <DateField.Group fullWidth>
+              <DateField.Input />
+              <DateField.Suffix>
+                <MonthPicker.TriggerIndicator />
+              </DateField.Suffix>
+            </DateField.Group>
+          </MonthPicker.Trigger>
+          <MonthPicker.BottomSheet>
+            <BottomSheet.Header title="Select month" onClose={() => setOpen(false)} />
+            <BottomSheet.Content>
+              <MonthPicker.Calendar aria-label="Statement month" />
+            </BottomSheet.Content>
+          </MonthPicker.BottomSheet>
+        </MonthPicker>
+      </Field>
+    </PickerBottomSheetFrame>
+  );
+}
+```
+
+## Standalone
+
+Render a `MonthCalendar` inline instead of a presentation surface when the field and calendar share the screen.
+
+```tsx
+import { useState } from 'react';
+import { DateField, Field, MonthCalendar, MonthPicker } from '@cdx-ui/components';
+import type { MonthId } from '@cdx-ui/formatters';
+
+export default function MonthPickerStandaloneDemo() {
+  const [value, setValue] = useState<MonthId | undefined>();
+
+  return (
+    <Field className="w-full max-w-sm">
+      <MonthPicker value={value} onValueChange={setValue}>
+        <Field.Label>Statement month</Field.Label>
+        <DateField.Group fullWidth>
+          <DateField.Input />
+        </DateField.Group>
+        <MonthCalendar
+          className="mt-2"
+          aria-label="Statement month"
+          value={value}
+          onValueChange={setValue}
+        />
+      </MonthPicker>
+    </Field>
+  );
+}
+```
+
+## Custom trigger
+
+Set `asChild` on `MonthPicker.Trigger` to drive selection from a custom pressable such as a `Chip`, which suits filter UIs where the whole value is chosen from the surface. The trigger merges its press and expanded-state accessibility props onto the child.
+
+```tsx
+import { useState } from 'react';
+import { Chip, Field, MonthPicker } from '@cdx-ui/components';
+import { CalendarMonth } from '@cdx-ui/icons';
+
+const monthYear = new Intl.DateTimeFormat('en-US', { month: 'long', year: 'numeric' });
+
+function formatMonth(id: string) {
+  const [year, month] = id.split('-').map(Number);
+  return monthYear.format(new Date(year, month - 1, 1));
+}
+
+export default function MonthPickerCustomTriggerDemo() {
+  const [value, setValue] = useState<string | undefined>();
+
+  return (
+    <Field className="w-full max-w-xs">
+      <MonthPicker onValueChange={setValue}>
+        <Field.Label>Statement month</Field.Label>
+        <MonthPicker.Trigger asChild>
+          <Chip variant={value ? 'subtle' : 'outline'} color={value ? 'action' : 'neutral'}>
+            <Chip.Icon as={CalendarMonth} position="leading" />
+            <Chip.Label>{value ? formatMonth(value) : 'Select month'}</Chip.Label>
+          </Chip>
+        </MonthPicker.Trigger>
+        <MonthPicker.Popover>
+          <MonthPicker.Calendar aria-label="Statement month" />
+        </MonthPicker.Popover>
+      </MonthPicker>
+    </Field>
+  );
+}
+```
+
+## API
+
+### MonthPicker
+
+Root of the compound. Owns the selected value, open state, `locale`, and `labels`, and provides `DateField` styling context to the field. Compose exactly one presentation surface — `MonthPicker.Popover`, `MonthPicker.Dialog`, or `MonthPicker.BottomSheet` — per picker.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `value?` | `MonthId` | — | — |
+| `defaultValue?` | `MonthId` | — | — |
+| `onValueChange?` | `((value: MonthId) => void)` | — | Called with the new `MonthId`, or `undefined` when the selection is cleared. |
+| `isOpen?` | `boolean` | — | Controlled open state. Use `defaultOpen` for the uncontrolled variant. |
+| `defaultOpen?` | `boolean` | — | — |
+| `onOpenChange?` | `((open: boolean) => void)` | — | — |
+| `isDisabled?` | `boolean` | — | — |
+| `isReadOnly?` | `boolean` | — | — |
+| `isInvalid?` | `boolean` | — | — |
+| `isRequired?` | `boolean` | — | — |
+| `minValue?` | `MonthId` | — | Earliest selectable month, applied to the embedded calendar. Build with `monthId(...)`. |
+| `maxValue?` | `MonthId` | — | Latest selectable month, applied to the embedded calendar. Build with `monthId(...)`. |
+| `name?` | `string` | — | — |
+| `locale?` | `string` | — | — |
+| `labels?` | `Partial<DateComponentLabels>` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Sub-components
+
+### MonthPicker.Trigger
+
+Toggles the presentation surface and announces its expanded state. Because month selection is surface-driven, wrap the entire `DateField.Group` so the whole field is the tap target, with a decorative `MonthPicker.TriggerIndicator` in the `DateField.Suffix`. Its accessible name defaults to the picker's `openMonthPicker` label. Set `asChild` to merge its press and accessibility props onto a custom interactive child — for example an `IconButton` — instead of rendering the default pressable.
+
+| 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. |
+| `ref?` | `React.Ref<View>` | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
+| `asChild?` | `boolean` | — | Merge press / a11y props onto the single child instead of rendering a `Pressable`. Use when the trigger should be another interactive host (e.g. `IconButton`). For a larger field hit target, prefer wrapping `DateField.Group` as children without `asChild` so the outer `Pressable` covers the whole input chrome. |
+| `key?` | `React.Key \| null` | — | — |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props).
+
+### MonthPicker.TriggerIndicator
+
+Renders the decorative calendar icon, typically inside the `DateField.Suffix` of a full-field `MonthPicker.Trigger`. Takes no props.
+
+### MonthPicker.Calendar
+
+Renders the picker's `MonthCalendar`, wired to the shared value, `locale`, and `labels`. Accepts all [`MonthCalendar`](https://design.candescent.com/docs/components/month-calendar/content.md) props except `value` and `onValueChange`, which the picker controls.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `ref?` | `React.Ref<View>` | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
+| `asChild?` | `boolean` | — | — |
+| `defaultValue?` | `MonthId` | — | — |
+| `locale?` | `string` | — | — |
+| `labels?` | `Partial<DateComponentLabels>` | — | — |
+| `view?` | `'month' \| 'year'` | — | — |
+| `defaultView?` | `'month' \| 'year'` | — | — |
+| `onViewChange?` | `((view: MonthCalendarView) => void)` | — | — |
+| `visibleYear?` | `number` | — | — |
+| `defaultVisibleYear?` | `number` | — | — |
+| `onVisibleYearChange?` | `((year: number) => void)` | — | — |
+| `disabled?` | `boolean` | — | — |
+| `key?` | `React.Key \| null` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### MonthPicker.Popover
+
+Presents the calendar in an anchored popover, positioned above or below the field based on available space. Wires the surface's open state and renders its children.
+
+### MonthPicker.Dialog
+
+Presents the calendar in a modal dialog. Wires the surface's open state and renders its children.
+
+### MonthPicker.BottomSheet
+
+Presents the calendar in a bottom sheet, the preferred surface on native. It wires open state only — compose `BottomSheet.Header` and `BottomSheet.Content` (or any sheet layout) as its children.
+
+## Accessibility
+
+Give the picker an accessible name with `Field.Label` or `aria-label`, and pass `aria-label` to `MonthPicker.Calendar` to name the grid. `MonthPicker.Trigger` announces the localized `openMonthPicker` label, which `labels` can override. While `disabled`, the trigger does not open a surface.

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

@@ -0,0 +1,327 @@
+# OTP Input Field (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)
+
+Each cell holds a single character and auto-advances on entry. Cells default to digit-only filtering and `keyboardType="number-pad"`.
+
+```tsx
+import { OtpInput } from '@cdx-ui/components';
+```
+
+## Basic
+
+`OtpInput` is controlled — pass `value` and `onChangeText`.
+
+```tsx
+import { useState } from 'react';
+import { OtpInput } from '@cdx-ui/components';
+
+export default function OtpInputBasicDemo() {
+  const [value, setValue] = useState('');
+
+  return (
+    <OtpInput
+      accessibilityLabel="Verification code"
+      cellCount={6}
+      value={value}
+      onChangeText={setValue}
+    />
+  );
+}
+```
+
+## Sizes
+
+Use `size="small"` for denser cells. Typography and cell dimensions scale together.
+
+```tsx
+import { useState } from 'react';
+import { Box, OtpInput, Text, type OtpInputProps } from '@cdx-ui/components';
+
+const sizes = ['default', 'small'] as const satisfies readonly NonNullable<OtpInputProps['size']>[];
+
+function SizeRow({ size }: { size: NonNullable<OtpInputProps['size']> }) {
+  const [value, setValue] = useState('');
+
+  return (
+    <Box className="gap-2">
+      <Text size="sm" color="secondary">
+        {size}
+      </Text>
+      <OtpInput
+        accessibilityLabel={`${size} verification code`}
+        cellCount={size === 'small' ? 4 : 6}
+        size={size}
+        value={value}
+        onChangeText={setValue}
+      />
+    </Box>
+  );
+}
+
+export default function OtpInputSizesDemo() {
+  return (
+    <Box className="w-full gap-4">
+      {sizes.map((size) => (
+        <SizeRow key={size} size={size} />
+      ))}
+    </Box>
+  );
+}
+```
+
+## Cell count
+
+Set `cellCount` to match the length of the code you expect (commonly 4 or 6).
+
+```tsx
+import { useState } from 'react';
+import { OtpInput } from '@cdx-ui/components';
+
+export default function OtpInputCellCountDemo() {
+  const [value, setValue] = useState('');
+
+  return (
+    <OtpInput
+      accessibilityLabel="Four-digit verification code"
+      cellCount={4}
+      value={value}
+      onChangeText={setValue}
+    />
+  );
+}
+```
+
+## States
+
+The root controls disabled, read-only, and invalid state for every cell.
+
+```tsx
+import { Box, OtpInput, Text } from '@cdx-ui/components';
+
+export default function OtpInputStatesDemo() {
+  return (
+    <Box className="w-full gap-4">
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Disabled
+        </Text>
+        <OtpInput
+          accessibilityLabel="Disabled verification code"
+          cellCount={6}
+          value="123456"
+          onChangeText={() => {}}
+          isDisabled
+        />
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Read-only
+        </Text>
+        <OtpInput
+          accessibilityLabel="Read-only verification code"
+          cellCount={6}
+          value="123456"
+          onChangeText={() => {}}
+          isReadOnly
+        />
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Invalid
+        </Text>
+        <OtpInput
+          accessibilityLabel="Invalid verification code"
+          cellCount={6}
+          value="123456"
+          onChangeText={() => {}}
+          isInvalid
+        />
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Alphanumeric
+
+By default only digits are accepted. Use `allowedCharacters`, `characterPattern`, or `filterInput` to allow other characters — and override `keyboardType` via `getCellProps` so the on-screen keyboard matches what you accept.
+
+```tsx
+import { useState } from 'react';
+import { OtpInput } from '@cdx-ui/components';
+
+export default function OtpInputAlphanumericDemo() {
+  const [value, setValue] = useState('');
+
+  return (
+    <OtpInput
+      accessibilityLabel="Hex code"
+      cellCount={6}
+      value={value}
+      onChangeText={setValue}
+      allowedCharacters="ABCDEFabcdef0123456789"
+      getCellProps={() => ({ keyboardType: 'default' })}
+    />
+  );
+}
+```
+
+## With field
+
+Compose with `Field` to provide a visible label and helper text. OtpInput also reads `isDisabled`, `isInvalid`, and `isReadOnly` from a parent `Field` context.
+
+```tsx
+import { useState } from 'react';
+import { Field, OtpInput } from '@cdx-ui/components';
+
+export default function OtpInputWithFieldDemo() {
+  const [value, setValue] = useState('');
+
+  return (
+    <Field className="w-full" isRequired>
+      <Field.Label>One-time code</Field.Label>
+      <OtpInput
+        accessibilityLabel="One-time code"
+        cellCount={6}
+        value={value}
+        onChangeText={setValue}
+      />
+      <Field.Helper>Enter the 6-digit code sent to your device.</Field.Helper>
+    </Field>
+  );
+}
+```
+
+## With field and validation
+
+Set the invalid state on `Field` so the error message stays in sync with incomplete input.
+
+```tsx
+import { useState } from 'react';
+import { Field, OtpInput } from '@cdx-ui/components';
+
+export default function OtpInputWithFieldInvalidDemo() {
+  const [value, setValue] = useState('');
+  const isInvalid = value.length >= 0 && value.length < 6;
+
+  return (
+    <Field className="w-full" isRequired isInvalid={isInvalid}>
+      <Field.Label>One-time code</Field.Label>
+      <OtpInput
+        accessibilityLabel="One-time code"
+        cellCount={6}
+        value={value}
+        onChangeText={setValue}
+      />
+      <Field.Error>Enter all 6 digits to continue.</Field.Error>
+    </Field>
+  );
+}
+```
+
+## API
+
+### OtpInput
+
+Controlled multi-cell OTP root. Renders one cell per `cellCount` and manages focus advancement, paste, filtering, and SMS autofill hints.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+| `size?` | `'default' \| 'small'` | — | — |
+| `cellCount` | `number` | — | Number of OTP cells (fixed). |
+| `value` | `string` | — | Controlled value: characters in order, length 0..`cellCount` (prefix fill). |
+| `onChangeText` | `(value: string) => void` | — | — |
+| `onComplete?` | `(() => void)` | — | Called when the code is ready to verify again: - `value` becomes full (`length === cellCount`) after being shorter, or - `value` stays full but the string changes (user corrected a digit without dropping below full length). Does not fire on mount when `value` is already full and unchanged, nor on re-renders with the same full `value`. |
+| `isDisabled?` | `boolean` | — | — |
+| `isInvalid?` | `boolean` | — | — |
+| `isReadOnly?` | `boolean` | — | — |
+| `smsOtpAutofill?` | `boolean` | `true` | When false, no SMS / Web OTP autofill hints on the first cell. |
+| `filterInput?` | `((input: string) => string)` | — | Override default digit-only filtering. Takes priority over `allowedCharacters` and `characterPattern` when truthy. Does not change the default `keyboardType` (`number-pad`); use `getCellProps` if the allowed character set needs a different keyboard. |
+| `allowedCharacters?` | `string` | — | Keep only characters present in this string (treated as a set of code units). Used when `filterInput` is not provided. Takes priority over `characterPattern`. Default keyboard remains numeric; use `getCellProps` to set `keyboardType` when allowing letters/symbols. |
+| `characterPattern?` | `RegExp` | — | Keep only characters matching this pattern (tested per code unit). Used when neither `filterInput` nor `allowedCharacters` is provided. Default keyboard remains numeric; use `getCellProps` to set `keyboardType` for non-digit input. |
+| `getCellProps?` | `((index: number) => Partial<TextInputProps>)` | — | Spread onto each cell after built-in field props (including `keyboardType="number-pad"`), so consumers can override `keyboardType`, `autoCapitalize`, etc. for non-digit OTPs. |
+| `cellTestIdPrefix?` | `string` | — | Optional prefix for `testID` on each field: `${cellTestIdPrefix}:${index}:...` |
+| `fullWidth?` | `boolean \| null` | — | — |
+| `variant?` | `'outline'` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute   | Values      | Description    |
+| ----------- | ----------- | -------------- |
+| `data-slot` | `otp-input` | Root container |
+
+### Input filtering
+
+By default only digits (`0-9`) are accepted. Three mechanisms override this, evaluated in priority order:
+
+| Mechanism           | Type                        | Behavior                                                     |
+| ------------------- | --------------------------- | ------------------------------------------------------------ |
+| `filterInput`       | `(input: string) => string` | Full custom filter — takes raw text, returns allowed portion |
+| `allowedCharacters` | `string`                    | Keeps only characters present in this string                 |
+| `characterPattern`  | `RegExp`                    | Keeps only characters matching this pattern (per code unit)  |
+
+None of these change the default `keyboardType` (`number-pad`). When allowing non-digits, pass `getCellProps` to set a matching keyboard.
+
+### `onComplete`
+
+Fires when the code is ready to verify again:
+
+- `value` reaches `cellCount` length after being shorter
+- `value` stays full length but the string changes (correction without deleting first)
+
+It does **not** fire on mount when `value` is already full, nor on re-renders with the same full value.
+
+### SMS autofill
+
+When `smsOtpAutofill` is `true` (default), the first cell receives platform autofill hints:
+
+| Platform | Hint                            |
+| -------- | ------------------------------- |
+| iOS      | `textContentType="oneTimeCode"` |
+| Android  | `autoComplete="sms-otp"`        |
+| Web      | `autoComplete="one-time-code"`  |
+
+Set `smsOtpAutofill={false}` to disable.
+
+## Sub-components
+
+`OtpInput` renders `OtpInput.Cell` and `OtpInput.Field` internally. Most consumers only need the root; the sub-components are available for advanced composition.
+
+### OtpInput.Cell
+
+Styled cell chrome built on `Input`. Inherits variant and size from the parent `OtpInput` context.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+| `variant?` | `'outline' \| null` | — | — |
+| `size?` | `'default' \| 'small' \| null` | — | — |
+| `isInvalid?` | `boolean` | — | — |
+| `isReadOnly?` | `boolean` | — | — |
+| `isDisabled?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### OtpInput.Field
+
+Per-cell text entry. Bridges focus/blur to the parent cell's `Input` context so focus styles activate.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextInputProps`](https://reactnative.dev/docs/textinput#props).
+
+## Accessibility
+
+| Attribute        | Behavior                                                                              |
+| ---------------- | ------------------------------------------------------------------------------------- |
+| **Label**        | Pass `accessibilityLabel` on the root. Each cell reads `"{label}, N of {cellCount}"`. |
+| **Disabled**     | Sets `editable={false}` on every cell.                                                |
+| **SMS autofill** | Applied to the first cell when `smsOtpAutofill` is enabled.                           |