@utilitywarehouse/hearth-react-native 0.10.0 → 0.12.0

package/build/utils/index.js

@@ -1,8 +1,10 @@
 export { default as coloursAsArray, extractLightColorValues } from './coloursAsArray';
 export { default as formatThousands } from './formatThousands';
 export { default as getFlattenedColorValue } from './getFlattenedColorValue';
+export { getInitials } from './getInitials';
 export { default as getStyleValue } from './getStyleValue';
 export { default as hexWithOpacity } from './hexWithOpacity';
 export { default as isEqual } from './isEqual';
+export { default as isThemedImageProps } from './isThemedImageProps';
 export * from './styleUtils';
 export * from './themeValueHelpers';

package/build/utils/isThemedImageProps.d.ts

@@ -0,0 +1,4 @@
+import { ImageProps } from 'react-native';
+import { ThemedImageProps } from 'src/components';
+declare const isThemedImageProps: (props: ThemedImageProps | ImageProps) => props is ThemedImageProps;
+export default isThemedImageProps;

package/build/utils/isThemedImageProps.js

@@ -0,0 +1,4 @@
+const isThemedImageProps = (props) => {
+    return 'light' in props && 'dark' in props;
+};
+export default isThemedImageProps;

package/docs/components/AllComponents.web.tsx

