@aircall/blocks 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aircall/blocks",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "type": "module",
   "private": false,
   "sideEffects": [
@@ -82,7 +82,7 @@
     "vite": "7.3.1",
     "vitest": "4.0.17",
     "zod": "4.4.3",
-    "@aircall/ds": "0.26.0",
+    "@aircall/ds": "0.28.0",
     "@aircall/hooks": "0.6.0"
   },
   "keywords": [

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

@@ -6,7 +6,6 @@ description: >
   has a blocks/ds equivalent, what is out of scope, and which sub-skill to load next.
 type: core
 library: aircall-blocks
-library_version: "0.5.1"
 requires:
   - aircall-blocks/setup
 sources:
@@ -19,6 +18,10 @@ This is the overview router for the `@dashboard/library` migration. Load it firs
 identify the right sub-skill for each component you are migrating, and to determine what
 falls outside the scope of blocks and ds entirely.
 
+> **Already migrated?** To *verify* existing `@aircall/blocks` / `@aircall/ds` code is on the
+> latest shared components and props (rather than convert `@dashboard/library` imports), load
+> `@aircall/blocks#aircall-blocks/migrate-dashboard/catch-up-checklist`.
+
 ## How to run this migration (end-to-end)
 
 Migrate incrementally — one screen/file at a time, shipping each green:
@@ -84,6 +87,10 @@ no target in `@aircall/blocks` or `@aircall/ds` yet (e.g. `PieChart` and other c
 not listed above, leave it imported from `@dashboard/library` for now — do not force a
 migration or invent a target.
 
+## Not yet migratable (tracked elsewhere)
+
+Components whose migration decision is still **TBD**, **TODO**, or **Ready for dev** are not built yet — do not migrate them or invent a target. They are tracked in `dashboard-modules/COMPONENT-MIGRATION-DECISIONS.md`. Known example: `DaysPicker` (→ a future `@aircall/blocks` `DaysPicker` block, not yet built).
+
 ## Component routing table
 
 | @dashboard/library | Target (pkg) | Recipe to load | Status |
@@ -91,7 +98,8 @@ migration or invent a target.
 | `MessageScreen` family + `UnknownError` | `ComingSoonEmptyState`, `RestrictedAccessEmptyState`, `NotFoundEmptyState`, `NoDataEmptyState`, `NoSupportEmptyState`, `UnknownErrorEmptyState` and the `EmptyState*` parts (@aircall/blocks) | load @aircall/blocks#aircall-blocks/migrate-dashboard/empty-states | available |
 | `PageHeader` | `DashboardPageHeader` (+ `DashboardPageHeaderTitle` / `DashboardPageHeaderActions` / `DashboardPageHeaderAction` / `DashboardPageHeaderNav` / `DashboardPageHeaderDescription`) (@aircall/blocks) | load @aircall/blocks#aircall-blocks/migrate-dashboard/page-header | available |
 | Page / screen shell — incl. full-page flows (Campaign Creation, Add Contacts) | `DashboardPage` (standard: sidebar + header + tabs + content) / `DashboardStandalonePage` (full-page, no sidebar) (@aircall/blocks) | load @aircall/blocks#aircall-blocks/migrate-dashboard/dashboard-page | available |
-| `Paper` | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`, `CardAction` (and @aircall/blocks `CardSaveBar` for a save bar) (@aircall/ds) | load @aircall/blocks#aircall-blocks/migrate-dashboard/card | available |
+| `Paper` / `PaperForm` (settings-page surface) | `SettingCard` (+ `SettingCardHeader` / `SettingCardTitle` / `SettingCardDescription` / `SettingCardAction` / `SettingCardContent`), plus `useForm` + `CardSaveBar` for the save bar (@aircall/blocks). Keep the `errorBoundary` (`ScopedErrorBoundary`) **outside** the card. | load @aircall/blocks#aircall-blocks/migrate-dashboard/setting-card | available |
+| `Paper` (generic non-settings surface — tile/container, no title/toggle semantics) | `Card` (+ parts) (@aircall/ds) | load @aircall/blocks#aircall-blocks/migrate-dashboard/card | available |
 | `LoadMoreTable` | `DataTable` (@aircall/ds) | load @aircall/blocks#aircall-blocks/migrate-dashboard/data-table | available |
 | `MultiSearchSelect` + `MultiInlineSearchSelect` + `MultiSelectOption` | `Combobox` with `multiple` (multi-select) (@aircall/ds) | load @aircall/blocks#aircall-blocks/migrate-dashboard/combobox | available |
 | `SingleSearchSelect` / `SearchSelect` / single-value `MultiSelect` | `Combobox` WITHOUT `multiple` (single-select) (@aircall/ds) | load @aircall/blocks#aircall-blocks/migrate-dashboard/combobox | available |
@@ -117,6 +125,15 @@ migration or invent a target.
 | `ConfirmationModal` | `AlertDialog` and its parts (@aircall/ds) | load @aircall/ds#aircall-ds/migrate-tractor/dialog | available |
 | `Tab` | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` (@aircall/ds) | load @aircall/ds#aircall-ds/migrate-tractor/tabs | available |
 | `Skeleton` + `SkeletonText` | `Skeleton` (@aircall/ds) | load @aircall/ds#aircall-ds/migrate-tractor/skeleton | available |
+| `Editable` | `InlineEditInput` / `InlineEditTextarea` / `InlineEditSelect` / `InlineEditMultiselect` (+ sub-parts) (@aircall/ds) | inline — click-to-edit; single-value via `InlineEditInput`/`InlineEditTextarea`/`InlineEditSelect`, multi via `InlineEditMultiselect`. Data-driven accessor API like `DataCombobox` (`items` + `getItemValue`/`getItemLabel`) | available |
+| `Dropzone` | `Dropzone` (@aircall/ds); render the dropped files with `Attachment` (@aircall/ds) | load @aircall/ds#aircall-ds/migrate-tractor/dropzone — display files via @aircall/ds#aircall-ds/adopt-attachment | available |
+| `EmojiPicker` | `EmojiPicker` (@aircall/ds) | inline — no sub-skill | available |
+| `DateSelect` | `Input` + `Popover` + `Calendar` (@aircall/ds) | inline — a `Calendar` in a `Popover` behind an `Input` trigger | available |
+| `TagStack` | `BadgeGroup` (@aircall/ds) | inline — `<BadgeGroup>` wrapping `Badge` children | available |
+| `AvailabilitySelect` / `Select` | `Select` (@aircall/ds) | load @aircall/ds#aircall-ds/migrate-tractor/select | available |
+| `Chevron` | `Icon` (@aircall/react-icons) | inline — import the specific directional icon (`ChevronDown`, `ChevronRight`, …); no `<Chevron>` wrapper | available |
+| `InlineForm` / `InlineFormWithSingleSearchSelect` | `useForm` + DS primitives (+ `Combobox` for the search-select variant) (@aircall/blocks) | load @aircall/blocks#aircall-blocks/migrate-dashboard/form-wizard | available |
+| `TimeSlotsForm` | `useForm` + 2 blocks (@aircall/blocks) | load @aircall/blocks#aircall-blocks/migrate-dashboard/form-wizard — too specific to extract; compose at app level | available |
 
 ## How to use this router
 

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

@@ -7,7 +7,6 @@ description: >
   Paper or PaperForm from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.5.1"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard
@@ -17,6 +16,12 @@ sources:
 
 This skill builds on aircall-blocks/migrate-dashboard.
 
+> **Migrating a settings-page `Paper` / `PaperForm`?** Prefer `SettingCard` — load
+> `@aircall/blocks#aircall-blocks/migrate-dashboard/setting-card`. It is purpose-built for
+> the title / description / toggle / save-bar layout and gets the level backgrounds and
+> level-aware title for free. Use the raw `Card` primitives below only for **non-settings**
+> card surfaces (tiles, generic containers with no title/toggle semantics).
+
 ## 1. Component mapping
 
 | @dashboard/library | @aircall/ds / @aircall/blocks |
@@ -35,7 +40,7 @@ This skill builds on aircall-blocks/migrate-dashboard.
 
 `PaperForm` is a compound: it wires a `react-final-form` form, renders `Paper`, and
 appends a `SaveBar` footer. The replacement is `Card` with TanStack Form (`useForm` from
-`@aircall/blocks`) and `CardSaveBar` in a `CardFooter`.
+`@aircall/blocks`) and `CardSaveBar` as a direct child of `Card` (it is the footer itself).
 
 ## 2. Imports
 
@@ -176,7 +181,7 @@ function ProfileForm() {
 **After (`@aircall/blocks`):**
 ```tsx
 import { useForm, CardSaveBar } from '@aircall/blocks';
-import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '@aircall/ds';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@aircall/ds';
 
 const form = useForm({
   defaultValues: { name: '' },
@@ -187,7 +192,7 @@ function ProfileForm() {
   return (
     <form.AppForm>
       <form onSubmit={(e) => { e.preventDefault(); form.handleSubmit(); }}>
-        <Card className="overflow-hidden pb-0">
+        <Card>
           <CardHeader>
             <CardTitle>Profile</CardTitle>
             <CardDescription>Update your display name.</CardDescription>
@@ -202,9 +207,7 @@ function ProfileForm() {
               )}
             </form.AppField>
           </CardContent>
-          <CardFooter className="p-0">
-            <CardSaveBar submitLabel="Save" resetLabel="Discard" />
-          </CardFooter>
+          <CardSaveBar submitLabel="Save" resetLabel="Discard" />
         </Card>
       </form>
     </form.AppForm>
@@ -214,11 +217,33 @@ function ProfileForm() {
 
 Key changes:
 - `PaperForm` `formProps` + `react-final-form` render-prop → `useForm` from `@aircall/blocks` (TanStack Form).
-- `PaperForm` `footer` (implicit `SaveBar`) → `CardSaveBar` inside `CardFooter`.
-- Add `className="overflow-hidden pb-0"` to `Card` so the animated save bar's border sits flush at the card edge.
-- Add `className="p-0"` to `CardFooter` to let `CardSaveBar` own its padding.
+- `PaperForm` `footer` (implicit `SaveBar`) → `CardSaveBar` as a **direct child of `Card`** (do NOT wrap it in a `CardFooter` — it already carries `data-slot="card-footer"` itself).
+- **No `className` needed on `Card`**: it already has `overflow-hidden` built in, and `CardSaveBar`'s `data-slot="card-footer"` makes the card auto-collapse its bottom padding (`has-data-[slot=card-footer]:pb-0`) so the bar sits flush.
 - `CardSaveBar` reads `isDirty` / `canSubmit` / `isSubmitting` from form context automatically — no extra props needed.
 
+**Submit error banner (`getErrorMessage` / `submitError`).** `PaperForm` surfaced a submit failure via `getErrorMessage` + `submitError`. There is no built-in equivalent — catch and store it in `onSubmit`, then render an inline `Alert` above `CardContent`:
+
+```tsx
+const [submitError, setSubmitError] = useState<string | null>(null);
+
+const form = useForm({
+  defaultValues: { name: '' },
+  onSubmit: async ({ value }) => {
+    try {
+      await save(value);
+      setSubmitError(null);
+    } catch (e) {
+      setSubmitError(getErrorMessage(e));
+    }
+  },
+});
+
+// In JSX, above CardContent:
+{submitError && <Alert variant="error">{submitError}</Alert>}
+```
+
+> DS `Alert`'s error variant is `error` (not Tractor's `critical`/`destructive`). Full set: `default` / `info` / `success` / `warning` / `error`.
+
 ### 3d. Paper with a generic footer
 
 **Before (`@dashboard/library`):**
@@ -287,78 +312,25 @@ function BillingCard() {
 
 Source: `packages/ds/src/components/card.tsx`
 
-### Mistake 2 — Placing CardAction outside CardHeader
-
-```tsx
-// ❌ Wrong — renders in normal flow, loses top-right pinning
-<Card>
-  <CardHeader>
-    <CardTitle>Title</CardTitle>
-  </CardHeader>
-  <CardAction>
-    <Button variant="ghost" size="icon" aria-label="Menu">…</Button>
-  </CardAction>
-  <CardContent>Body</CardContent>
-</Card>
-
-// ✅ Correct — CardAction inside CardHeader uses the header grid
-<Card>
-  <CardHeader>
-    <CardTitle>Title</CardTitle>
-    <CardAction>
-      <Button variant="ghost" size="icon" aria-label="Menu">…</Button>
-    </CardAction>
-  </CardHeader>
-  <CardContent>Body</CardContent>
-</Card>
-```
-
-`CardHeader` uses `grid auto-rows-min has-data-[slot=card-action]:grid-cols-[1fr_auto]`. `CardAction` carries `data-slot="card-action"` and is placed at `col-start-2 row-span-2`. Outside `CardHeader`, no grid parent exists and the action renders in document flow.
-
-Source: `packages/ds/src/components/card.tsx`
-
-### Mistake 3 — Omitting overflow-hidden/pb-0 on Card when using CardSaveBar
+### Mistake 2 — Wrapping CardSaveBar in a CardFooter (or adding overflow-hidden/pb-0)
 
 ```tsx
-// ❌ Wrong — animated bar peeks out of the card's rounded corners
-<Card>
+// ❌ Wrong — CardSaveBar already IS the footer; a CardFooter around it doubles
+//    the top border and padding, and the className hints are redundant
+<Card className="overflow-hidden pb-0">
   <CardContent>…</CardContent>
   <CardFooter className="p-0">
     <CardSaveBar />
   </CardFooter>
 </Card>
 
-// ✅ Correct — overflow-hidden clips the bar; pb-0 removes the gap below the footer
-<Card className="overflow-hidden pb-0">
+// ✅ Correct — drop CardSaveBar in as a direct child; no wrapper, no className
+<Card>
   <CardContent>…</CardContent>
-  <CardFooter className="p-0">
-    <CardSaveBar />
-  </CardFooter>
+  <CardSaveBar />
 </Card>
 ```
 
-`CardSaveBar` slides in via a `grid-rows-[0fr→1fr]` transition. Without `overflow-hidden` on `Card`, the collapsed bar overflows the card's rounded corners during animation. Without `pb-0` the card's own `py-4` leaves a gap between the footer and the card bottom edge.
-
-Source: `packages/blocks/src/components/card-save-bar.tsx`
-
-### Mistake 4 — Passing react-final-form formProps to useForm
-
-```tsx
-// ❌ Wrong — react-final-form API; useForm from @aircall/blocks is TanStack Form
-import { useForm } from '@aircall/blocks';
-const form = useForm({
-  initialValues: { name: '' },        // ← react-final-form key
-  onSubmit: (values) => save(values)  // ← sync signature; TanStack expects async
-});
-
-// ✅ Correct — TanStack Form API
-import { useForm } from '@aircall/blocks';
-const form = useForm({
-  defaultValues: { name: '' },
-  onSubmit: async ({ value }) => { await save(value); }
-});
-```
-
-`useForm` from `@aircall/blocks` wraps TanStack Form, not `react-final-form`. The key differences: `defaultValues` (not `initialValues`), and `onSubmit` receives `{ value }` (not the bare values object).
+`CardSaveBar` renders its own `border-t` + padding and carries `data-slot="card-footer"`, so it already behaves as the footer. `Card` has `overflow-hidden` built in (clips the slide-in), and the `data-slot="card-footer"` triggers `has-data-[slot=card-footer]:pb-0`, so the bar sits flush with no manual `overflow-hidden`, `pb-0`, or `CardFooter` wrapper.
 
 Source: `packages/blocks/src/components/card-save-bar.tsx`

package/skills/aircall-blocks/migrate-dashboard/catch-up-checklist/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: aircall-blocks/migrate-dashboard/catch-up-checklist
+description: >
+  Verify that already-migrated dashboard / extension code uses the CURRENT shared
+  @aircall/ds + @aircall/blocks components and props — not an earlier or interim
+  pattern. Load when someone wants to double-check a codebase that is already off
+  @dashboard/library against the latest components (e.g. after a DS/blocks release),
+  or to confirm shared-component adoption. This is a VERIFICATION pass, NOT a
+  migration — to convert @dashboard/library imports, use aircall-blocks/migrate-dashboard.
+type: sub-skill
+library: aircall-blocks
+requires:
+  - aircall-blocks/migrate-dashboard
+---
+
+# Catch-up checklist — are you using the shared component, the latest way?
+
+This is **not** a migration skill. It is for code that is **already** on `@aircall/ds` /
+`@aircall/blocks` (the extension especially). Newer releases keep adding components and
+props that supersede patterns written earlier — this checklist confirms each area uses the
+current shared component the intended way, and points you to the skill that does the swap.
+
+## How to run
+
+For each row:
+
+1. **`grep`** the hint to find candidates in the code.
+2. **Check** whether the current pattern is missing or on an older shape (the "Red flag" column).
+3. **Apply** the shared component/prop; open the linked skill for the detailed swap.
+4. **Verify green** — `tsc --noEmit`, tests, lint.
+
+Skip a row cleanly if the area isn't present in the codebase — this is a spot-check list, not a required sweep.
+
+## Keeping this list evolutive (maintenance rules)
+
+- **Add a row** whenever a release supersedes an existing pattern — a new component *or* a new prop/capability on one you already use.
+- **`Added`** is write-once: the month a row was introduced. Never bump it — it lets someone who ran the checklist last quarter jump to what's new. (This is not a version stamp on the skill; rows are keyed by pattern, not version.)
+- **Retire a row** once its old pattern is effectively gone from consumers — prune, don't accumulate.
+- Keep every row **one line**. Deep detail lives in the linked skill, not here. When a group gets long, split it.
+
+## Layout & navigation
+
+| Use (current) | Red flag to look for | Detail / skill | Added |
+| --- | --- | --- | --- |
+| `DashboardPageHeader` | a hand-rolled header `<div>` with title + actions, or the legacy `PageHeader` from `@dashboard/library` | `@aircall/blocks#aircall-blocks/migrate-dashboard/page-header` | 2026-07 |
+| `StandalonePage` | a full-screen page not wrapped in it | `@aircall/blocks#aircall-blocks/migrate-dashboard/dashboard-page` | 2026-07 |
+| `DashboardPageContent` at extension page level | an extension page that skips it, re-renders its own outer `DashboardPage`/sidebar shell, or still passes `className="h-full"` (now baked into the component) | in an extension the `DashboardPage` shell is provided by the Sandbox and (in integrate mode) by dashboard-v4, so each page returns just `<DashboardPageContent data-test="…">` + `DashboardPageHeader` + `DashboardPageMain`; `@aircall/blocks#aircall-blocks/migrate-dashboard/dashboard-page` | 2026-07 |
+| `Tabs` (`@aircall/ds`) | `@aircall/tractor` Tab imports or a custom tab bar (low priority — mostly done) | `@aircall/ds#aircall-ds/migrate-tractor/tabs` | 2026-07 |
+
+## Data display
+
+| Use (current) | Red flag to look for | Detail / skill | Added |
+| --- | --- | --- | --- |
+| `Card` (`@aircall/ds`) | a custom card `<div>` with border/shadow/padding on grid pages | `@aircall/blocks#aircall-blocks/migrate-dashboard/card` | 2026-07 |
+| `SettingCard` (`@aircall/blocks`) | `Paper` / `PaperForm` from `@dashboard/library`, or a settings section already migrated to raw `Card` with a hand-rolled title/description/toggle or a hand-placed save bar | use `SettingCard` (+ parts): auto level backgrounds + level-aware title, nesting auto-detected, `form.CardSaveBar` as a direct child; `@aircall/blocks#aircall-blocks/migrate-dashboard/setting-card` | 2026-07 |
+| `DataTable` infinite scroll | a "Load more" button, or `DataTable` without `virtualizeRows`+`fillHeight` on a paginated table | pass `virtualizeRows fillHeight` + `onFetchMore`; `@aircall/blocks#aircall-blocks/migrate-dashboard/data-table` | 2026-07 |
+| `DataTable` selection → `ActionBar` | old `enableRowSelection`/`rowSelection`, or a custom bulk-action bar | use `selectionMode`/`selectedKeys` (drives `ActionBar`); `@aircall/blocks#aircall-blocks/migrate-dashboard/data-table` | 2026-07 |
+| `HoverCard` | a custom info-on-hover popup (old `InfoPopup`) | `@aircall/blocks#aircall-blocks/migrate-dashboard/info-popup` | 2026-07 |
+| Re-evaluate `List`/`ListItem` | an `ItemGroup`/`Item` list that is really editable data or tabular data | **check with a designer**: could be `InlineEditMultiselect` or `Table`/`DataTable` instead — `@aircall/blocks#aircall-blocks/migrate-dashboard/data-table` | 2026-07 |
+
+## Forms
+
+| Use (current) | Red flag to look for | Detail / skill | Added |
+| --- | --- | --- | --- |
+| `Form*Field` family | `useState`-per-field, or bare ds `Field`/`Input` wired by hand | input/select/combobox/multi-combobox/textarea/switch/radio/slider/toggle-group/OTP/numeric; `@aircall/blocks#aircall-blocks/migrate-dashboard/form-wizard` | 2026-07 |
+| `FormArrayField` | manual add/remove-row state for dynamic lists | `@aircall/blocks#aircall-blocks/migrate-dashboard/form-wizard` | 2026-07 |
+| `SubmitButton` | manual `disabled`/`loading` wiring on a submit button | reads `canSubmit`/`isSubmitting` automatically; `@aircall/blocks#aircall-blocks/migrate-dashboard/form-wizard` | 2026-07 |
+| Field label/description affordances | labels without the newer affordances | `orientation`/`controlPosition` inline layouts, `FieldLabelInfo` (ⓘ), `FieldLabelAside`, contextual vs instructional descriptions; `@aircall/ds#aircall-ds/migrate-tractor/form-and-field` | 2026-07 |
+| `DataCombobox` | a hand-rolled async/paginated combobox, or a custom table filter | `@aircall/ds#aircall-ds/migrate-tractor/combobox` (§5c) | 2026-07 |
+
+## Inputs
+
+| Use (current) | Red flag to look for | Detail / skill | Added |
+| --- | --- | --- | --- |
+| `NumericInput` | `<Input type="number">`, a custom stepper, or the legacy `NumberInput` from `@dashboard/library`, for numeric fields | prefix/suffix + up/down controls; via `FormNumericField` in forms | 2026-07 |
+
+## File upload
+
+| Use (current) | Red flag to look for | Detail / skill | Added |
+| --- | --- | --- | --- |
+| `Dropzone` | `react-dropzone` / a custom drag-and-drop wrapper/ Dropzone from dashboard/library | `@aircall/ds#aircall-ds/migrate-tractor/dropzone` | 2026-07 |
+| `Attachment` | a custom file-row/list after uploading a file via dropzone | `AttachmentGroup` + `Attachment`; `@aircall/ds#aircall-ds/adopt-attachment` | 2026-07 |
+
+## Links & navigation
+
+| Use (current) | Red flag to look for | Detail / skill | Added |
+| --- | --- | --- | --- |
+| `Anchor` or `Button variant="ghost"` | `Button variant="link"` | `Anchor` if it navigates to a page; `Button variant="ghost"` (or another variant) if it triggers an action — `@aircall/ds#aircall-ds/migrate-tractor/link` | 2026-07 |
+
+## Audio player
+
+| Use (current) | Red flag to look for | Detail / skill | Added |
+| --- | --- | --- | --- |
+| Audio primitives (`@aircall/ds`) | an old Tractor or custom audio player | refer to `@aircall/ds#aircall-ds/migrate-audio-player` and pick the pattern that best fits the current implementation; a skip button is available, and multiple players wrap in `AudioPlayerManager` | 2026-07 |
+
+## Editable
+
+| Use (current) | Red flag to look for | Detail / skill | Added |
+| --- | --- | --- | --- |
+| `InlineEdit` family | `EditableInput` / `EditableTextarea` / `EditableSelect` from `@dashboard/library`, or a custom click-to-edit control | `InlineEditInput`/`InlineEditTextarea`/`InlineEditSelect`, multi via `InlineEditMultiselect` (data-driven accessor API like `DataCombobox`) | 2026-07 |
+
+## Business tags
+
+| Use (current) | Red flag to look for | Detail / skill | Added |
+| --- | --- | --- | --- |
+| `SentimentBadge` | a custom mood/sentiment pill | `@aircall/blocks` leaf component | 2026-07 |
+| `ScoreBadge` | a custom score/percentage pill | `@aircall/blocks` leaf component | 2026-07 |
+| `RoleBadge` | a custom role tag | `<RoleBadge role="admin" />` (`@aircall/blocks`) | 2026-07 |
+| `Badge` / `BadgeGroup` | custom tag chips or a stacked tag row | `Badge` with `legacyColor` (stored hex) or `color`+`tone`; `BadgeGroup` for a stack — `@aircall/ds#aircall-ds/migrate-tractor/badge` | 2026-07 |

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

@@ -7,7 +7,6 @@ description: >
   it. Load when a file imports any *SearchSelect / MultiSelect from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.5.1"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard

package/skills/aircall-blocks/migrate-dashboard/copy-button/SKILL.md

@@ -6,7 +6,6 @@ description: >
   CopyToClipboardButton or CopyToClipboardText from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.6.0"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard

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

@@ -7,7 +7,6 @@ description: >
   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
@@ -137,6 +136,45 @@ import {
 
 `DashboardPageBanner` is available for a page-level banner. The page header itself migrates per `@aircall/blocks#aircall-blocks/migrate-dashboard/page-header`.
 
+### Extension pages — start at `DashboardPageContent`, not `DashboardPage`
+
+The block above is the **full** shell, which is what the host renders. Inside an
+**extension** you do **not** render `DashboardPage` / `DashboardSidebarProvider` /
+`DashboardSidebar` yourself — that outer shell is provided by the Sandbox during local
+dev (`@dashboard/extension-script`) and by dashboard-v4 in integrate mode. Each extension
+page starts at `DashboardPageContent` and returns just the content card: header +
+`DashboardPageMain`.
+
+Do **not** pass `className="h-full"` — the height is now baked into `DashboardPageContent`
+at the component level. Just pass your `data-test`.
+
+```tsx
+// conversation-center-ext/src/pages/contact_insights/ContactInsights.page.tsx
+import {
+  DashboardPageContent,
+  DashboardPageHeader,
+  DashboardPageHeaderTitle,
+  DashboardPageMain
+} from '@aircall/blocks';
+
+export function ContactInsightsPage() {
+  const { t } = useTranslation();
+
+  return (
+    <DashboardPageContent data-test="contact-insights-page">
+      <DashboardPageHeader>
+        <DashboardPageHeaderTitle size="lg">
+          {t('ai_assist.live_assist.pre_call_insights.title')}
+        </DashboardPageHeaderTitle>
+      </DashboardPageHeader>
+      <DashboardPageMain className="flex flex-col gap-4 overflow-scroll">
+        <ContactInsights hasTitle={false} />
+      </DashboardPageMain>
+    </DashboardPageContent>
+  );
+}
+```
+
 ### 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`):

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

@@ -6,7 +6,6 @@ description: >
   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
@@ -166,6 +165,16 @@ Key changes:
 - `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

package/skills/aircall-blocks/migrate-dashboard/empty-states/SKILL.md

@@ -7,7 +7,6 @@ description: >
   Load when a file imports any of those from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.5.1"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard

package/skills/aircall-blocks/migrate-dashboard/form-wizard/SKILL.md

@@ -7,7 +7,6 @@ description: >
   FormWizard, useFormWizard, or FormField from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.5.1"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard
@@ -247,6 +246,46 @@ spread the control bundle onto the matching DS primitive.
 | combobox (single) | `FormComboboxField` | switch | `FormSwitchField` |
 | combobox (multi) | `FormMultiComboboxField` | number | `FormNumericField` |
 | textarea | `FormTextareaField` | slider | `FormSliderField` |
+| toggle group | `FormToggleGroupField` | | |
+
+### Building a wrapper for an unlisted primitive (`FormFieldBase`)
+
+For a DS primitive without a shipped `Form*Field`, build one on `FormFieldBase` — it owns the field binding + the shared `Field`/`Label`/`Description`/`Error` shell; you supply a `buildControl` that maps the typed field to the control bundle. This is the shape every shipped wrapper follows (here re-creating `FormSwitchField`, which already ships — copy the pattern for a genuinely new primitive):
+
+```tsx
+import { FormFieldBase, type BoundForm, type FormFieldValidators, type TypedField } from '@aircall/blocks';
+import { Switch } from '@aircall/ds';
+import type { DeepKeysOfType } from '@tanstack/react-form';
+
+type SwitchControl = {
+  switchProps: { checked: boolean; onCheckedChange: (checked: boolean) => void; onBlur: () => void };
+};
+
+function switchControl(field: TypedField<boolean>): SwitchControl {
+  return {
+    switchProps: {
+      checked: field.state.value,
+      onCheckedChange: checked => field.handleChange(checked),
+      onBlur: field.handleBlur,
+    },
+  };
+}
+
+function FormSwitchField<
+  TForm extends BoundForm,
+  TName extends DeepKeysOfType<TForm['state']['values'], boolean> // only boolean fields
+>(props: {
+  form: TForm;
+  name: TName;
+  label: string;
+  validators?: FormFieldValidators<TForm['state']['values'], TName>;
+  children: (field: TypedField<boolean>, control: SwitchControl) => React.ReactNode;
+}) {
+  return <FormFieldBase<boolean, SwitchControl> {...props} buildControl={switchControl} />;
+}
+```
+
+`DeepKeysOfType<…, boolean>` restricts `name` to fields whose value type matches the control (here `boolean`), so the form stays type-safe.
 
 ## Multi-step gotchas
 

package/skills/aircall-blocks/migrate-dashboard/info-popup/SKILL.md

@@ -6,7 +6,6 @@ description: >
   or InfoPopupContent from @dashboard/library or from the local shared info-popup.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.6.0"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard

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

@@ -6,7 +6,6 @@ description: >
   Load when a file imports GridLayout, GridItem, or Gap from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.5.1"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard

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

@@ -7,7 +7,6 @@ description: >
   or ListItemActions from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.5.1"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard

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

@@ -6,7 +6,6 @@ description: >
   file imports Loading, Loader, or Spinner from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.5.1"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard

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

@@ -9,7 +9,6 @@ description: >
   imports PageHeader or PageHeaderLink from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.5.1"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard