@aircall/ds 0.14.0 → 0.15.0

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

@@ -0,0 +1,278 @@
+---
+name: aircall-ds/migrate-tractor/card
+description: >
+  Migrate bespoke hand-rolled card components (plain div/Box with border/shadow/
+  padding) to the @aircall/ds Card compound (Card, CardHeader, CardTitle,
+  CardDescription, CardAction, CardContent, CardFooter). Load when a file
+  contains an in-app card implementation or imports card-like primitives 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/card.md"
+---
+
+This skill builds on aircall-ds/migrate-tractor.
+
+## 1. Component mapping
+
+Tractor had no `Card` component. Apps grew bespoke card implementations — `<div>` or Tractor `<Box>` elements with hand-rolled borders, shadows, padding, and per-use-case variations. DS `Card` is the single component to unify all of them.
+
+| App pattern (Tractor-era) | @aircall/ds |
+| --- | --- |
+| Root `<div>` / `<Box>` with border, shadow, radius, bg, padding | `Card` |
+| Title element inside the card header region | `CardTitle` (inside `CardHeader`) |
+| Subtitle / description element | `CardDescription` (inside `CardHeader`) |
+| Header region (`<div>` wrapping title + subtitle) | `CardHeader` |
+| Top-right control (icon button, menu trigger) | `CardAction` (inside `CardHeader`) |
+| Body / content region | `CardContent` |
+| Footer / actions region | `CardFooter` |
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle
+```
+
+## 3. Imports
+
+```tsx
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+  Button
+} from '@aircall/ds';
+import { MoreVertical } from '@aircall/react-icons';
+```
+
+Never import icons from `lucide-react` directly — always use `@aircall/react-icons`.
+
+## 4. Size prop
+
+`Card` accepts a `size` prop (`"default" | "sm"`). Setting it on the root propagates via `data-size` + Tailwind group selectors to **all** sub-components — padding, gap, and title font size all scale together. Never add per-part `p-*` overrides to achieve a compact variant; use `size="sm"` instead.
+
+| DS `size` | Padding | Gap | Title size |
+| --- | --- | --- | --- |
+| `"default"` (omit prop) | `py-4` / `px-4` | `gap-4` | `text-base` |
+| `"sm"` | `py-3` / `px-3` | `gap-3` | `text-sm` |
+
+## 5. Before / After
+
+### 5a. Basic card — replacing a bespoke surface
+
+**Before (Tractor-era bespoke component):**
+```tsx
+import { Box, Typography } from '@aircall/tractor';
+
+<Box
+  className="rounded-xl border border-neutral-200 bg-white p-4 shadow-sm"
+  display="flex"
+  flexDirection="column"
+  gap="space-16"
+>
+  <Box display="flex" flexDirection="column" gap="space-4">
+    <Typography variant="headingSmall">Card title</Typography>
+    <Typography variant="bodySmall" color="neutral.600">
+      A short supporting description.
+    </Typography>
+  </Box>
+  <Box>
+    <p>Card body content goes here.</p>
+  </Box>
+  <Box display="flex" justifyContent="flex-end">
+    <Button variant="primary" size="small">Action</Button>
+  </Box>
+</Box>
+```
+
+**After (DS):**
+```tsx
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Button } from '@aircall/ds';
+
+<Card className="w-[350px]">
+  <CardHeader>
+    <CardTitle>Card title</CardTitle>
+    <CardDescription>A short supporting description.</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p className="text-sm">Card body content goes here.</p>
+  </CardContent>
+  <CardFooter>
+    <Button variant="default" size="lg">Action</Button>
+  </CardFooter>
+</Card>
+```
+
+Key changes:
+- Delete all hand-rolled surface styles (border, shadow, radius, bg, padding) — `Card` owns all of it.
+- Map title/subtitle to `CardTitle` + `CardDescription` inside `CardHeader`.
+- Map body to `CardContent`; actions to `CardFooter`.
+- `CardFooter` renders with `border-t bg-muted/50` by default (distinct action bar). For a plain footer add `className="bg-transparent border-none"`.
+
+### 5b. Compact card using `size="sm"`
+
+**Before:**
+```tsx
+import { Box, Typography } from '@aircall/tractor';
+
+<Box className="rounded-xl border border-neutral-200 bg-white p-3 shadow-sm flex flex-col gap-3">
+  <Typography variant="headingXSmall">Compact card</Typography>
+  <p className="text-xs">Body content.</p>
+</Box>
+```
+
+**After:**
+```tsx
+import { Card, CardContent, CardHeader, CardTitle } from '@aircall/ds';
+
+<Card size="sm">
+  <CardHeader>
+    <CardTitle>Compact card</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <p className="text-sm">Body content.</p>
+  </CardContent>
+</Card>
+```
+
+Setting `size="sm"` on `Card` scales all sub-components — no per-part padding overrides needed.
+
+### 5c. Card with a header action
+
+**Before:**
+```tsx
+import { Box, Typography } from '@aircall/tractor';
+import { IconButton } from '@aircall/tractor';
+import { MoreVertical } from '@aircall/react-icons';
+
+<Box className="rounded-xl border bg-white p-4 relative">
+  <Box display="flex" justifyContent="space-between" alignItems="flex-start">
+    <Typography variant="headingSmall">With action</Typography>
+    <IconButton component={MoreVertical} aria-label="Open menu" />
+  </Box>
+</Box>
+```
+
+**After:**
+```tsx
+import { Card, CardAction, CardHeader, CardTitle, Button } from '@aircall/ds';
+import { MoreVertical } from '@aircall/react-icons';
+
+<Card>
+  <CardHeader>
+    <CardTitle>With action</CardTitle>
+    <CardAction>
+      <Button variant="ghost" size="icon" aria-label="Open menu">
+        <MoreVertical />
+      </Button>
+    </CardAction>
+  </CardHeader>
+</Card>
+```
+
+`CardAction` must live **inside** `CardHeader` — the header is a CSS grid that auto-places it in the top-right (`col-start-2 row-span-2`). Rendered elsewhere it loses positioning entirely.
+
+---
+
+## 6. Common mistakes
+
+### Mistake 1 — Keeping hand-rolled surface styles on the root element
+
+```tsx
+// ❌ Wrong — double-styles the surface; shadow and border clash with Card's ring
+<Card className="border border-neutral-200 rounded-xl shadow-sm bg-white p-4">
+  <CardContent>Content</CardContent>
+</Card>
+
+// ✅ Correct — Card owns border, radius, bg, and padding; only true one-offs belong in className
+<Card className="w-[350px]">
+  <CardContent>Content</CardContent>
+</Card>
+```
+
+`Card` already applies `rounded-xl border bg-card py-4` (plus ring, text color, and overflow). Adding these again creates double borders and mismatched shadows that diverge from the design token.
+
+Source: `packages/ds/src/components/card.tsx`
+
+### Mistake 2 — Placing `CardAction` outside `CardHeader`
+
+```tsx
+// ❌ Wrong — CardAction is not positioned; it renders inline with body content
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+  </CardHeader>
+  <CardAction>
+    <Button variant="ghost" size="icon" aria-label="Menu"><MoreVertical /></Button>
+  </CardAction>
+  <CardContent>Body</CardContent>
+</Card>
+
+// ✅ Correct — CardAction inside CardHeader uses the header grid to pin top-right
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+    <CardAction>
+      <Button variant="ghost" size="icon" aria-label="Menu"><MoreVertical /></Button>
+    </CardAction>
+  </CardHeader>
+  <CardContent>Body</CardContent>
+</Card>
+```
+
+`CardHeader` uses `grid auto-rows-min has-data-[slot=card-action]:grid-cols-[1fr_auto]`. `CardAction` carries `data-slot="card-action"` and is placed via `col-start-2 row-span-2`. Outside `CardHeader`, no grid parent exists and the action renders in normal flow.
+
+Source: `packages/ds/src/components/card.tsx`
+
+### Mistake 3 — Using per-part padding overrides instead of `size="sm"`
+
+```tsx
+// ❌ Wrong — overriding padding per part breaks the sizing contract and diverges from tokens
+<Card>
+  <CardHeader className="px-3 py-2">
+    <CardTitle className="text-sm">Compact</CardTitle>
+  </CardHeader>
+  <CardContent className="px-3">Body</CardContent>
+</Card>
+
+// ✅ Correct — size="sm" on the root scales all sub-components consistently
+<Card size="sm">
+  <CardHeader>
+    <CardTitle>Compact</CardTitle>
+  </CardHeader>
+  <CardContent>Body</CardContent>
+</Card>
+```
+
+`Card` propagates `data-size="sm"` to sub-components via the `group/card` modifier. Each part responds with `group-data-[size=sm]/card:px-3`, `group-data-[size=sm]/card:py-3`, and `group-data-[size=sm]/card:text-sm`. Overriding padding individually bypasses this mechanism and produces inconsistent spacing.
+
+Source: `packages/ds/src/components/card.tsx`
+
+### Mistake 4 — Adding bottom padding to `Card` when a footer is present
+
+```tsx
+// ❌ Wrong — adds visible gap between footer and card bottom edge
+<Card className="pb-4">
+  <CardContent>Body</CardContent>
+  <CardFooter>Actions</CardFooter>
+</Card>
+
+// ✅ Correct — Card auto-removes bottom padding when CardFooter is present
+<Card>
+  <CardContent>Body</CardContent>
+  <CardFooter>Actions</CardFooter>
+</Card>
+```
+
+`Card` uses `has-data-[slot=card-footer]:pb-0` to remove its own bottom padding when a `CardFooter` is present, so the footer's rounded corners (`rounded-b-xl`) flush with the card edge. Forcing `pb-4` overrides this and leaves a visible gap.
+
+Source: `packages/ds/src/components/card.tsx`

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

@@ -0,0 +1,346 @@
+---
+name: aircall-ds/migrate-tractor/combobox
+description: >
+  Migrate Tractor ComboBox (and the old Command + Popover search pattern) to the
+  @aircall/ds Combobox compound. Load when a file imports ComboBox, Command, or a
+  Command+Popover search combo 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/combobox.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 combobox-specific steps below.
+
+## 1. When to use Combobox vs Select
+
+Use `Combobox` when the user needs to **search or filter** options. For a short, fixed-enum list with no search, use `Select` instead (`aircall-ds/migrate-tractor/select`).
+
+## 2. Component mapping
+
+Tractor `ComboBox` was a single self-contained component. DS uses a compound structure where every visual slot is a named part. The old "Command + Popover" search recipe is fully replaced by this same compound.
+
+| Tractor / old pattern | DS compound part | Role |
+| --- | --- | --- |
+| `<ComboBox>` | `<Combobox>` | State owner (`value`, `onValueChange`, `multiple`) |
+| _(input built-in)_ | `<ComboboxInput>` | Visible text field (includes trigger chevron via `showTrigger`) |
+| _(trigger built-in)_ | `<ComboboxTrigger>` | Standalone chevron button (used inside custom layouts) |
+| _(no equivalent)_ | `<ComboboxContent>` | Popover container — handles portal + positioning |
+| _(no equivalent)_ | `<ComboboxList>` | Scrollable list inside the popover |
+| `<ComboBoxOption>` / `<CommandItem>` | `<ComboboxItem>` | Individual option |
+| _(no equivalent)_ | `<ComboboxEmpty>` | Shown automatically when the filtered list is empty |
+| _(no equivalent)_ | `<ComboboxGroup>` | Logical section wrapper |
+| _(no equivalent)_ | `<ComboboxLabel>` | Section heading (must be inside a `ComboboxGroup`) |
+| _(no equivalent)_ | `<ComboboxChips>` | Multi-select chip container (replaces custom tag inputs) |
+| _(no equivalent)_ | `<ComboboxChip>` | Individual removable chip inside `ComboboxChips` |
+| _(no equivalent)_ | `<ComboboxChipsInput>` | Inline input rendered inside `ComboboxChips` |
+| _(no equivalent)_ | `useComboboxAnchor()` | Returns a ref used to anchor `ComboboxContent` to a chips container |
+
+## 3. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Combobox, ComboboxChip, ComboboxChips, ComboboxChipsInput,
+ComboboxCollection, ComboboxContent, ComboboxEmpty, ComboboxGroup,
+ComboboxInput, ComboboxItem, ComboboxLabel, ComboboxList,
+ComboboxSeparator, ComboboxTrigger, ComboboxValue,
+useComboboxAnchor
+```
+
+All names used in the Before/After examples below exist in the published public API.
+
+## 4. Key prop differences
+
+| Tractor / old pattern | DS equivalent | Notes |
+| --- | --- | --- |
+| `onChange` | `onValueChange` | Signature: `(value: string \| null) => void` (single); `(value: string[]) => void` (multiple) |
+| `options={[…]}` | `<ComboboxItem>` children | Items are rendered declaratively, not via a data prop |
+| `multi` / `isMulti` | `multiple` on `<Combobox>` | Boolean flag; `value` and `onValueChange` then use `string[]` |
+| _(manual filter logic)_ | Built-in filtering | DS filters items automatically against typed input; opt out for async search by controlling `value` + `onChange` on `ComboboxInput` |
+| `showClear` _(absent)_ | `showClear` on `<ComboboxInput>` | Renders an X button that calls `ComboboxPrimitive.Clear` |
+
+## 5. Before / After
+
+### 5a. Single-select
+
+#### Before (Tractor)
+
+```tsx
+import { ComboBox, ComboBoxOption } from '@aircall/tractor';
+
+<ComboBox
+  value={country}
+  onChange={setCountry}
+  placeholder="Search countries"
+>
+  {countries.map(c => (
+    <ComboBoxOption key={c.iso} value={c.iso}>
+      {c.name}
+    </ComboBoxOption>
+  ))}
+</ComboBox>
+```
+
+#### After (DS)
+
+```tsx
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxGroup,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxLabel,
+  ComboboxList,
+} from '@aircall/ds';
+
+<Combobox value={country} onValueChange={setCountry}>
+  <ComboboxInput placeholder="Search countries" showTrigger />
+  <ComboboxContent>
+    <ComboboxList>
+      <ComboboxEmpty>No results.</ComboboxEmpty>
+      <ComboboxGroup>
+        <ComboboxLabel>Suggestions</ComboboxLabel>
+        {countries.map(c => (
+          <ComboboxItem key={c.iso} value={c.iso}>
+            {c.name}
+          </ComboboxItem>
+        ))}
+      </ComboboxGroup>
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+```
+
+### 5b. Multi-select with chips
+
+#### Before (Tractor — custom tag input pattern)
+
+```tsx
+import { ComboBox } from '@aircall/tractor';
+
+<ComboBox
+  multi
+  value={selected}
+  onChange={setSelected}
+  placeholder="Add a tag"
+  options={items}
+/>
+```
+
+#### After (DS)
+
+```tsx
+import {
+  Combobox,
+  ComboboxChip,
+  ComboboxChips,
+  ComboboxChipsInput,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxItem,
+  ComboboxList,
+  useComboboxAnchor,
+} from '@aircall/ds';
+
+function TagPicker() {
+  const [selected, setSelected] = React.useState<string[]>([]);
+  const anchorRef = useComboboxAnchor();
+
+  return (
+    <Combobox multiple value={selected} onValueChange={setSelected}>
+      <ComboboxChips ref={anchorRef}>
+        {selected.map(val => (
+          <ComboboxChip key={val} value={val}>
+            {items.find(i => i.value === val)?.label}
+          </ComboboxChip>
+        ))}
+        <ComboboxChipsInput placeholder="Add a tag" />
+      </ComboboxChips>
+      <ComboboxContent anchor={anchorRef}>
+        <ComboboxList>
+          <ComboboxEmpty>No results.</ComboboxEmpty>
+          {items.map(item => (
+            <ComboboxItem key={item.value} value={item.value}>
+              {item.label}
+            </ComboboxItem>
+          ))}
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>
+  );
+}
+```
+
+### 5c. Async / server-driven options
+
+Control the input value yourself and disable the built-in filter by rendering only the results you fetch.
+
+```tsx
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxList,
+} from '@aircall/ds';
+
+function ContactPicker({ onPick }: { onPick: (id: string) => void }) {
+  const [query, setQuery] = React.useState('');
+  const { data: results, loading } = useSearch(query);
+
+  return (
+    <Combobox onValueChange={onPick}>
+      <ComboboxInput
+        placeholder="Search contacts"
+        value={query}
+        onChange={e => setQuery(e.target.value)}
+      />
+      <ComboboxContent>
+        <ComboboxList>
+          {loading && <ComboboxEmpty>Searching…</ComboboxEmpty>}
+          {!loading && results.length === 0 && (
+            <ComboboxEmpty>No matches.</ComboboxEmpty>
+          )}
+          {results.map(r => (
+            <ComboboxItem key={r.id} value={r.id}>
+              {r.name}
+            </ComboboxItem>
+          ))}
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>
+  );
+}
+```
+
+## 6. Common Mistakes
+
+### Mistake 1 — Omitting `ComboboxList` and placing items directly in `ComboboxContent`
+
+```tsx
+// Wrong
+<ComboboxContent>
+  <ComboboxEmpty>No results.</ComboboxEmpty>
+  <ComboboxItem value="a">Alpha</ComboboxItem>
+</ComboboxContent>
+
+// Correct
+<ComboboxContent>
+  <ComboboxList>
+    <ComboboxEmpty>No results.</ComboboxEmpty>
+    <ComboboxItem value="a">Alpha</ComboboxItem>
+  </ComboboxList>
+</ComboboxContent>
+```
+
+`ComboboxContent` is the popover shell (portal + positioner + popup). The scrollable, filterable list — including `ComboboxEmpty` visibility logic — lives in `ComboboxList`. Placing items directly in `ComboboxContent` bypasses the scroll container and breaks the empty-state `group-data-empty` CSS selector that shows `ComboboxEmpty`.
+Source: `packages/ds/src/components/combobox.tsx`
+
+---
+
+### Mistake 2 — Forgetting `useComboboxAnchor` / not passing `anchor` for multi-select chips
+
+```tsx
+// Wrong — popover anchors to the document body, not the chips container
+<Combobox multiple value={selected} onValueChange={setSelected}>
+  <ComboboxChips>
+    {selected.map(val => <ComboboxChip key={val} value={val}>{val}</ComboboxChip>)}
+    <ComboboxChipsInput placeholder="Add a tag" />
+  </ComboboxChips>
+  <ComboboxContent>
+    <ComboboxList>
+      {items.map(i => <ComboboxItem key={i.value} value={i.value}>{i.label}</ComboboxItem>)}
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+
+// Correct
+const anchorRef = useComboboxAnchor();
+
+<Combobox multiple value={selected} onValueChange={setSelected}>
+  <ComboboxChips ref={anchorRef}>
+    {selected.map(val => <ComboboxChip key={val} value={val}>{val}</ComboboxChip>)}
+    <ComboboxChipsInput placeholder="Add a tag" />
+  </ComboboxChips>
+  <ComboboxContent anchor={anchorRef}>
+    <ComboboxList>
+      {items.map(i => <ComboboxItem key={i.value} value={i.value}>{i.label}</ComboboxItem>)}
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+```
+
+Without `anchor={anchorRef}`, `ComboboxContent` uses the default Combobox root as its positional reference, so the dropdown opens at the wrong position (above or misaligned with the chip container). `useComboboxAnchor()` returns a stable `ref` that must be attached to `ComboboxChips` and forwarded to `ComboboxContent`.
+Source: `packages/ds/src/components/combobox.tsx`
+
+---
+
+### Mistake 3 — Using a manual filter loop instead of the built-in filtering for static lists
+
+```tsx
+// Wrong — manual filter duplicates work the DS already does
+const [query, setQuery] = React.useState('');
+const visible = countries.filter(c =>
+  c.name.toLowerCase().includes(query.toLowerCase())
+);
+
+<Combobox value={country} onValueChange={setCountry}>
+  <ComboboxInput
+    placeholder="Search countries"
+    value={query}
+    onChange={e => setQuery(e.target.value)}
+  />
+  <ComboboxContent>
+    <ComboboxList>
+      {visible.map(c => (
+        <ComboboxItem key={c.iso} value={c.iso}>{c.name}</ComboboxItem>
+      ))}
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+
+// Correct — render all items; DS filters automatically
+<Combobox value={country} onValueChange={setCountry}>
+  <ComboboxInput placeholder="Search countries" showTrigger />
+  <ComboboxContent>
+    <ComboboxList>
+      <ComboboxEmpty>No results.</ComboboxEmpty>
+      {countries.map(c => (
+        <ComboboxItem key={c.iso} value={c.iso}>{c.name}</ComboboxItem>
+      ))}
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+```
+
+For static option lists, the DS Combobox (via Base UI) filters rendered items automatically against what the user types — no state or `filter` callback needed. Manual filtering is only required for async/server-driven lists where you control the results yourself.
+Source: `packages/ds/src/components/combobox.tsx`
+
+---
+
+### Mistake 4 — Placing `ComboboxLabel` directly in `ComboboxList` without a `ComboboxGroup`
+
+```tsx
+// Wrong
+<ComboboxList>
+  <ComboboxLabel>Suggestions</ComboboxLabel>
+  <ComboboxItem value="a">Alpha</ComboboxItem>
+</ComboboxList>
+
+// Correct
+<ComboboxList>
+  <ComboboxGroup>
+    <ComboboxLabel>Suggestions</ComboboxLabel>
+    <ComboboxItem value="a">Alpha</ComboboxItem>
+  </ComboboxGroup>
+</ComboboxList>
+```
+
+`ComboboxLabel` maps to Base UI's `ComboboxPrimitive.GroupLabel` — it is semantically scoped to a `ComboboxGroup`. Rendering it outside a group breaks the ARIA `group` association that screen readers rely on to announce the section heading.
+Source: `packages/ds/src/components/combobox.tsx`