@utilitywarehouse/hearth-react-native 0.34.4 → 0.35.0

package/{src/components/Radio/Radio.docs.mdx → public/llms/components/radio.md}

@@ -1,29 +1,3 @@
-import { Canvas, Controls, Meta, Story } from '@storybook/addon-docs/blocks';
-import { TickSmallIcon } from '@utilitywarehouse/hearth-react-native-icons';
-import {
-  Box,
-  Center,
-  Grid,
-  Radio,
-  RadioGroup,
-  RadioIcon,
-  RadioImage,
-  RadioIndicator,
-  RadioLabel,
-  RadioTile,
-} from '../../';
-import StorybookLink from '../../../../../shared/storybook/StorybookLink';
-import mastercardLogo from '../../../docs/assets/bank-logo.png';
-import visaLogo from '../../../docs/assets/bank-logo1.png';
-import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
-import * as Stories from './Radio.stories';
-
-<Meta title="Forms / Radio" />
-
-<BackToTopButton />
-
-<ViewFigmaButton url="https://www.figma.com/design/3RY3OvLA88yZksRjOfjQJm/UW-App-UI?node-id=4454-2232" />
-
 # Radio
 
 The Radio component presents users with predefined choices and enables them to select only one option. It is commonly used for providing a single-choice selection in forms or surveys.
@@ -49,9 +23,19 @@ The Radio component presents users with predefined choices and enables them to s
 
 ## Playground
 
-<Canvas of={Stories.Playground} />
-
-<Controls of={Stories.Playground} />
+```tsx
+// Example usage
+<RadioGroup>
+  <Radio
+    aria-label="Label 1"
+    onChange={(checked: boolean) => {
+      console.log(checked, '###');
+    }}
+    nativeID="Radio-1"
+    {...args}
+  />
+</RadioGroup>
+```
 
 ## Usage
 
@@ -59,31 +43,24 @@ The Radio component presents users with predefined choices and enables them to s
 - `Radio` is used for a single selection
 - `RadioGroup` is the building block for `Radio`
 
-<UsageWrap>
-  <Center>
-    <RadioGroup aria-label="Radio Group" nativeID="Radio-group">
-      <Radio
-        value="Label 1"
-        aria-label="Label 1"
-        label="Option 1"
-      />
-      <Radio
-        value="Label 2"
-        aria-label="Label 2"
-        label="Option 2"
-      />
-    </RadioGroup>
-
-  </Center>
-</UsageWrap>
-
 ```tsx
-import { Radio, RadioGroup, RadioLabel, RadioIndicator } from '@utilitywarehouse/native-ui';
+// Example usage
+import {
+  Radio,
+  RadioGroup,
+  RadioLabel,
+  RadioIndicator,
+} from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => {
   const [value, setValue] = React.useState('Option 1');
   return (
-    <RadioGroup aria-label="Radio Group" value={value} onChange={setValue} nativeID="Radio-group">
+    <RadioGroup
+      aria-label="Radio Group"
+      value={value}
+      onValueChange={setValue}
+      nativeID="Radio-group"
+    >
       <Radio value="Option 1" aria-label="Option 1" label="Option 1" />
       <Radio value="Option 2" aria-label="Option 2" label="Option 2" />
     </RadioGroup>
@@ -110,8 +87,6 @@ const MyComponent = () => {
 | `type`               | `'default' \| 'tile'`               | `'default'` | The type of the radio.                                                                               |
 | `image`              | `ReactNode`                         | -           | The image to be displayed next to the label.                                                         |
 
-## Components
-
 ### `Radio`
 
 Contains all Radio related layout style props and actions. It inherits all the properties of React Native's [View component](https://reactnative.dev/docs/view).
@@ -139,7 +114,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 radio group.                                       |
-| `onChange`           | function                            | -           | The callback fired when any children Radio is checked or unchecked. |
+| `onValueChange`      | `(value: string) => void`           | -           | The callback fired when any children Radio is checked or unchecked. |
+| `onChange`           | function                            | -           | **Deprecated** — use `onValueChange` instead.                       |
 | `disabled`           | bool                                | -           | To manually set disable to the radio group.                         |
 | `validationStatus`   | `'valid' \| 'invalid' \| 'initial'` | -           | The validation status of the radio group.                           |
 | `label`              | `string`                            | -           | The label to be displayed above the radio group.                    |
@@ -162,44 +138,75 @@ Contains all Group related layout style props and actions. It inherits all the p
 | `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 <StorybookLink to="utility-components-themed-image">`ThemedImage` documentation</StorybookLink>.
