@utilitywarehouse/hearth-react-native 0.24.0 → 0.26.0

package/src/components/TimePickerInput/TimePickerInput.docs.mdx

@@ -0,0 +1,135 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { BottomSheetModalProvider, Center, FormField, TimePickerInput } from '../../';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './TimePickerInput.stories';
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=10334-6212&t=Jg2fPJPQNzOyspmQ-4" />
+
+<Meta title="Forms / Time Picker Input" />
+
+<BackToTopButton />
+
+# Time Picker Input
+
+`TimePickerInput` extends the base input to present a time picker trigger while still allowing direct text entry. It keeps the field inline and formats values with Day.js when needed.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Formatting](#formatting)
+- [Examples](#examples)
+
+## 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>
+      <TimePickerInput placeholder="HH:mm" />
+    </Center>
+  </BottomSheetModalProvider>
+</UsageWrap>
+
+```tsx
+import { useState } from 'react';
+import {
+  BottomSheetModalProvider,
+  TimePickerInput,
+  type DateType,
+} from '@utilitywarehouse/hearth-react-native';
+
+const BookingTimeField = () => {
+  const [time, setTime] = useState<DateType>();
+
+  return (
+    <BottomSheetModalProvider>
+      <TimePickerInput
+        value={time}
+        onChange={({ date }) => setTime(date ?? undefined)}
+        onClear={() => setTime(undefined)}
+        placeholder="HH:mm"
+      />
+    </BottomSheetModalProvider>
+  );
+};
+```
+
+## Props
+
+`TimePickerInput` inherits all React of the `Input` component props 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 time picker trigger button.                                                  |
+| `readonly`          | `boolean`                                              | `false`              | Prevents manual typing while keeping the picker available.                                                |
+| `focused`           | `boolean`                                              | `false`              | Forces the focused state styling.                                                                         |
+| `label`             | `string`                                               | `-`                  | The label for the input. When used inside `FormField`, this is inherited from the context.                |
+| `labelVariant`      | `'heading' \| 'body'`                                  | `'body'`             | The variant of the label text.                                                                            |
+| `helperText`        | `string`                                               | `-`                  | Helper text to display below the input. When used inside `FormField`, this is inherited from the context. |
+| `helperIcon`        | `ComponentType`                                        | `-`                  | Icon to display alongside the helper                                                                      |
+| `validText`         | `string`                                               | `-`                  | Text to display when validation status is 'valid'. When used inside `FormField`, this is inherited.       |
+| `invalidText`       | `string`                                               | `-`                  | Text to display when validation status is 'invalid'. When used inside `FormField`, this is inherited.     |
+| `inBottomSheet`     | `boolean`                                              | `false`              | Uses `BottomSheetTextInput` when rendering inside a bottom sheet.                                         |
+| `format`            | `string`                                               | `'HH:mm'`            | Day.js format string used to render selected times and parse manual input.                                |
+| `openButtonLabel`   | `string`                                               | `'Open time picker'` | Accessible label read by screen readers for the time trigger button.                                      |
+| `autoCloseOnSelect` | `boolean`                                              | `true`               | Closes the picker automatically after a time is chosen.                                                   |
+| `timePickerProps`   | `Omit<TimePickerProps, 'date' \| 'onChange' \| 'ref'>` | `-`                  | Forwards props to the underlying `TimePicker` (e.g. `use12Hours`, `timeZone`, `minuteInterval`).          |
+| `onChange`          | `(payload: { date: DateType }) => void`                | `-`                  | Fired whenever a valid time is parsed from typing or picked via the selector.                             |
+| `onClear`           | `() => void`                                           | `-`                  | Called after the clear action resets the input. Also displays a trailing clear button when provided.      |
+
+## Formatting
+
+When `format` is left as `'HH:mm'`, the input automatically inserts `:` as people type and requests a numeric keypad on supported platforms.
+
+## Examples
+
+### With label and helper text
+
+<UsageWrap>
+  <BottomSheetModalProvider>
+    <Center>
+      <TimePickerInput
+        onClear={() => {}}
+        label="Meeting time"
+        helperText="Pick a time for your meeting"
+        validText="Time looks good!"
+        invalidText="Please enter a valid time"
+      />
+    </Center>
+  </BottomSheetModalProvider>
+</UsageWrap>
+
+```tsx
+<TimePickerInput
+  onClear={() => {}}
+  label="Meeting time"
+  helperText="Pick a time for your meeting"
+  validText="Time looks good!"
+  invalidText="Please enter a valid time"
+/>
+```
+
+### With `FormField`
+
+<UsageWrap>
+  <BottomSheetModalProvider>
+    <Center>
+      <FormField label="Meeting time" helperText="Pick a time">
+        <TimePickerInput onClear={() => {}} />
+      </FormField>
+    </Center>
+  </BottomSheetModalProvider>
+</UsageWrap>
+
+```tsx
+<FormField label="Meeting time" helperText="Pick a time">
+  <TimePickerInput onClear={() => {}} />
+</FormField>
+```

package/src/components/TimePickerInput/TimePickerInput.figma.tsx

@@ -0,0 +1,34 @@
+import figma from '@figma/code-connect';
+import { TimePickerInput } from '../';
+
+figma.connect(
+  TimePickerInput,
+  'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=10334-6212&t=Jg2fPJPQNzOyspmQ-4',
+  {
+    props: {
+      disabled: figma.enum('Variant', {
+        Disabled: true,
+      }),
+      validationStatus: figma.enum('Variant', {
+        Default: undefined,
+        Valid: 'valid',
+        Invalid: 'invalid',
+      }),
+      readonly: figma.enum('Variant', { 'Read-only': true }),
+      label: figma.string('Label'),
+      validText: figma.enum('Variant', {
+        Valid: figma.string('Validation'),
+      }),
+      invalidText: figma.enum('Variant', {
+        Invalid: figma.string('Validation'),
+      }),
+      placeholder: figma.enum('Value type', {
+        Placeholder: figma.string('Value'),
+      }),
+      value: figma.enum('Value type', {
+        Filled: figma.string('Value'),
+      }),
+    },
+    example: props => <TimePickerInput {...props} />,
+  }
+);

package/src/components/TimePickerInput/TimePickerInput.props.ts

@@ -0,0 +1,55 @@
+import type { TextInputProps, ViewProps } from 'react-native';
+import type { DateType } from '../DatePicker/DatePicker.props';
+import type { TimePickerProps } from '../TimePicker/TimePicker.props';
+
+export interface TimePickerInputBaseProps {
+  disabled?: boolean;
+  validationStatus?: 'initial' | 'valid' | 'invalid';
+  readonly?: boolean;
+  focused?: boolean;
+  label?: string;
+  labelVariant?: 'heading' | 'body';
+  helperText?: string;
+  helperIcon?: React.ComponentType;
+  validText?: string;
+  invalidText?: string;
+  placeholder?: string;
+  inBottomSheet?: boolean;
+  required?: boolean;
+  /**
+   * Controls how the selected time is formatted when displayed inside the input.
+   * Accepts any Day.js format string.
+   */
+  format?: string;
+  /**
+   * Accessible label announced when activating the time picker trigger button.
+   */
+  openButtonLabel?: string;
+  /**
+   * When true (default), the picker sheet is dismissed as soon as a time is picked.
+   */
+  autoCloseOnSelect?: boolean;
+  /**
+   * Additional props forwarded to the underlying TimePicker instance.
+   */
+  timePickerProps?: Omit<TimePickerProps, 'date' | 'onChange' | 'ref'>;
+  /**
+   * Handles cleared input values.
+   */
+  onClear?: () => void;
+}
+
+export type TimePickerInputProps = TimePickerInputBaseProps &
+  Omit<TextInputProps, 'value' | 'onChange' | 'children'> &
+  ViewProps & {
+    /**
+     * Controlled time value. Accepts Date, string, number or Day.js instances.
+     */
+    value?: DateType;
+    /**
+     * Fired after a valid time is parsed either from typing or the picker selection.
+     */
+    onChange?: (params: { date: DateType }) => void;
+  };
+
+export default TimePickerInputProps;

package/src/components/TimePickerInput/TimePickerInput.stories.tsx

@@ -0,0 +1,175 @@
+import { Meta, StoryObj } from '@storybook/react-native';
+import { useState } from 'react';
+import { Platform } from 'react-native';
+import { TimePickerInput, 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 / TimePickerInput',
+  component: TimePickerInput,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    format: {
+      control: 'text',
+      description: 'Day.js format string used to render and parse the value',
+      defaultValue: 'HH:mm',
+    },
+    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 time trigger button',
+      defaultValue: 'Open time picker',
+    },
+    autoCloseOnSelect: {
+      control: 'boolean',
+      description: 'Automatically close the picker after selecting a time',
+      defaultValue: false,
+    },
+  },
+  args: {
+    format: 'HH:mm',
+    validationStatus: 'initial',
+    disabled: false,
+    readonly: false,
+    focused: false,
+    openButtonLabel: 'Open time picker',
+    autoCloseOnSelect: false,
+    placeholder: undefined,
+  },
+} satisfies Meta<typeof TimePickerInput>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  render: (args: typeof meta.args) => {
+    const [selected, setSelected] = useState<DateType>();
+
+    const picker = (
+      <TimePickerInput
+        {...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 States: Story = {
+  parameters: {
+    controls: { include: [] },
+  },
+  render: () => {
+    const [withValue, setWithValue] = useState<DateType>(new Date());
+    const [clearableTime, setClearableTime] = useState<DateType>(new Date());
+    const [formFieldTime, setFormFieldTime] = useState<DateType>();
+
+    return (
+      <Flex direction="column" spacing="lg">
+        <VariantTitle title="Default">
+          <TimePickerInput />
+        </VariantTitle>
+        <VariantTitle title="With value">
+          <TimePickerInput
+            value={withValue}
+            onChange={({ date }) => setWithValue(date ?? undefined)}
+            onClear={() => setWithValue(undefined)}
+          />
+        </VariantTitle>
+        <VariantTitle title="Disabled">
+          <TimePickerInput disabled />
+        </VariantTitle>
+        <VariantTitle title="Readonly">
+          <TimePickerInput readonly value={withValue} />
+        </VariantTitle>
+        <VariantTitle title="Invalid">
+          <TimePickerInput validationStatus="invalid" />
+        </VariantTitle>
+        <VariantTitle title="Valid">
+          <TimePickerInput validationStatus="valid" />
+        </VariantTitle>
+        <VariantTitle title="With clear action">
+          <TimePickerInput
+            value={clearableTime}
+            onChange={({ date }) => setClearableTime(date ?? undefined)}
+            onClear={() => setClearableTime(undefined)}
+          />
+        </VariantTitle>
+        <VariantTitle title="Inside FormField">
+          <FormField label="Meeting time" helperText="Pick a time">
+            <TimePickerInput
+              value={formFieldTime}
+              onChange={({ date }) => setFormFieldTime(date ?? undefined)}
+              onClear={() => setFormFieldTime(undefined)}
+            />
+          </FormField>
+        </VariantTitle>
+      </Flex>
+    );
+  },
+};
+
+export const MinuteIntervals: Story = {
+  parameters: {
+    controls: { include: [] },
+  },
+  render: () => {
+    const [intervalTime, setIntervalTime] = useState<DateType>();
+
+    const picker = (
+      <TimePickerInput
+        value={intervalTime}
+        onChange={({ date }) => setIntervalTime(date ?? undefined)}
+        onClear={() => setIntervalTime(undefined)}
+        timePickerProps={{ minuteInterval: 5 }}
+      />
+    );
+
+    if (Platform.OS !== 'web') {
+      return picker;
+    }
+
+    return (
+      <View style={Platform.OS === 'web' ? { width: 400, height: 400 } : {}}>
+        <ViewWrap>{picker}</ViewWrap>
+      </View>
+    );
+  },
+};

package/src/components/TimePickerInput/TimePickerInput.tsx

@@ -0,0 +1,283 @@
+import type { BottomSheetModalMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
+import { CloseSmallIcon, TimeSmallIcon } from '@utilitywarehouse/hearth-react-native-icons';
+import dayjs from 'dayjs';
+import customParseFormat from 'dayjs/plugin/customParseFormat';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Keyboard, Platform, TextInputFocusEvent } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import type { DateType } from '../DatePicker/DatePicker.props';
+import { useFormFieldContext } from '../FormField';
+import { Input, InputField, InputSlot } from '../Input';
+import { TimePicker } from '../TimePicker';
+import { UnstyledIconButton } from '../UnstyledIconButton';
+import type TimePickerInputProps from './TimePickerInput.props';
+import TimePickerInputDoneButton from './TimePickerInputDoneButton';
+
+dayjs.extend(customParseFormat);
+
+const DEFAULT_FORMAT_24 = 'HH:mm';
+const DEFAULT_FORMAT_12 = 'hh:mm A';
+
+const maskDefaultFormat = (value: string) => {
+  const digitsOnly = value.replace(/\D/g, '').slice(0, 4);
+  const hours = digitsOnly.slice(0, 2);
+  const minutes = digitsOnly.slice(2, 4);
+
+  return [hours, minutes].filter(Boolean).join(':');
+};
+
+const TimePickerInput = ({
+  validationStatus = 'initial',
+  disabled,
+  focused,
+  readonly,
+  placeholder = '--:--',
+  inBottomSheet = false,
+  format,
+  openButtonLabel = 'Open time picker',
+  autoCloseOnSelect = true,
+  label,
+  labelVariant,
+  helperText,
+  helperIcon,
+  validText,
+  invalidText,
+  required = true,
+  onChange,
+  onChangeText,
+  onBlur,
+  onFocus,
+  value,
+  timePickerProps,
+  onClear,
+  ...rest
+}: TimePickerInputProps) => {
+  const formFieldContext = useFormFieldContext();
+  const isDisabled = formFieldContext?.disabled ?? disabled;
+  const isReadonly = formFieldContext?.readonly ?? readonly;
+
+  const pickerRef = useRef<BottomSheetModalMethods | null>(null);
+  const accessoryViewID = useMemo(() => {
+    if (Platform.OS !== 'ios') return undefined;
+    return `timepicker-input-${Math.random().toString(36).slice(2)}`;
+  }, []);
+
+  const use12Hours = timePickerProps?.use12Hours ?? false;
+  const resolvedFormat = useMemo(
+    () => format ?? (use12Hours ? DEFAULT_FORMAT_12 : DEFAULT_FORMAT_24),
+    [format, use12Hours]
+  );
+
+  const formatTime = useCallback(
+    (dateValue?: DateType) => {
+      if (!dateValue) return '';
+      const parsed = dayjs(dateValue);
+      return parsed.isValid() ? parsed.format(resolvedFormat) : '';
+    },
+    [resolvedFormat]
+  );
+
+  const isDefaultFormat = resolvedFormat === DEFAULT_FORMAT_24;
+
+  const [inputValue, setInputValue] = useState(() => formatTime(value));
+
+  useEffect(() => {
+    setInputValue(formatTime(value));
+  }, [value, formatTime]);
+
+  const handleTextChange = useCallback(
+    (text: string) => {
+      const nextValue = isDefaultFormat ? maskDefaultFormat(text) : text;
+
+      setInputValue(nextValue);
+      onChangeText?.(nextValue);
+
+      if (!nextValue) {
+        onChange?.({ date: undefined });
+        return;
+      }
+
+      const parsed = dayjs(nextValue, resolvedFormat, true);
+
+      if (parsed.isValid()) {
+        onChange?.({ date: parsed.toDate() });
+      } else {
+        onChange?.({ date: undefined });
+      }
+    },
+    [isDefaultFormat, onChange, onChangeText, resolvedFormat]
+  );
+
+  const handleClear = useCallback(() => {
+    setInputValue('');
+    onChange?.({ date: undefined });
+    onClear?.();
+  }, [onChange, onClear]);
+
+  const closeKeyboard = useCallback(() => {
+    Keyboard.dismiss();
+  }, []);
+
+  const openPicker = useCallback(() => {
+    if (isDisabled || isReadonly) return;
+    closeKeyboard();
+    pickerRef.current?.present();
+  }, [closeKeyboard, isDisabled, isReadonly]);
+
+  const selectedDate = useMemo(() => {
+    if (value) {
+      return value;
+    }
+
+    const parsed = dayjs(inputValue, resolvedFormat, true);
+    return parsed.isValid() ? parsed.toDate() : undefined;
+  }, [value, inputValue, resolvedFormat]);
+
+  const handlePickerChange = useCallback(
+    ({ date }: { date: DateType }) => {
+      if (!date) {
+        handleClear();
+        return;
+      }
+
+      const formatted = formatTime(date);
+      setInputValue(formatted);
+      onChange?.({ date });
+
+      if (autoCloseOnSelect) {
+        pickerRef.current?.close?.();
+      }
+    },
+    [autoCloseOnSelect, formatTime, handleClear, onChange]
+  );
+
+  const handleBlur = useCallback(
+    (event: TextInputFocusEvent) => {
+      onBlur?.(event);
+    },
+    [onBlur]
+  );
+
+  const handleFocus = useCallback(
+    (event: TextInputFocusEvent) => {
+      onFocus?.(event);
+    },
+    [onFocus]
+  );
+
+  const { onCancel: pickerOnCancel, ...restTimePickerProps } = timePickerProps ?? {};
+  const {
+    style: inputStyle,
+    keyboardType: keyboardTypeProp,
+    inputMode: inputModeProp,
+    accessibilityHint: accessibilityHintProp,
+    accessibilityLabel: accessibilityLabelProp,
+    accessible: accessibleProp,
+    importantForAccessibility: importantForAccessibilityProp,
+    ...textInputProps
+  } = rest;
+
+  const resolvedKeyboardType = keyboardTypeProp ?? (isDefaultFormat ? 'number-pad' : undefined);
+  const resolvedInputMode = inputModeProp ?? (isDefaultFormat ? 'numeric' : undefined);
+  const resolvedAccessibilityHint =
+    accessibilityHintProp ?? `Enter the time in ${resolvedFormat} format`;
+  const resolvedAccessibilityLabel = accessibilityLabelProp ?? 'Time input';
+  const resolvedAccessible = accessibleProp ?? true;
+  const resolvedImportantForAccessibility = importantForAccessibilityProp ?? 'yes';
+
+  const handleCancel = useCallback(() => {
+    pickerOnCancel?.();
+    pickerRef.current?.close?.();
+  }, [pickerOnCancel]);
+
+  const placeholderValue = placeholder;
+
+  return (
+    <>
+      <Input
+        validationStatus={validationStatus}
+        disabled={disabled}
+        readonly={readonly}
+        focused={focused}
+        label={label}
+        labelVariant={labelVariant}
+        helperText={helperText}
+        helperIcon={helperIcon}
+        validText={validText}
+        invalidText={invalidText}
+        required={required}
+        style={styles.wrap}
+        accessible={false}
+      >
+        <InputField
+          editable={!isReadonly && !isDisabled}
+          value={inputValue}
+          placeholder={placeholderValue}
+          onChangeText={handleTextChange}
+          onBlur={handleBlur}
+          onFocus={handleFocus}
+          inBottomSheet={inBottomSheet}
+          keyboardType={resolvedKeyboardType}
+          inputMode={resolvedInputMode}
+          accessibilityHint={resolvedAccessibilityHint}
+          aria-label="Time input"
+          accessibilityLabel={resolvedAccessibilityLabel}
+          accessible={resolvedAccessible}
+          accessibilityState={{
+            disabled: isDisabled || isReadonly,
+          }}
+          importantForAccessibility={resolvedImportantForAccessibility}
+          inputAccessoryViewID={Platform.OS === 'ios' ? accessoryViewID : undefined}
+          {...textInputProps}
+          style={[styles.input, inputStyle]}
+        />
+        {!!inputValue && onClear && !isReadonly && !isDisabled && (
+          <InputSlot accessibilityElementsHidden={false}>
+            <UnstyledIconButton
+              accessibilityLabel="Clear time"
+              accessibilityHint="Removes the current time"
+              icon={CloseSmallIcon}
+              onPress={handleClear}
+            />
+          </InputSlot>
+        )}
+        <InputSlot accessibilityElementsHidden={false}>
+          <UnstyledIconButton
+            accessibilityLabel={openButtonLabel}
+            accessibilityHint="Opens the time picker"
+            icon={TimeSmallIcon}
+            onPress={openPicker}
+            disabled={isDisabled || isReadonly}
+          />
+        </InputSlot>
+      </Input>
+      <TimePicker
+        ref={pickerRef}
+        date={selectedDate}
+        onChange={handlePickerChange}
+        onCancel={handleCancel}
+        {...restTimePickerProps}
+      />
+      {Platform.OS === 'ios' && accessoryViewID && (
+        <TimePickerInputDoneButton
+          accessoryViewID={accessoryViewID}
+          closeKeyboard={closeKeyboard}
+        />
+      )}
+    </>
+  );
+};
+
+TimePickerInput.displayName = 'TimePickerInput';
+
+const styles = StyleSheet.create(theme => ({
+  wrap: {
+    gap: theme.components.input.date.gap,
+  },
+  input: {
+    paddingLeft: 0,
+    paddingRight: 0,
+  },
+}));
+
+export default TimePickerInput;