@aircall/blocks 0.18.0 → 0.19.0

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

@@ -2,50 +2,69 @@
 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.
+  TileExtra, TileNumber, TileDuration, TileText) to @aircall/blocks KpiCard
+  compositions (KpiCard, KpiValue, KpiDescription, KpiValueSkeleton,
+  KpiDescriptionSkeleton) plus DS CardHeader / CardTitle / CardContent / CardAction.
+  Load when a file imports Tile, TileHeader, or TileValue from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard
 sources:
-  - "aircall/hydra:packages/ds/src/index.ts"
+  - "aircall/hydra:packages/blocks/src/components/kpi.tsx"
+  - "aircall/hydra:packages/blocks/src/helpers/format-kpi.ts"
+  - "aircall/hydra:packages/ds/src/components/card.tsx"
 ---
 
 This skill builds on aircall-blocks/migrate-dashboard.
 
 ## 1. Component mapping
 
-| @dashboard/library | @aircall/ds |
+| @dashboard/library | Target |
 | --- | --- |
-| `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.
+| `Tile` (root container) | `KpiCard` (`@aircall/blocks`) — DS `Card` wrapper, `size="sm"` by default |
+| `Tile` `disabled` prop | `KpiCard disabled` — applies `opacity-50` + `cursor-not-allowed` and cascades to nested `KpiValue`s |
+| `TileHeader` `label` prop | DS `CardTitle` inside DS `CardHeader` |
+| `TileHeader` `tooltipTexts` prop | inline DS `Tooltip` / `TooltipTrigger` / `TooltipContent` next to `CardTitle` |
+| `TileBody` (metric row wrapper) | DS `CardContent` |
+| `TileActions` (top-right action overlay) | DS `CardAction` inside `CardHeader` |
+| `TileValue` (number / duration / text / percent) | `KpiValue` (`@aircall/blocks`) — use `kind`, `durationStyle`, `unit`, `onClick`, `active` |
+| `TileValue loading` | `KpiValueSkeleton` (and `KpiDescriptionSkeleton` when a comparison line loads) |
+| `TileExtra` `secondaryText` prop | `KpiDescription` children |
+| `TileExtra` `trend` prop | `KpiDescription` `trend` + `tone` (`up` / `down` / `neutral` × `positive` / `negative` / `neutral`) |
+| `TileProvider` (internal context) | removed — `KpiCard` provides disabled context |
+
+`TILE_VALUE` enum and `TileValueSizes` type are internal to `@dashboard/library`; delete them from the import when migrating. Map former types via `KpiValue` `kind`:
+
+| Former `TILE_VALUE` / type | `KpiValue` props |
+| --- | --- |
+| number | `kind="number"` (default for numeric `value`) |
+| percent | `kind="percent"` |
+| duration (long / verbose) | `kind="duration"` (`durationStyle="long"` default) |
+| duration clock HH:MM | `kind="duration" durationStyle="clock" durationScale="hours"` |
+| duration clock MM:SS | `kind="duration" durationStyle="clock" durationScale="minutes"` |
+| opaque string | string `value` (or `kind="text"`) |
 
 ## 2. Imports
 
 ```tsx