+For more details about the ThemedImage component used internally, refer to the `ThemedImage` documentation.
 
 Contains all Image related layout style props and actions. It inherits all the properties of React Native's [Image component](https://reactnative.dev/docs/image).
 
 ## Variants
 
-<Canvas of={Stories.Variants} />
+```tsx
+// Example usage
+<Flex spacing="lg">
+  <VariantTitle title="Default">
+    <RadioGroup aria-label="Radio Group" value={value} onChange={setValue} nativeID="Radio-group">
+      <Radio
+        value="Option 1"
+        aria-label="Option 1"
+        onChange={(checked: boolean) => {
+          console.log(checked, '###');
+        }}
+        nativeID="Radio-1"
+        label="Option 1"
+        {...args}
+      />
+      <Radio
+        value="Option 2"
+        aria-label="Option 2"
+        onChange={(checked: boolean) => {
+          console.log(checked, '###');
+        }}
+        nativeID="Radio-2"
+        label="Option 2"
+        {...args}
+      />
+    </RadioGroup>
+  </VariantTitle>
+  <VariantTitle title="Disabled">
+    <RadioGroup
+      aria-label="Radio Group"
+      value={value}
+      onChange={setValue}
+      nativeID="Radio-group"
+      disabled
+    >
+      <Radio
+        aria-label="Option 3"
+        value="Option 1"
+        onChange={(checked: boolean) => console.log(checked, '###')}
+        nativeID="Radio-3"
+        label="Option 1"
+        {...args}
+      />
+      <Radio
+        aria-label="Option 4"
+        value="Option 2"
+        onChange={(checked: boolean) => console.log(checked, '###')}
+        nativeID="Radio-4"
+        label="Option 2"
+        {...args}
+      />
+    </RadioGroup>
+  </VariantTitle>
+</Flex>
+```
 
 ## Advanced Usage
 
 There may be cases where you need to customise the Radio component to fit your design requirements.
 In this example, we will create a custom Radio component with a badge and bullet list.
 
-<UsageWrap>
-  <Center>
-    <RadioGroup type="tile" aria-label="Radio Group" nativeID="Radio-group">
-      <Radio value="option-1" aria-label="Label 1">
-        <RadioIndicator>
-          <RadioIcon />
-        </RadioIndicator>
-        <RadioImage source={visaLogo} style={{ width: 40, height: 24, resizeMode: 'contain' }} />
-        <RadioLabel>Visa</RadioLabel>
-      </Radio>
-      <Radio value="option-2" aria-label="Label 2">
-        <RadioIndicator>
-          <RadioIcon />
-        </RadioIndicator>
-        <RadioImage
-          source={mastercardLogo}
-          style={{ width: 40, height: 24, resizeMode: 'contain' }}
-        />
-        <RadioLabel>Mastercard</RadioLabel>
-      </Radio>
-    </RadioGroup>
-  </Center>
-</UsageWrap>
-
 ```tsx
+// Example usage
 import {
   Radio,
   RadioGroup,
@@ -207,7 +214,7 @@ import {
   RadioIndicator,
   RadioIcon,
   RadioImage,
-} from '@utilitywarehouse/native-ui';
+} from '@utilitywarehouse/hearth-react-native';
 import { TickSmallIcon } from '@utilitywarehouse/hearth-react-native-icons';
 import visaLogo from '../../assets/bank-logo1.png';
 import mastercardLogo from '../../assets/bank-logo.png';
@@ -215,7 +222,7 @@ import mastercardLogo from '../../assets/bank-logo.png';
 const AdvancedExample = () => {
   const [value, setValue] = React.useState('option-1');
   return (
-    <RadioGroup value={value} onChange={setValue} aria-label="Card type" type="tile">
+    <RadioGroup value={value} onValueChange={setValue} aria-label="Card type" type="tile">
       <Radio value="option-1" aria-label="Visa">
         <RadioIndicator>
           <RadioIcon />
@@ -238,35 +245,24 @@ const AdvancedExample = () => {
 };
 ```
 
-## Examples
-
 ### Grid Layout With Tiles
 
 Wrap tile radios in a `Grid` when you want a multi-column layout while keeping the `RadioGroup` label, helper text and validation messaging.
 
