feat(ui): implement comprehensive Table component system with compound API
This commit is contained in:
27 files changed
+2016
-7
No files matched your search
@@ -0,0 +1,138 @@
|
||||
# Table Component Design
|
||||
|
||||
**Date:** 2026-02-08
|
||||
**Status:** Approved
|
||||
**Topic:** Core Table Primitives for Rainby Design System
|
||||
|
||||
## 1. Overview
|
||||
|
||||
A comprehensive, accessible, and highly composable set of Table components. The goal is to provide a direct counterpart to every native HTML table element, styled according to the Rainby Design System, while offering a specialized `Cell` helper to manage common content layouts (alignment, icons, truncation) without enforcing complex logic.
|
||||
|
||||
## 2. Architecture
|
||||
|
||||
The solution uses a **Context-based** architecture. The root `Table` component accepts high-level style props (`density`, `variant`) and propagates them to all child components via React Context. This avoids prop-drilling and ensures visual consistency.
|
||||
|
||||
### Components
|
||||
|
||||
- **`TableContainer`**: Wrapper for responsive scrolling and outer boundary styling.
|
||||
- **`Table`**: Root element. Manages context.
|
||||
- **`TableHeader`** (`thead`), **`TableBody`** (`tbody`), **`TableFooter`** (`tfoot`): Semantic wrappers.
|
||||
- **`TableRow`** (`tr`): Handles row-level states (hover, striping).
|
||||
- **`TableHead`** (`th`): Header cells.
|
||||
- **`TableCell`** (`td`): Data cells.
|
||||
- **`TableCaption`** (`caption`): Accessible description.
|
||||
- **`Cell`**: **(New)** A polymorphic layout primitive for content _inside_ cells.
|
||||
|
||||
## 3. API & Props
|
||||
|
||||
### 3.1 `Table` (Root)
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
| :------------- | :---------------------------------- | :---------- | :-------------------------------------------- |
|
||||
| `density` | `'s' \| 'm' \| 'l'` | `'m'` | Controls padding of all cells. |
|
||||
| `variant` | `'surface' \| 'outline' \| 'ghost'` | `'surface'` | Controls borders and backgrounds. |
|
||||
| `striped` | `boolean` | `false` | Enables zebra-striping on rows. |
|
||||
| `hoverable` | `boolean` | `false` | Enables hover effects on rows. |
|
||||
| `stickyHeader` | `boolean` | `false` | Fixes the header to the top of the container. |
|
||||
|
||||
### 3.2 `Cell` (Content Helper)
|
||||
|
||||
Used strictly for _layout and styling_ within a `TableCell` or `TableHead`. It does **not** handle sorting logic.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
| :--------- | :--------------------------------------------- | :---------- | :--------------------------------- |
|
||||
| `variant` | `'text' \| 'numeric' \| 'icon' \| 'checkbox'` | `'text'` | Presets for alignment and spacing. |
|
||||
| `layout` | `'flex' \| 'stack'` | `'flex'` | Internal flex direction. |
|
||||
| `align` | `'start' \| 'center' \| 'end' \| 'between'` | _(auto)_ | Flex alignment overrides. |
|
||||
| `truncate` | `boolean` | `false` | Forces single-line ellipsis. |
|
||||
| `color` | `'default' \| 'muted' \| 'error' \| 'success'` | `'default'` | Text color token mapping. |
|
||||
|
||||
## 4. Styling Strategy
|
||||
|
||||
### Visual Tokens
|
||||
|
||||
Mappings to Rainby CSS variables:
|
||||
|
||||
- **Backgrounds**: `bg-surface` (default), `bg-muted/50` (headers/striped).
|
||||
- **Borders**: `border-border` (outline), `border-b` only (ghost).
|
||||
- **Text**: `text-foreground` (body), `text-muted-foreground` (headers/icons).
|
||||
|
||||
### Density Map
|
||||
|
||||
- **Small (`s`)**: `px-3 py-2 text-sm`
|
||||
- **Medium (`m`)**: `px-4 py-3 text-sm`
|
||||
- **Large (`l`)**: `px-6 py-4 text-base`
|
||||
|
||||
## 5. Usage Example
|
||||
|
||||
```tsx
|
||||
import {
|
||||
TableContainer,
|
||||
Table,
|
||||
TableHeader,
|
||||
TableBody,
|
||||
TableRow,
|
||||
TableHead,
|
||||
TableCell,
|
||||
Cell,
|
||||
} from '@ermnvldmr/ui';
|
||||
|
||||
export const UserList = () => (
|
||||
<TableContainer>
|
||||
<Table density="m" variant="surface" striped hoverable>
|
||||
<TableHeader>
|
||||
<TableRow>
|
||||
<TableHead>
|
||||
<Cell variant="checkbox">
|
||||
<Checkbox />
|
||||
</Cell>
|
||||
</TableHead>
|
||||
<TableHead>
|
||||
<Cell>User</Cell>
|
||||
</TableHead>
|
||||
<TableHead>
|
||||
<Cell variant="numeric">Revenue</Cell>
|
||||
</TableHead>
|
||||
<TableHead>
|
||||
<Cell variant="icon">Actions</Cell>
|
||||
</TableHead>
|
||||
</TableRow>
|
||||
</TableHeader>
|
||||
|
||||
<TableBody>
|
||||
<TableRow>
|
||||
<TableCell>
|
||||
<Cell variant="checkbox">
|
||||
<Checkbox />
|
||||
</Cell>
|
||||
</TableCell>
|
||||
<TableCell>
|
||||
{/* Complex Content Layout */}
|
||||
<Cell layout="flex" gap="m">
|
||||
<Avatar src="..." />
|
||||
<Cell layout="stack" gap="s">
|
||||
<span className="font-medium">Jane Doe</span>
|
||||
<span className="text-muted-foreground text-xs">Admin</span>
|
||||
</Cell>
|
||||
</Cell>
|
||||
</TableCell>
|
||||
<TableCell>
|
||||
<Cell variant="numeric">$1,200.00</Cell>
|
||||
</TableCell>
|
||||
<TableCell>
|
||||
<Cell variant="icon">
|
||||
<Button variant="ghost" size="s" icon="more-horizontal" />
|
||||
</Cell>
|
||||
</TableCell>
|
||||
</TableRow>
|
||||
</TableBody>
|
||||
</Table>
|
||||
</TableContainer>
|
||||
);
|
||||
```
|
||||
|
||||
## 6. Implementation Notes
|
||||
|
||||
- **Accessibility**: Ensure `th` elements have `scope="col"` or `scope="row"` automatically where possible, or allow override. `TableCaption` is critical for screen readers.
|
||||
- **Polymorphism**: `TableContainer` should probably just be a `div`, but `Table` components must forward refs to underlying DOM nodes.
|
||||
- **Sorting**: Sorting UI is manual. Users will wrap `Cell` content in a button or place a sort icon next to it manually.
|
||||
Reference in new issue
Block a user