@aircall/ds 0.13.0 → 0.15.0

package/skills/aircall-ds/migrate-tractor/avatar/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: aircall-ds/migrate-tractor/avatar
+description: >
+  Migrate Tractor Avatar and QuickAvatar to the @aircall/ds Avatar compound
+  (Avatar, AvatarImage, AvatarFallback, AvatarBadge, AvatarGroup, AvatarGroupCount).
+  Load when a file imports Avatar or QuickAvatar from @aircall/tractor.
+type: sub-skill
+library: aircall-ds
+library_version: "0.13.0"
+requires:
+  - aircall-ds/setup
+  - aircall-ds/migrate-tractor
+sources:
+  - "aircall/hydra:docs/migration-guides/tractor-to-ds/recipes/avatar.md"
+---
+
+This skill builds on aircall-ds/migrate-tractor.
+
+## 1. Component mapping
+
+| Tractor part | DS replacement | Notes |
+| --- | --- | --- |
+| `<Avatar src url name size>` | `<Avatar size><AvatarImage /><AvatarFallback /></Avatar>` | Compound — image and fallback are explicit children |
+| `<QuickAvatar>` | `<Avatar>` | Identical DS compound; `QuickAvatar` had no extra API |
+| `name="Jane Doe"` prop | `<AvatarFallback>JD</AvatarFallback>` | Derive initials yourself; DS has no auto-initials prop |
+| Tractor `Badge` on avatar | `<AvatarBadge className="bg-…" />` | Child of `Avatar`; color set via `className` |
+| Tractor `AvatarGroup` stack | `<AvatarGroup>` | Wraps `Avatar` children with overlap ring |
+| Overflow chip `+N` | `<AvatarGroupCount>+3</AvatarGroupCount>` | Last child inside `AvatarGroup` |
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Avatar, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarImage
+```
+
+## 3. Imports
+
+```tsx
+import {
+  Avatar,
+  AvatarBadge,
+  AvatarFallback,
+  AvatarGroup,
+  AvatarGroupCount,
+  AvatarImage,
+} from '@aircall/ds';
+```
+
+## 4. Size mapping (Tractor → DS)
+
+| Tractor `size` | DS `size` | Rendered px |
+| --- | --- | --- |
+| `small` | `sm` | 24 px |
+| `regular` (default) | `default` | 32 px |
+| `large` | `xl` | 48 px |
+| `xLarge` | `xl` | 48 px |
+| _(none / 20 px)_ | `xs` | 20 px |
+| _(none / 40 px)_ | `lg` | 40 px |
+
+There is no 64 px size in DS. Map Tractor `xLarge` (64 px) to `xl` (48 px) — the closest available size.
+
+## 5. Before / After examples
+
+### 5a. Basic avatar with image and initials fallback
+
+**Before (Tractor):**
+```tsx
+import { Avatar } from '@aircall/tractor';
+
+<Avatar
+  src="https://example.com/photo.jpg"
+  name="Jane Doe"
+  size="regular"
+/>
+```
+
+**After (DS):**
+```tsx
+import { Avatar, AvatarFallback, AvatarImage } from '@aircall/ds';
+
+<Avatar size="default">
+  <AvatarImage src="https://example.com/photo.jpg" alt="Jane Doe" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+### 5b. QuickAvatar migration
+
+**Before (Tractor):**
+```tsx
+import { QuickAvatar } from '@aircall/tractor';
+
+<QuickAvatar src={photoUrl} size="large" />
+```
+
+**After (DS):**
+```tsx
+import { Avatar, AvatarFallback, AvatarImage } from '@aircall/ds';
+
+<Avatar size="xl">
+  <AvatarImage src={photoUrl} alt="" />
+  <AvatarFallback />
+</Avatar>
+```
+
+### 5c. Avatar with status badge
+
+**Before (Tractor):**
+```tsx
+import { Avatar } from '@aircall/tractor';
+
+<Avatar src={url} name="Jane Doe" size="regular" badge="online" />
+```
+
+**After (DS):**
+```tsx
+import { Avatar, AvatarBadge, AvatarFallback, AvatarImage } from '@aircall/ds';
+
+<Avatar size="default">
+  <AvatarImage src={url} alt="Jane Doe" />
+  <AvatarFallback>JD</AvatarFallback>
+  <AvatarBadge className="bg-success" />
+</Avatar>
+```
+
+`AvatarBadge` auto-positions at bottom-right and sizes itself from the parent `Avatar`'s `size` attribute. Pass a Tailwind background utility via `className` to set the status color.
+
+### 5d. Overlapping avatar group with overflow count
+
+**Before (Tractor):**
+```tsx
+import { Avatar, AvatarGroup } from '@aircall/tractor';
+
+<AvatarGroup max={3} users={users} />
+```
+
+**After (DS):**
+```tsx
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarGroup,
+  AvatarGroupCount,
+  AvatarImage,
+} from '@aircall/ds';
+
+<AvatarGroup>
+  <Avatar>
+    <AvatarImage src={users[0].photo} alt={users[0].name} />
+    <AvatarFallback>AB</AvatarFallback>
+  </Avatar>
+  <Avatar>
+    <AvatarImage src={users[1].photo} alt={users[1].name} />
+    <AvatarFallback>CD</AvatarFallback>
+  </Avatar>
+  <AvatarGroupCount>+{users.length - 2}</AvatarGroupCount>
+</AvatarGroup>
+```
+
+DS has no built-in `max` or `users` props — slice the array yourself before rendering and compute the overflow count explicitly.
+
+## 6. Common mistakes
+
+### Mistake 1: Passing `name` as a prop instead of rendering `AvatarFallback`
+
+**Wrong:**
+```tsx
+import { Avatar } from '@aircall/ds';
+
+<Avatar name="Jane Doe" size="default" />
+```
+
+**Correct:**
+```tsx
+import { Avatar, AvatarFallback, AvatarImage } from '@aircall/ds';
+
+<Avatar size="default">
+  <AvatarImage src={url} alt="Jane Doe" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+DS `Avatar` has no `name` prop. The prop is silently ignored and no fallback text renders when the image fails to load — the avatar shows a blank circle instead of initials.
+
+Source: packages/ds/src/components/avatar.tsx — `AvatarProps` extends `AvatarPrimitive.Root.Props` which has no `name` field.
+
+---
+
+### Mistake 2: Omitting `AvatarFallback` when no image src is provided
+
+**Wrong:**
+```tsx
+import { Avatar, AvatarImage } from '@aircall/ds';
+
+<Avatar size="default">
+  <AvatarImage src={maybeUndefinedUrl} alt="User" />
+</Avatar>
+```
+
+**Correct:**
+```tsx
+import { Avatar, AvatarFallback, AvatarImage } from '@aircall/ds';
+
+<Avatar size="default">
+  <AvatarImage src={maybeUndefinedUrl} alt="User" />
+  <AvatarFallback>U</AvatarFallback>
+</Avatar>
+```
+
+`AvatarImage` is a Base UI image that automatically swaps to `AvatarFallback` on load failure or when `src` is absent. Without `AvatarFallback`, a failed or missing image leaves an empty, unstyled circle with no content.
+
+Source: packages/ds/src/components/avatar.tsx — `AvatarFallback` renders via `AvatarPrimitive.Fallback` which is only shown when the image is unavailable.
+
+---
+
+### Mistake 3: Placing `AvatarBadge` outside `Avatar`
+
+**Wrong:**
+```tsx
+import { Avatar, AvatarBadge, AvatarFallback, AvatarImage } from '@aircall/ds';
+
+<div style={{ position: 'relative' }}>
+  <Avatar size="default">
+    <AvatarImage src={url} alt="Jane Doe" />
+    <AvatarFallback>JD</AvatarFallback>
+  </Avatar>
+  <AvatarBadge className="bg-success" />
+</div>
+```
+
+**Correct:**
+```tsx
+import { Avatar, AvatarBadge, AvatarFallback, AvatarImage } from '@aircall/ds';
+
+<Avatar size="default">
+  <AvatarImage src={url} alt="Jane Doe" />
+  <AvatarFallback>JD</AvatarFallback>
+  <AvatarBadge className="bg-success" />
+</Avatar>
+```
+
+`AvatarBadge` uses `absolute` positioning and reads the parent `group/avatar`'s `data-size` attribute to scale itself. Outside `Avatar`, it loses both the positioning context and the size-driven Tailwind group variants, so it renders at the wrong position and wrong size.
+
+Source: packages/ds/src/components/avatar.tsx — `AvatarBadge` className includes `absolute right-0 bottom-0` and `group-data-[size=…]/avatar:size-…` variants.
+
+---
+
+### Mistake 4: Using Tractor `size="large"` or `size="xLarge"` expecting a 64 px avatar
+
+**Wrong:**
+```tsx
+import { Avatar, AvatarFallback, AvatarImage } from '@aircall/ds';
+
+<Avatar size="large">
+  <AvatarImage src={url} alt="User" />
+  <AvatarFallback>U</AvatarFallback>
+</Avatar>
+```
+
+**Correct:**
+```tsx
+import { Avatar, AvatarFallback, AvatarImage } from '@aircall/ds';
+
+<Avatar size="xl">
+  <AvatarImage src={url} alt="User" />
+  <AvatarFallback>U</AvatarFallback>
+</Avatar>
+```
+
+DS has no `"large"` size token and no 64 px size. Passing `size="large"` falls back to the `default` (32 px) size because `data-size="large"` matches none of the Tailwind variants. The closest DS size to Tractor `xLarge` (64 px) is `xl` (48 px).
+
+Source: packages/ds/src/components/avatar.tsx — `AvatarProps` size union is `'xs' | 'sm' | 'default' | 'lg' | 'xl'`.

package/skills/aircall-ds/migrate-tractor/badge/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: aircall-ds/migrate-tractor/badge
+description: >
+  Migrate Tractor Tag and CounterBadge to @aircall/ds Badge, CounterBadge, BadgeGroup,
+  and BadgeGroupCount. Load when a file imports Tag or CounterBadge from @aircall/tractor.
+  Maps Tractor variant (grey/primary/blue/red/yellow/green/purple/pink/dark* prefixes)
+  to the DS color + tone two-axis model, and Tractor status Badge (dot) to AvatarBadge.
+type: sub-skill
+library: aircall-ds
+library_version: "0.13.0"
+requires:
+  - aircall-ds/setup
+  - aircall-ds/migrate-tractor
+sources:
+  - "aircall/hydra:docs/migration-guides/tractor-to-ds/recipes/badge.md"
+---
+
+This skill builds on aircall-ds/migrate-tractor.
+
+## 1. Component mapping
+
+Tractor's badge surface had three distinct concepts that map to different DS components:
+
+| Tractor component | DS replacement | Notes |
+| --- | --- | --- |
+| `<Tag>` | `<Badge>` | Color model changes from single `variant` to `color` + `tone` |
+| `<CounterBadge>` | `<CounterBadge>` | No `max` prop — cap the value yourself before passing as children |
+| `<Badge>` (status dot) | `<AvatarBadge>` | Tractor's dot-indicator badge is unrelated to DS `Badge`; see the avatar skill |
+| _(grouping)_ | `<BadgeGroup>` + `<BadgeGroupCount>` | Wraps multiple badges; `BadgeGroupCount` renders the overflow "+N" chip |
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Badge, BadgeGroup, BadgeGroupCount
+CounterBadge, counterBadgeVariants
+AvatarBadge
+Chip, ChipRemove
+```
+
+## 3. Imports
+
+```tsx
+import { Badge, BadgeGroup, BadgeGroupCount, CounterBadge } from '@aircall/ds';
+```
+
+Icons inside badges import from `@aircall/react-icons` — never from `lucide-react` directly.
+
+## 4. `Tag` variant → `Badge` color + tone
+
+DS Badge uses two orthogonal props instead of Tractor's single `variant`:
+
+- `color`: `charcoal` (default) · `red` · `green` · `blue` · `purple` · `yellow` · `pink`
+- `tone`: `dark` · `medium-dark` · `medium-light` · `light` (default)
+
+| Tractor `variant` | DS `color` | DS `tone` |
+| --- | --- | --- |
+| `grey` / `white` | `charcoal` | `light` |
+| `secondary` | `charcoal` | `medium-light` |
+| `lightSecondary` | `charcoal` | `light` |
+| `darkSecondary` | `charcoal` | `medium-dark` |
+| `primary` | `green` | `medium-light` |
+| `lightPrimary` | `green` | `light` |
+| `darkPrimary` | `green` | `dark` |
+| `blue` | `blue` | `medium-light` |
+| `darkBlue` | `blue` | `dark` |
+| `red` | `red` | `medium-light` |
+| `darkRed` | `red` | `dark` |
+| `yellow` | `yellow` | `medium-light` |
+| `darkYellow` | `yellow` | `dark` |
+| `green` | `green` | `medium-light` |
+| `darkGreen` | `green` | `dark` |
+| `purple` | `purple` | `medium-light` |
+| `darkPurple` | `purple` | `dark` |
+| `pink` | `pink` | `medium-light` |
+
+> The base color variant maps to `medium-light`; `dark*` variants map to `dark` or `medium-dark`. `light*` variants map to `light`. Pick the tone that best matches the surface.
+
+### Hard-coded hex colors (`bg` prop)
+
+When Tractor used a hard-coded hex (e.g. `bg="#0761B5"`), pass it via `legacyColor` — DS resolves it to the nearest `color` + `tone` at render time from an internal map. Unknown hexes fall back to `charcoal` / `dark`.
+
+```tsx
+<Badge legacyColor="#0761B5">Sales</Badge>
+```
+
+## 5. Size mapping
+
+| Tractor `size` | DS `size` |
+| --- | --- |
+| `xSmall` | `default` (20px) |
+| `small` | `default` (20px) |
+| `regular` (default) | `default` (20px) |
+| `large` | `lg` (24px) |
+
+DS has no `mode` prop (`outline` / `fill`). Use a lighter `tone` (e.g. `light`) to approximate the old outline look.
+
+## 6. CounterBadge
+
+DS `CounterBadge` has no `max` prop. Cap the displayed value yourself before passing as children:
+
+```tsx
+<CounterBadge>{count > 99 ? '99+' : count}</CounterBadge>
+```
+
+Available `variant` values: `default` (destructive background) · `secondary` · `ghost`.
+
+## 7. Grouping badges
+
+Use `BadgeGroup` to wrap a set of badges with consistent spacing, and `BadgeGroupCount` for the trailing overflow chip:
+
+```tsx
+<BadgeGroup>
+  <Badge color="blue" tone="medium-light">Support</Badge>
+  <Badge color="green" tone="medium-light">Active</Badge>
+  <BadgeGroupCount>{overflow}</BadgeGroupCount>
+</BadgeGroup>
+```
+
+## 8. Before / After examples
+
+### 8a. Simple Tag → Badge (variant rename)
+
+**Before (Tractor):**
+```tsx
+import { Tag } from '@aircall/tractor';
+
+<Tag variant="primary">Active</Tag>
+```
+
+**After (DS):**
+```tsx
+import { Badge } from '@aircall/ds';
+
+<Badge color="green" tone="medium-light">Active</Badge>
+```
+
+> Tractor `primary` = green brand color → DS `color="green"` `tone="medium-light"`.
+
+### 8b. Dark variant
+
+**Before (Tractor):**
+```tsx
+import { Tag } from '@aircall/tractor';
+
+<Tag variant="darkBlue">Escalated</Tag>
+```
+
+**After (DS):**
+```tsx
+import { Badge } from '@aircall/ds';
+
+<Badge color="blue" tone="dark">Escalated</Badge>
+```
+
+### 8c. Hard-coded hex color
+
+**Before (Tractor):**
+```tsx
+import { Tag } from '@aircall/tractor';
+
+<Tag bg="#0761B5">Sales</Tag>
+```
+
+**After (DS):**
+```tsx
+import { Badge } from '@aircall/ds';
+
+<Badge legacyColor="#0761B5">Sales</Badge>
+```
+
+### 8d. CounterBadge with max cap
+
+**Before (Tractor):**
+```tsx
+import { CounterBadge } from '@aircall/tractor';
+
+<CounterBadge count={count} max={99} />
+```
+
+**After (DS):**
+```tsx
+import { CounterBadge } from '@aircall/ds';
+
+<CounterBadge>{count > 99 ? '99+' : count}</CounterBadge>
+```
+
+### 8e. Icon inside a Badge
+
+**Before (Tractor):**
+```tsx
+import { Tag } from '@aircall/tractor';
+import { CheckCircle } from '@aircall/react-icons';
+
+<Tag variant="green"><CheckCircle size={12} /> Verified</Tag>
+```
+
+**After (DS):**
+```tsx
+import { Badge } from '@aircall/ds';
+import { CheckCircle } from '@aircall/react-icons';
+
+<Badge color="green" tone="medium-light"><CheckCircle /> Verified</Badge>
+```
+
+> DS auto-sizes SVG children via `[&>svg]:size-3!` (default) or `[&>svg]:size-4!` (lg). Do not pass a `size` prop to the icon.
+
+## 9. Common mistakes
+
+### Mistake 1: Using `variant` instead of `color` + `tone`
+
+```tsx
+// Wrong — DS Badge has no `variant` prop; it is silently ignored
+<Badge variant="primary">Active</Badge>
+
+// Correct — map to the two-axis color + tone model
+<Badge color="green" tone="medium-light">Active</Badge>
+```
+
+**Mechanism:** DS Badge replaced Tractor's single `variant` string with two orthogonal props `color` and `tone`. Passing `variant` goes to the underlying `span` as an unknown HTML attribute and has no visual effect — the badge renders with the default charcoal/light appearance instead of the intended color.
+
+Source: `packages/ds/src/components/badge.tsx` — `badgeVariants` has `color` and `tone` keys, no `variant` key.
+
+---
+
+### Mistake 2: Mapping Tractor status `Badge` (dot) to DS `Badge`
+
+```tsx
+// Wrong — DS Badge is a label chip, not a status dot
+<Badge status="online" />
+
+// Correct — Tractor's status dot maps to AvatarBadge
+import { Avatar, AvatarBadge, AvatarImage } from '@aircall/ds';
+
+<Avatar>
+  <AvatarImage src={src} alt={name} />
+  <AvatarBadge />
+</Avatar>
+```
+
+**Mechanism:** Tractor had two components both named `Badge`: a label chip (`Tag`) and a small status dot (`Badge`). DS names them differently — `Badge` is the label chip and `AvatarBadge` is the status indicator that composes inside `Avatar`. Migrating the dot to DS `Badge` renders a text chip with no content instead of a dot.
+
+Source: `packages/ds/src/components/badge.tsx` — `Badge` is a label chip; `packages/ds/src/components/avatar.tsx` exports `AvatarBadge` for the status dot.
+
+---
+
+### Mistake 3: Relying on DS `CounterBadge` to cap overflow automatically
+
+```tsx
+// Wrong — DS CounterBadge has no `max` prop; it renders the raw number
+<CounterBadge max={99} count={count} />
+
+// Correct — cap the value yourself before passing as children
+<CounterBadge>{count > 99 ? '99+' : count}</CounterBadge>
+```
+
+**Mechanism:** Tractor's `CounterBadge` accepted a `max` prop and formatted "99+" internally. DS `CounterBadge` is a presentational span that renders whatever children it receives — the cap logic is the caller's responsibility. Passing `max` and `count` as props results in an empty badge with two unknown HTML attributes instead of the formatted string.
+
+Source: `packages/ds/src/components/counter-badge.tsx` — `CounterBadge.Props` extends `useRender.ComponentProps<'span'>` with only a `variant` prop; no `max` or `count` keys.
+
+---
+
+### Mistake 4: Using `outline` / `fill` mode to style a badge
+
+```tsx
+// Wrong — DS Badge has no `mode` prop
+<Badge color="blue" mode="outline">Beta</Badge>
+
+// Correct — reach for a lighter tone to approximate the outline look
+<Badge color="blue" tone="light">Beta</Badge>
+```
+
+**Mechanism:** Tractor's `Tag` supported a `mode` prop (`outline` / `fill`) that toggled between a bordered and a filled appearance. DS Badge has no `mode` prop — the visual weight is controlled entirely by `tone`. A lighter tone (`light` or `medium-light`) produces a softer background that approximates the old outline look.
+
+Source: `packages/ds/src/components/badge.tsx` — `badgeVariants` has `size`, `color`, and `tone` variants; no `mode` variant.