@cdx-ui/components 0.2.3 → 0.2.4

package/docs/components/table/content.md

@@ -0,0 +1,548 @@
+# Table (https://design.candescent.com/docs/components/table)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/data-visualization-table--default)
+
+`Table` is a presentational compound component for rendering tabular data. Compose header, body, footer, and cell sub-slots declaratively. For a web data-driven grid with sort, filters, selection, and pagination, use `DataGrid` from `@cdx-ui/data-grid`. Sorting, filtering, and pagination on `Table` itself are consumer responsibilities.
+
+```tsx
+import { Table } from '@cdx-ui/components';
+```
+
+## Basic
+
+Use `Table.Caption` for an accessible title, then compose `Table.Header`, `Table.Body`, and rows of `Table.Head` / `Table.Cell` cells.
+
+```tsx
+import { Table } from '@cdx-ui/components';
+
+const invoices = [
+  { id: 'INV001', status: 'Paid', method: 'Credit Card', amount: '$250.00' },
+  { id: 'INV002', status: 'Pending', method: 'PayPal', amount: '$150.00' },
+  { id: 'INV003', status: 'Unpaid', method: 'Bank Transfer', amount: '$350.00' },
+];
+
+export default function TableBasicDemo() {
+  return (
+    <Table>
+      <Table.Caption>A list of your recent invoices.</Table.Caption>
+      <Table.Header>
+        <Table.Row>
+          <Table.Head>Invoice</Table.Head>
+          <Table.Head>Status</Table.Head>
+          <Table.Head>Method</Table.Head>
+          <Table.Head align="end">Amount</Table.Head>
+        </Table.Row>
+      </Table.Header>
+      <Table.Body>
+        {invoices.map((invoice) => (
+          <Table.Row key={invoice.id}>
+            <Table.Cell>{invoice.id}</Table.Cell>
+            <Table.Cell>{invoice.status}</Table.Cell>
+            <Table.Cell>{invoice.method}</Table.Cell>
+            <Table.Cell align="end">{invoice.amount}</Table.Cell>
+          </Table.Row>
+        ))}
+      </Table.Body>
+    </Table>
+  );
+}
+```
+
+Set `fullBleed` on the root when the table should align flush with a parent container — the first column drops left padding and the last column drops right padding on every row.
+
+```tsx
+<Table fullBleed>{/* ... */}</Table>
+```
+
+## Footer
+
+`Table.Footer` groups summary rows such as totals. On web, pass `colSpan` to merge cells.
+
+```tsx
+import { Table } from '@cdx-ui/components';
+
+const invoices = [
+  { id: 'INV001', status: 'Paid', amount: '$250.00' },
+  { id: 'INV002', status: 'Pending', amount: '$150.00' },
+];
+
+export default function TableWithFooterDemo() {
+  return (
+    <Table>
+      <Table.Caption>Recent invoices</Table.Caption>
+      <Table.Header>
+        <Table.Row>
+          <Table.Head>Invoice</Table.Head>
+          <Table.Head>Status</Table.Head>
+          <Table.Head align="end">Amount</Table.Head>
+        </Table.Row>
+      </Table.Header>
+      <Table.Body>
+        {invoices.map((invoice) => (
+          <Table.Row key={invoice.id}>
+            <Table.Cell>{invoice.id}</Table.Cell>
+            <Table.Cell>{invoice.status}</Table.Cell>
+            <Table.Cell align="end">{invoice.amount}</Table.Cell>
+          </Table.Row>
+        ))}
+      </Table.Body>
+      <Table.Footer>
+        <Table.Row>
+          <Table.Cell colSpan={2}>Total</Table.Cell>
+          <Table.Cell align="end">$400.00</Table.Cell>
+        </Table.Row>
+      </Table.Footer>
+    </Table>
+  );
+}
+```
+
+## Rich cells
+
+Cells can compose text, status indicators, and other Forge UI components. Tables with more columns remain horizontally scrollable on compact screens.
+
+```tsx
+import { Box, Chip, Table, Text } from '@cdx-ui/components';
+
+const transactions = [
+  {
+    merchant: 'Northstar Market',
+    detail: 'Groceries · Sep 8',
+    category: 'Groceries',
+    color: 'success',
+    status: 'Posted',
+    amount: '−$86.42',
+  },
+  {
+    merchant: 'Cloud Nine Media',
+    detail: 'Subscription · Sep 7',
+    category: 'Entertainment',
+    color: 'info',
+    status: 'Posted',
+    amount: '−$18.99',
+  },
+  {
+    merchant: 'City Electric',
+    detail: 'Autopay · Sep 6',
+    category: 'Utilities',
+    color: 'warning',
+    status: 'Pending',
+    amount: '−$124.30',
+  },
+] as const;
+
+export default function TableRichCellsDemo() {
+  return (
+    <Table accessibilityLabel="Recent account activity">
+      <Table.Header>
+        <Table.Row>
+          <Table.Head>Merchant</Table.Head>
+          <Table.Head>Category</Table.Head>
+          <Table.Head>Status</Table.Head>
+          <Table.Head align="end">Amount</Table.Head>
+        </Table.Row>
+      </Table.Header>
+      <Table.Body>
+        {transactions.map((transaction) => (
+          <Table.Row key={transaction.merchant}>
+            <Table.Cell>
+              <Box className="gap-0.5">
+                <Text weight="medium" numberOfLines={1}>
+                  {transaction.merchant}
+                </Text>
+                <Text size="sm" color="secondary" numberOfLines={1}>
+                  {transaction.detail}
+                </Text>
+              </Box>
+            </Table.Cell>
+            <Table.Cell>
+              <Chip size="small" color={transaction.color}>
+                <Chip.Label>{transaction.category}</Chip.Label>
+              </Chip>
+            </Table.Cell>
+            <Table.Cell>{transaction.status}</Table.Cell>
+            <Table.Cell align="end">{transaction.amount}</Table.Cell>
+          </Table.Row>
+        ))}
+      </Table.Body>
+    </Table>
+  );
+}
+```
+
+## Row actions
+
+Compose interactive controls such as `Menu` inside `Table.Cell` for per-row actions. Use the
+logical `align` prop to align both text and composed content with RTL support.
+
+```tsx
+import { IconButton, Menu, Table } from '@cdx-ui/components';
+import { MoreHoriz } from '@cdx-ui/icons';
+
+const products = [
+  { name: 'Wireless Mouse', price: '$29.99' },
+  { name: 'Mechanical Keyboard', price: '$129.99' },
+];
+
+export default function TableRowActionsDemo() {
+  return (
+    <Table fullBleed>
+      <Table.Header>
+        <Table.Row>
+          <Table.Head>Product</Table.Head>
+          <Table.Head align="end">Price</Table.Head>
+          <Table.Head align="end">Actions</Table.Head>
+        </Table.Row>
+      </Table.Header>
+      <Table.Body>
+        {products.map((product) => (
+          <Table.Row key={product.name}>
+            <Table.Cell>{product.name}</Table.Cell>
+            <Table.Cell align="end">{product.price}</Table.Cell>
+            <Table.Cell align="end">
+              <Menu placement="bottom-end">
+                <Menu.Trigger asChild>
+                  <IconButton
+                    as={MoreHoriz}
+                    accessibilityLabel={`Actions for ${product.name}`}
+                    variant="ghost"
+                    size="small"
+                  />
+                </Menu.Trigger>
+                <Menu.Popup>
+                  <Menu.Content accessibilityLabel={`${product.name} actions`}>
+                    <Menu.Item>
+                      <Menu.ItemLabel>Edit</Menu.ItemLabel>
+                    </Menu.Item>
+                    <Menu.Item color="danger">
+                      <Menu.ItemLabel>Delete</Menu.ItemLabel>
+                    </Menu.Item>
+                  </Menu.Content>
+                </Menu.Popup>
+              </Menu>
+            </Table.Cell>
+          </Table.Row>
+        ))}
+      </Table.Body>
+    </Table>
+  );
+}
+```
+
+## In card
+
+On mobile, a headerless table can present key-value summaries inside a card. Pair it with a compact visual summary built from layout primitives while chart components are unavailable, and keep the values in the table as the accessible source of detail.
+
+```tsx
+import { Box, Card, Heading, HStack, Table, Text } from '@cdx-ui/components';
+
+const categories = [
+  {
+    name: 'Rent',
+    amount: '$2,240',
+    percent: 42,
+    indicatorClassName: 'bg-surface-action-strong',
+    dotClassName: 'size-3 rounded-full bg-surface-action-strong',
+  },
+  {
+    name: 'Entertainment',
+    amount: '$1,015',
+    percent: 19,
+    indicatorClassName: 'bg-surface-info-strong',
+    dotClassName: 'size-3 rounded-full bg-surface-info-strong',
+  },
+  {
+    name: 'Dining out',
+    amount: '$685',
+    percent: 13,
+    indicatorClassName: 'bg-surface-warning-strong',
+    dotClassName: 'size-3 rounded-full bg-surface-warning-strong',
+  },
+  {
+    name: 'Utilities',
+    amount: '$520',
+    percent: 10,
+    indicatorClassName: 'bg-surface-success-strong',
+    dotClassName: 'size-3 rounded-full bg-surface-success-strong',
+  },
+  {
+    name: 'Other',
+    amount: '$865',
+    percent: 16,
+    indicatorClassName: 'bg-surface-secondary',
+    dotClassName: 'size-3 rounded-full bg-surface-secondary',
+  },
+] as const;
+
+export default function TableMobileSpendingBreakdownDemo() {
+  return (
+    <Card className="w-full max-w-sm overflow-hidden">
+      <Card.Stripe />
+      <Card.Header>
+        <Heading size="sm">Spending this month</Heading>
+      </Card.Header>
+      <Card.Content className="gap-5">
+        <Box className="items-center gap-1 py-2">
+          <Text size="xl" weight="semibold">
+            $5,325
+          </Text>
+          <Text size="sm" weight="semibold" color="secondary" className="uppercase">
+            Total
+          </Text>
+        </Box>
+        <Box
+          accessible
+          accessibilityLabel="Rent 42%, entertainment 19%, dining out 13%, utilities 10%, other 16%"
+          className="h-3 flex-row overflow-hidden rounded-full"
+        >
+          {categories.map((category) => (
+            <Box
+              key={category.name}
+              className={category.indicatorClassName}
+              style={{ flex: category.percent }}
+            />
+          ))}
+        </Box>
+        <Table fullBleed accessibilityLabel="Spending by category">
+          <Table.Body>
+            {categories.map((category) => (
+              <Table.Row key={category.name}>
+                <Table.Cell>
+                  <HStack space="sm" className="items-center">
+                    <Box className={category.dotClassName} />
+                    <Text numberOfLines={1}>{category.name}</Text>
+                  </HStack>
+                </Table.Cell>
+                <Table.Cell align="end">{category.amount}</Table.Cell>
+                <Table.Cell align="end">{category.percent}%</Table.Cell>
+              </Table.Row>
+            ))}
+          </Table.Body>
+        </Table>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+```tsx
+import { Box, Card, Chip, Heading, HStack, Table, Text } from '@cdx-ui/components';
+
+const spendingDays = [
+  { day: 'M', barClassName: 'h-10 w-1.5 rounded-full bg-surface-action-strong' },
+  { day: 'T', barClassName: 'h-8 w-1.5 rounded-full bg-surface-action-strong' },
+  { day: 'W', barClassName: 'h-10 w-1.5 rounded-full bg-surface-action-strong' },
+  { day: 'T', barClassName: 'h-9 w-1.5 rounded-full bg-surface-action-strong' },
+  { day: 'F', barClassName: 'h-8 w-1.5 rounded-full bg-surface-action-strong' },
+  { day: 'S', barClassName: 'h-16 w-1.5 rounded-full bg-surface-warning-strong' },
+  { day: 'S', barClassName: 'h-20 w-1.5 rounded-full bg-surface-warning-strong' },
+] as const;
+
+export default function TableMobileSpendingComparisonDemo() {
+  return (
+    <Card className="w-full max-w-sm overflow-hidden">
+      <Card.Stripe />
+      <Card.Header className="flex-row items-center justify-between">
+        <Heading size="sm">Spending patterns</Heading>
+        <Chip size="small" color="warning">
+          <Chip.Label>Review</Chip.Label>
+        </Chip>
+      </Card.Header>
+      <Card.Content className="gap-5">
+        <Box className="gap-0.5">
+          <Text size="xl" weight="semibold">
+            40%
+          </Text>
+          <Text weight="medium">more on weekends</Text>
+        </Box>
+        <HStack
+          accessible
+          accessibilityLabel="Daily spending rises from Monday through Sunday and is highest on weekends"
+          className="items-end justify-between px-2"
+        >
+          {spendingDays.map((entry, index) => (
+            <Box key={`${entry.day}-${String(index)}`} className="items-center gap-2">
+              <Box className="h-20 justify-end">
+                <Box className={entry.barClassName} />
+              </Box>
+              <Text size="sm">{entry.day}</Text>
+            </Box>
+          ))}
+        </HStack>
+        <Table fullBleed accessibilityLabel="Average spending comparison">
+          <Table.Body>
+            <Table.Row>
+              <Table.Cell>Weekend average</Table.Cell>
+              <Table.Cell align="end">$89</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Weekday average</Table.Cell>
+              <Table.Cell align="end">$52</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+## API
+
+### Table
+
+Root table container. On web, renders semantic `<table>` markup inside a horizontally scrollable wrapper. On native, renders a horizontally scrollable flex layout.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `fullBleed?` | `boolean \| null` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `containerStyle?` | `ViewStyle` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute   | Values  | Description    |
+| ----------- | ------- | -------------- |
+| `data-slot` | `table` | Root container |
+
+## Sub-components
+
+### Table.Caption
+
+Accessible table title or summary.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+| Attribute   | Values          | Description |
+| ----------- | --------------- | ----------- |
+| `data-slot` | `table-caption` | Caption     |
+
+### Table.Header
+
+Header section containing header rows. Renders `<thead>` on web.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute   | Values         | Description    |
+| ----------- | -------------- | -------------- |
+| `data-slot` | `table-header` | Header section |
+
+### Table.Body
+
+Body section containing data rows. Renders `<tbody>` on web.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute   | Values       | Description  |
+| ----------- | ------------ | ------------ |
+| `data-slot` | `table-body` | Body section |
+
+### Table.Footer
+
+Footer section for totals and summaries. Renders `<tfoot>` on web.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute   | Values         | Description    |
+| ----------- | -------------- | -------------- |
+| `data-slot` | `table-footer` | Footer section |
+
+### Table.Row
+
+A single table row. Renders `<tr>` on web.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute   | Values      | Description |
+| ----------- | ----------- | ----------- |
+| `data-slot` | `table-row` | Table row   |
+
+### Table.Head
+
+Header cell within a header row. Renders `<th scope="col">` on web by default.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `align?` | `'start' \| 'center' \| 'end'` | `'start'` | Logical horizontal alignment for text and composed content. |
+| `colSpan?` | `number` | — | — |
+| `rowSpan?` | `number` | — | — |
+| `scope?` | `'col' \| 'row' \| 'colgroup' \| 'rowgroup'` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props). Accepts logical `align`, `colSpan`, `rowSpan`, and `scope` (web).
+
+| Attribute   | Values       | Description |
+| ----------- | ------------ | ----------- |
+| `data-slot` | `table-head` | Header cell |
+
+### Table.Cell
+
+Data cell within a body or footer row. Renders `<td>` on web.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `align?` | `'start' \| 'center' \| 'end'` | `'start'` | Logical horizontal alignment for text and composed content. |
+| `colSpan?` | `number` | — | — |
+| `rowSpan?` | `number` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props). Accepts logical `align`, `colSpan`, and `rowSpan` (web).
+
+| Attribute   | Values       | Description |
+| ----------- | ------------ | ----------- |
+| `data-slot` | `table-cell` | Data cell   |
+
+## Anatomy
+
+| `data-slot`     | Element         |
+| --------------- | --------------- |
+| `table`         | `Table`         |
+| `table-caption` | `Table.Caption` |
+| `table-header`  | `Table.Header`  |
+| `table-body`    | `Table.Body`    |
+| `table-footer`  | `Table.Footer`  |
+| `table-row`     | `Table.Row`     |
+| `table-head`    | `Table.Head`    |
+| `table-cell`    | `Table.Cell`    |
+
+## Accessibility
+
+On web, `Table` renders native table semantics (`table`, `thead`, `tbody`, `tfoot`, `tr`, `th`, `td`, `caption`). Use `Table.Caption` or `accessibilityLabel` on the root so screen readers can identify the table.
+
+On native, rows and cells use flex layout with header/text roles. For complex grids requiring full screen-reader table navigation, prefer web or validate with VoiceOver and TalkBack during review.