@utilitywarehouse/hearth-react-native 0.28.6 → 0.29.1

package/src/components/Modal/Modal.web.tsx

@@ -1,18 +1,9 @@
 import { BottomSheetScrollViewMethods, SNAP_POINT_TYPE } 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 { useImperativeHandle, useRef } from 'react';
 import { AccessibilityInfo, Platform, View, findNodeHandle } from 'react-native';
-import Animated, {
-  Easing,
-  useAnimatedStyle,
-  useSharedValue,
-  withDelay,
-  withTiming,
-} from 'react-native-reanimated';
 import { StyleSheet } from 'react-native-unistyles';
-import { useTheme } from '../../hooks';
-import { hexWithOpacity } from '../../utils';
 import { BodyText } from '../BodyText';
 import { BottomSheetModal, BottomSheetScrollView } from '../BottomSheet';
 import { Button } from '../Button';
@@ -38,74 +29,19 @@ const Modal = ({
   closeOnSecondaryButtonPress = true,
   loading,
   loadingHeading = 'Loading...',
+  fullscreen = false,
   image,
   primaryButtonProps,
   secondaryButtonProps,
   closeButtonProps,
-  inNavModal = false,
   ...props
 }: ModalProps) => {
   const bottomSheetModalRef = useRef<BottomSheetModal>(null);
   const viewRef = useRef<View>(null);
   const scrollViewRef = useRef<BottomSheetScrollViewMethods>(null);
-  const theme = useTheme();
-  const backgroundOpacity = useSharedValue(0);
-  const pretendContentTranslateY = useSharedValue(20);
-
-  const triggerCloseAnimation = useCallback(() => {
-    if (Platform.OS === 'android' && inNavModal) {
-      pretendContentTranslateY.value = withTiming(20, {
-        duration: 50,
-        easing: Easing.in(Easing.quad),
-      });
-      backgroundOpacity.value = withTiming(0, {
-        duration: 100,
-        easing: Easing.in(Easing.quad),
-      });
-    }
-  }, [Platform.OS, inNavModal, pretendContentTranslateY, backgroundOpacity]);
 
   useImperativeHandle(ref, () => ({
     ...(bottomSheetModalRef.current as BottomSheetModal),
-    triggerCloseAnimation,
-  }));
-
-  // Trigger animations on render for inNavModal Android modal
-  useEffect(() => {
-    if (Platform.OS === 'android' && inNavModal) {
-      backgroundOpacity.value = withDelay(
-        300,
-        withTiming(1, {
-          duration: 200,
-          easing: Easing.out(Easing.quad),
-        })
-      );
-      pretendContentTranslateY.value = withDelay(
-        500,
-        withTiming(0, {
-          duration: 300,
-          easing: Easing.out(Easing.quad),
-        })
-      );
-    }
-  }, [inNavModal, backgroundOpacity, pretendContentTranslateY]);
-
-  const animatedBackgroundStyle = useAnimatedStyle(() => ({
-    backgroundColor: hexWithOpacity(
-      theme.components.overlay.backgroundColor,
-      backgroundOpacity.value * (theme.components.overlay.opacity / 100)
-    ),
-  }));
-
-  const animatedInNavModalStyle = useAnimatedStyle(() => ({
-    backgroundColor: hexWithOpacity(
-      theme.components.overlay.backgroundColor,
-      backgroundOpacity.value * (theme.components.overlay.opacity / 100)
-    ),
-  }));
-
-  const animatedPretendContentStyle = useAnimatedStyle(() => ({
-    transform: [{ translateY: pretendContentTranslateY.value }],
   }));
 
   const handleChange = (index: number, position: number, type: SNAP_POINT_TYPE) => {
@@ -155,6 +91,8 @@ const Modal = ({
     }
   };
 
+  const noButtons = !onPressPrimaryButton && !onPressSecondaryButton;
+
   const content = (
     <>
       {loading ? (
@@ -214,49 +152,38 @@ const Modal = ({
             </View>
           ) : null}
           {children}
-          <View style={styles.footer}>
-            {onPressPrimaryButton && primaryButtonText ? (
-              <Button
-                onPress={handlePrimaryButtonPress}
-                text={primaryButtonText}
-                {...primaryButtonProps}
-                variant={(primaryButtonProps?.variant as 'solid') ?? 'solid'}
-                colorScheme={(primaryButtonProps?.colorScheme as 'highlight') ?? 'highlight'}
-              />
-            ) : null}
-            {onPressSecondaryButton && secondaryButtonText ? (
-              <Button
-                onPress={handleSecondaryButtonPress}
-                text={secondaryButtonText}
-                {...secondaryButtonProps}
-                variant={(secondaryButtonProps?.variant as 'outline') ?? 'outline'}
-                colorScheme={(secondaryButtonProps?.colorScheme as 'functional') ?? 'functional'}
-              />
-            ) : null}
-          </View>
+          {!noButtons ? (
+            <View style={styles.footer}>
+              {onPressPrimaryButton && primaryButtonText ? (
+                <Button
+                  onPress={handlePrimaryButtonPress}
+                  text={primaryButtonText}
+                  {...primaryButtonProps}
+                  variant={(primaryButtonProps?.variant as 'solid') ?? 'solid'}
+                  colorScheme={(primaryButtonProps?.colorScheme as 'highlight') ?? 'highlight'}
+                />
+              ) : null}
+              {onPressSecondaryButton && secondaryButtonText ? (
+                <Button
+                  onPress={handleSecondaryButtonPress}
+                  text={secondaryButtonText}
+                  {...secondaryButtonProps}
+                  variant={(secondaryButtonProps?.variant as 'outline') ?? 'outline'}
+                  colorScheme={(secondaryButtonProps?.colorScheme as 'functional') ?? 'functional'}
+                />
+              ) : null}
+            </View>
+          ) : null}
         </View>
       )}
     </>
   );
 
-  return inNavModal ? (
-    <View style={{ flex: 1, backgroundColor: theme.color.background.primary }}>
-      {Platform.OS === 'android' ? (
-        <Animated.View style={[styles.androidContainer, animatedBackgroundStyle]}>
-          <Animated.View style={[styles.pretendContent, animatedPretendContentStyle]} />
-        </Animated.View>
-      ) : null}
-      <Animated.View
-        style={[styles.inNavModalContainer, Platform.OS === 'android' && animatedInNavModalStyle]}
-      >
-        <View style={styles.inNavModalContent}>{content}</View>
-      </Animated.View>
-    </View>
-  ) : (
+  return (
     <BottomSheetModal
       ref={bottomSheetModalRef}
       enableDynamicSizing={true}
-      snapPoints={image ? ['90%'] : props.snapPoints}
+      snapPoints={image || fullscreen ? ['90%'] : props.snapPoints}
       showHandle={typeof loading !== 'undefined' && loading ? false : props.showHandle}
       accessible={false}
       {...props}
@@ -269,7 +196,7 @@ const Modal = ({
   );
 };
 
-const styles = StyleSheet.create((theme, rt) => ({
+const styles = StyleSheet.create(theme => ({
   container: {
     flex: 1,
     gap: theme.components.modal.gap,
@@ -300,31 +227,6 @@ const styles = StyleSheet.create((theme, rt) => ({
   footer: {
     gap: theme.components.modal.action.gap,
   },
-  inNavModalContainer: {
-    flex: 1,
-    ...(Platform.OS === 'ios' ? { backgroundColor: theme.components.overlay.backgroundColor } : {}),
-  },
-  inNavModalContent: {
-    flex: 1,
-    borderTopLeftRadius: theme.components.modal.borderRadius,
-    borderTopRightRadius: theme.components.modal.borderRadius,
-    backgroundColor: theme.color.surface.neutral.strong,
-    gap: theme.components.modal.gap,
-    padding: theme.components.bottomSheet.padding,
-    paddingBottom: theme.components.modal.padding + rt.insets.bottom,
-  },
-  androidContainer: {
-    height: rt.insets.top + 18,
-    paddingLeft: theme.components.bottomSheet.padding,
-    paddingRight: theme.components.bottomSheet.padding,
-    justifyContent: 'flex-end',
-  },
-  pretendContent: {
-    borderTopLeftRadius: theme.components.modal.borderRadius,
-    borderTopRightRadius: theme.components.modal.borderRadius,
-    height: 12,
-    backgroundColor: theme.components.parts.modalStack.backgroundColorCardTop,
-  },
 }));
 
 export default Modal;

package/src/components/NavModal/NavModal.docs.mdx

@@ -0,0 +1,178 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import StorybookLink from '../../../../../shared/storybook/StorybookLink';
+import modalAndroidVideo from '../../../docs/assets/modal-android.mp4';
+import modaliOSVideo from '../../../docs/assets/modal-ios.mp4';
+import { BackToTopButton, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './NavModal.stories';
+
+<Meta title="Components / NavModal" />
+
+<ViewFigmaButton url="https://www.figma.com/design/dLI9bmyMr42LV7dtFeW27J/Hearth-Patterns---Guides?node-id=6314-9103&t=oq3NaPLaAu3di6Db-4" />
+
+<BackToTopButton />
+
+# NavModal
+
+The `NavModal` component is the screen-based modal layout for navigation flows. Use it when a screen is already being presented by React Navigation with `presentation: 'modal'` or `presentation: 'fullScreenModal'` and you want Hearth's modal structure, actions, and Android close animation support.
+
+If you need a bottom-sheet modal that you present with a ref, use <StorybookLink to="components-modal">`Modal`</StorybookLink> instead.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Features](#features)
+- [Accessibility](#accessibility)
+- [Examples](#examples)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+```tsx
+import { useNavigation } from '@react-navigation/native';
+import type { NavigationAction } from '@react-navigation/native';
+import { useCallback, useEffect, useRef } from 'react';
+import { Platform, StyleSheet, View } from 'react-native';
+
+import {
+  BodyText,
+  Heading,
+  InlineLink,
+  NavModal,
+  type NavModalRef,
+} from '@utilitywarehouse/hearth-react-native';
+
+export default function ModalScreen({ onClose }: { onClose?: () => void }) {
+  const modalRef = useRef<NavModalRef>(null);
+  const navigation = useNavigation();
+  const isClosingRef = useRef(false);
+
+  const handleClose = useCallback(
+    (action?: NavigationAction) => {
+      if (Platform.OS === 'ios') {
+        if (onClose) {
+          onClose();
+        } else {
+          navigation.goBack();
+        }
+
+        return;
+      }
+
+      if (isClosingRef.current) {
+        return;
+      }
+
+      isClosingRef.current = true;
+      modalRef.current?.triggerCloseAnimation?.();
+
+      setTimeout(() => {
+        if (onClose) {
+          onClose();
+        } else if (action) {
+          navigation.dispatch(action);
+        } else {
+          navigation.goBack();
+        }
+      }, 100);
+    },
+    [navigation, onClose]
+  );
+
+  useEffect(() => {
+    if (Platform.OS === 'android') {
+      const unsubscribe = navigation.addListener('beforeRemove', e => {
+        if (!isClosingRef.current) {
+          e.preventDefault();
+          handleClose(e.data.action);
+        }
+      });
+
+      return unsubscribe;
+    }
+  }, [handleClose, navigation]);
+
+  return (
+    <NavModal
+      ref={modalRef}
+      onPressCloseButton={handleClose}
+      primaryButtonText="Action"
+      onPressPrimaryButton={handleClose}
+      secondaryButtonText="Cancel"
+      onPressSecondaryButton={handleClose}
+    >
+      <View style={styles.container}>
+        <Heading size="xl">This is a modal</Heading>
+        <BodyText>
+          <InlineLink onPress={handleClose} style={styles.link}>
+            Go to home screen
+          </InlineLink>
+        </BodyText>
+      </View>
+    </NavModal>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 20,
+  },
+  link: {
+    marginTop: 15,
+    paddingVertical: 15,
+  },
+});
+```
+
+## Props
+
+`NavModal` supports Hearth's modal content props plus the navigation-specific `background`, `scrollable`, and `presentation` options. Set `presentation` to the same value you pass to React Navigation so `NavModal` can match the route's sheet-style or full-screen layout. It does not take bottom-sheet props such as `snapPoints`, and it does not manage its own dismissal. Your screen or navigator owns closing behavior.
+
+| Property                 | Type                                                                                                             | Description                                                                                                                                   | Default        |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| `heading`                | `string`                                                                                                         | Heading text shown at the top of the modal when no `image` is provided.                                                                       | -              |
+| `description`            | `string`                                                                                                         | Supporting text shown below the heading when no `image` is provided.                                                                          | -              |
+| `showCloseButton`        | `boolean`                                                                                                        | Whether to render the close button in the top-right corner.                                                                                   | `true`         |
+| `primaryButtonText`      | `string`                                                                                                         | Label for the primary action button.                                                                                                          | -              |
+| `secondaryButtonText`    | `string`                                                                                                         | Label for the secondary action button.                                                                                                        | -              |
+| `onPressPrimaryButton`   | `() => void`                                                                                                     | Called when the primary action button is pressed.                                                                                             | -              |
+| `onPressSecondaryButton` | `() => void`                                                                                                     | Called when the secondary action button is pressed.                                                                                           | -              |
+| `onPressCloseButton`     | `() => void`                                                                                                     | Called when the close button is pressed.                                                                                                      | -              |
+| `primaryButtonProps`     | `Omit<ButtonWithoutChildrenProps, 'children'>`                                                                   | Extra props forwarded to the primary button.                                                                                                  | -              |
+| `secondaryButtonProps`   | `Omit<ButtonWithoutChildrenProps, 'children'>`                                                                   | Extra props forwarded to the secondary button.                                                                                                | -              |
+| `closeButtonProps`       | `Omit<UnstyledIconButtonProps, 'children'>`                                                                      | Extra props forwarded to the close button.                                                                                                    | -              |
+| `loading`                | `boolean`                                                                                                        | Replaces the content with a loading state and spinner.                                                                                        | `false`        |
+| `loadingHeading`         | `string`                                                                                                         | Heading text shown while `loading` is true.                                                                                                   | `'Loading...'` |
+| `image`                  | `ReactNode`                                                                                                      | Optional image or illustration shown above the text content.                                                                                  | -              |
+| `children`               | `ReactNode`                                                                                                      | Content rendered inside the modal body.                                                                                                       | -              |
+| `stickyFooter`           | `boolean`                                                                                                        | Keeps action buttons pinned to the bottom instead of flowing with the content.                                                                | `true`         |
+| `background`             | `'default' /\| 'brand'`                                                                                          | Switches between the default surface background and the brand background treatment.                                                           | `'default'`    |
+| `scrollable`             | `boolean`                                                                                                        | Wraps the content area in a `ScrollView`. Set this to `false` for custom layouts that should not scroll.                                      | `true`         |
+| `presentation`           | `'modal' \| 'fullScreenModal' \| 'transparentModal' `<br />` \| 'containedModal' \| 'containedTransparentModal'` | Matches the React Navigation screen presentation. `fullScreenModal` uses the full-screen layout; the other values use the sheet-style layout. | `'modal'`      |
+| `safeAreaViewProps`      | `SafeAreaViewProps`                                                                                              | Extra props forwarded to the `SafeAreaView` wrapping the modal content.                                                                       | -              |
+| `scrollViewProps`        | `ScrollViewProps`                                                                                                | Extra props forwarded to the `ScrollView` wrapping the modal content when `scrollable` is true.                                               | -              |
+
+## Accessibility
+
+`NavModal` keeps the same heading, description, button labeling, and loading-state support as `Modal`, but it does not force accessibility focus on mount. Because this component is used on a navigation-presented screen, React Navigation and the platform own the initial screen focus behavior.
+
+## Examples
+
+| ios                                                                            | android                                                                            |
+| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| <video src={modaliOSVideo} width={300} height="auto" controls loop autoPlay /> | <video src={modalAndroidVideo} width={300} height="auto" controls loop autoPlay /> |
+
+### Brand Background
+
+<Canvas of={Stories.BrandBackground} />
+
+### Full-Screen Presentation
+
+<Canvas of={Stories.FullScreenPresentation} />

package/src/components/NavModal/NavModal.figma.tsx

@@ -0,0 +1,13 @@
+import figma from '@figma/code-connect';
+import { NavModal } from '..';
+
+figma.connect(
+  NavModal,
+  'https://www.figma.com/design/dLI9bmyMr42LV7dtFeW27J/Hearth-Patterns---Guides?node-id=6314-9103&t=oq3NaPLaAu3di6Db-4',
+  {
+    props: {},
+    example: props => {
+      return <NavModal>{/* Your content here */}</NavModal>;
+    },
+  }
+);

package/src/components/NavModal/NavModal.props.ts

@@ -0,0 +1,23 @@
+import { Ref } from 'react';
+import { SafeAreaViewProps } from 'react-native-safe-area-context';
+import { ModalCommonProps } from '../Modal/Modal.shared.types';
+
+export interface NavModalRef {
+  triggerCloseAnimation?: () => void;
+}
+
+interface NavModalProps extends ModalCommonProps {
+  ref?: Ref<NavModalRef>;
+  background?: 'default' | 'brand';
+  scrollable?: boolean;
+  presentation?:
+    | 'fullScreenModal'
+    | 'modal'
+    | 'transparentModal'
+    | 'containedModal'
+    | 'containedTransparentModal';
+  safeAreaViewProps?: Omit<SafeAreaViewProps, 'children'>;
+  scrollViewProps?: Omit<SafeAreaViewProps, 'children'>;
+}
+
+export default NavModalProps;

package/src/components/NavModal/NavModal.stories.tsx

@@ -0,0 +1,131 @@
+import { Meta, StoryObj } from '@storybook/react-native';
+import { Platform, View } from 'react-native';
+import { BodyText } from '../BodyText';
+import { Box } from '../Box';
+import NavModal from './NavModal';
+
+const meta = {
+  title: 'Stories / NavModal',
+  component: NavModal,
+  parameters: {
+    layout: 'fullscreen',
+    noScroll: true,
+  },
+  argTypes: {
+    heading: {
+      control: 'text',
+      description: 'The heading text to be displayed.',
+    },
+    description: {
+      control: 'text',
+      description: 'The description text to be displayed.',
+    },
+    showCloseButton: {
+      control: 'boolean',
+      description: 'Whether to show the close button.',
+    },
+    primaryButtonText: {
+      control: 'text',
+      description: 'Text for the primary button.',
+    },
+    secondaryButtonText: {
+      control: 'text',
+      description: 'Text for the secondary button.',
+    },
+    loading: {
+      control: 'boolean',
+      description: 'Whether the modal is in a loading state.',
+    },
+    loadingHeading: {
+      control: 'text',
+      description: 'The heading text to be displayed when loading is true.',
+    },
+    background: {
+      control: 'radio',
+      options: ['default', 'brand'],
+      description: 'Sets the modal background.',
+    },
+    presentation: {
+      control: 'radio',
+      options: [
+        'modal',
+        'fullScreenModal',
+        'transparentModal',
+        'containedModal',
+        'containedTransparentModal',
+      ],
+      description: 'Matches the React Navigation presentation style for the screen.',
+    },
+    scrollable: {
+      control: 'boolean',
+      description: 'Whether the modal content should be wrapped in a ScrollView.',
+    },
+  },
+  actions: {
+    onPressPrimaryButton: { action: () => null },
+    onPressSecondaryButton: { action: () => null },
+    onPressCloseButton: { action: () => null },
+  },
+  args: {
+    heading: 'NavModal Heading',
+    description: 'This is a navigation modal description',
+    showCloseButton: true,
+    primaryButtonText: 'Primary',
+    secondaryButtonText: 'Cancel',
+    loading: false,
+    background: 'default',
+    scrollable: true,
+    presentation: 'modal',
+    onPressCloseButton: () => null,
+    onPressPrimaryButton: () => null,
+    onPressSecondaryButton: () => null,
+  },
+} satisfies Meta<typeof NavModal>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  render: (args: StoryObj<typeof meta.args>) => (
+    <View style={Platform.OS === 'web' ? { width: 400, height: 720 } : { flex: 1 }}>
+      <NavModal {...args}>
+        <Box gap="200">
+          <BodyText>This is a navigation modal with content.</BodyText>
+          <BodyText>Use it for React Navigation modal screens instead of bottom sheets.</BodyText>
+        </Box>
+      </NavModal>
+    </View>
+  ),
+};
+
+export const BrandBackground: Story = {
+  args: {
+    background: 'brand',
+  },
+  render: (args: StoryObj<typeof meta.args>) => (
+    <View style={Platform.OS === 'web' ? { width: 400, height: 720 } : { flex: 1 }}>
+      <NavModal {...args}>
+        <Box gap="200">
+          <BodyText inverted>Brand background content stays readable with inverted text.</BodyText>
+          <BodyText inverted>Buttons and the close icon also invert automatically.</BodyText>
+        </Box>
+      </NavModal>
+    </View>
+  ),
+};
+
+export const FullScreenPresentation: Story = {
+  args: {
+    presentation: 'fullScreenModal',
+  },
+  render: (args: StoryObj<typeof meta.args>) => (
+    <View style={Platform.OS === 'web' ? { width: 400, height: 720 } : { flex: 1 }}>
+      <NavModal {...args}>
+        <Box gap="200">
+          <BodyText>This uses the full-screen navigation modal presentation.</BodyText>
+          <BodyText>The content switches away from the sheet-style card treatment.</BodyText>
+        </Box>
+      </NavModal>
+    </View>
+  ),
+};