@utilitywarehouse/hearth-react-native 0.23.0 → 0.25.0

package/src/components/TimePicker/TimePickerWheel.web.tsx

@@ -0,0 +1,217 @@
+import { memo, useCallback, useMemo } from 'react';
+import { Platform, View } from 'react-native';
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+import Animated, {
+  Extrapolate,
+  interpolate,
+  runOnJS,
+  type SharedValue,
+  useAnimatedStyle,
+  useSharedValue,
+} from 'react-native-reanimated';
+import { StyleSheet } from 'react-native-unistyles';
+import { isEqual } from '../../utils';
+import { BodyText } from '../BodyText';
+import type { PickerOption } from './TimePicker.props';
+
+type TimePickerWheelProps = {
+  value: number | string;
+  setValue?: (value: any) => void;
+  items: PickerOption[];
+};
+
+const ITEM_HEIGHT = 44;
+
+type WheelWebItemProps = {
+  displayValue: PickerOption | undefined;
+  index: number;
+  currentIndex: number;
+  translateY: SharedValue<number>;
+  radius: number;
+  displayCount: number;
+  value: number | string;
+};
+
+const WheelWebItem = ({
+  displayValue,
+  index,
+  currentIndex,
+  translateY,
+  radius,
+  displayCount,
+  value,
+}: WheelWebItemProps) => {
+  const baseOpacity = displayValue?.value !== value ? 0.3 : 1;
+
+  const animatedStyle = useAnimatedStyle(() => {
+    const offset = (radius * 2) / displayCount;
+    const shifted = interpolate(
+      translateY.value,
+      [-radius, radius],
+      [-radius + offset * (index - currentIndex), radius + offset * (index - currentIndex)],
+      Extrapolate.EXTEND
+    );
+    const angle = interpolate(
+      shifted,
+      [-radius, radius],
+      [-Math.PI / 2, Math.PI / 2],
+      Extrapolate.CLAMP
+    );
+    const translate = radius * Math.sin(angle);
+    const rotateX = (angle * 180) / Math.PI;
+
+    return {
+      position: 'absolute',
+      height: ITEM_HEIGHT - 10,
+      opacity: baseOpacity,
+      alignItems: 'center',
+      justifyContent: 'center',
+      transform: [{ translateY: translate }, { rotateX: `${rotateX}deg` }],
+    };
+  }, [baseOpacity, currentIndex, displayCount, index, radius, translateY]);
+
+  return (
+    <Animated.View style={animatedStyle}>
+      <BodyText size="lg">{displayValue?.text}</BodyText>
+    </Animated.View>
+  );
+};
+
+const TimePickerWheel = ({ value, setValue = () => {}, items }: TimePickerWheelProps) => {
+  const displayCount = 5;
+  const translateY = useSharedValue(0);
+  const renderCount = displayCount * 2 < items.length ? displayCount * 8 : displayCount * 2 - 1;
+  const circular = items.length >= displayCount;
+  const height = 140;
+  const radius = height / 2;
+
+  const valueIndex = useMemo(() => {
+    return Math.max(
+      0,
+      items.findIndex(item => item.value === value)
+    );
+  }, [items, value]);
+
+  const handlePanEnd = useCallback(
+    (deltaY: number) => {
+      let newValueIndex = valueIndex - Math.round(deltaY / ((radius * 2) / displayCount));
+      if (circular) {
+        newValueIndex = (newValueIndex + items.length) % items.length;
+      } else {
+        if (newValueIndex < 0) {
+          newValueIndex = 0;
+        } else if (newValueIndex >= items.length) {
+          newValueIndex = items.length - 1;
+        }
+      }
+      const newValue = items[newValueIndex];
+      if (newValue?.value === value) {
+        return;
+      }
+      if (newValue?.value) {
+        setValue(newValue.value);
+      } else if (items[0]?.value) {
+        setValue(items[0].value);
+      }
+    },
+    [circular, displayCount, items, radius, setValue, value, valueIndex]
+  );
+
+  const panGesture = useMemo(
+    () =>
+      Gesture.Pan()
+        .onUpdate(event => {
+          translateY.value = event.translationY;
+        })
+        .onEnd(event => {
+          runOnJS(handlePanEnd)(event.translationY);
+          translateY.value = 0;
+        }),
+    [handlePanEnd, translateY]
+  );
+
+  const displayValues = useMemo(() => {
+    const centerIndex = Math.floor(renderCount / 2);
+
+    return Array.from({ length: renderCount }, (_, index) => {
+      let targetIndex = valueIndex + index - centerIndex;
+      if (circular) {
+        targetIndex = ((targetIndex % items.length) + items.length) % items.length;
+      } else {
+        targetIndex = Math.max(0, Math.min(targetIndex, items.length - 1));
+      }
+      return items[targetIndex] || items[0];
+    });
+  }, [renderCount, valueIndex, items, circular]);
+
+  const currentIndex = Math.max(
+    0,
+    displayValues.findIndex(item => item?.value === value)
+  );
+
+  return (
+    <GestureDetector gesture={panGesture}>
+      <View style={styles.container}>
+        <View
+          style={[
+            styles.selectedIndicator,
+            {
+              transform: [{ translateY: -ITEM_HEIGHT / 2 }],
+              height: ITEM_HEIGHT,
+            },
+          ]}
+        />
+        {displayValues?.map((displayValue, index) => (
+          <WheelWebItem
+            key={`${displayValue?.text}-${index}`}
+            displayValue={displayValue}
+            index={index}
+            currentIndex={currentIndex}
+            translateY={translateY}
+            radius={radius}
+            displayCount={displayCount}
+            value={value}
+          />
+        ))}
+      </View>
+    </GestureDetector>
+  );
+};
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    minWidth: 30,
+    overflow: 'hidden',
+    alignItems: 'center',
+    justifyContent: 'center',
+    height: 208,
+    ...Platform.select({
+      web: {
+        cursor: 'pointer',
+        userSelect: 'none',
+      },
+    }),
+  },
+  selectedIndicator: {
+    position: 'absolute',
+    width: theme.components.timePicker.time.item.width,
+    height: theme.components.timePicker.time.item.height,
+    top: '50%',
+    backgroundColor: theme.color.interactive.neutral.surface.subtle.active,
+    borderRadius: theme.borderRadius.md,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+}));
+
+const customComparator = (
+  prev: Readonly<TimePickerWheelProps>,
+  next: Readonly<TimePickerWheelProps>
+) => {
+  const areEqual =
+    prev.value === next.value && prev.setValue === next.setValue && isEqual(prev.items, next.items);
+
+  return areEqual;
+};
+
+export default memo(TimePickerWheel, customComparator);

package/src/components/TimePicker/index.ts

@@ -0,0 +1,8 @@
+import 'dayjs/locale/en';
+import '../DatePicker/polyfill';
+
+export type { BottomSheetMethods as TimePickerMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
+export type { DateType } from '../DatePicker/DatePicker.props';
+
+export { default as TimePicker } from './TimePicker';
+export type { TimePickerProps } from './TimePicker.props';

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>
+    );
+  },
+};