@utilitywarehouse/hearth-react-native 0.34.5 → 0.35.0

package/{src/components/Switch/Switch.docs.mdx → public/llms/components/switch.md}

@@ -1,21 +1,3 @@
-import { Canvas, Controls, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Center, Flex, FormField, FormFieldLabel, FormFieldLabelText, Label, Switch } from '../../';
-import StorybookLink from '../../../../../shared/storybook/StorybookLink';
-import {
-  BackToTopButton,
-  SwitchExample,
-  SwitchList,
-  UsageWrap,
-  ViewFigmaButton,
-} from '../../../docs/components';
-import * as Stories from './Switch.stories';
-
-<Meta title="Components / Switch" />
-
-<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components-%26-Tokens?node-id=3044-243&t=LTpZP1nQm1AOWfUF-4" />
-
-<BackToTopButton />
-
 # Switch
 
 The Switch component is used to indicate switching between two opposing options. Switches allow users
@@ -31,20 +13,16 @@ to turn an individual option on or off. They are usually used to activate or dea
 
 ## Playground
 
-<Canvas of={Stories.Playground} />
-
-<Controls of={Stories.Playground} />
+```tsx
+// Example usage
+<Switch {...args} value={toggled} onValueChange={handleToggle} />
+```
 
 ## Usage
 
-<UsageWrap>
-  <Center>
-    <SwitchExample />
-  </Center>
-</UsageWrap>
-
 ```tsx
-import { Switch } from '@utilitywarehouse/native-ui';
+// Example usage
+import { Switch } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => {
   const [settings, setSettings] = useState(false);
@@ -57,37 +35,58 @@ const MyComponent = () => {
 
 ## Props
 
-| Property      | Type                       | Default    | Description                            |
-| ------------- | -------------------------- | ---------- | -------------------------------------- |
-| value         | `boolean`                  | `false`    | The value of the switch                |
-| onValueChange | `(value: boolean) => void` | -          | Callback when the switch value changes |
-| disabled      | `boolean`                  | `false`    | If true, the switch will be disabled   |
-| size          | `'small' \| 'medium'`      | `'medium'` | The size of the switch                 |
+| Property      | Type                       | Default | Description                            |
+| ------------- | -------------------------- | ------- | -------------------------------------- |
+| value         | `boolean`                  | `false` | The value of the switch                |
+| onValueChange | `(value: boolean) => void` | -       | Callback when the switch value changes |
+| disabled      | `boolean`                  | `false` | If true, the switch will be disabled   |
+| size          | `'sm' \| 'md'`             | `'md'`  | The size of the switch                 |
 
 ## Variants
 
-<Canvas of={Stories.Variants} />
-
-## Examples
+```tsx
+// Example usage
+<Flex direction="column" spacing="sm">
+  <VariantTitle title="Off - medium">
+    <Switch value={false} />
+  </VariantTitle>
+  <VariantTitle title="On - medium">
+    <Switch value={true} />
+  </VariantTitle>
+  <VariantTitle title="Off - medium - Disabled">
+    <Switch value={false} disabled />
+  </VariantTitle>
+  <VariantTitle title="On - medium - Disabled">
+    <Switch value={true} disabled />
+  </VariantTitle>
+  <VariantTitle title="Off - small">
+    <Switch value={false} size="sm" />
+  </VariantTitle>
+  <VariantTitle title="On - small">
+    <Switch value={true} size="sm" />
+  </VariantTitle>
+  <VariantTitle title="Off - small - Disabled">
+    <Switch value={false} size="sm" disabled />
+  </VariantTitle>
+  <VariantTitle title="On - small - Disabled">
+    <Switch value={true} size="sm" disabled />
+  </VariantTitle>
+</Flex>
+```
 
 ### Switch with Label
 
 When the Switch is not placed in a List Item, you should use the `Label` component next to it. See
-the <StorybookLink to="forms-form-field">`FormField` documentation</StorybookLink> for more information.
-
-<UsageWrap>
-  <FormField>
-    <Flex spacing="sm" direction="row" align="center" justify="center">
-      <SwitchExample />
-      <FormFieldLabel>
-        <FormFieldLabelText>Enable notifications</FormFieldLabelText>
-      </FormFieldLabel>
-    </Flex>
-  </FormField>
-</UsageWrap>
+the `FormField` documentation for more information.
 
 ```tsx
