@utilitywarehouse/hearth-react-native 0.4.2 → 0.6.0

package/src/components/List/List.docs.mdx

@@ -25,6 +25,10 @@ import {
   ListItemTrailingContent,
   ListItemTrailingIcon,
   SectionHeader,
+  Switch,
+  Link,
+  ListAction,
+  BodyText,
 } from '../../';
 import { BackToTopButton, BadgeList, UsageWrap, ViewFigmaButton } from '../../../docs/components';
 import * as Stories from './List.stories';
@@ -46,15 +50,18 @@ List item is the main building block of list. Each item has its own set of prope
 - [Props](#props)
   - [`List`](#list-1)
   - [`ListItem`](#listitem)
-- [Advanced Usage](#advanced-usage)
-- [Variants](#variants)
 - [Examples](#examples)
-  - [List Item with Container](#list-item-with-container)
-  - [List Item with Badge](#list-item-with-badge)
-  - [Checbox List](#checbox-list)
-  - [Radio List](#radio-list)
-  - [Switch List](#switch-list)
-  - [List with FlatList](#list-with-flatlist)
+  - [`ListItem` with container](#listitem-with-container)
+  - [`ListItem` with `Badge`](#listitem-with-badge)
+  - [`ListItem` with `Switch`](#listitem-with-switch)
+  - [`List` with `SectionHeader`](#list-with-sectionheader)
+  - [`List` with `ListAction`](#list-with-listaction)
+  - [`ListItem` with transaction](#listitem-with-transaction)
+  - [`ListItem` with numeric value](#listitem-with-numeric-value)
+  - [`ListItem` with `Link`](#listitem-with-link)
+  - [`List` with `FlatList`](#list-with-flatlist)
+- [Advanced Usage](#advanced-usage)
+- [Accessibility](#accessibility)
 
 ## Playground
 
@@ -65,10 +72,10 @@ List item is the main building block of list. Each item has its own set of prope
 ## Usage
 
 <UsageWrap>
-  <List heading="Heading" helperText="Supporting text" divider>
-    <ListItem text="List Item 1" onPress={() => console.log('item pressed')} />
-    <ListItem text="List Item 2" onPress={() => console.log('item pressed')} />
-    <ListItem text="List Item 3" onPress={() => console.log('item pressed')} />
+  <List heading="Heading" helperText="Supporting text">
+    <ListItem heading="List Item 1" onPress={() => console.log('item pressed')} />
+    <ListItem heading="List Item 2" onPress={() => console.log('item pressed')} />
+    <ListItem heading="List Item 3" onPress={() => console.log('item pressed')} />
   </List>
 </UsageWrap>
 
@@ -76,10 +83,10 @@ List item is the main building block of list. Each item has its own set of prope
 import { List, ListItem } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => (
-  <List headingText="Heading" headingHelperText="Supporting text" divider>
-    <ListItem text="List Item 1" onPress={() => console.log('item pressed')} />
-    <ListItem text="List Item 2" onPress={() => console.log('item pressed')} />
-    <ListItem text="List Item 3" onPress={() => console.log('item pressed')} />
+  <List heading="Heading" helperText="Supporting text">
+    <ListItem heading="List Item 1" onPress={() => console.log('item pressed')} />
+    <ListItem heading="List Item 2" onPress={() => console.log('item pressed')} />
+    <ListItem heading="List Item 3" onPress={() => console.log('item pressed')} />
   </List>
 );
 ```
@@ -88,35 +95,38 @@ const MyComponent = () => (
 
 ### `List`
 
-| Name             | Type                                                                                              | Default   | Description                                                |
-| ---------------- | ------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------- | --- |
-| container        | `'none' \| 'subtleWhite' \| 'emphasisWhite' \|` <br /> `'subtleWarmWhite' \| 'emphasisWarmWhite'` | `'none'`  | The container style of the list.                           |
-| heading          | `string`                                                                                          |           | The text to display in the heading of the list.            |
-| helperText       | `string`                                                                                          |           | The supporting text to display in the heading of the list. |
-| linkText         | `string`                                                                                          |           | The text for the link in the heading.                      |
-| linkHref         | `string`                                                                                          |           | The href for the link in the heading.                      |
-| linkOnPress      | `() => void`                                                                                      |           | Callback function when the heading link is pressed.        |
-| linkTarget       | `'_blank' \| '_self' \| '_parent' \| '_top'`                                                      |           | Target for the link in the heading.                        |     |
-| linkIcon         | `ComponentType`                                                                                   |           | Icon for the heading link.                                 |
-| linkIconPosition | `'left' \| 'right'`                                                                               | `'right'` | Position of the icon in the heading link.                  |
-| linkShowIcon     | `boolean`                                                                                         | `true`    | Whether to show the icon in the heading link.              |
-| divider          | `boolean`                                                                                         | `false`   | Whether to display a divider below the list items.         |
-| loading          | `boolean`                                                                                         | `false`   | Whether to show the list items in loading state.           |
-| disabled         | `boolean`                                                                                         | `false`   | Whether to disable the list.                               |
+| Name                  | Type                                                                                              | Default  | Description                                                  |
+| --------------------- | ------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------ |
+| container             | `'none' \| 'subtleWhite' \| 'emphasisWhite' \|` <br /> `'subtleWarmWhite' \| 'emphasisWarmWhite'` | `'none'` | The container style of the list.                             |
+| heading               | `string`                                                                                          |          | The text to display in the heading of the list.              |
+| helperText            | `string`                                                                                          |          | The supporting text to display in the heading of the list.   |
+| headerTrailingContent | `ReactNode`                                                                                       |          | Optional content to display on the right side of the header. |
+| loading               | `boolean`                                                                                         | `false`  | Whether to show the list items in loading state.             |
+| disabled              | `boolean`                                                                                         | `false`  | Whether to disable the list.                                 |
 
 ### `ListItem`
 
-| Name            | Type                     | Default | Description                                                     |
-| --------------- | ------------------------ | ------- | --------------------------------------------------------------- |
-| text            | `string`                 |         | The text to display in the list item.                           |
-| onPress         | `() => void`             |         | A callback function to be called when the list item is pressed. |
-| helperText      | `string`                 |         | The supporting text to display in the list item.                |
-| leadingContent  | `ReactNode`              |         | The leading content to display in the list item.                |
-| trailingContent | `ReactNode`              |         | The trailing content to display in the list item.               |
-| variant         | `'subtle' \| 'emphasis'` |         | The variant style of the list item.                             |
-| disabled        | `boolean`                | `false` | Whether to disable the list item.                               |
-| loading         | `boolean`                | `false` | Whether to show the list item in loading state.                 |
-| divider         | `boolean`                | `false` | Whether to display a divider below the list item.               |
+| Name            | Type                     | Default  | Description                                                     |
+| --------------- | ------------------------ | -------- | --------------------------------------------------------------- |
+| heading         | `string`                 |          | The text to display in the list item.                           |
+| onPress         | `() => void`             |          | A callback function to be called when the list item is pressed. |
+| helperText      | `string`                 |          | The supporting text to display in the list item.                |
+| leadingContent  | `ReactNode`              |          | The leading content to display in the list item.                |
+| trailingContent | `ReactNode`              |          | The trailing content to display in the list item.               |
+| variant         | `'subtle' \| 'emphasis'` |          | The variant style of the list item.                             |
+| disabled        | `boolean`                | `false`  | Whether to disable the list item.                               |
+| loading         | `boolean`                | `false`  | Whether to show the list item in loading state.                 |
+| badge           | `BadgeProps`             |          | Props to pass to the Badge component.                           |
+| badgePosition   | `'top' \| 'bottom'`      | `bottom` | Position of the badge in the list item.                         |
+| numericValue    | `string \| number`       |          | A numeric value to display on the right side of the item.       |
+
+### `ListAction`
+
+| Name     | Type         | Default | Description                                  |
+| -------- | ------------ | ------- | -------------------------------------------- |
+| heading  | `string`     |         | The text to display in the list action item. |
+| onPress  | `() => void` |         | A callback function to be called             |
+| disabled | `boolean`    | `false` | Whether to disable the list action item.     |
 
 #### - `ListItemLeadingContent`
 
@@ -140,9 +150,319 @@ const MyComponent = () => (
 | ---- | --------------- | ------- | ----------------------------------------------- |
 | as   | `ComponentType` |         | The icon component to display in the list item. |
 
+## Examples
+
+### `ListItem` with Container
+
+Thie `List` has an inbuilt `Card` component to wrap the list items and setting the `container` prop to one if `subtleWhite`,
+`emphasisWhite`, `subtleWarmWhite`, or `emphasisWarmWhite` will apply the respective background color and border colour to
+the `Card` and child `ListItem` components.
+
+<Canvas of={Stories.WithContainer} />
+
+```tsx
+import { List, ListItem, Card } from '@utilitywarehouse/hearth-react-native';
+import {
+  BillMediumIcon,
+  PaymentMediumIcon,
+  HomeMediumIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+
+const MyComponent = () => (
+  <List container="subtleWhite">
+    <ListItem
+      leadingContent={<BillMediumIcon />}
+      heading="Bills"
+      onPress={() => console.log('item pressed')}
+    />
+    <ListItem
+      leadingContent={<PaymentMediumIcon />}
+      heading="Payments"
+      onPress={() => console.log('item pressed')}
+    />
+    <ListItem
+      leadingContent={<HomeMediumIcon />}
+      heading="Moving Home"
+      onPress={() => console.log('item pressed')}
+    />
+  </List>
+);
+```
+
+### `ListItem` with `Badge`
+
+You can use the `Badge` component to display additional information in the list item. You can achieve this by using the List Item's
+parts like `ListItemLeadingContent`, `ListItemContent`, and `ListItemTrailingContent` components.
+
+<Canvas of={Stories.WithBadge} />
+
+```tsx
+import { List, ListItem, IconContainer, Flex, Box } from '@utilitywarehouse/hearth-react-native';
+
+import { ElectricityMediumIcon, GasMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
+
+const BadgeList = () => {
+  return (
+    <List>
+      <ListItem
+        heading="Electricity"
+        helperText="Last reading 23/03/24"
+        onPress={() => console.log('pressed')}
+        leadingContent={
+          <IconContainer icon={ElectricityMediumIcon} size="md" variant="emphasis" color="energy" />
+        }
+        badge={{ text: 'Text' }}
+      />
+      <ListItem
+        heading="Gas"
+        helperText="Last reading 23/03/24"
+        onPress={() => console.log('pressed')}
+        leadingContent={
+          <IconContainer icon={GasMediumIcon} size="md" variant="emphasis" color="energy" />
+        }
+        badge={{ text: 'Smart Meter' }}
+      />
+    </List>
+  );
+};
+
+export default BadgeList;
+```
+
+### `ListItem` with `Switch`
+
+You can use a `Switch` component as the trailing content of a `ListItem` to create toggleable list items.
+
+<Canvas of={Stories.WithSwitch} />
+
+```tsx
+import { List, ListItem, Switch } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <List container="subtleWhite">
+    <ListItem
+      heading="Enable notifications"
+      helperText="Receive updates and alerts"
+      onPress={() => console.log('item pressed')}
+      trailingContent={
+        <Switch size="small" value={true} onValueChange={() => console.log('switch toggled')} />
+      }
+    />
+    <ListItem
+      heading="Dark mode"
+      helperText="Use dark theme throughout the app"
+      onPress={() => console.log('item pressed')}
+      trailingContent={
+        <Switch size="small" value={false} onValueChange={() => console.log('switch toggled')} />
+      }
+    />
+  </List>
+);
+```
+
+### `List` with `SectionHeader`
+
+You can use the `SectionHeader` component to add a heading and supporting text to your list.
+
+<Canvas of={Stories.WithSectionHeader} />
+
+```tsx
+import {
+  List,
+  ListItem,
+  ListItemIcon,
+  ListItemTrailingIcon,
+} from '@utilitywarehouse/hearth-react-native';
+import {
+  BillMediumIcon,
+  ChevronRightSmallIcon,
+  PaymentMediumIcon,
+  HomeMediumIcon,
+  UserMediumIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+
+const MyComponent = ({ navigate }) => (
+  <List
+    heading="Your account"
+    helperText="Tap the links below to view your account"
+    headerTrailingContent={<Link onPress={navigate('account')}>View all</Link>}
+  >
+    <ListItem
+      heading="Bills"
+      helperText="View your bills"
+      leadingContent={<ListItemIcon as={BillMediumIcon} />}
+      trailingContent={<ListItemTrailingIcon as={ChevronRightSmallIcon} />}
+      onPress={() => console.log('pressed')}
+    />
+    <ListItem
+      heading="Payments"
+      helperText="Make a payment"
+      leadingContent={<ListItemIcon as={PaymentMediumIcon} />}
+      trailingContent={<ListItemTrailingIcon as={ChevronRightSmallIcon} />}
+      onPress={() => console.log('pressed')}
+    />
+    <ListItem
+      heading="Moving home"
+      helperText="Tell us if you're moving"
+      leadingContent={<ListItemIcon as={HomeMediumIcon} />}
+      trailingContent={<ListItemTrailingIcon as={ChevronRightSmallIcon} />}
+      onPress={() => console.log('pressed')}
+    />
+    <ListItem
+      heading="Refer a friend"
+      helperText="Get rewarded with a friend"
+      leadingContent={<ListItemIcon as={UserMediumIcon} />}
+      trailingContent={<ListItemTrailingIcon as={ChevronRightSmallIcon} />}
+      onPress={() => console.log('pressed')}
+    />
+  </List>
+);
+```
+
+### `List` with `ListAction`
+
+You can use the `ListAction` component to add actionable items to your list.
+
+<Canvas of={Stories.WithListAction} />
+
+```tsx
+import {
+  List,
+  ListItem,
+  ListItemTrailingIcon,
+  ListAction,
+} from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <List container="subtleWarmWhite">
+    <ListItem
+      heading="Upgrade your plan"
+      helperText="Get more features with a premium plan"
+      onPress={() => console.log('Upgrade pressed')}
+    />
+    <ListItem
+      heading="Manage payment methods"
+      helperText="Update your credit or debit cards"
+      onPress={() => console.log('Manage pressed')}
+    />
+    <ListAction heading="Contact support" onPress={() => console.log('Contact pressed')} />
+  </List>
+);
+```
+
+### `ListItem` with transaction
+
+You can use the `ListItem` component to display transaction details.
+
+<Canvas of={Stories.WithTransactions} />
+
+```tsx
+import { List, ListItem, BodyText } from '@utilitywarehouse/hearth-react-native';
+const MyComponent = () => (
+  <List container="subtleWhite">
+    <ListItem
+      heading="Coffee Shop"
+      helperText="Apr 5, 2024"
+      trailingContent={
+        <>
+          <BodyText>-£100.00</BodyText>
+          <BodyText color="textBrand">-£100.00</BodyText>
+        </>
+      }
+      onPress={() => console.log('Transaction pressed')}
+    />
+    <ListItem
+      heading="Top up"
+      helperText="Apr 4, 2024"
+      trailingContent={
+        <>
+          <BodyText color="textAffirmative">+£100.00</BodyText>
+        </>
+      }
+      onPress={() => console.log('Transaction pressed')}
+    />
+  </List>
+);
+```
+
+### `ListItem` with numeric value
+
+You can use the `numericValue` prop to display a numeric value on the right side of the `ListItem`.
+
+<Canvas of={Stories.WithNumericValue} />
+
+```tsx
+import { List, ListItem } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <List container="subtleWhite">
+    <ListItem
+      heading="Steps today"
+      numericValue="8,542"
+      onPress={() => console.log('Steps pressed')}
+    />
+    <ListItem
+      heading="Calories burned"
+      numericValue="2,300 kcal"
+      onPress={() => console.log('Calories pressed')}
+    />
+  </List>
+);
+```
+
+### `ListItem` with `Link`
+
+You can use a `Link` component as the trailing content of a `ListItem` to create list items with links.
+
+<Canvas of={Stories.WithLink} />
+
+```tsx
+import { List, ListItem, Link } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <List container="subtleWhite">
+    <ListItem
+      heading="Terms of Service"
+      onPress={() => console.log('item pressed')}
+      trailingContent={<Link onPress={() => console.log('link pressed')}>View</Link>}
+    />
+    <ListItem
+      heading="Privacy Policy"
+      onPress={() => console.log('item pressed')}
+      trailingContent={<Link onPress={() => console.log('link pressed')}>View</Link>}
+    />
+  </List>
+);
+```
+
+### `List` with `FlatList`
+
+You can use the `FlatList` component to render a large list of items efficiently.
+
+```tsx
+import { FlatList } from 'react-native';
+import { List, ListItem } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <List container="subtleWhite">
+    <FlatList
+      data={[
+        { id: '1', heading: 'Item 1' },
+        { id: '2', heading: 'Item 2' },
+        { id: '3', heading: 'Item 3' },
+      ]}
+      renderItem={({ item }) => (
+        <ListItem heading={item.heading} onPress={() => console.log(`${item.heading} pressed`)} />
+      )}
+      keyExtractor={item => item.id}
+    />
+  </List>
+);
+```
+
 ## Advanced Usage
 
-If you need to use the List component in a more advanced way, you can use the parts of the component directly.
+If you need to use the `<List>` component in a more advanced way, you can use the parts of the component directly.
 
 <UsageWrap>
   <List>
@@ -274,147 +594,24 @@ const MyComponent = () => (
 );
 ```
 
-## Variants
+## Accessibility
 
-The `List` component has different ways to display the list.
+The List component is designed with accessibility in mind to ensure all users can interact with list items effectively.
 
-<Canvas of={Stories.KitchenSink} />
+### Screen Reader Support
 
-## Examples
+- **List Items with `onPress`**: When a `ListItem` has an `onPress` handler, it is automatically exposed to screen readers (VoiceOver on iOS and TalkBack on Android) as an interactive element. Users can focus on and activate these items using assistive technologies.
 
-### List Item with Container
+- **List Items without `onPress`**: Non-interactive list items are still accessible to screen readers, allowing users to navigate through and read the content. The list structure is preserved for context.
 
-Thie `List` has an inbuilt `Card` component to wrap the list items and setting the `container` prop to one if `subtleWhite`,
-`emphasisWhite`, `subtleWarmWhite`, or `emphasisWarmWhite` will apply the respective background color and border colour to
-the `Card` and child `ListItem` components.
+- **List with Container**: When using the `container` prop (e.g., `subtleWhite`, `emphasisWhite`), the List wraps items in a Card component. The Card wrapper itself is hidden from screen readers, but all ListItems remain fully accessible and focusable.
 
-<UsageWrap>
-  <List container="subtleWhite">
-    <ListItem
-      leadingContent={<BillMediumIcon />}
-      text="Bills"
-      divider
-      onPress={() => console.log('item pressed')}
-    />
-    <ListItem
-      leadingContent={<PaymentMediumIcon />}
-      text="Payments"
-      divider
-      onPress={() => console.log('item pressed')}
-    />
-    <ListItem
-      leadingContent={<HomeMediumIcon />}
-      text="Moving Home"
-      onPress={() => console.log('item pressed')}
-    />
-  </List>
-</UsageWrap>
+- **ListAction**: The `ListAction` component is always interactive and accessible as a button element with screen readers.
 
-```tsx
-import { List, ListItem, Card } from '@utilitywarehouse/hearth-react-native';
-import {
-  BillMediumIcon,
-  PaymentMediumIcon,
-  HomeMediumIcon,
-} from '@utilitywarehouse/hearth-react-native-icons';
+### Best Practices
 
-const MyComponent = () => (
-  <List container="subtleWhite">
-    <ListItem
-      leadingContent={<BillMediumIcon />}
-      text="Bills"
-      divider
-      onPress={() => console.log('item pressed')}
-    />
-    <ListItem
-      leadingContent={<PaymentMediumIcon />}
-      text="Payments"
-      divider
-      onPress={() => console.log('item pressed')}
-    />
-    <ListItem
-      leadingContent={<HomeMediumIcon />}
-      text="Moving Home"
-      onPress={() => console.log('item pressed')}
-    />
-  </List>
-);
-```
-
-### List Item with Badge
-
-You can use the `Badge` component to display additional information in the list item. You can achieve this by using the List Item's
-parts like `ListItemLeadingContent`, `ListItemContent`, and `ListItemTrailingContent` components.
-
-<UsageWrap>
-  <BadgeList />
-</UsageWrap>
-
-```tsx
-import {
-  List,
-  ListItem,
-  ListItemIcon,
-  ListItemLeadingContent,
-  ListItemHelperText,
-  ListItemText,
-  ListItemTrailingContent,
-  ListItemTrailingIcon,
-  ListItemContent,
-  Badge,
-  BadgeText,
-  Flex,
-  Box,
-} from '@utilitywarehouse/hearth-react-native';
-
-import {
-  ChevronRightSmallIcon,
-  ElectricityMediumIcon,
-  GasMediumIcon,
-} from '@utilitywarehouse/hearth-react-native-icons';
-
-const BadgeList = () => {
-  return (
-    <List>
-      <ListItem onPress={() => console.log('pressed')} divider>
-        <ListItemLeadingContent>
-          <Box padding="300" borderRadius="lg" bg={'energyBlue'}>
-            <ListItemIcon as={ElectricityMediumIcon} color="green900" />
-          </Box>
-        </ListItemLeadingContent>
-        <ListItemContent>
-          <ListItemText>Electricity</ListItemText>
-          <Badge colorScheme="info">
-            <BadgeText>Text</BadgeText>
-          </Badge>
-          <ListItemHelperText>Last reading 23/03/24</ListItemHelperText>
-        </ListItemContent>
-        <ListItemTrailingContent>
-          <ListItemTrailingIcon as={ChevronRightSmallIcon} />
-        </ListItemTrailingContent>
-      </ListItem>
-      <ListItem onPress={() => console.log('pressed')} divider={false}>
-        <ListItemLeadingContent>
-          <Box padding="300" borderRadius="lg" bg={'energyBlue'}>
-            <ListItemIcon as={GasMediumIcon} color="green900" />
-          </Box>
-        </ListItemLeadingContent>
-        <ListItemContent>
-          <Flex direction="row" style={{ justifyContent: 'space-between' }}>
-            <ListItemText>Gas</ListItemText>
-            <Badge colorScheme="positive">
-              <BadgeText>Smart meter</BadgeText>
-            </Badge>
-          </Flex>
-          <ListItemHelperText>Last reading 23/03/24</ListItemHelperText>
-        </ListItemContent>
-        <ListItemTrailingContent>
-          <ListItemTrailingIcon as={ChevronRightSmallIcon} />
-        </ListItemTrailingContent>
-      </ListItem>
-    </List>
-  );
-};
-
-export default BadgeList;
-```
+- Use descriptive `heading` and `helperText` to provide clear context for each list item
+- Ensure `onPress` handlers provide meaningful feedback for interactive items
+- When using custom content with `children`, ensure all interactive elements are properly labeled
+- Test with VoiceOver (iOS) and TalkBack (Android) to verify the experience
+- Avoid nesting too many interactive elements within a single ListItem to prevent confusion

package/src/components/List/List.props.ts

@@ -1,20 +1,12 @@
 import type { ViewProps } from 'react-native';
-import { ComponentType } from 'react';
 
 interface ListProps extends ViewProps {
   container?: 'none' | 'subtleWhite' | 'emphasisWhite' | 'subtleWarmWhite' | 'emphasisWarmWhite';
   heading?: string;
   helperText?: string;
-  linkText?: string;
-  linkHref?: string;
-  linkIcon?: ComponentType;
-  linkIconPosition?: 'left' | 'right';
-  linkOnPress?: () => void;
-  linkTarget?: '_blank' | '_self' | '_parent' | '_top';
-  linkShowIcon?: boolean;
+  headerTrailingContent?: React.ReactNode;
   disabled?: boolean;
   loading?: boolean;
-  divider?: boolean;
 }
 
 export default ListProps;