@aircall/blocks 0.6.0 → 0.9.0

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

@@ -0,0 +1,429 @@
+---
+name: aircall-blocks/migrate-dashboard/tile
+description: >
+  Migrate @dashboard/library Tile, TileHeader, TileValue (+ TileBody, TileActions,
+  TileExtra, TileNumber, TileDuration, TileText) to @aircall/ds Card primitives
+  (Card, CardHeader, CardTitle, CardAction, CardContent). Load when a file imports
+  Tile, TileHeader, or TileValue 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 |
+| --- | --- |
+| `Tile` (root container) | `Card` |
+| `TileHeader` `label` prop | `CardTitle` inside `CardHeader` |
+| `TileHeader` `tooltipTexts` prop | inline `Tooltip` / `TooltipTrigger` / `TooltipContent` next to `CardTitle` |
+| `TileBody` (metric row wrapper) | `CardContent` |
+| `TileActions` (top-right action overlay) | `CardAction` inside `CardHeader` |
+| `TileValue` (number / duration / text display) | inline JSX using `Skeleton` (loading state) + plain markup |
+| `TileExtra` `secondaryText` prop | plain `<span>` inside `CardContent` |
+| `TileExtra` `trend` prop | custom trend badge — no DS equivalent; keep app-side |
+| `Tile` `disabled` prop | `data-disabled` attribute on `Card` + `className="opacity-50 cursor-not-allowed"` |
+| `TileProvider` (internal context) | removed — no equivalent needed |
+
+`TileValue` has no direct DS replacement — it is a formatting component (locale number, duration, text), not a structural one. Replace it with a plain `<span>` or `<p>` carrying the formatted value, optionally wrapped in a `Skeleton` for the loading state.
+
+`TILE_VALUE` enum and `TileValueSizes` type are internal to `@dashboard/library`; delete them from the import when migrating.
+
+## 2. Imports
+
+```tsx
+// DS primitives — tile shell
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  Skeleton,
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger
+} from '@aircall/ds';
+```
+
+No `@aircall/blocks` import is required for the tile container migration. Blocks are only
+needed if the tile sits inside a larger page layout from that package.
+
+## 3. Before / After
+
+### 3a. Basic tile — number value
+
+**Before (`@dashboard/library`):**
+```tsx
+import { Tile, TileBody, TileHeader, TileValue } from '@dashboard/library';
+
+function AnsweredTile() {
+  return (
+    <Tile>
+      <TileHeader label="Answered" />
+      <TileBody>
+        <TileValue value={123} />
+      </TileBody>
+    </Tile>
+  );
+}
+```
+
+**After (`@aircall/ds`):**
+```tsx
+import { Card, CardContent, CardHeader, CardTitle } from '@aircall/ds';
+
+function AnsweredTile() {
+  return (
+    <Card className="min-w-36">
+      <CardHeader>
+        <CardTitle className="text-xs font-medium text-muted-foreground">Answered</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <span className="text-2xl font-bold tabular-nums">123</span>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+Key changes:
+- `Tile` → `Card`. The `minWidth` prop (default 144 px) becomes `className="min-w-36"`.
+- `TileHeader label` → `CardTitle` inside `CardHeader`. Apply `text-xs font-medium text-muted-foreground` to match the original `supportingMediumXS` / `text-interactive-neutral` visual style.
+- `TileBody` → `CardContent`. Flex alignment was internal; use `className="flex items-center gap-1"` on `CardContent` if you need the row layout.
+- `TileValue` → inline `<span>` with the formatted value. The `size="regular"` style maps to `text-2xl font-bold tabular-nums`.
+
+### 3b. Tile with loading state
+
+**Before (`@dashboard/library`):**
+```tsx
+import { Tile, TileBody, TileHeader, TileValue } from '@dashboard/library';
+
+function LoadingTile() {
+  return (
+    <Tile>
+      <TileHeader label="Answered" />
+      <TileBody>
+        <TileValue loading />
+      </TileBody>
+    </Tile>
+  );
+}
+```
+
+**After (`@aircall/ds`):**
+```tsx
+import { Card, CardContent, CardHeader, CardTitle, Skeleton } from '@aircall/ds';
+
+function LoadingTile() {
+  return (
+    <Card className="min-w-36">
+      <CardHeader>
+        <CardTitle className="text-xs font-medium text-muted-foreground">Answered</CardTitle>
+      </CardHeader>
+      <CardContent className="flex h-8 items-center">
+        <Skeleton className="h-6 w-18" />
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+`TileValue loading` rendered a `Skeleton` at a fixed height container (32 px for `size="regular"`).
+Replicate with `className="flex h-8 items-center"` on `CardContent` and `className="h-6 w-18"` on `Skeleton`.
+
+### 3c. Tile with tooltip on header
+
+**Before (`@dashboard/library`):**
+```tsx
+import { Tile, TileBody, TileHeader, TileValue } from '@dashboard/library';
+
+function InfoTile() {
+  return (
+    <Tile>
+      <TileHeader label="Answered" tooltipTexts={{ info: 'Calls answered in the period' }} />
+      <TileBody>
+        <TileValue value={123} />
+      </TileBody>
+    </Tile>
+  );
+}
+```
+
+**After (`@aircall/ds`):**
+```tsx
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger
+} from '@aircall/ds';
+import { InformationCircleIcon } from '@aircall/react-icons';
+
+function InfoTile() {
+  return (
+    <Card className="min-w-36">
+      <CardHeader>
+        <CardTitle className="flex items-center gap-1 text-xs font-medium text-muted-foreground">
+          Answered
+          <TooltipProvider>
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <InformationCircleIcon className="h-3 w-3 cursor-default" aria-hidden />
+              </TooltipTrigger>
+              <TooltipContent>Calls answered in the period</TooltipContent>
+            </Tooltip>
+          </TooltipProvider>
+        </CardTitle>
+      </CardHeader>
+      <CardContent>
+        <span className="text-2xl font-bold tabular-nums">123</span>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+`TileHeader` showed the tooltip icon only on hover (`hovering` from `TileProvider`). The DS
+`Tooltip` is hover-driven by default — no extra state needed.
+
+### 3d. Tile with actions (TileActions)
+
+**Before (`@dashboard/library`):**
+```tsx
+import { Gap, Tile, TileActions, TileBody, TileHeader, TileValue } from '@dashboard/library';
+import { IconButton } from '@aircall/tractor';
+import { SettingsFilled, MenuVerticalFilled } from '@aircall/icons';
+
+function ActionTile() {
+  return (
+    <Tile>
+      <TileActions>
+        <Gap gap="xxxs">
+          <IconButton component={SettingsFilled} size={16} onClick={() => null} type="button" />
+          <IconButton component={MenuVerticalFilled} size={16} onClick={() => null} type="button" />
+        </Gap>
+      </TileActions>
+      <TileHeader label="Answered" />
+      <TileBody>
+        <TileValue onClick={() => null} value={123} />
+      </TileBody>
+    </Tile>
+  );
+}
+```
+
+**After (`@aircall/ds`):**
+```tsx
+import {
+  Button,
+  Card,
+  CardAction,
+  CardContent,
+  CardHeader,
+  CardTitle
+} from '@aircall/ds';
+import { SettingsIcon, MoreVerticalIcon } from '@aircall/react-icons';
+
+function ActionTile() {
+  return (
+    <Card className="min-w-36">
+      <CardHeader>
+        <CardTitle className="text-xs font-medium text-muted-foreground">Answered</CardTitle>
+        <CardAction className="flex items-center gap-1">
+          <Button variant="ghost" size="icon" aria-label="Settings" onClick={() => null}>
+            <SettingsIcon className="h-4 w-4" />
+          </Button>
+          <Button variant="ghost" size="icon" aria-label="More options" onClick={() => null}>
+            <MoreVerticalIcon className="h-4 w-4" />
+          </Button>
+        </CardAction>
+      </CardHeader>
+      <CardContent>
+        <button
+          type="button"
+          className="text-2xl font-bold tabular-nums underline decoration-dashed"
+          onClick={() => null}
+        >
+          123
+        </button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+Key changes:
+- `TileActions` → `CardAction` inside `CardHeader`. `CardAction` carries `data-slot="card-action"` and is pinned top-right by the header grid automatically.
+- `Gap` + `IconButton` from tractor → `Button variant="ghost" size="icon"` from `@aircall/ds`.
+- `TileValue onClick` (clickable value) → plain `<button>` element styled to match.
+
+### 3e. Disabled tile
+
+**Before (`@dashboard/library`):**
+```tsx
+import { Tile, TileBody, TileHeader, TileValue } from '@dashboard/library';
+
+function DisabledTile() {
+  return (
+    <Tile disabled>
+      <TileHeader label="Answered" tooltipTexts={{ help: 'Feature disabled' }} />
+      <TileBody>
+        <TileValue onClick={() => null} value={123} />
+      </TileBody>
+    </Tile>
+  );
+}
+```
+
+**After (`@aircall/ds`):**
+```tsx
+import { Card, CardContent, CardHeader, CardTitle } from '@aircall/ds';
+
+function DisabledTile() {
+  return (
+    <Card className="min-w-36 opacity-50" data-disabled aria-disabled>
+      <CardHeader>
+        <CardTitle className="text-xs font-medium text-muted-foreground">Answered</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <span className="cursor-not-allowed text-2xl font-bold tabular-nums">123</span>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+`Tile disabled` set `disabled` on `TileProvider` context, which `TileValue` read to disable its
+internal button. Replace by setting `opacity-50` + `aria-disabled` on `Card` and
+`cursor-not-allowed` on the value element; remove the `onClick` handler.
+
+---
+
+## 4. Common mistakes
+
+### Mistake 1 — Passing Tile/TileBody flex props to Card/CardContent
+
+```tsx
+// ❌ Wrong — tractor FlexProps (px, py, minWidth, flexDirection…) on Card
+<Card minWidth="228px" px="xxs" py="xxs" flexDirection="column">
+  <CardContent alignItems="center" gap="xxxs">…</CardContent>
+</Card>
+
+// ✅ Correct — use className with Tailwind utilities
+<Card className="min-w-[228px]">
+  <CardContent className="flex items-center gap-1">…</CardContent>
+</Card>
+```
+
+`Tile` extended `FlexProps` from `@aircall/tractor` (spacing tokens like `px`, `py`, `minWidth`).
+`Card` and `CardContent` extend `React.ComponentProps<'div'>` — passing tractor tokens results in
+unknown HTML attribute warnings at runtime and no styling effect.
+
+Source: `packages/ds/src/components/card.tsx`
+
+### Mistake 2 — Placing CardAction outside CardHeader
+
+```tsx
+// ❌ Wrong — action renders in document flow; loses top-right pinning
+<Card>
+  <CardAction>
+    <Button variant="ghost" size="icon">…</Button>
+  </CardAction>
+  <CardHeader>
+    <CardTitle>Answered</CardTitle>
+  </CardHeader>
+  <CardContent>…</CardContent>
+</Card>
+
+// ✅ Correct — CardAction must be a child of CardHeader
+<Card>
+  <CardHeader>
+    <CardTitle>Answered</CardTitle>
+    <CardAction>
+      <Button variant="ghost" size="icon">…</Button>
+    </CardAction>
+  </CardHeader>
+  <CardContent>…</CardContent>
+</Card>
+```
+
+`CardHeader` uses `grid auto-rows-min has-data-[slot=card-action]:grid-cols-[1fr_auto]`.
+`CardAction` carries `data-slot="card-action"` and sits at `col-start-2 row-span-2`. Outside
+`CardHeader` there is no grid parent; the action renders in document flow at full width.
+
+Source: `packages/ds/src/components/card.tsx`
+
+### Mistake 3 — Importing TILE_VALUE enum or TileValue from @dashboard/library after migration
+
+```tsx
+// ❌ Wrong — keeping the enum import after TileValue is removed
+import { TILE_VALUE, Tile, TileHeader, TileValue } from '@dashboard/library';
+
+<TileValue type={TILE_VALUE.DURATION} value={123} />
+
+// ✅ Correct — format the value in the consuming component; no TILE_VALUE needed
+import { Card, CardContent, CardHeader, CardTitle } from '@aircall/ds';
+
+// Duration formatting (seconds → "2m 03s") — implement inline or extract to a util
+function formatDuration(seconds: number): string {
+  const m = Math.floor(seconds / 60);
+  const s = seconds % 60;
+  return `${m}m ${String(s).padStart(2, '0')}s`;
+}
+
+<Card className="min-w-36">
+  <CardHeader>
+    <CardTitle className="text-xs font-medium text-muted-foreground">AHT</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <span className="text-2xl font-bold tabular-nums">{formatDuration(123)}</span>
+  </CardContent>
+</Card>
+```
+
+`TileValue` with `type={TILE_VALUE.DURATION}` delegated to `TileDuration`, which formatted
+seconds via an internal `formatSecondsToDuration` helper. That helper is not exported from
+`@dashboard/library`'s public API. Extract the formatting logic to a local utility function.
+
+Source: `packages/ds/src/components/card.tsx`
+
+### Mistake 4 — Using CardTitle for the metric value instead of the label
+
+```tsx
+// ❌ Wrong — CardTitle used for the big number; label lost
+<Card>
+  <CardHeader>
+    <CardTitle>123</CardTitle>
+  </CardHeader>
+</Card>
+
+// ✅ Correct — CardTitle holds the label; value sits in CardContent
+<Card className="min-w-36">
+  <CardHeader>
+    <CardTitle className="text-xs font-medium text-muted-foreground">Answered</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <span className="text-2xl font-bold tabular-nums">123</span>
+  </CardContent>
+</Card>
+```
+
+In `@dashboard/library`, `TileHeader` rendered the human-readable label ("Answered") and
+`TileValue` rendered the metric number. In the DS mapping, `CardTitle` takes the label and
+`CardContent` holds the value element. Swapping them produces an inverted visual hierarchy
+and breaks assistive-technology reading order.
+
+Source: `packages/ds/src/components/card.tsx`

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

@@ -0,0 +1,177 @@
+---
+name: aircall-blocks/migrate-dashboard/toggle-row
+description: >
+  Migrate @dashboard/library ToggleRow to @aircall/ds Field + Switch composition.
+  Load when a file imports ToggleRow from @dashboard/library.
+type: sub-skill
+library: aircall-blocks
+library_version: "0.6.0"
+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. Key premise
+
+`ToggleRow` was a single component. The DS replacement is a **composition** of
+`Field` (orientation="horizontal") + `Switch` + `FieldLabel` + optional `FieldDescription`.
+There is no 1:1 component — you must assemble the parts.
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Field, FieldLabel, FieldDescription, FieldTitle, FieldContent
+Switch
+Spinner
+```
+
+## 3. Imports
+
+```tsx
+import { Field, FieldDescription, FieldLabel, Spinner, Switch } from '@aircall/ds';
+```
+
+## 4. Prop mapping
+
+| `ToggleRow` prop | DS equivalent |
+| --- | --- |
+| `label` | `<FieldLabel>` inside `<Field orientation="horizontal">` |
+| `description` | `<FieldDescription>` next to `<FieldLabel>` |
+| `value` | `<Switch checked={…}>` or `<Switch defaultChecked>` |
+| `onChange` | `<Switch onCheckedChange={…}>` |
+| `disabled` | `<Switch disabled>` |
+| `loading` | Replace `<Switch>` with a `<Spinner>` in a `data-slot="switch"` wrapper (see §6) |
+| `data-test` | Pass to `<Switch>` directly |
+
+## 5. Structure
+
+```tsx
+<Field orientation="horizontal">
+  <Switch />                          {/* or Spinner placeholder when loading */}
+  <FieldLabel>Label text</FieldLabel>
+</Field>
+```
+
+With description:
+```tsx
+<Field orientation="horizontal" className="max-w-sm">
+  <Switch />
+  <div className="flex flex-col gap-0.5">
+    <FieldLabel>Label text</FieldLabel>
+    <FieldDescription>Supporting description.</FieldDescription>
+  </div>
+</Field>
+```
+
+## 6. Before / After examples
+
+### 6a. Label only
+
+**Before:**
+```tsx
+import { ToggleRow } from '@dashboard/library';
+
+<ToggleRow
+  label="Enable notifications"
+  value={enabled}
+  onChange={setEnabled}
+/>
+```
+
+**After:**
+```tsx
+import { Field, FieldLabel, Switch } from '@aircall/ds';
+
+<Field orientation="horizontal">
+  <Switch checked={enabled} onCheckedChange={setEnabled} />
+  <FieldLabel>Enable notifications</FieldLabel>
+</Field>
+```
+
+### 6b. With description
+
+**Before:**
+```tsx
+<ToggleRow
+  label="Recording"
+  description="Automatically record all inbound calls."
+  value={recording}
+  onChange={setRecording}
+/>
+```
+
+**After:**
+```tsx
+import { Field, FieldDescription, FieldLabel, Switch } from '@aircall/ds';
+
+<Field orientation="horizontal" className="max-w-sm">
+  <Switch checked={recording} onCheckedChange={setRecording} />
+  <div className="flex flex-col gap-0.5">
+    <FieldLabel>Recording</FieldLabel>
+    <FieldDescription>Automatically record all inbound calls.</FieldDescription>
+  </div>
+</Field>
+```
+
+### 6c. Loading state
+
+`ToggleRow` accepted a `loading` prop that replaced the toggle with a spinner.
+In the DS, swap the `Switch` for a `Spinner` placed inside a `data-slot="switch"`
+wrapper so Field's horizontal layout still aligns correctly:
+
+**Before:**
+```tsx
+<ToggleRow label="Syncing contacts" loading={true} />
+```
+
+**After:**
+```tsx
+import { Field, FieldLabel, Spinner } from '@aircall/ds';
+
+<Field orientation="horizontal">
+  <div data-slot="switch" className="grid h-6 w-10 shrink-0 place-items-center">
+    <Spinner size="default" />
+  </div>
+  <FieldLabel>Syncing contacts</FieldLabel>
+</Field>
+```
+
+## 7. Common mistakes
+
+### Mistake 1: Using `Switch` without `Field`
+
+```tsx
+// WRONG — no layout wrapper; label and switch won't align
+<Switch checked={value} onCheckedChange={onChange} />
+<label>Enable notifications</label>
+```
+
+```tsx
+// CORRECT — Field orientation="horizontal" provides the flex row layout
+<Field orientation="horizontal">
+  <Switch checked={value} onCheckedChange={onChange} />
+  <FieldLabel>Enable notifications</FieldLabel>
+</Field>
+```
+
+### Mistake 2: Putting description inside FieldLabel
+
+```tsx
+// WRONG — FieldLabel is for the label text only
+<FieldLabel>
+  Recording
+  <FieldDescription>…</FieldDescription>
+</FieldLabel>
+```
+
+```tsx
+// CORRECT — wrap label + description in a flex column div
+<div className="flex flex-col gap-0.5">
+  <FieldLabel>Recording</FieldLabel>
+  <FieldDescription>…</FieldDescription>
+</div>
+```