@aircall/ds 0.14.0 → 0.15.0

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

@@ -0,0 +1,225 @@
+---
+name: aircall-ds/migrate-tractor/alert
+description: >
+  Migrate Tractor Banner (Banner, BannerHeading, BannerIcon, BannerParagraph) to
+  @aircall/ds Alert (rounded) vs Banner (inline). Load when a file imports Banner*
+  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/alert-and-banner.md"
+---
+
+This skill builds on aircall-ds/migrate-tractor. Apply all cross-cutting rules from that skill (prop renames, `render` prop, data attributes) before the alert-specific steps below.
+
+## 1. Alert vs Banner — pick the right component
+
+Tractor `Banner` maps to **two** DS components. Choose based on visual shape:
+
+| If the Tractor `Banner` looks like… | Use DS component |
+| --- | --- |
+| Rounded card-style callout (`rounded-3xl`, full border) | `Alert` |
+| Full-width inline strip with accent edge (square corners, border on one side) | `Banner` |
+
+`Banner` re-exports the `Alert*` sub-parts under `Banner*` aliases — the children grammar is identical. Pick the container; the parts follow.
+
+## 2. Sub-part mapping
+
+| Tractor | DS (`Alert`) | DS (`Banner`) |
+| --- | --- | --- |
+| `BannerHeading` | `AlertTitle` | `BannerTitle` |
+| `BannerIcon` | first `<svg>` child — **no wrapper** | same |
+| `BannerSuffix` | `AlertAction` | `BannerAction` |
+| `BannerParagraph` (body text) | `AlertDescription` | `BannerDescription` |
+
+> **Icon is a direct child, not a part.** `Alert`/`Banner` detect a leading icon via `has-[>svg]` CSS. Render the icon as the **first child** — never wrap it. There is no `AlertIcon` or `BannerIcon` component in DS.
+
+## 3. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Alert, AlertAction, AlertDescription, AlertTitle,
+Banner, BannerAction, BannerDescription, BannerTitle,
+```
+
+All eight names exist in the published public API. Do not use any other Alert/Banner parts.
+
+## 4. Imports
+
+```tsx
+import {
+  Alert, AlertTitle, AlertDescription, AlertAction,
+  Banner, BannerTitle, BannerDescription, BannerAction,
+  Button,
+} from '@aircall/ds';
+import { Info, AlertTriangle, X } from '@aircall/react-icons';
+```
+
+## 5. Before / After
+
+### Before (Tractor)
+
+```tsx
+import { Banner, BannerHeading, BannerIcon, BannerParagraph, BannerSuffix } from '@aircall/tractor';
+
+// Rounded callout
+<Banner variant="informative">
+  <BannerIcon><Info /></BannerIcon>
+  <BannerHeading>Heads up</BannerHeading>
+  <BannerParagraph>Your trial ends in 3 days.</BannerParagraph>
+  <BannerSuffix><button onClick={onDismiss}>✕</button></BannerSuffix>
+</Banner>
+
+// Full-width inline strip
+<Banner variant="critical">
+  <BannerIcon><AlertTriangle /></BannerIcon>
+  <BannerHeading>Limited connectivity</BannerHeading>
+  <BannerParagraph>Some calls may not connect.</BannerParagraph>
+  <BannerSuffix><button onClick={onRetry}>Retry</button></BannerSuffix>
+</Banner>
+```
+
+### After (DS)
+
+```tsx
+import {
+  Alert, AlertTitle, AlertDescription, AlertAction,
+  Banner, BannerTitle, BannerDescription, BannerAction,
+  Button,
+} from '@aircall/ds';
+import { Info, AlertTriangle, X } from '@aircall/react-icons';
+
+// Rounded callout → Alert
+<Alert variant="info">
+  <Info />                       {/* BannerIcon → first <svg> child, no wrapper */}
+  <AlertTitle>Heads up</AlertTitle>
+  <AlertDescription>Your trial ends in 3 days.</AlertDescription>
+  <AlertAction>
+    <Button variant="ghost" size="icon-sm" onClick={onDismiss}><X /></Button>
+  </AlertAction>
+</Alert>
+
+// Full-width inline strip → Banner
+<Banner variant="error" borderDirection="top">
+  <AlertTriangle />
+  <BannerTitle>Limited connectivity</BannerTitle>
+  <BannerDescription>Some calls may not connect.</BannerDescription>
+  <BannerAction>
+    <Button variant="outline" size="sm" onClick={onRetry}>Retry</Button>
+  </BannerAction>
+</Banner>
+```
+
+## 6. Variant mapping
+
+| Tractor variant | DS variant |
+| --- | --- |
+| `informative` | `info` |
+| `critical` | `error` |
+| `warning` | `warning` |
+| `positive` / `success` | `success` |
+| (default / none) | `default` |
+
+Both `Alert` and `Banner` share the same set: `default` / `info` / `success` / `warning` / `error`.
+
+## 7. `Banner`-only prop: `borderDirection`
+
+`Banner` accepts `borderDirection="top" | "bottom"` to place the accent border. `Alert` has no border-side prop — it is fully bordered and rounded.
+
+## 8. Common Mistakes
+
+### Mistake 1 — Wrapping the icon in a part component
+
+```tsx
+// Wrong
+<Alert variant="info">
+  <AlertIcon><Info /></AlertIcon>   {/* AlertIcon does not exist in @aircall/ds */}
+  ...
+</Alert>
+
+// Correct
+<Alert variant="info">
+  <Info />                           {/* bare <svg> first child activates the grid */}
+  ...
+</Alert>
+```
+
+`Alert`/`Banner` use `has-[>svg]` to detect the icon slot. Wrapping the SVG in any element breaks the CSS selector and the icon fails to render in the correct grid area.
+Source: `packages/ds/src/components/alert.tsx`
+
+---
+
+### Mistake 2 — Using `destructive` instead of `error`
+
+```tsx
+// Wrong
+<Alert variant="destructive">...</Alert>   {/* destructive is a Button variant, not Alert */}
+
+// Correct
+<Alert variant="error">...</Alert>         {/* maps Tractor critical */}
+```
+
+`destructive` is a `Button` variant. `Alert`/`Banner` only accept `default | info | success | warning | error`. Passing an unknown variant silently falls through to `default` styling.
+Source: `packages/ds/src/components/alert.tsx`
+
+---
+
+### Mistake 3 — Using `AlertAction`/`BannerAction` for the icon instead of the suffix
+
+```tsx
+// Wrong
+<Alert variant="warning">
+  <AlertAction><AlertTriangle /></AlertAction>  {/* icon in the trailing action slot */}
+  <AlertTitle>Watch out</AlertTitle>
+</Alert>
+
+// Correct
+<Alert variant="warning">
+  <AlertTriangle />         {/* first <svg> child → leading icon slot */}
+  <AlertTitle>Watch out</AlertTitle>
+</Alert>
+```
+
+`AlertAction`/`BannerAction` is the **trailing** slot (self-positions right, vertically centered). It is for close buttons or CTAs, not the leading icon. Placing the icon there yields wrong layout.
+Source: `packages/ds/src/components/alert.tsx`
+
+---
+
+### Mistake 4 — Setting icon color manually
+
+```tsx
+// Wrong
+<Alert variant="info">
+  <Info className="text-blue-500" />   {/* manual color overrides variant-driven color */}
+  ...
+</Alert>
+
+// Correct
+<Alert variant="info">
+  <Info />                              {/* variant applies [&>svg]:text-info automatically */}
+  ...
+</Alert>
+```
+
+`Alert`/`Banner` apply `[&>svg]:text-<variant>` on the root. Explicit color classes on the icon fight the cascade and cause inconsistency across themes.
+Source: `packages/ds/src/components/alert.tsx`
+
+---
+
+### Mistake 5 — Using `borderDirection` on `Alert`
+
+```tsx
+// Wrong
+<Alert variant="warning" borderDirection="top">...</Alert>  {/* prop not supported on Alert */}
+
+// Correct
+<Banner variant="warning" borderDirection="top">            {/* Banner is the inline strip */}
+  ...
+</Banner>
+```
+
+`borderDirection` is a `Banner`-only prop (inline strip component). `Alert` is always fully bordered and rounded; it has no border-side prop. The prop is silently ignored on `Alert`.
+Source: `packages/ds/src/components/banner.tsx`

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'`.