@utilitywarehouse/hearth-react-native 0.24.0 → 0.26.0

package/src/components/Modal/Modal.docs.mdx

@@ -107,9 +107,10 @@ The Modal component extends the `BottomSheetModal` component and accepts all of
 | `primaryButtonProps`          | `Omit<ButtonWithoutChildrenProps, 'children'>`                     | Additional props to pass to the primary button (colorScheme defaults to 'highlight', variant to 'solid')      | -              |
 | `secondaryButtonProps`        | `Omit<ButtonWithoutChildrenProps, 'children'>`                     | Additional props to pass to the secondary button (colorScheme defaults to 'functional', variant to 'outline') | -              |
 | `closeButtonProps`            | `Omit<UnstyledIconButtonProps, 'children'>`                        | Additional props to pass to the close button                                                                  | -              |
-| `fullscreen`                  | `boolean`                                                          | Whether the modal should take up the full screen height                                                       | `false`        |
+| `fullscreen`                  | `boolean`                                                          | Whether the modal should take up the full screen height. Only applies when `inNavModal` is `false`            | `false`        |
 | `inNavModal`                  | `boolean`                                                          | Renders the modal correctly when used inside a navigation modal                                               | `false`        |
 | `background`                  | `'default' \| 'brand'`                                             | Sets the modal background. Only applies when `inNavModal` is `true`                                           | `'default'`    |
+| `scrollable`                  | `boolean`                                                          | Whether the modal's content should be placed in a `ScrollView`. Only applies when `inNavModal` is `true`      | `true`         |
 
 \* use this to detect if the modal has been opened or closed, index 0 indicates open state and -1 indicates closed state
 
