@utilitywarehouse/hearth-react-native 0.34.5 → 0.35.0

package/public/llms/components/pill-group.md

@@ -0,0 +1,162 @@
+# 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
+
+```tsx
+// Example usage
+<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>
+```
+
+## 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
+// Example usage
+import { Pill, PillGroup } from '@utilitywarehouse/hearth-react-native';
+import { useState } from 'react';
+
+const [selectedTags, setSelectedTags] = useState(['ui']);
+
+<PillGroup value={selectedTags} onValueChange={setSelectedTags}>
+  <Pill value="ui" label="UI" />
+  <Pill value="backend" label="Backend" icon={ServerMediumIcon} />
+  <Pill value="devops" label="DevOps" />
+</PillGroup>;
+```
+
+### 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                                    |
+| `onValueChange` | `(value: string \| string[]) => void` | -        | Handle selection changes. Returns single string in single-select mode, array in multi-select mode |
+| `onChange`      | `(value: string \| string[]) => void` | -        | **Deprecated** — use `onValueChange` instead                                                      |
+| `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
+// Example usage
+const [tags, setTags] = useState(['ui', 'backend']);
+
+<PillGroup multiple value={tags} onValueChange={setTags}>
+  <Pill value="ui" label="UI" />
+  <Pill value="backend" label="Backend" icon={ServerMediumIcon} />
+  <Pill value="devops" label="DevOps" />
+</PillGroup>;
+```
+
+### Wrap Behavior
+
+Compare how pills behave with and without wrapping enabled.
+
+```tsx
+// Example usage
+<Flex spacing="xl" direction="column" align="center">
+  <VariantTitle title="Wrap: False">
+    <PillGroup wrap={false} value={value1} onChange={setValue1}>
+      <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={setValue2}>
+      <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>
+```
+
+### Multi-Select Example
+
+Select multiple options
+
+```tsx
+// Example usage
+<Flex spacing="lg" direction="column" align="center" style={{ maxWidth: 400 }}>
+  <PillGroup wrap={true} multiple value={selectedCategories} onChange={setSelectedCategories}>
+    <Pill value="unread" label="Unread" />
+    <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>
+```
+
+### All States of Pill
+
+```tsx
+// Example usage
+<Flex spacing="xl" direction="column" align="center">
+  <VariantTitle title="Unselected">
+    <Flex direction="row" spacing="sm">
+      <PillGroup value={selectedValue} onChange={() => {}}>
+        <Pill value="1" label="Label" />
+      </PillGroup>
+    </Flex>
+  </VariantTitle>
+  <VariantTitle title="Selected">
+    <Flex direction="row" spacing="sm">
+      <PillGroup value={selectedValue} onChange={() => {}}>
+        <Pill value="2" label="Label" />
+      </PillGroup>
+    </Flex>
+  </VariantTitle>
+  <VariantTitle title="With Icon - Unselected">
+    <Flex direction="row" spacing="sm">
+      <PillGroup value={selectedValue} onChange={() => {}}>
+        <Pill value="1" label="New" icon={HeartMediumIcon} />
+      </PillGroup>
+    </Flex>
+  </VariantTitle>
+  <VariantTitle title="With Icon - Selected">
+    <Flex direction="row" spacing="sm">
+      <PillGroup value={selectedValue} onChange={() => {}}>
+        <Pill value="2" label="New" icon={HeartMediumIcon} />
+      </PillGroup>
+    </Flex>
+  </VariantTitle>
+</Flex>
+```

package/{src/components/ProgressBar/ProgressBar.docs.mdx → public/llms/components/progress-bar.md}

@@ -1,15 +1,3 @@
-import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
-import { Box, Center, ProgressBar } from '../..';
-import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
-import * as Stories from './ProgressBar.stories';
-
-<Meta title="Components / Progress Bar" />
-
-<BackToTopButton />
-
-<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=7849-5704&t=Jg2fPJPQNzOyspmQ-4" />
-<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=7863-3977&t=Jg2fPJPQNzOyspmQ-4" />
-
 # Progress Bar
 
 Progress bars communicate task completion for linear flows and bounded operations. Use the linear variant for
@@ -25,21 +13,23 @@ inline layouts and the circular variant when space is tighter or when progress n
 
 ## Playground
 
-<Canvas of={Stories.Playground} />
-
-<Controls of={Stories.Playground} />
+```tsx
+// Example usage
+<ProgressBar
+  variant="linear"
+  colorScheme="default"
+  size="md"
+  value={35}
+  min={0}
+  max={100}
+  label="Progress"
+/>
+```
 
 ## Usage
 
-<UsageWrap>
-  <Center>
-    <Box style={{ width: 260 }}>
-      <ProgressBar value={42} label="Uploading documents" />
-    </Box>
-  </Center>
-</UsageWrap>
-
 ```tsx
