@utilitywarehouse/hearth-react-native 0.29.1 → 0.30.0

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
 
@@ -476,6 +477,20 @@ const App = () => {
 };
 ```
 
+If your app already handles safe-area padding around modal content, you can disable Hearth's bottom-sheet safe-area spacing:
+
+```tsx
+import { BottomSheetModalProvider } from '@utilitywarehouse/hearth-react-native';
+
+const App = () => {
+  return (
+    <BottomSheetModalProvider useSafeAreaInsets={false}>
+      {/* Your app content */}
+    </BottomSheetModalProvider>
+  );
+};
+```
+
 ### Ref Usage
 
 The Modal component forwards its ref to the underlying `BottomSheetModal`, giving you access to methods like:

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

@@ -11,6 +11,7 @@ import { AccessibilityInfo, Platform, View, findNodeHandle } from 'react-native'
 import { StyleSheet } from 'react-native-unistyles';
 import { BodyText } from '../BodyText';
 import { BottomSheetModal, BottomSheetScrollView } from '../BottomSheet';
+import { useBottomSheetContext } from '../BottomSheet/BottomSheet.context';
 import { Button } from '../Button';
 import { Heading } from '../Heading';
 import { Spinner } from '../Spinner';
@@ -34,6 +35,7 @@ const Modal = ({
   closeOnSecondaryButtonPress = true,
   loading,
   loadingHeading = 'Loading...',
+  loadingDescription,
   fullscreen = false,
   image,
   primaryButtonProps,
@@ -45,6 +47,7 @@ const Modal = ({
   const bottomSheetModalRef = useRef<BottomSheetModal>(null);
   const viewRef = useRef<View>(null);
   const scrollViewRef = useRef<BottomSheetScrollViewMethods>(null);
+  const { useSafeAreaInsets } = useBottomSheetContext();
 
   useImperativeHandle(ref, () => ({
     ...(bottomSheetModalRef.current as BottomSheetModal),
@@ -105,6 +108,7 @@ const Modal = ({
     noButtons,
     stickyFooter,
     showHandle: props.showHandle,
+    useSafeAreaInsets,
   });
 
   const footer = useMemo(
@@ -148,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}
         >
@@ -156,6 +163,7 @@ const Modal = ({
           <Heading size="lg" textAlign="center">
             {loadingHeading}
           </Heading>
+          {loadingDescription ? <BodyText textAlign="center">{loadingDescription}</BodyText> : null}
         </View>
       ) : (
         <View
@@ -256,13 +264,44 @@ const styles = StyleSheet.create((theme, rt) => ({
     variants: {
       bothButtons: {
         true: {
+          paddingBottom: 166,
+        },
+        false: {
+          paddingBottom: 102,
+        },
+      },
+      noButtons: {
+        true: {
+          paddingBottom: theme.components.modal.padding,
+        },
+      },
+      stickyFooter: {
+        true: {},
+        false: {
+          paddingBottom: theme.components.modal.padding + theme.components.bottomSheet.padding,
+        },
+      },
+      useSafeAreaInsets: {
+        true: {},
+        false: {},
+      },
+    },
+    compoundVariants: [
+      {
+        bothButtons: true,
+        useSafeAreaInsets: true,
+        styles: {
           paddingBottom:
             166 +
             rt.insets.bottom -
             theme.components.modal.padding +
             theme.components.bottomSheet.padding,
         },
-        false: {
+      },
+      {
+        bothButtons: false,
+        useSafeAreaInsets: true,
+        styles: {
           paddingBottom:
             102 +
             rt.insets.bottom -
@@ -270,24 +309,27 @@ const styles = StyleSheet.create((theme, rt) => ({
             theme.components.bottomSheet.padding,
         },
       },
-      noButtons: {
-        true: {
+      {
+        noButtons: true,
+        useSafeAreaInsets: true,
+        styles: {
           paddingBottom:
             rt.insets.bottom +
             theme.components.modal.padding +
             theme.components.bottomSheet.padding,
         },
       },
-      stickyFooter: {
-        true: {},
-        false: {
+      {
+        useSafeAreaInsets: true,
+        stickyFooter: false,
+        styles: {
           paddingBottom:
             rt.insets.bottom +
             theme.components.modal.padding +
             theme.components.bottomSheet.padding,
         },
       },
-    },
+    ],
   },
   header: {
     flexDirection: 'row',
@@ -333,7 +375,16 @@ const styles = StyleSheet.create((theme, rt) => ({
   footerWrap: {
     backgroundColor: theme.color.surface.neutral.strong,
     paddingHorizontal: theme.components.bottomSheet.padding,
-    paddingBottom: theme.components.bottomSheet.padding + rt.insets.bottom,
+    variants: {
+      useSafeAreaInsets: {
+        true: {
+          paddingBottom: theme.components.bottomSheet.padding + rt.insets.bottom,
+        },
+        false: {
+          paddingBottom: theme.components.bottomSheet.padding,
+        },
+      },
+    },
   },
 }));
 

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

package/src/components/Select/Select.tsx

@@ -10,6 +10,7 @@ import {
   BottomSheetScrollView,
   BottomSheetView,
 } from '../BottomSheet';
+import { useBottomSheetContext } from '../BottomSheet/BottomSheet.context';
 import { DetailText } from '../DetailText';
 import { FormField, useFormFieldContext } from '../FormField';
 import { Icon } from '../Icon';
@@ -49,6 +50,7 @@ const Select = ({
   const isRequired = formFieldContext?.required ?? required;
   const isDisabled = formFieldContext?.disabled ?? disabled;
   const isReadonly = formFieldContext?.readonly ?? readonly;
+  const { useSafeAreaInsets } = useBottomSheetContext();
 
   const bottomSheetModalRef = useRef<BottomSheetModal>(null);
   const [search, setSearch] = useState('');
@@ -183,7 +185,7 @@ const Select = ({
             close: closeBottomSheet,
           }}
         >
-          <SafeAreaView edges={['top']} style={{ flex: 1 }}>
+          <SafeAreaView edges={useSafeAreaInsets ? ['top'] : []} style={{ flex: 1 }}>
             {menuHeading && (
               <View style={styles.headingContainer}>
                 <DetailText size="lg">{menuHeading}</DetailText>