@utilitywarehouse/hearth-react-native 0.31.1 → 0.32.0

package/build/components/StepperInput/index.js

@@ -0,0 +1 @@
+export { default as StepperInput } from './StepperInput';

package/build/components/Textarea/Textarea.d.ts

@@ -7,5 +7,5 @@ export declare const TextareaComponent: import("@gluestack-ui/textarea/lib/types
     };
 }, import("react-native").TextInputProps>;
 export declare const TextareaField: import("react").ForwardRefExoticComponent<import("react-native").TextInputProps & import("react").RefAttributes<import("react-native").TextInputProps> & import("@gluestack-ui/textarea/lib/typescript/types").IInputProps>;
-declare const Textarea: ({ validationStatus, children, resizable, disabled, focused, readonly, label, labelVariant, helperText, validText, invalidText, required, helperIcon, onLayout, ...props }: TextareaProps) => import("react/jsx-runtime").JSX.Element;
+declare const Textarea: ({ validationStatus, children, resizable, defaultHeight, disabled, focused, readonly, label, labelVariant, helperText, validText, invalidText, required, helperIcon, onLayout, ...props }: TextareaProps) => import("react/jsx-runtime").JSX.Element;
 export default Textarea;

package/build/components/Textarea/Textarea.js

@@ -18,7 +18,7 @@ export const TextareaField = TextareaComponent.Input;
 const DEFAULT_TEXTAREA_HEIGHT = 96;
 const RESIZE_HANDLE_TOUCH_SIZE = 28;
 const RESIZE_HANDLE_ICON_SIZE = 9;