+// Example usage
 import { ProgressBar } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => <ProgressBar value={42} label="Uploading documents" />;
@@ -62,21 +52,45 @@ const MyComponent = () => <ProgressBar value={42} label="Uploading documents" />
 
 ## Variants
 
-<Canvas of={Stories.Variants} />
+```tsx
+// Example usage
+<Box gap="300" style={{ width: 260 }}>
+  <VariantTitle title="Linear">
+    <ProgressBar {...args} variant="linear" />
+  </VariantTitle>
+  <VariantTitle title="Circular">
+    <ProgressBar {...args} variant="circular" />
+  </VariantTitle>
+</Box>
+```
 
 ## Circular Sizes
 
-<Canvas of={Stories.CircularSizes} />
-
-## Examples
+```tsx
+// Example usage
+<Box gap="300">
+  <VariantTitle title="Small">
+    <ProgressBar {...args} size="sm" />
+  </VariantTitle>
+  <VariantTitle title="Medium">
+    <ProgressBar {...args} size="md" />
+  </VariantTitle>
+</Box>
+```
 
 ### Custom Value Labels
 
 Use `formatValueText` to show values that are not percentages, such as remaining data allowance.
 
-<Canvas of={Stories.CustomValueLabels} />
+```tsx
+// Example usage
+<Box style={{ width: 260 }}>
+  <ProgressBar {...args} />
+</Box>
+```
 
 ```tsx
+// Example usage
 import { ProgressBar } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => (

package/public/llms/components/progress-stepper.md

@@ -0,0 +1,144 @@
+# Progress Stepper
+
+A form helper component that displays a series of dots connected by lines, showing the progress through a multi-step process. Each step can be marked as completed, active, or uncompleted.
+
+- [Usage](#usage)
+- [Examples](#examples)
+- [API](#api)
+- [Step Statuses](#step-statuses-1)
+- [Accessibility](#accessibility)
+- [Best Practices](#best-practices)
+
+## Usage
+
+The `ProgressStepper` component uses a compound component pattern, making it easy to define steps declaratively. It provides visual feedback about complete steps, the current active step, and remaining incomplete steps.
+
+### Basic Usage
+
+```tsx
+// Example usage
+import { ProgressStepper, ProgressStep } from '@utilitywarehouse/hearth-react-native';
+
+<ProgressStepper>
+  <ProgressStep id={'1'} status="complete" />
+  <ProgressStep id={'2'} status="complete" />
+  <ProgressStep id={'3'} status="active" />
+  <ProgressStep id={'4'} status="incomplete" />
+  <ProgressStep id={'5'} status="incomplete" />
+</ProgressStepper>;
+```
+
+### Default Layout
+
+```tsx
+// Example usage
+<ProgressStepper>
+  (
+  <Flex spacing="xl" direction="column" align="center" style={{ flex: 1, minWidth: 200 }}>
+    <ProgressStepper>
+      <ProgressStep id={'1'} status="complete" />
+      <ProgressStep id={'2'} status="complete" />
+      <ProgressStep id={'3'} status="active" />
+      <ProgressStep id={'4'} status="incomplete" />
+    </ProgressStepper>
+    <Flex direction="row" spacing="lg" style={{ width: '100%' }}>
+      <ProgressStep id={'1'} status="complete" />
+    </Flex>
+    <Flex direction="row" spacing="lg" style={{ width: '100%' }}>
+      <ProgressStep id={'3'} status="active" />
+    </Flex>
+    <Flex direction="row" spacing="lg" style={{ width: '100%' }}>
+      <ProgressStep id={'5'} status="incomplete" />
+    </Flex>
+  </Flex>
+  )
+</ProgressStepper>
+```
+
+### Step Statuses
+
+See how different step statuses are visualized:
+
+```tsx
+// Example usage
+<Flex spacing="xl" direction="column" align="center">
+  <VariantTitle title="All Uncompleted Steps">
+    <ProgressStepper {...props}>
+      <ProgressStep id={'1'} status="incomplete" />
+      <ProgressStep id={'2'} status="incomplete" />
+      <ProgressStep id={'3'} status="incomplete" />
+    </ProgressStepper>
+  </VariantTitle>
+  <VariantTitle title="One Active Step">
+    <ProgressStepper {...props}>
+      <ProgressStep id={'1'} status="active" />
+      <ProgressStep id={'2'} status="incomplete" />
+      <ProgressStep id={'3'} status="incomplete" />
+    </ProgressStepper>
+  </VariantTitle>
+  <VariantTitle title="Mixed Statuses">
+    <ProgressStepper {...props}>
+      <ProgressStep id={'1'} status="complete" />
+      <ProgressStep id={'2'} status="complete" />
+      <ProgressStep id={'3'} status="active" />
+      <ProgressStep id={'4'} status="incomplete" />
+    </ProgressStepper>
+  </VariantTitle>
+  <VariantTitle title="All Completed">
+    <ProgressStepper {...props}>
+      <ProgressStep id={'1'} status="complete" />
+      <ProgressStep id={'2'} status="complete" />
+      <ProgressStep id={'3'} status="complete" />
+    </ProgressStepper>
+  </VariantTitle>
+</Flex>
+```
+
+### Basic
+
+```tsx
+// Example usage
+<Flex spacing="lg" direction="column" align="center">
+  <Heading size="md">Progress Stepper</Heading>
+  <BodyText>Shows progress through multi-step processes</BodyText>
+  <ProgressStepper {...props}>
+    <ProgressStep id="services-data" status="complete" />
+    <ProgressStep id="customer-data" status="complete" />
+    <ProgressStep id="shipping-data" status="active" />
+    <ProgressStep id="payment-data" status="incomplete" />
+    <ProgressStep id="summary" status="incomplete" />
+  </ProgressStepper>
+  <BodyText>Step 3 of 5</BodyText>
+</Flex>
+```
+
+### Progress Stepper Props
+
+| Prop       | Type        | Default  | Description               |
+| ---------- | ----------- | -------- | ------------------------- |
+| `children` | `ReactNode` | Required | `ProgressStep` components |
+
+### Progress Step Props
+
+| Prop     | Type                                     | Default  | Description                    |
+| -------- | ---------------------------------------- | -------- | ------------------------------ |
+| `id`     | `string`                                 | Required | Unique identifier for the step |
+| `status` | `'complete' \| 'active' \| 'incomplete'` | Required | Current status of the step     |
+
+## Step Statuses
+
+- **complete**: Step has been finished, shows a checkmark icon
+- **active**: Current step, shows a number with highlighted background
+- **incomplete**: Future step, shows a number with muted styling
+
+## Accessibility
+
+- Each step is properly labeled for screen readers
+- The component follows WCAG guidelines for color contrast
+- Progress indication is communicated through both visual and textual means
+
+## Best Practices
+
+1. **Keep it simple** - The stepper focuses on essential functionality without complexity
+1. **Indicate progress clearly** - Make sure users understand how many steps remain
+1. **Use meaningful IDs** - Choose IDs that make sense for your specific use case (numbers, step names, etc.)

package/{src/components/RadioCard/RadioCard.docs.mdx → public/llms/components/radio-card.md}

@@ -1,25 +1,3 @@
-import { Canvas, Controls, Meta, Story } from '@storybook/addon-docs/blocks';
-import { TickSmallIcon } from '@utilitywarehouse/hearth-react-native-icons';
-import {
-  BodyText,
-  Box,
-  Center,
-  DetailText,
-  Heading,
-  LI,
-  RadioCard,
-  RadioCardGroup,
-  UL,
-} from '../..';
-import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
-import * as Stories from './RadioCardGroup.stories';
-
-<Meta title="Components / Radio Card" />
-
-<BackToTopButton />
-
-<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=1-161" />
-
 # Radio Card
 
 The `RadioCard` component is a UI element that allows users to select one option from a set of predefined choices.
@@ -32,34 +10,26 @@ with other `RadioCard`s to create a `RadioCardGroup`, providing a cohesive and o
 
 ## Playground
 
-<Canvas of={Stories.Playground} />
-
-<Controls of={Stories.Playground} />
+```tsx
+// Example usage
+<RadioCardGroup {...args}>
+  <RadioCard aria-label="Label 1" label="Option 1" value="Option 1" nativeID="RadioCard-1">
+    <BodyText>Additional content</BodyText>
+  </RadioCard>
+  <RadioCard aria-label="Label 2" label="Option 2" value="Option 2" nativeID="RadioCard-2">
+    <BodyText>Additional content</BodyText>
+  </RadioCard>
+  <RadioCard aria-label="Label 3" label="Option 3" value="Option 3" nativeID="RadioCard-3">
+    <BodyText>Additional content</BodyText>
+  </RadioCard>
+</RadioCardGroup>
+```
 
 ## Usage
 
-<UsageWrap>
-  <Center>
-    <RadioCardGroup aria-label="RadioCard Group" nativeID="RadioCard-group">
-      <RadioCard value="fixed" aria-label="Debit Card Payment" label="Debit card payment">
-        <UL>
-          <LI>5 free top-ups per month</LI>
-          <LI>£0.35 per additional top-up</LI>
-        </UL>
-      </RadioCard>
-      <RadioCard value="variable" aria-label="Instant bank transfer" label="Instant bank transfer">
-        <UL>
-          <LI>Unlimited free top-ups</LI>
-          <LI>Instant withdrawals</LI>
-          <LI>Extra layer of security</LI>
-        </UL>
-      </RadioCard>
-    </RadioCardGroup>
-  </Center>
-</UsageWrap>
-
 ```tsx
