@utilitywarehouse/hearth-react-native 0.31.1 → 0.32.1

package/docs/components/AllComponents.web.tsx

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utilitywarehouse/hearth-react-native",
-  "version": "0.31.1",
+  "version": "0.32.1",
   "description": "Utility Warehouse React Native UI library",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -33,6 +33,7 @@
     "@storybook/addon-vitest": "^10.2.1",
     "@storybook/react-native-web-vite": "^10.2.1",
     "@types/prismjs": "^1.26.5",
+    "@types/react-dom": "^19.1.6",
     "@types/react": "^19.1.10",
     "@vitest/browser": "^3.2.4",
     "@vitest/coverage-v8": "^3.2.4",
@@ -41,6 +42,7 @@
     "playwright": "^1.55.1",
     "prismjs": "^1.30.0",
     "react": "^19.1.0",
+    "react-dom": "^19.1.0",
     "react-native": "0.80.0",
     "react-native-edge-to-edge": "1.6.1",
     "react-native-gesture-handler": "2.28.0",
@@ -58,10 +60,10 @@
     "vite-plugin-svgr": "^4.5.0",
     "vitest": "^3.2.4",
     "@utilitywarehouse/hearth-fonts": "^0.0.4",
+    "@utilitywarehouse/hearth-react-icons": "^0.8.0",
     "@utilitywarehouse/hearth-react-native-icons": "^0.8.0",
     "@utilitywarehouse/hearth-svg-assets": "^0.6.0",
-    "@utilitywarehouse/hearth-tokens": "^0.2.4",
-    "@utilitywarehouse/hearth-react-icons": "^0.8.0"
+    "@utilitywarehouse/hearth-tokens": "^0.2.4"
   },
   "peerDependencies": {
     "@gorhom/bottom-sheet": ">=5.0.0",
@@ -86,7 +88,7 @@
     "watch": "tsc --watch",
     "figma:create": "figma connect create",
     "figma:publish": "figma connect publish",
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "vitest run --config vitest.unit.config.ts",
     "test:storybook": "vitest run --project storybook",
     "dev": "npm run copyChangelog && storybook dev -p 6006",
     "dev:docs": "storybook dev -p 6002 --no-open --docs",

package/src/components/Banner/Banner.stories.tsx

@@ -55,6 +55,7 @@ const meta = {
         'insurance',
         'cashback',
         'pig',
+        'highlight',
       ],
     },
     iconContainerVariant: {
@@ -548,6 +549,19 @@ export const ColorSchemes: Story = {
               </Button>
             }
           />
+          <Banner
+            icon={HomeMediumIcon}
+            iconContainerColor="highlight"
+            iconContainerVariant="emphasis"
+            colorScheme="highlight"
+            heading="Highlight Yellow"
+            description="Banner with highlight color scheme."
+            button={
+              <Button size="sm" onPress={() => console.log('Action pressed')}>
+                Action
+              </Button>
+            }
+          />
         </Flex>
       </View>
     );

package/src/components/Card/Card.docs.mdx

@@ -61,23 +61,22 @@ const MyComponent = () => (
 
 ## Props
 
-| Property       | Type                                                                                                                                         | Description                                | Default           |
-| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ----------------- |
-| variant        | `'subtle' \| 'emphasis' `                                                                                                                    | The variant of the card.                   | `'subtle'`        |
-| colorScheme    | `'neutralStrong' \| 'neutralSubtle' \| 'purple' \| 'energy'` <br /> `'broadband' \| 'mobile' \| 'insurance' \| 'cashback' \|` <br /> `'pig'` | The color scheme of the card.              | `'neutralStrong'` |
-| shadowColor    | `'functional' \| 'brand' \| 'energy' \| 'broadband' \| 'mobile' `<br /> `'insurance' \| 'cashback' \| 'pig'`                                 | The shadow color of the card.              | `-`               |
-| noPadding      | `boolean`                                                                                                                                    | Whether or not the card has padding.       | `false`           |
-| selected       | `boolean`                                                                                                                                    | Whether the card is selected.              | `false`           |
-| onPress        | `() => void`                                                                                                                                 | Callback function to be called.            | `-`               |
-| disabled       | `boolean`                                                                                                                                    | Whether the card is disabled.              | `false`           |
-| spacing          | `'none' \| '2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`                                                                           | The space between the content.             | `none`            |
-| alignItems     | `'flex-start' \| 'flex-end' \| `<br />`'center' \| 'stretch' \| 'baseline'`                                                                  | The align items of the flex container.     | `flex-start`      |
-| justifyContent | `'flex-start' \| 'flex-end' \| 'center' \| 'space-between' \| `<br />` 'space-around' \| 'space-evenly'`                                     | The justify content of the flex container. | `flex-start`      |
-| flexWrap       | `'wrap' \| 'nowrap' \| 'wrap-reverse'`                                                                                                       | The wrap of the flex container.            | `nowrap`          |
-| flexDirection  | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'`                                                                                     | The direction of the flex container.       | `column`          |
-| gap            | `number`                                                                                                                                     | The gap between the content.               | `0`               |
-| rowGap         | `number`                                                                                                                                     | The row gap between the content.           | `0`               |
-| columnGap      | `number`                                                                                                                                     | The column gap between the content.        | `0`               |
+| Property       | Type                                                                                                                                                        | Description                                | Default           |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ----------------- |
+| variant        | `'subtle' \| 'emphasis' `                                                                                                                                   | The variant of the card.                   | `'subtle'`        |
+| colorScheme    | `'neutralStrong' \| 'neutralSubtle' \| 'brand' \| 'energy'` <br /> `'broadband' \| 'mobile' \| 'insurance' \| 'cashback' \|` <br /> `'highlight' \| 'pig'` | The color scheme of the card.              | `'neutralStrong'` |
+| shadowColor    | `'functional' \| 'brand' \| 'energy' \| 'broadband' \| 'mobile' `<br /> `'insurance' \| 'cashback' \| 'pig'`                                                | The shadow color of the card.              | `-`               |
+| noPadding      | `boolean`                                                                                                                                                   | Whether or not the card has padding.       | `false`           |
+| onPress        | `() => void`                                                                                                                                                | Callback function to be called.            | `-`               |
+| disabled       | `boolean`                                                                                                                                                   | Whether the card is disabled.              | `false`           |
+| spacing        | `'none' \| '2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`                                                                                          | The space between the content.             | `none`            |
+| alignItems     | `'flex-start' \| 'flex-end' \| `<br />`'center' \| 'stretch' \| 'baseline'`                                                                                 | The align items of the flex container.     | `flex-start`      |
+| justifyContent | `'flex-start' \| 'flex-end' \| 'center' \| 'space-between' \| `<br />` 'space-around' \| 'space-evenly'`                                                    | The justify content of the flex container. | `flex-start`      |
+| flexWrap       | `'wrap' \| 'nowrap' \| 'wrap-reverse'`                                                                                                                      | The wrap of the flex container.            | `nowrap`          |
+| flexDirection  | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'`                                                                                                    | The direction of the flex container.       | `column`          |
+| gap            | `number`                                                                                                                                                    | The gap between the content.               | `0`               |
+| rowGap         | `number`                                                                                                                                                    | The row gap between the content.           | `0`               |
+| columnGap      | `number`                                                                                                                                                    | The column gap between the content.        | `0`               |
 
 ### `CardPressHandler` Props
 

package/src/components/Card/Card.props.ts

@@ -10,6 +10,7 @@ interface CardProps
     | 'brand'
     | 'energy'
     | 'broadband'
+    | 'highlight'
     | 'mobile'
     | 'insurance'
     | 'cashback'