-<UsageWrap>
-  <Center>
-    <RadioGroup label="Did this solve your problem?" type="tile">
-      <Box minWidth={300}>
-        <Grid columns={2} spacing="md">
-          <Radio label="Yes" value="yes" />
-          <Radio label="No" value="no" />
-          <Radio label="Partly" value="partly" />
-          <Radio label="Not yet" value="not-yet" />
-        </Grid>
-      </Box>
-    </RadioGroup>
-  </Center>
-</UsageWrap>
-
 ```tsx
+// Example usage
 import { Grid, Radio, RadioGroup } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => {
   const [value, setValue] = React.useState('yes');
 
   return (
-    <RadioGroup label="Did this solve your problem?" type="tile" value={value} onChange={setValue}>
+    <RadioGroup
+      label="Did this solve your problem?"
+      type="tile"
+      value={value}
+      onValueChange={setValue}
+    >
       <Grid columns={2} spacing="md">
         <Radio label="Yes" value="yes" />
         <Radio label="No" value="no" />
@@ -283,22 +279,14 @@ const MyComponent = () => {
 The `RadioTile` component is a variant of the `Radio` component that displays the radio button as a card.
 It is used to present options in a more visually appealing way.
 
-<UsageWrap>
-  <Center>
-    <RadioGroup>
-      <RadioTile value="option-1" aria-label="Label 1" label="Option 1" />
-      <RadioTile value="option-2" aria-label="Label 2" label="Option 2" />
-    </RadioGroup>
-  </Center>
-</UsageWrap>
-
 ```tsx
