@utilitywarehouse/hearth-react-native 0.31.0 → 0.32.0

package/docs/changelog.mdx

@@ -9,6 +9,171 @@ 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
+
+- [#1108](https://github.com/utilitywarehouse/hearth/pull/1108) [`8c2f3b5`](https://github.com/utilitywarehouse/hearth/commit/8c2f3b5334de83a7dd799b857394a34209b748e7) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE]: Add margin, padding, and layout utility props to `Flex`.
+
+  `Flex` now exposes the shared margin and padding utility props, along with the existing layout utility prop surface, so it can be used more like other layout primitives such as `Card`.
+
+  **Component affected**:
+  - `Flex`
+
+  **Developer changes**:
+
+  You can now apply spacing and layout utility props directly on `Flex`:
+
+  ```tsx
+  <Flex direction="row" spacing="md" padding="300" marginTop="200" flex={1}>
+    <Button>Back</Button>
+    <Button>Continue</Button>
+  </Flex>
+  ```
+
+- [#1104](https://github.com/utilitywarehouse/hearth/pull/1104) [`91feeab`](https://github.com/utilitywarehouse/hearth/commit/91feeab091ae6bf80e543f9196214066ce8b29b0) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE]: Add custom trigger content options to `ExpandableCard`.
+
+  `ExpandableCard` now supports a `triggerContent` prop for replacing the default trigger layout while keeping the chevron. `ExpandableCardTrigger` also now supports `children` with an optional `showChevron` prop, so you can fully compose the trigger content yourself and still opt in to the built-in expand/collapse chevron.
+
+  **Components affected**:
+  - `ExpandableCard`
+  - `ExpandableCardTrigger`
+
+  **Developer changes**:
+
+  Use `triggerContent` when you want a single prop on `ExpandableCard` to replace the standard trigger content:
+
+  ```tsx
+  <ExpandableCard
+    triggerContent={<BodyText weight="semibold">March bill ready</BodyText>}
+    expandedContent={<BodyText>Balance: £89.50</BodyText>}
+  />
+  ```
+
+  Use `ExpandableCardTrigger` children when you want full control over the trigger structure. Add `showChevron` if you still want the built-in chevron:
+
+  ```tsx
+  <ExpandableCardTrigger isExpanded={expanded} onPress={toggleExpanded} showChevron>
+    <ExpandableCardContent>
+      <ExpandableCardText>Custom trigger</ExpandableCardText>
+    </ExpandableCardContent>
+  </ExpandableCardTrigger>
+  ```
+
+- [#1109](https://github.com/utilitywarehouse/hearth/pull/1109) [`8215550`](https://github.com/utilitywarehouse/hearth/commit/8215550745d08a8b4c18a6902e39d3199018092a) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE]: Add `numberOfLines` support to `Badge` text.
+
+  `Badge` now renders its text content on a single line by default and supports a new `numberOfLines` prop when you want to allow more lines.
+
+  **Components affected**:
+  - `Badge`
+
+  **Developer changes**:
+
+  No changes are required unless you want a `Badge` to wrap onto more than one line. To opt in, pass `numberOfLines`:
+
+  ```tsx
+  <Badge numberOfLines={2} text="Long badge text that can wrap onto a second line" />
+  ```
+
+- [#1108](https://github.com/utilitywarehouse/hearth/pull/1108) [`8c2f3b5`](https://github.com/utilitywarehouse/hearth/commit/8c2f3b5334de83a7dd799b857394a34209b748e7) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE]: Add custom footer support to `Modal` and `NavModal`.
+
+  `Modal` and `NavModal` now support a `footer` prop for replacing the built-in primary and secondary action buttons with custom content, plus a `footerStyle` prop for styling the footer container. When `footer` is provided, the button props are now disallowed at the type level.
+
+  **Components affected**:
+  - `Modal`
+  - `NavModal`
+
+  **Developer changes**:
+
+  Use `footer` when you need a custom footer layout, such as horizontal actions or extra decoration:
+
+  ```tsx
+  <Modal
+    heading="Update billing details"
+    footer={
+      <Flex direction="row" spacing="md" pt="250">
+        <Button variant="outline" colorScheme="functional" style={{ flex: 1 }}>
+          Cancel
+        </Button>
+        <Button style={{ flex: 1 }}>Save changes</Button>
+      </Flex>
+    }
+    footerStyle={{
+      boxShadow: '0px -6px 12px rgba(16, 24, 40, 0.12)',
+    }}
+  />
+  ```
+
+- [#1103](https://github.com/utilitywarehouse/hearth/pull/1103) [`e375a44`](https://github.com/utilitywarehouse/hearth/commit/e375a442c507da1807e49f4d78e44edfff51d245) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE]: Add optional vertical resizing to `Textarea`.
+
+  `Textarea` now supports a new `resizable` prop that adds a bottom-right drag handle so people can increase the field height when they need more space for longer content.
+
+  **Components affected**:
+  - `Textarea`
+
+  **Developer changes**:
+
+  No changes are required unless you want to enable resizing for a textarea. To opt in, pass the new `resizable` prop:
+
+  ```tsx
+  <Textarea
+    label="Additional notes"
+    helperText="Drag the corner handle to resize"
+    placeholder="Enter your text here..."
+    resizable
+  />
+  ```
+
+- [#1108](https://github.com/utilitywarehouse/hearth/pull/1108) [`8c2f3b5`](https://github.com/utilitywarehouse/hearth/commit/8c2f3b5334de83a7dd799b857394a34209b748e7) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE]: Add flex utility props to `Container`.
+
+  `Container` now exposes shared flex layout utility props, allowing layout properties such as `flex`, `alignItems`, `justifyContent`, and `flexDirection` to be applied directly through its public prop API.
+
+  **Component affected**:
+  - `Container`
+
+  **Developer changes**:
+
+  You can now combine `Container`'s existing spacing props with flex layout props:
+
+  ```tsx
+  <Container flex={1} justifyContent="center" alignItems="stretch" gap="200">
+    <BodyText>Content</BodyText>
+  </Container>
+  ```
+
+### Patch Changes
+
+- [#1103](https://github.com/utilitywarehouse/hearth/pull/1103) [`e375a44`](https://github.com/utilitywarehouse/hearth/commit/e375a442c507da1807e49f4d78e44edfff51d245) Thanks [@jordmccord](https://github.com/jordmccord)! - 🐛 [FIX]: Render FormField optional text with regular weight instead of inheriting the label weight.
+
+  This fixes FormField labels that append `(Optional)` so the optional text no longer inherits the main label weight.
+
+  **Components affected**:
+  - `FormField`
+  - `Textarea`
+  - `Input`
+
+  **Developer changes**:
+
+  No changes are required.
+
+- [#1104](https://github.com/utilitywarehouse/hearth/pull/1104) [`91feeab`](https://github.com/utilitywarehouse/hearth/commit/91feeab091ae6bf80e543f9196214066ce8b29b0) Thanks [@jordmccord](https://github.com/jordmccord)! - 🐛 [FIX]: `ExpandableCard` heading font size and weight
+
 ## 0.30.4
 
 ### Patch 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.0",
+  "version": "0.32.0",
   "description": "Utility Warehouse React Native UI library",
   "main": "build/index.js",
   "types": "build/index.d.ts",

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/).