@utilitywarehouse/hearth-react-native 0.27.3 → 0.28.0

package/src/components/Table/Table.docs.mdx

@@ -0,0 +1,239 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import {
+  Box,
+  Center,
+  Table,
+  TableBody,
+  TableCell,
+  TableHeader,
+  TableHeaderCell,
+  TablePagination,
+  TableRow,
+} from '../..';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './Table.stories';
+
+<Meta title="Components / Table" />
+
+<BackToTopButton />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=6403-17515&t=pZwKJYFo1y1QRQD1-4" />
+
+# 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
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+<UsageWrap>
+  <Center>
+    <Box style={{ width: 520, maxWidth: '100%' }}>
+      <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>
+    </Box>
+  </Center>
+</UsageWrap>
+
+```tsx
+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>
+);
+```
+
+## Props
+
+### 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` |
+
+## Examples
+
+### Containers
+
+<Canvas of={Stories.Variants} />
+
+```tsx
+<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
+
+<Canvas of={Stories.WithPagination} />
+
+```tsx
+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
+
+<Canvas of={Stories.NarrowViewport} />
+
+```tsx
+<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
+
+<Canvas of={Stories.ConfiguredColumnWidths} />
+
+```tsx
+<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
+
+<Canvas of={Stories.WithCustomSortFunction} />
+
+```tsx
+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>;
+```

package/src/components/Table/Table.figma.tsx

@@ -0,0 +1,65 @@
+import figma from '@figma/code-connect';
+import { ExpandSmallIcon } from '@utilitywarehouse/hearth-react-native-icons';
+import { UnstyledIconButton } from '../UnstyledIconButton';
+import { Table, TableBody, TableCell, TableHeader, TableHeaderCell, TableRow } from './';
+
+figma.connect(
+  Table,
+  'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=6403-17515&t=pZwKJYFo1y1QRQD1-4',
+  {
+    props: {},
+    example: () => (
+      <Table container="subtle">
+        <TableHeader color="purple">
+          <TableHeaderCell
+            trailingContent={
+              <UnstyledIconButton
+                accessibilityLabel="Sort"
+                icon={ExpandSmallIcon}
+                inverted
+                size="sm"
+              />
+            }
+          >
+            Header
+          </TableHeaderCell>
+          <TableHeaderCell
+            trailingContent={
+              <UnstyledIconButton
+                accessibilityLabel="Sort"
+                icon={ExpandSmallIcon}
+                inverted
+                size="sm"
+              />
+            }
+          >
+            Header
+          </TableHeaderCell>
+        </TableHeader>
+        <TableBody>
+          <TableRow>
+            <TableHeaderCell row>Row title</TableHeaderCell>
+            <TableCell>Value</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>
+    ),
+  }
+);
+
+figma.connect(
+  TableHeaderCell,
+  'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=6414-6728&t=pZwKJYFo1y1QRQD1-4',
+  {
+    props: {},
+    example: () => (
+      <TableHeaderCell
+        trailingContent={
+          <UnstyledIconButton accessibilityLabel="Sort" icon={ExpandSmallIcon} size="sm" />
+        }
+      >
+        Header
+      </TableHeaderCell>
+    ),
+  }
+);

package/src/components/Table/Table.props.ts

@@ -0,0 +1,65 @@
+import type { ReactNode } from 'react';
+import type { ViewProps } from 'react-native';
+import type PaginationProps from '../Pagination/Pagination.props';
+
+export interface TableFlexibleColumnWidth {
+  flex: number;
+}
+
+export type TableColumnWidth = number | `${number}fr` | TableFlexibleColumnWidth;
+
+export interface TableProps extends ViewProps {
+  /**
+   * Controls whether the table is wrapped in a card container.
+   * @default 'none'
+   */
+  container?: 'emphasis' | 'subtle' | 'none';
+  /**
+   * Optional per-column sizing using fixed pixel widths or flexible fractions.
+   * Use numbers for fixed widths and values like `'2fr'` for flexible columns.
+   * Objects like `{ flex: 2 }` are also supported internally.
+   * Unspecified columns default to `1fr`.
+   */
+  columnWidths?: TableColumnWidth[];
+  /**
+   * Optional pagination controls rendered beneath the rows.
+   */
+  pagination?: React.ReactElement<PaginationProps> | ReactNode;
+}
+
+export interface TableBodyProps extends ViewProps {
+  children: ReactNode;
+}
+
+export interface TableHeaderProps extends ViewProps {
+  children: ReactNode;
+  /**
+   * Visual style for header cells.
+   * @default 'purple'
+   */
+  color?: 'purple' | 'white';
+}
+
+export interface TableRowProps extends ViewProps {
+  children: ReactNode;
+}
+
+export interface TableCellProps extends ViewProps {
+  children?: ReactNode;
+}
+
+export interface TableHeaderCellProps extends ViewProps {
+  children?: ReactNode;
+  color?: 'purple' | 'white';
+  /**
+   * Renders the header cell as a row header within the body.
+   * @default false
+   */
+  row?: boolean;
+  /**
+   * Optional content aligned to the end of a header cell.
+   */
+  trailingContent?: ReactNode;
+}
+
+export type TablePaginationProps = PaginationProps;