first commit
This commit is contained in:
171
docs/ui/react/react-ui/src/components/table/table.md
Normal file
171
docs/ui/react/react-ui/src/components/table/table.md
Normal file
@@ -0,0 +1,171 @@
|
||||
# Table
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs --> - table.variants — `tableVariants` and its eight sub-…
|
||||
- [table.variants](./table.variants.md) — `tableVariants` and its eight sub-component cva resolvers (`tableHeaderVariants`, `tableBodyVariants`, `tableFooterVari…
|
||||
- table.variants — `tableVariants` and its eight sub-…
|
||||
|
||||
- [table.variants](./table.variants.md) — `tableVariants` and its eight sub-component cva resolvers (`tableHeaderVariants`, `tableBodyVariants`, `tableFooterVari…
|
||||
|
||||
- table.variants — `tableVariants` and its eight sub-…
|
||||
|
||||
- [table.variants](./table.variants.md) — `tableVariants` and its eight sub-component cva resolvers (`tableHeaderVariants`, `tableBodyVariants`, `tableFooterVari…
|
||||
|
||||
- table.variants — `tableVariants` and its eight sub-…
|
||||
|
||||
- [table.variants](./table.variants.md) — `tableVariants` and its eight sub-component cva resolvers (`tableHeaderVariants`, `tableBodyVariants`, `tableFooterVari…
|
||||
- [table.variants](./table.variants.md) — `tableVariants` and its eight sub-component cva resolvers (`tableHeaderVariants`, `tableBodyVariants`, `tableFooterVari…
|
||||
|
||||
## Purpose
|
||||
|
||||
`<Table>` is the chassis pure-HTML table family — `<Table>` (root, wrapping `<table>`), `<TableHeader>` (`<thead>`), `<TableBody>` (`<tbody>`), `<TableFooter>` (`<tfoot>`), `<TableRow>` (`<tr>`), `<TableHead>` (`<th>`), `<TableCell>` (`<td>`), `<TableCaption>` (`<caption>`). The chassis exposes NO variants — typography and spacing are baked in so every chassis table renders consistently across consumers. The root wraps the native `<table>` in an `overflow-auto` container so wide tables scroll horizontally without breaking the layout.
|
||||
|
||||
For a headless data-table with sorting, pagination, and selection on top of these primitives, use `<DataTable>`.
|
||||
|
||||
## Features
|
||||
|
||||
- Eight composition primitives mapping 1:1 to native HTML table elements.
|
||||
- `overflow-auto` wrapper on the root so wide tables scroll horizontally.
|
||||
- Logical-property text alignment (`text-start` on `<TableHead>`) so RTL renders correctly.
|
||||
- Hover + selected (`data-state="selected"`) row states on `<TableRow>`.
|
||||
- Footer reads as a summary surface (`bg-muted/50 font-medium`).
|
||||
- Caption sits below the table (`caption-bottom`) per conventional reading order.
|
||||
- All sub-components forward refs to their underlying native elements.
|
||||
|
||||
## Usage: Basic Example
|
||||
|
||||
```tsx
|
||||
import {
|
||||
Table,
|
||||
TableBody,
|
||||
TableCaption,
|
||||
TableCell,
|
||||
TableHead,
|
||||
TableHeader,
|
||||
TableRow,
|
||||
} from "@suaveplan/react-ui";
|
||||
|
||||
interface Invoice {
|
||||
readonly id: string;
|
||||
readonly status: string;
|
||||
readonly amount: string;
|
||||
}
|
||||
|
||||
export function InvoiceTable({ invoices }: { invoices: Invoice[] }) {
|
||||
return (
|
||||
<Table>
|
||||
<TableCaption>A list of recent invoices.</TableCaption>
|
||||
<TableHeader>
|
||||
<TableRow>
|
||||
<TableHead>ID</TableHead>
|
||||
<TableHead>Status</TableHead>
|
||||
<TableHead className="text-end">Amount</TableHead>
|
||||
</TableRow>
|
||||
</TableHeader>
|
||||
<TableBody>
|
||||
{invoices.map((invoice) => (
|
||||
<TableRow key={invoice.id}>
|
||||
<TableCell>{invoice.id}</TableCell>
|
||||
<TableCell>{invoice.status}</TableCell>
|
||||
<TableCell className="text-end">
|
||||
{invoice.amount}
|
||||
</TableCell>
|
||||
</TableRow>
|
||||
))}
|
||||
</TableBody>
|
||||
</Table>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Usage: Advanced Example
|
||||
|
||||
```tsx
|
||||
import {
|
||||
Table,
|
||||
TableBody,
|
||||
TableCell,
|
||||
TableFooter,
|
||||
TableHead,
|
||||
TableHeader,
|
||||
TableRow,
|
||||
} from "@suaveplan/react-ui";
|
||||
|
||||
export function OrderTotals({
|
||||
orders,
|
||||
grandTotal,
|
||||
}: {
|
||||
orders: Array<{ id: string; line: string; amount: number }>;
|
||||
grandTotal: number;
|
||||
}) {
|
||||
return (
|
||||
<Table>
|
||||
<TableHeader>
|
||||
<TableRow>
|
||||
<TableHead>Order</TableHead>
|
||||
<TableHead>Line</TableHead>
|
||||
<TableHead className="text-end">Amount</TableHead>
|
||||
</TableRow>
|
||||
</TableHeader>
|
||||
<TableBody>
|
||||
{orders.map((order) => (
|
||||
<TableRow key={order.id}>
|
||||
<TableCell>{order.id}</TableCell>
|
||||
<TableCell>{order.line}</TableCell>
|
||||
<TableCell className="text-end">
|
||||
${order.amount.toFixed(2)}
|
||||
</TableCell>
|
||||
</TableRow>
|
||||
))}
|
||||
</TableBody>
|
||||
<TableFooter>
|
||||
<TableRow>
|
||||
<TableCell colSpan={2}>Total</TableCell>
|
||||
<TableCell className="text-end">
|
||||
${grandTotal.toFixed(2)}
|
||||
</TableCell>
|
||||
</TableRow>
|
||||
</TableFooter>
|
||||
</Table>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### `<Table>`
|
||||
|
||||
`forwardRef<HTMLTableElement, TableProps>` — root `<table>` wrapped in `<div className="relative w-full overflow-auto">`.
|
||||
|
||||
### `<TableHeader>`, `<TableBody>`, `<TableFooter>`
|
||||
|
||||
`forwardRef<HTMLTableSectionElement, …>` — `<thead>`, `<tbody>`, `<tfoot>` row groups.
|
||||
|
||||
### `<TableRow>`
|
||||
|
||||
`forwardRef<HTMLTableRowElement, TableRowProps>` — `<tr>`. Hover + `data-state="selected"` background.
|
||||
|
||||
### `<TableHead>`
|
||||
|
||||
`forwardRef<HTMLTableCellElement, TableHeadProps>` — `<th>` header cell.
|
||||
|
||||
### `<TableCell>`
|
||||
|
||||
`forwardRef<HTMLTableCellElement, TableCellProps>` — `<td>` body cell.
|
||||
|
||||
### `<TableCaption>`
|
||||
|
||||
`forwardRef<HTMLTableCaptionElement, TableCaptionProps>` — `<caption>` rendered below the table.
|
||||
|
||||
#### Errors
|
||||
|
||||
The Table components do NOT call `useTranslation()` so they do not interact with the i18n provider. Children carrying user-perceivable text must be resolved at the call site.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- The chassis intentionally exposes NO `variant` axis on any sub-component — tables are pure-data surfaces and every chassis table should look the same. Consumers wanting different surfaces (zebra striping, dense layouts) override at the call site via `className` or register `variantOverrides` on their theme plugin.
|
||||
- The root wraps the native `<table>` in `<div className="relative w-full overflow-auto">` so wide tables scroll horizontally without breaking the page layout. This means refs forwarded to `<Table>` reach the inner `<table>`, NOT the outer `<div>`.
|
||||
- `<TableCaption>` always renders below the table thanks to `caption-bottom` on the root. Always include a caption (visually-hidden via `className="sr-only"` is acceptable) so screen-readers announce the table's purpose; tables without captions are unintelligible to screen-reader users.
|
||||
- `text-start` on `<TableHead>` uses Tailwind's logical-property class so the alignment flips automatically in RTL layouts. The same applies to `text-end` for right-aligned numeric columns — never use `text-left` / `text-right` in chassis-rendered tables.
|
||||
- The chassis does NOT inject any data-cell-binding behaviour. For a headless data-table with sorting, pagination, and selection on top of these primitives, use `<DataTable>` (which renders into the same `<Table>` family).
|
||||
Reference in New Issue
Block a user