--- name: aircall-blocks/migrate-dashboard/data-table description: > Migrate @dashboard/library LoadMoreTable, LoadMoreStrategy, LoadMoreTableProps, and LoadMoreScrollProps to the @aircall/ds DataTable (TanStack Table-backed). Load when a file imports LoadMoreTable or LoadMoreStrategy from @dashboard/library. type: sub-skill library: aircall-blocks requires: - aircall-blocks/setup - aircall-blocks/migrate-dashboard sources: - "aircall/hydra:packages/ds/src/index.ts" --- This skill builds on aircall-blocks/migrate-dashboard. ## 1. Architecture change `LoadMoreTable` from `@dashboard/library` was a self-contained wrapper around Tractor's `Table` that bolted on a load-more strategy (`button` or `scroll`) and a loading spinner overlay. Columns were passed as plain descriptor objects (`{ id, label, renderer? }`). `DataTable` from `@aircall/ds` is built on **TanStack Table v8**. There is no strategy enum — pagination mode is controlled by a `loadingState` string and an `onFetchMore` callback. Columns are `ColumnDef<TData>[]` (a bound alias exported from `@aircall/ds`). The component handles both infinite scroll (via IntersectionObserver sentinel) and initial-load skeletons natively. ## 2. Target mapping | `@dashboard/library` | `@aircall/ds` | |---|---| | `LoadMoreTable` | `DataTable` | | `LoadMoreStrategy.Button` | No direct equivalent — use a custom "Load more" button rendered outside `DataTable` (see §4b) | | `LoadMoreStrategy.Scroll` | `onFetchMore` + `hasMore` (built-in sentinel) | | `loading={true}` (initial) | `loadingState="loading"` | | `loadingMore={true}` | `loadingState="loadingMore"` | | `hasMore` | `hasMore` | | `onLoadMore` | `onFetchMore` | | `columns[n].id` | `ColumnDef.accessorKey` (or `id` + `accessorFn`) | | `columns[n].label` | `ColumnDef.header` | | `columns[n].renderer` | `ColumnDef.cell: ({ row }) => row.original.<field>` | | `noDataMessage` | `emptyState` (accepts `ReactNode`) | | `data-test` | `data-test` (still forwarded via `...props`) | | `buttonText` / `loadingText` | Not a prop — render your own button outside `DataTable` | | `scrollThreshold` | Fixed 200 px look-ahead in `DataTable` sentinel — not configurable | | `h` / flex layout props | Use `fillHeight` prop + flex parent (`flex flex-col min-h-0`) | ## 3. Verified DS exports (`packages/ds/src/index.ts`) ``` DataTable, type ColumnDef, type DataTableLoadingState, type OnChangeFn, type SortingState Empty, EmptyContent, EmptyTitle, EmptyDescription Spinner ``` `@aircall/ds` **exposes** the TanStack Table types you author — `ColumnDef`, `SortingState`, `OnChangeFn` — as bound aliases, 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. Before / After ### 4a. Scroll strategy (infinite scroll) **Before (`@dashboard/library`):** ```tsx import { useState } from 'react'; import { LoadMoreTable, LoadMoreStrategy } from '@dashboard/library'; type Row = { id: string; name: string; email: string }; const columns = [ { id: 'name', label: 'Name' }, { id: 'email', label: 'Email', renderer: ({ email }: Row) => <a href={`mailto:${email}`}>{email}</a> }, ]; function PeopleTable() { const [data, setData] = useState<Row[]>(initialPage); const [loading, setLoading] = useState(false); const [loadingMore, setLoadingMore] = useState(false); const [hasMore, setHasMore] = useState(true); const handleLoadMore = async () => { setLoadingMore(true); const next = await fetchNextPage(); setData(prev => [...prev, ...next.rows]); setHasMore(next.hasMore); setLoadingMore(false); }; return ( <LoadMoreTable data={data} columns={columns} hasMore={hasMore} loading={loading} loadingMore={loadingMore} h="420px" onLoadMore={handleLoadMore} strategy={LoadMoreStrategy.Scroll} noDataMessage="No people found." data-test="people-table" /> ); } ``` **After (`@aircall/ds`):** ```tsx import { useState } from 'react'; import { DataTable, type DataTableLoadingState, Empty, EmptyContent, EmptyTitle } from '@aircall/ds'; import type { ColumnDef } from '@aircall/ds'; type Row = { id: string; name: string; email: string }; const columns: ColumnDef<Row>[] = [ { accessorKey: 'name', header: 'Name' }, { accessorKey: 'email', header: 'Email', cell: ({ row }) => <a href={`mailto:${row.original.email}`}>{row.original.email}</a>, }, ]; function PeopleTable() { const [data, setData] = useState<Row[]>(initialPage); const [loadingState, setLoadingState] = useState<DataTableLoadingState>('idle'); const [hasMore, setHasMore] = useState(true); const handleFetchMore = async () => { setLoadingState('loadingMore'); const next = await fetchNextPage(); setData(prev => [...prev, ...next.rows]); setHasMore(next.hasMore); setLoadingState('idle'); }; return ( <div className="flex flex-col min-h-0" style={{ height: 420 }}> <DataTable data={data} columns={columns} getRowId={row => row.id} loadingState={loadingState} hasMore={hasMore} onFetchMore={handleFetchMore} fillHeight emptyState={ <Empty> <EmptyContent> <EmptyTitle>No people found</EmptyTitle> </EmptyContent> </Empty> } data-test="people-table" /> </div> ); } ``` Key changes: - `loading` / `loadingMore` booleans collapse into a single `loadingState` discriminated string - `strategy={LoadMoreStrategy.Scroll}` + `onLoadMore` → `onFetchMore` + `hasMore` (sentinel is built-in) - Column descriptors (`{ id, label, renderer }`) → `ColumnDef<TData>[]` with `accessorKey`, `header`, and `cell` - `h="420px"` (Tractor Flex prop) → wrap in a flex container with a bounded height + pass `fillHeight` - `noDataMessage` string → `emptyState` ReactNode > **Row virtualization (large accumulated lists).** For an infinite-scroll table that > piles up many pages, also pass `virtualizeRows` so only visible rows are in the DOM > (requires `fillHeight`). **Tradeoff:** `virtualizeRows` implies `fixedLayout` > (`table-layout: fixed`) — every column then takes its `size`, and columns with no > `size` fall back to TanStack's **150px** default. A table that relied on content-based > auto widths (e.g. a narrow icon column) will visibly snap to 150px columns. Add an > explicit `size` to each `ColumnDef` to keep the intended widths, and check them in the > browser (`tsc`/tests won't catch a width regression). See > `@aircall/ds#aircall-ds/migrate-tractor/data-table` §8 for details. ### 4b. Button strategy `LoadMoreStrategy.Button` has no direct prop equivalent in `DataTable`. Render the "Load more" button below the table instead: **Before (`@dashboard/library`):** ```tsx import { LoadMoreTable, LoadMoreStrategy } from '@dashboard/library'; <LoadMoreTable data={data} columns={columns} hasMore={hasMore} loading={loading} loadingMore={loadingMore} buttonText="Load more" loadingText="Loading…" onLoadMore={handleLoadMore} strategy={LoadMoreStrategy.Button} /> ``` **After (`@aircall/ds`):** ```tsx import { DataTable, type DataTableLoadingState, Spinner, Button } from '@aircall/ds'; import type { ColumnDef } from '@aircall/ds'; // Button is from @aircall/ds; import it alongside DataTable. <div className="flex flex-col gap-4"> <DataTable data={data} columns={columns} loadingState={loadingState === 'loading' ? 'loading' : 'idle'} /> {hasMore && ( <div className="flex justify-center"> <Button variant="outline" onClick={handleLoadMore} disabled={loadingState === 'loadingMore'} > {loadingState === 'loadingMore' ? <Spinner /> : 'Load more'} </Button> </div> )} </div> ``` Key changes: - `buttonText` / `loadingText` / `loadingMore` are not props on `DataTable` — drive the button's label and disabled state from your own `loadingState` variable - `Spinner` and `Button` are imported from `@aircall/ds` (same package as `DataTable`) ### 4c. Initial loading state **Before (`@dashboard/library`):** ```tsx import { LoadMoreTable } from '@dashboard/library'; <LoadMoreTable data={data ?? null} columns={columns} hasMore={false} loading={isLoading} onLoadMore={() => {}} /> ``` **After (`@aircall/ds`):** ```tsx import { DataTable } from '@aircall/ds'; import type { ColumnDef } from '@aircall/ds'; <DataTable data={data ?? []} columns={columns} loadingState={isLoading ? 'loading' : 'idle'} /> ``` Key changes: - `data` is always `TData[]`; pass `[]` while loading (skeleton rows replace the empty body) - `loading={true}` → `loadingState="loading"` shows skeleton rows automatically - No `hasMore` or `onLoadMore` needed for a non-paginated table ## 5. Common mistakes ### Mistake 1 — Passing `strategy` or `onLoadMore` to `DataTable` ```tsx // Wrong — DataTable has no strategy or onLoadMore prop; they are silently ignored import { DataTable } from '@aircall/ds'; <DataTable data={data} columns={columns} strategy="scroll" onLoadMore={handleLoadMore} /> // Correct — use onFetchMore for scroll-based pagination <DataTable data={data} columns={columns} hasMore={hasMore} onFetchMore={handleFetchMore} /> ``` `LoadMoreStrategy` and `onLoadMore` are `@dashboard/library` concepts. `DataTable` exposes `onFetchMore` (triggers when the IntersectionObserver sentinel enters the viewport) and `hasMore` (hides the sentinel when false). There is no button-strategy prop — render your own button outside the table for that UX pattern. Source: `packages/ds/src/components/data-table.tsx` ### Mistake 2 — Keeping `loading` / `loadingMore` as separate boolean props ```tsx // Wrong — DataTable has no loading or loadingMore props; they are silently ignored <DataTable data={data} columns={columns} loading={isLoading} loadingMore={isFetchingMore} /> // Correct — collapse both booleans into a single loadingState string <DataTable data={data} columns={columns} loadingState={isLoading ? 'loading' : isFetchingMore ? 'loadingMore' : 'idle'} /> ``` DS replaced the dual-boolean pattern with a discriminated `loadingState` string so each async phase renders the right UX: `'loading'` shows skeleton rows (initial load), while `'loadingMore'` appends a spinner row at the bottom (pagination). Passing `loading` or `loadingMore` as props is silently ignored and the table will not show any loading indicator. Source: `packages/ds/src/components/data-table.tsx` ### Mistake 3 — Using column descriptor objects instead of `ColumnDef` ```tsx // Wrong — { id, label, renderer } is the @dashboard/library TableColumn shape; // DataTable does not read these fields import { DataTable } from '@aircall/ds'; const columns = [ { id: 'name', label: 'Name' }, { id: 'email', label: 'Email', renderer: ({ email }) => <a href={`mailto:${email}`}>{email}</a> }, ]; <DataTable data={data} columns={columns} /> // Correct — use ColumnDef from @aircall/ds import type { ColumnDef } from '@aircall/ds'; type Row = { id: string; name: string; email: string }; const columns: ColumnDef<Row>[] = [ { accessorKey: 'name', header: 'Name' }, { accessorKey: 'email', header: 'Email', cell: ({ row }) => <a href={`mailto:${row.original.email}`}>{row.original.email}</a>, }, ]; ``` `DataTable` is built on TanStack Table v8. It reads `ColumnDef` fields (`accessorKey`, `header`, `cell`, `enableSorting`, etc.) — not `id`, `label`, or `renderer`. Passing the old descriptor shape compiles (TypeScript can't narrow the column union tightly), but all columns will render blank cells because no accessor is registered. Source: `packages/ds/src/components/data-table.tsx` ### Mistake 4 — Passing `noDataMessage` instead of `emptyState` ```tsx // Wrong — noDataMessage is a @dashboard/library / Tractor prop; DataTable ignores it <DataTable data={[]} columns={columns} noDataMessage="No records found." /> // Correct — emptyState accepts any ReactNode; use the Empty compound for rich states import { DataTable, 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> } /> ``` `DataTable` requires an `emptyState` prop; `noDataMessage` is not defined on `DataTable` and is silently ignored — the table body renders nothing when data is empty. For plain text wrap it in `<p className="text-sm text-muted-foreground">`. For a full empty state with an icon and call-to-action, compose with the `Empty` family from `@aircall/ds`. Source: `packages/ds/src/components/data-table.tsx` ### Mistake 5 — Passing height as a Tractor prop instead of using `fillHeight` ```tsx // Wrong — h / w are Tractor Flex props; DataTable does not accept them <DataTable data={data} columns={columns} h="420px" /> // Correct — constrain the parent height with a flex container and pass fillHeight <div className="flex flex-col min-h-0" style={{ height: 420 }}> <DataTable data={data} columns={columns} fillHeight /> </div> ``` `LoadMoreTable` forwarded layout props (`h`, `w`, `flex`, etc.) to the Tractor `Flex` wrapper it rendered internally. `DataTable` has no such props. Use `fillHeight` to pin the header and scroll the body internally — the parent must provide a bounded height via a flex column (`flex flex-col` + `min-h-0`). Without a bounded parent, `fillHeight` has no effect and the table grows to its natural height. Source: `packages/ds/src/components/data-table.tsx`