@cdx-ui/components 0.2.2 → 0.2.4

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

@@ -0,0 +1,360 @@
+# Date Picker (https://design.candescent.com/docs/components/date-picker)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=12349-9879), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/date-time-datepicker--standalone)
+
+`DatePicker` pairs a segmented `DateField` with a `Calendar` and coordinates the surface that presents it. Values are `DateId` strings in `YYYY-MM-DD` format.
+
+```tsx
+import { Calendar, DateField, DatePicker, Field } from '@cdx-ui/components';
+```
+
+## Basic
+
+Because the date field is editable, keep the `DatePicker.Trigger` around the suffix icon only, so typing in the field does not open the calendar. Then present the calendar — `DatePicker.Popover` anchors to the field and is the preferred surface on web. For surface-driven selection with no typing, you can instead wrap the whole `DateField.Group` in the trigger, as [DateRangePicker](https://design.candescent.com/docs/components/date-range-picker/content.md) and [MonthPicker](https://design.candescent.com/docs/components/month-picker/content.md) do.
+
+```tsx
+import { useState } from 'react';
+import { DateField, DatePicker, Field } from '@cdx-ui/components';
+import type { DateId } from '@cdx-ui/formatters';
+
+export default function DatePickerBasicDemo() {
+  const [value, setValue] = useState<DateId | undefined>();
+
+  return (
+    <Field className="w-full max-w-xs">
+      <DatePicker value={value} onValueChange={setValue}>
+        <Field.Label>Transfer date</Field.Label>
+        <DateField.Group fullWidth>
+          <DateField.Input />
+          <DateField.Suffix>
+            <DatePicker.Trigger>
+              <DatePicker.TriggerIndicator />
+            </DatePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        <DatePicker.Popover>
+          <DatePicker.Calendar aria-label="Transfer date" />
+        </DatePicker.Popover>
+      </DatePicker>
+    </Field>
+  );
+}
+```
+
+## Dialog
+
+Use `DatePicker.Dialog` to present the calendar in a modal surface.
+
+```tsx
+import { useState } from 'react';
+import { DateField, DatePicker, Field } from '@cdx-ui/components';
+import type { DateId } from '@cdx-ui/formatters';
+
+export default function DatePickerDialogDemo() {
+  const [value, setValue] = useState<DateId | undefined>();
+
+  return (
+    <Field className="w-full max-w-xs">
+      <DatePicker value={value} onValueChange={setValue}>
+        <Field.Label>Transfer date</Field.Label>
+        <DateField.Group fullWidth>
+          <DateField.Input />
+          <DateField.Suffix>
+            <DatePicker.Trigger>
+              <DatePicker.TriggerIndicator />
+            </DatePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        <DatePicker.Dialog>
+          <DatePicker.Calendar aria-label="Transfer date" />
+        </DatePicker.Dialog>
+      </DatePicker>
+    </Field>
+  );
+}
+```
+
+## Bottom sheet
+
+Use `DatePicker.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, DatePicker, Field } from '@cdx-ui/components';
+import type { DateId } from '@cdx-ui/formatters';
+import { PickerBottomSheetFrame } from './_frame';
+
+export default function DatePickerBottomSheetDemo() {
+  const [value, setValue] = useState<DateId | undefined>();
+  const [open, setOpen] = useState(false);
+
+  return (
+    <PickerBottomSheetFrame>
+      <Field className="w-full max-w-xs">
+        <DatePicker value={value} onValueChange={setValue} isOpen={open} onOpenChange={setOpen}>
+          <Field.Label>Transfer date</Field.Label>
+          <DateField.Group fullWidth>
+            <DateField.Input />
+            <DateField.Suffix>
+              <DatePicker.Trigger>
+                <DatePicker.TriggerIndicator />
+              </DatePicker.Trigger>
+            </DateField.Suffix>
+          </DateField.Group>
+          <DatePicker.BottomSheet>
+            <BottomSheet.Header title="Select date" onClose={() => setOpen(false)} />
+            <BottomSheet.Content>
+              <DatePicker.Calendar aria-label="Transfer date" />
+            </BottomSheet.Content>
+          </DatePicker.BottomSheet>
+        </DatePicker>
+      </Field>
+    </PickerBottomSheetFrame>
+  );
+}
+```
+
+## Standalone
+
+Render a `Calendar` inline instead of a presentation surface when the field and calendar share the screen.
+
+```tsx
+import { useState } from 'react';
+import { Calendar, DateField, DatePicker, Field } from '@cdx-ui/components';
+import type { DateId } from '@cdx-ui/formatters';
+
+export default function DatePickerStandaloneDemo() {
+  const [value, setValue] = useState<DateId | undefined>();
+
+  return (
+    <Field className="w-full max-w-sm">
+      <DatePicker value={value} onValueChange={setValue}>
+        <Field.Label>Transfer date</Field.Label>
+        <DateField.Group fullWidth>
+          <DateField.Input />
+        </DateField.Group>
+        <Calendar
+          className="mt-2"
+          aria-label="Transfer date"
+          value={value}
+          onValueChange={setValue}
+        />
+      </DatePicker>
+    </Field>
+  );
+}
+```
+
+## Unavailable dates
+
+Pass `isDateUnavailable` to disable weekends, holidays, or any other day the calendar should not offer, and add an empty `Field.Error` to the `Field` so a typed unavailable or out-of-range date explains itself.
+
+```tsx
+import { useState } from 'react';
+import { DateField, DatePicker, Field } from '@cdx-ui/components';
+import { dateId, monthId, type DateId } from '@cdx-ui/formatters';
+import { isNonBusinessDay } from '../calendar/_business-days';
+
+const LABELS = { validationUnavailable: 'Payments do not process on weekends or bank holidays' };
+
+export default function DatePickerBusinessDaysDemo() {
+  const [value, setValue] = useState<DateId | undefined>();
+
+  return (
+    <Field className="w-full max-w-xs">
+      <Field.Label>Payment date</Field.Label>
+      <DatePicker
+        value={value}
+        onValueChange={setValue}
+        minValue={dateId('2026-11-02')}
+        isDateUnavailable={isNonBusinessDay}
+        labels={LABELS}
+      >
+        <DateField.Group fullWidth>
+          <DateField.Input />
+          <DateField.Suffix>
+            <DatePicker.Trigger>
+              <DatePicker.TriggerIndicator />
+            </DatePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        <DatePicker.Popover>
+          <DatePicker.Calendar defaultMonthId={monthId('2026-11-01')} aria-label="Payment date" />
+        </DatePicker.Popover>
+      </DatePicker>
+      <Field.Helper>Payments process on business days only.</Field.Helper>
+      <Field.Error />
+    </Field>
+  );
+}
+```
+
+## Custom error messages
+
+Override `validationBeforeMin`, `validationAfterMax`, and `validationUnavailable` in `labels` to reword the message an empty `Field.Error` shows, using `{date}` for the bound.
+
+```tsx
+import { useState } from 'react';
+import { DateField, DatePicker, Field } from '@cdx-ui/components';
+import { dateId, monthId, type DateId } from '@cdx-ui/formatters';
+import { isNonBusinessDay } from '../calendar/_business-days';
+
+const LABELS = {
+  validationBeforeMin: 'Payments can be scheduled from {date}',
+  validationAfterMax: 'Payments can be scheduled up to {date}',
+  validationUnavailable: 'Payments do not process on weekends or bank holidays',
+};
+
+export default function DatePickerCustomMessagesDemo() {
+  const [value, setValue] = useState<DateId | undefined>(dateId('2026-10-30'));
+
+  return (
+    <Field className="w-full max-w-xs">
+      <Field.Label>Payment date</Field.Label>
+      <DatePicker
+        value={value}
+        onValueChange={setValue}
+        minValue={dateId('2026-11-02')}
+        maxValue={dateId('2026-12-31')}
+        isDateUnavailable={isNonBusinessDay}
+        labels={LABELS}
+      >
+        <DateField.Group fullWidth>
+          <DateField.Input />
+          <DateField.Suffix>
+            <DatePicker.Trigger>
+              <DatePicker.TriggerIndicator />
+            </DatePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        <DatePicker.Popover>
+          <DatePicker.Calendar defaultMonthId={monthId('2026-11-01')} aria-label="Payment date" />
+        </DatePicker.Popover>
+      </DatePicker>
+      <Field.Helper>Payments process on business days only.</Field.Helper>
+      <Field.Error />
+    </Field>
+  );
+}
+```
+
+## Custom trigger
+
+Set `asChild` on `DatePicker.Trigger` to open the calendar from a custom pressable such as an `IconButton`, keeping the segmented field for direct entry. The trigger merges its press and expanded-state accessibility props onto the child.
+
+```tsx
+import { Box, DateField, DatePicker, Field, IconButton } from '@cdx-ui/components';
+import { CalendarToday } from '@cdx-ui/icons';
+
+export default function DatePickerCustomTriggerDemo() {
+  return (
+    <Field className="w-full max-w-xs">
+      <DatePicker>
+        <Field.Label>Transfer date</Field.Label>
+        <Box className="flex-row items-center gap-2">
+          <DateField.Group fullWidth>
+            <DateField.Input />
+          </DateField.Group>
+          <DatePicker.Trigger asChild>
+            <IconButton as={CalendarToday} variant="subtle" accessibilityLabel="Open calendar" />
+          </DatePicker.Trigger>
+        </Box>
+        <DatePicker.Popover>
+          <DatePicker.Calendar aria-label="Transfer date" />
+        </DatePicker.Popover>
+      </DatePicker>
+    </Field>
+  );
+}
+```
+
+## API
+
+### DatePicker
+
+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 — `DatePicker.Popover`, `DatePicker.Dialog`, or `DatePicker.BottomSheet` — per picker.
+
+`minValue`, `maxValue`, and `isDateUnavailable` apply to both the calendar and typed entry. The calendar disables days that break a rule; a complete typed date that breaks one is kept in the field and still emitted through `onValueChange`, but renders invalid. Partial input is never invalid. The picker reports its invalid state to the enclosing `Field`, so the field root, `Field.Helper`, and `Field.Error` reflect it wherever they sit in the field. A `Field.Error` with no children renders the matching `labels` message (`validationBeforeMin`, `validationAfterMax`, or `validationUnavailable`), with the `{date}` bound formatted in the picker's `locale`. `onValidationChange` reports the `DateValidationReason` (`beforeMin`, `afterMax`, or `unavailable`) and that message whenever the reason or the formatted message changes — including a new bound, `locale`, or `labels` that keeps the same reason — and `undefined` once the value is valid or cleared. It fires before paint, so anything you render from it appears in the same frame as the invalid styling. Consumer `isInvalid` is OR-ed with this validation: it can force the invalid state but cannot hide a rule violation. The same checks are available outside the component as `getDateValidationReason` and `formatDateValidationMessage`. Define `isDateUnavailable` outside the component or memoize it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `value?` | `DateId` | — | — |
+| `defaultValue?` | `DateId` | — | — |
+| `onValueChange?` | `((value: DateId) => void)` | — | — |
+| `isOpen?` | `boolean` | — | Controlled open state. Use `defaultOpen` for the uncontrolled variant. |
+| `defaultOpen?` | `boolean` | — | — |
+| `onOpenChange?` | `((open: boolean) => void)` | — | — |
+| `isDisabled?` | `boolean` | — | — |
+| `isReadOnly?` | `boolean` | — | — |
+| `isInvalid?` | `boolean` | — | Forces the invalid state. OR-ed with the picker's own validation: setting `true` marks the field invalid, but `false` never hides a `minValue` / `maxValue` / `isDateUnavailable` violation. |
+| `isRequired?` | `boolean` | — | — |
+| `minValue?` | `DateId` | — | Earliest selectable date, applied to the embedded calendar and to typed entry. Build with `dateId(...)`. |
+| `maxValue?` | `DateId` | — | Latest selectable date, applied to the embedded calendar and to typed entry. Build with `dateId(...)`. |
+| `isDateUnavailable?` | `((date: DateId) => boolean)` | — | Returns `true` for dates that cannot be selected, such as weekends or holidays. The calendar renders them disabled; a typed unavailable date is kept and emitted but renders invalid. Pass a stable (memoized) function. |
+| `onValidationChange?` | `((reason: DateValidationReason, message: string) => void)` | — | Called when the committed value starts or stops violating `minValue`, `maxValue`, or `isDateUnavailable`, and again when the formatted message changes while the reason stays the same — a new bound, `locale`, or `labels` while the value is still `beforeMin`, for example. Receives the reason and its `labels` message formatted in `locale`, or `undefined` for both once the value is valid or cleared. Fires before paint, so state set here renders in the same frame as the invalid styling. Not needed to show the message: an empty `Field.Error` anywhere in the enclosing `Field` already renders it. |
+| `name?` | `string` | — | — |
+| `locale?` | `string` | — | — |
+| `labels?` | `Partial<DateComponentLabels>` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Sub-components
+
+### DatePicker.Trigger
+
+Toggles the presentation surface and announces its expanded state. For an editable field, wrap only the `DatePicker.TriggerIndicator` inside a `DateField.Suffix`; for surface-driven selection, wrap the whole `DateField.Group` so the entire field is the tap target. Its accessible name defaults to the picker's `openDatePicker` 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).
+
+### DatePicker.TriggerIndicator
+
+Renders the calendar icon inside `DatePicker.Trigger`. Takes no props.
+
+### DatePicker.Calendar
+
+Renders the picker's `Calendar`, wired to the shared value, `minValue`, `maxValue`, `isDateUnavailable`, `locale`, and `labels`. Accepts all [`Calendar`](https://design.candescent.com/docs/components/calendar/content.md) props except `value`, `onValueChange`, `minValue`, `maxValue`, and `isDateUnavailable`, 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). |
+| `defaultValue?` | `DateId` | — | Uncontrolled initial selection as a `YYYY-MM-DD` string. |
+| `locale?` | `string` | — | BCP 47 locale for weekday and month formatting. Defaults to `en-US`. |
+| `labels?` | `Partial<DateComponentLabels>` | — | — |
+| `monthId?` | `MonthId` | — | Month shown in the grid as a `YYYY-MM-01` string. Follows the selected `value` unless controlled. |
+| `defaultMonthId?` | `MonthId` | — | Uncontrolled initial month as a `YYYY-MM-01` string. |
+| `onMonthIdChange?` | `((monthId: MonthId) => void)` | — | — |
+| `disabled?` | `boolean` | — | — |
+| `key?` | `React.Key \| null` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### DatePicker.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.
+
+### DatePicker.Dialog
+
+Presents the calendar in a modal dialog. Wires the surface's open state and renders its children.
+
+### DatePicker.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 `DatePicker.Calendar` to name the grid. `DatePicker.Trigger` announces the localized `openDatePicker` label, which `labels` can override. While `disabled`, the trigger does not open a surface.
+
+Unavailable days render in the calendar's disabled state with no per-day reason announced, so add a `Field.Helper` that explains which days are unavailable and why — for example, "Payments process on business days only." When a typed date breaks a rule, `Field.Error` replaces the helper and is announced as an alert. On web the segments also carry `aria-invalid`; on iOS and Android, which have no equivalent, each segment's accessible name gains the localized `segmentInvalid` label (for example "Day, invalid") and its hint carries the error message.

package/docs/components/date-range-picker/content.md

@@ -0,0 +1,301 @@
+# Date Range Picker (https://design.candescent.com/docs/components/date-range-picker)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=12449-28564), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/date-time-daterangepicker--standalone)
+
+`DateRangePicker` pairs two segmented `DateField` inputs with a `RangeCalendar` and coordinates the surface that presents it. The start and end values are `DateId` strings in `YYYY-MM-DD` format.
+
+```tsx
+import { DateField, DateRangePicker, Field } from '@cdx-ui/components';
+```
+
+## Basic
+
+Wrap the whole `DateField.Group` — a start input, a `DateRangePicker.RangeSeparator`, an end input, and a decorative `DateRangePicker.TriggerIndicator` in a `DateField.Suffix` — in a single `DateRangePicker.Trigger` so the entire range field is one large tap target. Because range selection is surface-driven, there is no typing to interrupt. `DateRangePicker.Popover` anchors to the field and is the preferred surface on web.
+
+```tsx
+import { useState } from 'react';
+import { DateField, DateRangePicker, Field, type DateRangeValue } from '@cdx-ui/components';
+
+export default function DateRangePickerBasicDemo() {
+  const [value, setValue] = useState<DateRangeValue | undefined>();
+
+  return (
+    <Field className="w-full max-w-sm">
+      <DateRangePicker value={value} onValueChange={setValue}>
+        <Field.Label>Trip dates</Field.Label>
+        <DateRangePicker.Trigger className="w-full">
+          <DateField.Group fullWidth>
+            <DateField.Input slot="start" />
+            <DateRangePicker.RangeSeparator />
+            <DateField.Input slot="end" />
+            <DateField.Suffix>
+              <DateRangePicker.TriggerIndicator />
+            </DateField.Suffix>
+          </DateField.Group>
+        </DateRangePicker.Trigger>
+        <DateRangePicker.Popover>
+          <DateRangePicker.Calendar accessibilityLabel="Trip dates" />
+        </DateRangePicker.Popover>
+      </DateRangePicker>
+    </Field>
+  );
+}
+```
+
+## Dialog
+
+Use `DateRangePicker.Dialog` to present the range calendar in a modal surface.
+
+```tsx
+import { useState } from 'react';
+import { DateField, DateRangePicker, Field, type DateRangeValue } from '@cdx-ui/components';
+
+export default function DateRangePickerDialogDemo() {
+  const [value, setValue] = useState<DateRangeValue | undefined>();
+
+  return (
+    <Field className="w-full max-w-sm">
+      <DateRangePicker value={value} onValueChange={setValue}>
+        <Field.Label>Trip dates</Field.Label>
+        <DateRangePicker.Trigger className="w-full">
+          <DateField.Group fullWidth>
+            <DateField.Input slot="start" />
+            <DateRangePicker.RangeSeparator />
+            <DateField.Input slot="end" />
+            <DateField.Suffix>
+              <DateRangePicker.TriggerIndicator />
+            </DateField.Suffix>
+          </DateField.Group>
+        </DateRangePicker.Trigger>
+        <DateRangePicker.Dialog>
+          <DateRangePicker.Calendar accessibilityLabel="Trip dates" />
+        </DateRangePicker.Dialog>
+      </DateRangePicker>
+    </Field>
+  );
+}
+```
+
+## Bottom sheet
+
+Use `DateRangePicker.BottomSheet` to present the range 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,
+  DateRangePicker,
+  Field,
+  type DateRangeValue,
+} from '@cdx-ui/components';
+import { PickerBottomSheetFrame } from './_frame';
+
+export default function DateRangePickerBottomSheetDemo() {
+  const [value, setValue] = useState<DateRangeValue | undefined>();
+  const [open, setOpen] = useState(false);
+
+  return (
+    <PickerBottomSheetFrame>
+      <Field className="w-full max-w-sm">
+        <DateRangePicker
+          value={value}
+          onValueChange={setValue}
+          isOpen={open}
+          onOpenChange={setOpen}
+        >
+          <Field.Label>Trip dates</Field.Label>
+          <DateRangePicker.Trigger className="w-full">
+            <DateField.Group fullWidth>
+              <DateField.Input slot="start" />
+              <DateRangePicker.RangeSeparator />
+              <DateField.Input slot="end" />
+              <DateField.Suffix>
+                <DateRangePicker.TriggerIndicator />
+              </DateField.Suffix>
+            </DateField.Group>
+          </DateRangePicker.Trigger>
+          <DateRangePicker.BottomSheet>
+            <BottomSheet.Header title="Select dates" onClose={() => setOpen(false)} />
+            <BottomSheet.Content>
+              <DateRangePicker.Calendar accessibilityLabel="Trip dates" />
+            </BottomSheet.Content>
+          </DateRangePicker.BottomSheet>
+        </DateRangePicker>
+      </Field>
+    </PickerBottomSheetFrame>
+  );
+}
+```
+
+## Standalone
+
+Render a `DateRangePicker.Calendar` inline instead of a presentation surface when the fields and calendar share the screen.
+
+```tsx
+import { useState } from 'react';
+import { DateField, DateRangePicker, Field, type DateRangeValue } from '@cdx-ui/components';
+
+export default function DateRangePickerStandaloneDemo() {
+  const [value, setValue] = useState<DateRangeValue | undefined>();
+
+  return (
+    <Field className="w-full max-w-sm">
+      <DateRangePicker value={value} onValueChange={setValue}>
+        <Field.Label>Trip dates</Field.Label>
+        <DateField.Group fullWidth>
+          <DateField.Input slot="start" />
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end" />
+        </DateField.Group>
+        <DateRangePicker.Calendar className="mt-2" accessibilityLabel="Trip dates" />
+      </DateRangePicker>
+    </Field>
+  );
+}
+```
+
+## Custom trigger
+
+Set `asChild` on `DateRangePicker.Trigger` to drive selection from a custom pressable such as a `Chip` — ideal for a filter row where the chip reflects the active range. The trigger merges its press and expanded-state accessibility props onto the child.
+
+```tsx
+import { useState } from 'react';
+import { Box, Chip, DateRangePicker, type DateRangeValue } from '@cdx-ui/components';
+import { CalendarToday } from '@cdx-ui/icons';
+
+const monthDay = new Intl.DateTimeFormat('en-US', { month: 'short', day: 'numeric' });
+
+function formatDateId(id: string) {
+  const [year, month, day] = id.split('-').map(Number);
+  return monthDay.format(new Date(year, month - 1, day));
+}
+
+function formatRange(value: DateRangeValue | undefined) {
+  if (!value?.startId) return 'Any dates';
+  if (!value.endId) return `${formatDateId(value.startId)} – …`;
+  return `${formatDateId(value.startId)} – ${formatDateId(value.endId)}`;
+}
+
+export default function DateRangePickerCustomTriggerDemo() {
+  const [value, setValue] = useState<DateRangeValue | undefined>();
+  const hasRange = !!value?.startId;
+
+  return (
+    <DateRangePicker value={value} onValueChange={setValue}>
+      <Box className="flex-row flex-wrap items-center gap-2">
+        <Chip variant="outline">
+          <Chip.Label>All accounts</Chip.Label>
+        </Chip>
+        <DateRangePicker.Trigger asChild>
+          <Chip variant={hasRange ? 'subtle' : 'outline'} color={hasRange ? 'action' : 'neutral'}>
+            <Chip.Icon as={CalendarToday} position="leading" />
+            <Chip.Label>{formatRange(value)}</Chip.Label>
+          </Chip>
+        </DateRangePicker.Trigger>
+        <Chip variant="outline">
+          <Chip.Label>All statuses</Chip.Label>
+        </Chip>
+      </Box>
+      <DateRangePicker.Popover>
+        <DateRangePicker.Calendar accessibilityLabel="Filter by date range" />
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+  );
+}
+```
+
+## API
+
+### DateRangePicker
+
+Root of the compound. Owns the start and end values, open state, `locale`, and `labels`, and provides `DateField` styling context to the fields. Compose exactly one presentation surface — `DateRangePicker.Popover`, `DateRangePicker.Dialog`, or `DateRangePicker.BottomSheet` — per picker.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `value?` | `DateRangeValue` | — | Controlled range value as `{ startId, endId? }`. Build the ids with `dateId(...)` from `@cdx-ui/formatters` — a bare string will not type-check. |
+| `defaultValue?` | `DateRangeValue` | — | Uncontrolled initial range, in the same shape as `value`. |
+| `onValueChange?` | `((value: DateRangeValue) => void)` | — | Called as the range changes. Emits `{ startId, endId? }` during selection — a **partial** range (with `endId` undefined) is emitted after the first endpoint is picked — and `undefined` when the range is fully cleared. |
+| `focusedField?` | `'start' \| 'end'` | — | — |
+| `defaultFocusedField?` | `'start' \| 'end'` | — | — |
+| `onFocusedFieldChange?` | `((field: RangeCalendarFocus) => void)` | — | — |
+| `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` | — | — |
+| `locale?` | `string` | — | — |
+| `labels?` | `Partial<DateComponentLabels>` | — | — |
+| `name?` | `string` | — | Form field name used when the selected range is submitted. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Sub-components
+
+### DateRangePicker.Trigger
+
+Toggles the presentation surface and announces its expanded state. Because range selection is surface-driven, wrap the entire `DateField.Group` so the whole field is the tap target, with a decorative `DateRangePicker.TriggerIndicator` in the `DateField.Suffix`. Its accessible name defaults to the picker's `openDateRangePicker` 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).
+
+### DateRangePicker.TriggerIndicator
+
+Renders the decorative calendar icon, typically inside the `DateField.Suffix` of a full-field `DateRangePicker.Trigger`. Takes no props.
+
+### DateRangePicker.RangeSeparator
+
+Renders the localized separator between the start and end inputs. Takes no props.
+
+### DateRangePicker.Calendar
+
+Renders the picker's `RangeCalendar`, wired to the shared start and end values, `locale`, and `labels`. Accepts all [`RangeCalendar`](https://design.candescent.com/docs/components/range-calendar/content.md) props except the range value and focus props, which the picker controls.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the calendar's own styles. |
+| `children?` | `ReactNode` | — | Custom calendar body. Omit to render the default header and month grid. |
+| `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` | — | Render the consumer's child element in place of the default `View` host. |
+| `defaultFocusedField?` | `'start' \| 'end'` | `'start'` | Initial active field when uncontrolled. |
+| `locale?` | `string` | `'en-US'` | BCP 47 locale for month and weekday names. |
+| `labels?` | `Partial<DateComponentLabels>` | — | Overrides for the built-in UI copy, such as the previous- and next-month button labels. |
+| `defaultStartValue?` | `DateId` | — | Initial range start when uncontrolled. |
+| `defaultEndValue?` | `DateId` | — | Initial range end when uncontrolled. |
+| `monthId?` | `MonthId` | — | Controlled visible month. When set, `defaultMonthId` has no effect. |
+| `defaultMonthId?` | `MonthId` | — | Initial visible month when uncontrolled. Defaults to the month of the range, or today. |
+| `onMonthIdChange?` | `((monthId: MonthId) => void)` | — | Called with the new visible month when the user navigates months. |
+| `minValue?` | `DateId` | — | Earliest selectable date. Build with `dateId(...)` from `@cdx-ui/formatters`. |
+| `maxValue?` | `DateId` | — | Latest selectable date. Build with `dateId(...)` from `@cdx-ui/formatters`. |
+| `disabled?` | `boolean` | `false` | Prevents day selection and month navigation. |
+| `key?` | `React.Key \| null` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### DateRangePicker.Popover
+
+Presents the range 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.
+
+### DateRangePicker.Dialog
+
+Presents the range calendar in a modal dialog. Wires the surface's open state and renders its children.
+
+### DateRangePicker.BottomSheet
+
+Presents the range 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 `DateRangePicker.Calendar` to name the grid. `DateRangePicker.Trigger` announces the localized `openDateRangePicker` label, which `labels` can override. While `disabled`, the trigger does not open a surface.