-const Textarea = ({ validationStatus = 'initial', children, resizable = false, disabled, focused, readonly, label, labelVariant, helperText, validText, invalidText, required, helperIcon, onLayout, ...props }) => {
+const Textarea = ({ validationStatus = 'initial', children, resizable = false, defaultHeight, disabled, focused, readonly, label, labelVariant, helperText, validText, invalidText, required, helperIcon, onLayout, ...props }) => {
     const formFieldContext = useFormFieldContext();
     const hasMeasuredHeight = useRef(false);
     const textareaLabel = label ?? formFieldContext?.label;
@@ -29,14 +29,21 @@ const Textarea = ({ validationStatus = 'initial', children, resizable = false, d
     const textareaDisabled = disabled ?? formFieldContext?.disabled;
     const textareaReadonly = readonly ?? formFieldContext?.readonly;
     const textareaValidationStatus = formFieldContext?.validationStatus ?? validationStatus;
-    const textareaHeight = useSharedValue(DEFAULT_TEXTAREA_HEIGHT);
-    const resizeStartHeight = useSharedValue(DEFAULT_TEXTAREA_HEIGHT);
+    const textareaDefaultHeight = defaultHeight ?? DEFAULT_TEXTAREA_HEIGHT;
+    const textareaHeight = useSharedValue(textareaDefaultHeight);
+    const resizeStartHeight = useSharedValue(textareaDefaultHeight);
     const theme = useTheme();
     useEffect(() => {
         if (formFieldContext?.setShouldHandleAccessibility) {
             formFieldContext.setShouldHandleAccessibility(true);
         }
     }, [formFieldContext]);
+    useEffect(() => {
+        if (!hasMeasuredHeight.current) {
+            textareaHeight.value = textareaDefaultHeight;
+            resizeStartHeight.value = textareaDefaultHeight;
+        }
+    }, [resizeStartHeight, textareaDefaultHeight, textareaHeight]);
     const getAccessibilityLabel = () => {
         let accessibilityLabel = '';
         if (textareaLabel) {

package/build/components/Textarea/Textarea.props.d.ts

@@ -1,5 +1,16 @@
 import type { TextInputProps, ViewProps } from 'react-native';
 export interface TextareaBaseProps {
+    /**
+     * Sets the initial height of a resizable textarea in pixels.
+     * Has no effect unless `resizable` is enabled.
+     *
+     * @type number
+     * @example
+     * ```tsx
+     * <Textarea resizable defaultHeight={140} />
+     * ```
+     */
+    defaultHeight?: number;
     /**
      * If true, the textarea can be resized vertically using a drag handle.
      *

package/build/components/index.d.ts

@@ -47,11 +47,14 @@ export * from './ProgressBar';
 export * from './ProgressStepper';
 export * from './Radio';
 export * from './RadioCard';
+export * from './Rating';
+export * from './Roundel';
 export * from './SectionHeader';
 export * from './SegmentedControl';
 export * from './Select';
 export * from './Skeleton';
 export * from './Spinner';
+export * from './StepperInput';
 export * from './Switch';
 export * from './Table';
 export * from './Tabs';

package/build/components/index.js

@@ -48,11 +48,14 @@ export * from './ProgressBar';
 export * from './ProgressStepper';
 export * from './Radio';
 export * from './RadioCard';
+export * from './Rating';
+export * from './Roundel';
 export * from './SectionHeader';
 export * from './SegmentedControl';
 export * from './Select';
 export * from './Skeleton';
 export * from './Spinner';
+export * from './StepperInput';
 export * from './Switch';
 export * from './Table';
 export * from './Tabs';

package/docs/adding-shadows.mdx

@@ -62,6 +62,6 @@ const MyComponent = () => <Card shadowColor="brand">{/* Card content */}</Card>;
 <NextPrevPage
   prevLink="all-components"
   prevTitle="All Components"
-  nextLink="primitives-box"
-  nextTitle="Box"
+  nextLink="guides-dark-mode-best-practice"
+  nextTitle="Dark Mode Best Practice"
 />

package/docs/changelog.mdx

@@ -9,6 +9,22 @@ import { BackToTopButton, NextPrevPage } from './components';
 The changelog for the Hearth React Native library. Here you can find all the changes, improvements, and bug fixes for each version.
 
 
+## 0.31.1
+
+### Patch Changes
+
+- [#1119](https://github.com/utilitywarehouse/hearth/pull/1119) [`19415d4`](https://github.com/utilitywarehouse/hearth/commit/19415d4d54458b3fb019df6647b9a5e4c375b672) Thanks [@jordmccord](https://github.com/jordmccord)! - 🐛 [FIX]: Refresh dark mode tokens across components and semantic colors.
+
+  Dark mode color tokens have been updated across semantic and component tokens to improve contrast and visual consistency. This also fixes `TableHeaderCell` text colors so purple and white header variants resolve the correct foreground token.
+
+  **Components affected**:
+  - dark mode tokens
+  - `TableHeaderCell`
+
+  **Developer changes**:
+
+  No code changes are required unless you rely on the previous dark mode token values or visual snapshots.
+
 ## 0.31.0
 
 ### Minor Changes

package/docs/components/AllComponents.web.tsx

@@ -87,12 +87,15 @@ import {
   RadioCard,
   RadioCardGroup,
   RadioGroup,
+  Rating,
+  Roundel,
   SectionHeader,
   SegmentedControl,
   SegmentedControlOption,
   Select,
   Skeleton,
   Spinner,
+  StepperInput,
   Switch,
   Tab,
   Table,
@@ -145,6 +148,8 @@ const ComponentWrapper = ({
 const AllComponents: React.FC = () => {
   const [comboboxValue, setComboboxValue] = React.useState<string | null>('uk');
   const [selectValue, setSelectValue] = React.useState('1');
+  const [stepperValue, setStepperValue] = React.useState('10');
+  const [ratingValue, setRatingValue] = React.useState<0 | 1 | 2 | 3 | 4 | 5>(3);
   const [toggleButtonValue, setToggleButtonValue] = React.useState('');
   const bottomSheetRef = useRef<BottomSheet>(null);
   const handleOpenPress = useCallback(() => {
@@ -233,6 +238,7 @@ const AllComponents: React.FC = () => {
                 </View>
               </Center>
             </ComponentWrapper>
+
             <ComponentWrapper name="Banner" link="components-banner">
               <Center flex={1} p="200">
                 <Banner
@@ -733,7 +739,20 @@ const AllComponents: React.FC = () => {
                 </RadioCardGroup>
               </Center>
             </ComponentWrapper>
-
+            <ComponentWrapper name="Rating" link="components-rating">
+              <Center flex={1} padding="200">
+                <Rating value={ratingValue} onChange={setRatingValue} />
+              </Center>
+            </ComponentWrapper>
+            <ComponentWrapper name="Roundel" link="components-roundel">
+              <Center flex={1}>
+                <Flex direction="row" spacing="md" alignItems="center">
+                  <Roundel variant="success" />
+                  <Roundel variant="pending" />
+                  <Roundel variant="error" />
+                </Flex>
+              </Center>
+            </ComponentWrapper>
             <ComponentWrapper name="Section Header" link="components-section-header">
               <Center flex={1} p="300">
                 <SectionHeader
@@ -790,6 +809,16 @@ const AllComponents: React.FC = () => {
                 <Switch value={switchEnabled} onValueChange={toggleSwitch} />
               </Center>
             </ComponentWrapper>
+            <ComponentWrapper name="Stepper Input" link="forms-stepper-input">
+              <Center flex={1} padding="200">
+                <StepperInput
+                  label="Label"
+                  helperText="Helper text"
+                  value={stepperValue}
+                  onChangeText={setStepperValue}
+                />
+              </Center>
+            </ComponentWrapper>
             <ComponentWrapper name="Table" link="components-table">
               <Center flex={1} px="300">
                 <Box style={{ width: 360 }}>

package/docs/dark-mode-best-practice.mdx

@@ -0,0 +1,328 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+import { SearchMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
+import SceneBroadbandDark from '@utilitywarehouse/hearth-svg-assets/lib/scene-broadband-dark.svg';
+import SceneBroadbandLight from '@utilitywarehouse/hearth-svg-assets/lib/scene-broadband-light.svg';
+import SpotPiggyBankDark from '@utilitywarehouse/hearth-svg-assets/lib/spot-piggy-bank-dark.svg';
+import SpotPiggyBankLight from '@utilitywarehouse/hearth-svg-assets/lib/spot-piggy-bank-light.svg';
+import { ScopedTheme } from 'react-native-unistyles';
+import StorybookLink from '../../../shared/storybook/StorybookLink';
+import { Alert, BodyText, Box, Center, Flex, Heading, Icon } from '../src';
+import { BackToTopButton, NextPrevPage, UsageWrap } from './components';
+
+<Meta title="Guides / Dark Mode Best Practice" />
+<BackToTopButton />
+
+# Dark Mode Best Practice
+
+When designing for dark mode in Hearth React Native, it's important to ensure that your UI remains visually appealing and accessible. Here are some best practices to follow:
+
+- [Setting Up Dark Mode](#setting-up-dark-mode)
+- [Use Semantic Theme Colours](#use-semantic-theme-colours)
+- [Use Semantic Utility Props](#use-semantic-utility-props)
+- [Use the asset libraries](#use-the-asset-libraries)
+  - [Icons](#icons)
+  - [Illustrations](#illustrations)
+  - [Animations](#animations)
+- [`ThemedImage` component](#themedimage-component)
+
+<br />
+<Box my="400">
+  <Alert text="By default, all components adapt to the current themed colour mode. This guide will help you understand how to work with and easily support dark mode in your apps using Hearth React Native." />
+</Box>
+<br />
+<br />
+
+## Setting Up Dark Mode
+
+By default Hearth React Native theme is set to light mode. To enable dark mode, you can set the `colorMode` property in your theme configuration to `'dark'`.
+This will automatically apply the dark mode color palette and styles across your app.
+
+```tsx
+import { useEffect } from 'react';
+import { Appearance } from 'react-native';
+import { useColorMode } from '@utilitywarehouse/hearth-react-native';
+
+const App = () => {
+  // To set the colour mode use the useColorMode hook and set the color mode
+  // to the current system preference on app load
+  const [colorMode, setColorMode] = useColorMode();
+
+  // You can optionally set the theme from the system preference on app load or
+  // load from async storage if you are persisting the user's theme choice
+  useEffect(() => {
+    setColorMode(Appearance.getColorScheme() || 'light');
+  }, []);
+
+  const toggleColorMode = () => {
+    setColorMode(colorMode === 'light' ? 'dark' : 'light');
+  };
+
+  return (/* Your app content */);
+};
+```
+
+You can also use the Unistyles runtime to set the theme outside of React components, [read more here](https://www.unistyl.es/v3/guides/theming/#change-theme):
+
+```tsx
+import { UnistylesRuntime } from 'react-native-unistyles';
+
+const toggleTheme = () => {
+  const theme = UnistylesRuntime.getTheme();
+  UnistylesRuntime.setTheme(theme === 'dark' ? 'light' : 'dark');
+};
+```
+
+## Use Semantic Theme Colours
+
+When styling your components, it's best to use the semantic colour tokens provided by the Hearth theme. This ensures that your colours will
+automatically adapt to both light and dark modes without needing to write custom styles for each mode.
+
+To use the semantic colours, you can access them from the theme object in your styles:
+
+```tsx
+import { StyleSheet } from '@utilitywarehouse/hearth-react-native';
+
+const styles = StyleSheet.create(theme => ({
+  text: {
+    color: theme.colors.text.primary, // Use semantic colour token
+  },
+}));
+```
+
+You can also use the `useTheme` hook to access the theme colours directly in your components:
+
+<UsageWrap>
+  <Center>
+    <Flex direction="row" spacing="lg">
+      <ScopedTheme name="dark">
+        <Box backgroundColor="primary" p="400">
+          <Center>
+            <BodyText>This text adapts to dark mode!</BodyText>
+          </Center>
+        </Box>
+      </ScopedTheme>
+      <ScopedTheme name="light">
+        <Box backgroundColor="primary" p="400">
+          <Center>
+            <BodyText>This text adapts to light mode!</BodyText>
+          </Center>
+        </Box>
+      </ScopedTheme>
+    </Flex>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { useTheme } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => {
+  const theme = useTheme();
+
+  return <Text style={{ color: theme.colors.text.primary }}>This text adapts to dark mode!</Text>;
+};
+```
+
+To learn more about the available colours in the Hearth theme, check out the <StorybookLink to="theme-tokens">theme tokens documentation</StorybookLink>.
+
+## Use Semantic Utility Props
+
+In addition to using semantic colour tokens, you should also use the semantic utility props provided by Hearth components.
+These props are designed to work with the theme and will automatically adjust their styles based on the current colour mode.
+
+For example, instead of setting a background colour directly, you can use the `backgroundColor` or, for text, the `color` prop with a semantic colour value:
+
+<UsageWrap>
+  <Center spacing="lg">
+    <Box>
+      <BodyText weight="semibold" mb="100">
+        {'Light Mode'}
+      </BodyText>
+      <Flex direction="row" spacing="lg">
+        <ScopedTheme name="light">
+          <Box backgroundColor="brand" p="400">
+            <BodyText color="inverted">
+              This branded box and text adapt to light or dark mode!
+            </BodyText>
+          </Box>
+          <Box backgroundColor="secondary" p="400">
+            <BodyText color="primary">This box and text adapt to light or dark mode!</BodyText>
+            <BodyText color="secondary">This secondary text adapt to light or dark mode!</BodyText>
+          </Box>
+        </ScopedTheme>
+      </Flex>
+    </Box>
+    <Box>
+      <BodyText weight="semibold" mb="100">
+        {'Dark Mode'}
+      </BodyText>
+      <Flex direction="row" spacing="lg">
+        <ScopedTheme name="dark">
+          <Box backgroundColor="brand" p="400">
+            <BodyText color="inverted">
+              This branded box and text adapt to light or dark mode!
+            </BodyText>
+          </Box>
+          <Box backgroundColor="secondary" p="400">
+            <BodyText color="primary">This box and text adapt to light or dark mode!</BodyText>
+            <BodyText color="secondary">This secondary text adapt to light or dark mode!</BodyText>
+          </Box>
+        </ScopedTheme>
+      </Flex>
+    </Box>
+  </Center>
+</UsageWrap>
+
+```tsx
+<Box backgroundColor="brand" p="400">
+  <BodyText color="inverted">This branded box and text adapt to light or dark mode!</BodyText>
+</Box>
+<Box backgroundColor="secondary" p="400">
+  <BodyText color="primary">This box and text adapt to light or dark mode!</BodyText>
+  <BodyText color="secondary">This secondary text adapt to light or dark mode!</BodyText>
+</Box>
+```
+
+By using these semantic utility props, you can ensure that your components will look great and be accessible in both light and dark
+modes without needing to write custom styles for each mode.
+
+## Use the asset libraries
+
+Hearth provides asset libraries for icons and illustrations that are designed to work well in both light and dark modes.
+When using these assets, make sure to choose the appropriate version (light or dark) based on the current colour mode.
+
+### Icons
+
+When using icons from the `@utilitywarehouse/hearth-react-native-icons` library, you can automatically handle light and dark mode
+by using the `color` prop and the `Icon` component with a semantic colour token (by default the `Icon` will use the `theme.colors.icon.primary`
+colour which adapts to light and dark mode):
+
+<UsageWrap>
+  <Center>
+    <Flex direction="row" spacing="lg">
+      <ScopedTheme name="light">
+        <Box p="400" backgroundColor="secondary">
+          <Icon as={SearchMediumIcon} />
+        </Box>
+      </ScopedTheme>
+      <ScopedTheme name="dark">
+        <Box p="400" backgroundColor="secondary">
+          <Icon as={SearchMediumIcon} color="warmWhite0" />
+        </Box>
+      </ScopedTheme>
+    </Flex>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { Icon , useTheme } from '@utilitywarehouse/hearth-react-native';
+import { SearchMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
+
+<Icon as={SearchMediumIcon} />;
+
+// Or to specify a colour
+const theme = useTheme();
+...
+<SearchMediumIcon color={theme.colors.icon.primary} />;
+```
+
+To learn more about the available icons, check out the [icon library documentation](https://hearth.prod.uw.systems/icons/?path=/docs/introduction--docs).
+
+### Illustrations
+
+When using illustrations from the `@utilitywarehouse/hearth-svg-assets` library, you'll need to import both the light and dark versions
+of the illustration and conditionally render the appropriate one based on the current colour mode.
+
+<UsageWrap>
+  <Center>
+    <Flex direction="row" spacing="lg">
+      <ScopedTheme name="light">
+        <Box p="400" backgroundColor="secondary">
+          <SceneBroadbandLight width={200} height={200} />
+        </Box>
+      </ScopedTheme>
+      <ScopedTheme name="dark">
+        <Box p="400" backgroundColor="secondary">
+          <SceneBroadbandDark width={200} height={200} />
+        </Box>
+      </ScopedTheme>
+    </Flex>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { useColorMode } from '@utilitywarehouse/hearth-react-native';
+import SceneBroadbandDark from '@utilitywarehouse/hearth-svg-assets/lib/scene-broadband-dark.svg';
+import SceneBroadbandLight from '@utilitywarehouse/hearth-svg-assets/lib/scene-broadband-light.svg';
+
+const MyComponent = () => {
+  const [colorMode] = useColorMode();
+
+  return colorMode === 'dark' ? (
+    <SceneBroadbandDark width={200} height={200} />
+  ) : (
+    <SceneBroadbandLight width={200} height={200} />
+  );
+};
+```
+
+The above example is to illustrate the concept of handling light and dark mode with illustrations,
+but you should use a reusable `ThemedImage` component to simplify this pattern, which we will cover in the next section.
+
+You can view the available illustrations in the [Hearth SVG asset library documentation](https://hearth.prod.uw.systems/assets/?path=/docs/introduction--docs).
+
+### Animations
+
+When using animations from the `@utilitywarehouse/hearth-json-assets` library, you can also import both light and dark versions of the animation.
+
+We currently only have the light variation of the animations available, but when the dark versions are added you can use a similar approach to
+the illustrations example above to conditionally render the appropriate version based on the current colour mode.
+
+You can view the available animations in the [Hearth JSON asset library documentation](https://hearth.prod.uw.systems/assets/?path=/docs/introduction--docs).
+
+## `ThemedImage` component
+
+To simplify the process of handling light and dark mode for images, you can create a reusable `ThemedImage` component that takes both light and dark versions of an image as props and automatically renders the correct one based on the current colour mode.
+Here's an example implementation of a `ThemedImage` component:
+
+<UsageWrap>
+  <Center>
+    <Flex direction="row" spacing="lg">
+      <ScopedTheme name="light">
+        <Box p="400" backgroundColor="secondary">
+          <SpotPiggyBankLight width={200} height={200} />
+        </Box>
+      </ScopedTheme>
+      <ScopedTheme name="dark">
+        <Box p="400" backgroundColor="secondary">
+          <SpotPiggyBankDark width={200} height={200} />
+        </Box>
+      </ScopedTheme>
+    </Flex>
+  </Center>
+</UsageWrap>
+
+```tsx
+import React from 'react';
+import { ThemedImage } from '@utilitywarehouse/hearth-react-native';
+import SpotPiggyBankLight from '@utilitywarehouse/hearth-svg-assets/lib/spot-piggy-bank-light.svg';
+import SpotPiggyBankDark from '@utilitywarehouse/hearth-svg-assets/lib/spot-piggy-bank-dark.svg';
+
+const MyComponent = () => {
+  return (
+    <ThemedImage
+      light={SpotPiggyBankLight}
+      dark={SpotPiggyBankDark}
+      style={{ width: 200, height: 200 }}
+    />
+  );
+};
+```
+
+See the full `ThemedImage` docs and implementation in the <StorybookLink to="utility-components-themed-image">`ThemedImage` documentation</StorybookLink>.
+
+<NextPrevPage
+  prevLink="guides-adding-shadows"
+  prevTitle="Adding Shadows"
+  nextLink="primitives-box"
+  nextTitle="Box"
+/>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utilitywarehouse/hearth-react-native",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "description": "Utility Warehouse React Native UI library",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -58,10 +58,10 @@
     "vite-plugin-svgr": "^4.5.0",
     "vitest": "^3.2.4",
     "@utilitywarehouse/hearth-fonts": "^0.0.4",
+    "@utilitywarehouse/hearth-react-icons": "^0.8.0",
     "@utilitywarehouse/hearth-react-native-icons": "^0.8.0",
     "@utilitywarehouse/hearth-svg-assets": "^0.6.0",
-    "@utilitywarehouse/hearth-tokens": "^0.2.4",
-    "@utilitywarehouse/hearth-react-icons": "^0.8.0"
+    "@utilitywarehouse/hearth-tokens": "^0.2.4"
   },
   "peerDependencies": {
     "@gorhom/bottom-sheet": ">=5.0.0",

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

@@ -12,11 +12,14 @@ import * as Stories from './Modal.stories';
 
 # Modal
 
-The `Modal` component provides a versatile dialog interface that slides up from the bottom of the screen. It's built on top of the `BottomSheetModal` component and includes pre-configured layouts for common modal patterns including headers, content areas, and action buttons.
+The `Modal` component provides a versatile dialog interface that slides up from the bottom of the screen. It's built on top of
+the <StorybookLink to="components-bottom-sheet">`BottomSheetModal`</StorybookLink>
+component and includes pre-configured layouts for common modal patterns including headers, content areas, and action buttons.
 
-The Modal component is ideal for displaying important information, collecting user input, or presenting choices that require user attention without navigating away from the current screen.
+The Modal component is ideal for displaying important information, collecting user input, or presenting choices that require user attention
+without navigating away from the current screen.
 
-If you need a modal layout inside a React Navigation modal screen, use <StorybookLink to="components-navmodal">`NavModal`</StorybookLink> instead.
+If you need a modal layout inside a React Navigation modal screen, use <StorybookLink to="components-nav-modal">`NavModal`</StorybookLink> instead.
 
 - [Playground](#playground)
 - [Usage](#usage)
@@ -32,6 +35,8 @@ If you need a modal layout inside a React Navigation modal screen, use <Storyboo
   - [Loading State](#loading-state)
   - [Without Close Button](#without-close-button)
   - [Single Action Modal](#single-action-modal)
+  - [Navigation Modals](#navigation-modals)
+  - [Close handlers and state management](#close-handlers-and-state-management)
 - [Integration Notes](#integration-notes)
 - [External Resources](#external-resources)
 
@@ -514,6 +519,53 @@ const AlertModal = () => {
 
 For React Navigation modal screens, use <StorybookLink to="components-navmodal">`NavModal`</StorybookLink>. It contains the extracted screen-based modal layout, background variants, scrollable content handling, and the Android `triggerCloseAnimation()` ref used during navigation dismissal.
 
+### Close handlers and state management
+
+The Modal component provides multiple ways to handle closing the modal and managing state:
+
+- Use the `onPressPrimaryButton`, `onPressSecondaryButton`, and `onPressCloseButton` props to run custom logic when buttons are pressed, such as form validation or API calls, before closing the modal.
+- Control whether the modal should automatically close when action buttons are pressed using the `closeOnPrimaryButtonPress` and `closeOnSecondaryButtonPress` props. This allows you to keep the modal
+  open while performing async operations and only close it when those operations are complete.
+- Use the `onChange` prop to detect when the modal is opened or closed based on the index parameter (0 for open, -1 for closed) and manage state accordingly.
+
+```tsx
+const MyModal = () => {
+  const modalRef = useRef<BottomSheetModal>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const handleSubmit = async () => {
+    setIsSubmitting(true);
+    // Simulate API call
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    setIsSubmitting(false);
+    modalRef.current?.dismiss();
+  };
+
+  return (
+    <>
+      <Button onPress={() => modalRef.current?.present()}>Open Modal</Button>
+
+      <Modal
+        ref={modalRef}
+        heading="Submit Data"
+        description="Please confirm your submission"
+        primaryButtonText="Submit"
+        secondaryButtonText="Cancel"
+        onPressPrimaryButton={handleSubmit}
+        closeOnPrimaryButtonPress={false} // Keep modal open while submitting
+        onChange={index => {
+          if (index === -1) {
+            // Modal closed, reset state if needed
+            setIsSubmitting(false);
+          }
+        }}
+        loading={isSubmitting}
+      />
+    </>
+  );
+};
+```
+
 ## Integration Notes
 
 ### BottomSheetModalProvider
@@ -567,4 +619,6 @@ modalRef.current?.snapToIndex(1);
 
 ## External Resources
 
-This component is built on top of [@gorhom/bottom-sheet](https://gorhom.github.io/react-native-bottom-sheet/) (v5). For more information about the underlying BottomSheet functionality, please refer to the [BottomSheet documentation](./BottomSheet.docs.mdx) and the [official documentation](https://gorhom.dev/react-native-bottom-sheet/).
+This component is built on top of [@gorhom/bottom-sheet](https://gorhom.github.io/react-native-bottom-sheet/) (v5). For more information about the
+underlying BottomSheet functionality, please refer to the <StorybookLink to="components-bottomsheet">BottomSheet documentation</StorybookLink> and
+the [official documentation](https://gorhom.dev/react-native-bottom-sheet/).

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

@@ -6,13 +6,13 @@ import modaliOSVideo from '../../../docs/assets/modal-ios.mp4';
 import { BackToTopButton, ViewFigmaButton } from '../../../docs/components';
 import * as Stories from './NavModal.stories';
 
-<Meta title="Components / NavModal" />
+<Meta title="Components / Nav Modal" />
 
 <ViewFigmaButton url="https://www.figma.com/design/dLI9bmyMr42LV7dtFeW27J/Hearth-Patterns---Guides?node-id=6314-9103&t=oq3NaPLaAu3di6Db-4" />
 
 <BackToTopButton />
 
-# NavModal
+# Nav Modal
 
 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.