@utilitywarehouse/hearth-react-native 0.29.2 → 0.30.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @utilitywarehouse/hearth-react-native@0.29.2 build /home/runner/work/hearth/hearth/packages/react-native
+> @utilitywarehouse/hearth-react-native@0.30.0 build /home/runner/work/hearth/hearth/packages/react-native
 > tsc
 

package/.turbo/turbo-lint.log

@@ -1,5 +1,5 @@
 
-> @utilitywarehouse/hearth-react-native@0.29.2 lint /home/runner/work/hearth/hearth/packages/react-native
+> @utilitywarehouse/hearth-react-native@0.30.0 lint /home/runner/work/hearth/hearth/packages/react-native
 > TIMING=1 eslint .
 
 
@@ -51,15 +51,15 @@
 
 ✖ 22 problems (0 errors, 22 warnings)
 
-Rule                                     | Time (ms) | Relative
-:----------------------------------------|----------:|--------:
-@typescript-eslint/no-unused-vars        |  1520.806 |    60.5%
-react-hooks/exhaustive-deps              |   119.554 |     4.8%
-no-global-assign                         |    82.827 |     3.3%
-react-hooks/rules-of-hooks               |    73.620 |     2.9%
-no-loss-of-precision                     |    46.636 |     1.9%
-no-unexpected-multiline                  |    38.241 |     1.5%
-no-misleading-character-class            |    37.413 |     1.5%
-@typescript-eslint/no-unused-expressions |    31.682 |     1.3%
-no-useless-escape                        |    28.666 |     1.1%
-@typescript-eslint/ban-ts-comment        |    27.948 |     1.1%
+Rule                              | Time (ms) | Relative
+:---------------------------------|----------:|--------:
+@typescript-eslint/no-unused-vars |  1641.469 |    60.9%
+no-global-assign                  |    98.820 |     3.7%
+react-hooks/exhaustive-deps       |    93.179 |     3.5%
+no-unexpected-multiline           |    70.646 |     2.6%
+react-hooks/rules-of-hooks        |    65.259 |     2.4%
+@typescript-eslint/ban-ts-comment |    45.783 |     1.7%
+no-misleading-character-class     |    45.630 |     1.7%
+no-loss-of-precision              |    43.137 |     1.6%
+@typescript-eslint/no-this-alias  |    38.127 |     1.4%
+no-control-regex                  |    32.544 |     1.2%

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @utilitywarehouse/hearth-react-native
 
