@aircall/blocks 0.5.1 → 0.7.0

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@aircall/blocks",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "type": "module",
   "private": false,
   "sideEffects": [
-    "**/*.css"
+    "**/*.css",
+    "**/i18n/register.ts"
   ],
   "description": "Aircall Blocks — higher-level UI compositions built on @aircall/ds",
   "author": "Aircall",
@@ -15,7 +16,8 @@
   "files": [
     "dist",
     "README.md",
-    "package.json"
+    "package.json",
+    "skills"
   ],
   "exports": {
     ".": {
@@ -39,6 +41,10 @@
       "optional": true
     }
   },
+  "dependencies": {
+    "react-markdown": "9.0.3",
+    "remark-gfm": "4.0.1"
+  },
   "devDependencies": {
     "@aircall/react-icons": "*",
     "@aircall/tsconfig": "1.4.3",
@@ -54,6 +60,7 @@
     "@storybook/react-vite": "10.3.3",
     "@tailwindcss/cli": "4.1.18",
     "@tailwindcss/postcss": "4.1.18",
+    "@tanstack/intent": "0.1.1",
     "@tanstack/react-form": "^1.33.0",
     "@types/node": "24",
     "@types/react": "19",
@@ -74,14 +81,23 @@
     "vite": "7.3.1",
     "vitest": "4.0.17",
     "zod": "4.4.3",
-    "@aircall/ds": "0.13.0",
+    "@aircall/ds": "0.15.0",
     "@aircall/hooks": "0.5.1"
   },