@@ -23,6 +23,7 @@ import {
   Accordion,
   AccordionItem,
   Alert,
+  Avatar,
   Badge,
   Banner,
   BodyText,
@@ -39,6 +40,7 @@ import {
   Checkbox,
   Container,
   CurrencyInput,
+  DateInput,
   DatePicker,
   DatePickerInput,
   DateType,
@@ -196,6 +198,11 @@ const AllComponents: React.FC = () => {
               <Alert text="This is an alert" />
             </Center>
           </ComponentWrapper>
+          <ComponentWrapper name="Avatar" link="/?path=/docs/components-avatar--docs">
+            <Center flex={1} gap="200">
+              <Avatar name="John Doe" />
+            </Center>
+          </ComponentWrapper>
           <ComponentWrapper name="Badge" link="/?path=/docs/components-badge--docs">
             <Center gap="200" flex={1}>
               <View>
@@ -340,6 +347,11 @@ const AllComponents: React.FC = () => {
               <CurrencyInput />
             </Center>
           </ComponentWrapper>
+          <ComponentWrapper name="Date Input" link="/?path=/docs/forms-date-input--docs">
+            <Center flex={1} padding="200">
+              <DateInput />
+            </Center>
+          </ComponentWrapper>
           <ComponentWrapper name="Date Picker" link="/?path=/docs/components-date-picker--docs">
             <Center flex={1}>
               <Button onPress={handleDatePickerOpenPress}>Open Date Picker</Button>
@@ -635,7 +647,12 @@ const AllComponents: React.FC = () => {
               {(() => {
                 const [pillValue, setPillValue] = React.useState<string[]>(['energy', 'mobile']);
                 return (
-                  <PillGroup value={pillValue} onChange={v => setPillValue(v as string[])} wrap={false} multiple>
+                  <PillGroup
+                    value={pillValue}
+                    onChange={v => setPillValue(v as string[])}
+                    wrap={false}
+                    multiple
+                  >
                     <Pill value="all" label="All" />
                     <Pill value="energy" label="Energy" icon={ElectricityMediumIcon} />
                     <Pill value="broadband" label="Broadband" icon={BroadbandMediumIcon} />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utilitywarehouse/hearth-react-native",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Utility Warehouse React Native UI library",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -60,7 +60,7 @@
     "@utilitywarehouse/hearth-react-icons": "^0.7.4",
     "@utilitywarehouse/hearth-react-native-icons": "^0.7.4",
     "@utilitywarehouse/hearth-svg-assets": "^0.2.0",
-    "@utilitywarehouse/hearth-tokens": "^0.2.0"
+    "@utilitywarehouse/hearth-tokens": "^0.2.1"
   },
   "peerDependencies": {
     "@gorhom/bottom-sheet": "^5.0.0",

package/src/components/Avatar/Avatar.docs.mdx

@@ -0,0 +1,105 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { Avatar, Box, Center } from '../..';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './Avatar.stories';
+
+<Meta title="Components / Avatar" />
+
+<BackToTopButton />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components-%26-Tokens?node-id=1%3A148" />
+
+# Avatar
+
+Avatars help humanise the product experience by connecting users with the product and to each other.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Accessibility](#accessibility)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+### Icon
+
+The icon variant is the default `Avatar` type. It ensures UI remains balanced and visually complete, even with limited data.
+
+<UsageWrap>
+  <Center>
+    <Box>
+      <Avatar />
+    </Box>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { Avatar } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => <Avatar />;
+```
+
+### Initials
+
+The initials variant can be used when a profile image is not available, but you have the user's name.
+
+<UsageWrap>
+  <Center>
+    <Box>
+      <Avatar name="Jane Doe" />
+    </Box>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { Avatar } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => <Avatar name="Jane Doe" />;
+```
+
+### Image
+
+The image variant is available to use in journeys where a user is able to upload their own profile picture.
+
+<UsageWrap>
+  <Center>
+    <Box>
+      <Avatar
+        name="Jane Doe"
+        src={{ uri: 'https://ca.slack-edge.com/T0HR00WDA-U05SHRATW7Q-3ad4ae7c75b8-512' }}
+      />
+    </Box>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { Avatar } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <Avatar
+    name="Jane Doe"
+    src={{ uri: 'https://ca.slack-edge.com/T0HR00WDA-U05SHRATW7Q-3ad4ae7c75b8-512' }}
+  />
+);
+```
+
+## Props
+
+| Property                | Type                                                       | Description                                                                          | Default |
+| ----------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------- |
+| `src`                   | `ImageSourcePropType`                                      | The image source to display.                                                         |         |
+| `name`                  | `string`                                                   | The name associated with the avatar, used for creating initials and accessibility.   |         |
+| `size`                  | `'sm' \| 'md'`                                             | Sets the avatar size.                                                                | `md`    |
+| `delayMs`               | `number`                                                   | Delay in milliseconds before the image is rendered to avoid flickering.              | `0`     |
+| `onLoadingStatusChange` | `(status: 'idle' \| 'loading' \| 'loaded' \| 'error') => void` | Callback fired when the loading status of the image changes.                         |         |
+
+## Accessibility
+
+When passing a user image to the `src` prop, you should also pass their name to the `name` prop so it can be used as an accessible description for the image.
+
+If the image fails to load, the component will automatically fall back to displaying the initials (if `name` is provided) or the default user icon.

package/src/components/Avatar/Avatar.props.ts

@@ -0,0 +1,31 @@
+import type { ImageSourcePropType, ViewProps } from 'react-native';
+
+export type AvatarLoadingStatus = 'idle' | 'loading' | 'loaded' | 'error';
+
+interface AvatarProps extends ViewProps {
+  /**
+   * The image source to display.
+   */
+  src?: ImageSourcePropType;
+  /**
+   * The name associated with the avatar, used for creating initials and accessibility label.
+   */
+  name?: string;
+  /**
+   * Sets the avatar size.
+   * @default md
+   */
+  size?: 'sm' | 'md';
+  /**
+   * Delay in milliseconds before the image is rendered.
+   * Useful to prevent flickering when the image loads very quickly.
+   * @default 0
+   */
+  delayMs?: number;
+  /**
+   * Callback fired when the loading status of the image changes.
+   */
+  onLoadingStatusChange?: (status: AvatarLoadingStatus) => void;
+}
+
+export default AvatarProps;

package/src/components/Avatar/Avatar.stories.tsx

@@ -0,0 +1,77 @@
+import { Meta, StoryObj } from '@storybook/react-vite';
+import React from 'react';
+import { Avatar } from '.';
+import { Flex } from '../Flex';
+import { VariantTitle } from '../../../docs/components';
+
+const meta = {
+  title: 'Stories / Avatar',
+  component: Avatar,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    size: {
+      options: ['sm', 'md'],
+      control: 'radio',
+      description: 'Size of the avatar.',
+    },
+    name: {
+      control: 'text',
+      description: 'Name used for initials and accessibility.',
+    },
+    src: {
+      control: 'object',
+      description: 'Image source object (e.g. { uri: "..." }).',
+    },
+    delayMs: {
+      control: 'number',
+      description: 'Delay in ms before showing the fallback.',
+    },
+  },
+  args: {
+    size: 'md',
+  },
+} satisfies Meta<typeof Avatar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  args: {
+    name: 'Jane Doe',
+    src: { uri: 'https://ca.slack-edge.com/T0HR00WDA-U05SHRATW7Q-3ad4ae7c75b8-512' },
+  },
+};
+
+export const Icon: Story = {};
+
+export const Initials: Story = {
+  args: {
+    name: 'Jane Doe',
+  },
+};
+
+export const Image: Story = {
+  args: {
+    name: 'Jane Doe',
+    src: { uri: 'https://ca.slack-edge.com/T0HR00WDA-U05SHRATW7Q-3ad4ae7c75b8-512' },
+  },
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <Flex direction="row" space="xl" align="center">
+      <Flex direction="column" space="md" align="center">
+        <VariantTitle title="SM">
+          <Avatar size="sm" name="Jane Doe" />
+        </VariantTitle>
+      </Flex>
+      <Flex direction="column" space="md" align="center">
+        <VariantTitle title="MD">
+          <Avatar size="md" name="Jane Doe" />
+        </VariantTitle>
+      </Flex>
+    </Flex>
+  ),
+};

package/src/components/Avatar/Avatar.tsx

@@ -0,0 +1,136 @@
+import { UserMediumIcon, UserSmallIcon } from '@utilitywarehouse/hearth-react-native-icons';
+import { useEffect, useState } from 'react';
+import { Image, View } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { useTheme } from '../../hooks';
+import { getInitials } from '../../utils';
+import BodyText from '../BodyText/BodyText';
+import AvatarProps, { AvatarLoadingStatus } from './Avatar.props';
+
+const Avatar = ({
+  src,
+  name,
+  size = 'md',
+  delayMs = 0,
+  onLoadingStatusChange,
+  style,
+  ...props
+}: AvatarProps) => {
+  const [status, setStatus] = useState<AvatarLoadingStatus>('idle');
+  const [isDelayed, setIsDelayed] = useState(delayMs > 0);
+  const { components } = useTheme();
+
+  useEffect(() => {
+    if (!src) {
+      setStatus('idle');
+      return;
+    }
+
+    setStatus('loading');
+  }, [src]);
+
+  useEffect(() => {
+    onLoadingStatusChange?.(status);
+  }, [status, onLoadingStatusChange]);
+
+  useEffect(() => {
+    if (delayMs <= 0) {
+      setIsDelayed(false);
+      return;
+    }
+
+    const timerId = setTimeout(() => {
+      setIsDelayed(false);
+    }, delayMs);
+    return () => clearTimeout(timerId);
+  }, [delayMs]);
+
+  styles.useVariants({ size });
+
+  const initials = getInitials(name);
+
+  const handleLoad = () => setStatus('loaded');
+  const handleError = () => setStatus('error');
+
+  const showImage = src && status === 'loaded';
+  const showFallback = !showImage && !isDelayed;
+
+  const textSize = size === 'sm' ? 'md' : 'lg';
+  const FallbackIcon = size === 'sm' ? UserSmallIcon : UserMediumIcon;
+
+  return (
+    <View
+      {...props}
+      style={[styles.container, style]}
+      accessibilityRole={showImage && name ? 'image' : undefined}
+      accessibilityLabel={showImage ? name : undefined}
+    >
+      {src && (
+        <Image
+          source={src}
+          style={styles.image}
+          onLoad={handleLoad}
+          onError={handleError}
+          accessibilityElementsHidden
+        />
+      )}
+      {showFallback && (
+        <View style={styles.fallback}>
+          {name ? (
+            <BodyText
+              size={textSize}
+              weight="semibold"
+              textTransform="uppercase"
+              style={styles.text}
+            >
+              {initials}
+            </BodyText>
+          ) : (
+            <FallbackIcon />
+          )}
+        </View>
+      )}
+    </View>
+  );
+};
+
+Avatar.displayName = 'Avatar';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    justifyContent: 'center',
+    alignItems: 'center',
+    overflow: 'hidden',
+    backgroundColor: theme.color.surface.pig.subtle,
+    variants: {
+      size: {
+        sm: {
+          width: theme.components.avatar.sm.width,
+          height: theme.components.avatar.sm.height,
+          borderRadius: theme.components.avatar.sm.borderRadius,
+        },
+        md: {
+          width: theme.components.avatar.md.width,
+          height: theme.components.avatar.md.height,
+          borderRadius: theme.components.avatar.md.borderRadius,
+        },
+      },
+    },
+  },
+  image: {
+    width: '100%',
+    height: '100%',
+    position: 'absolute',
+  },
+  fallback: {
+    width: '100%',
+    height: '100%',
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  text: {
+    color: theme.color.text.primary,
+  },
+}));
+
+export default Avatar;

package/src/components/Avatar/index.ts

@@ -0,0 +1,2 @@
+export { default as Avatar } from './Avatar';
+export type { default as AvatarProps, AvatarLoadingStatus } from './Avatar.props';

package/src/components/Banner/Banner.context.ts

@@ -0,0 +1,11 @@
+import { createContext, useContext } from 'react';
+
+const BannerContext = createContext<{ direction: 'horizontal' | 'vertical' }>({
+  direction: 'horizontal',
+});
+
+export const useBannerContext = () => {
+  return useContext(BannerContext);
+};
+
+export default BannerContext;

package/src/components/Banner/Banner.docs.mdx

@@ -63,26 +63,39 @@ const MyComponent = () => (
 
 ## Props
 
-| Property             | Type                                                                                               | Description                                                            | Default        |
-| -------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -------------- |
-| icon                 | `ComponentType`                                                                                    | Icon component to display (mutually exclusive with image/illustration) | `-`            |
-| iconContainerVariant | `'subtle' \| 'emphasis'`                                                                           | Icon container visual style                                            | `'subtle'`     |
-| iconContainerSize    | `'sm' \| 'md' \| 'lg'`                                                                             | Icon container size                                                    | `'md'`         |
-| iconContainerColor   | `'pig' \| 'energy' \| 'broadband' \| 'mobile' \|` <br />`'insurance' \| 'cashback' \| 'highlight'` | Icon container color scheme                                            | `'pig'`        |
-| illustration         | `ThemedImageProps \| ImageProps`                                                                   | Themed illustration object (mutually exclusive with icon/image)        | `-`            |
-| image                | `ThemedImageProps \| ImageProps`                                                                   | Themed image object (mutually exclusive with icon/illustration)        | `-`            |
-| heading              | `string`                                                                                           | Heading text                                                           | `-` (required) |
-| description          | `string`                                                                                           | Description text                                                       | `-` (required) |
-| direction            | `'horizontal' \| 'vertical'`                                                                       | Layout direction for icon/image and content                            | `'horizontal'` |
-| link                 | `ReactNode`                                                                                        | Link element to display                                                | `-`            |
-| button               | `ReactNode`                                                                                        | Button element to display                                              | `-`            |
-| onPress              | `() => void`                                                                                       | Makes the entire banner pressable (shows chevron)                      | `-`            |
-| onClose              | `() => void`                                                                                       | Shows close button with handler                                        | `-`            |
-| variant              | `'subtle' \| 'emphasis'`                                                                           | Card visual style variant                                              | `'subtle'`     |
-| colorScheme          | `'pig' \| 'energy' \| 'broadband' \| 'mobile' \|` <br />`'insurance' \| 'cashback' \| 'highlight'` | Color scheme for buttons                                               | `'pig'`        |
+| Property             | Type                                                                                               | Description                                                             | Default        |
+| -------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------- |
+| icon                 | `ComponentType`                                                                                    | Icon component to display (mutually exclusive with image/illustration)  | `-`            |
+| iconContainerVariant | `'subtle' \| 'emphasis'`                                                                           | Icon container visual style                                             | `'subtle'`     |
+| iconContainerSize    | `'sm' \| 'md' \| 'lg'`                                                                             | Icon container size                                                     | `'md'`         |
+| iconContainerColor   | `'pig' \| 'energy' \| 'broadband' \| 'mobile' \|` <br />`'insurance' \| 'cashback' \| 'highlight'` | Icon container color scheme                                             | `'pig'`        |
+| illustration         | `ReactNode`                                                                                        | The illustration element to render (mutually exclusive with icon/image) | `-`            |
+| image                | `ReactNode`                                                                                        | The image element to render (mutually exclusive with icon/illustration) | `-`            |
+| heading              | `string`                                                                                           | Heading text                                                            | `-` (required) |
+| description          | `string`                                                                                           | Description text                                                        | `-` (required) |
+| direction            | `'horizontal' \| 'vertical'`                                                                       | Layout direction for icon/image and content                             | `'horizontal'` |
+| link                 | `ReactNode`                                                                                        | Link element to display                                                 | `-`            |
+| button               | `ReactNode`                                                                                        | Button element to display                                               | `-`            |
+| onPress              | `() => void`                                                                                       | Makes the entire banner pressable (shows chevron)                       | `-`            |
+| onClose              | `() => void`                                                                                       | Shows close button with handler                                         | `-`            |
+| variant              | `'subtle' \| 'emphasis'`                                                                           | Card visual style variant                                               | `'subtle'`     |
+| colorScheme          | `'pig' \| 'energy' \| 'broadband' \| 'mobile' \|` <br />`'insurance' \| 'cashback' \| 'highlight'` | Color scheme for buttons                                                | `'pig'`        |
 
 The component also accepts all standard Card props except `noPadding`, `space`, `gap`, `rowGap`, `columnGap`, `flexDirection`, `flexWrap`, `alignItems`, and `justifyContent`.
 
+### `BannerImage` & `BannerIllustration` Props
+
+The `BannerImage` & `BannerIllustration` component can be used to display an image within the Banner. It accepts the following props:
+
+| Property  | Type                  | Description                                                              |
+| --------- | --------------------- | ------------------------------------------------------------------------ |
+| `source`  | `ImageSourcePropType` | The source of the image to display                                       |
+| `light`   | `ImageSourcePropType` | The source of the image to display in light mode (use instead of source) |
+| `dark`    | `ImageSourcePropType` | The source of the image to display in dark mode (use instead of source)  |
+| `...rest` | `ImageProps`          | Additional props to pass to the underlying Image component               |
+
+For more details about the ThemedImage component used internally, refer to the [`ThemedImage` documentation](/docs/utility-components-themed-image--docs).
+
 ## Layout Options
 
 ### Horizontal Layout (Default)
@@ -153,22 +166,28 @@ Display a themed image that automatically switches between light and dark modes:
 <Canvas of={Stories.WithImage} />
 
 ```jsx
-import { Banner } from '@utilitywarehouse/hearth-react-native';
+import { Banner, BannerImage } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => (
   <>
     <Banner
-      image={{
-        source: { uri: 'https://example.com/image.jpg' },
-      }}
+      image={
+        <BannerImage
+          source={{
+            uri: 'https://example.com/image.jpg',
+          }}
+        />
+      }
       heading="Featured Content"
       description="Discover amazing content curated just for you."
     />
     <Banner
-      image={{
-        light: { uri: 'https://example.com/light-image.jpg' },
-        dark: { uri: 'https://example.com/dark-image.jpg' },
-      }}
+      image={
+        <BannerImage
+          light={{ uri: 'https://example.com/light-image.jpg' }}
+          dark={{ uri: 'https://example.com/dark-image.jpg' }}
+        />
+      }
       heading="Featured Content"
       description="Discover amazing content curated just for you."
     />
@@ -183,18 +202,15 @@ Display a themed illustration that adapts to layout changes:
 <Canvas of={Stories.WithIllustration} />
 
 ```jsx
-import { Banner } from '@utilitywarehouse/hearth-react-native';
+import { Banner, BannerIllustration } from '@utilitywarehouse/hearth-react-native';
 import SpotBillingDark from '@utilitywarehouse/hearth-svg-assets/lib/spot-billing-dark.svg';
 import SpotBillingLight from '@utilitywarehouse/hearth-svg-assets/lib/spot-billing-light.svg';
 
 const MyComponent = () => (
   <Banner
-    illustration={{
-      light: SpotBillingLight,
-      dark: SpotBillingDark,
-      width: 80,
-      height: 80,
-    }}
+    illustration={
+      <BannerIllustration light={SpotBillingLight} dark={SpotBillingDark} width={80} height={80} />
+    }
     heading="Featured Content"
     description="Discover amazing content curated just for you."
   />
@@ -358,7 +374,7 @@ Combine multiple features for rich interactive banners:
 <Canvas of={Stories.ComplexExample} />
 
 ```jsx
-import { Banner } from '@utilitywarehouse/hearth-react-native';
+import { Banner, BannerImage } from '@utilitywarehouse/hearth-react-native';
 import { InsuranceMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
 
 const MyComponent = () => (
@@ -381,10 +397,12 @@ const MyComponent = () => (
 
     {/* Dismissible banner with link */}
     <Banner
-      image={{
-        light: { uri: 'https://example.com/light.jpg' },
-        dark: { uri: 'https://example.com/dark.jpg' },
-      }}
+      image={
+        <BannerImage
+          light={{ uri: 'https://example.com/light.jpg' }}
+          dark={{ uri: 'https://example.com/dark.jpg' }}
+        />
+      }
       heading="Exclusive Member Benefit"
       description="As a valued member, you now have access to premium features at no extra cost."
       variant="emphasis"

package/src/components/Banner/Banner.props.ts

@@ -1,7 +1,5 @@
-import type { ComponentType, ReactElement } from 'react';
-import { ImageProps } from 'react-native';
+import type { ComponentType, ReactElement, ReactNode } from 'react';
 import type CardProps from '../Card/Card.props';
-import { ThemedImageProps } from '../ThemedImage';
 
 export type BannerDirection = 'horizontal' | 'vertical';
 
@@ -51,12 +49,12 @@ export interface BannerProps
    * Illustration to display in the banner
    * Mutually exclusive with icon and image
    */
-  illustration?: ThemedImageProps | ImageProps;
+  illustration?: ReactNode;
   /**
    * Image to display in the banner
    * Mutually exclusive with icon and illustration
    */
-  image?: ThemedImageProps | ImageProps;
+  image?: ReactNode;
   /**
    * Heading text
    */