@@ -462,11 +463,16 @@ const AlertModal = () => {
 
 ### Modal In Navigation Modal
 
-When using the Modal component in a navigation context, you can set it to `inNavModal` mode, this will make it behave like a standard modal screen.
+When wanting to use the Modal component in a navigation context using [React Navigation](https://reactnavigation.org/docs/modal), you can set `inNavModal` to `true` to make it behave like a standard modal screen.
+
+Within React Navigation, you can set `presentation: 'modal'` in the screen's settings to have the Modal look and behave like a standard modal/bottom sheet, or you can set `presentation: 'fullScreenModal'` to have the Modal fill the entire screen.
+
+When using `inNavModal`, by default the content will be rendered inside a `ScrollView` to ensure it is scrollable, especially on smaller devices or smaller modals. You can disable this by setting `scrollable={false}` if, for example, you need to center your content or add some custom content.
+
 Here's an example of how to implement this with custom close animations for Android:
 
 ```tsx
-import { useNavigation } from 'react-navigation/native';
+import { useNavigation } from '@react-navigation/native';
 import { useCallback, useEffect, useRef } from 'react';
 import { Platform, StyleSheet, View } from 'react-native';
 

package/src/components/Modal/Modal.props.ts

@@ -12,6 +12,7 @@ interface ModalPropsBase extends Omit<BottomSheetProps, 'children'> {
   loadingHeading?: string;
   description?: string;
   fullscreen?: boolean;
+  stickyFooter?: boolean;
   children?: ViewProps['children'];
   onPressPrimaryButton?: () => void;
   primaryButtonText?: string;
@@ -28,12 +29,13 @@ interface ModalPropsBase extends Omit<BottomSheetProps, 'children'> {
 type ModalProps =
   | (ModalPropsBase & {
       inNavModal?: false | undefined;
-      stickyFooter?: boolean;
+      scrollable?: never;
       background?: never;
     })
   | (ModalPropsBase & {
       inNavModal: true;
-      stickyFooter?: never;
+      fullscreen?: never;
+      scrollable?: boolean;
       background?: 'default' | 'brand';
     });
 

package/src/components/Modal/Modal.tsx

@@ -6,8 +6,8 @@ import {
 } from '@gorhom/bottom-sheet';
 import { BottomSheetModalMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
 import { CloseMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
-import { useCallback, useEffect, useImperativeHandle, useRef } from 'react';
-import { AccessibilityInfo, Platform, ScrollView, View, findNodeHandle } from 'react-native';
+import { useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
+import { AccessibilityInfo, Dimensions, Platform, ScrollView, View, findNodeHandle } from 'react-native';
 import Animated, {
   Easing,
   useAnimatedStyle,
@@ -51,6 +51,7 @@ const Modal = ({
   inNavModal = false,
   stickyFooter = true,
   background = 'default',
+  scrollable = true,
   ...props
 }: ModalProps) => {
   const bottomSheetModalRef = useRef<BottomSheetModal>(null);
@@ -61,6 +62,16 @@ const Modal = ({
   const pretendContentTranslateY = useSharedValue(20);
   const isBrandBackground = background === 'brand';
 
+  const [inNavModalHeight, setInNavModalHeight] = useState<number>();
+
+  const isNavModalFullScreen = useMemo(() => {
+    if (!inNavModalHeight || !inNavModal) return false;
+
+    const screenHeight = Dimensions.get('window').height;
+
+    return inNavModalHeight >= screenHeight;
+  }, [inNavModalHeight, inNavModal]);
+
   const triggerCloseAnimation = useCallback(() => {
     if (Platform.OS === 'android' && inNavModal) {
       pretendContentTranslateY.value = withTiming(20, {
@@ -173,6 +184,9 @@ const Modal = ({
     stickyFooter,
     showHandle: props.showHandle,
     background: isBrandBackground ? 'brand' : 'primary',
+    ...(inNavModal && {
+      fullscreen: isNavModalFullScreen,
+    }),
   });
 
   const footer = (
@@ -200,6 +214,8 @@ const Modal = ({
     </View>
   );
 
+  const InNavModalContainer = scrollable ? ScrollView : View;
+
   const content = (
     <>
       {loading ? (
@@ -275,8 +291,14 @@ const Modal = ({
               </View>
             </View>
           ) : null}
-          {inNavModal ? <ScrollView style={{ flex: 1 }}>{children}</ScrollView> : children}
-          {(!stickyFooter || inNavModal) && !noButtons ? footer : null}
+          {inNavModal && (
+            <InNavModalContainer style={{ flexGrow: stickyFooter ? 1 : 0 }}>
+              {children}
+              {!stickyFooter ? <View style={styles.inNavModalFooterContainer}>{footer}</View> : null}
+            </InNavModalContainer>
+          )}
+          {!inNavModal && children}
+          {((!stickyFooter && !inNavModal) || (inNavModal && stickyFooter)) && !noButtons ? footer : null}
         </View>
       )}
     </>
@@ -300,6 +322,9 @@ const Modal = ({
 
   return inNavModal ? (
     <View
+      onLayout={(e) => {
+        setInNavModalHeight(e.nativeEvent.layout.height);
+      }}
       style={{
         flex: 1,
         backgroundColor: theme.color.background[isBrandBackground ? 'brand' : 'primary'],
@@ -313,7 +338,9 @@ const Modal = ({
       <Animated.View
         style={[styles.inNavModalContainer, Platform.OS === 'android' && animatedInNavModalStyle]}
       >
-        <View style={styles.inNavModalContent}>{content}</View>
+        <View style={styles.inNavModalContent}>
+          {content}
+        </View>
       </Animated.View>
     </View>
   ) : (
@@ -444,8 +471,6 @@ const styles = StyleSheet.create((theme, rt) => ({
     borderTopLeftRadius: theme.components.modal.borderRadius,
     borderTopRightRadius: theme.components.modal.borderRadius,
     backgroundColor: theme.color.surface.neutral.strong,
-    gap: theme.components.modal.gap,
-    padding: theme.components.modal.padding,
     paddingBottom: theme.components.modal.padding + rt.insets.bottom,
     variants: {
       background: {
@@ -454,8 +479,20 @@ const styles = StyleSheet.create((theme, rt) => ({
           backgroundColor: theme.color.background.brand,
         },
       },
+      fullscreen: {
+        true: {
+          padding: theme.components.modal.padding,
+          paddingTop: rt.insets.top,
+        },
+        false: {
+          padding: theme.components.modal.padding,
+        }
+      }
     },
   },
+  inNavModalFooterContainer: {
+    paddingTop: theme.components.modal.padding,
+  },
   androidContainer: {
     height: rt.insets.top + 18,
     paddingLeft: theme.components.modal.padding,

package/src/components/TimePicker/TimePicker.docs.mdx

@@ -0,0 +1,84 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { Button, Center } from '../../';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './TimePicker.stories';
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=10334-16770&t=Jg2fPJPQNzOyspmQ-4" />
+
+<Meta title="Components / Time Picker" />
+
+<BackToTopButton />
+
+# Time Picker
+
+`TimePicker` presents a wheel-based time selector inside a bottom sheet, letting people pick hours and minutes without leaving the current context. It supports 12-hour and 24-hour clocks and returns a JavaScript `Date` whenever the selection changes.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Accessibility](#accessibility)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+Use the `TimePicker` with a ref to present the bottom sheet when people tap a trigger button.
+
+<UsageWrap>
+  <Center>
+    <Button onPress={() => {}}>Pick a time</Button>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { useRef, useState } from 'react';
+import {
+  BottomSheetModalProvider,
+  Button,
+  TimePicker,
+  type DateType,
+} from '@utilitywarehouse/hearth-react-native';
+
+const BookingTime = () => {
+  const pickerRef = useRef(null);
+  const [time, setTime] = useState<DateType>();
+
+  return (
+    <BottomSheetModalProvider>
+      <Button onPress={() => pickerRef.current?.present()}>Choose time</Button>
+
+      <TimePicker
+        ref={pickerRef}
+        date={time}
+        onChange={({ date }) => setTime(date)}
+        onCancel={() => setTime(undefined)}
+        use12Hours={false}
+      />
+    </BottomSheetModalProvider>
+  );
+};
+```
+
+## Props
+
+`TimePicker` extends the `BottomSheetModal` component. The table below highlights the main props.
+
+| Prop             | Type                                    | Default    | Description                                                     |
+| ---------------- | --------------------------------------- | ---------- | --------------------------------------------------------------- |
+| `date`           | `DateType`                              | `-`        | Selected time value.                                            |
+| `timeZone`       | `string`                                | `-`        | IANA time zone identifier applied to the selected time.         |
+| `use12Hours`     | `boolean`                               | `false`    | Displays an AM/PM selector and formats hours from 1 to 12.      |
+| `minuteInterval` | `number`                                | `1`        | Step interval for minutes shown in the picker.                  |
+| `hideFooter`     | `boolean`                               | `false`    | Hides the Cancel/Ok actions.                                    |
+| `onChange`       | `(payload: { date: DateType }) => void` | `-`        | Fired whenever the selected time changes.                       |
+| `onCancel`       | `() => void`                            | `() => {}` | Fired when the cancel action is triggered.                      |
+| `ref`            | `Ref<BottomSheetModalMethods>`          | `-`        | Gives imperative access to present or dismiss the bottom sheet. |
+
+## Accessibility
+
+- Screen readers announce the picker when the sheet opens and focus the wheel area on Android.
+- Action buttons are exposed as standard buttons with clear labels.

package/src/components/TimePicker/TimePicker.figma.tsx

@@ -0,0 +1,29 @@
+import figma from '@figma/code-connect';
+import { useRef, useState } from 'react';
+import { BottomSheetModalProvider, Button, DateType, TimePicker } from '../';
+
+figma.connect(
+  TimePicker,
+  'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=10334-16770&t=Jg2fPJPQNzOyspmQ-4',
+  {
+    props: {},
+    example: props => {
+      const pickerRef = useRef(null);
+      const [time, setTime] = useState<DateType>();
+
+      return (
+        <BottomSheetModalProvider>
+          <Button onPress={() => pickerRef.current?.present()}>Choose time</Button>
+
+          <TimePicker
+            ref={pickerRef}
+            date={time}
+            onChange={({ date }) => setTime(date)}
+            onCancel={() => setTime(undefined)}
+            use12Hours={false}
+          />
+        </BottomSheetModalProvider>
+      );
+    },
+  }
+);

package/src/components/TimePicker/TimePicker.props.ts

@@ -0,0 +1,45 @@
+import type { BottomSheetModalMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
+import type { Ref } from 'react';
+import type { ViewStyle } from 'react-native';
+import type { DateType, PickerOption } from '../DatePicker/DatePicker.props';
+
+export interface TimePickerProps {
+  /**
+   * IANA time zone identifier applied when normalising and comparing times.
+   */
+  timeZone?: string;
+  /**
+   * Controlled time value.
+   */
+  date?: DateType;
+  /**
+   * Fired whenever a time is picked.
+   */
+  onChange?: (params: { date: DateType }) => void;
+  /**
+   * Display a 12-hour clock with AM/PM selector.
+   */
+  use12Hours?: boolean;
+  /**
+   * Step interval for minutes shown in the picker.
+   */
+  minuteInterval?: number;
+  /**
+   * Hide the footer actions.
+   */
+  hideFooter?: boolean;
+  /**
+   * Custom container styling for the time picker surface.
+   */
+  style?: ViewStyle;
+  /**
+   * Gives imperative access to the bottom sheet instance.
+   */
+  ref?: Ref<BottomSheetModalMethods<any>>;
+  /**
+   * Fired when the cancel action is triggered.
+   */
+  onCancel?: () => void;
+}
+
+export type { DateType, PickerOption };

package/src/components/TimePicker/TimePicker.stories.tsx

@@ -0,0 +1,85 @@
+import { Meta, StoryObj } from '@storybook/react-native';
+import { useRef, useState } from 'react';
+import { Platform, View } from 'react-native';
+import { DateType, TimePicker } from '.';
+import { ViewWrap } from '../../../docs/components';
+import { BottomSheetModal } from '../BottomSheet';
+import { Button } from '../Button';
+
+const meta = {
+  title: 'Stories / TimePicker',
+  component: TimePicker,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    use12Hours: {
+      control: 'boolean',
+      description: 'Display a 12-hour clock with AM/PM selector',
+      defaultValue: false,
+    },
+    minuteInterval: {
+      control: 'number',
+      description: 'Step interval for minutes shown in the picker',
+      defaultValue: 1,
+    },
+  },
+  args: {
+    use12Hours: false,
+    minuteInterval: 1,
+  },
+} satisfies Meta<typeof TimePicker>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+type StoryArgs = Story['args'];
+
+export const Playground: Story = {
+  render: (args: StoryArgs) => {
+    const [selected, setSelected] = useState<DateType>();
+    const modalRef = useRef<BottomSheetModal>(null);
+
+    return (
+      <View style={Platform.OS === 'web' ? { width: 400, height: 400 } : {}}>
+        <ViewWrap>
+          <Button onPress={() => modalRef.current?.present()}>Show Time Picker</Button>
+          <TimePicker
+            ref={modalRef}
+            date={selected}
+            use12Hours={args.use12Hours}
+            minuteInterval={args.minuteInterval}
+            onChange={({ date }) => setSelected(date)}
+            onCancel={() => setSelected(undefined)}
+          />
+        </ViewWrap>
+      </View>
+    );
+  },
+};
+
+export const TwelveHour: Story = {
+  args: {
+    use12Hours: true,
+  },
+  render: (args: StoryArgs) => {
+    const [selected, setSelected] = useState<DateType>();
+    const modalRef = useRef<BottomSheetModal>(null);
+
+    return (
+      <View style={Platform.OS === 'web' ? { width: 400, height: 400 } : {}}>
+        <ViewWrap>
+          <Button onPress={() => modalRef.current?.present()}>Show 12-hour Time Picker</Button>
+          <TimePicker
+            ref={modalRef}
+            date={selected}
+            use12Hours={args.use12Hours}
+            minuteInterval={args.minuteInterval}
+            onChange={({ date }) => setSelected(date)}
+            onCancel={() => setSelected(undefined)}
+          />
+        </ViewWrap>
+      </View>
+    );
+  },
+};

package/src/components/TimePicker/TimePicker.tsx

@@ -0,0 +1,150 @@
+import dayjs from 'dayjs';
+import timezone from 'dayjs/plugin/timezone';
+import utc from 'dayjs/plugin/utc';
+import { useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
+import { AccessibilityInfo, findNodeHandle, Platform, View as RNView } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { BottomSheetModal, BottomSheetView } from '../BottomSheet';
+import { Button } from '../Button';
+import type { DateType, TimePickerProps } from './TimePicker.props';
+import TimePickerView from './TimePickerView';
+
+dayjs.extend(utc);
+dayjs.extend(timezone);
+
+type FooterProps = {
+  onCancel: () => void;
+  onConfirm: () => void;
+};
+
+const Footer = ({ onCancel, onConfirm }: FooterProps) => {
+  return (
+    <RNView style={styles.footer} testID="footer">
+      <Button variant="ghost" colorScheme="functional" onPress={onCancel}>
+        Cancel
+      </Button>
+      <Button variant="ghost" colorScheme="functional" onPress={onConfirm}>
+        Ok
+      </Button>
+    </RNView>
+  );
+};
+
+const TimePicker = ({
+  timeZone,
+  date,
+  onChange,
+  use12Hours,
+  minuteInterval,
+  hideFooter,
+  style,
+  ref,
+  onCancel = () => {},
+}: TimePickerProps) => {
+  dayjs.tz.setDefault(timeZone);
+  dayjs.locale('en');
+
+  const modalRef = useRef<BottomSheetModal>(null);
+  const pickerViewRef = useRef<RNView>(null);
+
+  useImperativeHandle(ref, () => modalRef.current as BottomSheetModal);
+
+  const [currentDate, setCurrentDate] = useState<DateType>(() => {
+    return date ? dayjs.tz(date, timeZone) : dayjs().tz(timeZone);
+  });
+
+  useEffect(() => {
+    const nextDate = date ? dayjs.tz(date, timeZone) : dayjs().tz(timeZone);
+    const isSameMinute = dayjs(currentDate).isSame(nextDate, 'minute');
+
+    if (!isSameMinute) {
+      setCurrentDate(nextDate);
+    }
+  }, [currentDate, date, timeZone]);
+
+  const closeTimePicker = useCallback(() => {
+    modalRef.current?.close();
+  }, []);
+
+  const handleSelectDate = useCallback(
+    (selectedDate: DateType) => {
+      const newDate = dayjs.tz(selectedDate ?? currentDate, timeZone);
+      if (!dayjs(currentDate).isSame(newDate, 'minute')) {
+        setCurrentDate(newDate);
+      }
+      onChange?.({ date: newDate ? dayjs(newDate).toDate() : newDate });
+    },
+    [currentDate, onChange, timeZone]
+  );
+
+  const handleCancel = useCallback(() => {
+    onCancel?.();
+    closeTimePicker();
+  }, [closeTimePicker, onCancel]);
+
+  const handleConfirm = useCallback(() => {
+    closeTimePicker();
+  }, [closeTimePicker]);
+
+  const handleChange = useCallback((index: number) => {
+    if (index > -1) {
+      setTimeout(() => {
+        AccessibilityInfo.announceForAccessibility('Time picker opened.');
+
+        const targetRef = pickerViewRef.current;
+        if (targetRef) {
+          const nodeHandle = findNodeHandle(targetRef);
+          if (nodeHandle) {
+            AccessibilityInfo.setAccessibilityFocus(nodeHandle);
+          }
+        }
+      }, 50);
+    }
+  }, []);
+
+  const contentStyle = useMemo(() => [styles.container, style], [style]);
+
+  return (
+    <BottomSheetModal
+      ref={modalRef}
+      onChange={handleChange}
+      accessible={false}
+      enableContentPanningGesture={false}
+    >
+      <BottomSheetView>
+        <RNView
+          ref={pickerViewRef}
+          accessible={Platform.OS === 'android' ? true : undefined}
+          accessibilityLabel={Platform.OS === 'android' ? 'Time picker' : undefined}
+          importantForAccessibility={Platform.OS === 'android' ? 'yes' : 'auto'}
+          style={contentStyle}
+        >
+          <TimePickerView
+            currentDate={currentDate}
+            onSelectDate={handleSelectDate}
+            timeZone={timeZone}
+            use12Hours={use12Hours}
+            minuteInterval={minuteInterval}
+          />
+          {!hideFooter ? <Footer onCancel={handleCancel} onConfirm={handleConfirm} /> : null}
+        </RNView>
+      </BottomSheetView>
+    </BottomSheetModal>
+  );
+};
+
+TimePicker.displayName = 'TimePicker';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    backgroundColor: theme.color.background.secondary,
+    gap: theme.components.datePicker.calendar.gap,
+  },
+  footer: {
+    flexDirection: 'row',
+    gap: theme.components.datePicker.calendar.footer.gap,
+    justifyContent: 'flex-end',
+  },
+}));
+
+export default TimePicker;