@aircall/ds 0.13.0 → 0.15.0

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

@@ -0,0 +1,214 @@
+---
+name: aircall-ds/migrate-tractor/popover
+description: >
+  Migrate Tractor Popover (single-component, content + placement props) to the
+  @aircall/ds Popover compound (Popover, PopoverTrigger, PopoverContent, PopoverHeader,
+  PopoverTitle, PopoverDescription). Load when a file imports Popover 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/popover.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 popover-specific steps below.
+
+## 1. Component mapping
+
+Tractor `Popover` was a single component: you passed a `content` prop (the panel) and a `placement` prop (positioning) alongside the trigger child. DS uses a Base UI compound where each concern is a named part.
+
+| Tractor | @aircall/ds | Role |
+| --- | --- | --- |
+| `<Popover>` | `<Popover>` | State owner (open, onOpenChange) |
+| _(trigger child of `<Popover>`)_ | `<PopoverTrigger>` | The anchor element that opens the panel |
+| `content={…}` prop | `<PopoverContent>` | The floating panel; children replace the prop |
+| `placement="bottom-start"` | `side="bottom" align="start"` on `<PopoverContent>` | Split into two props |
+| _(no equivalent)_ | `<PopoverHeader>` | Optional structured header wrapper |
+| _(no equivalent)_ | `<PopoverTitle>` | Accessible title inside the panel |
+| _(no equivalent)_ | `<PopoverDescription>` | Accessible description inside the panel |
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Popover, PopoverContent, PopoverDescription,
+PopoverHeader, PopoverTitle, PopoverTrigger
+```
+
+## 3. Imports
+
+```tsx
+import {
+  Popover,
+  PopoverContent,
+  PopoverDescription,
+  PopoverHeader,
+  PopoverTitle,
+  PopoverTrigger,
+  Button,
+} from '@aircall/ds';
+```
+
+## 4. Before / After
+
+### Uncontrolled (most common)
+
+```tsx
+// Before
+import { Popover, Button } from '@aircall/tractor';
+
+<Popover
+  placement="bottom-start"
+  content={
+    <div>
+      <strong>Title</strong>
+      <p>A short description.</p>
+      <p>Body content.</p>
+    </div>
+  }
+>
+  <Button variant="secondary" mode="outline">Open</Button>
+</Popover>
+
+// After
+import { Popover, PopoverContent, PopoverHeader, PopoverTitle, PopoverDescription, PopoverTrigger, Button } from '@aircall/ds';
+
+<Popover>
+  <PopoverTrigger render={<Button variant="outline" />}>Open</PopoverTrigger>
+  <PopoverContent side="bottom" align="start">
+    <PopoverHeader>
+      <PopoverTitle>Title</PopoverTitle>
+      <PopoverDescription>A short description.</PopoverDescription>
+    </PopoverHeader>
+    <p>Body content.</p>
+  </PopoverContent>
+</Popover>
+```
+
+### Controlled (replaces `isOpen` / `onClose`)
+
+```tsx
+// Before
+import { Popover, Button } from '@aircall/tractor';
+
+<Popover
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  placement="top"
+  content={<p>Settings panel</p>}
+>
+  <Button variant="primary">Settings</Button>
+</Popover>
+
+// After
+import { Popover, PopoverContent, PopoverTrigger, Button } from '@aircall/ds';
+
+<Popover open={isOpen} onOpenChange={setIsOpen}>
+  <PopoverTrigger render={<Button variant="default" />}>Settings</PopoverTrigger>
+  <PopoverContent side="top">
+    <p>Settings panel</p>
+  </PopoverContent>
+</Popover>
+```
+
+Key changes:
+- `isOpen` → `open`; `onClose` → `onOpenChange` (receives the new boolean)
+- `content={…}` prop is removed — panel content is children of `PopoverContent`
+- Tractor's trigger child becomes `<PopoverTrigger render={<Button />}>` — label goes on `PopoverTrigger`, not inside the `render` element
+- `placement="bottom-start"` splits into `side="bottom" align="start"` on `PopoverContent`
+
+## 5. Positioning
+
+Tractor's single `placement` string maps to two props on `PopoverContent`:
+
+| Tractor `placement` | DS `side` | DS `align` |
+| --- | --- | --- |
+| `"bottom"` | `"bottom"` | `"center"` (default) |
+| `"bottom-start"` | `"bottom"` | `"start"` |
+| `"bottom-end"` | `"bottom"` | `"end"` |
+| `"top"` | `"top"` | `"center"` (default) |
+| `"top-start"` | `"top"` | `"start"` |
+| `"top-end"` | `"top"` | `"end"` |
+| `"left"` | `"left"` | `"center"` (default) |
+| `"right"` | `"right"` | `"center"` (default) |
+
+Defaults when omitted: `side="bottom"`, `align="center"`, `sideOffset={4}`. Fine-tune gap with `sideOffset` / `alignOffset`.
+
+## 6. Panel surface
+
+`PopoverContent` ships its own surface styles — `rounded-md`, `ring-1`, `bg-popover`, `p-4`, `shadow-md`. Do not re-add a wrapper `<div>` with manual padding, background, or border inside `PopoverContent`; it will double the spacing and styling.
+
+---
+
+## 7. Common mistakes
+
+### Mistake 1 — Keeping `content` as a prop instead of children
+
+```tsx
+// Wrong — content prop does not exist on DS Popover
+<Popover content={<p>Body content.</p>}>
+  <PopoverTrigger render={<Button variant="outline" />}>Open</PopoverTrigger>
+</Popover>
+
+// Correct — panel content is children of PopoverContent
+<Popover>
+  <PopoverTrigger render={<Button variant="outline" />}>Open</PopoverTrigger>
+  <PopoverContent>
+    <p>Body content.</p>
+  </PopoverContent>
+</Popover>
+```
+
+The DS compound has no `content` prop on `Popover`. Passing it silently does nothing — the popover renders with an empty panel. Move the JSX into children of `PopoverContent`.
+
+Source: `packages/ds/src/components/popover.tsx`
+
+---
+
+### Mistake 2 — Putting the label inside the `render` Button instead of `PopoverTrigger`
+
+```tsx
+// Wrong — label ends up inside Button's children prop, not managed by PopoverTrigger
+<PopoverTrigger render={<Button variant="outline">Open</Button>} />
+
+// Correct — label is a child of PopoverTrigger; it is merged into the rendered Button
+<PopoverTrigger render={<Button variant="outline" />}>Open</PopoverTrigger>
+```
+
+`PopoverTrigger` uses the Base UI `render` prop pattern: it clones the element passed as `render` and merges its own open/close handler. The visible label must be the child of `PopoverTrigger`, not of the inner Button — otherwise it is ignored and the button renders empty.
+
+Source: `packages/ds/src/components/popover.tsx`
+
+---
+
+### Mistake 3 — Passing a single `placement` string instead of `side` + `align`
+
+```tsx
+// Wrong — placement is a Tractor prop; DS PopoverContent does not accept it
+<PopoverContent placement="bottom-start">…</PopoverContent>
+
+// Correct — split into side and align
+<PopoverContent side="bottom" align="start">…</PopoverContent>
+```
+
+The DS `PopoverContent` accepts `side` and `align` as separate props (sourced from `PopoverPrimitive.Positioner`). A `placement` string is silently ignored, and the panel falls back to the default `side="bottom" align="center"` — which may look correct until the layout shifts.
+
+Source: `packages/ds/src/components/popover.tsx`
+
+---
+
+### Mistake 4 — Using `isOpen` / `onClose` instead of `open` / `onOpenChange`
+
+```tsx
+// Wrong — isOpen and onClose are Tractor props; DS Popover ignores them
+<Popover isOpen={isOpen} onClose={() => setIsOpen(false)}>…</Popover>
+
+// Correct — controlled via open and onOpenChange
+<Popover open={isOpen} onOpenChange={setIsOpen}>…</Popover>
+```
+
+DS `Popover` follows the Base UI controlled pattern: `open` (boolean) and `onOpenChange` (callback receiving the new boolean). `onClose` is not called — the popover stays open permanently when `onClose` is the only handler provided.
+
+Source: `packages/ds/src/components/popover.tsx`

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

@@ -0,0 +1,245 @@
+---
+name: aircall-ds/migrate-tractor/select
+description: >
+  Migrate Tractor Select to the @aircall/ds Select compound. Load when a file
+  imports Select from @aircall/tractor. Covers the compound parts, the nullable
+  onValueChange, and the Group-wraps-Label rule.
+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/select.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 select-specific steps below.
+
+## 1. Component mapping
+
+Tractor `Select` was a flat component with `SelectOption` children. DS uses a compound structure where each visual slot is a named part:
+
+| Tractor | DS compound part | Role |
+| --- | --- | --- |
+| `<Select>` | `<Select>` | State owner (value, open, disabled) |
+| _(no equivalent)_ | `<SelectTrigger>` | Visible field / button |
+| _(no equivalent)_ | `<SelectValue>` | Renders current label or placeholder |
+| _(no equivalent)_ | `<SelectContent>` | Dropdown container |
+| `<SelectOption>` | `<SelectItem>` | Individual option |
+| _(no equivalent)_ | `<SelectGroup>` | Required wrapper around a labelled section |
+| _(no equivalent)_ | `<SelectLabel>` | Section heading inside a `SelectGroup` |
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Select, SelectContent, SelectGroup, SelectItem,
+SelectLabel, SelectTrigger, SelectValue,
+SelectScrollDownButton, SelectScrollUpButton, SelectSeparator,
+selectTriggerVariants
+```
+
+All names listed in the Before/After section below exist in the published public API.
+
+## 3. Imports
+
+```tsx
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectTrigger,
+  SelectValue,
+} from '@aircall/ds';
+```
+
+## 4. Prop renames
+
+| Tractor prop | DS prop | Notes |
+| --- | --- | --- |
+| `onChange` | `onValueChange` | Signature change — see Mistake 1 below |
+| `placeholder` on `<Select>` | `placeholder` on `<SelectValue>` | Moved to the value part |
+| `selectedOption` / `value` | `value` | Unchanged name, same position |
+
+## 5. Before / After
+
+### Before (Tractor)
+
+```tsx
+import { Select, SelectOption } from '@aircall/tractor';
+
+<Select
+  value={channelType}
+  onChange={(value) => setChannelType(value)}
+  placeholder="Pick a channel"
+>
+  <SelectOption value="phone">Phone</SelectOption>
+  <SelectOption value="email">Email</SelectOption>
+  <SelectOption value="sms">SMS</SelectOption>
+</Select>
+```
+
+### After (DS)
+
+```tsx
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@aircall/ds';
+
+<Select
+  value={channelType}
+  onValueChange={(value: string | null) => {
+    if (value !== null) setChannelType(value);
+  }}
+>
+  <SelectTrigger>
+    <SelectValue placeholder="Pick a channel" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="phone">Phone</SelectItem>
+    <SelectItem value="email">Email</SelectItem>
+    <SelectItem value="sms">SMS</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+## 6. With sections (Labels)
+
+When grouping options under a label, `SelectLabel` **must** be inside a `SelectGroup` along with its items. Direct children of `SelectContent` are not accessibility-correct in Base UI.
+
+```tsx
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectTrigger,
+  SelectValue,
+} from '@aircall/ds';
+
+<Select value={value} onValueChange={setValue}>
+  <SelectTrigger>
+    <SelectValue placeholder="Pick a channel" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectLabel>Voice</SelectLabel>
+      <SelectItem value="phone">Phone</SelectItem>
+      <SelectItem value="sms">SMS</SelectItem>
+    </SelectGroup>
+    <SelectGroup>
+      <SelectLabel>Written</SelectLabel>
+      <SelectItem value="email">Email</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>
+```
+
+## 7. Size
+
+`SelectTrigger` accepts a `size` prop:
+
+| Value | Height | Use for |
+| --- | --- | --- |
+| `"default"` | 40px | Any Tractor `regular` or `small` size |
+| `"sm"` | 32px | Compact layouts |
+
+## 8. When to use Combobox instead
+
+If users need to **search or filter** the options list, use `Combobox` rather than `Select`. Plain `Select` is for short, fixed-enum lists where no search is needed.
+
+## 9. Common Mistakes
+
+### Mistake 1 — Not widening the `onValueChange` handler for `null`
+
+```tsx
+// Wrong
+<Select onValueChange={(value: string) => setChannelType(value)}>
+  ...
+</Select>
+
+// Correct
+<Select
+  onValueChange={(value: string | null) => {
+    if (value !== null) setChannelType(value);
+  }}
+>
+  ...
+</Select>
+```
+
+The DS `onValueChange` callback receives `string | null` — `null` is emitted when the selection is cleared. Typing the parameter as `string` causes a TypeScript error; omitting the null guard causes a runtime `null` to propagate into state that expects a string.
+Source: `packages/ds/src/components/select.tsx`
+
+---
+
+### Mistake 2 — Placing `SelectLabel` as a direct child of `SelectContent`
+
+```tsx
+// Wrong
+<SelectContent>
+  <SelectLabel>Voice</SelectLabel>      {/* label outside a SelectGroup */}
+  <SelectItem value="phone">Phone</SelectItem>
+</SelectContent>
+
+// Correct
+<SelectContent>
+  <SelectGroup>
+    <SelectLabel>Voice</SelectLabel>    {/* label always inside a SelectGroup */}
+    <SelectItem value="phone">Phone</SelectItem>
+  </SelectGroup>
+</SelectContent>
+```
+
+In Base UI, `SelectLabel` must be a sibling of its items inside a `SelectGroup`. A bare `SelectLabel` in `SelectContent` is not accessibility-correct — the group association that screen readers rely on is missing, and the label may render incorrectly.
+Source: `packages/ds/src/components/select.tsx`
+
+---
+
+### Mistake 3 — Keeping `placeholder` on `<Select>` instead of `<SelectValue>`
+
+```tsx
+// Wrong
+<Select placeholder="Pick a channel">
+  <SelectTrigger>
+    <SelectValue />
+  </SelectTrigger>
+  ...
+</Select>
+
+// Correct
+<Select>
+  <SelectTrigger>
+    <SelectValue placeholder="Pick a channel" />
+  </SelectTrigger>
+  ...
+</Select>
+```
+
+Tractor accepted `placeholder` on the root `<Select>`. In the DS compound, the `placeholder` prop lives on `<SelectValue>` — it is silently ignored when placed on `<Select>`, so no placeholder text appears in the trigger.
+Source: `packages/ds/src/components/select.tsx`
+
+---
+
+### Mistake 4 — Using `SelectOption` instead of `SelectItem`
+
+```tsx
+// Wrong
+import { Select, SelectOption } from '@aircall/tractor';
+// SelectOption does not exist in @aircall/ds
+
+// Correct
+import { Select, SelectItem } from '@aircall/ds';
+
+<SelectItem value="phone">Phone</SelectItem>
+```
+
+Tractor used `SelectOption` for each choice. The DS compound uses `SelectItem`. `SelectOption` is not exported from `@aircall/ds` — importing it will cause a build error.
+Source: `packages/ds/src/components/select.tsx`