+## 0.30.0
+
+### Minor Changes
+
+- [#1072](https://github.com/utilitywarehouse/hearth/pull/1072) [`55f0095`](https://github.com/utilitywarehouse/hearth/commit/55f009576ba55081de358bccc21691861ddd7c33) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE]: Add `loadingDescription` support to `Modal` and `NavModal`
+
+  `Modal` and `NavModal` now accept a `loadingDescription` prop to render supporting text beneath the spinner while `loading` is true. This makes it easier to give users more context during loading states without building custom loading content.
+
+  **Components affected**:
+  - `Modal`
+  - `NavModal`
+
+  **Developer changes**:
+
+  No changes are required for existing usage. To show supporting text in a loading state, pass `loadingDescription` alongside `loading` and, if needed, `loadingHeading`.
+
+### Patch Changes
+
+- [#1070](https://github.com/utilitywarehouse/hearth/pull/1070) [`93c042c`](https://github.com/utilitywarehouse/hearth/commit/93c042c7772ab298e2ea4888a9777e8176453098) Thanks [@jordmccord](https://github.com/jordmccord)! - 🐛 [FIX]: Standardise numeric value typography across list-based components.
+
+  Numeric values in `DescriptionListItem`, `ExpandableCard`, and `ListItem` now render with semibold `BodyText` instead of `DetailText`, aligning them with the updated content hierarchy used elsewhere in the library.
+
+  **Components affected**:
+  - `DescriptionListItem`
+  - `ExpandableCard`
+  - `ListItem`
+
+  **Developer changes**:
+
+  No changes are required.
+
+- [#1073](https://github.com/utilitywarehouse/hearth/pull/1073) [`9759622`](https://github.com/utilitywarehouse/hearth/commit/975962229137dd196e5f72a04037a8f181907818) Thanks [@jordmccord](https://github.com/jordmccord)! - 🐛 [FIX]: Announce `Heading` as a header for assistive technologies.
+
+  `Heading` now sets `accessibilityRole="header"` automatically so VoiceOver and TalkBack can identify headings as part of the screen structure.
+
+  **Components affected**:
+  - `Heading`
+
+  **Developer changes**:
+
+  No changes are required.
+
+- [#1074](https://github.com/utilitywarehouse/hearth/pull/1074) [`95fe19e`](https://github.com/utilitywarehouse/hearth/commit/95fe19e6328bf652ff3ac1b2c723e1389fc59936) Thanks [@jordmccord](https://github.com/jordmccord)! - 🐛 [FIX]: Improve accessibility roles for `List`, `ListItem`, and `ListAction`
+
+  `List` now defaults to `accessibilityRole="list"`, `ListAction` now defaults to `accessibilityRole="button"`, and `ListItem` respects an explicitly provided `accessibilityRole` instead of always forcing button semantics when `onPress` is set.
+
+  **Components affected**:
+  - `List`
+  - `ListItem`
+  - `ListAction`
+
+  **Developer changes**:
+
+  No changes are required unless you want a tappable `ListItem` to be announced as something other than a button. In that case, pass `accessibilityRole` explicitly.
+
 ## 0.29.2
 
 ### Patch Changes

package/build/components/DescriptionList/DescriptionListItem.js

@@ -4,7 +4,6 @@ import { View } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
 import { useTheme } from '../../hooks';
 import { BodyText } from '../BodyText';
-import { DetailText } from '../DetailText';
 import Helper from '../Helper/Helper';
 import { useDescriptionListContext } from './DescriptionList.context';
 const DescriptionListItem = ({ heading, description, headingWidth, trailingContent, invalidText, numericValue, style, ...props }) => {
@@ -15,7 +14,7 @@ const DescriptionListItem = ({ heading, description, headingWidth, trailingConte
     const descIsText = typeof description === 'string' || typeof description === 'number';
     const combinedLabel = headingIsText && descIsText ? `${heading}: ${description}` : undefined;
     const hideDescendants = !!combinedLabel;
-    return (_jsxs(View, { accessibilityRole: "text", accessible: !!combinedLabel, accessibilityLabel: combinedLabel, ...props, style: [styles.item, style], children: [_jsxs(View, { style: styles.textWrap, importantForAccessibility: hideDescendants ? 'no-hide-descendants' : undefined, accessibilityElementsHidden: hideDescendants || undefined, children: [_jsx(View, { style: [direction === 'row' && { width: headingWidth || itemHeadingWidth }], children: headingIsText ? _jsx(BodyText, { style: styles.headingText, children: heading }) : heading }), _jsxs(View, { style: styles.descriptionWrapper, children: [descIsText ? _jsx(BodyText, { children: description }) : description, !!invalidText && (_jsx(Helper, { validationStatus: "invalid", showIcon: true, icon: ErrorCircleSmallIcon, text: invalidText || '' }))] }), numericValue ? (_jsx(View, { style: styles.descriptionWrapper, children: _jsx(DetailText, { size: "lg", children: numericValue }) })) : null] }), trailingContent ? trailingContent : null] }));
+    return (_jsxs(View, { accessibilityRole: "text", accessible: !!combinedLabel, accessibilityLabel: combinedLabel, ...props, style: [styles.item, style], children: [_jsxs(View, { style: styles.textWrap, importantForAccessibility: hideDescendants ? 'no-hide-descendants' : undefined, accessibilityElementsHidden: hideDescendants || undefined, children: [_jsx(View, { style: [direction === 'row' && { width: headingWidth || itemHeadingWidth }], children: headingIsText ? _jsx(BodyText, { style: styles.headingText, children: heading }) : heading }), _jsxs(View, { style: styles.descriptionWrapper, children: [descIsText ? _jsx(BodyText, { children: description }) : description, !!invalidText && (_jsx(Helper, { validationStatus: "invalid", showIcon: true, icon: ErrorCircleSmallIcon, text: invalidText || '' }))] }), numericValue ? (_jsx(View, { style: styles.descriptionWrapper, children: _jsx(BodyText, { weight: "semibold", children: numericValue }) })) : null] }), trailingContent ? trailingContent : null] }));
 };
 DescriptionListItem.displayName = 'DescriptionListItem';
 const styles = StyleSheet.create(theme => ({

package/build/components/ExpandableCard/ExpandableCardTriggerRoot.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { ChevronDownSmallIcon, ChevronUpSmallIcon, } from '@utilitywarehouse/hearth-react-native-icons';
 import { Pressable } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
-import { DetailText } from '../DetailText';
+import { BodyText } from '../BodyText';
 import ExpandableCardContent from './ExpandableCardContent';
 import ExpandableCardHelperText from './ExpandableCardHelperText';
 import ExpandableCardIcon from './ExpandableCardIcon';
@@ -26,7 +26,7 @@ const ExpandableCardTriggerRoot = ({ heading, helperText, leadingIcon, leadingCo
         }
         return null;
     };
-    const renderDefaultContent = () => (_jsxs(_Fragment, { children: [renderLeadingContent(), _jsxs(ExpandableCardContent, { children: [badgePosition === 'top' ? badge : null, _jsx(ExpandableCardText, { children: heading }), helperText && _jsx(ExpandableCardHelperText, { children: helperText }), badgePosition === 'bottom' ? badge : null] }), numericValue && (_jsx(DetailText, { size: "lg", style: styles.numericValue, children: numericValue })), _jsx(ExpandableCardTrailingContent, { style: styles.chevron, children: _jsx(ExpandableCardTrailingIcon, { as: isExpanded ? ChevronUpSmallIcon : ChevronDownSmallIcon }) })] }));
+    const renderDefaultContent = () => (_jsxs(_Fragment, { children: [renderLeadingContent(), _jsxs(ExpandableCardContent, { children: [badgePosition === 'top' ? badge : null, _jsx(ExpandableCardText, { children: heading }), helperText && _jsx(ExpandableCardHelperText, { children: helperText }), badgePosition === 'bottom' ? badge : null] }), !!numericValue && (_jsx(BodyText, { weight: "semibold", style: styles.numericValue, children: numericValue })), _jsx(ExpandableCardTrailingContent, { style: styles.chevron, children: _jsx(ExpandableCardTrailingIcon, { as: isExpanded ? ChevronUpSmallIcon : ChevronDownSmallIcon }) })] }));
     return (_jsx(Pressable, { ...props, testID: testID, style: [styles.container, props.style], disabled: disabled, accessibilityRole: "button", accessibilityState: { expanded: isExpanded, disabled }, accessibilityLabel: `${heading}${helperText ? `, ${helperText}` : ''}`, children: children || renderDefaultContent() }));
 };
 ExpandableCardTriggerRoot.displayName = 'ExpandableCardTriggerRoot';

package/build/components/Heading/Heading.js

@@ -12,7 +12,7 @@ const Heading = ({ children, color, size = 'lg', truncated, underline, strikeThr
         strikeThrough,
         inverted,
     });
-    return (_jsx(Text, { ...remainingProps, ...(truncated
+    return (_jsx(Text, { accessibilityRole: "header", ...remainingProps, ...(truncated
             ? {
                 numberOfLines: 1,
                 ellipsizeMode: 'tail',

package/build/components/List/List.js

@@ -6,7 +6,7 @@ import { Card } from '../Card';
 import { SectionHeader } from '../SectionHeader';
 import { ListContext } from './List.context';
 const List = ({ children, heading, helperText, headerTrailingContent, invalidText, ...props }) => {
-    const { loading, disabled, container = 'none', testID, style, ...rest } = props;
+    const { loading, disabled, container = 'none', testID, style, accessibilityRole, ...rest } = props;
     const orderRef = useRef([]);
     const [firstItemId, setFirstItemId] = useState(undefined);
     const containerToCard = {
@@ -35,7 +35,7 @@ const List = ({ children, heading, helperText, headerTrailingContent, invalidTex
         registerItem,
     };
     styles.useVariants({ disabled });
-    return (_jsx(ListContext.Provider, { value: value, children: _jsxs(View, { ...rest, style: [styles.container, style], children: [heading ? (_jsx(SectionHeader, { heading: heading, helperText: helperText, trailingContent: headerTrailingContent, invalidText: invalidText })) : null, container === 'none' ? (_jsx(View, { testID: testID, children: children })) : (React.Children.count(children) > 0 && (_jsx(Card, { ...containerToCard, noPadding: true, style: styles.card, testID: testID, children: _jsx(_Fragment, { children: children }) })))] }) }));
+    return (_jsx(ListContext.Provider, { value: value, children: _jsxs(View, { ...rest, accessibilityRole: accessibilityRole ?? 'list', style: [styles.container, style], children: [heading ? (_jsx(SectionHeader, { heading: heading, helperText: helperText, trailingContent: headerTrailingContent, invalidText: invalidText })) : null, container === 'none' ? (_jsx(View, { testID: testID, children: children })) : (React.Children.count(children) > 0 && (_jsx(Card, { ...containerToCard, noPadding: true, style: styles.card, testID: testID, children: _jsx(_Fragment, { children: children }) })))] }) }));
 };
 List.displayName = 'List';
 const styles = StyleSheet.create(theme => ({

package/build/components/List/ListAction/ListAction.js

@@ -43,7 +43,7 @@ const ListActionRoot = ({ heading, disabled, variant = 'subtle', loading, ...pro
         isFirstChild,
         container: listContext?.container,
     });
-    return (_jsx(Pressable, { ...props, testID: testID, style: [styles.container, props.style], disabled: isDisabled || !onPress, children: loading ? (_jsxs(View, { style: styles.loadingWrap, children: [_jsx(Skeleton, { style: { flex: 1, maxWidth: 166 }, width: "auto", height: 24, borderRadius: "sm" }), _jsx(Skeleton, { width: 24, height: 24, borderRadius: "sm" })] })) : (_jsxs(_Fragment, { children: [_jsx(ListActionContent, { children: _jsx(ListActionText, { children: heading }) }), _jsx(ListActionTrailingContent, { style: styles.centeredTrailingIcon, children: _jsx(ListActionTrailingIcon, { as: ChevronRightSmallIcon }) })] })) }));
+    return (_jsx(Pressable, { ...props, accessibilityRole: props.accessibilityRole ?? 'button', testID: testID, style: [styles.container, props.style], disabled: isDisabled || !onPress, children: loading ? (_jsxs(View, { style: styles.loadingWrap, children: [_jsx(Skeleton, { style: { flex: 1, maxWidth: 166 }, width: "auto", height: 24, borderRadius: "sm" }), _jsx(Skeleton, { width: 24, height: 24, borderRadius: "sm" })] })) : (_jsxs(_Fragment, { children: [_jsx(ListActionContent, { children: _jsx(ListActionText, { children: heading }) }), _jsx(ListActionTrailingContent, { style: styles.centeredTrailingIcon, children: _jsx(ListActionTrailingIcon, { as: ChevronRightSmallIcon }) })] })) }));
 };
 const ListAction = createPressable({
     Root: ListActionRoot,

package/build/components/List/ListItem/ListItemRoot.js

@@ -3,7 +3,7 @@ import { ChevronRightSmallIcon } from '@utilitywarehouse/hearth-react-native-ico
 import { useId, useLayoutEffect, useMemo } from 'react';
 import { Pressable } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
-import { DetailText } from '../../DetailText';
+import { BodyText } from '../../BodyText';
 import { Skeleton } from '../../Skeleton';
 import { useListContext } from '../List.context';
 import { ListItemContext } from './ListItem.context';
@@ -61,7 +61,7 @@ const ListItemRoot = ({ heading, helperText, leadingContent, trailingContent, di
     if (loading || listContext?.loading) {
         return (_jsxs(Pressable, { ...props, testID: loadingTestID, style: [styles.container, props.style], disabled: isDisabled, children: [leadingContent ? _jsx(Skeleton, { width: 24, height: 24 }) : null, _jsxs(ListItemContent, { children: [_jsx(Skeleton, { width: "80%", height: 20 }), _jsx(Skeleton, { width: "100%", height: 16 })] }), onPress || trailingContent ? _jsx(Skeleton, { width: 24, height: 24 }) : null] }));
     }
-    return (_jsx(ListItemContext.Provider, { value: value, children: _jsx(Pressable, { ...props, testID: testID, style: [styles.container, props.style], disabled: isDisabled, accessibilityRole: onPress ? 'button' : undefined, children: children ? (children) : (_jsxs(_Fragment, { children: [leadingContent ? (_jsx(ListItemLeadingContent, { children: leadingContent })) : null, _jsxs(ListItemContent, { children: [badgePosition === 'top' && badge ? badge : null, _jsx(ListItemHeading, { truncated: truncateHeading, children: heading }), helperText ? (_jsx(ListItemHelperText, { truncated: truncateHelperText, children: helperText })) : null, badgePosition === 'bottom' && badge ? badge : null] }), !!numericValue && _jsx(DetailText, { size: "lg", children: numericValue }), trailingContent ? (_jsx(ListItemTrailingContent, { children: trailingContent })) : onPress ? (_jsx(ListItemTrailingContent, { style: styles.centeredTrailingIcon, children: _jsx(ListItemTrailingIcon, { as: ChevronRightSmallIcon }) })) : null] })) }) }));
+    return (_jsx(ListItemContext.Provider, { value: value, children: _jsx(Pressable, { ...props, testID: testID, style: [styles.container, props.style], disabled: isDisabled, accessibilityRole: props.accessibilityRole ?? (onPress ? 'button' : undefined), children: children ? (children) : (_jsxs(_Fragment, { children: [leadingContent ? (_jsx(ListItemLeadingContent, { children: leadingContent })) : null, _jsxs(ListItemContent, { children: [badgePosition === 'top' && badge ? badge : null, _jsx(ListItemHeading, { truncated: truncateHeading, children: heading }), helperText ? (_jsx(ListItemHelperText, { truncated: truncateHelperText, children: helperText })) : null, badgePosition === 'bottom' && badge ? badge : null] }), !!numericValue && _jsx(BodyText, { weight: "semibold", children: numericValue }), trailingContent ? (_jsx(ListItemTrailingContent, { children: trailingContent })) : onPress ? (_jsx(ListItemTrailingContent, { style: styles.centeredTrailingIcon, children: _jsx(ListItemTrailingIcon, { as: ChevronRightSmallIcon }) })) : null] })) }) }));
 };
 ListItemRoot.displayName = 'ListItemRoot';
 const styles = StyleSheet.create(theme => ({

package/build/components/Modal/Modal.d.ts

@@ -3,5 +3,5 @@ import ModalProps from './Modal.props';
 type Modal<T = any> = BottomSheetModalMethods<T> & {
     triggerCloseAnimation?: () => void;
 };
-declare const Modal: ({ ref, children, heading, description, showCloseButton, primaryButtonText, secondaryButtonText, onPressPrimaryButton, onPressCloseButton, onPressSecondaryButton, closeOnPrimaryButtonPress, closeOnSecondaryButtonPress, loading, loadingHeading, fullscreen, image, primaryButtonProps, secondaryButtonProps, closeButtonProps, stickyFooter, ...props }: ModalProps) => import("react/jsx-runtime").JSX.Element;
+declare const Modal: ({ ref, children, heading, description, showCloseButton, primaryButtonText, secondaryButtonText, onPressPrimaryButton, onPressCloseButton, onPressSecondaryButton, closeOnPrimaryButtonPress, closeOnSecondaryButtonPress, loading, loadingHeading, loadingDescription, fullscreen, image, primaryButtonProps, secondaryButtonProps, closeButtonProps, stickyFooter, ...props }: ModalProps) => import("react/jsx-runtime").JSX.Element;
 export default Modal;

package/build/components/Modal/Modal.js

@@ -11,7 +11,7 @@ import { Button } from '../Button';
 import { Heading } from '../Heading';
 import { Spinner } from '../Spinner';
 import { UnstyledIconButton } from '../UnstyledIconButton';
-const Modal = ({ ref, children, heading, description, showCloseButton = true, primaryButtonText, secondaryButtonText, onPressPrimaryButton, onPressCloseButton, onPressSecondaryButton, closeOnPrimaryButtonPress = true, closeOnSecondaryButtonPress = true, loading, loadingHeading = 'Loading...', fullscreen = false, image, primaryButtonProps, secondaryButtonProps, closeButtonProps, stickyFooter = true, ...props }) => {
+const Modal = ({ ref, children, heading, description, showCloseButton = true, primaryButtonText, secondaryButtonText, onPressPrimaryButton, onPressCloseButton, onPressSecondaryButton, closeOnPrimaryButtonPress = true, closeOnSecondaryButtonPress = true, loading, loadingHeading = 'Loading...', loadingDescription, fullscreen = false, image, primaryButtonProps, secondaryButtonProps, closeButtonProps, stickyFooter = true, ...props }) => {
     const bottomSheetModalRef = useRef(null);
     const viewRef = useRef(null);
     const scrollViewRef = useRef(null);
@@ -78,7 +78,7 @@ const Modal = ({ ref, children, heading, description, showCloseButton = true, pr
         secondaryButtonProps,
         secondaryButtonText,
     ]);
-    const content = (_jsx(_Fragment, { children: loading ? (_jsxs(View, { style: styles.loadingContainer, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? 'Loading' : undefined, screenReaderFocusable: true, ref: viewRef, children: [_jsx(Spinner, { size: "lg" }), _jsx(Heading, { size: "lg", textAlign: "center", children: loadingHeading })] })) : (_jsxs(View, { style: styles.container, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? 'Modal content' : undefined, screenReaderFocusable: true, ref: viewRef, children: [_jsxs(View, { style: styles.header, children: [_jsxs(View, { style: styles.headerTextContent, children: [heading && !image ? (_jsx(Heading, { size: "lg", accessible: true, children: heading })) : null, description && !image ? _jsx(BodyText, { accessible: true, children: description }) : null] }), showCloseButton ? (_jsx(UnstyledIconButton, { icon: CloseMediumIcon, onPress: handleCloseButtonPress, accessibilityLabel: "Close modal", ...closeButtonProps })) : null] }), image ? (_jsxs(View, { style: styles.imageContainer, children: [image, _jsxs(View, { style: styles.textContent, children: [heading ? (_jsx(Heading, { size: "lg", textAlign: "center", accessible: true, children: heading })) : null, description ? (_jsx(BodyText, { textAlign: "center", accessible: true, children: description })) : null] })] })) : null, children, !stickyFooter && !noButtons ? footer : null] })) }));
+    const content = (_jsx(_Fragment, { children: loading ? (_jsxs(View, { style: styles.loadingContainer, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? (loadingHeading ?? 'Loading') : undefined, accessibilityHint: Platform.OS === 'android' && loadingDescription ? loadingDescription : undefined, screenReaderFocusable: true, ref: viewRef, children: [_jsx(Spinner, { size: "lg" }), _jsx(Heading, { size: "lg", textAlign: "center", children: loadingHeading }), loadingDescription ? _jsx(BodyText, { textAlign: "center", children: loadingDescription }) : null] })) : (_jsxs(View, { style: styles.container, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? 'Modal content' : undefined, screenReaderFocusable: true, ref: viewRef, children: [_jsxs(View, { style: styles.header, children: [_jsxs(View, { style: styles.headerTextContent, children: [heading && !image ? (_jsx(Heading, { size: "lg", accessible: true, children: heading })) : null, description && !image ? _jsx(BodyText, { accessible: true, children: description }) : null] }), showCloseButton ? (_jsx(UnstyledIconButton, { icon: CloseMediumIcon, onPress: handleCloseButtonPress, accessibilityLabel: "Close modal", ...closeButtonProps })) : null] }), image ? (_jsxs(View, { style: styles.imageContainer, children: [image, _jsxs(View, { style: styles.textContent, children: [heading ? (_jsx(Heading, { size: "lg", textAlign: "center", accessible: true, children: heading })) : null, description ? (_jsx(BodyText, { textAlign: "center", accessible: true, children: description })) : null] })] })) : null, children, !stickyFooter && !noButtons ? footer : null] })) }));
     const renderFooter = useCallback((props) => (_jsx(BottomSheetFooter, { ...props, children: _jsx(View, { style: styles.footerWrap, children: footer }) })), [footer]);
     return (_jsxs(BottomSheetModal, { ref: bottomSheetModalRef, enableDynamicSizing: true, snapPoints: image || fullscreen ? ['90%'] : props.snapPoints, showHandle: typeof loading !== 'undefined' && loading ? false : props.showHandle, accessible: false, style: styles.modal, footerComponent: stickyFooter && !noButtons ? renderFooter : undefined, ...props, onChange: handleChange, children: [loading ? _jsx(View, { style: styles.loadingTop }) : null, _jsx(BottomSheetScrollView, { contentContainerStyle: styles.scrollView, ref: scrollViewRef, children: content })] }));
 };

package/build/components/Modal/Modal.shared.types.d.ts

@@ -8,6 +8,7 @@ export interface ModalCommonProps {
     showCloseButton?: boolean;
     heading?: string;
     loadingHeading?: string;
+    loadingDescription?: string;
     description?: string;
     stickyFooter?: boolean;
     children?: ViewProps['children'];

package/build/components/NavModal/NavModal.d.ts

@@ -1,3 +1,3 @@
 import NavModalProps from './NavModal.props';
-declare const NavModal: ({ ref, children, heading, description, showCloseButton, primaryButtonText, secondaryButtonText, onPressPrimaryButton, onPressCloseButton, onPressSecondaryButton, loading, loadingHeading, image, primaryButtonProps, secondaryButtonProps, closeButtonProps, stickyFooter, background, scrollable, presentation, scrollViewProps, safeAreaViewProps, ...props }: NavModalProps) => import("react/jsx-runtime").JSX.Element;
+declare const NavModal: ({ ref, children, heading, description, showCloseButton, primaryButtonText, secondaryButtonText, onPressPrimaryButton, onPressCloseButton, onPressSecondaryButton, loading, loadingHeading, loadingDescription, image, primaryButtonProps, secondaryButtonProps, closeButtonProps, stickyFooter, background, scrollable, presentation, scrollViewProps, safeAreaViewProps, ...props }: NavModalProps) => import("react/jsx-runtime").JSX.Element;
 export default NavModal;

package/build/components/NavModal/NavModal.js

@@ -12,7 +12,7 @@ import { Button } from '../Button';
 import { Heading } from '../Heading';
 import { Spinner } from '../Spinner';
 import { UnstyledIconButton } from '../UnstyledIconButton';
-const NavModal = ({ ref, children, heading, description, showCloseButton = true, primaryButtonText, secondaryButtonText, onPressPrimaryButton, onPressCloseButton, onPressSecondaryButton, loading, loadingHeading = 'Loading...', image, primaryButtonProps, secondaryButtonProps, closeButtonProps, stickyFooter = true, background = 'default', scrollable = true, presentation = 'modal', scrollViewProps, safeAreaViewProps, ...props }) => {
+const NavModal = ({ ref, children, heading, description, showCloseButton = true, primaryButtonText, secondaryButtonText, onPressPrimaryButton, onPressCloseButton, onPressSecondaryButton, loading, loadingHeading = 'Loading...', loadingDescription, image, primaryButtonProps, secondaryButtonProps, closeButtonProps, stickyFooter = true, background = 'default', scrollable = true, presentation = 'modal', scrollViewProps, safeAreaViewProps, ...props }) => {
     const theme = useTheme();
     const backgroundOpacity = useSharedValue(0);
     const pretendContentTranslateY = useSharedValue(20);
@@ -78,7 +78,7 @@ const NavModal = ({ ref, children, heading, description, showCloseButton = true,
         secondaryButtonProps,
         secondaryButtonText,
     ]);
-    const content = (_jsx(_Fragment, { children: loading ? (_jsxs(View, { style: styles.loadingContainer, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? 'Loading' : undefined, screenReaderFocusable: true, children: [_jsx(Spinner, { size: "lg", color: isBrandBackground ? theme.color.icon.inverted : undefined }), _jsx(Heading, { size: "lg", textAlign: "center", inverted: isBrandBackground, children: loadingHeading })] })) : (_jsxs(View, { style: styles.container, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? 'Modal content' : undefined, screenReaderFocusable: true, children: [_jsxs(View, { style: styles.header, children: [_jsxs(View, { style: styles.headerTextContent, children: [heading && !image ? (_jsx(Heading, { size: "lg", accessible: true, inverted: isBrandBackground, children: heading })) : null, description && !image ? (_jsx(BodyText, { accessible: true, inverted: isBrandBackground, children: description })) : null] }), showCloseButton ? (_jsx(UnstyledIconButton, { icon: CloseMediumIcon, onPress: handleCloseButtonPress, accessibilityLabel: "Close modal", inverted: isBrandBackground, ...closeButtonProps })) : null] }), image ? (_jsxs(View, { style: styles.imageContainer, children: [image, _jsxs(View, { style: styles.textContent, children: [heading ? (_jsx(Heading, { size: "lg", textAlign: "center", accessible: true, inverted: isBrandBackground, children: heading })) : null, description ? (_jsx(BodyText, { textAlign: "center", accessible: true, inverted: isBrandBackground, children: description })) : null] })] })) : null, scrollable ? (_jsxs(ScrollView, { style: {
+    const content = (_jsx(_Fragment, { children: loading ? (_jsxs(View, { style: styles.loadingContainer, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? (loadingHeading ?? 'Loading') : undefined, accessibilityHint: Platform.OS === 'android' && loadingDescription ? loadingDescription : undefined, screenReaderFocusable: true, children: [_jsx(Spinner, { size: "lg", color: isBrandBackground ? theme.color.icon.inverted : undefined }), _jsx(Heading, { size: "lg", textAlign: "center", inverted: isBrandBackground, children: loadingHeading }), loadingDescription ? (_jsx(BodyText, { size: "md", textAlign: "center", inverted: isBrandBackground, children: loadingDescription })) : null] })) : (_jsxs(View, { style: styles.container, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? 'Modal content' : undefined, screenReaderFocusable: true, children: [_jsxs(View, { style: styles.header, children: [_jsxs(View, { style: styles.headerTextContent, children: [heading && !image ? (_jsx(Heading, { size: "lg", accessible: true, inverted: isBrandBackground, children: heading })) : null, description && !image ? (_jsx(BodyText, { accessible: true, inverted: isBrandBackground, children: description })) : null] }), showCloseButton ? (_jsx(UnstyledIconButton, { icon: CloseMediumIcon, onPress: handleCloseButtonPress, accessibilityLabel: "Close modal", inverted: isBrandBackground, ...closeButtonProps })) : null] }), image ? (_jsxs(View, { style: styles.imageContainer, children: [image, _jsxs(View, { style: styles.textContent, children: [heading ? (_jsx(Heading, { size: "lg", textAlign: "center", accessible: true, inverted: isBrandBackground, children: heading })) : null, description ? (_jsx(BodyText, { textAlign: "center", accessible: true, inverted: isBrandBackground, children: description })) : null] })] })) : null, scrollable ? (_jsxs(ScrollView, { style: {
                         flex: stickyFooter ? 1 : 0,
                         marginHorizontal: -4,
                     }, contentContainerStyle: { paddingHorizontal: 4 }, ...scrollViewProps, children: [children, !stickyFooter && !noButtons ? (_jsx(View, { style: styles.inNavModalFooterContainer, children: footer })) : null] })) : (_jsxs(View, { style: {

package/docs/changelog.mdx

@@ -9,6 +9,92 @@ 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.29.2
+
+### Patch Changes
+
+- [#1067](https://github.com/utilitywarehouse/hearth/pull/1067) [`893cbfd`](https://github.com/utilitywarehouse/hearth/commit/893cbfd1bf090b8b75df6f58f2babaf8ba1e0033) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE]: Add a `useSafeAreaInsets` prop to `BottomSheetModalProvider` to control Hearth's bottom-sheet safe-area spacing.
+
+  Bottom-sheet wrappers such as `BottomSheetView`, `BottomSheetScrollView`, `BottomSheetFlatList`, and components that render `SafeAreaView` inside a bottom sheet now respect `BottomSheetModalProvider` configuration.
+
+  **Components affected**:
+  - `BottomSheetModalProvider`
+  - `BottomSheetView`
+  - `BottomSheetScrollView`
+  - `BottomSheetFlatList`
+  - `Modal`
+  - `Select`
+  - `Combobox`
+
+  **Developer changes**:
+
+  No changes are required if you want the current behaviour. If your app already applies its own safe-area padding around bottom-sheet content, opt out like this:
+
+  ```tsx
+  <BottomSheetModalProvider useSafeAreaInsets={false}>
+    {/* Your app content */}
+  </BottomSheetModalProvider>
+  ```
+
+## 0.29.1
+
+### Patch Changes
+
+- [#1062](https://github.com/utilitywarehouse/hearth/pull/1062) [`0da3ffe`](https://github.com/utilitywarehouse/hearth/commit/0da3ffe12691a4287694ae9fcb2290d459e3c041) Thanks [@jordmccord](https://github.com/jordmccord)! - 🐛 [FIX]: Respect the selected `NavModal` background style
+
+  Fixed an issue where `NavModal` always rendered its inner content with the default surface background, which prevented the `background="brand"` treatment from being applied correctly.
+
+  **Components affected**:
+  - `NavModal`
+
+  **Developer changes**:
+
+  No changes are required.
+
+## 0.29.0
+
+### Minor Changes
+
+- [#1060](https://github.com/utilitywarehouse/hearth/pull/1060) [`05d38f9`](https://github.com/utilitywarehouse/hearth/commit/05d38f9414fec6d6b4a0733829b4d290d96fccae) Thanks [@jordmccord](https://github.com/jordmccord)! - 💔 [BREAKING CHANGE]: Extract navigation-presented modal behaviour into `NavModal`
+
+  `Modal` now only supports the bottom-sheet modal behaviour. The React Navigation screen-based API that was previously exposed through `inNavModal`, `background`, and `scrollable` has moved to the new `NavModal` component.
+
+  `NavModal` also adds a `presentation` prop so the component can match the React Navigation screen presentation style for sheet-style and full-screen modal routes.
+
+  The package-owned `SafeAreaView` component has also been removed in favour of the `react-native-safe-area-context` `SafeAreaView`. Hearth now re-exports that implementation from the package root.
+
+  **Components affected**:
+  - `Modal`
+  - `NavModal`
+  - `SafeAreaView`
+
+  **Developer changes**:
+
+  Update navigation modal screens to use `NavModal` instead of `Modal`:
+
+  ```diff
+  - import { Modal } from '@utilitywarehouse/hearth-react-native';
+  + import { NavModal, type NavModalRef } from '@utilitywarehouse/hearth-react-native';
+
+  - const modalRef = useRef<Modal>(null);
+  + const modalRef = useRef<NavModalRef>(null);
+
+  - <Modal inNavModal background="brand" scrollable={false}>
+  + <NavModal background="brand" scrollable={false} presentation="modal">
+      {/* content */}
+  - </Modal>
+  + </NavModal>
+  ```
+
+  If you are using the bottom-sheet modal API, no changes are required.
+
+  If you were importing the old component from the component path, update it to use the package root re-export or import directly from `react-native-safe-area-context`:
+
+  ```diff
+  - import { SafeAreaView } from '@utilitywarehouse/hearth-react-native';
+  + import { SafeAreaView } from 'react-native-safe-area-context';
+  ```
+
 ## 0.28.6
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utilitywarehouse/hearth-react-native",
-  "version": "0.29.2",
+  "version": "0.30.0",
   "description": "Utility Warehouse React Native UI library",
   "main": "build/index.js",
   "types": "build/index.d.ts",

package/src/components/DescriptionList/DescriptionListItem.tsx

@@ -3,7 +3,6 @@ import { View } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
 import { useTheme } from '../../hooks';
 import { BodyText } from '../BodyText';
-import { DetailText } from '../DetailText';
 import Helper from '../Helper/Helper';
 import { useDescriptionListContext } from './DescriptionList.context';
 import type DescriptionListItemProps from './DescriptionListItem.props';
@@ -55,7 +54,7 @@ const DescriptionListItem = ({
         </View>
         {numericValue ? (
           <View style={styles.descriptionWrapper}>
-            <DetailText size="lg">{numericValue}</DetailText>
+            <BodyText weight="semibold">{numericValue}</BodyText>
           </View>
         ) : null}
       </View>

package/src/components/ExpandableCard/ExpandableCardTriggerRoot.tsx

@@ -4,7 +4,7 @@ import {
 } from '@utilitywarehouse/hearth-react-native-icons';
 import { Pressable, ViewStyle } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
-import { DetailText } from '../DetailText';
+import { BodyText } from '../BodyText';
 import ExpandableCardContent from './ExpandableCardContent';
 import ExpandableCardHelperText from './ExpandableCardHelperText';
 import ExpandableCardIcon from './ExpandableCardIcon';
@@ -62,10 +62,10 @@ const ExpandableCardTriggerRoot = ({
         {helperText && <ExpandableCardHelperText>{helperText}</ExpandableCardHelperText>}
         {badgePosition === 'bottom' ? badge : null}
       </ExpandableCardContent>
-      {numericValue && (
-        <DetailText size="lg" style={styles.numericValue}>
+      {!!numericValue && (
+        <BodyText weight="semibold" style={styles.numericValue}>
           {numericValue}
-        </DetailText>
+        </BodyText>
       )}
       <ExpandableCardTrailingContent style={styles.chevron}>
         <ExpandableCardTrailingIcon as={isExpanded ? ChevronUpSmallIcon : ChevronDownSmallIcon} />

package/src/components/Heading/Heading.docs.mdx

@@ -1,7 +1,7 @@
-import { Meta, Canvas, Story, Controls, Primary } from '@storybook/addon-docs/blocks';
+import { Canvas, Controls, Meta, Primary, Story } from '@storybook/addon-docs/blocks';
+import { Box, Center, Heading, Pressable } from '../../';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
 import * as Stories from './Heading.stories';
-import { Center, Pressable, Heading, Box } from '../../';
-import { UsageWrap, BackToTopButton, ViewFigmaButton } from '../../../docs/components';
 
 <Meta title="Typography / Heading" />
 
@@ -17,6 +17,7 @@ The `Heading` component gives you the ability to create headings for your screen
 - [Usage](#usage)
 - [Props](#props)
 - [Sizes](#sizes)
+- [Accessibility](#accessibility)
 
 ## Playground
 
@@ -60,3 +61,11 @@ const MyComponent = () => <Heading>Welcome to Utility Warehouse</Heading>;
 The `Heading` component has different sizes to style the text.
 
 <Canvas of={Stories.KitchenSink} />
+
+## Accessibility
+
+`Heading` sets `accessibilityRole="header"` by default, so VoiceOver and TalkBack can announce it as a heading without any extra configuration.
+If you need to override this behavior, pass an explicit `accessibilityRole` prop (for example, `accessibilityRole="text"`) to opt out of heading semantics.
+
+- Use `Heading` for actual screen or section titles so assistive technologies can expose the right document structure.
+- If you need styled text without heading semantics, either override the `accessibilityRole` on `Heading` or use one of the other text components instead.

package/src/components/Heading/Heading.tsx

@@ -33,6 +33,7 @@ const Heading = ({
 
   return (
     <Text
+      accessibilityRole="header"
       {...remainingProps}
       {...(truncated
         ? {

package/src/components/List/List.docs.mdx

@@ -383,7 +383,7 @@ const MyComponent = () => (
       trailingContent={
         <>
           <BodyText>-£100.00</BodyText>
-          <BodyText color="textBrand">-£100.00</BodyText>
+          <BodyText color="brand">-£100.00</BodyText>
         </>
       }
       onPress={() => console.log('Transaction pressed')}
@@ -393,7 +393,7 @@ const MyComponent = () => (
       helperText="Apr 4, 2024"
       trailingContent={
         <>
-          <BodyText color="textAffirmative">+£100.00</BodyText>
+          <BodyText color="affirmative">+£100.00</BodyText>
         </>
       }
       onPress={() => console.log('Transaction pressed')}

package/src/components/List/List.stories.tsx

@@ -1,4 +1,4 @@
-import { Meta, StoryObj } from '@storybook/react-vite';
+import { Meta, StoryObj } from '@storybook/react-native';
 import {
   BillMediumIcon,
   ChevronRightSmallIcon,
@@ -60,7 +60,7 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Playground: Story = {
-  render: ({ container, ...args }) => {
+  render: ({ container, ...args }: StoryObj<typeof meta.args>) => {
     return (
       <List {...args} container={container}>
         {Array.from({ length: 4 }).map((_, index) => (
@@ -75,7 +75,7 @@ export const WithAction: Story = {
   args: {
     container: 'subtleWhite',
   },
-  render: ({ container, ...args }) => (
+  render: ({ container, ...args }: StoryObj<typeof meta.args>) => (
     <List {...args} container={container}>
       {Array.from({ length: 4 }).map((_, index) => (
         <ListItem key={index} heading="List item text" helperText="Supporting text" />
@@ -292,6 +292,7 @@ export const WithListAction: Story = {
         heading="Manage payment methods"
         helperText="Update your credit or debit cards"
         onPress={() => console.log('Manage pressed')}
+        accessibilityRole="link"
       />
       <ListAction heading="Contact support" onPress={() => console.log('Contact pressed')} />
     </List>
@@ -310,7 +311,7 @@ export const WithTransactions: Story = {
         trailingContent={
           <>
             <BodyText>-£100.00</BodyText>
-            <BodyText color="textBrand">+£1.00 CB</BodyText>
+            <BodyText color="brand">+£1.00 CB</BodyText>
           </>
         }
         onPress={() => console.log('Transaction pressed')}
@@ -320,7 +321,7 @@ export const WithTransactions: Story = {
         helperText="Apr 4, 2024"
         trailingContent={
           <>
-            <BodyText color="textAffirmative">+£100.00</BodyText>
+            <BodyText color="affirmative">+£100.00</BodyText>
           </>
         }
         onPress={() => console.log('Transaction pressed')}

package/src/components/List/List.tsx

@@ -14,7 +14,15 @@ const List = ({
   invalidText,
   ...props
 }: ListProps) => {
-  const { loading, disabled, container = 'none', testID, style, ...rest } = props;
+  const {
+    loading,
+    disabled,
+    container = 'none',
+    testID,
+    style,
+    accessibilityRole,
+    ...rest
+  } = props;
 
   const orderRef = useRef<string[]>([]);
   const [firstItemId, setFirstItemId] = useState<string | undefined>(undefined);
@@ -52,7 +60,11 @@ const List = ({
   styles.useVariants({ disabled });
   return (
     <ListContext.Provider value={value}>
-      <View {...rest} style={[styles.container, style]}>
+      <View
+        {...rest}
+        accessibilityRole={accessibilityRole ?? 'list'}
+        style={[styles.container, style]}
+      >
         {heading ? (
           <SectionHeader
             heading={heading}

package/src/components/List/ListAction/ListAction.tsx

@@ -62,6 +62,7 @@ const ListActionRoot = ({
   return (
     <Pressable
       {...props}
+      accessibilityRole={props.accessibilityRole ?? 'button'}
       testID={testID}
       style={[styles.container, props.style as ViewStyle]}
       disabled={isDisabled || !onPress}

package/src/components/List/ListItem/ListItemRoot.tsx

@@ -2,7 +2,7 @@ import { ChevronRightSmallIcon } from '@utilitywarehouse/hearth-react-native-ico
 import { useId, useLayoutEffect, useMemo } from 'react';
 import { Pressable, ViewStyle } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
-import { DetailText } from '../../DetailText';
+import { BodyText } from '../../BodyText';
 import { Skeleton } from '../../Skeleton';
 import { useListContext } from '../List.context';
 import { IListItemContext, ListItemContext } from './ListItem.context';
@@ -109,7 +109,7 @@ const ListItemRoot = ({
         testID={testID}
         style={[styles.container, props.style as ViewStyle]}
         disabled={isDisabled}
-        accessibilityRole={onPress ? 'button' : undefined}
+        accessibilityRole={props.accessibilityRole ?? (onPress ? 'button' : undefined)}
       >
         {children ? (
           children
@@ -126,7 +126,7 @@ const ListItemRoot = ({
               ) : null}
               {badgePosition === 'bottom' && badge ? badge : null}
             </ListItemContent>
-            {!!numericValue && <DetailText size="lg">{numericValue}</DetailText>}
+            {!!numericValue && <BodyText weight="semibold">{numericValue}</BodyText>}
             {trailingContent ? (
               <ListItemTrailingContent>{trailingContent}</ListItemTrailingContent>
             ) : onPress ? (

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

@@ -87,27 +87,28 @@ const MyComponent = () => {
 
 The Modal component extends the `BottomSheetModal` component and accepts all of its props, plus the following additional props:
 
-| Property                      | Type                                                               | Description                                                                                                   | Default        |
-| ----------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | -------------- |
-| `heading`                     | `string`                                                           | The heading text displayed at the top of the modal                                                            | -              |
-| `description`                 | `string`                                                           | The description text displayed below the heading                                                              | -              |
-| `showCloseButton`             | `boolean`                                                          | Whether to show the close button in the top-right corner                                                      | `true`         |
-| `primaryButtonText`           | `string`                                                           | Text for the primary action button                                                                            | -              |
-| `secondaryButtonText`         | `string`                                                           | Text for the secondary action button                                                                          | -              |
-| `onPressPrimaryButton`        | `() => void`                                                       | Callback function called when the primary button is pressed                                                   | -              |
-| `onPressSecondaryButton`      | `() => void`                                                       | Callback function called when the secondary button is pressed                                                 | -              |
-| `onPressCloseButton`          | `() => void`                                                       | Callback function called when the close button is pressed                                                     | -              |
-| `closeOnPrimaryButtonPress`   | `boolean`                                                          | Whether to automatically close the modal when the primary button is pressed                                   | `true`         |
-| `closeOnSecondaryButtonPress` | `boolean`                                                          | Whether to automatically close the modal when the secondary button is pressed                                 | `true`         |
-| `onChange`                    | `(index: number, position: number, `<br />` type: number) => void` | Callback function called when the modal's position changes \*                                                 | -              |
-| `loading`                     | `boolean`                                                          | Whether to show a loading state with spinner                                                                  | `false`        |
-| `loadingHeading`              | `string`                                                           | The heading text to be displayed when loading is true. If not provided, the regular heading will be shown.    | `'Loading...'` |
-| `image`                       | `ImageProps`                                                       | Image to display in the modal (shows as centered content with text below)                                     | -              |
-| `children`                    | `ReactNode`                                                        | Custom content to display in the modal body                                                                   | -              |
-| `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`        |
+| Property                      | Type                                                               | Description                                                                                                        | Default        |
+| ----------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | -------------- |
+| `heading`                     | `string`                                                           | The heading text displayed at the top of the modal                                                                 | -              |
+| `description`                 | `string`                                                           | The description text displayed below the heading                                                                   | -              |
+| `showCloseButton`             | `boolean`                                                          | Whether to show the close button in the top-right corner                                                           | `true`         |
+| `primaryButtonText`           | `string`                                                           | Text for the primary action button                                                                                 | -              |
+| `secondaryButtonText`         | `string`                                                           | Text for the secondary action button                                                                               | -              |
+| `onPressPrimaryButton`        | `() => void`                                                       | Callback function called when the primary button is pressed                                                        | -              |
+| `onPressSecondaryButton`      | `() => void`                                                       | Callback function called when the secondary button is pressed                                                      | -              |
+| `onPressCloseButton`          | `() => void`                                                       | Callback function called when the close button is pressed                                                          | -              |
+| `closeOnPrimaryButtonPress`   | `boolean`                                                          | Whether to automatically close the modal when the primary button is pressed                                        | `true`         |
+| `closeOnSecondaryButtonPress` | `boolean`                                                          | Whether to automatically close the modal when the secondary button is pressed                                      | `true`         |
+| `onChange`                    | `(index: number, position: number, `<br />` type: number) => void` | Callback function called when the modal's position changes \*                                                      | -              |
+| `loading`                     | `boolean`                                                          | Whether to show a loading state with spinner                                                                       | `false`        |
+| `loadingHeading`              | `string`                                                           | The heading text to be displayed when loading is true. If not provided, the regular heading will be shown.         | `'Loading...'` |
+| `loadingDescription`          | `string`                                                           | The description text to be displayed when loading is true. If not provided, the regular description will be shown. | -              |
+| `image`                       | `ImageProps`                                                       | Image to display in the modal (shows as centered content with text below)                                          | -              |
+| `children`                    | `ReactNode`                                                        | Custom content to display in the modal body                                                                        | -              |
+| `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`        |
 
 \* use this to detect if the modal has been opened or closed, index 0 indicates open state and -1 indicates closed state
 

package/src/components/Modal/Modal.shared.types.ts

@@ -9,6 +9,7 @@ export interface ModalCommonProps {
   showCloseButton?: boolean;
   heading?: string;
   loadingHeading?: string;
+  loadingDescription?: string;
   description?: string;
   stickyFooter?: boolean;
   children?: ViewProps['children'];

package/src/components/Modal/Modal.tsx

@@ -35,6 +35,7 @@ const Modal = ({
   closeOnSecondaryButtonPress = true,
   loading,
   loadingHeading = 'Loading...',
+  loadingDescription,
   fullscreen = false,
   image,
   primaryButtonProps,
@@ -151,7 +152,10 @@ const Modal = ({
         <View
           style={styles.loadingContainer}
           accessible={Platform.OS === 'android' ? true : undefined}
-          accessibilityLabel={Platform.OS === 'android' ? 'Loading' : undefined}
+          accessibilityLabel={Platform.OS === 'android' ? (loadingHeading ?? 'Loading') : undefined}
+          accessibilityHint={
+            Platform.OS === 'android' && loadingDescription ? loadingDescription : undefined
+          }
           screenReaderFocusable
           ref={viewRef}
         >
@@ -159,6 +163,7 @@ const Modal = ({
           <Heading size="lg" textAlign="center">
             {loadingHeading}
           </Heading>
+          {loadingDescription ? <BodyText textAlign="center">{loadingDescription}</BodyText> : null}
         </View>
       ) : (
         <View

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

@@ -150,6 +150,7 @@ const styles = StyleSheet.create({
 | `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...'` |
+| `loadingDescription`     | `string`                                                                                                         | Supporting text shown below the heading while `loading` is true.                                                                              | -              |
 | `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`         |

package/src/components/NavModal/NavModal.tsx

@@ -32,6 +32,7 @@ const NavModal = ({
   onPressSecondaryButton,
   loading,
   loadingHeading = 'Loading...',
+  loadingDescription,
   image,
   primaryButtonProps,
   secondaryButtonProps,
@@ -162,13 +163,21 @@ const NavModal = ({
         <View
           style={styles.loadingContainer}
           accessible={Platform.OS === 'android' ? true : undefined}
-          accessibilityLabel={Platform.OS === 'android' ? 'Loading' : undefined}
+          accessibilityLabel={Platform.OS === 'android' ? (loadingHeading ?? 'Loading') : undefined}
+          accessibilityHint={
+            Platform.OS === 'android' && loadingDescription ? loadingDescription : undefined
+          }
           screenReaderFocusable
         >
           <Spinner size="lg" color={isBrandBackground ? theme.color.icon.inverted : undefined} />
           <Heading size="lg" textAlign="center" inverted={isBrandBackground}>
             {loadingHeading}
           </Heading>
+          {loadingDescription ? (
+            <BodyText size="md" textAlign="center" inverted={isBrandBackground}>
+              {loadingDescription}
+            </BodyText>
+          ) : null}
         </View>
       ) : (
         <View