@utilitywarehouse/hearth-react-native 0.9.0 → 0.11.0

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,
@@ -68,6 +70,8 @@ import {
   MenuTrigger,
   Modal,
   OL,
+  Pill,
+  PillGroup,
   ProgressStep,
   ProgressStepper,
   Radio,
@@ -85,6 +89,7 @@ import {
   TabsList,
   Textarea,
   ThemedImage,
+  ToastItem,
   ToggleButtonCard,
   ToggleButtonCardGroup,
   UL,
@@ -193,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>
@@ -337,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>
@@ -627,6 +642,26 @@ const AllComponents: React.FC = () => {
               </OL>
             </Center>
           </ComponentWrapper>
+          <ComponentWrapper name="Pill Group" link="/?path=/docs/components-pill-group--docs">
+            <Center flex={1} p="200">
+              {(() => {
+                const [pillValue, setPillValue] = React.useState<string[]>(['energy', 'mobile']);
+                return (
+                  <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} />
+                    <Pill value="mobile" label="Mobile" icon={MobileMediumIcon} />
+                  </PillGroup>
+                );
+              })()}
+            </Center>
+          </ComponentWrapper>
           <ComponentWrapper
             name="Progress Stepper"
             link="/?path=/docs/components-progress-stepper--docs"
@@ -745,6 +780,14 @@ const AllComponents: React.FC = () => {
               />
             </Center>
           </ComponentWrapper>
+          <ComponentWrapper name="Toast" link="/?path=/docs/components-toast--docs">
+            <Center flex={1} p="200">
+              <ToastItem
+                onClose={() => {}}
+                toast={{ id: 'tst', text: "I'm a toast", duration: 0 }}
+              />
+            </Center>
+          </ComponentWrapper>
           <ComponentWrapper
             name="Toggle Button Card"
             link="/?path=/docs/components-toggle-button-card--docs"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utilitywarehouse/hearth-react-native",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Utility Warehouse React Native UI library",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -57,8 +57,8 @@
     "vite-plugin-svgr": "^4.5.0",
     "vitest": "^3.2.4",
     "@utilitywarehouse/hearth-fonts": "^0.0.4",
-    "@utilitywarehouse/hearth-react-icons": "^0.7.3",
-    "@utilitywarehouse/hearth-react-native-icons": "^0.7.3",
+    "@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"
   },

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/DateInput/DateInput.docs.mdx

@@ -0,0 +1,163 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { BackToTopButton, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './DateInput.stories';
+
+<Meta title="Forms / Date Input" />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=2277-14708&t=dbFGPEbIX93BQlur-4" />
+
+<BackToTopButton />
+
+# Date Input
+
+The `DateInput` component allows users to enter dates manually using separate input fields for day, month, and year. It provides flexibility to show only the date segments you need, supports validation states, and integrates seamlessly with the React Native form system.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Examples](#examples)
+  - [Date of Birth](#date-of-birth)
+  - [Card Expiry](#card-expiry)
+  - [Year Only](#year-only)
+  - [Validation](#validation)
+  - [Disabled](#disabled)
+  - [Default Value](#default-value)
+  - [Custom Validation](#custom-validation)
+  - [Flexible Segments](#flexible-segments)
+  - [Grouping Inputs](#grouping-inputs)
+  - [With State](#with-state)
+- [Accessibility](#accessibility)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+Use state to control the date values:
+
+```tsx
+import { useState } from 'react';
+import { DateInput } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => {
+  const [day, setDay] = useState('');
+  const [month, setMonth] = useState('');
+  const [year, setYear] = useState('');
+
+  return (
+    <DateInput
+      label="Date of birth"
+      dayValue={day}
+      monthValue={month}
+      yearValue={year}
+      onDayChange={setDay}
+      onMonthChange={setMonth}
+      onYearChange={setYear}
+    />
+  );
+};
+```
+
+## Props
+
+### DateInputProps
+
+| Prop               | Type                                | Default     | Description                                           |
+| ------------------ | ----------------------------------- | ----------- | ----------------------------------------------------- |
+| `label`            | `string`                            | -           | Label text displayed above the inputs                 |
+| `helperText`       | `string`                            | -           | Helper text displayed below the inputs                |
+| `helperIcon`       | `ComponentType`                     | -           | Icon component to display with helper/validation text |
+| `validationStatus` | `'initial' \| 'valid' \| 'invalid'` | `'initial'` | Validation status of the input                        |
+| `validText`        | `string`                            | -           | Text to display when validation status is valid       |
+| `invalidText`      | `string`                            | -           | Text to display when validation status is invalid     |
+| `required`         | `boolean`                           | `false`     | Whether the input is required                         |
+| `disabled`         | `boolean`                           | `false`     | Whether the input is disabled                         |
+| `readonly`         | `boolean`                           | `false`     | Whether the input is read-only                        |
+| `hideDay`          | `boolean`                           | `false`     | Whether to hide the day segment                       |
+| `hideMonth`        | `boolean`                           | `false`     | Whether to hide the month segment                     |
+| `hideYear`         | `boolean`                           | `false`     | Whether to hide the year segment                      |
+| `dayPlaceholder`   | `string`                            | `'DD'`      | Placeholder text for the day segment                  |
+| `monthPlaceholder` | `string`                            | `'MM'`      | Placeholder text for the month segment                |
+| `yearPlaceholder`  | `string`                            | `'YYYY'`    | Placeholder text for the year segment                 |
+| `dayValue`         | `string`                            | -           | Controlled value for the day segment                  |
+| `monthValue`       | `string`                            | -           | Controlled value for the month segment                |
+| `yearValue`        | `string`                            | -           | Controlled value for the year segment                 |
+| `onDayChange`      | `(text: string) => void`            | -           | Callback fired when the day value changes             |
+| `onMonthChange`    | `(text: string) => void`            | -           | Callback fired when the month value changes           |
+| `onYearChange`     | `(text: string) => void`            | -           | Callback fired when the year value changes            |
+| `onDayFocus`       | `(e: NativeSyntheticEvent) => void` | -           | Callback fired when the day segment receives focus    |
+| `onMonthFocus`     | `(e: NativeSyntheticEvent) => void` | -           | Callback fired when the month segment receives focus  |
+| `onYearFocus`      | `(e: NativeSyntheticEvent) => void` | -           | Callback fired when the year segment receives focus   |
+| `onDayBlur`        | `(e: NativeSyntheticEvent) => void` | -           | Callback fired when the day segment loses focus       |
+| `onMonthBlur`      | `(e: NativeSyntheticEvent) => void` | -           | Callback fired when the month segment loses focus     |
+| `onYearBlur`       | `(e: NativeSyntheticEvent) => void` | -           | Callback fired when the year segment loses focus      |
+
+## Examples
+
+### Date of Birth
+
+<Canvas of={Stories.DateOfBirth} />
+
+### Card Expiry
+
+Hide the day segment for card expiry dates:
+
+<Canvas of={Stories.CardExpiry} />
+
+### Year Only
+
+Hide day and month segments for year-only inputs:
+
+<Canvas of={Stories.YearOnly} />
+
+### Validation
+
+Show validation states with helper text and icons:
+
+<Canvas of={Stories.Validation} />
+
+### Disabled
+
+Disabled date inputs:
+
+<Canvas of={Stories.Disabled} />
+
+### Default Value
+
+Set initial values with `value` props:
+
+<Canvas of={Stories.DefaultValue} />
+
+### Custom Validation
+
+Implement custom validation logic:
+
+<Canvas of={Stories.WithCustomValidation} />
+
+### Flexible Segments
+
+Control which segments are visible:
+
+<Canvas of={Stories.FlexibleSegments} />
+
+### Grouping Inputs
+
+Group date inputs with other form fields in a card:
+
+<Canvas of={Stories.GroupingInputs} />
+
+### With State
+
+Programmatically control date values:
+
+<Canvas of={Stories.WithState} />
+
+## Accessibility
+
+- Each segment has a descriptive label ("Day", "Month", "Year") for screen readers
+- Keyboard type is set to `number-pad` for easier numeric input
+- Validation states are communicated through helper text and icons
+- Disabled state properly communicated to assistive technologies