-// DS primitives — tile shell
+// Blocks — KPI composition
 import {
-  Card,
+  KpiCard,
+  KpiValue,
+  KpiDescription,
+  KpiValueSkeleton,
+  KpiDescriptionSkeleton
+} from '@aircall/blocks';
+
+// DS — card slots + optional tooltip / actions
+import {
+  Button,
   CardAction,
   CardContent,
   CardHeader,
   CardTitle,
-  Skeleton,
   Tooltip,
   TooltipContent,
   TooltipProvider,
@@ -53,9 +72,6 @@ import {
 } 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
@@ -76,29 +92,30 @@ function AnsweredTile() {
 }
 ```
 
-**After (`@aircall/ds`):**
+**After (`@aircall/blocks` + `@aircall/ds`):**
 ```tsx
-import { Card, CardContent, CardHeader, CardTitle } from '@aircall/ds';
+import { CardContent, CardHeader, CardTitle } from '@aircall/ds';
+import { KpiCard, KpiValue } from '@aircall/blocks';
 
 function AnsweredTile() {
   return (
-    <Card className="min-w-36">
+    <KpiCard className="min-w-36">
       <CardHeader>
-        <CardTitle className="text-xs font-medium text-muted-foreground">Answered</CardTitle>
+        <CardTitle>Answered</CardTitle>
       </CardHeader>
       <CardContent>
-        <span className="text-2xl font-bold tabular-nums">123</span>
+        <KpiValue value={123} kind="number" />
       </CardContent>
-    </Card>
+    </KpiCard>
   );
 }
 ```
 
 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`.
+- `Tile` → `KpiCard`. Optional `minWidth` (default 144 px) becomes `className="min-w-36"`.
+- `TileHeader label` → `CardTitle` inside `CardHeader`.
+- `TileBody` → `CardContent`.
+- `TileValue` → `KpiValue` (formatting + typography owned by the block).
 
 ### 3b. Tile with loading state
 
@@ -118,26 +135,27 @@ function LoadingTile() {
 }
 ```
 
-**After (`@aircall/ds`):**
+**After:**
 ```tsx
-import { Card, CardContent, CardHeader, CardTitle, Skeleton } from '@aircall/ds';
+import { CardContent, CardHeader, CardTitle } from '@aircall/ds';
+import { KpiCard, KpiValueSkeleton } from '@aircall/blocks';
 
 function LoadingTile() {
   return (
-    <Card className="min-w-36">
+    <KpiCard className="min-w-36">
       <CardHeader>
-        <CardTitle className="text-xs font-medium text-muted-foreground">Answered</CardTitle>
+        <CardTitle>Answered</CardTitle>
       </CardHeader>
-      <CardContent className="flex h-8 items-center">
-        <Skeleton className="h-6 w-18" />
+      <CardContent>
+        <KpiValueSkeleton />
       </CardContent>
-    </Card>
+    </KpiCard>
   );
 }
 ```
 
-`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`.
+When a comparison line also loads, pair with `KpiDescriptionSkeleton` inside
+`CardContent className="flex flex-col gap-1"`.
 
 ### 3c. Tile with tooltip on header
 
@@ -157,10 +175,9 @@ function InfoTile() {
 }
 ```
 
-**After (`@aircall/ds`):**
+**After:**
 ```tsx
 import {
-  Card,
   CardContent,
   CardHeader,
   CardTitle,
@@ -170,16 +187,19 @@ import {
   TooltipTrigger
 } from '@aircall/ds';
 import { InformationCircleIcon } from '@aircall/react-icons';
+import { KpiCard, KpiValue } from '@aircall/blocks';
 
 function InfoTile() {
   return (
-    <Card className="min-w-36">
+    <KpiCard className="min-w-36">
       <CardHeader>
-        <CardTitle className="flex items-center gap-1 text-xs font-medium text-muted-foreground">
+        <CardTitle className="flex items-center gap-1">
           Answered
           <TooltipProvider>
             <Tooltip>
-              <TooltipTrigger asChild>
+              <TooltipTrigger
+                render={<button type="button" className="inline-flex" aria-label="More info" />}
+              >
                 <InformationCircleIcon className="h-3 w-3 cursor-default" aria-hidden />
               </TooltipTrigger>
               <TooltipContent>Calls answered in the period</TooltipContent>
@@ -188,17 +208,14 @@ function InfoTile() {
         </CardTitle>
       </CardHeader>
       <CardContent>
-        <span className="text-2xl font-bold tabular-nums">123</span>
+        <KpiValue value={123} />
       </CardContent>
-    </Card>
+    </KpiCard>
   );
 }
 ```
 
-`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)
+### 3d. Tile with actions + clickable value
 
 **Before (`@dashboard/library`):**
 ```tsx
@@ -224,50 +241,37 @@ function ActionTile() {
 }
 ```
 
-**After (`@aircall/ds`):**
+**After:**
 ```tsx
-import {
-  Button,
-  Card,
-  CardAction,
-  CardContent,
-  CardHeader,
-  CardTitle
-} from '@aircall/ds';
-import { SettingsIcon, MoreVerticalIcon } from '@aircall/react-icons';
+import { Button, CardAction, CardContent, CardHeader, CardTitle } from '@aircall/ds';
+import { EllipsisVertical, Settings } from '@aircall/react-icons';
+import { KpiCard, KpiValue } from '@aircall/blocks';
 
 function ActionTile() {
   return (
-    <Card className="min-w-36">
+    <KpiCard className="min-w-36">
       <CardHeader>
-        <CardTitle className="text-xs font-medium text-muted-foreground">Answered</CardTitle>
+        <CardTitle>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 variant="ghost" size="icon-sm" aria-label="Settings" onClick={() => null}>
+            <Settings />
           </Button>
-          <Button variant="ghost" size="icon" aria-label="More options" onClick={() => null}>
-            <MoreVerticalIcon className="h-4 w-4" />
+          <Button variant="ghost" size="icon-sm" aria-label="More options" onClick={() => null}>
+            <EllipsisVertical />
           </Button>
         </CardAction>
       </CardHeader>
       <CardContent>
-        <button
-          type="button"
-          className="text-2xl font-bold tabular-nums underline decoration-dashed"
-          onClick={() => null}
-        >
-          123
-        </button>
+        <KpiValue value={123} onClick={() => null} />
       </CardContent>
-    </Card>
+    </KpiCard>
   );
 }
 ```
 
 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.
+- `TileActions` → `CardAction` inside `CardHeader`.
+- `TileValue onClick` → `KpiValue onClick` (dotted underline; `active` for solid underline).
 
 ### 3e. Disabled tile
 
@@ -278,7 +282,7 @@ import { Tile, TileBody, TileHeader, TileValue } from '@dashboard/library';
 function DisabledTile() {
   return (
     <Tile disabled>
-      <TileHeader label="Answered" tooltipTexts={{ help: 'Feature disabled' }} />
+      <TileHeader label="Answered" />
       <TileBody>
         <TileValue onClick={() => null} value={123} />
       </TileBody>
@@ -287,142 +291,189 @@ function DisabledTile() {
 }
 ```
 
-**After (`@aircall/ds`):**
+**After:**
 ```tsx
-import { Card, CardContent, CardHeader, CardTitle } from '@aircall/ds';
+import { CardContent, CardHeader, CardTitle } from '@aircall/ds';
+import { KpiCard, KpiValue } from '@aircall/blocks';
 
 function DisabledTile() {
   return (
-    <Card className="min-w-36 opacity-50" data-disabled aria-disabled>
+    <KpiCard disabled className="min-w-36">
       <CardHeader>
-        <CardTitle className="text-xs font-medium text-muted-foreground">Answered</CardTitle>
+        <CardTitle>Answered</CardTitle>
       </CardHeader>
       <CardContent>
-        <span className="cursor-not-allowed text-2xl font-bold tabular-nums">123</span>
+        <KpiValue value={123} onClick={() => null} />
+      </CardContent>
+    </KpiCard>
+  );
+}
+```
+
+`KpiCard disabled` applies `opacity-50` + `cursor-not-allowed` and cascades so nested
+`KpiValue` buttons cannot be activated — no need to strip `onClick` or style the value by hand.
+
+### 3f. Comparison / trend line (TileExtra)
+
+**Before:** `TileExtra` with `secondaryText` + `trend`.
+
+**After:**
+```tsx
+import { CardContent, CardHeader, CardTitle } from '@aircall/ds';
+import { KpiCard, KpiDescription, KpiValue } from '@aircall/blocks';
+
+function OutboundCallsTile() {
+  return (
+    <KpiCard className="min-w-36">
+      <CardHeader>
+        <CardTitle>Outbound calls</CardTitle>
+      </CardHeader>
+      <CardContent className="flex flex-col gap-1">
+        <KpiValue value={87} onClick={() => null} />
+        <KpiDescription trend="up" tone="positive">
+          +16.3% vs previous period
+        </KpiDescription>
       </CardContent>
-    </Card>
+    </KpiCard>
   );
 }
 ```
 
-`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.
+`trend` is icon direction only; `tone` is color only — an upward change that is bad uses
+`trend="up" tone="negative"`.
+
+### 3g. Duration values
+
+```tsx
+{/* Long: "1h 2min 3s" */}
+<KpiValue value={3723} kind="duration" />
+
+{/* Clock hours: "01:38 hr/min" */}
+<KpiValue value={5880} kind="duration" durationStyle="clock" durationScale="hours" />
+
+{/* Clock minutes: "05:04 min/sec" */}
+<KpiValue value={304} kind="duration" durationStyle="clock" durationScale="minutes" />
+
+{/* Duration + unit label */}
+<KpiValue value={112} kind="duration" unit="avg" />
+```
+
+Do not reimplement `formatSecondsToDuration` in the app — `KpiValue` owns formatting.
 
 ---
 
 ## 4. Common mistakes
 
-### Mistake 1 — Passing Tile/TileBody flex props to Card/CardContent
+### Mistake 1 — Using raw DS `Card` instead of `KpiCard`
 
 ```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>
+// ❌ Wrong — loses disabled cascade and KPI defaults (size="sm", gap)
+<Card size="sm">
+  <CardHeader>
+    <CardTitle>Answered</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <KpiValue value={123} />
+  </CardContent>
 </Card>
 
-// ✅ Correct — use className with Tailwind utilities
-<Card className="min-w-[228px]">
-  <CardContent className="flex items-center gap-1">…</CardContent>
-</Card>
+// ✅ Correct
+<KpiCard>
+  <CardHeader>
+    <CardTitle>Answered</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <KpiValue value={123} />
+  </CardContent>
+</KpiCard>
 ```
 
-`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.
+### Mistake 2 — Hand-formatting values or using raw `Skeleton`
+
+```tsx
+// ❌ Wrong
+<span className="text-3xl font-bold">{formatDuration(123)}</span>
+<Skeleton className="h-6 w-18" />
+
+// ✅ Correct
+<KpiValue value={123} kind="duration" />
+<KpiValueSkeleton />
+```
+
+### Mistake 3 — Passing Tile/TileBody flex props to KpiCard / CardContent
+
+```tsx
+// ❌ Wrong — tractor FlexProps on the card
+<KpiCard minWidth="228px" px="xxs" py="xxs">
+  <CardContent alignItems="center" gap="xxxs">…</CardContent>
+</KpiCard>
 
-Source: `packages/ds/src/components/card.tsx`
+// ✅ Correct — Tailwind via className
+<KpiCard className="min-w-[228px]">
+  <CardContent className="flex flex-col gap-1">…</CardContent>
+</KpiCard>
+```
 
-### Mistake 2 — Placing CardAction outside CardHeader
+### Mistake 4 — Placing CardAction outside CardHeader
 
 ```tsx
-// ❌ Wrong — action renders in document flow; loses top-right pinning
-<Card>
-  <CardAction>
-    <Button variant="ghost" size="icon">…</Button>
-  </CardAction>
+// ❌ Wrong
+<KpiCard>
+  <CardAction>…</CardAction>
   <CardHeader>
     <CardTitle>Answered</CardTitle>
   </CardHeader>
   <CardContent>…</CardContent>
-</Card>
+</KpiCard>
 
 // ✅ Correct — CardAction must be a child of CardHeader
-<Card>
+<KpiCard>
   <CardHeader>
     <CardTitle>Answered</CardTitle>
-    <CardAction>
-      <Button variant="ghost" size="icon">…</Button>
-    </CardAction>
+    <CardAction>…</CardAction>
   </CardHeader>
   <CardContent>…</CardContent>
-</Card>
+</KpiCard>
 ```
 
-`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
+### Mistake 5 — Keeping TILE_VALUE / TileValue imports after migration
 
 ```tsx
-// ❌ Wrong — keeping the enum import after TileValue is removed
+// ❌ Wrong
 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`;
-}
+// ✅ Correct
+import { KpiCard, KpiValue } from '@aircall/blocks';
+import { CardContent, CardHeader, CardTitle } from '@aircall/ds';
 
-<Card className="min-w-36">
+<KpiCard>
   <CardHeader>
-    <CardTitle className="text-xs font-medium text-muted-foreground">AHT</CardTitle>
+    <CardTitle>AHT</CardTitle>
   </CardHeader>
   <CardContent>
-    <span className="text-2xl font-bold tabular-nums">{formatDuration(123)}</span>
+    <KpiValue value={123} kind="duration" />
   </CardContent>
-</Card>
+</KpiCard>
 ```
 
-`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
+### Mistake 6 — Using CardTitle for the metric value instead of the label
 
 ```tsx
-// ❌ Wrong — CardTitle used for the big number; label lost
-<Card>
+// ❌ Wrong — CardTitle used for the big number
+<KpiCard>
   <CardHeader>
     <CardTitle>123</CardTitle>
   </CardHeader>
-</Card>
+</KpiCard>
 
-// ✅ Correct — CardTitle holds the label; value sits in CardContent
-<Card className="min-w-36">
+// ✅ Correct — CardTitle = label; KpiValue = metric
+<KpiCard>
   <CardHeader>
-    <CardTitle className="text-xs font-medium text-muted-foreground">Answered</CardTitle>
+    <CardTitle>Answered</CardTitle>
   </CardHeader>
   <CardContent>
-    <span className="text-2xl font-bold tabular-nums">123</span>
+    <KpiValue value={123} />
   </CardContent>
-</Card>
+</KpiCard>
 ```
-
-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`