@utilitywarehouse/hearth-react-native 0.9.0 → 0.11.0

package/src/components/PillGroup/PillGroup.docs.mdx

@@ -0,0 +1,96 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { BackToTopButton, ViewFigmaButton } from '../../../docs/components';
+import * as PillGroupStories from './PillGroup.stories';
+
+<Meta title="Components / Pill Group" />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens" />
+
+<BackToTopButton />
+
+# Pill Group
+
+A container component that groups multiple `Pill` components together for filtering and categorization. It provides layout control with optional wrapping behavior and manages selection state.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Examples](#examples)
+
+## Playground
+
+<Canvas of={PillGroupStories.Playground} />
+
+<Controls of={PillGroupStories.Playground} />
+
+## Usage
+
+The `PillGroup` component is a controlled component that manages the selection state of multiple `Pill` components. It supports both single and multi-select modes.
+
+### Basic Usage
+
+```tsx
+import { Pill, PillGroup } from '@hearth/react-native';
+import { useState } from 'react';
+
+const [selectedTags, setSelectedTags] = useState(['ui']);
+
+<PillGroup value={selectedTags} onChange={setSelectedTags}>
+  <Pill value="ui" label="UI" />
+  <Pill value="backend" label="Backend" icon={ServerMediumIcon} />
+  <Pill value="devops" label="DevOps" />
+</PillGroup>
+```
+
+## Props
+
+### PillGroup Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string \| string[]` | Required | Controlled selected value(s). Single string for single-select, array for multi-select |
+| `multiple` | `boolean` | `false` | Enable multi-select mode |
+| `wrap` | `boolean` | `true` | Whether pills should wrap to multiple lines when they overflow |
+| `onChange` | `(value: string \| string[]) => void` | - | Handle selection changes. Returns single string in single-select mode, array in multi-select mode |
+| `children` | `ReactNode` | Required | `Pill` components to group together |
+| ...rest | `ViewProps` | - | All standard View props are supported |
+
+### Pill Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | Required | Value returned when selected |
+| `label` | `string` | Required | The text content of the pill |
+| `icon` | `ComponentType<any>` | - | Optional icon component to display before the label |
+| ...rest | `PressableProps` | - | All standard Pressable props are supported |
+
+
+### Multi-Select Mode
+
+```tsx
+const [tags, setTags] = useState(['ui', 'backend']);
+
+<PillGroup multiple value={tags} onChange={setTags}>
+  <Pill value="ui" label="UI" />
+  <Pill value="backend" label="Backend" icon={ServerMediumIcon} />
+  <Pill value="devops" label="DevOps" />
+</PillGroup>
+```
+
+## Examples
+
+### Wrap Behavior
+
+Compare how pills behave with and without wrapping enabled.
+
+<Canvas of={PillGroupStories.WrapBehavior} />
+
+### Multi-Select Example
+
+Select multiple options
+
+<Canvas of={PillGroupStories.Multiple} />
+
+### All States of Pill
+
+<Canvas of={PillGroupStories.PillStates} />

package/src/components/PillGroup/PillGroup.props.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import { ScrollViewProps, ViewStyle } from 'react-native';
+
+export interface PillGroupProps
+  extends Omit<ScrollViewProps, 'horizontal' | 'contentContainerStyle' | 'showsHorizontalScrollIndicator'> {
+  /** Controlled selected value(s) */
+  value: string | string[];
+
+  /** Multi-select mode. Default = false */
+  multiple?: boolean;
+
+  /** Allow pills to wrap lines. Default = true */
+  wrap?: boolean;
+
+  /** Handle selection changes */
+  onChange?: (value: string | string[]) => void;
+
+  /** Children must be <Pill> elements */
+  children: React.ReactNode;
+
+  style?: ViewStyle | ViewStyle[];
+}

package/src/components/PillGroup/PillGroup.stories.tsx

@@ -0,0 +1,159 @@
+import React, { useState } from 'react';
+import { Meta, StoryObj } from '@storybook/react-vite';
+import { HeartMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
+import { PillGroup } from '.';
+import { Pill } from './Pill';
+import { VariantTitle } from '../../../docs/components';
+import { BodyText } from '../BodyText';
+import { Flex } from '../Flex';
+import { Heading } from '../Heading';
+
+const meta = {
+  title: 'Stories / PillGroup',
+  component: PillGroup,
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof PillGroup>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  args: {
+    wrap: false,
+    multiple: false,
+    value: '2',
+    children: <></>,
+  },
+  parameters: {
+    controls: { exclude: ['value', 'onChange', 'style', 'children'] },
+  },
+  render: props => {
+    const [value, setValue] = useState<string | string[]>(props.value || '');
+
+    return (
+      <PillGroup {...props} value={value} onChange={setValue}>
+        <Pill value="1" label="All" />
+        <Pill value="2" label="Energy" />
+        <Pill value="3" label="Broadband" />
+        <Pill value="4" label="Mobile" />
+      </PillGroup>
+    );
+  },
+};
+
+export const PillStates: Story = {
+  args: {
+    value: '',
+    children: <></>,
+  },
+  parameters: {
+    controls: { exclude: ['value', 'onChange', 'multiple', 'wrap', 'style', 'children'] },
+  },
+  render: () => {
+    const selectedValue = '2';
+
+    return (
+      <Flex space="xl" direction="column" align="center">
+        <VariantTitle title="Unselected">
+          <Flex direction="row" space="sm">
+            <PillGroup value={selectedValue} onChange={() => {}}>
+              <Pill value="1" label="Label" />
+            </PillGroup>
+          </Flex>
+        </VariantTitle>
+        <VariantTitle title="Selected">
+          <Flex direction="row" space="sm">
+            <PillGroup value={selectedValue} onChange={() => {}}>
+              <Pill value="2" label="Label" />
+            </PillGroup>
+          </Flex>
+        </VariantTitle>
+        <VariantTitle title="With Icon - Unselected">
+          <Flex direction="row" space="sm">
+            <PillGroup value={selectedValue} onChange={() => {}}>
+              <Pill value="1" label="New" icon={HeartMediumIcon} />
+            </PillGroup>
+          </Flex>
+        </VariantTitle>
+        <VariantTitle title="With Icon - Selected">
+          <Flex direction="row" space="sm">
+            <PillGroup value={selectedValue} onChange={() => {}}>
+              <Pill value="2" label="New" icon={HeartMediumIcon} />
+            </PillGroup>
+          </Flex>
+        </VariantTitle>
+      </Flex>
+    );
+  },
+};
+
+export const WrapBehavior: Story = {
+  args: {
+    value: '',
+    children: <></>,
+  },
+  parameters: {
+    controls: { exclude: ['wrap', 'value', 'onChange', 'multiple'] },
+  },
+  render: () => {
+    const [value1, setValue1] = useState<string>('2');
+    const [value2, setValue2] = useState<string>('7');
+
+    return (
+      <Flex space="xl" direction="column" align="center">
+        <VariantTitle title="Wrap: False">
+          <PillGroup wrap={false} value={value1} onChange={v => setValue1(v as string)}>
+            <Pill value="1" label="New" />
+            <Pill value="2" label="Some label" />
+            <Pill value="3" label="Short" />
+            <Pill value="4" label="Quite a long label" />
+            <Pill value="5" label="Hmm, another label" />
+          </PillGroup>
+        </VariantTitle>
+        <VariantTitle title="Wrap: True">
+          <PillGroup wrap={true} value={value2} onChange={v => setValue2(v as string)}>
+            <Pill value="6" label="New" />
+            <Pill value="7" label="Some label" />
+            <Pill value="8" label="Short" />
+            <Pill value="9" label="Quite a long label" />
+            <Pill value="10" label="Hmm, another label" />
+            <Pill value="11" label="Custom Range" />
+            <Pill value="12" label="Last 7 Days" />
+          </PillGroup>
+        </VariantTitle>
+      </Flex>
+    );
+  },
+};
+
+export const Multiple: Story = {
+  args: {
+    value: [],
+    children: <></>,
+  },
+  parameters: {
+    controls: { exclude: ['wrap', 'value', 'onChange', 'multiple'] },
+  },
+  render: () => {
+    const [selectedCategories, setSelectedCategories] = useState<string[]>(['new', 'read']);
+
+    return (
+      <Flex space="lg" direction="column" align="center" style={{ maxWidth: 400 }}>
+        <PillGroup wrap={true} multiple value={selectedCategories} onChange={v => setSelectedCategories(v as string[])}>
+          <Pill value="all" label="All" />
+          <Pill value="new" label="New" icon={HeartMediumIcon} />
+          <Pill value="favourites" label="My favourites" icon={HeartMediumIcon} />
+          <Pill value="read" label="Read" />
+          <Pill value="yesterday" label="Yesterday" />
+          <Pill value="lastweek" label="Last Week" />
+        </PillGroup>
+        <BodyText>
+          Selected: {selectedCategories.length}{' '}
+          {selectedCategories.length === 1 ? 'category' : 'categories'}
+        </BodyText>
+      </Flex>
+    );
+  },
+};

package/src/components/PillGroup/PillGroup.tsx

@@ -0,0 +1,66 @@
+import React, { useMemo } from 'react';
+import { ScrollView } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { Box } from '../Box';
+import { PillGroupContext, PillGroupContextValue } from './PillGroup.context';
+import type { PillGroupProps } from './PillGroup.props';
+
+export const PillGroup = ({
+  children,
+  value,
+  multiple = false,
+  wrap = true,
+  onChange,
+  style,
+  ...props
+}: PillGroupProps) => {
+  const normalizedValue = Array.isArray(value) ? value : [value];
+
+  const contextValue: PillGroupContextValue = useMemo(
+    () => ({
+      value: normalizedValue,
+      onChange: (pillValue: string) => {
+        if (multiple) {
+          const newValue = normalizedValue.includes(pillValue)
+            ? normalizedValue.filter(v => v !== pillValue)
+            : [...normalizedValue, pillValue];
+          onChange?.(newValue);
+        } else {
+          onChange?.(pillValue);
+        }
+      },
+    }),
+    [normalizedValue, multiple, onChange]
+  );
+
+  return (
+    <PillGroupContext.Provider value={contextValue}>
+      {wrap ? (
+        <Box style={[styles.group, styles.wrap, style]} {...props}>
+          {children}
+        </Box>
+      ) : (
+        <ScrollView
+          horizontal
+          contentContainerStyle={[styles.group, style]}
+          showsHorizontalScrollIndicator={false}
+          {...props}
+        >
+          {children}
+        </ScrollView>
+      )}
+    </PillGroupContext.Provider>
+  );
+};
+
+PillGroup.displayName = 'PillGroup';
+
+const styles = StyleSheet.create(theme => ({
+  group: {
+    flexDirection: 'row',
+    gap: theme.components.pill.group.gap,
+  },
+  wrap: {
+    flexWrap: 'wrap',
+  },
+}));

package/src/components/PillGroup/index.ts

@@ -0,0 +1,4 @@
+export { PillGroup } from './PillGroup';
+export type { PillGroupProps } from './PillGroup.props';
+export { Pill } from './Pill';
+export type { PillProps } from './Pill.props';

package/src/components/Select/Select.tsx

@@ -181,6 +181,7 @@ const Select = ({
               <Input
                 placeholder={searchPlaceholder}
                 value={search}
+                inBottomSheet
                 onChangeText={setSearch}
                 type="search"
               />
@@ -287,6 +288,7 @@ const styles = StyleSheet.create(theme => ({
   emptyContainer: {
     alignItems: 'center',
     justifyContent: 'center',
+    marginTop: theme.space.md,
   },
 }));
 

package/src/components/Toast/Toast.context.tsx

@@ -0,0 +1,118 @@
+import React, { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { View } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import type { ToastContextValue, ToastInstance, ToastOptions } from './Toast.props';
+import ToastItem, { type ToastItemHandle } from './ToastItem';
+
+const ToastContext = createContext<ToastContextValue | undefined>(undefined);
+
+export const useToastContext = () => {
+  const ctx = useContext(ToastContext);
+  if (!ctx) throw new Error('useToastContext must be used within ToastProvider');
+  return ctx;
+};
+
+export const ToastProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const [toasts, setToasts] = useState<ToastInstance[]>([]);
+  const timers = useRef<Record<string, number>>({});
+  const toastRefs = useRef<Record<string, ToastItemHandle | null>>({});
+
+  const removeToast = useCallback((id: string) => {
+    setToasts(s => s.filter(t => t.id !== id));
+    const timer = timers.current[id];
+    if (timer) {
+      clearTimeout(timer);
+      delete timers.current[id];
+    }
+    delete toastRefs.current[id];
+  }, []);
+
+  const addToast = useCallback(
+    (opts: ToastOptions) => {
+      const id = opts.id ?? `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+      const toast: ToastInstance = {
+        id,
+        text: opts.text,
+        actionText: opts.actionText,
+        onPress: opts.onPress,
+        onDismiss: opts.onDismiss,
+        icon: opts.icon,
+        duration: opts.duration ?? 6000,
+        showDismissIcon: opts.showDismissIcon,
+        dismissOnPress: opts.dismissOnPress ?? true,
+      };
+      setToasts(s => [toast, ...s]);
+
+      // set auto-dismiss timer
+      if (toast.duration && toast.duration > 0) {
+        const t = setTimeout(() => {
+          // call dismiss animation if ref exists, otherwise remove immediately
+          const ref = toastRefs.current[id];
+          if (ref) {
+            ref.dismiss();
+          } else {
+            removeToast(id);
+          }
+        }, toast.duration) as unknown as number;
+        timers.current[id] = t;
+      }
+
+      return id;
+    },
+    [removeToast]
+  );
+
+  useEffect(() => {
+    return () => {
+      // cleanup timers on unmount
+      Object.values(timers.current).forEach(t => clearTimeout(t));
+      timers.current = {};
+    };
+  }, []);
+
+  return (
+    <ToastContext.Provider value={{ addToast, removeToast }}>
+      {children}
+      <View pointerEvents="box-none" style={styles.container as any}>
+        <View style={styles.stack as any}>
+          {toasts.map(t => (
+            <ToastItem
+              key={t.id}
+              ref={el => {
+                toastRefs.current[t.id] = el;
+              }}
+              toast={t}
+              onClose={removeToast}
+            />
+          ))}
+        </View>
+      </View>
+    </ToastContext.Provider>
+  );
+};
+
+export const useToast = () => {
+  const ctx = useContext(ToastContext);
+  if (!ctx) throw new Error('useToast must be used within ToastProvider');
+  return ctx;
+};
+
+export default ToastContext;
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    bottom: 0,
+    alignItems: 'stretch',
+    paddingBottom: theme.space['200'],
+    pointerEvents: 'box-none',
+  },
+  stack: {
+    width: '100%',
+    alignItems: 'center',
+    justifyContent: 'flex-end',
+    gap: theme.components.toast.stack.gap,
+  },
+}));

package/src/components/Toast/Toast.docs.mdx

@@ -0,0 +1,164 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import toastiOSVideo from '../../../docs/assets/toast-ios.MP4';
+import { BackToTopButton, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './Toast.stories';
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=7072-902" />
+
+<Meta title="Components / Toast" />
+
+<BackToTopButton />
+
+# Toast
+
+The `Toast` component provides a non-intrusive way to display brief messages to users. Toasts appear at the bottom of the screen, can be stacked vertically, and automatically dismiss after a configurable duration. They support swipe-to-dismiss gestures and can include icons, action links, and a dismiss button.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Features](#features)
+- [Examples](#examples)
+  - [Basic Toast](#basic-toast)
+  - [With Icon](#with-icon)
+  - [With Action](#with-action)
+  - [Custom Duration](#custom-duration)
+  - [Stacked Toasts](#stacked-toasts)
+  - [Programmatic Dismiss](#programmatic-dismiss)
+  - [Dismiss Options](#dismiss-options)
+- [Accessibility](#accessibility)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+### Setup
+
+First, wrap your app with the `ToastProvider` at the root level:
+
+```tsx
+import { ToastProvider } from '@utilitywarehouse/hearth-react-native';
+
+function App() {
+  return <ToastProvider>{/* Your app content */}</ToastProvider>;
+}
+```
+
+**Important:** Place the `ToastProvider` at the root of your app, outside of any scroll views or nested containers. This ensures toasts are displayed in a fixed position at the bottom of the screen, regardless of scroll position.
+
+### Basic Usage
+
+Use the `useToast` hook to display toasts from any component:
+
+```tsx
+import { useToast } from '@utilitywarehouse/hearth-react-native';
+import { TickSmallIcon } from '@utilitywarehouse/hearth-react-native-icons';
+
+const MyComponent = () => {
+  const { addToast } = useToast();
+
+  const handleSave = () => {
+    // Your save logic
+    addToast({
+      text: 'Settings saved successfully',
+      icon: TickSmallIcon,
+    });
+  };
+
+  return <Button onPress={handleSave}>Save</Button>;
+};
+```
+
+## Props
+
+### ToastOptions
+
+| Prop              | Type                  | Default        | Description                                                      |
+| ----------------- | --------------------- | -------------- | ---------------------------------------------------------------- |
+| `text`            | `string \| ReactNode` | -              | The main message to display                                      |
+| `icon`            | `ComponentType`       | -              | Optional icon component to display                               |
+| `actionText`      | `string`              | -              | Optional action text to display as a link                        |
+| `onPress`         | `() => void`          | -              | Optional callback when action or toast is pressed                |
+| `onDismiss`       | `() => void`          | -              | Optional callback when toast is dismissed                        |
+| `duration`        | `number`              | `6000`         | Auto-dismiss duration in ms (0 = no dismiss)                     |
+| `showDismissIcon` | `boolean`             | `true`         | Whether to show the dismiss icon button                          |
+| `dismissOnPress`  | `boolean`             | `true`         | Whether to dismiss the toast when pressed when Toast has onPress |
+| `id`              | `string`              | auto-generated | Optional custom ID for the toast                                 |
+
+### useToast Hook
+
+Returns an object with:
+
+| Method        | Signature                           | Description                              |
+| ------------- | ----------------------------------- | ---------------------------------------- |
+| `addToast`    | `(options: ToastOptions) => string` | Shows a new toast and returns its ID     |
+| `removeToast` | `(id: string) => void`              | Programmatically dismisses a toast by ID |
+
+## Features
+
+- **Auto-Dismiss:** Toasts automatically dismiss after 6 seconds by default. You can customize this duration or disable auto-dismiss entirely by setting `duration` to `0`.
+- **Swipe to Dismiss:** Users can swipe down on any toast to dismiss it immediately. The gesture uses smooth animations for a native feel.
+- **Dismiss Button:** Each toast includes a close button in the top-right corner for manual dismissal.
+- **Stacking:** Multiple toasts stack vertically at the bottom of the screen, with the newest toast appearing on top. Each toast maintains its own auto-dismiss timer.
+- **Icons:** Add visual context by including an icon component. Icons are positioned at the start of the toast message.
+- **Action Links:** Include interactive action links (like "Undo" or "View") as secondary actions within the toast using the `actionText` prop. When `onPress` is provided, the entire toast becomes tappable, allowing users to trigger the action by tapping anywhere on the toast.
+
+### Native iOS Toast Animation
+
+<video src={toastiOSVideo} width={400} height="auto" controls loop autoPlay />
+
+## Examples
+
+### Basic Toast
+
+A simple text-only toast:
+
+<Canvas of={Stories.BasicToast} />
+
+### With Icon
+
+Toasts with icons for different message types:
+
+<Canvas of={Stories.WithIcon} />
+
+### With Action
+
+Include interactive action links for secondary actions:
+
+<Canvas of={Stories.WithAction} />
+
+### Custom Duration
+
+Control how long toasts stay visible:
+
+<Canvas of={Stories.CustomDuration} />
+
+### Stacked Toasts
+
+Multiple toasts stack vertically, newest on top:
+
+<Canvas of={Stories.StackedToasts} />
+
+### Programmatic Dismiss
+
+Dismiss toasts programmatically using their ID:
+
+<Canvas of={Stories.ProgrammaticDismiss} />
+
+### Dismiss Options
+
+Control dismiss behavior with `showDismissIcon` and `dismissOnPress`:
+
+<Canvas of={Stories.DismissOptions} />
+
+## Accessibility
+
+- **Screen reader announcements**: Toast content is automatically announced when it appears. On iOS, VoiceOver receives the announcement via accessibility live regions. On Android, TalkBack receives a direct announcement to avoid duplication
+- **Semantic structure**: Toasts use proper ARIA roles (`alert` on iOS) for screen readers
+- **Dismiss button**: Includes an accessibility label for easy dismissal
+- **Action links**: Properly accessible as interactive elements when provided
+- **Swipe gestures**: Work alongside manual dismiss options for user flexibility
+- **Non-blocking**: Toasts don't interrupt user interaction with the app or steal focus

package/src/components/Toast/Toast.props.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from 'react';
+
+export interface ToastOptions {
+  id?: string;
+  text: string | ReactNode;
+  /** Optional action text to display as a link */
+  actionText?: string;
+  /** Optional callback when action link or toast is pressed */
+  onPress?: () => void;
+  /** Optional callback when toast is dismissed */
+  onDismiss?: () => void;
+  /** Optional icon component */
+  icon?: React.ComponentType;
+  /** Duration in milliseconds; default 6000 */
+  duration?: number;
+  /** Whether to show the dismiss icon button; default true */
+  showDismissIcon?: boolean;
+  /** Whether to dismiss the toast when pressed; default true */
+  dismissOnPress?: boolean;
+}
+
+export interface ToastInstance extends ToastOptions {
+  id: string;
+  /** resolved duration */
+  duration: number;
+}
+
+export interface ToastContextValue {
+  addToast: (opts: ToastOptions) => string;
+  removeToast: (id: string) => void;
+}
+
+export default ToastOptions;