@aircall/blocks 0.6.0 → 0.7.0

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`