@utilitywarehouse/hearth-react-native 0.3.1 → 0.4.0

package/src/components/DatePickerInput/DatePickerInput.docs.mdx

@@ -0,0 +1,237 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { BottomSheetModalProvider, Center, DatePickerInput, FormField } from '../../';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './DatePickerInput.stories';
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=3725-357" />
+
+<Meta title="Forms / Date Picker Input" />
+
+<BackToTopButton />
+
+# Date Picker Input
+
+`DatePickerInput` extends the base input to present a calendar trigger for choosing dates while still allowing direct text entry. It keeps the field inline while delegating selection to the `DatePicker` bottom sheet and formats values with Day.js when needed. The default `DD/MM/YYYY` mask auto-inserts separators and surfaces a numeric keypad for faster entry.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Formatting and validation](#formatting-and-validation)
+- [Examples](#examples)
+- [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
+
+Wrap the component with `BottomSheetModalProvider` so the underlying picker can render its modal. Provide a controlled `value` if you want to react to changes immediately or let the component manage its own display string.
+
+<UsageWrap>
+  <BottomSheetModalProvider>
+    <Center>
+      <DatePickerInput placeholder="DD/MM/YYYY" />
+    </Center>
+  </BottomSheetModalProvider>
+</UsageWrap>
+
+```tsx
+import { useState } from 'react';
+import {
+  BottomSheetModalProvider,
+  DatePickerInput,
+  type DateType,
+} from '@utilitywarehouse/hearth-react-native';
+
+type Props = {};
+
+const BookingDateField = ({}: Props) => {
+  const [date, setDate] = useState<DateType>();
+
+  return (
+    <BottomSheetModalProvider>
+      <DatePickerInput
+        value={date}
+        onChange={({ date }) => setDate(date ?? undefined)}
+        onClear={() => setDate(undefined)}
+        placeholder="DD/MM/YYYY"
+      />
+    </BottomSheetModalProvider>
+  );
+};
+```
+
+When used inside `FormField`, validation, disabled, and required states are inherited from the context.
+
+## Props
+
+`DatePickerInput` inherits all React Native `TextInput` props (except `children`) and adds the following:
+
+| Prop                | Type                                                                   | Default              | Description                                                                                                                                                                 |
+| ------------------- | ---------------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `validationStatus`  | `'initial' \| 'valid' \| 'invalid'`                                    | `'initial'`          | Renders the corresponding validation style. Inherited from `FormField` when nested.                                                                                         |
+| `disabled`          | `boolean`                                                              | `false`              | Disables both typing and the calendar trigger button.                                                                                                                       |
+| `readonly`          | `boolean`                                                              | `false`              | Prevents manual typing while keeping the picker available.                                                                                                                  |
+| `focused`           | `boolean`                                                              | `false`              | Forces the focused state styling.                                                                                                                                           |
+| `inBottomSheet`     | `boolean`                                                              | `false`              | Uses `BottomSheetTextInput` when rendering inside a bottom sheet.                                                                                                           |
+| `format`            | `string`                                                               | `'DD/MM/YYYY'`       | Day.js format string used to render selected dates and parse manual input. Leaving it as `'DD/MM/YYYY'` automatically inserts `/` separators and requests a numeric keypad. |
+| `openButtonLabel`   | `string`                                                               | `'Open date picker'` | Accessible label read by screen readers for the calendar trigger button.                                                                                                    |
+| `autoCloseOnSelect` | `boolean`                                                              | `true`               | Closes the picker automatically after a date is chosen.                                                                                                                     |
+| `datePickerProps`   | `Omit<DatePickerSingleProps, 'mode' \| 'date' \| 'onChange' \| 'ref'>` | `-`                  | Forwards props to the underlying `DatePicker` (e.g. `minDate`, `maxDate`, `timeZone`).                                                                                      |
+| `onChange`          | `(payload: { date: DateType }) => void`                                | `-`                  | Fired whenever a valid date is parsed from typing or picked via the calendar.                                                                                               |
+| `onClear`           | `() => void`                                                           | `-`                  | Called after the clear action resets the input. Also displays a trailing clear button when provided.                                                                        |
+
+## Formatting and validation
+
+### Automatic formatting
+
+When `format` is left as `'DD/MM/YYYY'`, the input automatically inserts `/` separators as people type and requests a numeric keypad on supported platforms. This keeps manual entry quick while matching the preferred UK date layout.
+
+On iOS, a contextual **Done** button appears above the keyboard so people can dismiss it as soon as they're finished typing.
+
+### Handling validation yourself
+
+`DatePickerInput` doesn't display validation styles by itself. Pair it with `FormField` (or your own state) to surface errors whenever the typed value doesn't match your expected format.
+
+```tsx
+import { useState } from 'react';
+import dayjs from 'dayjs';
+import { DatePickerInput, FormField, type DateType } from '@utilitywarehouse/hearth-react-native';
+
+const TravelDateField = () => {
+  const [value, setValue] = useState<DateType>();
+  const [rawInput, setRawInput] = useState('');
+  const [status, setStatus] = useState<'initial' | 'invalid'>('initial');
+
+  const handleBlur = () => {
+    if (!rawInput) {
+      setStatus('initial');
+      return;
+    }
+
+    const isValid = dayjs(rawInput, 'DD/MM/YYYY', true).isValid();
+    setStatus(isValid ? 'initial' : 'invalid');
+  };
+
+  return (
+    <FormField
+      label="Travel date"
+      helperText="Use DD/MM/YYYY"
+      validationStatus={status}
+      invalidText="Enter a valid date"
+    >
+      <DatePickerInput
+        value={value}
+        onChange={({ date }) => {
+          setValue(date ?? undefined);
+          if (date) {
+            setStatus('initial');
+          }
+        }}
+        onChangeText={setRawInput}
+        onBlur={handleBlur}
+        onClear={() => {
+          setValue(undefined);
+          setRawInput('');
+          setStatus('initial');
+        }}
+      />
+    </FormField>
+  );
+};
+```
+
+Swap `'DD/MM/YYYY'` in the example for the `format` you're using, and reuse the same rule inside `dayjs(..., format, true)` to keep the behaviour aligned.
+
+Selection through the calendar always returns a JavaScript `Date` that is reformatted according to `format` when displayed in the field.
+
+## Examples
+
+### With `FormField`
+
+<UsageWrap>
+  <BottomSheetModalProvider>
+    <Center>
+      <FormField label="Travel date" helperText="Choose a departure day">
+        <DatePickerInput onClear={() => {}} />
+      </FormField>
+    </Center>
+  </BottomSheetModalProvider>
+</UsageWrap>
+
+```tsx
+<FormField label="Travel date" helperText="Choose a departure day">
+  <DatePickerInput onClear={() => {}} />
+</FormField>
+```
+
+### Custom formatting
+
+<UsageWrap>
+  <BottomSheetModalProvider>
+    <Center>
+      <DatePickerInput format="MMM D, YYYY" placeholder="MMM D, YYYY" />
+    </Center>
+  </BottomSheetModalProvider>
+</UsageWrap>
+
+```tsx
+<DatePickerInput format="MMM D, YYYY" placeholder="MMM D, YYYY" />
+```
+
+## Accessibility
+
+`DatePickerInput` is designed to work seamlessly with VoiceOver (iOS), TalkBack (Android), and other assistive technologies:
+
+### Screen reader support
+
+- **Text input field**:
+
+  - Announces as "Date input" by default (customizable via `accessibilityLabel`).
+  - Provides helpful context: "Enter the date in DD/MM/YYYY format" (or your custom format) via `accessibilityHint`.
+  - Announces disabled and readonly states appropriately.
+  - When focused, screen readers identify it as an editable text field.
+
+- **Calendar trigger button**:
+
+  - Announces as "Open date picker" by default (customizable via `openButtonLabel`).
+  - Includes helpful hint: "Opens the date picker calendar".
+  - Clearly identified as a button with `accessibilityRole="button"`.
+  - Respects disabled/readonly state from the input or surrounding `FormField`.
+
+- **Clear button** (when `onClear` is provided):
+  - Announces as "Clear date".
+  - Includes hint: "Removes the current date".
+  - Only appears when there's a value to clear and the input isn't readonly/disabled.
+
+### Keyboard and input management
+
+- Both the text input and action buttons are individually focusable and navigable.
+- The `DD/MM/YYYY` format triggers a numeric keypad on iOS/Android for faster entry.
+- On iOS, a contextual **Done** button appears above the keyboard to dismiss it when finished typing.
+- Custom formats can be specified to match your application's needs while maintaining accessibility.
+
+### Integration with DatePicker
+
+- When the calendar opens, screen readers announce "Date picker opened" and automatically focus on the calendar content.
+- All calendar navigation (days, months, years) is fully accessible with descriptive labels.
+- Selected dates are announced with full context: "Monday, October 8, selected".
+- The underlying `DatePicker` follows platform-specific accessibility patterns for optimal screen reader experience.
+
+### Validation and state
+
+- Validation state is inherited from surrounding `FormField` or controlled via `validationStatus` prop.
+- Invalid states are properly communicated through the `FormField`'s error messaging system.
+- The `importantForAccessibility` prop is set to `'yes'` by default to ensure the input is prioritized by screen readers.
+
+### Best practices
+
+- Always pair with `FormField` for proper label, helper text, and error message announcements.
+- Use `openButtonLabel` to customize the calendar button announcement if the default doesn't fit your use case.
+- Provide clear validation feedback through `FormField` when manual date entry doesn't match the expected format.
+- Test with VoiceOver and TalkBack to ensure the date entry flow works smoothly in your specific context.

package/src/components/DatePickerInput/DatePickerInput.props.ts

@@ -0,0 +1,50 @@
+import type { TextInputProps, ViewProps } from 'react-native';
+import type { DatePickerSingleProps } from '../DatePicker/DatePicker';
+import type { DateType } from '../DatePicker/DatePicker.props';
+
+export interface DatePickerInputBaseProps {
+  disabled?: boolean;
+  validationStatus?: 'initial' | 'valid' | 'invalid';
+  readonly?: boolean;
+  focused?: boolean;
+  placeholder?: string;
+  inBottomSheet?: boolean;
+  required?: boolean;
+  /**
+   * Controls how the selected date is formatted when displayed inside the input.
+   * Accepts any Day.js format string. When left as the default `DD/MM/YYYY`,
+   * the input automatically inserts separators as people type.
+   */
+  format?: string;
+  /**
+   * Accessible label announced when activating the calendar trigger button.
+   */
+  openButtonLabel?: string;
+  /**
+   * When true (default), the calendar sheet is dismissed as soon as a date is picked.
+   */
+  autoCloseOnSelect?: boolean;
+  /**
+   * Additional props forwarded to the underlying DatePicker instance.
+   */
+  datePickerProps?: Omit<DatePickerSingleProps, 'mode' | 'date' | 'onChange' | 'ref'>;
+  /**
+   * Handles cleared input values.
+   */
+  onClear?: () => void;
+}
+
+export type DatePickerInputProps = DatePickerInputBaseProps &
+  Omit<TextInputProps, 'value' | 'onChange' | 'children'> &
+  ViewProps & {
+    /**
+     * Controlled date value. Accepts Date, string, number or Day.js instances.
+     */
+    value?: DateType;
+    /**
+     * Fired after a valid date is parsed either from typing or the picker selection.
+     */
+    onChange?: (params: { date: DateType }) => void;
+  };
+
+export default DatePickerInputProps;

package/src/components/DatePickerInput/DatePickerInput.stories.tsx

@@ -0,0 +1,178 @@
+import { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { Platform } from 'react-native';
+import { DatePickerInput, View } from '..';
+import { VariantTitle, ViewWrap } from '../../../docs/components';
+import type { DateType } from '../DatePicker';
+import { Flex } from '../Flex';
+import { FormField } from '../FormField';
+
+const meta = {
+  title: 'Stories / DatePickerInput',
+  component: DatePickerInput,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    format: {
+      control: 'text',
+      description: 'Day.js format string used to render and parse the value',
+      defaultValue: 'DD/MM/YYYY',
+    },
+    validationStatus: {
+      control: 'select',
+      options: ['initial', 'valid', 'invalid'],
+      description: 'Manually set the validation status',
+      defaultValue: 'initial',
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Disable the input and trigger button',
+      defaultValue: false,
+    },
+    readonly: {
+      control: 'boolean',
+      description: 'Make the input read-only (typing disabled, picker still accessible)',
+      defaultValue: false,
+    },
+    focused: {
+      control: 'boolean',
+      description: 'Force the focused visual state',
+      defaultValue: false,
+    },
+    openButtonLabel: {
+      control: 'text',
+      description: 'Accessible label for the calendar trigger button',
+      defaultValue: 'Open date picker',
+    },
+    autoCloseOnSelect: {
+      control: 'boolean',
+      description: 'Automatically close the picker after selecting a date',
+      defaultValue: false,
+    },
+  },
+  args: {
+    format: 'DD/MM/YYYY',
+    validationStatus: 'initial',
+    disabled: false,
+    readonly: false,
+    focused: false,
+    openButtonLabel: 'Open date picker',
+    autoCloseOnSelect: false,
+    placeholder: 'DD/MM/YYYY',
+  },
+} satisfies Meta<typeof DatePickerInput>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  render: args => {
+    const [selected, setSelected] = useState<DateType>();
+
+    const picker = (
+      <DatePickerInput
+        {...args}
+        value={selected}
+        onChange={({ date }) => setSelected(date ?? undefined)}
+        onClear={() => setSelected(undefined)}
+      />
+    );
+
+    if (Platform.OS !== 'web') {
+      return picker;
+    }
+
+    return (
+      <View style={Platform.OS === 'web' ? { width: 400, height: 400 } : {}}>
+        <ViewWrap>{picker}</ViewWrap>
+      </View>
+    );
+  },
+};
+
+export const CustomFormat: Story = {
+  parameters: {
+    controls: { include: ['format'] },
+  },
+  args: {
+    format: 'YYYY-MM-DD',
+    placeholder: 'YYYY-MM-DD',
+  },
+  render: args => {
+    const [selected, setSelected] = useState<DateType>(new Date());
+
+    const picker = (
+      <DatePickerInput
+        {...args}
+        value={selected}
+        onChange={({ date }) => setSelected(date ?? undefined)}
+        onClear={() => setSelected(undefined)}
+      />
+    );
+
+    if (Platform.OS !== 'web') {
+      return picker;
+    }
+
+    return <ViewWrap>{picker}</ViewWrap>;
+  },
+};
+
+export const States: Story = {
+  parameters: {
+    controls: { include: [] },
+  },
+  render: () => {
+    const [withValue, setWithValue] = useState<DateType>(new Date());
+    const [clearableDate, setClearableDate] = useState<DateType>(new Date());
+    const [formFieldDate, setFormFieldDate] = useState<DateType>();
+
+    return (
+      <Flex direction="column" space="lg">
+        <VariantTitle title="Default">
+          <DatePickerInput placeholder="DD/MM/YYYY" />
+        </VariantTitle>
+        <VariantTitle title="With value">
+          <DatePickerInput
+            value={withValue}
+            onChange={({ date }) => setWithValue(date ?? undefined)}
+            onClear={() => setWithValue(undefined)}
+          />
+        </VariantTitle>
+        <VariantTitle title="Disabled">
+          <DatePickerInput disabled placeholder="DD/MM/YYYY" />
+        </VariantTitle>
+        <VariantTitle title="Readonly">
+          <DatePickerInput readonly value={withValue} />
+        </VariantTitle>
+        <VariantTitle title="Invalid">
+          <DatePickerInput validationStatus="invalid" placeholder="DD/MM/YYYY" />
+        </VariantTitle>
+        <VariantTitle title="Valid">
+          <DatePickerInput validationStatus="valid" placeholder="DD/MM/YYYY" />
+        </VariantTitle>
+        <VariantTitle title="Custom format">
+          <DatePickerInput format="MMM D, YYYY" placeholder="MMM D, YYYY" />
+        </VariantTitle>
+        <VariantTitle title="With clear action">
+          <DatePickerInput
+            value={clearableDate}
+            onChange={({ date }) => setClearableDate(date ?? undefined)}
+            onClear={() => setClearableDate(undefined)}
+          />
+        </VariantTitle>
+        <VariantTitle title="Inside FormField">
+          <FormField label="Booking date" helperText="Pick a date">
+            <DatePickerInput
+              value={formFieldDate}
+              onChange={({ date }) => setFormFieldDate(date ?? undefined)}
+              onClear={() => setFormFieldDate(undefined)}
+            />
+          </FormField>
+        </VariantTitle>
+      </Flex>
+    );
+  },
+};