# Table

> Slug: `table` · Category: Data Visualization

## When to use
- Tabular data with consistent columns and rows — plan comparison, billing line items, settings matrices.
- You want strong typing across columns and data: `<Table<RowType>>` enforces that every column's `field` is a key of the row.

## When NOT to use
- A list of records that wrap or have rich content -> `List` / `Lists`.
- Single-record key/value display -> a definition list or `BroadbandFacts` for FCC labels.
- A chart -> `HybridBarChart`, `ProgressBar`, `ProgressRing`.

## Variants & decision tree
- Plain data table -> pass `columns` and `data`.
- Mark the leftmost identifying column as the row header for screen readers -> `isRowHeader: true` on that column.
- Inverse / dark surface -> `inverse`.

## States
- `inverse` — dark-background styling.
- No interactive states (sorting / pagination are out of scope).

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **`columns`** | `TableColumn<T>[]` | — | Column definitions. |
| **`data`** | `TableRow<T>[]` | — | Row records, typed by `T`. |
| **`ariaLabel`** | `string` | — | Required accessible name for the table region. |
| `inverse` | `boolean` | inherits | Dark-background styling. |
| `className` | `string` | — | Additional class names. |

`TableColumn<T>`: `{ header: string; field: keyof T; isRowHeader?: boolean }`.

## Usage examples
```tsx
import { Table } from 'arrow-react-bootstrap';

interface Plan { plan: string; speed: string; price: string }

<Table<Plan>
  ariaLabel="Plan comparison"
  columns={[
    { header: 'Plan',  field: 'plan',  isRowHeader: true },
    { header: 'Speed', field: 'speed' },
    { header: 'Price', field: 'price' },
  ]}
  data={[
    { plan: 'Basic',     speed: '300 Mbps', price: '$49/mo' },
    { plan: 'Pro',       speed: '1 Gbps',   price: '$99/mo' },
    { plan: 'Gigabit X', speed: '2 Gbps',   price: '$149/mo' },
  ]}
/>
```

## Composition
- Pair with a `SectionHeader` and short paragraph above the table.
- Inside a card, set `inverse` to inherit the card's tone.

## Accessibility
- `ariaLabel` is required — it provides the table's accessible name.
- Mark the identifying column with `isRowHeader: true` so each row is announced relative to that header.
- Cells render plain text; if you need formatted content, format upstream and pass strings.

## Do / Don't
- Do: type the table generically (`Table<Plan>`) — it catches field typos at compile time.
- Do: keep tables short; large datasets need pagination, which this component does not provide.
- Don't: use a table for layout — semantics matter for assistive tech.
- Don't: render interactive controls (`Button`, `MenuDropdown`) inside cells; use `List` rows for action-bearing content.
