@aircall/ds 0.14.0 → 0.15.0

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`

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

@@ -0,0 +1,206 @@
+---
+name: aircall-ds/migrate-tractor/dialog
+description: >
+  Migrate Tractor Modal (ModalDialog, ModalHeader, ModalTitle, ModalBody,
+  ModalFooter) to the @aircall/ds Dialog compound. Load when a file imports Modal*
+  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/dialog.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 dialog-specific steps below.
+
+## 1. Component mapping
+
+| Tractor | @aircall/ds |
+| --- | --- |
+| `Modal` (state owner + panel) | `Dialog` (state owner) + `DialogContent` (panel) |
+| `ModalHeader` | `DialogHeader` |
+| `ModalTitle` | `DialogTitle` |
+| `ModalBody` | — (plain children inside `DialogContent`, no wrapper) |
+| `ModalFooter` | `DialogFooter` |
+| — | `DialogTrigger` (uncontrolled open trigger) |
+| — | `DialogClose` (any button that closes the dialog) |
+| — | `DialogDescription` (optional accessible subtitle) |
+
+## 2. Imports
+
+```tsx
+import {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+  Button
+} from '@aircall/ds';
+```
+
+## 3. Before / After
+
+### Controlled (most common — replaces `<Modal isOpen={…} onClose={…}>`)
+
+```tsx
+// Before
+import { Modal, ModalHeader, ModalTitle, ModalBody, ModalFooter, Button } from '@aircall/tractor';
+
+<Modal isOpen={isOpen} onClose={() => setIsOpen(false)} size="regular">
+  <ModalHeader>
+    <ModalTitle>Confirm delete</ModalTitle>
+  </ModalHeader>
+  <ModalBody>
+    <p>This will permanently remove the contact. Are you sure?</p>
+  </ModalBody>
+  <ModalFooter>
+    <Button variant="outline" onClick={() => setIsOpen(false)}>Cancel</Button>
+    <Button variant="critical" onClick={onConfirm}>Delete</Button>
+  </ModalFooter>
+</Modal>
+
+// After
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose, Button } from '@aircall/ds';
+
+<Dialog open={isOpen} onOpenChange={setIsOpen}>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Confirm delete</DialogTitle>
+      <DialogDescription>
+        This will permanently remove the contact.
+      </DialogDescription>
+    </DialogHeader>
+
+    <p className="text-sm">Are you sure?</p>
+
+    <DialogFooter>
+      <DialogClose render={<Button variant="outline" size="lg" />}>
+        Cancel
+      </DialogClose>
+      <Button variant="destructive" size="lg" onClick={onConfirm}>
+        Delete
+      </Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+Key changes:
+- `isOpen` → `open`; `onClose(reason)` → `onOpenChange(boolean)`
+- `ModalBody` is removed — body content is plain children inside `DialogContent`
+- `DialogClose` wraps any button that should close the dialog; pass the DS `Button` via `render` and put the label as children of `DialogClose`, not of the inner Button
+- `variant="critical"` → `variant="destructive"` (Button)
+
+### Uncontrolled with a trigger
+
+```tsx
+// After
+<Dialog>
+  <DialogTrigger render={<Button size="lg" />}>Open settings</DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Settings</DialogTitle>
+    </DialogHeader>
+    {/* body content */}
+    <DialogFooter>
+      <DialogClose render={<Button variant="outline" size="lg" />}>Close</DialogClose>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### Size
+
+`Dialog` has no built-in `size` prop. For the Tractor `size="large"` case, set width on `DialogContent`:
+
+```tsx
+// Tractor: size="large"
+<DialogContent className="max-w-2xl">…</DialogContent>
+```
+
+### Hiding the default close button
+
+`DialogContent` renders a default "×" close button in the top-right. Hide it when you want to force the user to use a footer action:
+
+```tsx
+<DialogContent showCloseButton={false}>…</DialogContent>
+```
+
+---
+
+## 4. Common mistakes
+
+### Mistake 1 — Passing `onClose` instead of `onOpenChange`
+
+```tsx
+// ❌ Wrong — onClose is a Tractor prop; DS ignores it silently
+<Dialog open={isOpen} onClose={() => setIsOpen(false)}>…</Dialog>
+
+// ✅ Correct — onOpenChange receives the new boolean state
+<Dialog open={isOpen} onOpenChange={setIsOpen}>…</Dialog>
+```
+
+`onOpenChange` fires with `false` when the dialog closes (backdrop click, Escape, or `DialogClose`). Widen your handler if you were using the Tractor `reason` argument — DS does not pass a reason.
+
+Source: `packages/ds/src/components/dialog.tsx`
+
+### Mistake 2 — Keeping `ModalBody` or wrapping body content in `DialogBody`
+
+```tsx
+// ❌ Wrong — neither ModalBody nor DialogBody exists in @aircall/ds
+<DialogContent>
+  <DialogHeader>…</DialogHeader>
+  <DialogBody>
+    <p>Content here</p>
+  </DialogBody>
+  <DialogFooter>…</DialogFooter>
+</DialogContent>
+
+// ✅ Correct — body content is plain children between DialogHeader and DialogFooter
+<DialogContent>
+  <DialogHeader>…</DialogHeader>
+  <p className="text-sm">Content here</p>
+  <DialogFooter>…</DialogFooter>
+</DialogContent>
+```
+
+DS's `Dialog` is a compound with no `DialogBody` export. The body is just children of `DialogContent`. Remove `ModalBody` and render content directly.
+
+Source: `packages/ds/src/components/dialog.tsx`
+
+### Mistake 3 — Putting the label inside the `render` Button instead of `DialogClose`
+
+```tsx
+// ❌ Wrong — the label ends up inside the Button's children, not DialogClose's
+<DialogClose render={<Button variant="outline" size="lg">Cancel</Button>} />
+
+// ✅ Correct — label is a child of DialogClose; DialogClose clones it into the rendered Button
+<DialogClose render={<Button variant="outline" size="lg" />}>
+  Cancel
+</DialogClose>
+```
+
+`DialogClose` uses the Base UI `render` prop pattern: it renders the element you pass as `render`, merging its own click handler. The label must be the child of `DialogClose`, not of the inner Button.
+
+Source: `packages/ds/src/components/dialog.tsx`
+
+### Mistake 4 — Using `variant="critical"` on the Button
+
+```tsx
+// ❌ Wrong — critical is a Tractor variant; DS Button doesn't have it
+<Button variant="critical" onClick={onConfirm}>Delete</Button>
+
+// ✅ Correct — DS Button uses destructive
+<Button variant="destructive" size="lg" onClick={onConfirm}>Delete</Button>
+```
+
+DS renamed `critical` to `destructive` for Button (and other components). The Tractor prop is silently dropped; no TypeScript error is shown because the variant may fall through to the default style.
+
+Source: `packages/ds/src/components/dialog.tsx`