@aircall/ds 0.14.0 → 0.15.0

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

@@ -0,0 +1,298 @@
+---
+name: aircall-ds/migrate-tractor/item
+description: >
+  Migrate Tractor Menu/MenuItem and List/ListItem to the @aircall/ds Item family
+  (ItemGroup, Item, ItemMedia, ItemContent, ItemTitle, ItemDescription, ItemActions,
+  ItemHeader, ItemFooter, ItemSeparator). Load when a file imports Menu, MenuItem,
+  List, or ListItem 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/item.md"
+---
+
+This skill builds on aircall-ds/migrate-tractor.
+
+## 1. Component mapping
+
+Tractor's `Menu`/`MenuItem` and `List`/`ListItem` are two separate component families. DS collapses them into a single `Item` family. Use `DropdownMenu` instead if the list lives inside a popover/context-menu trigger.
+
+| Tractor | @aircall/ds | Notes |
+| --- | --- | --- |
+| `<Menu>` / `<List>` | `<ItemGroup>` | Wrapper; manages layout and stacking |
+| `<MenuItem>` / `<ListItem>` | `<Item>` | Single row; supports `variant` and `size` |
+| Left icon / avatar slot | `<ItemMedia>` | `variant="icon"` for icons, `variant="image"` for avatars/photos |
+| Primary text | `<ItemTitle>` | Inside `<ItemContent>` |
+| Secondary text / subtext | `<ItemDescription>` | Inside `<ItemContent>`, renders as `<p>` |
+| Text content wrapper | `<ItemContent>` | Grows to fill; direct parent of Title + Description |
+| Right slot (buttons, badges) | `<ItemActions>` | Flex row, shrinks to content |
+| — | `<ItemHeader>` | Full-width row spanning the top of the item (optional) |
+| — | `<ItemFooter>` | Full-width row spanning the bottom of the item (optional) |
+| — | `<ItemSeparator>` | Horizontal rule between groups |
+
+## 2. Imports
+
+```tsx
+import {
+  Item,
+  ItemActions,
+  ItemContent,
+  ItemDescription,
+  ItemFooter,
+  ItemGroup,
+  ItemHeader,
+  ItemMedia,
+  ItemSeparator,
+  ItemTitle
+} from '@aircall/ds';
+```
+
+For icons, import from `@aircall/react-icons` — never from `lucide-react` directly:
+
+```tsx
+import { PhoneCallFill } from '@aircall/react-icons';
+```
+
+## 3. Key props
+
+### ItemGroup
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `stackedItems` | `boolean` | `false` | Renders the group as a bordered card with separators — classic settings panel |
+
+### Item
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `variant` | `default` \| `outline` \| `muted` | `default` |
+| `size` | `xs` \| `sm` \| `default` | `default` |
+| `render` | Base UI render element | — |
+
+`size="xs"` is the dropdown-menu density. `variant="outline"` adds a visible border. `variant="muted"` adds a tinted background.
+
+### ItemMedia
+
+| Prop | Values | Default | Effect |
+| --- | --- | --- | --- |
+| `variant` | `default` \| `icon` \| `image` | `default` | `icon` auto-sizes SVGs to 16 px; `image` gives a square slot (40 px default, responsive to item size) for avatars and photos |
+
+## 4. Before / After examples
+
+### Settings row (Tractor `Menu` with a toggle)
+
+```tsx
+// Before
+import { Menu, MenuItem } from '@aircall/tractor';
+
+<Menu>
+  <MenuItem
+    label="Enable notifications"
+    description="Get a desktop alert for incoming calls."
+    action={<Toggle checked={enabled} onChange={setEnabled} />}
+  />
+</Menu>
+```
+
+```tsx
+// After
+import { Item, ItemActions, ItemContent, ItemDescription, ItemGroup, ItemTitle } from '@aircall/ds';
+import { Switch } from '@aircall/ds';
+
+<ItemGroup>
+  <Item>
+    <ItemContent>
+      <ItemTitle>Enable notifications</ItemTitle>
+      <ItemDescription>Get a desktop alert for incoming calls.</ItemDescription>
+    </ItemContent>
+    <ItemActions>
+      <Switch checked={enabled} onCheckedChange={setEnabled} />
+    </ItemActions>
+  </Item>
+</ItemGroup>
+```
+
+### Contact list (Tractor `List` with avatar + secondary text)
+
+```tsx
+// Before
+import { List, ListItem } from '@aircall/tractor';
+
+<List>
+  {contacts.map(c => (
+    <ListItem
+      key={c.id}
+      avatar={<img src={c.avatar} alt={c.name} />}
+      primaryText={c.name}
+      secondaryText={c.lastMessage}
+    />
+  ))}
+</List>
+```
+
+```tsx
+// After
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  Button,
+  Item,
+  ItemActions,
+  ItemContent,
+  ItemDescription,
+  ItemGroup,
+  ItemMedia,
+  ItemTitle
+} from '@aircall/ds';
+import { PhoneCallFill } from '@aircall/react-icons';
+
+<ItemGroup>
+  {contacts.map(c => (
+    <Item key={c.id}>
+      <ItemMedia variant="image">
+        <Avatar>
+          <AvatarImage src={c.avatar} alt={c.name} />
+          <AvatarFallback>{initials(c.name)}</AvatarFallback>
+        </Avatar>
+      </ItemMedia>
+      <ItemContent>
+        <ItemTitle>{c.name}</ItemTitle>
+        <ItemDescription>{c.lastMessage}</ItemDescription>
+      </ItemContent>
+      <ItemActions>
+        <Button variant="ghost" size="icon-sm">
+          <PhoneCallFill className="size-4" />
+        </Button>
+      </ItemActions>
+    </Item>
+  ))}
+</ItemGroup>
+```
+
+### Stacked settings group with dividers
+
+```tsx
+// After
+import { Item, ItemContent, ItemDescription, ItemGroup, ItemTitle } from '@aircall/ds';
+
+<ItemGroup stackedItems>
+  <Item>
+    <ItemContent>
+      <ItemTitle>Notifications</ItemTitle>
+      <ItemDescription>Alert on incoming calls</ItemDescription>
+    </ItemContent>
+  </Item>
+  <Item>
+    <ItemContent>
+      <ItemTitle>Do not disturb</ItemTitle>
+      <ItemDescription>Silence all alerts</ItemDescription>
+    </ItemContent>
+  </Item>
+</ItemGroup>
+```
+
+`stackedItems` renders the group as a single bordered card. Adjacent items share borders — no gap between rows.
+
+## 5. Common mistakes
+
+### Mistake 1: Putting text directly in `<Item>` instead of `<ItemContent>`
+
+```tsx
+// Wrong — text string becomes a direct flex child of Item, not inside ItemContent
+<Item>
+  Enable notifications
+</Item>
+
+// Correct — always wrap text in ItemContent with ItemTitle / ItemDescription
+<Item>
+  <ItemContent>
+    <ItemTitle>Enable notifications</ItemTitle>
+  </ItemContent>
+</Item>
+```
+
+`Item` is a flex container whose children are the named slot components. A raw text string sits outside any slot and is not styled as a title — it misaligns with `ItemActions` and `ItemMedia`.
+
+Source: `packages/ds/src/components/item.tsx` — `ItemContent` carries `flex-1 flex-col gap-1` that positions the text column correctly.
+
+---
+
+### Mistake 2: Using `variant="icon"` for avatar/photo media
+
+```tsx
+// Wrong — variant="icon" clips the avatar and applies SVG-only sizing rules
+<ItemMedia variant="icon">
+  <Avatar>
+    <AvatarImage src={user.avatar} alt={user.name} />
+    <AvatarFallback>JD</AvatarFallback>
+  </Avatar>
+</ItemMedia>
+
+// Correct — use variant="image" for avatars and photos
+<ItemMedia variant="image">
+  <Avatar>
+    <AvatarImage src={user.avatar} alt={user.name} />
+    <AvatarFallback>JD</AvatarFallback>
+  </Avatar>
+</ItemMedia>
+```
+
+`variant="icon"` applies `[&_svg:not([class*='size-'])]:size-4` — it auto-sizes SVGs to 16 px and does not constrain the container. `variant="image"` sets a fixed square slot (`size-10`, responsive to item size) with `overflow-hidden rounded-sm` so the avatar fills the frame correctly.
+
+Source: `packages/ds/src/components/item.tsx` — `itemMediaVariants` defines `icon` and `image` separately.
+
+---
+
+### Mistake 3: Using `<ItemGroup>` for popover/context menus
+
+```tsx
+// Wrong — ItemGroup is for inline lists; it has no popover, trigger, or keyboard-menu semantics
+<ItemGroup>
+  <Item onClick={onEdit}>Edit</Item>
+  <Item onClick={onDelete}>Delete</Item>
+</ItemGroup>
+
+// Correct — use DropdownMenu for popover menus triggered by a button
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger, Button } from '@aircall/ds';
+
+<DropdownMenu>
+  <DropdownMenuTrigger render={<Button variant="ghost" size="icon" />}>
+    <MoreVertical />
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem onSelect={onEdit}>Edit</DropdownMenuItem>
+    <DropdownMenuItem onSelect={onDelete}>Delete</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+`ItemGroup`/`Item` is a layout primitive with `role="list"` — it has no focus trap, keyboard navigation, or popover positioning. Tractor's `Menu` was sometimes used for both inline lists and popover menus; DS splits these concerns into `Item` (inline) and `DropdownMenu` (popover).
+
+Source: `packages/ds/src/components/item.tsx` — `ItemGroup` renders a `<div role="list">` with no floating/portal behavior.
+
+---
+
+### Mistake 4: Omitting `stackedItems` and expecting automatic borders between items
+
+```tsx
+// Wrong — without stackedItems, items are separated by a gap (not bordered/merged)
+<ItemGroup>
+  <Item variant="outline">Row A</Item>
+  <Item variant="outline">Row B</Item>
+</ItemGroup>
+
+// Correct — use stackedItems to get a single bordered card with shared inner borders
+<ItemGroup stackedItems>
+  <Item>Row A</Item>
+  <Item>Row B</Item>
+</ItemGroup>
+```
+
+Without `stackedItems`, `ItemGroup` uses `gap-4` (or `gap-2.5` / `gap-2` for smaller sizes) between items. The `stackedItems` prop removes the gap and applies CSS sibling selectors that collapse adjacent borders into a single shared edge, producing a classic settings-panel appearance.
+
+Source: `packages/ds/src/components/item.tsx` — `ItemGroup` applies `stackedItems` via `data-stacked` and sibling border-collapse selectors.

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

@@ -0,0 +1,263 @@
+---
+name: aircall-ds/migrate-tractor/link
+description: >
+  Migrate Tractor Link (from @aircall/tractor Typography family) to @aircall/ds.
+  Covers the Link component exported from @aircall/tractor. Load when a file imports
+  Link 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:packages/ds/src/components/button.tsx"
+---
+
+This skill builds on aircall-ds/migrate-tractor. Apply all cross-cutting rules from that skill (prop renames, `render` prop, data attributes) before the link-specific steps below.
+
+## 1. Key premise
+
+`@aircall/ds` has **no `Link` component**. Tractor's `Link` was a styled inline `<a>` built on top of `Typography`. The DS equivalent is `Button` with `variant="link"` — it produces underlined primary-coloured text with no button chrome. For any navigational use (real `href`, router link), you must additionally supply a `render` prop so the output is an `<a>` element, not a `<button>`.
+
+## 2. Component mapping
+
+| Tractor | @aircall/ds | Notes |
+| --- | --- | --- |
+| `<Link href="…">text</Link>` | `<Button variant="link" render={<a href="…" />}>text</Button>` | Preserves anchor semantics |
+| `<Link href="…" target="_blank">` | `<Button variant="link" render={<a href="…" target="_blank" rel="noreferrer" />}>` | `target`/`rel` go on the rendered `<a>` |
+| `<Link as={RouterLink} to="…">` | `<Button variant="link" render={<RouterLink to="…" />}>` | Router links use `render`, not `as` |
+| `<Link onClick={fn}>text</Link>` | `<Button variant="link" onClick={fn}>text</Button>` | Click-only — no href, no anchor needed |
+
+## 3. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Button, buttonVariants
+```
+
+There is no `Link` export. `PaginationLink` exists but is scoped to the Pagination compound and must not be used here.
+
+## 4. Imports
+
+```tsx
+import { Button } from '@aircall/ds';
+```
+
+Icons (if needed alongside a link):
+
+```tsx
+import { ExternalLink } from '@aircall/react-icons';
+```
+
+Never import icons from `lucide-react` directly — always use `@aircall/react-icons`.
+
+## 5. Prop mapping
+
+| Tractor `Link` prop | DS equivalent | Notes |
+| --- | --- | --- |
+| `href` | Goes on `render={<a href="…" />}` | `Button` has no `href` prop |
+| `target` | Goes on `render={<a target="…" />}` | Same as `href` |
+| `rel` | Goes on `render={<a rel="…" />}` | Always set `rel="noreferrer"` for `target="_blank"` |
+| `as={RouterLink}` | `render={<RouterLink to="…" />}` | Base UI render-prop pattern |
+| `to` (router) | Goes on the element in `render` | e.g. `render={<RouterLink to="…" />}` |
+| `onClick` | `onClick` | Direct prop on `Button`, unchanged |
+| `variant` (Typography) | _(removed)_ | DS link style is fixed; use `className` for size overrides |
+| `ellipsis` | `className="truncate"` | Tailwind utility; wrap in a sized container |
+| `disabled` | `disabled` | Direct prop, unchanged |
+
+## 6. Before / After examples
+
+### 6a. Plain anchor link
+
+**Before (Tractor):**
+```tsx
+import { Link } from '@aircall/tractor';
+
+<Link href="https://aircall.io/docs">Read the docs</Link>
+```
+
+**After (DS):**
+```tsx
+import { Button } from '@aircall/ds';
+
+<Button variant="link" render={<a href="https://aircall.io/docs" />}>
+  Read the docs
+</Button>
+```
+
+### 6b. External link (new tab)
+
+**Before (Tractor):**
+```tsx
+import { Link } from '@aircall/tractor';
+
+<Link href="https://aircall.io" target="_blank" rel="noreferrer">
+  Open Aircall
+</Link>
+```
+
+**After (DS):**
+```tsx
+import { Button } from '@aircall/ds';
+
+<Button variant="link" render={<a href="https://aircall.io" target="_blank" rel="noreferrer" />}>
+  Open Aircall
+</Button>
+```
+
+### 6c. React Router link
+
+**Before (Tractor):**
+```tsx
+import { Link } from '@aircall/tractor';
+import { Link as RouterLink } from 'react-router-dom';
+
+<Link as={RouterLink} to="/settings">
+  Settings
+</Link>
+```
+
+**After (DS):**
+```tsx
+import { Button } from '@aircall/ds';
+import { Link as RouterLink } from 'react-router-dom';
+
+<Button variant="link" render={<RouterLink to="/settings" />}>
+  Settings
+</Button>
+```
+
+### 6d. Click-only inline action (no navigation)
+
+**Before (Tractor):**
+```tsx
+import { Link } from '@aircall/tractor';
+
+<Link onClick={handleRetry}>Retry</Link>
+```
+
+**After (DS):**
+```tsx
+import { Button } from '@aircall/ds';
+
+<Button variant="link" onClick={handleRetry}>Retry</Button>
+```
+
+> No `render` prop needed here because there is no navigation target — the default `<button>` element is semantically correct for a click action.
+
+### 6e. Link with trailing icon
+
+**Before (Tractor):**
+```tsx
+import { Link } from '@aircall/tractor';
+import { ExternalLink } from '@aircall/react-icons';
+
+<Link href="https://aircall.io/docs" target="_blank" rel="noreferrer">
+  Docs <ExternalLink size={12} />
+</Link>
+```
+
+**After (DS):**
+```tsx
+import { Button } from '@aircall/ds';
+import { ExternalLink } from '@aircall/react-icons';
+
+<Button variant="link" render={<a href="https://aircall.io/docs" target="_blank" rel="noreferrer" />}>
+  Docs <ExternalLink />
+</Button>
+```
+
+> Drop the `size` prop from the icon — DS auto-sizes SVGs via `[&_svg:not([class*='size-'])]:size-4`. Passing a numeric `size` attribute overrides Tailwind and locks the icon to the wrong dimension.
+
+## 7. Common mistakes
+
+### Mistake 1: Importing `Link` from `@aircall/ds`
+
+```tsx
+// WRONG — there is no Link export in @aircall/ds
+import { Link } from '@aircall/ds';
+
+<Link href="/settings">Settings</Link>
+```
+
+```tsx
+// CORRECT — use Button with variant="link"
+import { Button } from '@aircall/ds';
+
+<Button variant="link" render={<a href="/settings" />}>Settings</Button>
+```
+
+`@aircall/ds` exports `PaginationLink` but not a general `Link`. Importing `Link` from `@aircall/ds` produces a module error at runtime and a TypeScript named-export error at compile time. The only valid export for this use case is `Button`.
+
+`Source: packages/ds/src/index.ts` — only `PaginationLink` exists; no standalone `Link`.
+
+---
+
+### Mistake 2: Passing `href` directly to `Button`
+
+```tsx
+// WRONG — Button has no href prop; it is silently forwarded to a <button> element
+// that ignores it, breaking navigation entirely
+import { Button } from '@aircall/ds';
+
+<Button variant="link" href="/settings">Settings</Button>
+```
+
+```tsx
+// CORRECT — href belongs on the rendered anchor element
+import { Button } from '@aircall/ds';
+
+<Button variant="link" render={<a href="/settings" />}>Settings</Button>
+```
+
+`Button` wraps Base UI's `ButtonPrimitive`, which renders a `<button>` by default. A `<button>` element ignores `href`. The `render` prop swaps the root element to an `<a>`, which honours `href` and restores anchor semantics (middle-click, right-click menu, browser history).
+
+`Source: packages/ds/src/components/button.tsx` — `Button` extends `ButtonPrimitive.Props` from `@base-ui/react/button`; no `href` in `ButtonProps`.
+
+---
+
+### Mistake 3: Using `as` instead of `render` for router links
+
+```tsx
+// WRONG — DS Button is built on Base UI, not Radix; it has no `as` prop
+import { Button } from '@aircall/ds';
+import { Link as RouterLink } from 'react-router-dom';
+
+<Button variant="link" as={RouterLink} to="/settings">Settings</Button>
+```
+
+```tsx
+// CORRECT — Base UI uses the render prop; pass router-specific props on the element
+import { Button } from '@aircall/ds';
+import { Link as RouterLink } from 'react-router-dom';
+
+<Button variant="link" render={<RouterLink to="/settings" />}>Settings</Button>
+```
+
+Base UI replaced Radix UI in `@aircall/ds`. The `asChild`/`as` pattern from Radix is gone. The `render` prop accepts a JSX element — all element-specific props (`to`, `href`, `target`) go on that element, not on `Button` directly.
+
+`Source: packages/ds/src/components/button.tsx` — `Button` extends `ButtonPrimitive.Props` from `@base-ui/react/button`, which exposes `render`.
+
+---
+
+### Mistake 4: Omitting `render` for real anchor links
+
+```tsx
+// WRONG — renders a <button> with no href; middle-click and right-click-open broken
+import { Button } from '@aircall/ds';
+
+<Button variant="link">Read the docs</Button>
+```
+
+```tsx
+// CORRECT — supply render to get a real <a> element
+import { Button } from '@aircall/ds';
+
+<Button variant="link" render={<a href="https://aircall.io/docs" />}>
+  Read the docs
+</Button>
+```
+
+Without `render`, `Button` always outputs `<button>`. A `<button>` cannot be middle-clicked to open in a new tab, does not appear in browser link lists, and has no implicit `link` ARIA role. For any navigational use, `render={<a href="…" />}` is required to preserve anchor semantics.
+
+`Source: packages/ds/src/components/button.tsx` — default element is `<button>` via `ButtonPrimitive`.