@utilitywarehouse/hearth-react-native 0.10.0 → 0.11.0

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

package/src/components/DateInput/DateInput.props.ts

@@ -0,0 +1,80 @@
+import type { TextInputProps } from 'react-native';
+import type { FormFieldBaseProps } from '../FormField/FormField.props';
+
+export interface DateInputProps extends FormFieldBaseProps {
+  /**
+   * Whether the day segment is hidden.
+   * @default false
+   */
+  hideDay?: boolean;
+  /**
+   * Whether the month segment is hidden.
+   * @default false
+   */
+  hideMonth?: boolean;
+  /**
+   * Whether the year segment is hidden.
+   * @default false
+   */
+  hideYear?: boolean;
+  /**
+   * Placeholder text for the day segment.
+   */
+  dayPlaceholder?: string;
+  /**
+   * Placeholder text for the month segment.
+   */
+  monthPlaceholder?: string;
+  /**
+   * Placeholder text for the year segment.
+   */
+  yearPlaceholder?: string;
+  /**
+   * The controlled value for the day segment. Must be used with an `onDayChange` handler.
+   */
+  dayValue?: string;
+  /**
+   * The controlled value for the month segment. Must be used with an `onMonthChange` handler.
+   */
+  monthValue?: string;
+  /**
+   * The controlled value for the year segment. Must be used with an `onYearChange` handler.
+   */
+  yearValue?: string;
+  /**
+   * Callback fired when the day value changes.
+   */
+  onDayChange?: (text: string) => void;
+  /**
+   * Callback fired when the month value changes.
+   */
+  onMonthChange?: (text: string) => void;
+  /**
+   * Callback fired when the year value changes.
+   */
+  onYearChange?: (text: string) => void;
+  /**
+   * Callback fired when the day segment receives focus.
+   */
+  onDayFocus?: TextInputProps['onFocus'];
+  /**
+   * Callback fired when the month segment receives focus.
+   */
+  onMonthFocus?: TextInputProps['onFocus'];
+  /**
+   * Callback fired when the year segment receives focus.
+   */
+  onYearFocus?: TextInputProps['onFocus'];
+  /**
+   * Callback fired when the day segment loses focus.
+   */
+  onDayBlur?: TextInputProps['onBlur'];
+  /**
+   * Callback fired when the month segment loses focus.
+   */
+  onMonthBlur?: TextInputProps['onBlur'];
+  /**
+   * Callback fired when the year segment loses focus.
+   */
+  onYearBlur?: TextInputProps['onBlur'];
+}