@utilitywarehouse/hearth-react-native 0.34.4 → 0.35.0

package/{src/components/DescriptionList/DescriptionList.docs.mdx → public/llms/components/description-list.md}

@@ -1,12 +1,3 @@
-import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
-import { DescriptionList, DescriptionListItem } from '../../';
-import { BackToTopButton, UsageWrap } from '../../../docs/components';
-import * as Stories from './DescriptionList.stories';
-
-<BackToTopButton />
-
-<Meta title="Components / Description List" />
-
 # Description List
 
 Display pairs of related metadata (heading + description). Supports column (stacked) and row (two-column) layouts, optional SectionHeader (heading + helper text), and per-item action links.
@@ -19,28 +10,24 @@ Display pairs of related metadata (heading + description). Supports column (stac
 
 ## Playground
 
-<Canvas of={Stories.Playground} />
-<Controls of={Stories.Playground} />
-
-## Usage
-
-<UsageWrap>
-  <DescriptionList
-    direction="column"
-    heading="Account details"
-    helperText="Static account metadata"
-  >
-    <DescriptionListItem heading="Account Number" description="123456789" />
-    <DescriptionListItem heading="Sort Code" description="12-34-56" />
+```tsx
+// Example usage
+<DescriptionList {...args}>
+  {sampleData.map(item => (
     <DescriptionListItem
-      heading="Status"
-      description="Inactive"
-      invalidText="Status cannot be inactive"
+      key={item.heading}
+      heading={item.heading}
+      description={item.description}
+      invalidText={item.invalidText}
     />
-  </DescriptionList>
-</UsageWrap>
+  ))}
+</DescriptionList>
+```
+
+## Usage
 
 ```tsx
+// Example usage
 import { DescriptionList, DescriptionListItem } from '@utilitywarehouse/hearth-react-native';
 
 <DescriptionList direction="column" heading="Account details" helperText="Static account metadata">
@@ -54,8 +41,6 @@ import { DescriptionList, DescriptionListItem } from '@utilitywarehouse/hearth-r
 </DescriptionList>;
 ```
 
-## Props
-
 ### DescriptionList
 
 | Prop                    | Type                | Default     | Description                                      |
@@ -82,8 +67,56 @@ import { DescriptionList, DescriptionListItem } from '@utilitywarehouse/hearth-r
 
 ## Variants
 
-<Canvas of={Stories.KitchenSink} />
-<Canvas of={Stories.WithLinks} />
+```tsx
+// Example usage
+<Flex direction="column" spacing="lg" style={{ width: '100%' }}>
+  <VariantTitle title="Row direction">
+    <DescriptionList direction="row">
+      {sampleData.map(item => (
+        <DescriptionListItem
+          key={item.heading}
+          heading={item.heading}
+          description={item.description}
+          invalidText={item.invalidText}
+        />
+      ))}
+    </DescriptionList>
+  </VariantTitle>
+  <VariantTitle title="Column direction">
+    <DescriptionList direction="column">
+      {sampleData.map(item => (
+        <DescriptionListItem
+          key={item.heading}
+          heading={item.heading}
+          description={item.description}
+          invalidText={item.invalidText}
+        />
+      ))}
+    </DescriptionList>
+  </VariantTitle>
+</Flex>
+```
+
+```tsx
+// Example usage
+<DescriptionList {...args}>
+  <DescriptionListItem
+    heading="Account Number"
+    description="123456789"
+    trailingContent={<Link href="https://example.com/account">Manage account</Link>}
+  />
+  <DescriptionListItem
+    heading="Status"
+    description="Active"
+    trailingContent={
+      <Link href="https://example.com/status" showIcon={false}>
+        Change
+      </Link>
+    }
+  />
+  <DescriptionListItem heading="Region" description="United Kingdom" />
+</DescriptionList>
+```
 
 ## Accessibility
 

package/{src/components/DetailText/DetailText.docs.mdx → public/llms/components/detail-text.md}

@@ -1,14 +1,3 @@
-import { Meta, Canvas, Story, Controls, Primary } from '@storybook/addon-docs/blocks';
-import * as Stories from './DetailText.stories';
-import { Center, Pressable, DetailText, Box } from '../..';
-import { UsageWrap, BackToTopButton, ViewFigmaButton } from '../../../docs/components';
-
-<Meta title="Typography / Detail Text" />
-
-<BackToTopButton />
-
-<ViewFigmaButton url="https://www.figma.com/design/9kCLtrMGwNFTscSEIbrXEl/Hearth-Design-Tokens?node-id=43-709" />
-
 # DetailText
 
 The `DetailText` component gives you the ability to create text for your screen. It can be used to display detail text in different sizes and styles.
@@ -20,23 +9,17 @@ The `DetailText` component gives you the ability to create text for your screen.
 
 ## Playground
 
-<Canvas of={Stories.Playground} />
-
-<Controls of={Stories.Playground} />
+```tsx
+// Example usage
+<DetailText size="md" textDecorationColor="grey1000">
+  Hello there, I'm some detail text!
+</DetailText>
+```
 
 ## Usage
 
-<UsageWrap>
-  <Center>
-    <DetailText>
-      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
-      labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
-      laboris nisi ut aliquip ex ea commodo consequat.
-    </DetailText>
-  </Center>
-</UsageWrap>
-
 ```jsx
+// Example usage
 import { DetailText } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => (
@@ -70,4 +53,43 @@ const MyComponent = () => (
 
 The `DetailText` component has different sizes to style the text.
 
-<Canvas of={Stories.KitchenSink} />
+```tsx
+// Example usage
+<Box gap="200">
+  <VariantTitle title="SM">
+    <DetailText {...args} size="sm">
+      Hello there, I'm some detail text!
+    </DetailText>
+  </VariantTitle>
+  <VariantTitle title="MD">
+    <DetailText {...args} size="md">
+      Hello there, I'm some detail text!
+    </DetailText>
+  </VariantTitle>
+  <VariantTitle title="LG">
+    <DetailText {...args} size="lg">
+      Hello there, I'm some detail text!
+    </DetailText>
+  </VariantTitle>
+  <VariantTitle title="XL">
+    <DetailText {...args} size="xl">
+      Hello there, I'm some detail text!
+    </DetailText>
+  </VariantTitle>
+  <VariantTitle title="2XL">
+    <DetailText {...args} size="2xl">
+      Hello there, I'm some detail text!
+    </DetailText>
+  </VariantTitle>
+  <VariantTitle title="3XL">
+    <DetailText {...args} size="3xl">
+      Hello there, I'm some detail text!
+    </DetailText>
+  </VariantTitle>
+  <VariantTitle title="4XL">
+    <DetailText {...args} size="4xl">
+      Hello there, I'm some detail text!
+    </DetailText>
+  </VariantTitle>
+</Box>
+```

package/{src/components/Divider/Divider.docs.mdx → public/llms/components/divider.md}

@@ -1,14 +1,3 @@
-import { Canvas, Controls, Meta, Story } from '@storybook/addon-docs/blocks';
-import { BodyText, Center, Divider } from '../../';
-import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
-import * as Stories from './Divider.stories';
-
-<Meta title="Components / Divider" />
-
-<BackToTopButton />
-
-<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components?node-id=1-151" />
-
 # Divider
 
 `Divider` components in `hearth-react-native` enhances visual organisation by creating clear boundaries between sections, improving readability and content grouping. They reinforce the visual hierarchy, making it easier for users to understand relationships between elements.
@@ -26,21 +15,20 @@ Dividers can help establish a visual hierarchy on your designs. They can indicat
 
 ## Playground
 
-<Canvas of={Stories.Playground} />
-
-<Controls of={Stories.Playground} />
+```tsx
+// Example usage
+<Box
+  minWidth={args.orientation === 'horizontal' ? 200 : 1}
+  minHeight={args.orientation === 'horizontal' ? 1 : 30}
+>
+  <Divider {...args} />
+</Box>
+```
 
 ## Usage
 
-<UsageWrap>
-  <Center>
-    <BodyText>This text is divided</BodyText>
-    <Divider spacing="sm" />
-    <BodyText>From this text</BodyText>
-  </Center>
-</UsageWrap>
-
 ```tsx
+// Example usage
 import { Spinner, Center } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => (

package/{src/components/ExpandableCard/ExpandableCard.docs.mdx → public/llms/components/expandable-card.md}

@@ -1,13 +1,3 @@
-import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
-import { BackToTopButton, ViewFigmaButton } from '../../../docs/components';
-import * as Stories from './ExpandableCard.stories';
-
-<Meta title="Components / Expandable Card" />
-
-<BackToTopButton />
-
-<ViewFigmaButton link="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=7222-5934" />
-
 # Expandable Card
 
 The `ExpandableCard` component is an interactive card that expands to reveal additional content when clicked. It's a Card component with smooth expansion animations, making it perfect for displaying collapsible information sections.
@@ -29,15 +19,42 @@ The `ExpandableCard` component is an interactive card that expands to reveal add
 
 ## Playground
 
-<Canvas of={Stories.Playground} />
-
-<Controls of={Stories.Playground} />
+```tsx
+// Example usage
+<ExpandableCard
+  heading="Expandable Card"
+  helperText="Click to expand"
+  duration={200}
+  animateOpacity
+  variant="subtle"
+  expandedContent={
+    <BodyText>
+      This is the expanded content. It can contain any component or content you need.
+    </BodyText>
+  }
+/>
+```
 
 ## Usage
 
-<Canvas of={Stories.BasicExample} />
+```tsx
+// Example usage
+<ExpandableCard
+  heading="Order Details"
+  helperText="View your order information"
+  expandedContent={
+    <>
+      <BodyText>Order #12345</BodyText>
+      <BodyText>Status: Delivered</BodyText>
+      <BodyText>Date: 10 Nov 2025</BodyText>
+    </>
+  }
+  style={{ width: 350 }}
+/>
+```
 
 ```tsx
+// Example usage
 import { ExpandableCard, BodyText } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => (
@@ -55,8 +72,6 @@ const MyComponent = () => (
 );
 ```
 
-## Props
-
 ### `ExpandableCard`
 
 | Prop               | Type                          | Default             | Description                                                    |
@@ -91,19 +106,47 @@ When `triggerContent` is provided, the default trigger props such as `heading`,
 | `children`              | `ReactNode` | -                         | The ExpandableCard children                    |
 | `testID`                | `string`    | `'expandable-card-group'` | Test ID for testing                            |
 
-## Examples
-
 ### Basic Example
 
-<Canvas of={Stories.BasicExample} />
+```tsx
+// Example usage
+<ExpandableCard
+  heading="Order Details"
+  helperText="View your order information"
+  expandedContent={
+    <>
+      <BodyText>Order #12345</BodyText>
+      <BodyText>Status: Delivered</BodyText>
+      <BodyText>Date: 10 Nov 2025</BodyText>
+    </>
+  }
+  style={{ width: 350 }}
+/>
+```
 
 ### With Leading Icon
 
 You can add a leading icon using the `leadingIcon` prop for simple icons, or use `leadingContent` with an `IconContainer` for more customization.
 
-<Canvas of={Stories.WithLeadingIcon} />
+```tsx
+// Example usage
+<ExpandableCard
+  heading="Settings"
+  helperText="Configure your preferences"
+  leadingIcon={SettingsMediumIcon}
+  expandedContent={
+    <>
+      <BodyText>• Notifications</BodyText>
+      <BodyText>• Privacy</BodyText>
+      <BodyText>• Account</BodyText>
+    </>
+  }
+  style={{ width: 350 }}
+/>
+```
 
 ```tsx
+// Example usage
 import { ExpandableCard, BodyText } from '@utilitywarehouse/hearth-react-native';
 import { SettingsMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
 
@@ -125,9 +168,27 @@ const MyComponent = () => (
 
 Or use `leadingContent` with `IconContainer` for emphasis variants:
 
-<Canvas of={Stories.WithIconContainer} />
+```tsx
+// Example usage
+<ExpandableCard
+  heading="Electricity"
+  helperText="Last reading 23/03/24"
+  leadingContent={
+    <IconContainer icon={ElectricityMediumIcon} size="md" variant="emphasis" color="energy" />
+  }
+  expandedContent={
+    <>
+      <BodyText>Current Usage: 245 kWh</BodyText>
+      <BodyText>Estimated Cost: £45.50</BodyText>
+      <BodyText>Next Reading: 23/04/24</BodyText>
+    </>
+  }
+  style={{ width: 350 }}
+/>
+```
 
 ```tsx
+// Example usage
 import { ExpandableCard, IconContainer, BodyText } from '@utilitywarehouse/hearth-react-native';
 import { ElectricityMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
 
@@ -150,9 +211,21 @@ const MyComponent = () => (
 
 ### With `Badge`
 
-<Canvas of={Stories.WithBadge} />
+```tsx
+// Example usage
+<ExpandableCard
+  heading="New Feature"
+  helperText="Check out what's new"
+  badge={<Badge text="New" colorScheme="info" />}
+  expandedContent={
+    <BodyText>We've added new features to improve your experience. Explore them now!</BodyText>
+  }
+  style={{ width: 350 }}
+/>
+```
 
 ```tsx
+// Example usage
 <ExpandableCard
   heading="New Feature"
   helperText="Check out what's new"
@@ -163,9 +236,24 @@ const MyComponent = () => (
 
 ### With Numeric Value
 
-<Canvas of={Stories.WithNumericValue} />
+```tsx
+// Example usage
+<ExpandableCard
+  heading="Total Balance"
+  helperText="Current account balance"
+  numericValue="£123.45"
+  expandedContent={
+    <>
+      <BodyText>Available: £100.00</BodyText>
+      <BodyText>Pending: £23.45</BodyText>
+    </>
+  }
+  style={{ width: 350 }}
+/>
+```
 
 ```tsx
+// Example usage
 <ExpandableCard
   heading="Total Balance"
   helperText="Current account balance"
@@ -183,11 +271,30 @@ const MyComponent = () => (
 
     Use `triggerContent` when you need to replace the standard trigger layout entirely while keeping the expandable chevron.
 
-    <Canvas of={Stories.WithCustomTriggerContent} />
+```tsx
+// Example usage
+<ExpandableCard
+  triggerContent={
+    <View style={{ flex: 1, gap: 4 }}>
+      <BodyText weight="semibold">March bill ready</BodyText>
+      <BodyText color="secondary">Due on 18 April 2026</BodyText>
+    </View>
+  }
+  expandedContent={
+    <>
+      <BodyText>Balance: £89.50</BodyText>
+      <BodyText>Payment method: Direct Debit</BodyText>
+    </>
+  }
+  style={{ width: 350 }}
+/>
+```
 
     ```tsx
-    import { ExpandableCard, BodyText } from '@utilitywarehouse/hearth-react-native';
-    import { View } from 'react-native';
+
+// Example usage
+import { ExpandableCard, BodyText } from '@utilitywarehouse/hearth-react-native';
+import { View } from 'react-native';
 
     const MyComponent = () => (
       <ExpandableCard
@@ -211,9 +318,44 @@ const MyComponent = () => (
 
 Use `ExpandableCardGroup` to group multiple expandable cards with an optional header.
 
-<Canvas of={Stories.CardGroup} />
+```tsx
+// Example usage
+<ExpandableCardGroup
+  heading="Your Services"
+  helperText="View details for each service"
+  headerTrailingContent={<Link href="#">View all</Link>}
+>
+  <ExpandableCard
+    heading="Electricity"
+    helperText="Last reading 23/03/24"
+    leadingContent={
+      <IconContainer icon={ElectricityMediumIcon} size="md" variant="emphasis" color="energy" />
+    }
+    expandedContent={
+      <>
+        <BodyText>Current Usage: 245 kWh</BodyText>
+        <BodyText>Estimated Cost: £45.50</BodyText>
+      </>
+    }
+  />
+  <ExpandableCard
+    heading="Gas"
+    helperText="Last reading 23/03/24"
+    leadingContent={
+      <IconContainer icon={GasMediumIcon} size="md" variant="emphasis" color="energy" />
+    }
+    expandedContent={
+      <>
+        <BodyText>Current Usage: 180 kWh</BodyText>
+        <BodyText>Estimated Cost: £32.00</BodyText>
+      </>
+    }
+  />
+</ExpandableCardGroup>
+```
 
 ```tsx
+// Example usage
 import {
   ExpandableCard,
   ExpandableCardGroup,
@@ -263,9 +405,52 @@ const MyComponent = () => (
 
 If you need to use the `ExpandableCard` component in a more advanced way, you can use the child components directly for full composition control.
 
-<Canvas of={Stories.AdvancedComposition} />
+```tsx
+// Example usage
+<div style={{ display: 'flex', flexDirection: 'column', gap: 16, width: 350 }}>
+  <ExpandableCard
+    expanded={triggerContentExpanded}
+    onExpandedChange={setTriggerContentExpanded}
+    expandedContent={
+      <>
+        <BodyText>Account Number: 1234567890</BodyText>
+        <BodyText>Sort Code: 12-34-56</BodyText>
+        <BodyText>Balance: £123.45</BodyText>
+      </>
+    }
+    triggerContent={
+      <View style={{ flex: 1, gap: 4 }}>
+        <BodyText weight="semibold">Use `triggerContent`</BodyText>
+        <BodyText color="secondary">Replace the built-in trigger layout</BodyText>
+      </View>
+    }
+  />
+
+  <ExpandableCard expanded={customChildrenExpanded} onExpandedChange={setCustomChildrenExpanded}>
+    <ExpandableCardTrigger
+      onPress={() => setCustomChildrenExpanded(!customChildrenExpanded)}
+      isExpanded={customChildrenExpanded}
+      showChevron
+    >
+      <ExpandableCardContent>
+        <ExpandableCardText>Use `children` + `showChevron`</ExpandableCardText>
+        <ExpandableCardHelperText>
+          Build the trigger yourself and keep the chevron
+        </ExpandableCardHelperText>
+      </ExpandableCardContent>
+    </ExpandableCardTrigger>
+    <ExpandableCardExpandedContent isExpanded={customChildrenExpanded}>
+      <BodyText>Account Number: 1234567890</BodyText>
+      <BodyText>Sort Code: 12-34-56</BodyText>
+      <BodyText>Balance: £123.45</BodyText>
+      <BodyText>Last Updated: 12/11/25</BodyText>
+    </ExpandableCardExpandedContent>
+  </ExpandableCard>
+</div>
+```
 
 ```tsx
+// Example usage
 import {
   ExpandableCard,
   ExpandableCardTrigger,