@utilitywarehouse/hearth-react-native 0.1.0

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

@@ -0,0 +1,440 @@
+import { Meta, Canvas, Story, Controls } from '@storybook/addon-docs/blocks';
+import * as Stories from './List.stories';
+import { ViewFigmaButton, BackToTopButton, UsageWrap, BadgeList } from '../../../docs/components';
+import {
+  List,
+  ListHeading,
+  ListItem,
+  ListItemIcon,
+  ListItemLeadingContent,
+  ListItemHelperText,
+  ListItemText,
+  ListItemTrailingContent,
+  ListItemTrailingIcon,
+  ListItemContent,
+  Box,
+  Badge,
+  BadgeText,
+  FlatList,
+  Image,
+} from '../../';
+import {
+  BillMediumIcon,
+  ChevronRightSmallIcon,
+  PaymentMediumIcon,
+  HomeFilledMediumIcon,
+  UserMediumIcon,
+  ElectricityMediumIcon,
+  GasMediumIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+
+<Meta title="Components / List" />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components-%26-Tokens?node-id=1-163" />
+
+<BackToTopButton />
+
+# List
+
+The List component serves as the primary wrapper for List Items and List Heading components.
+
+List item is the main building block of list. Each item has its own set of properties that you can customise and adapt to suit your needs.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+  - [`List`](#list-1)
+  - [`ListHeading`](#listheading)
+  - [`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)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+<UsageWrap>
+  <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>
+</UsageWrap>
+
+```tsx
+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>
+);
+```
+
+## Props
+
+### `List`
+
+| Name                    | Type                                                                                              | Default   | Description                                                |
+| ----------------------- | ------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------- |
+| container               | `'none' \| 'subtleWhite' \| 'emphasisWhite' \|` <br /> `'subtleWarmWhite' \| 'emphasisWarmWhite'` | `'none'`  | The container style of the list.                           |
+| headingText             | `string`                                                                                          |           | The text to display in the heading of the list.            |
+| headingHelperText       | `string`                                                                                          |           | The supporting text to display in the heading of the list. |
+| headingLinkText         | `string`                                                                                          |           | The text for the link in the heading.                      |
+| headingLinkHref         | `string`                                                                                          |           | The href for the link in the heading.                      |
+| headingLinkOnPress      | `() => void`                                                                                      |           | Callback function when the heading link is pressed.        |
+| headingLinkTarget       | `'_blank' \| '_self' \| '_parent' \| '_top'`                                                      |           | Target for the link in the heading.                        |
+| headingLinkDisabled     | `boolean`                                                                                         | `false`   | Whether the heading link is disabled.                      |
+| headingLinkIcon         | `ComponentType`                                                                                   |           | Icon for the heading link.                                 |
+| headingLinkIconPosition | `'left' \| 'right'`                                                                               | `'right'` | Position of the icon in the heading link.                  |
+| headingLinkShowIcon     | `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.                               |
+
+### `ListHeading`
+
+| Name             | Type                                         | Default    | Description                                                |
+| ---------------- | -------------------------------------------- | ---------- | ---------------------------------------------------------- |
+| text             | `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 link is pressed.                |
+| linkTarget       | `'_blank' \| '_self' \| '_parent' \| '_top'` | `'_blank'` | Target for the link in the heading.                        |
+| linkDisabled     | `boolean`                                    | `false`    | Whether the link is disabled.                              |
+| linkIcon         | `ComponentType`                              |            | Icon for the link.                                         |
+| linkIconPosition | `'left' \| 'right'`                          | `'right'`  | Position of the icon in the link.                          |
+| linkShowIcon     | `boolean`                                    | `true`     | Whether to show the icon in the link.                      |
+
+#### - `ListHeadingText`
+
+#### - `ListHeadingHelperText`
+
+### `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.               |
+
+#### - `ListItemLeadingContent`
+
+#### - `ListItemIcon`
+
+| Name | Type            | Default | Description                                     |
+| ---- | --------------- | ------- | ----------------------------------------------- |
+| as   | `ComponentType` |         | The icon component to display in the list item. |
+
+#### - `ListItemContent`
+
+#### - `ListItemText`
+
+#### - `ListItemHelperText`
+
+#### - `ListItemTrailingContent`
+
+#### - `ListItemTrailingIcon`
+
+| Name | Type            | Default | Description                                     |
+| ---- | --------------- | ------- | ----------------------------------------------- |
+| as   | `ComponentType` |         | The icon component to display in the list item. |
+
+## Advanced Usage
+
+If you need to use the List component in a more advanced way, you can use the parts of the component directly.
+
+<UsageWrap>
+  <List>
+    <ListHeading text="Your account" helperText="Tap the links below to view your account" />
+    <ListItem onPress={() => console.log('pressed')}>
+      <ListItemLeadingContent>
+        <ListItemIcon as={BillMediumIcon} />
+      </ListItemLeadingContent>
+      <ListItemContent>
+        <ListItemText>Bills</ListItemText>
+        <ListItemHelperText>View your bills</ListItemHelperText>
+      </ListItemContent>
+      <ListItemTrailingContent>
+        <ListItemTrailingIcon as={ChevronRightSmallIcon} />
+      </ListItemTrailingContent>
+    </ListItem>
+    <ListItem onPress={() => console.log('pressed')}>
+      <ListItemLeadingContent>
+        <ListItemIcon as={PaymentMediumIcon} />
+      </ListItemLeadingContent>
+      <ListItemContent>
+        <ListItemText>Payments</ListItemText>
+        <ListItemHelperText>Make a payment</ListItemHelperText>
+      </ListItemContent>
+      <ListItemTrailingContent>
+        <ListItemTrailingIcon as={ChevronRightSmallIcon} />
+      </ListItemTrailingContent>
+    </ListItem>
+    <ListItem onPress={() => console.log('pressed')}>
+      <ListItemLeadingContent>
+        <ListItemIcon as={HomeFilledMediumIcon} />
+      </ListItemLeadingContent>
+      <ListItemContent>
+        <ListItemText>Moving home</ListItemText>
+        <ListItemHelperText>Tell us if your moving</ListItemHelperText>
+      </ListItemContent>
+      <ListItemTrailingContent>
+        <ListItemTrailingIcon as={ChevronRightSmallIcon} />
+      </ListItemTrailingContent>
+    </ListItem>
+    <ListItem onPress={() => console.log('pressed')}>
+      <ListItemLeadingContent>
+        <ListItemIcon as={UserMediumIcon} />
+      </ListItemLeadingContent>
+      <ListItemContent>
+        <ListItemText>Refer a friend</ListItemText>
+        <ListItemHelperText>Get rewarded with a friend</ListItemHelperText>
+      </ListItemContent>
+      <ListItemTrailingContent>
+        <ListItemTrailingIcon as={ChevronRightSmallIcon} />
+      </ListItemTrailingContent>
+    </ListItem>
+  </List>
+</UsageWrap>
+
+```tsx
+import {
+  List,
+  ListHeading,
+  ListItem,
+  ListItemIcon,
+  ListItemLeadingContent,
+  ListItemHelperText,
+  ListItemText,
+  ListItemTrailingContent,
+  ListItemTrailingIcon,
+  ListItemContent,
+} from '@utilitywarehouse/hearth-react-native';
+import {
+  BillMediumIcon,
+  ChevronRightSmallIcon,
+  PaymentMediumIcon,
+  HomeFilledMediumIcon,
+  UserMediumIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+
+const MyComponent = () => (
+  <List>
+    <ListHeading text="Your account" helperText="Tap the links below to view your account" />
+    <ListItem onPress={() => console.log('pressed')}>
+      <ListItemLeadingContent>
+        <ListItemIcon as={BillMediumIcon} />
+      </ListItemLeadingContent>
+      <ListItemContent>
+        <ListItemText>Bills</ListItemText>
+        <ListItemHelperText>View your bills</ListItemHelperText>
+      </ListItemContent>
+      <ListItemTrailingContent>
+        <ListItemTrailingIcon as={ChevronRightSmallIcon} />
+      </ListItemTrailingContent>
+    </ListItem>
+    <ListItem onPress={() => console.log('pressed')}>
+      <ListItemLeadingContent>
+        <ListItemIcon as={PaymentMediumIcon} />
+      </ListItemLeadingContent>
+      <ListItemContent>
+        <ListItemText>Payments</ListItemText>
+        <ListItemHelperText>Make a payment</ListItemHelperText>
+      </ListItemContent>
+      <ListItemTrailingContent>
+        <ListItemTrailingIcon as={ChevronRightSmallIcon} />
+      </ListItemTrailingContent>
+    </ListItem>
+    <ListItem onPress={() => console.log('pressed')}>
+      <ListItemLeadingContent>
+        <ListItemIcon as={HomeFilledMediumIcon} />
+      </ListItemLeadingContent>
+      <ListItemContent>
+        <ListItemText>Moving home</ListItemText>
+        <ListItemHelperText>Tell us if your moving</ListItemHelperText>
+      </ListItemContent>
+      <ListItemTrailingContent>
+        <ListItemTrailingIcon as={ChevronRightSmallIcon} />
+      </ListItemTrailingContent>
+    </ListItem>
+    <ListItem onPress={() => console.log('pressed')}>
+      <ListItemLeadingContent>
+        <ListItemIcon as={UserMediumIcon} />
+      </ListItemLeadingContent>
+      <ListItemContent>
+        <ListItemText>Refer a friend</ListItemText>
+        <ListItemHelperText>Get rewarded with a friend</ListItemHelperText>
+      </ListItemContent>
+      <ListItemTrailingContent>
+        <ListItemTrailingIcon as={ChevronRightSmallIcon} />
+      </ListItemTrailingContent>
+    </ListItem>
+  </List>
+);
+```
+
+## Variants
+
+The `List` component has different ways to display the list.
+
+<Canvas of={Stories.KitchenSink} />
+
+## Examples
+
+### List Item 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.
+
+<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={<HomeFilledMediumIcon />}
+      text="Moving Home"
+      onPress={() => console.log('item pressed')}
+    />
+  </List>
+</UsageWrap>
+
+```tsx
+import { List, ListItem, Card } from '@utilitywarehouse/hearth-react-native';
+import {
+  BillMediumIcon,
+  PaymentMediumIcon,
+  HomeFilledMediumIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+
+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={<HomeFilledMediumIcon />}
+      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="blue">
+            <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="green">
+              <BadgeText>Smart meter</BadgeText>
+            </Badge>
+          </Flex>
+          <ListItemHelperText>Last reading 23/03/24</ListItemHelperText>
+        </ListItemContent>
+        <ListItemTrailingContent>
+          <ListItemTrailingIcon as={ChevronRightSmallIcon} />
+        </ListItemTrailingContent>
+      </ListItem>
+    </List>
+  );
+};
+
+export default BadgeList;
+```

package/src/components/List/List.figma.tsx

@@ -0,0 +1,110 @@
+// /* eslint-disable react/jsx-no-undef */
+//
+// import { List } from './';
+// import figma from '@figma/code-connect';
+// import { Card } from '../Card';
+
+// const props = {
+//   heading: figma.nestedProps('List Heading', {
+//     text: figma.string('heading'),
+//     helperText: figma.string('Supporting text'),
+//   }),
+//   listItem: figma.children('List Item'),
+//   listItems: figma.children('List Items'),
+//   cardProps: figma.nestedProps('Card', {
+//     variant: figma.enum('variant', {
+//       dashed: 'dashed',
+//       elevated: 'elevated',
+//       outline: 'outline',
+//       filled: 'filled',
+//     }),
+//     padding: figma.enum('padding', {
+//       large: 'large',
+//       medium: 'medium',
+//       small: 'small',
+//       none: 'none',
+//     }),
+//     colorScheme: figma.enum('colorScheme', {
+//       base: 'base',
+//       grey: 'grey',
+//       purple: 'purple',
+//     }),
+//     surface: figma.enum('surface', {
+//       base: 'base',
+//       purple: 'purple',
+//     }),
+//   }),
+// };
+
+// figma.connect(
+//   List,
+//   'https://www.figma.com/design/3RY3OvLA88yZksRjOfjQJm/UW-App-UI?node-id=4643-17907&m=dev',
+//   {
+//     props,
+//     example: ({ listItems }) => <List>{listItems}</List>,
+//   }
+// );
+
+// figma.connect(
+//   List,
+//   'https://www.figma.com/design/3RY3OvLA88yZksRjOfjQJm/UW-App-UI?node-id=4643-17907&m=dev',
+//   {
+//     props,
+//     variant: {
+//       'Heading?': true,
+//     },
+//     example: ({ heading, listItems }) => (
+//       <List headingText={heading.text} headingHelperText={heading.helperText}>
+//         {listItems}
+//       </List>
+//     ),
+//   }
+// );
+
+// figma.connect(
+//   List,
+//   'https://www.figma.com/design/3RY3OvLA88yZksRjOfjQJm/UW-App-UI?node-id=4643-17907&m=dev',
+//   {
+//     props,
+//     variant: {
+//       container: 'tile',
+//       'Heading?': true,
+//     },
+//     example: ({ heading, listItems, cardProps }) => (
+//       <List
+//         container="card"
+//         headingText={heading.text}
+//         headingHelperText={heading.helperText}
+//       >
+//         <Card {...cardProps}>{listItems}</Card>
+//       </List>
+//     ),
+//   }
+// );
+
+// figma.connect(
+//   List,
+//   'https://www.figma.com/design/3RY3OvLA88yZksRjOfjQJm/UW-App-UI?node-id=4643-17907&m=dev',
+//   {
+//     props,
+//     variant: {
+//       container: 'tile',
+//       'Heading?': false,
+//     },
+//     example: ({ listItems, cardProps }) => (
+//       <List container="card">
+//         <Card {...cardProps}>{listItems}</Card>
+//       </List>
+//     ),
+//   }
+// );
+
+// figma.connect(
+//   List,
+//   'https://www.figma.com/design/3RY3OvLA88yZksRjOfjQJm/UW-App-UI?node-id=4623-14698&m=dev',
+//   {
+//     props,
+//     imports: [],
+//     example: ({ listItem }) => <>{listItem}</>,
+//   }
+// );

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

@@ -0,0 +1,21 @@
+import type { ViewProps } from 'react-native';
+import { ComponentType } from 'react';
+
+interface ListProps extends ViewProps {
+  container?: 'none' | 'subtleWhite' | 'emphasisWhite' | 'subtleWarmWhite' | 'emphasisWarmWhite';
+  headingText?: string;
+  headingHelperText?: string;
+  headingLinkText?: string;
+  headingLinkHref?: string;
+  headingLinkOnPress?: () => void;
+  headingLinkTarget?: '_blank' | '_self' | '_parent' | '_top';
+  headingLinkDisabled?: boolean;
+  headingLinkIcon?: ComponentType;
+  headingLinkIconPosition?: 'left' | 'right';
+  headingLinkShowIcon?: boolean;
+  disabled?: boolean;
+  loading?: boolean;
+  divider?: boolean;
+}
+
+export default ListProps;