-import { RadioCard, RadioCardGroup, UL, LI } from '@utilitywarehouse/native-ui';
+// Example usage
+import { RadioCard, RadioCardGroup, UL, LI } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => {
   const [value, setValue] = React.useState('Option 1');
@@ -67,7 +37,7 @@ const MyComponent = () => {
     <RadioCardGroup
       aria-label="Select Tariff"
       value={value}
-      onChange={setValue}
+      onValueChange={setValue}
       nativeID="RadioCard-group"
     >
       <RadioCard value="fixed" aria-label="Debit Card Payment" label="Debit card payment">
@@ -104,8 +74,6 @@ The `RadioCard` component accepts the following props:
 | `alignItems`     | `'flex-start' \| 'flex-end' \| 'center' \|`<br />` 'stretch' \| 'baseline'`                             | -        | Sets the alignment of flex items on the cross axis.                                                       |
 | `justifyContent` | `'flex-start' \| 'flex-end' \| 'center' \|`<br />` 'space-between' \| 'space-around' \| 'space-evenly'` | -        | Sets the alignment of flex items on the main axis.                                                        |
 
-## Components
-
 ### `RadioCard`
 
 Contains all RadioCard related layout style props and actions. It inherits all the properties of React Native's [`Pressable` component](https://reactnative.dev/docs/pressable) and [`View` component](https://reactnative.dev/docs/view) styles for layout.
@@ -117,7 +85,8 @@ Contains all Group related layout style props and actions. It inherits all the p
 | Property         | Type                                                                                                     | Default  | Description                                                                                                |
 | ---------------- | -------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
 | `value`          | `string`                                                                                                 | -        | The value of the currently selected `RadioCard`.                                                           |
-| `onChange`       | `(value: string) => void`                                                                                | -        | Callback fired when the selected `RadioCard` changes.                                                      |
+| `onValueChange`  | `(value: string) => void`                                                                                | -        | Callback fired when the selected `RadioCard` changes.                                                      |
+| `onChange`       | `(value: string) => void`                                                                                | -        | **Deprecated** — use `onValueChange` instead.                                                              |
 | `gap`            | `keyof typeof space`                                                                                     | -        | The gap between the `RadioCard` items.                                                                     |
 | `columns`        | `GridProps['columns']`                                                                                   | -        | If set, the group will use a grid layout with the specified number of columns. Otherwise, it uses flexbox. |
 | `flexDirection`  | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'`                                                 | `'row'`  | (Flexbox only) Sets the direction of the flex items.                                                       |