@aircall/ds 0.13.0 → 0.15.0

package/skills/aircall-ds/migrate-tractor/combobox/SKILL.md

@@ -0,0 +1,346 @@
+---
+name: aircall-ds/migrate-tractor/combobox
+description: >
+  Migrate Tractor ComboBox (and the old Command + Popover search pattern) to the
+  @aircall/ds Combobox compound. Load when a file imports ComboBox, Command, or a
+  Command+Popover search combo from @aircall/tractor.
+type: sub-skill
+library: aircall-ds
+library_version: "0.13.0"
+requires:
+  - aircall-ds/setup
+  - aircall-ds/migrate-tractor
+sources:
+  - "aircall/hydra:docs/migration-guides/tractor-to-ds/recipes/combobox.md"
+---
+
+This skill builds on aircall-ds/migrate-tractor. Apply all cross-cutting rules from that skill (prop renames, `render` prop, data attributes) before the combobox-specific steps below.
+
+## 1. When to use Combobox vs Select
+
+Use `Combobox` when the user needs to **search or filter** options. For a short, fixed-enum list with no search, use `Select` instead (`aircall-ds/migrate-tractor/select`).
+
+## 2. Component mapping
+
+Tractor `ComboBox` was a single self-contained component. DS uses a compound structure where every visual slot is a named part. The old "Command + Popover" search recipe is fully replaced by this same compound.
+
+| Tractor / old pattern | DS compound part | Role |
+| --- | --- | --- |
+| `<ComboBox>` | `<Combobox>` | State owner (`value`, `onValueChange`, `multiple`) |
+| _(input built-in)_ | `<ComboboxInput>` | Visible text field (includes trigger chevron via `showTrigger`) |
+| _(trigger built-in)_ | `<ComboboxTrigger>` | Standalone chevron button (used inside custom layouts) |
+| _(no equivalent)_ | `<ComboboxContent>` | Popover container — handles portal + positioning |
+| _(no equivalent)_ | `<ComboboxList>` | Scrollable list inside the popover |
+| `<ComboBoxOption>` / `<CommandItem>` | `<ComboboxItem>` | Individual option |
+| _(no equivalent)_ | `<ComboboxEmpty>` | Shown automatically when the filtered list is empty |
+| _(no equivalent)_ | `<ComboboxGroup>` | Logical section wrapper |
+| _(no equivalent)_ | `<ComboboxLabel>` | Section heading (must be inside a `ComboboxGroup`) |
+| _(no equivalent)_ | `<ComboboxChips>` | Multi-select chip container (replaces custom tag inputs) |
+| _(no equivalent)_ | `<ComboboxChip>` | Individual removable chip inside `ComboboxChips` |
+| _(no equivalent)_ | `<ComboboxChipsInput>` | Inline input rendered inside `ComboboxChips` |
+| _(no equivalent)_ | `useComboboxAnchor()` | Returns a ref used to anchor `ComboboxContent` to a chips container |
+
+## 3. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Combobox, ComboboxChip, ComboboxChips, ComboboxChipsInput,
+ComboboxCollection, ComboboxContent, ComboboxEmpty, ComboboxGroup,
+ComboboxInput, ComboboxItem, ComboboxLabel, ComboboxList,
+ComboboxSeparator, ComboboxTrigger, ComboboxValue,
+useComboboxAnchor
+```
+
+All names used in the Before/After examples below exist in the published public API.
+
+## 4. Key prop differences
+
+| Tractor / old pattern | DS equivalent | Notes |
+| --- | --- | --- |
+| `onChange` | `onValueChange` | Signature: `(value: string \| null) => void` (single); `(value: string[]) => void` (multiple) |
+| `options={[…]}` | `<ComboboxItem>` children | Items are rendered declaratively, not via a data prop |
+| `multi` / `isMulti` | `multiple` on `<Combobox>` | Boolean flag; `value` and `onValueChange` then use `string[]` |
+| _(manual filter logic)_ | Built-in filtering | DS filters items automatically against typed input; opt out for async search by controlling `value` + `onChange` on `ComboboxInput` |
+| `showClear` _(absent)_ | `showClear` on `<ComboboxInput>` | Renders an X button that calls `ComboboxPrimitive.Clear` |
+
+## 5. Before / After
+
+### 5a. Single-select
+
+#### Before (Tractor)
+
+```tsx
+import { ComboBox, ComboBoxOption } from '@aircall/tractor';
+
+<ComboBox
+  value={country}
+  onChange={setCountry}
+  placeholder="Search countries"
+>
+  {countries.map(c => (
+    <ComboBoxOption key={c.iso} value={c.iso}>
+      {c.name}
+    </ComboBoxOption>
+  ))}
+</ComboBox>
+```
+
+#### After (DS)
+
+```tsx
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxGroup,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxLabel,
+  ComboboxList,
+} from '@aircall/ds';
+
+<Combobox value={country} onValueChange={setCountry}>
+  <ComboboxInput placeholder="Search countries" showTrigger />
+  <ComboboxContent>
+    <ComboboxList>
+      <ComboboxEmpty>No results.</ComboboxEmpty>
+      <ComboboxGroup>
+        <ComboboxLabel>Suggestions</ComboboxLabel>
+        {countries.map(c => (
+          <ComboboxItem key={c.iso} value={c.iso}>
+            {c.name}
+          </ComboboxItem>
+        ))}
+      </ComboboxGroup>
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+```
+
+### 5b. Multi-select with chips
+
+#### Before (Tractor — custom tag input pattern)
+
+```tsx
+import { ComboBox } from '@aircall/tractor';
+
+<ComboBox
+  multi
+  value={selected}
+  onChange={setSelected}
+  placeholder="Add a tag"
+  options={items}
+/>
+```
+
+#### After (DS)
+
+```tsx
+import {
+  Combobox,
+  ComboboxChip,
+  ComboboxChips,
+  ComboboxChipsInput,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxItem,
+  ComboboxList,
+  useComboboxAnchor,
+} from '@aircall/ds';
+
+function TagPicker() {
+  const [selected, setSelected] = React.useState<string[]>([]);
+  const anchorRef = useComboboxAnchor();
+
+  return (
+    <Combobox multiple value={selected} onValueChange={setSelected}>
+      <ComboboxChips ref={anchorRef}>
+        {selected.map(val => (
+          <ComboboxChip key={val} value={val}>
+            {items.find(i => i.value === val)?.label}
+          </ComboboxChip>
+        ))}
+        <ComboboxChipsInput placeholder="Add a tag" />
+      </ComboboxChips>
+      <ComboboxContent anchor={anchorRef}>
+        <ComboboxList>
+          <ComboboxEmpty>No results.</ComboboxEmpty>
+          {items.map(item => (
+            <ComboboxItem key={item.value} value={item.value}>
+              {item.label}
+            </ComboboxItem>
+          ))}
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>
+  );
+}
+```
+
+### 5c. Async / server-driven options
+
+Control the input value yourself and disable the built-in filter by rendering only the results you fetch.
+
+```tsx
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxList,
+} from '@aircall/ds';
+
+function ContactPicker({ onPick }: { onPick: (id: string) => void }) {
+  const [query, setQuery] = React.useState('');
+  const { data: results, loading } = useSearch(query);
+
+  return (
+    <Combobox onValueChange={onPick}>
+      <ComboboxInput
+        placeholder="Search contacts"
+        value={query}
+        onChange={e => setQuery(e.target.value)}
+      />
+      <ComboboxContent>
+        <ComboboxList>
+          {loading && <ComboboxEmpty>Searching…</ComboboxEmpty>}
+          {!loading && results.length === 0 && (
+            <ComboboxEmpty>No matches.</ComboboxEmpty>
+          )}
+          {results.map(r => (
+            <ComboboxItem key={r.id} value={r.id}>
+              {r.name}
+            </ComboboxItem>
+          ))}
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>
+  );
+}
+```
+
+## 6. Common Mistakes
+
+### Mistake 1 — Omitting `ComboboxList` and placing items directly in `ComboboxContent`
+
+```tsx
+// Wrong
+<ComboboxContent>
+  <ComboboxEmpty>No results.</ComboboxEmpty>
+  <ComboboxItem value="a">Alpha</ComboboxItem>
+</ComboboxContent>
+
+// Correct
+<ComboboxContent>
+  <ComboboxList>
+    <ComboboxEmpty>No results.</ComboboxEmpty>
+    <ComboboxItem value="a">Alpha</ComboboxItem>
+  </ComboboxList>
+</ComboboxContent>
+```
+
+`ComboboxContent` is the popover shell (portal + positioner + popup). The scrollable, filterable list — including `ComboboxEmpty` visibility logic — lives in `ComboboxList`. Placing items directly in `ComboboxContent` bypasses the scroll container and breaks the empty-state `group-data-empty` CSS selector that shows `ComboboxEmpty`.
+Source: `packages/ds/src/components/combobox.tsx`
+
+---
+
+### Mistake 2 — Forgetting `useComboboxAnchor` / not passing `anchor` for multi-select chips
+
+```tsx
+// Wrong — popover anchors to the document body, not the chips container
+<Combobox multiple value={selected} onValueChange={setSelected}>
+  <ComboboxChips>
+    {selected.map(val => <ComboboxChip key={val} value={val}>{val}</ComboboxChip>)}
+    <ComboboxChipsInput placeholder="Add a tag" />
+  </ComboboxChips>
+  <ComboboxContent>
+    <ComboboxList>
+      {items.map(i => <ComboboxItem key={i.value} value={i.value}>{i.label}</ComboboxItem>)}
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+
+// Correct
+const anchorRef = useComboboxAnchor();
+
+<Combobox multiple value={selected} onValueChange={setSelected}>
+  <ComboboxChips ref={anchorRef}>
+    {selected.map(val => <ComboboxChip key={val} value={val}>{val}</ComboboxChip>)}
+    <ComboboxChipsInput placeholder="Add a tag" />
+  </ComboboxChips>
+  <ComboboxContent anchor={anchorRef}>
+    <ComboboxList>
+      {items.map(i => <ComboboxItem key={i.value} value={i.value}>{i.label}</ComboboxItem>)}
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+```
+
+Without `anchor={anchorRef}`, `ComboboxContent` uses the default Combobox root as its positional reference, so the dropdown opens at the wrong position (above or misaligned with the chip container). `useComboboxAnchor()` returns a stable `ref` that must be attached to `ComboboxChips` and forwarded to `ComboboxContent`.
+Source: `packages/ds/src/components/combobox.tsx`
+
+---
+
+### Mistake 3 — Using a manual filter loop instead of the built-in filtering for static lists
+
+```tsx
+// Wrong — manual filter duplicates work the DS already does
+const [query, setQuery] = React.useState('');
+const visible = countries.filter(c =>
+  c.name.toLowerCase().includes(query.toLowerCase())
+);
+
+<Combobox value={country} onValueChange={setCountry}>
+  <ComboboxInput
+    placeholder="Search countries"
+    value={query}
+    onChange={e => setQuery(e.target.value)}
+  />
+  <ComboboxContent>
+    <ComboboxList>
+      {visible.map(c => (
+        <ComboboxItem key={c.iso} value={c.iso}>{c.name}</ComboboxItem>
+      ))}
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+
+// Correct — render all items; DS filters automatically
+<Combobox value={country} onValueChange={setCountry}>
+  <ComboboxInput placeholder="Search countries" showTrigger />
+  <ComboboxContent>
+    <ComboboxList>
+      <ComboboxEmpty>No results.</ComboboxEmpty>
+      {countries.map(c => (
+        <ComboboxItem key={c.iso} value={c.iso}>{c.name}</ComboboxItem>
+      ))}
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+```
+
+For static option lists, the DS Combobox (via Base UI) filters rendered items automatically against what the user types — no state or `filter` callback needed. Manual filtering is only required for async/server-driven lists where you control the results yourself.
+Source: `packages/ds/src/components/combobox.tsx`
+
+---
+
+### Mistake 4 — Placing `ComboboxLabel` directly in `ComboboxList` without a `ComboboxGroup`
+
+```tsx
+// Wrong
+<ComboboxList>
+  <ComboboxLabel>Suggestions</ComboboxLabel>
+  <ComboboxItem value="a">Alpha</ComboboxItem>
+</ComboboxList>
+
+// Correct
+<ComboboxList>
+  <ComboboxGroup>
+    <ComboboxLabel>Suggestions</ComboboxLabel>
+    <ComboboxItem value="a">Alpha</ComboboxItem>
+  </ComboboxGroup>
+</ComboboxList>
+```
+
+`ComboboxLabel` maps to Base UI's `ComboboxPrimitive.GroupLabel` — it is semantically scoped to a `ComboboxGroup`. Rendering it outside a group breaks the ARIA `group` association that screen readers rely on to announce the section heading.
+Source: `packages/ds/src/components/combobox.tsx`

package/skills/aircall-ds/migrate-tractor/data-table/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: aircall-ds/migrate-tractor/data-table
+description: >
+  Migrate Tractor Table and TableColumn to the @aircall/ds DataTable (TanStack
+  Table-backed). Load when a file imports Table or TableColumn from @aircall/tractor.
+  Covers column definitions, sorting, row selection, loading states, and empty states.
+type: sub-skill
+library: aircall-ds
+library_version: "0.13.0"
+requires:
+  - aircall-ds/setup
+  - aircall-ds/migrate-tractor
+sources:
+  - "aircall/hydra:packages/ds/src/components/data-table.tsx"
+---
+
+This skill builds on aircall-ds/migrate-tractor. Apply all cross-cutting rules from that skill (prop renames, `render` prop, data attributes) before the data-table-specific steps below.
+
+## 1. Architecture change
+
+Tractor `Table` was a self-contained component: you passed `data`, `columns` (a `TableColumn[]` descriptor array), and optional callbacks — Tractor handled layout, sorting state, and selection state internally.
+
+DS `DataTable` is built on **TanStack Table v8**. Columns are defined as `ColumnDef<TData>[]` (from `@tanstack/react-table`), sorting and selection state are controlled externally by the caller, and loading is expressed as a single `loadingState` string rather than a boolean `loading` flag.
+
+There is no sub-component API (no `<TableColumn>`) — everything is declared in `columns`.
+
+## 2. Component mapping
+
+| Tractor | @aircall/ds |
+| --- | --- |
+| `<Table data columns loading ...>` | `<DataTable data columns loadingState ...>` |
+| `TableColumn<T>` (object descriptor) | `ColumnDef<TData, unknown>` from `@tanstack/react-table` |
+| `columns[n].id` | `ColumnDef.id` (or accessor key) |
+| `columns[n].label` | `ColumnDef.header` |
+| `columns[n].renderer` | `ColumnDef.cell` (receives `{ row }`) |
+| `columns[n].sortable` | `ColumnDef.enableSorting` |
+| `loading={true}` | `loadingState="loading"` |
+| `noDataMessage` | `emptyState` (accepts any `ReactNode`) |
+| `onRowClick(record, event)` | `onRowClick(row)` (no `event` argument) |
+| `bulkActions` + `verticalScrollingParent` | `enableRowSelection` + `actionBar` |
+| `onOrderChange(columnId)` | `onSortingChange` (receives `SortingState`) + `sorting` |
+| `order` (`OrderInput`) | `sorting` (`SortingState`) |
+| `footer` | column-level `ColumnDef.footer` (auto-renders `<tfoot>`) |
+| _(no equivalent)_ | `loadingState="sorting"` / `"filtering"` (overlay spinner) |
+| _(no equivalent)_ | `loadingState="loadingMore"` (infinite scroll spinner row) |
+| _(no equivalent)_ | `onFetchMore` + `hasMore` (IntersectionObserver sentinel) |
+| _(no equivalent)_ | `fillHeight` (sticky header, internal scroll) |
+
+## 3. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+DataTable, type DataTableLoadingState
+```
+
+`@aircall/ds` **re-exports** the TanStack Table types you author — `ColumnDef`, `SortingState`, `RowSelectionState`, `OnChangeFn` — so **import them from `@aircall/ds`**, not `@tanstack/react-table`. The react-table runtime ships as a regular `@aircall/ds` dependency (auto-installed; `DataTable` owns the table instance internally), so there is nothing to install and no version to keep in sync.
+
+## 4. Imports
+
+```tsx
+import { DataTable, type DataTableLoadingState } from '@aircall/ds';
+import type { ColumnDef, SortingState, RowSelectionState, OnChangeFn } from '@aircall/ds';
+```
+
+## 5. Column definitions
+
+Tractor used a descriptor array (`TableColumn[]`) with a `renderer` function. DS uses `ColumnDef<TData>[]` from TanStack Table. The key changes:
+
+| Tractor `TableColumn` field | TanStack `ColumnDef` equivalent |
+| --- | --- |
+| `id` | `accessorKey` (auto-creates accessor) or `id` + `accessorFn` |
+| `label` | `header` (`ReactNode` or render function) |
+| `renderer(rowData, value, rowIndex)` | `cell: ({ row }) => row.original.<field>` |
+| `sortable: false` | `enableSorting: false` |
+| _(no equivalent)_ | `footer` (triggers `<tfoot>` rendering) |
+| _(no equivalent)_ | `size`, `minSize`, `maxSize` (for `enableColumnResizing`) |
+
+## 6. Before / After
+
+### 6a. Basic read-only table
+
+```tsx
+// Before
+import { Table, TableColumn } from '@aircall/tractor';
+
+type Person = { id: string; firstName: string; lastName: string; email: string };
+
+const columns: TableColumn<Person>[] = [
+  { id: 'firstName', label: 'First name' },
+  { id: 'lastName', label: 'Last name' },
+  {
+    id: 'email',
+    label: 'Email',
+    renderer: ({ email }) => <a href={`mailto:${email}`}>{email}</a>
+  }
+];
+
+<Table data={people} columns={columns} loading={isLoading} noDataMessage="No people found." />
+```
+
+```tsx
+// After
+import { DataTable } from '@aircall/ds';
+import type { ColumnDef } from '@aircall/ds';
+
+type Person = { id: string; firstName: string; lastName: string; email: string };
+
+const columns: ColumnDef<Person>[] = [
+  { accessorKey: 'firstName', header: 'First name' },
+  { accessorKey: 'lastName', header: 'Last name' },
+  {
+    accessorKey: 'email',
+    header: 'Email',
+    cell: ({ row }) => <a href={`mailto:${row.original.email}`}>{row.original.email}</a>
+  }
+];
+
+<DataTable
+  data={people}
+  columns={columns}
+  loadingState={isLoading ? 'loading' : 'idle'}
+  emptyState={<p className="text-sm text-muted-foreground">No people found.</p>}
+/>
+```
+
+### 6b. Server-side sortable table
+
+```tsx
+// Before
+import { Table, TableColumn, OrderInput } from '@aircall/tractor';
+import { OrderDirection } from '@aircall/tractor';
+
+const [order, setOrder] = React.useState<OrderInput>({ field: 'firstName', direction: OrderDirection.Asc });
+
+const columns: TableColumn<Person>[] = [
+  { id: 'firstName', label: 'First name', sortable: true },
+  { id: 'lastName', label: 'Last name', sortable: true },
+  { id: 'email', label: 'Email', sortable: false }
+];
+
+<Table
+  data={people}
+  columns={columns}
+  order={order}
+  onOrderChange={(columnId) => {
+    setOrder(prev => ({
+      field: columnId,
+      direction: prev.field === columnId && prev.direction === OrderDirection.Asc
+        ? OrderDirection.Desc
+        : OrderDirection.Asc
+    }));
+  }}
+/>
+```
+
+```tsx
+// After
+import { DataTable } from '@aircall/ds';
+import type { ColumnDef, SortingState, OnChangeFn } from '@aircall/ds';
+
+const [sorting, setSorting] = React.useState<SortingState>([{ id: 'firstName', desc: false }]);
+
+const columns: ColumnDef<Person>[] = [
+  { accessorKey: 'firstName', header: 'First name', enableSorting: true },
+  { accessorKey: 'lastName', header: 'Last name', enableSorting: true },
+  { accessorKey: 'email', header: 'Email', enableSorting: false }
+];
+
+<DataTable
+  data={people}
+  columns={columns}
+  sorting={sorting}
+  onSortingChange={setSorting}
+  loadingState={isSorting ? 'sorting' : 'idle'}
+/>
+```
+
+Key changes:
+- `order: OrderInput` → `sorting: SortingState` (array of `{ id, desc }` objects)
+- `onOrderChange(columnId)` → `onSortingChange: OnChangeFn<SortingState>` (receives the new full state)
+- A `loadingState="sorting"` dims the existing rows with an overlay spinner while the server re-queries — no skeleton flash
+
+### 6c. Selectable table with bulk action bar
+
+```tsx
+// Before
+import { Table, TableColumn } from '@aircall/tractor';
+
+const parentRef = React.useRef<HTMLDivElement | null>(null);
+
+<div ref={parentRef} style={{ height: '500px', overflowY: 'auto' }}>
+  <Table
+    data={people}
+    columns={columns}
+    verticalScrollingParent={parentRef}
+    bulkActions={[
+      { label: 'Delete', onExecute: (records) => deleteRecords(records) }
+    ]}
+  />
+</div>
+```
+
+```tsx
+// After
+import { DataTable } from '@aircall/ds';
+import { ActionBar, ActionBarButton } from '@aircall/ds';
+import type { RowSelectionState, OnChangeFn } from '@aircall/ds';
+
+const [rowSelection, setRowSelection] = React.useState<RowSelectionState>({});
+
+<DataTable
+  data={people}
+  columns={columns}
+  getRowId={(row) => row.id}
+  enableRowSelection
+  rowSelection={rowSelection}
+  onRowSelectionChange={setRowSelection}
+  actionBar={
+    <ActionBar>
+      <ActionBarButton variant="destructive" onClick={() => deleteSelected()}>
+        Delete
+      </ActionBarButton>
+    </ActionBar>
+  }
+/>
+```
+
+Key changes:
+- `verticalScrollingParent` is not needed — `DataTable` manages its own ActionBar positioning
+- `bulkActions` array → pass an `<ActionBar>` node to the `actionBar` prop
+- `onSelectionChange(selectedRows, count)` is replaced by controlled `rowSelection` state — derive selected records from `people.filter(p => rowSelection[p.id])`
+- `getRowId` is required when selection must survive data refreshes (server pagination)
+
+## 7. Common mistakes
+
+### Mistake 1 — Using `renderer` from `TableColumn` on a `ColumnDef`
+
+```tsx
+// Wrong — renderer is a Tractor TableColumn field; ColumnDef ignores it
+const columns: ColumnDef<Person>[] = [
+  {
+    accessorKey: 'email',
+    header: 'Email',
+    renderer: ({ email }) => <a href={`mailto:${email}`}>{email}</a>
+  }
+];
+
+// Correct — ColumnDef uses cell; the cell function receives the TanStack cell context
+const columns: ColumnDef<Person>[] = [
+  {
+    accessorKey: 'email',
+    header: 'Email',
+    cell: ({ row }) => <a href={`mailto:${row.original.email}`}>{row.original.email}</a>
+  }
+];
+```
+
+`ColumnDef` has no `renderer` field — passing it adds an unrecognised property that TypeScript will not catch (the field just becomes dead code). The cell always renders the raw accessor value. Use `cell: ({ row }) => …` and access typed row data via `row.original`.
+
+Source: `packages/ds/src/components/data-table.tsx`
+
+### Mistake 2 — Passing `loading={true}` instead of `loadingState="loading"`
+
+```tsx
+// Wrong — loading is a Tractor prop; DataTable has no loading prop
+<DataTable data={[]} columns={columns} loading={isLoading} />
+
+// Correct — use loadingState with one of the four async-state values
+<DataTable
+  data={[]}
+  columns={columns}
+  loadingState={isLoading ? 'loading' : 'idle'}
+/>
+```
+
+DS replaced the boolean `loading` flag with a discriminated `loadingState` string so that different async phases (`'loading'`, `'sorting'`, `'filtering'`, `'loadingMore'`) can produce different UX (skeleton rows vs. overlay spinner vs. bottom spinner row). Passing `loading` as a prop is silently ignored — the table renders the empty state or no rows instead of skeleton rows.
+
+Source: `packages/ds/src/components/data-table.tsx`
+
+### Mistake 3 — Deriving selected records from `onSelectionChange` instead of `rowSelection` state
+
+```tsx
+// Wrong — onSelectionChange does not exist on DataTable; selection is controlled via state
+<DataTable
+  enableRowSelection
+  onSelectionChange={(selectedRows) => setSelectedPeople(selectedRows)}
+  columns={columns}
+  data={people}
+/>
+
+// Correct — hold RowSelectionState; derive selected records from data + state when needed
+const [rowSelection, setRowSelection] = React.useState<RowSelectionState>({});
+const selectedPeople = people.filter(p => rowSelection[p.id]);
+
+<DataTable
+  enableRowSelection
+  rowSelection={rowSelection}
+  onRowSelectionChange={setRowSelection}
+  getRowId={(row) => row.id}
+  columns={columns}
+  data={people}
+/>
+```
+
+Tractor called `onSelectionChange(rows, count)` with the actual row objects. DS selection is fully controlled: `onRowSelectionChange` receives the new `RowSelectionState` (a record of `{ [rowId]: boolean }`). Derive selected rows by filtering your data array against the state object. Always provide `getRowId` so the IDs in `RowSelectionState` match your data's primary key.
+
+Source: `packages/ds/src/components/data-table.tsx`
+
+### Mistake 4 — Passing `noDataMessage` as a string instead of an `emptyState` node
+
+```tsx
+// Wrong — noDataMessage is a Tractor prop; DataTable renders nothing for it
+<DataTable data={[]} columns={columns} noDataMessage="No records found." />
+
+// Correct — emptyState accepts any ReactNode; render an Empty component for rich states
+import { Empty, EmptyContent, EmptyTitle, EmptyDescription } from '@aircall/ds';
+
+<DataTable
+  data={[]}
+  columns={columns}
+  emptyState={
+    <Empty>
+      <EmptyContent>
+        <EmptyTitle>No records found</EmptyTitle>
+        <EmptyDescription>Try adjusting your filters.</EmptyDescription>
+      </EmptyContent>
+    </Empty>
+  }
+/>
+```
+
+Tractor `noDataMessage` accepted a `ReactNode` but was declared as a simple prop. DS requires an `emptyState` prop; `noDataMessage` is silently ignored. For plain text, wrap it in a `<p>` with `text-sm text-muted-foreground`. For a full empty state with an icon and a call-to-action, use the `Empty` compound from `@aircall/ds`.
+
+Source: `packages/ds/src/components/data-table.tsx`