+  "keywords": [
+    "tanstack-intent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/aircall/shared/hydra.git",
+    "directory": "packages/blocks"
+  },
   "scripts": {
     "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
     "build:js": "tsdown --config ./tsdown.config.ts",
     "build:css": "tailwindcss -i ./src/styles/globals.css -o ./dist/globals.css --minify",
     "build:package": "pnpm run build:js && pnpm run build:css",
+    "typecheck": "tsc --noEmit",
     "lint": "eslint . --max-warnings 0",
     "sb:dev": "storybook dev -p 6009",
     "sb:build": "storybook build",

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

@@ -0,0 +1,127 @@
+---
+name: aircall-blocks/migrate-dashboard
+description: >
+  Migrate a file from @dashboard/library to @aircall/blocks / @aircall/ds. Load FIRST
+  to get the full component-level routing table before picking a recipe. Identifies what
+  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:
+  - "aircall/hydra:docs/migration-guides/dashboard-lib-to-blocks/AGENTS.md"
+---
+
+# Migrate @dashboard/library → @aircall/blocks / @aircall/ds
+
+This is the overview router for the `@dashboard/library` migration. Load it first to
+identify the right sub-skill for each component you are migrating, and to determine what
+falls outside the scope of blocks and ds entirely.
+
+## How to run this migration (end-to-end)
+
+Migrate incrementally — one screen/file at a time, shipping each green:
+
+0. **Set up once** — load `@aircall/blocks#aircall-blocks/setup` (it builds on
+   `@aircall/ds#aircall-ds/setup`): install `@aircall/blocks` + `@aircall/ds`, import both
+   `globals.css` bundles, and mount the DS root providers — including `DsI18nProvider`
+   (under your react-i18next provider, fed the user's language; importing `@aircall/blocks`
+   registers a `blocks` i18n namespace, so it needs DS's i18n engine) and
+   `NotificationQueueProvider` if you use banners. Add the jsdom test shims from setup.
+   (Loaded automatically via `requires`, but do the wiring first.)
+1. **Inventory** — list the file's `@dashboard/library` imports. The routing table below
+   says which have a blocks/ds equivalent and which are out of scope (hooks/utils/constants
+   don't migrate — leave them on `@dashboard/library`).
+2. **Migrate** — load the per-area recipe from the routing table for each UI component. Any
+   Tractor primitives in the same file migrate via `@aircall/ds#aircall-ds/migrate-tractor`;
+   icons via `@aircall/ds#aircall-ds/migrate-icons`.
+3. **Verify green** — `tsc --noEmit`, tests (DS popups/Switch need the setup jsdom shims),
+   biome/lint.
+4. **Repeat** until no in-scope `@dashboard/library` UI imports remain.
+
+## Cross-cutting note
+
+`@dashboard/library` mixes UI components with non-UI utilities. Only the UI components
+migrate. When writing replacement code:
+
+- Import block-level compositions (page layout, empty states, form layer) from
+  `'@aircall/blocks'`.
+- Import DS primitives (Card, Spinner, DataTable, Combobox, ItemGroup, etc.) from
+  `'@aircall/ds'`.
+- Never mix the two import paths for the same logical component — pick the package that
+  owns it per the table below.
+
+## Forms — never local state
+
+Any form that collects and submits data migrates to **`@aircall/blocks` `useForm` + the
+`Form*Field` wrappers** (the Storybook-proven `CommonForm` pattern) — NOT React
+`useState` per field, and NOT bare ds `Field`/`Input` primitives wired by hand. The form
+owns field state, validation, dirty/`canSubmit`/`isSubmitting`, and error display; those
+are what drive `SubmitButton`/`CardSaveBar`. Hand-rolled `useState` bypasses all of it and
+must be rewritten, not preserved, during migration. (`useState` for non-field UI — open,
+active tab — is fine.) Converting a large legacy `useState` form is a deliberate refactor,
+not a 1:1 swap. See `…/migrate-dashboard/form-wizard` and `@aircall/ds#aircall-ds/migrate-tractor/form-and-field`.
+
+## Out of scope
+
+The following `@dashboard/library` exports do NOT have an equivalent in `@aircall/blocks`
+or `@aircall/ds`. Do not try to map them to a DS component. They need a shared
+utils/data home or must stay in the consuming app.
+
+**Hooks**: `useGraphQuery`, `useGraphMutation`, `useToast`, `useToggle`,
+`useBroadcastChannel`
+
+**Helpers / utils**: `generateRandomUUID`, `isTruthy`, `toFixedNumber`,
+`capitalizeFirstLetter`, `getInitials`
+
+**Constants, types, and contexts**: `ROLE_NAME`, `RESOURCE`,
+`NavigationBlockerProvider`, `ClientError`
+
+**UI with no blocks/ds equivalent yet**: some `@dashboard/library` UI components have
+no target in `@aircall/blocks` or `@aircall/ds` yet (e.g. `PieChart` and other charts,
+`AudioPlayer`, `TileLegend`). If a UI component is not in the routing table below and
+not listed above, leave it imported from `@dashboard/library` for now — do not force a
+migration or invent a target.
+
+## Component routing table
+
+| @dashboard/library | Target (pkg) | Recipe to load | Status |
+|---|---|---|---|
+| `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 |
+| `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 |
+| `FormWizard` + `useFormWizard` + `FormField` | `useForm`, `CommonForm`, `FormInputField`/`FormSelectField`/`FormComboboxField`/etc., `CardSaveBar`/`SaveBar` (@aircall/blocks) | load @aircall/blocks#aircall-blocks/migrate-dashboard/form-wizard | available |
+| `Loading` | `Spinner` (and `Skeleton` for content placeholders) (@aircall/ds) | load @aircall/blocks#aircall-blocks/migrate-dashboard/loading | available |
+| `List` + `ListItem` | `ItemGroup`, `Item`, `ItemMedia`, `ItemContent`, `ItemActions` (@aircall/ds) | load @aircall/blocks#aircall-blocks/migrate-dashboard/list | available |
+| `Tile` + `TileHeader` + `TileValue` | `Card` (+ parts) as the tile container (@aircall/ds) | load @aircall/blocks#aircall-blocks/migrate-dashboard/tile | available |
+| `GridLayout` + `GridItem` + `Gap` | native `<div>` + Tailwind grid/flex/gap utilities (NO component import needed — these are layout primitives) (@aircall/ds) | load @aircall/blocks#aircall-blocks/migrate-dashboard/layout | available |
+| `InfoPopup` + `InfoPopupTrigger` + `InfoPopupContent` | `HoverCard`, `HoverCardTrigger`, `HoverCardContent` (@aircall/ds) | load @aircall/blocks#aircall-blocks/migrate-dashboard/info-popup | available |
+| `CopyToClipboardButton` + `CopyToClipboardText` | `CopyButton`, `CopyButtonIcon`, `CopyButtonLabel` (@aircall/blocks) | load @aircall/blocks#aircall-blocks/migrate-dashboard/copy-button | available |
+| `ToggleRow` | `Field` (orientation="horizontal") + `Switch` + `FieldLabel` + optional `FieldDescription` (@aircall/ds) | load @aircall/blocks#aircall-blocks/migrate-dashboard/toggle-row | available |
+| `AddButton` + `SaveButton` + `LoadingButton` | `Button` (@aircall/ds) — `AddButton` → `Button` with leading icon; `LoadingButton` loading state → `Button disabled` + `Spinner`; `SaveButton` saved state → `Button variant="outline"` + check icon | load @aircall/ds#aircall-ds/migrate-tractor/button | available |
+| `ConditionalTooltip` | Conditional JSX: wrap children in `<Tooltip>` / `<TooltipTrigger>` / `<TooltipContent>` when condition is true, render children bare when false — no wrapper component needed (@aircall/ds) | inline — no sub-skill | available |
+| `RadioBoxGroup` + `RadioBox` | `RadioGroup` + `RadioGroupItem` wrapped in `Field` + `FieldLabel` + `FieldContent` (@aircall/ds) | inline — see @aircall/ds#aircall-ds/migrate-tractor/form-and-field for Field patterns | available |
+| `TagBeautified` | `Badge` with `legacyColor` prop for stored hex colors; `Badge` with `color` + `tone` props for new tags (@aircall/ds) | inline — `<Badge legacyColor="#0761b5">Sales</Badge>` | available |
+| `RolesTags` | `RoleBadge` with `role` prop (`"owner"` \| `"admin"` \| `"supervisor"` \| `"agent"`) (@aircall/blocks) | inline — `<RoleBadge role="admin" />` | available |
+| `Count` | `CounterBadge` — pass the capped value as children: `<CounterBadge>{n > 99 ? '99+' : n}</CounterBadge>` (@aircall/ds) | inline — no size or max props | available |
+| `Avatar` | `Avatar`, `AvatarImage`, `AvatarFallback` compound (@aircall/ds) | load @aircall/ds#aircall-ds/migrate-tractor/avatar | available |
+| `ProgressBar` + `OptimisticProgressBar` | `Progress` with `value` prop (0–100) (@aircall/ds) | inline — `<Progress value={60} />` | available |
+| `ShadowScrollContainer` | `ScrollArea` with `scrollFade` prop — use a fixed `h-[…]` not `max-h-[…]` on the root (@aircall/ds) | inline — `<ScrollArea scrollFade className="h-[400px] rounded-md border">` | available |
+| `AccordionSection` | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` (@aircall/ds) | load @aircall/ds#aircall-ds/migrate-tractor/accordion | available |
+| `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 |
+
+## How to use this router
+
+1. Identify the `@dashboard/library` export(s) in the file you are migrating.
+2. Check the **Out of scope** section first — if the export is listed there, skip it.
+3. For each UI component, find the matching row in the table above and load the
+   indicated recipe sub-skill.
+4. Each sub-skill is self-contained: it carries the full prop mapping, common mistakes,
+   and import paths for its component family.

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

@@ -0,0 +1,364 @@
+---
+name: aircall-blocks/migrate-dashboard/card
+description: >
+  Migrate @dashboard/library Paper and PaperForm to @aircall/ds Card primitives
+  (Card, CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter)
+  and @aircall/blocks CardSaveBar for save/discard bars. Load when a file imports
+  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
+sources:
+  - "aircall/hydra:packages/ds/src/index.ts"
+---
+
+This skill builds on aircall-blocks/migrate-dashboard.
+
+## 1. Component mapping
+
+| @dashboard/library | @aircall/ds / @aircall/blocks |
+| --- | --- |
+| `Paper` (root surface) | `Card` (`@aircall/ds`) |
+| `Paper` `title` prop | `CardTitle` inside `CardHeader` (`@aircall/ds`) |
+| `Paper` `subtitle` prop | `CardDescription` inside `CardHeader` (`@aircall/ds`) |
+| `Paper` `titleSide` prop | `CardAction` inside `CardHeader` (`@aircall/ds`) |
+| `Paper` `children` (body) | `CardContent` (`@aircall/ds`) |
+| `Paper` `footer` prop (generic) | `CardFooter` (`@aircall/ds`) |
+| `Paper` `footer` prop (save/discard bar) | `CardSaveBar` (`@aircall/blocks`) |
+| `PaperForm` (form wrapper with save bar) | `Card` + `useForm` + `CardSaveBar` (`@aircall/blocks`) |
+| `Paper` `banner` prop | Inline `Banner` before `CardHeader` inside `Card` (`@aircall/ds`) |
+| `Paper` `disabled` / `disabledText` props | `className="opacity-50 cursor-not-allowed"` on `Card` + custom label |
+| `Paper` `fluid` prop | `className="w-full"` on `CardContent` (default is already full-width) |
+
+`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`.
+
+## 2. Imports
+
+```tsx
+// DS primitives — structural card shell
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+  Banner,
+  BannerTitle,
+  BannerDescription
+} from '@aircall/ds';
+
+// blocks — TanStack Form + animated save bar
+import { useForm, CardSaveBar } from '@aircall/blocks';
+```
+
+## 3. Before / After
+
+### 3a. Basic Paper — read-only surface
+
+**Before (`@dashboard/library`):**
+```tsx
+import { Paper } from '@dashboard/library';
+
+function SettingsSection() {
+  return (
+    <Paper
+      title="General settings"
+      subtitle="Manage your workspace preferences."
+    >
+      <p>Section content here.</p>
+    </Paper>
+  );
+}
+```
+
+**After (`@aircall/ds`):**
+```tsx
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@aircall/ds';
+
+function SettingsSection() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>General settings</CardTitle>
+        <CardDescription>Manage your workspace preferences.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p>Section content here.</p>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+Key changes:
+- `Paper` `title` → `CardTitle` inside `CardHeader`.
+- `Paper` `subtitle` → `CardDescription` inside `CardHeader`.
+- `Paper` `children` → wrapped in `CardContent`.
+- Drop `BoxProps` spread (`maxWidth`, `borderColor`, etc.) — `Card` owns the surface.
+
+### 3b. Paper with a header action (titleSide)
+
+**Before (`@dashboard/library`):**
+```tsx
+import { Paper } from '@dashboard/library';
+import { Button } from '@aircall/tractor';
+
+function IntegrationCard() {
+  return (
+    <Paper
+      title="Integrations"
+      subtitle="Connect your tools."
+      titleSide={<Button variant="primary" size="small">Add integration</Button>}
+    >
+      <p>Integration list here.</p>
+    </Paper>
+  );
+}
+```
+
+**After (`@aircall/ds`):**
+```tsx
+import { Button, Card, CardAction, CardContent, CardDescription, CardHeader, CardTitle } from '@aircall/ds';
+
+function IntegrationCard() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Integrations</CardTitle>
+        <CardDescription>Connect your tools.</CardDescription>
+        <CardAction>
+          <Button variant="default" size="sm">Add integration</Button>
+        </CardAction>
+      </CardHeader>
+      <CardContent>
+        <p>Integration list here.</p>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+`CardAction` must be inside `CardHeader` — the header grid (`grid-cols-[1fr_auto]`) positions it top-right automatically.
+
+### 3c. PaperForm — form with save/discard bar
+
+**Before (`@dashboard/library`):**
+```tsx
+import { PaperForm } from '@dashboard/library';
+
+function ProfileForm() {
+  return (
+    <PaperForm
+      title="Profile"
+      subtitle="Update your display name."
+      formProps={{
+        initialValues: { name: '' },
+        onSubmit: async (values) => { /* submit */ }
+      }}
+      submitButtonText="Save"
+      undoButtonText="Discard"
+    >
+      {({ values }) => (
+        <input name="name" defaultValue={values.name} />
+      )}
+    </PaperForm>
+  );
+}
+```
+
+**After (`@aircall/blocks`):**
+```tsx
+import { useForm, CardSaveBar } from '@aircall/blocks';
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '@aircall/ds';
+
+const form = useForm({
+  defaultValues: { name: '' },
+  onSubmit: async ({ value }) => { /* submit */ }
+});
+
+function ProfileForm() {
+  return (
+    <form.AppForm>
+      <form onSubmit={(e) => { e.preventDefault(); form.handleSubmit(); }}>
+        <Card className="overflow-hidden pb-0">
+          <CardHeader>
+            <CardTitle>Profile</CardTitle>
+            <CardDescription>Update your display name.</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <form.AppField name="name">
+              {(field) => (
+                <input
+                  value={field.state.value}
+                  onChange={(e) => field.handleChange(e.target.value)}
+                />
+              )}
+            </form.AppField>
+          </CardContent>
+          <CardFooter className="p-0">
+            <CardSaveBar submitLabel="Save" resetLabel="Discard" />
+          </CardFooter>
+        </Card>
+      </form>
+    </form.AppForm>
+  );
+}
+```
+
+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.
+- `CardSaveBar` reads `isDirty` / `canSubmit` / `isSubmitting` from form context automatically — no extra props needed.
+
+### 3d. Paper with a generic footer
+
+**Before (`@dashboard/library`):**
+```tsx
+import { Paper } from '@dashboard/library';
+import { Button } from '@aircall/tractor';
+
+function BillingCard() {
+  return (
+    <Paper
+      title="Billing"
+      footer={
+        <div style={{ padding: 16 }}>
+          <Button variant="primary">Upgrade plan</Button>
+        </div>
+      }
+    >
+      <p>Current plan: Free</p>
+    </Paper>
+  );
+}
+```
+
+**After (`@aircall/ds`):**
+```tsx
+import { Button, Card, CardContent, CardFooter, CardHeader, CardTitle } from '@aircall/ds';
+
+function BillingCard() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Billing</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <p>Current plan: Free</p>
+      </CardContent>
+      <CardFooter>
+        <Button variant="default">Upgrade plan</Button>
+      </CardFooter>
+    </Card>
+  );
+}
+```
+
+`CardFooter` applies `border-t bg-muted/50 p-4` by default. For a transparent footer pass `className="bg-transparent border-none"`.
+
+---
+
+## 4. Common mistakes
+
+### Mistake 1 — Spreading BoxProps onto Card
+
+```tsx
+// ❌ Wrong — tractor/dashboard BoxProps (maxWidth, borderRadius, backgroundColor…) on Card
+<Card maxWidth={1372} borderRadius="sm" backgroundColor="white">
+  <CardContent>Content</CardContent>
+</Card>
+
+// ✅ Correct — Card owns the surface; use className for true one-offs only
+<Card className="max-w-[1372px]">
+  <CardContent>Content</CardContent>
+</Card>
+```
+
+`Paper` accepted arbitrary `BoxProps` from `@aircall/tractor`. `Card` extends `React.ComponentProps<'div'>` — it accepts `className`, not tractor spacing/color tokens. Spread them and React will warn on unknown HTML attributes.
+
+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
+
+```tsx
+// ❌ Wrong — animated bar peeks out of the card's rounded corners
+<Card>
+  <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">
+  <CardContent>…</CardContent>
+  <CardFooter className="p-0">
+    <CardSaveBar />
+  </CardFooter>
+</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).
+
+Source: `packages/blocks/src/components/card-save-bar.tsx`