-import { Switch, FormField, FormFieldLabel, FormFieldLabelText } from '@utilitywarehouse/native-ui';
+// Example usage
+import {
+  Switch,
+  FormField,
+  FormFieldLabel,
+  FormFieldLabelText,
+} from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => {
   const [notifications, setNotifications] = useState(false);
@@ -110,16 +109,13 @@ const MyComponent = () => {
 ### List with Switch
 
 You can also use the list to display a list of switches. You can achieve this by using the `Switch`
-component as the `trailingContent` of the `ListItem`. See the <StorybookLink to="native-ui-components-list">`List` documentation</StorybookLink>
+component as the `trailingContent` of the `ListItem`. See the `List` documentation
 for more information.
 
-<UsageWrap>
-  <SwitchList />
-</UsageWrap>
-
 ```tsx
+// Example usage
 import React, { useState } from 'react';
-import { Card, List, ListItem, ListItemIcon, Switch } from '@utilitywarehouse/native-ui';
+import { Card, List, ListItem, ListItemIcon, Switch } from '@utilitywarehouse/hearth-react-native';
 import {
   BellMediumIcon,
   LockMediumIcon,
@@ -140,7 +136,7 @@ const SwitchList = () => {
         helperText="Allow notifications"
         leadingContent={<ListItemIcon as={BellMediumIcon} />}
         trailingContent={
-          <Switch value={notifications} onValueChange={setNotifications} size="small" />
+          <Switch value={notifications} onValueChange={setNotifications} size="sm" />
         }
         onPress={() => setNotifications(!notifications)}
       />
@@ -148,21 +144,21 @@ const SwitchList = () => {
         text="Secure ID"
         helperText="Use secure ID"
         leadingContent={<ListItemIcon as={LockMediumIcon} />}
-        trailingContent={<Switch value={secureId} onValueChange={setSecureId} size="small" />}
+        trailingContent={<Switch value={secureId} onValueChange={setSecureId} size="sm" />}
         onPress={() => setSecureId(!secureId)}
       />
       <ListItem
         text="Location"
         helperText="Allow location"
         leadingContent={<ListItemIcon as={LocationMediumIcon} />}
-        trailingContent={<Switch value={location} onValueChange={setLocation} size="small" />}
+        trailingContent={<Switch value={location} onValueChange={setLocation} size="sm" />}
         onPress={() => setLocation(!location)}
       />
       <ListItem
         text="Dark mode"
         helperText="Enable dark mode"
         leadingContent={<ListItemIcon as={EyeMediumIcon} />}
-        trailingContent={<Switch value={darkMode} onValueChange={setDarkMode} size="small" />}
+        trailingContent={<Switch value={darkMode} onValueChange={setDarkMode} size="sm" />}
         onPress={() => setDarkMode(!darkMode)}
       />
     </List>

package/public/llms/components/table.md

@@ -0,0 +1,408 @@
+# Table
+
+Table arranges structured data into rows and columns, with optional pagination beneath the rows. The React Native version uses horizontal scrolling automatically when the columns need more space than the viewport allows.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Examples](#examples)
+
+## Playground
+
+```tsx
+// Example usage
+<Table {...args}>
+  <TableHeader color={headerColor}>
+    <TableHeaderCell
+      trailingContent={<HeaderSortButton inverted={headerInverted} label="Sort by name" />}
+    >
+      Name
+    </TableHeaderCell>
+    <TableHeaderCell
+      trailingContent={<HeaderSortButton inverted={headerInverted} label="Sort by email" />}
+    >
+      Email
+    </TableHeaderCell>
+    <TableHeaderCell
+      trailingContent={<HeaderSortButton inverted={headerInverted} label="Sort by phone" />}
+    >
+      Phone
+    </TableHeaderCell>
+    <TableHeaderCell
+      trailingContent={<HeaderSortButton inverted={headerInverted} label="Sort by city" />}
+    >
+      City
+    </TableHeaderCell>
+  </TableHeader>
+  <TableBody>
+    {rows.slice(0, 5).map(person => (
+      <TableRow key={person.id}>
+        <TableHeaderCell row>{person.name}</TableHeaderCell>
+        <TableCell>{person.email}</TableCell>
+        <TableCell>{person.phone}</TableCell>
+        <TableCell>{person.city}</TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+## Usage
+
+```tsx
+// Example usage
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHeader,
+  TableHeaderCell,
+  TableRow,
+} from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <Table container="subtle">
+    <TableHeader color="purple">
+      <TableHeaderCell>Name</TableHeaderCell>
+      <TableHeaderCell>Email</TableHeaderCell>
+      <TableHeaderCell>City</TableHeaderCell>
+    </TableHeader>
+    <TableBody>
+      <TableRow>
+        <TableHeaderCell row>Alex Morgan</TableHeaderCell>
+        <TableCell>alex@example.com</TableCell>
+        <TableCell>London</TableCell>
+      </TableRow>
+    </TableBody>
+  </Table>
+);
+```
+
+### Table Props
+
+| Property       | Type                                              | Description                                                                                             | Default     |
+| -------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------- |
+| `container`    | `'none' \| 'subtle' \| 'emphasis'`                | Applies the List-style outer container wrapping.                                                        | `'none'`    |
+| `columnWidths` | `(number \| '${number}fr' \| { flex: number })[]` | Optional per-column sizing. Use numbers for fixed widths and `'2fr'`-style values for flexible columns. | `undefined` |
+| `pagination`   | `ReactNode`                                       | Optional pagination content rendered below the rows.                                                    | `undefined` |
+
+### TableHeader Props
+
+| Property | Type                  | Description                                       | Default    |
+| -------- | --------------------- | ------------------------------------------------- | ---------- |
+| `color`  | `'purple' \| 'white'` | Controls the header background and text contrast. | `'purple'` |
+
+### TableHeaderCell Props
+
+| Property          | Type        | Description                                                | Default     |
+| ----------------- | ----------- | ---------------------------------------------------------- | ----------- |
+| `row`             | `boolean`   | Uses body-row header styling for the first cell in a row.  | `false`     |
+| `trailingContent` | `ReactNode` | Optional content aligned to the trailing edge of the cell. | `undefined` |
+
+### Containers
+
+```tsx
+// Example usage
+<Flex direction="column" spacing="xl" style={{ width: '100%' }}>
+  {[
+    { container: 'none' as const, color: 'white' as const },
+    { container: 'subtle' as const, color: 'purple' as const },
+    { container: 'emphasis' as const, color: 'purple' as const },
+  ].map(({ container, color }) => (
+    <Table key={`${container}-${color}`} container={container}>
+      <TableHeader color={color}>
+        <TableHeaderCell
+          trailingContent={<HeaderSortButton inverted={color === 'purple'} label="Sort by name" />}
+        >
+          Name
+        </TableHeaderCell>
+        <TableHeaderCell
+          trailingContent={<HeaderSortButton inverted={color === 'purple'} label="Sort by plan" />}
+        >
+          Plan
+        </TableHeaderCell>
+        <TableHeaderCell
+          trailingContent={
+            <HeaderSortButton inverted={color === 'purple'} label="Sort by status" />
+          }
+        >
+          Status
+        </TableHeaderCell>
+      </TableHeader>
+      <TableBody>
+        <TableRow>
+          <TableHeaderCell row>Alex Morgan</TableHeaderCell>
+          <TableCell>Full Fibre 900</TableCell>
+          <TableCell>Active</TableCell>
+        </TableRow>
+        <TableRow>
+          <TableHeaderCell row>Priya Shah</TableHeaderCell>
+          <TableCell>Energy Saver</TableCell>
+          <TableCell>Pending</TableCell>
+        </TableRow>
+      </TableBody>
+    </Table>
+  ))}
+</Flex>
+```
+
+```tsx
+// Example usage
+<Table container="subtle">
+  <TableHeader color="purple">
+    <TableHeaderCell>Name</TableHeaderCell>
+    <TableHeaderCell>Plan</TableHeaderCell>
+    <TableHeaderCell>Status</TableHeaderCell>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableHeaderCell row>Alex Morgan</TableHeaderCell>
+      <TableCell>Full Fibre 900</TableCell>
+      <TableCell>Active</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+### With pagination
+
+```tsx
+// Example usage
+<Table
+  {...args}
+  pagination={
+    <TablePagination
+      currentPage={currentPage}
+      onPageChange={setCurrentPage}
+      totalPages={totalPages}
+    />
+  }
+>
+  <TableHeader color={headerColor}>
+    <TableHeaderCell
+      trailingContent={<HeaderSortButton inverted={headerInverted} label="Sort by name" />}
+    >
+      Name
+    </TableHeaderCell>
+    <TableHeaderCell
+      trailingContent={<HeaderSortButton inverted={headerInverted} label="Sort by email" />}
+    >
+      Email
+    </TableHeaderCell>
+    <TableHeaderCell
+      trailingContent={<HeaderSortButton inverted={headerInverted} label="Sort by city" />}
+    >
+      City
+    </TableHeaderCell>
+  </TableHeader>
+  <TableBody>
+    {pageRows.map(person => (
+      <TableRow key={person.id}>
+        <TableHeaderCell row>{person.name}</TableHeaderCell>
+        <TableCell>{person.email}</TableCell>
+        <TableCell>{person.city}</TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+```tsx
+// Example usage
+const [currentPage, setCurrentPage] = useState(1);
+
+<Table
+  container="subtle"
+  pagination={
+    <TablePagination currentPage={currentPage} onPageChange={setCurrentPage} totalPages={10} />
+  }
+>
+  <TableHeader color="purple">
+    <TableHeaderCell>Name</TableHeaderCell>
+    <TableHeaderCell>Email</TableHeaderCell>
+    <TableHeaderCell>City</TableHeaderCell>
+  </TableHeader>
+  <TableBody>{/* paged rows */}</TableBody>
+</Table>;
+```
+
+### Narrow viewport
+
+```tsx
+// Example usage
+<Box style={{ width: 320 }}>
+  <Table
+    container="subtle"
+    pagination={
+      <TablePagination condensed currentPage={1} onPageChange={() => {}} totalPages={10} />
+    }
+  >
+    <TableHeader color="purple">
+      <TableHeaderCell trailingContent={<HeaderSortButton inverted label="Sort by account" />}>
+        Account
+      </TableHeaderCell>
+      <TableHeaderCell trailingContent={<HeaderSortButton inverted label="Sort by type" />}>
+        Type
+      </TableHeaderCell>
+      <TableHeaderCell trailingContent={<HeaderSortButton inverted label="Sort by monthly cost" />}>
+        Monthly cost
+      </TableHeaderCell>
+      <TableHeaderCell trailingContent={<HeaderSortButton inverted label="Sort by renewal" />}>
+        Renewal
+      </TableHeaderCell>
+    </TableHeader>
+    <TableBody>
+      <TableRow>
+        <TableHeaderCell row>Energy</TableHeaderCell>
+        <TableCell>Dual fuel</TableCell>
+        <TableCell>£132.50</TableCell>
+        <TableCell>12 Sep</TableCell>
+      </TableRow>
+      <TableRow>
+        <TableHeaderCell row>Broadband</TableHeaderCell>
+        <TableCell>Full Fibre 900</TableCell>
+        <TableCell>£44.00</TableCell>
+        <TableCell>22 Nov</TableCell>
+      </TableRow>
+    </TableBody>
+  </Table>
+</Box>
+```
+
+```tsx
+// Example usage
+<Box style={{ width: 320 }}>
+  <Table container="subtle">
+    <TableHeader color="purple">
+      <TableHeaderCell>Account</TableHeaderCell>
+      <TableHeaderCell>Type</TableHeaderCell>
+      <TableHeaderCell>Monthly cost</TableHeaderCell>
+      <TableHeaderCell>Renewal</TableHeaderCell>
+    </TableHeader>
+    <TableBody>{/* rows */}</TableBody>
+  </Table>
+</Box>
+```
+
+### Configured column widths
+
+```tsx
+// Example usage
+<Table columnWidths={[180, '2fr', '1fr', 140]} container="subtle">
+  <TableHeader color="purple">
+    <TableHeaderCell>Name</TableHeaderCell>
+    <TableHeaderCell>Email</TableHeaderCell>
+    <TableHeaderCell>Plan</TableHeaderCell>
+    <TableHeaderCell>Status</TableHeaderCell>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableHeaderCell row>Alex Morgan</TableHeaderCell>
+      <TableCell>alex.longer-email@example.com</TableCell>
+      <TableCell>Full Fibre 900</TableCell>
+      <TableCell>Active</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableHeaderCell row>Priya Shah</TableHeaderCell>
+      <TableCell>priya@example.com</TableCell>
+      <TableCell>Energy Saver</TableCell>
+      <TableCell>Pending</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+```tsx
+// Example usage
+<Table columnWidths={[180, '2fr', '1fr', 140]} container="subtle">
+  <TableHeader color="purple">
+    <TableHeaderCell>Name</TableHeaderCell>
+    <TableHeaderCell>Email</TableHeaderCell>
+    <TableHeaderCell>Plan</TableHeaderCell>
+    <TableHeaderCell>Status</TableHeaderCell>
+  </TableHeader>
+  <TableBody>{/* rows */}</TableBody>
+</Table>
+```
+
+### Custom sort function
+
+```tsx
+// Example usage
+<Table columnWidths={[180, '2fr', 120]} container="subtle">
+  <TableHeader color="purple">
+    <TableHeaderCell>Customer</TableHeaderCell>
+    <TableHeaderCell>Plan</TableHeaderCell>
+    <TableHeaderCell
+      trailingContent={
+        <UnstyledIconButton
+          accessibilityLabel="Sort by custom status order"
+          icon={ExpandSmallIcon}
+          inverted
+          onPress={() => setDirection(current => (current === 'asc' ? 'desc' : 'asc'))}
+          size="sm"
+        />
+      }
+    >
+      Status
+    </TableHeaderCell>
+  </TableHeader>
+  <TableBody>
+    {sortedRows.map(item => (
+      <TableRow key={item.id}>
+        <TableHeaderCell row>{item.customer}</TableHeaderCell>
+        <TableCell>{item.plan}</TableCell>
+        <TableCell>{item.status}</TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+```tsx
+// Example usage
+const statusOrder = {
+  Active: 0,
+  Pending: 1,
+  Paused: 2,
+  Cancelled: 3,
+} as const;
+
+const sortRowsByStatus = (items, direction = 'asc') => {
+  const multiplier = direction === 'asc' ? 1 : -1;
+
+  return [...items].sort((left, right) => {
+    const statusDifference = (statusOrder[left.status] - statusOrder[right.status]) * multiplier;
+
+    if (statusDifference !== 0) {
+      return statusDifference;
+    }
+
+    return left.customer.localeCompare(right.customer) * multiplier;
+  });
+};
+
+const [direction, setDirection] = useState<'asc' | 'desc'>('asc');
+const sortedRows = sortRowsByStatus(rows, direction);
+
+<Table columnWidths={[180, '2fr', 120]} container="subtle">
+  <TableHeader color="purple">
+    <TableHeaderCell>Customer</TableHeaderCell>
+    <TableHeaderCell>Plan</TableHeaderCell>
+    <TableHeaderCell
+      trailingContent={
+        <UnstyledIconButton
+          accessibilityLabel="Sort by custom status order"
+          icon={ExpandSmallIcon}
+          inverted
+          onPress={() => setDirection(current => (current === 'asc' ? 'desc' : 'asc'))}
+          size="sm"
+        />
+      }
+    >
+      Status
+    </TableHeaderCell>
+  </TableHeader>
+  <TableBody>{/* sortedRows */}</TableBody>
+</Table>;
+```