@utilitywarehouse/hearth-react-native 0.3.1 → 0.4.1

package/build/tokens/components/light/date-picker.js

@@ -20,6 +20,7 @@ export default {
         item: {
             borderRadius: 8,
             minWidth: 32,
+            rangeBackground: '#f7f7f7',
             roundelBackgroundColorInverted: '#fcfbf2',
             roundelHeight: 6,
             roundelWidth: 6,

package/build/tokens/components/light/illustrations.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+declare const _default: {
+    readonly mode: "light";
+};
+export default _default;

package/build/tokens/components/light/illustrations.js

@@ -0,0 +1,6 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+export default {
+    mode: 'light',
+};

package/build/tokens/components/light/index.d.ts

@@ -21,6 +21,7 @@ export { default as expandableCard } from './expandable-card';
 export { default as formField } from './form-field';
 export { default as iconButton } from './icon-button';
 export { default as iconContainer } from './icon-container';
+export { default as illustrations } from './illustrations';
 export { default as indicatorIconButton } from './indicator-icon-button';
 export { default as inlineLink } from './inline-link';
 export { default as input } from './input';

package/build/tokens/components/light/index.js

@@ -21,6 +21,7 @@ export { default as expandableCard } from './expandable-card';
 export { default as formField } from './form-field';
 export { default as iconButton } from './icon-button';
 export { default as iconContainer } from './icon-container';
+export { default as illustrations } from './illustrations';
 export { default as indicatorIconButton } from './indicator-icon-button';
 export { default as inlineLink } from './inline-link';
 export { default as input } from './input';

package/build/tokens/components/light/segmented-control.d.ts

@@ -2,10 +2,10 @@
  * Do not edit directly, this file was auto-generated.
  */
 declare const _default: {
-    readonly borderRadius: 6;
+    readonly borderRadius: 9999;
     readonly gap: 6;
     readonly group: {
-        readonly borderRadius: 8;
+        readonly borderRadius: 9999;
         readonly borderWidth: 1;
         readonly gap: 4;
         readonly height: 48;

package/build/tokens/components/light/segmented-control.js

@@ -2,10 +2,10 @@
  * Do not edit directly, this file was auto-generated.
  */
 export default {
-    borderRadius: 6,
+    borderRadius: 9999,
     gap: 6,
     group: {
-        borderRadius: 8,
+        borderRadius: 9999,
         borderWidth: 1,
         gap: 4,
         height: 48,

package/build/tokens/components/light/table.d.ts

@@ -13,6 +13,9 @@ declare const _default: {
     readonly headerCell: {
         readonly borderWidth: 2;
         readonly gap: 8;
+        readonly neutral: {
+            readonly backgroundColor: "#f1efe4";
+        };
         readonly paddingHorizontal: 12;
         readonly paddingVertical: 16;
     };

package/build/tokens/components/light/table.js

@@ -13,6 +13,9 @@ export default {
     headerCell: {
         borderWidth: 2,
         gap: 8,
+        neutral: {
+            backgroundColor: '#f1efe4',
+        },
         paddingHorizontal: 12,
         paddingVertical: 16,
     },

package/build/utils/index.d.ts

@@ -3,4 +3,5 @@ export { default as formatThousands } from './formatThousands';
 export { default as getFlattenedColorValue } from './getFlattenedColorValue';
 export { default as getStyleValue } from './getStyleValue';
 export { default as hexWithOpacity } from './hexWithOpacity';
+export { default as isEqual } from './isEqual';
 export * from './styleUtils';

package/build/utils/index.js

@@ -3,4 +3,5 @@ export { default as formatThousands } from './formatThousands';
 export { default as getFlattenedColorValue } from './getFlattenedColorValue';
 export { default as getStyleValue } from './getStyleValue';
 export { default as hexWithOpacity } from './hexWithOpacity';
+export { default as isEqual } from './isEqual';
 export * from './styleUtils';

package/build/utils/isEqual.d.ts

@@ -0,0 +1,2 @@
+declare const isEqual: (a: any, b: any) => boolean;
+export default isEqual;

package/build/utils/isEqual.js

@@ -0,0 +1,29 @@
+const isEqual = (a, b) => {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== 'object' || a === null || b === null)
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a)) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (!isEqual(a[i], b[i]))
+                return false;
+        }
+        return true;
+    }
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    for (const key of keysA) {
+        if (!keysB.includes(key) || !isEqual(a[key], b[key]))
+            return false;
+    }
+    return true;
+};
+export default isEqual;

package/chromatic.config.json

@@ -0,0 +1,6 @@
+{
+  "onlyChanged": true,
+  "projectId": "Project:68e3ad5c6e80b57678cad6c6",
+  "storybookBaseDir": "packages/react-native",
+  "zip": true
+}

package/docs/components/AllComponents.web.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useEffect, useRef } from 'react';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
 
 import { BottomSheetModalMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
 import {
@@ -18,6 +18,7 @@ import {
   Badge,
   BodyText,
   BottomSheet,
+  BottomSheetModal,
   BottomSheetModalProvider,
   BottomSheetView,
   Box,
@@ -26,6 +27,9 @@ import {
   Center,
   Checkbox,
   CurrencyInput,
+  DatePicker,
+  DatePickerInput,
+  DateType,
   DescriptionList,
   DescriptionListItem,
   DetailText,
@@ -110,6 +114,11 @@ const AllComponents: React.FC = () => {
   const handleModalOpenPress = useCallback(() => {
     modalRef.current?.present();
   }, []);
+  const [selected, setSelected] = useState<DateType>();
+  const datePickerRef = useRef<BottomSheetModal>(null);
+  const handleDatePickerOpenPress = useCallback(() => {
+    datePickerRef.current?.present();
+  }, []);
   useEffect(() => {
     if (bottomSheetRef.current) {
       setTimeout(() => {
@@ -124,8 +133,16 @@ const AllComponents: React.FC = () => {
       }, 400);
     }
   }, [modalRef]);
+  useEffect(() => {
+    if (datePickerRef.current) {
+      setTimeout(() => {
+        datePickerRef.current?.present();
+      }, 500);
+    }
+  }, [datePickerRef]);
   const [switchEnabled, setSwitchEnabled] = React.useState(false);
   const toggleSwitch = () => setSwitchEnabled(!switchEnabled);
+
   const [colorMode] = useColorMode();
   const isDark = colorMode === 'dark';
   return (
@@ -225,6 +242,30 @@ const AllComponents: React.FC = () => {
               <CurrencyInput />
             </Center>
           </ComponentWrapper>
+          <ComponentWrapper name="Date Picker" link="/?path=/docs/components-date-picker--docs">
+            <Center flex={1}>
+              <Button onPress={handleDatePickerOpenPress}>Open Date Picker</Button>
+              <BottomSheetModalProvider>
+                <DatePicker
+                  ref={datePickerRef}
+                  mode="single"
+                  date={selected}
+                  onChange={({ date }) => setSelected(date)}
+                  onCancel={() => setSelected(undefined)}
+                />
+              </BottomSheetModalProvider>
+            </Center>
+          </ComponentWrapper>
+          <ComponentWrapper
+            name="Date Picker Input"
+            link="/?path=/docs/forms-date-picker-input--docs"
+          >
+            <Center flex={1} padding="200">
+              <BottomSheetModalProvider>
+                <DatePickerInput placeholder="DD/MM/YYYY" />
+              </BottomSheetModalProvider>
+            </Center>
+          </ComponentWrapper>
           <ComponentWrapper
             name="Description List"
             link="/?path=/docs/components-description-list--docs"
@@ -241,6 +282,7 @@ const AllComponents: React.FC = () => {
               <DetailText>This is some Detail Text</DetailText>
             </Center>
           </ComponentWrapper>
+
           <ComponentWrapper name="Divider" link="/?path=/docs/components-divider--docs">
             <Center flex={1} p="300">
               <BodyText>This text is divided</BodyText>

package/docs/components/ViewWrap.tsx

@@ -0,0 +1,32 @@
+import { Dimensions, Platform, View, ViewProps } from 'react-native';
+import { UnistylesRuntime } from '../../src/core';
+
+const ViewWrap = ({ children }: { children: ViewProps['children'] }) => (
+  <View
+    style={{
+      width: Platform.OS === 'web' ? '100%' : Dimensions.get('window').width,
+      height:
+        Platform.OS === 'web'
+          ? '100%'
+          : Dimensions.get('window').height -
+            UnistylesRuntime.insets.top -
+            UnistylesRuntime.insets.bottom -
+            33,
+
+      position: 'absolute',
+      top: 0,
+      left: 0,
+      right: 0,
+      bottom: 0,
+      flex: 1,
+      marginVertical: Platform.OS === 'web' ? 0 : -8,
+      justifyContent: 'center',
+      alignItems: 'center',
+      padding: 16,
+    }}
+  >
+    {children}
+  </View>
+);
+
+export default ViewWrap;

package/docs/components/index.ts

@@ -8,3 +8,4 @@ export { default as SwitchList } from './SwitchList';
 export { default as UsageWrap } from './UsageWrap';
 export { default as VariantTitle } from './VariantTitle';
 export { default as ViewFigmaButton } from './ViewFigmaButton';
+export { default as ViewWrap } from './ViewWrap';

package/docs/getting-started.mdx

@@ -9,12 +9,12 @@ import { BackToTopButton, NextPrevPage } from './components';
 You can just start using the components from the `@utilitywarehouse/hearth-react-native` package.
 
 ```tsx
-import { Box, Alert, Text } from '@utilitywarehouse/hearth-react-native';
+import { Box, Alert, BodyText } from '@utilitywarehouse/hearth-react-native';
 
 const App: React.FC = () => (
-  <Box>
+  <Box p="200">
     <Alert variant="info" text="Welcome to Hearth React Native!" />
-    <Text>Start building your app with Hearth React Native components.</Text>
+    <BodyText>Start building your app with Hearth React Native components.</BodyText>
   </Box>
 );
 ```
@@ -25,15 +25,15 @@ By default the light colour mode is enabled. If you want to enable dark mode, yo
 use the `useColorMode` hook to toggle between light and dark modes.
 
 ```tsx
-import { useColorMode, Box, Alert, Text, Button } from '@utilitywarehouse/hearth-react-native';
+import { useColorMode, Box, Alert, BodyText, Button } from '@utilitywarehouse/hearth-react-native';
 
 const App: React.FC = () => {
   const [colorMode, setColorMode] = useColorMode();
 
   return (
-    <Box>
+    <Box p="200">
       <Alert variant="info" text="Welcome to Hearth React Native!" />
-      <Text>Start building your app with Hearth React Native components.</Text>
+      <BodyText>Start building your app with Hearth React Native components.</BodyText>
       <Button onPress={() => setColorMode(colorMode === 'light' ? 'dark' : 'light')}>
         Toggle Color Mode
       </Button>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utilitywarehouse/hearth-react-native",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Utility Warehouse React Native UI library",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -8,7 +8,6 @@
   "type": "module",
   "sideEffects": false,
   "dependencies": {
-    "@expo/html-elements": "latest",
     "@gluestack-ui/accordion": "1.0.7",
     "@gluestack-ui/alert": "0.1.15",
     "@gluestack-ui/button": "1.0.7",
@@ -20,7 +19,8 @@
     "@gluestack-ui/radio": "0.1.33",
     "@gluestack-ui/spinner": "0.1.14",
     "@gluestack-ui/switch": "0.1.22",
-    "@gluestack-ui/textarea": "0.1.23"
+    "@gluestack-ui/textarea": "0.1.23",
+    "dayjs": "^1.11.13"
   },
   "devDependencies": {
     "@babel/plugin-proposal-export-namespace-from": "^7.18.9",
@@ -35,6 +35,7 @@
     "@types/react": "^19.1.10",
     "@vitest/browser": "^3.2.4",
     "@vitest/coverage-v8": "^3.2.4",
+    "chromatic": "^13.3.0",
     "eslint-plugin-storybook": "9.1.6",
     "playwright": "^1.53.1",
     "prismjs": "^1.30.0",
@@ -53,13 +54,13 @@
     "vite": "^7.1.3",
     "vitest": "^3.2.4",
     "@utilitywarehouse/hearth-fonts": "^0.0.3",
-    "@utilitywarehouse/hearth-react-native-icons": "^0.4.0",
-    "@utilitywarehouse/hearth-react-icons": "^0.4.0",
-    "@utilitywarehouse/hearth-tokens": "^0.1.0"
+    "@utilitywarehouse/hearth-react-icons": "^0.5.0",
+    "@utilitywarehouse/hearth-react-native-icons": "^0.5.0",
+    "@utilitywarehouse/hearth-tokens": "^0.1.1"
   },
   "peerDependencies": {
     "@gorhom/bottom-sheet": "^5.0.0",
-    "@utilitywarehouse/hearth-react-native-icons": "~0.4.0",
+    "@utilitywarehouse/hearth-react-native-icons": "0.4.0",
     "react": ">=17 || ^18.0.0 || ^19.0.0",
     "react-native": ">=0.77",
     "react-native-gesture-handler": "^2.22.0",
@@ -80,6 +81,8 @@
     "figma:publish": "figma connect publish",
     "test": "echo \"Error: no test specified\" && exit 1",
     "dev": "storybook dev -p 6006",
-    "build:storybook": "storybook build"
+    "build:storybook": "storybook build",
+    "build-storybook": "storybook build",
+    "chromatic": "npx chromatic --project-token=chpt_cce0fb1ebd95d2a --build-script-name build:storybook"
   }
 }

package/src/components/CurrencyInput/CurrencyInput.tsx

@@ -47,13 +47,14 @@ const CurrencyInput = ({
       style={styles.wrap}
     >
       <InputSlot>
-        <DetailText size="4xl" style={styles.text}>
+        <DetailText size="4xl" style={styles.text} accessible={false}>
           £
         </DetailText>
       </InputSlot>
       <InputField
         inputMode="decimal"
         inBottomSheet={inBottomSheet}
+        accessibilityHint='Enter the amount in pounds and pence, for example "10.99"'
         {...rest}
         placeholder={getPlaceholder}
         keyboardType="decimal-pad"

package/src/components/DatePicker/DatePicker.context.ts

@@ -0,0 +1,23 @@
+import { createContext, useContext } from 'react';
+import type { DatePickerBaseProps, DateType } from './DatePicker.props';
+import { CalendarViews } from './enums';
+
+export interface DatePickerContextType extends DatePickerBaseProps {
+  showOutsideDays: boolean;
+  firstDayOfWeek: number;
+  calendarView: CalendarViews;
+  currentDate: DateType; // used for latest state of calendar based on Month and Year
+  currentYear: number;
+  numerals: 'latn';
+  setCalendarView: (value: CalendarViews) => void;
+  onSelectDate: (date: DateType) => void;
+  onSelectMonth: (month: number) => void;
+  onSelectYear: (year: number) => void;
+  onChangeMonth: (value: number) => void;
+  onChangeYear: (value: number) => void;
+  closeDatePicker: () => void;
+}
+
+export const DatePickerContext = createContext({} as DatePickerContextType);
+
+export const useDatePickerContext = () => useContext(DatePickerContext);

package/src/components/DatePicker/DatePicker.docs.mdx

@@ -0,0 +1,239 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { Button, Center } from '../../';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './DatePicker.stories';
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=3725-357" />
+
+<Meta title="Components / Date Picker" />
+
+<BackToTopButton />
+
+# Date Picker
+
+The `DatePicker` component presents a calendar experience in a bottom sheet so people can choose one or more dates without leaving the current screen. It supports single-day, ranged, and multi-date selection while respecting locale, calendar, and availability rules.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+  - [`DatePicker`](#datepicker)
+  - [Change handlers](#change-handlers)
+  - [Imperative API](#imperative-api)
+- [Examples](#examples)
+  - [Range selection](#range-selection)
+  - [Multiple selection](#multiple-selection)
+- [Integration notes](#integration-notes)
+- [Accessibility](#accessibility)
+  - [Screen reader support](#screen-reader-support)
+  - [Keyboard navigation](#keyboard-navigation)
+  - [Best practices](#best-practices)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+Use the `DatePicker` with a ref so you can present and dismiss the bottom sheet when people tap a trigger like a button or form field. The picker respects the locale and calendar you provide and can be configured to limit which dates are selectable.
+
+<UsageWrap>
+  <Center>
+    <Button onPress={() => {}}>Pick a date</Button>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { useRef, useState } from 'react';
+import {
+  BottomSheetModalProvider,
+  Button,
+  DatePicker,
+  type DateType,
+} from '@utilitywarehouse/hearth-react-native';
+
+const BookingDates = () => {
+  const pickerRef = useRef(null);
+  const [selected, setSelected] = useState<DateType>();
+
+  return (
+    <BottomSheetModalProvider>
+      <Button onPress={() => pickerRef.current?.present()}>Choose booking date</Button>
+
+      <DatePicker
+        ref={pickerRef}
+        mode="single"
+        date={selected}
+        onChange={({ date }) => setSelected(date)}
+        onCancel={() => setSelected(undefined)}
+        minDate={new Date()}
+      />
+    </BottomSheetModalProvider>
+  );
+};
+```
+
+## Props
+
+### `DatePicker`
+
+The `DatePicker` extends the `BottomSheetModal` component. The table below highlights the most frequently used props.
+
+| Prop                 | Type                                          | Default            | Description                                                                                               |
+| -------------------- | --------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------- |
+| `mode`               | `'single' \| 'range' \| 'multiple'`           | `'single'`         | Controls whether the picker returns one date, a start/end range, or multiple discrete dates.              |
+| `timeZone`           | `string`                                      | `-`                | IANA time zone identifier applied when normalising and comparing dates.                                   |
+| `date`               | `DateType`                                    | `-`                | Selected date in single mode.                                                                             |
+| `startDate`          | `DateType`                                    | `-`                | Range start value in range mode.                                                                          |
+| `endDate`            | `DateType`                                    | `-`                | Range end value in range mode.                                                                            |
+| `dates`              | `DateType[]`                                  | `-`                | Selected dates in multiple mode.                                                                          |
+| `min`                | `number`                                      | `-`                | Minimum length of a selected range (in days) when using range mode.                                       |
+| `max`                | `number`                                      | `-`                | Maximum length of a selected range (in days) or the maximum number of selected dates in multiple mode.    |
+| `onChange`           | `SingleChange \| RangeChange \| MultiChange`  | `-`                | Callback fired after a selection changes.                                                                 |
+| `minDate`            | `DateType`                                    | `-`                | Earliest selectable date. Values before this are disabled.                                                |
+| `maxDate`            | `DateType`                                    | `-`                | Latest selectable date. Values after this are disabled.                                                   |
+| `enabledDates`       | `DateType[] \| ((date: DateType) => boolean)` | `-`                | List or predicate that marks which dates can be chosen.                                                   |
+| `disabledDates`      | `DateType[] \| ((date: DateType) => boolean)` | `-`                | List or predicate that marks dates that cannot be chosen.                                                 |
+| `firstDayOfWeek`     | `number`                                      | `1`                | Index of the first weekday (0 = Sunday, 6 = Saturday).                                                    |
+| `showOutsideDays`    | `boolean`                                     | `true`             | Shows the trailing and leading days from adjacent months.                                                 |
+| `initialView`        | `'day' \| 'month' \| 'year'`                  | `'day'`            | Determines the first calendar view when the sheet opens.                                                  |
+| `containerHeight`    | `number`                                      | `CONTAINER_HEIGHT` | Height of the calendar container.                                                                         |
+| `weekdaysHeight`     | `number`                                      | `WEEKDAYS_HEIGHT`  | Height of the weekday header row.                                                                         |
+| `navigationPosition` | `'around' \| 'right' \| 'left'`               | `'right'`          | Placement of the navigation controls.                                                                     |
+| `weekdaysFormat`     | `'min' \| 'short' \| 'full'`                  | `'min'`            | Formatting used for weekday labels.                                                                       |
+| `monthsFormat`       | `'short' \| 'full'`                           | `'short'`          | Formatting used for month names.                                                                          |
+| `monthCaptionFormat` | `'short' \| 'full'`                           | `'full'`           | Formatting used for the heading above the calendar grid.                                                  |
+| `multiRangeMode`     | `boolean`                                     | `-`                | Enables an experimental range selection where users can keep choosing additional spans before confirming. |
+| `hideHeader`         | `boolean`                                     | `-`                | Hides the calendar header controls.                                                                       |
+| `hideFooter`         | `boolean`                                     | `-`                | Hides the footer actions.                                                                                 |
+| `hideWeekdays`       | `boolean`                                     | `-`                | Removes the weekday labels row.                                                                           |
+| `disableMonthPicker` | `boolean`                                     | `-`                | Prevents switching to the month selection view.                                                           |
+| `disableYearPicker`  | `boolean`                                     | `-`                | Prevents switching to the year selection view.                                                            |
+| `month`              | `number`                                      | `-`                | Forces the calendar to display a specific month (0-11).                                                   |
+| `year`               | `number`                                      | `-`                | Forces the calendar to display a specific year.                                                           |
+| `onMonthChange`      | `(month: number) => void`                     | `() => {}`         | Fired when the displayed month changes.                                                                   |
+| `onYearChange`       | `(year: number) => void`                      | `() => {}`         | Fired when the displayed year changes.                                                                    |
+| `onCancel`           | `() => void`                                  | `() => {}`         | Fired when the cancel action is triggered from the footer.                                                |
+| `ref`                | `Ref<BottomSheetModalMethods>`                | `-`                | Gives imperative access to the underlying bottom sheet for presenting or dismissing the picker.           |
+
+### Change handlers
+
+Each selection mode provides specialised payloads when `onChange` fires:
+
+- **Single**: `{ date: DateType }`
+- **Range**: `{ startDate: DateType; endDate: DateType }`
+- **Multiple**: `{ dates: DateType[]; datePressed?: DateType; change: 'added' | 'removed' | 'updated' }`
+
+### Imperative API
+
+Attach a ref that conforms to `BottomSheetModalMethods` so you can call `present()`, `close()`, or `dismiss()` as needed. This matches the API surface of `BottomSheetModal`.
+
+## Examples
+
+### Range selection
+
+<Canvas of={Stories.Range} />
+
+```tsx
+import { useRef, useState } from 'react';
+import {
+  BottomSheetModalProvider,
+  Button,
+  DatePicker,
+  type DateType,
+} from '@utilitywarehouse/hearth-react-native';
+
+const Example = () => {
+  const pickerRef = useRef(null);
+  const [range, setRange] = useState<{ startDate?: DateType; endDate?: DateType }>({});
+
+  return (
+    <BottomSheetModalProvider>
+      <Button onPress={() => pickerRef.current?.present()}>Choose booking dates</Button>
+
+      <DatePicker
+        ref={pickerRef}
+        mode="range"
+        startDate={range.startDate}
+        endDate={range.endDate}
+        onChange={({ startDate, endDate }) => setRange({ startDate, endDate })}
+        onCancel={() => setRange({})}
+        minDate={new Date()}
+        min={2}
+        max={14}
+      />
+    </BottomSheetModalProvider>
+  );
+};
+```
+
+### Multiple selection
+
+<Canvas of={Stories.Multi} />
+
+```tsx
+import { useRef, useState } from 'react';
+import {
+  BottomSheetModalProvider,
+  Button,
+  DatePicker,
+} from '@utilitywarehouse/hearth-react-native';
+
+const Example = () => {
+  const pickerRef = useRef(null);
+  const [dates, setDates] = useState<DateType[]>([]);
+
+  return (
+    <BottomSheetModalProvider>
+      <Button onPress={() => pickerRef.current?.present()}>Choose booking dates</Button>
+
+      <DatePicker
+        ref={pickerRef}
+        mode="multiple"
+        dates={dates}
+        onChange={({ dates, datePressed, change }) => setDates(dates)}
+        onCancel={() => setDates([])}
+        minDate={new Date()}
+        min={2}
+        max={14}
+      />
+    </BottomSheetModalProvider>
+  );
+};
+```
+
+## Integration notes
+
+- Wrap your application (or the portion that renders the picker) with `BottomSheetModalProvider` so the sheet can mount correctly, especially when combining with other bottom-sheet components.
+- Because the picker respects locale and time zone information, ensure you pass consistent values throughout your app when working with server-sourced dates.
+- When pairing the picker with inputs like `FormField`, surface the chosen dates in the trigger control so people can review their selection after the sheet closes.
+
+## Accessibility
+
+The `DatePicker` is designed to be fully accessible for VoiceOver (iOS) and TalkBack (Android) users:
+
+### Screen reader support
+
+- **Automatic focus**: When the picker opens, screen readers automatically announce "Date picker opened" and focus on the calendar content.
+- **Platform-optimized navigation**:
+  - On iOS, VoiceOver can freely navigate through all calendar elements.
+  - On Android, TalkBack announces "Date picker calendar" when opened, then allows navigation through child elements.
+- **Descriptive labels**: Each interactive element has clear accessibility labels:
+  - Day buttons announce the full date: "Monday, October 8" (with "selected" appended for chosen dates).
+  - Month/year buttons announce the current month and year.
+  - Navigation buttons specify direction: "Next month", "Prev month", etc.
+  - View switcher announces: "Change to day view" or "Change to month view".
+
+### Keyboard navigation
+
+- All interactive controls (days, months, years, navigation) expose `accessibilityRole="button"` for proper identification.
+- Buttons respond to standard tap/activate gestures with screen readers.
+- The footer cancel button is fully accessible and announced properly.
+
+### Best practices
+
+- The picker works seamlessly within forms when triggered by accessible inputs like `DatePickerInput`.
+- Disabled dates are marked as disabled in the accessibility tree, preventing selection attempts.
+- The bottom sheet modal itself is marked as not accessible (`accessible={false}`) to prevent it from blocking navigation to child elements.
+- All date announcements respect the English locale for consistency with the current implementation.