-import { RadioTile, RadioGroup } from '@utilitywarehouse/native-ui';
+// Example usage
+import { RadioTile, RadioGroup } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => {
   const [value, setValue] = React.useState('option-1');
   return (
-    <RadioGroup value={value} onChange={setValue}>
+    <RadioGroup value={value} onValueChange={setValue}>
       <RadioTile value="option-1" aria-label="Label 1" label="Option 1" />
       <RadioTile value="option-2" aria-label="Label 2" label="Option 2" />
     </RadioGroup>
@@ -310,17 +298,61 @@ const MyComponent = () => {
 
 The `RadioImage` component is used to display an image next to the radio button.
 
-<Canvas of={Stories.WithImage} />
+```tsx
+// Example usage
+<RadioGroup>
+  <Radio
+    aria-label="Label 1"
+    onChange={(checked: boolean) => {
+      console.log(checked, '###');
+    }}
+    nativeID="Radio-1"
+    {...args}
+    label="Visa"
+    value="Option 1"
+    image={
+      <RadioImage
+        source={bankLogo1 as ImageSourcePropType}
+        style={{ width: 48, height: 32 }}
+        resizeMode="cover"
+      />
+    }
+  />
+  <Radio
+    aria-label="Label 2"
+    onChange={(checked: boolean) => {
+      console.log(checked, '###');
+    }}
+    nativeID="Radio-2"
+    {...args}
+    label="Mastercard"
+    value="Option 2"
+    image={
+      <RadioImage
+        source={bankLogo as ImageSourcePropType}
+        style={{ width: 48, height: 32 }}
+        resizeMode="cover"
+      />
+    }
+  />
+</RadioGroup>
+```
 
 ```tsx
-import { Radio, RadioGroup, RadioImage } from '@utilitywarehouse/native-ui';
+// Example usage
+import { Radio, RadioGroup, RadioImage } from '@utilitywarehouse/hearth-react-native';
 import visaLogo from './visa-logo.png';
 import mastercardLogo from './mastercard-logo.png';
 
 const MyComponent = () => {
   const [value, setValue] = React.useState('Option 1');
   return (
-    <RadioGroup value={value} onChange={setValue} aria-label="Radio Group" nativeID="Radio-group">
+    <RadioGroup
+      value={value}
+      onValueChange={setValue}
+      aria-label="Radio Group"
+      nativeID="Radio-group"
+    >
       <Radio
         value="visa"
         aria-label="Visa"
@@ -350,27 +382,9 @@ const MyComponent = () => {
 The `RadioGroup` component is used to group multiple `Radio` components together.
 You can pass props like `label` and `helperText` to the `RadioGroup` component to provide context for the group of radios.
 
-<UsageWrap>
-  <Center>
-    <RadioGroup
-      aria-label="Radio Group"
-      label="Radio Group Label"
-      helperText="This is the supporting text"
-      invalidText="This is an invalid text"
-      validText="This is a valid text"
-      validationStatus="invalid"
-    >
-      <Radio value="option-1" aria-label="Label 1" label="Option 1" />
-      <Radio value="option-2" aria-label="Label 2" label="Option 2" />
-      <Radio value="option-3" aria-label="Label 3" label="Option 3" />
-      <Radio value="option-4" aria-label="Label 4" label="Option 4" />
-    </RadioGroup>
-
-  </Center>
-</UsageWrap>
-
 ```tsx
-import { Radio, RadioGroup } from '@utilitywarehouse/native-ui';
+// Example usage
+import { Radio, RadioGroup } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => {
   const [value, setValue] = React.useState('option-1');

package/public/llms/components/rating.md

@@ -0,0 +1,147 @@
+# Rating
+
+Use Rating to collect a score with an optional descriptive label. Supports star and emoji variants.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Examples](#examples)
+- [Emoji variant](#emoji-variant)
+- [Accessibility](#accessibility)
+
+## Playground
+
+```tsx
+// Example usage
+<Rating
+  {...args}
+  value={value}
+  onChange={nextValue => {
+    setValue(nextValue);
+    onChange?.(nextValue);
+  }}
+/>
+```
+
+## Usage
+
+```tsx
+// Example usage
+import { useState } from 'react';
+import { Rating } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => {
+  const [rating, setRating] = useState<0 | 1 | 2 | 3 | 4 | 5>(0);
+
+  return <Rating value={rating} onValueChange={setRating} labels={{ 0: 'Not rated' }} />;
+};
+```
+
+## Props
+
+| Property        | Type                                   | Description                                                         | Default                                                |
+| --------------- | -------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------ |
+| `value`         | `0 \| 1 \| 2 \| 3 \| 4 \| 5`           | Current rating value.                                               | `0`                                                    |
+| `defaultValue`  | `0 \| 1 \| 2 \| 3 \| 4 \| 5`           | Initial rating value when uncontrolled.                             | `0`                                                    |
+| `onValueChange` | `(value: RatingValue) => void`         | Called when a rating is selected.                                   | `undefined`                                            |
+| `onChange`      | `(value: RatingValue) => void`         | **Deprecated** — use `onValueChange` instead.                       | `undefined`                                            |
+| `disabled`      | `boolean`                              | Disables the rating input.                                          | `false`                                                |
+| `labels`        | `Partial<Record<RatingValue, string>>` | Override labels for specific rating values.                         | `undefined`                                            |
+| `rangeLabels`   | `{ low: string; high: string }`        | Override the low and high end labels shown below the emoji variant. | `{ low: 'Very dissatisfied', high: 'Very satisfied' }` |
+| `hideLabel`     | `boolean`                              | Hide the label text below the rating.                               | `false`                                                |
+| `variant`       | `'stars' \| 'emojis'`                  | Visual variant for the rating indicators.                           | `'stars'`                                              |
+
+### Default rating
+
+Use the default labels for a quick feedback prompt.
+
+```tsx
+// Example usage
+import { Rating } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => <Rating value={3} />;
+```
+
+### Empty rating
+
+Use `value={0}` to show a zero-star state.
+
+```tsx
+// Example usage
+import { Rating } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => <Rating value={0} labels={{ 0: 'Not rated' }} />;
+```
+
+### Custom labels
+
+Provide custom copy for each rating value.
+
+```tsx
+// Example usage
+import { Rating } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <Rating
+    value={5}
+    labels={{
+      0: 'Not rated',
+      1: 'Terrible',
+      2: 'Poor',
+      3: 'OK',
+      4: 'Great',
+      5: 'Outstanding',
+    }}
+  />
+);
+```
+
+### Hidden label
+
+Use `hideLabel` when the context already explains the rating.
+
+```tsx
+// Example usage
+import { Rating } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => <Rating value={2} hideLabel />;
+```
+
+### Disabled
+
+Use `disabled` to show a read-only rating.
+
+```tsx
+// Example usage
+import { Rating } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => <Rating value={4} disabled />;
+```
+
+### Emoji variant
+
+Use `variant="emojis"` to show emoji faces instead of stars. Labels default to "Very dissatisfied" and "Very satisfied" at the extremes. Override them with `rangeLabels={{ low: 'Custom low', high: 'Custom high' }}`.
+
+```tsx
+// Example usage
+import { Rating } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => <Rating value={4} variant="emojis" />;
+```
+
+### Emoji variant (no selection)
+
+When no emoji is selected, all emojis display at normal size with full colour.
+
+```tsx
+// Example usage
+import { Rating } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => <Rating value={0} variant="emojis" />;
+```
+
+## Accessibility
+
+- Rating uses a `radiogroup` container with `radio` items for each star or emoji.
+- Each star announces a descriptive label (e.g., "Rate Okay"). Each emoji announces its sentiment (e.g., "Rate Neutral"). Override labels with the `labels` prop to match your content.
+- Provide `accessibilityLabel` when the default label text is not sufficient for your screen reader context.

package/{src/components/Roundel/Roundel.docs.mdx → public/llms/components/roundel.md}

@@ -1,14 +1,3 @@
-import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
-import { Roundel } from '../../';
-import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
-import * as Stories from './Roundel.stories';
-
-<Meta title="Components / Roundel" />
-
-<BackToTopButton />
-
-<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=6414-8697&t=aFS22MoPV7Y08jdq-4" />
-
 # Roundel
 
 The `Roundel` component is a compact status indicator with success, pending, and error variants.
@@ -20,17 +9,15 @@ The `Roundel` component is a compact status indicator with success, pending, and
 
 ## Playground
 
-<Canvas of={Stories.Playground} />
-
-<Controls of={Stories.Playground} />
+```tsx
+// Example usage
+<Roundel {...args} />
+```
 
 ## Usage
 
-<UsageWrap>
-  <Roundel variant="success" />
-</UsageWrap>
-
 ```tsx
+// Example usage
 import { Roundel } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => <Roundel variant="success" />;
@@ -45,4 +32,17 @@ const MyComponent = () => <Roundel variant="success" />;
 
 ## Examples
 
-<Canvas of={Stories.Variants} />
+```tsx
+// Example usage
+<Flex direction="column" spacing="md" alignItems="center">
+  <VariantTitle title="Success">
+    <Roundel variant="success" />
+  </VariantTitle>
+  <VariantTitle title="Pending">
+    <Roundel variant="pending" />
+  </VariantTitle>
+  <VariantTitle title="Error">
+    <Roundel variant="error" />
+  </VariantTitle>
+</Flex>
+```

package/{src/components/SectionHeader/Sectionheader.docs.mdx → public/llms/components/section-header.md}

@@ -1,14 +1,3 @@
-import { Canvas, Controls, Meta, Story } from '@storybook/addon-docs/blocks';
-import { SectionHeader } from '../..';
-import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
-import * as Stories from './SectionHeader.stories';
-
-<Meta title="Components / Section Header" />
-
-<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components-%26-Tokens?node-id=1-163" />
-
-<BackToTopButton />
-
 # Section Header
 
 Use the `Section Header` component to help define and separate content within a screen. It provides structure, clarity, and improves page scannability for users. It is nested within components, such as List, but can be used outside of components too.
@@ -20,9 +9,10 @@ Use the `Section Header` component to help define and separate content within a
 
 ## Playground
 
-<Canvas of={Stories.Playground} />
-
-<Controls of={Stories.Playground} />
+```tsx
+// Example usage
+<SectionHeader heading="This is the section heading" helperText="Helper text" />
+```
 
 ## Anatomy
 
@@ -44,11 +34,8 @@ Use helper text when users need extra clarity or explanation before engaging wit
 
 ## Usage
 
-<UsageWrap>
-  <SectionHeader heading="Heading" helperText="Helper text" />
-</UsageWrap>
-
 ```tsx
+// Example usage
 import { SectionHeader } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => <SectionHeader heading="Heading" helperText="Helper text" />;
@@ -65,4 +52,44 @@ const MyComponent = () => <SectionHeader heading="Heading" helperText="Helper te
 
 ## Variants
 
-<Canvas of={Stories.KitchenSink} />
+```tsx
+// Example usage
+<Flex spacing="xl" direction="column" style={{ width: '100%' }}>
+  <VariantTitle title="Default SectionHeader with helper text and link">
+    <SectionHeader
+      heading="Heading"
+      helperText="Helper text"
+      trailingContent={<Link>See more</Link>}
+    />
+  </VariantTitle>
+  <VariantTitle title="SectionHeader with icon on the left of the link ">
+    <SectionHeader
+      heading="Heading"
+      helperText="Helper text"
+      trailingContent={
+        <Link icon={SettingsMediumIcon} iconPosition="left">
+          Settings
+        </Link>
+      }
+    />
+  </VariantTitle>
+  <VariantTitle title="SectionHeader with no icon">
+    <SectionHeader
+      heading="Heading"
+      helperText="Helper text"
+      trailingContent={<Link showIcon={false}>Call to action</Link>}
+    />
+  </VariantTitle>
+  <VariantTitle title="SectionHeader with badge">
+    <SectionHeader heading="Heading" helperText="Helper text" badge={{ text: "I'm a badge" }} />
+  </VariantTitle>
+  <VariantTitle title="SectionHeader with badge and link">
+    <SectionHeader
+      heading="Heading"
+      helperText="Helper text"
+      trailingContent={<Link>Show more</Link>}
+      badge={{ text: 'New' }}
+    />
+  </VariantTitle>
+</Flex>
+```