@aircall/blocks 0.5.1 → 0.7.0

package/skills/aircall-blocks/migrate-dashboard/dashboard-page/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: aircall-blocks/migrate-dashboard/dashboard-page
+description: >
+  Migrate a screen's page shell to @aircall/blocks — DashboardPage (standard in-app page:
+  sidebar + header + optional tabs + content) vs DashboardStandalonePage (full-page focused
+  flow with no sidebar, e.g. Campaign Creation, Add Contacts). Load when migrating a screen's
+  outer layout, a full-page wizard/creation flow, or a page header+content scaffold.
+type: sub-skill
+library: aircall-blocks
+library_version: "0.5.1"
+requires:
+  - aircall-blocks/setup
+  - aircall-blocks/migrate-dashboard
+sources:
+  - "aircall/hydra:packages/blocks/src/components/dashboard-page.tsx"
+  - "aircall/hydra:packages/blocks/src/components/dashboard-standalone-page.tsx"
+---
+
+This skill builds on aircall-blocks/migrate-dashboard.
+
+## 1. Which shell?
+
+| Screen kind | Use | Why |
+|---|---|---|
+| Standard in-app page (sidebar + header + optional tabs + content) | `DashboardPage` | Lives inside the dashboard chrome |
+| Full-page focused flow — creation wizard, Add Contacts, standalone forms (no sidebar) | `DashboardStandalonePage` | Takes over the viewport; header is just title + actions |
+
+Campaign Creation (`CampaignWizardPage`) and Add Contacts (`AddContactsPage`) are **standalone** flows → `DashboardStandalonePage`, with the multi-step form inside (see `@aircall/blocks#aircall-blocks/migrate-dashboard/form-wizard`).
+
+## 2. DashboardStandalonePage (full-page flows)
+
+```tsx
+import {
+  DashboardStandalonePage,
+  DashboardStandalonePageHeader,
+  DashboardStandalonePageTitle,
+  DashboardStandalonePageActions,
+  DashboardStandalonePageAction,
+  DashboardStandalonePageContent
+} from '@aircall/blocks';
+
+<DashboardStandalonePage>
+  <DashboardStandalonePageHeader>
+    <DashboardStandalonePageTitle>Create campaign</DashboardStandalonePageTitle>
+    <DashboardStandalonePageActions>
+      <DashboardStandalonePageAction onClick={onCancel}>Cancel</DashboardStandalonePageAction>
+    </DashboardStandalonePageActions>
+  </DashboardStandalonePageHeader>
+  <DashboardStandalonePageContent>
+    {/* a centered, width-capped Card — see below */}
+  </DashboardStandalonePageContent>
+</DashboardStandalonePage>
+```
+
+### What goes inside `DashboardStandalonePageContent` — a centered, width-capped Card
+
+`DashboardStandalonePageContent` is a full-bleed scroll area; it does **not** constrain
+width. The actual content is a centered container (`mx-auto` + a `max-w-*` cap) wrapping
+one or more `Card`s — the consistent pattern across the `DashboardStandalonePage` stories.
+Don't let content run full-width, and don't reach for `Paper`/raw page wrappers.
+
+```tsx
+import { Card, CardHeader, CardContent, CardFooter } from '@aircall/ds';
+
+<DashboardStandalonePageContent>
+  {/* single-column form / wizard */}
+  <div className="mx-auto max-w-2xl pt-4">
+    <Card>
+      <CardHeader>{/* title, or Stepper progress for a wizard */}</CardHeader>
+      <CardContent>{/* fields */}</CardContent>
+      <CardFooter className="justify-end gap-2">{/* Back / Next / Submit */}</CardFooter>
+    </Card>
+  </div>
+</DashboardStandalonePageContent>
+```
+
+Width cap by layout:
+- **Single-column form / wizard** → `mx-auto max-w-2xl pt-4` around one `Card` (CampaignWizard pattern).
+- **Wide / two-column** (form + summary aside) → `mx-auto flex max-w-7xl flex-col gap-6 pt-8 lg:flex-row`, a `Card` per column.
+
+## 3. DashboardPage (standard in-app page)
+
+```tsx
+import {
+  DashboardPage,
+  DashboardPageContent,
+  DashboardPageMain,
+  DashboardPageTabs,
+  DashboardPageHeader,
+  DashboardPageHeaderTitle,
+  DashboardPageHeaderActions,
+  DashboardPageHeaderAction,
+  DashboardSidebarProvider
+} from '@aircall/blocks';
+
+<DashboardPage>
+  <DashboardSidebarProvider defaultOpen>
+    {/* your <DashboardSidebar> */}
+    <DashboardPageContent>
+      <DashboardPageHeader>
+        <DashboardPageHeaderTitle size="lg">Campaigns</DashboardPageHeaderTitle>
+        <DashboardPageHeaderActions>
+          <DashboardPageHeaderAction variant="default">New campaign</DashboardPageHeaderAction>
+        </DashboardPageHeaderActions>
+      </DashboardPageHeader>
+      {/* optional: <DashboardPageTabs> here, as a sibling of the header */}
+      <DashboardPageMain>{/* page content */}</DashboardPageMain>
+    </DashboardPageContent>
+  </DashboardSidebarProvider>
+</DashboardPage>
+```
+
+`DashboardPageBanner` is available for a page-level banner. The page header itself migrates per `@aircall/blocks#aircall-blocks/migrate-dashboard/page-header`.
+
+### Page-level notices (beta/feature/trial banners) → `NotificationQueue`
+
+For app/page-level notices (e.g. a "beta feature" banner), prefer the ds **`NotificationQueue`** over an inline `Banner` — it stacks, dedupes, and orders by priority, and renders wherever you place a `NotificationSlot` (e.g. at the very top of the page, above the header). Mechanism (from `packages/ds/src/components/notification-queue.tsx`):
+
+```tsx
+import { NotificationQueueProvider, NotificationSlot, useNotification } from '@aircall/ds';
+
+// 1. Wrap the screen (or app) once:
+<NotificationQueueProvider>
+  <NotificationSlot slot="page" />        {/* render output at the top of the page */}
+  {/* …DashboardPage / DashboardStandalonePage… */}
+</NotificationQueueProvider>
+
+// 2. Declare the notice (lifecycle-bound) from any descendant:
+useNotification({
+  id: 'campaigns-beta',
+  slot: 'page',
+  priority: 'promotional',                 // 'error' | 'warning' | 'success' | 'info' | 'promotional'
+  render: () => <>You're using a beta feature 🚧 …</>
+});
+```
+
+Use `useNotification(...)` for persistent/conditional notices (beta banner); `useNotificationQueue().push(...)` for imperative, event-driven ones. `error` priority renders without a dismiss CTA.
+
+Source: `packages/ds/src/components/notification-queue.tsx`
+
+## 4. Common Mistakes
+
+### HIGH — Using `DashboardPage` (with sidebar) for a full-page creation flow
+
+Wrong:
+```tsx
+<DashboardPage>
+  <DashboardSidebarProvider>{/* sidebar */}
+    <DashboardPageContent>{/* Campaign Creation wizard */}</DashboardPageContent>
+  </DashboardSidebarProvider>
+</DashboardPage>
+```
+
+Correct:
+```tsx
+<DashboardStandalonePage>
+  <DashboardStandalonePageHeader>...</DashboardStandalonePageHeader>
+  <DashboardStandalonePageContent>{/* wizard */}</DashboardStandalonePageContent>
+</DashboardStandalonePage>
+```
+
+Focused flows (creation, Add Contacts) take over the viewport and have no sidebar. Wrapping them in `DashboardPage` renders the dashboard chrome/sidebar around the flow and needlessly pulls in `DashboardSidebarProvider`.
+
+Source: `packages/blocks/src/components/dashboard-standalone-page.tsx`
+
+### HIGH — Putting the header outside `DashboardPageContent`
+
+Wrong:
+```tsx
+<DashboardPage>
+  <DashboardPageHeader>...</DashboardPageHeader>   {/* direct child of DashboardPage */}
+  <DashboardPageContent>...</DashboardPageContent>
+</DashboardPage>
+```
+
+Correct: the header lives **inside** `DashboardPageContent`, alongside `DashboardPageMain`.
+
+`DashboardPageContent` owns the header/main grid (and a `:has()` rule manages the header border). A header outside it loses that layout and the border handling.
+
+Source: `packages/blocks/src/components/dashboard-page.tsx`
+
+### MEDIUM — Nesting `DashboardPageTabs` inside the header
+
+Wrong: `<DashboardPageHeader><DashboardPageTabs/></DashboardPageHeader>`.
+
+Correct: `DashboardPageTabs` is a **sibling** of `DashboardPageHeader` inside `DashboardPageContent`.
+
+`DashboardPageTabs` provides its own `border-b`; nesting it in the header double-borders and misplaces the tab strip.
+
+Source: `packages/blocks/src/components/dashboard-page.tsx`
+
+### MEDIUM — Re-creating page chrome with raw `div`/`Paper` instead of the shell
+
+Wrong: a hand-rolled `<div className="page">` + a `Paper`/`Card` page header.
+
+Correct: use the `DashboardPage` / `DashboardStandalonePage` shell so spacing, borders, and the header/content grid match the rest of the dashboard.
+
+Source: `packages/blocks/src/components/dashboard-page.tsx`

package/skills/aircall-blocks/migrate-dashboard/data-table/SKILL.md

@@ -0,0 +1,395 @@
+---
+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
+library_version: "0.5.1"
+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>[]` from `@tanstack/react-table`. 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 DataTableLoadingState
+Empty, EmptyContent, EmptyTitle, EmptyDescription
+Spinner
+```
+
+`@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. 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
+
+### 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 @tanstack/react-table
+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`