@aircall/ds 0.14.0 → 0.15.0

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

@@ -0,0 +1,226 @@
+---
+name: aircall-ds/migrate-tractor/divider
+description: >
+  Migrate Tractor Divider to the @aircall/ds Separator. Load when a file imports
+  Divider from @aircall/tractor. Maps orientation (vertical|horizontal), drops the
+  size and bg props, and replaces Box-level color overrides with Tailwind className.
+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/separator.tsx"
+---
+
+This skill builds on aircall-ds/migrate-tractor.
+
+## 1. Component mapping
+
+| Tractor part | @aircall/ds part | Notes |
+| --- | --- | --- |
+| `<Divider>` | `<Separator>` | Name change; orientation prop is preserved |
+| `size` prop | _(removed)_ | DS Separator is always 1 px; no thickness control |
+| `bg` prop | `className` | Pass a Tailwind background utility to override the border color |
+| Extends `BoxProps` | Extends `SeparatorPrimitive.Props` | DS root is a Base UI element, not a styled Box |
+
+## 2. Verified DS export (`packages/ds/src/index.ts`)
+
+```
+Separator
+```
+
+## 3. Imports
+
+**Before (Tractor):**
+```tsx
+import { Divider } from '@aircall/tractor';
+```
+
+**After (DS):**
+```tsx
+import { Separator } from '@aircall/ds';
+```
+
+## 4. Prop changes
+
+| Tractor prop | DS prop | Action |
+| --- | --- | --- |
+| `orientation?: 'vertical' \| 'horizontal'` | `orientation?: 'vertical' \| 'horizontal'` | Same values — pass through as-is |
+| `size?: 'xSmall' \| 'small'` | _(removed)_ | Delete the prop; DS Separator is always 1 px thick |
+| `bg?: string` | `className` | Replace with a Tailwind `bg-*` utility on `className` |
+
+The DS `Separator` accepts all standard HTML attributes (`id`, `aria-*`, `data-*`, `style`, `className`) plus `orientation`. It does not accept `children`.
+
+### Default orientation difference
+
+Tractor's `Divider` defaulted to `orientation="vertical"`. The DS `Separator` defaults to `orientation="horizontal"`. Always pass `orientation` explicitly on both sides of the migration to avoid a silent layout change.
+
+## 5. Sizing behavior
+
+Tractor's `Divider` used a `size` prop to control thickness (`xSmall` = 1 px, `small` = 2 px). The DS `Separator` is always 1 px thick via Tailwind classes applied internally (`data-[orientation=horizontal]:h-px` / `data-[orientation=vertical]:w-px`). There is no thickness prop — if you need a 2 px separator, add `className="data-[orientation=horizontal]:h-0.5 data-[orientation=vertical]:w-0.5"`.
+
+## 6. Color behavior
+
+Tractor's `Divider` accepted a Tractor design-token string via `bg` (e.g. `"graphic-default"`, `"neutral-700"`). The DS `Separator` uses `bg-border` by default (mapped to the DS border token). To override, pass a Tailwind utility class via `className`:
+
+```tsx
+// Tractor custom color
+<Divider orientation="vertical" bg="neutral-700" />
+
+// DS equivalent
+<Separator orientation="vertical" className="bg-neutral-700" />
+```
+
+## 7. Before / After examples
+
+### 7a. Horizontal separator between sections (default use case)
+
+**Before (Tractor):**
+```tsx
+import { Divider } from '@aircall/tractor';
+
+export function SectionBreak() {
+  return <Divider orientation="horizontal" />;
+}
+```
+
+**After (DS):**
+```tsx
+import { Separator } from '@aircall/ds';
+
+export function SectionBreak() {
+  return <Separator orientation="horizontal" />;
+}
+```
+
+### 7b. Vertical separator between inline items
+
+**Before (Tractor):**
+```tsx
+import { Divider } from '@aircall/tractor';
+
+export function InlineActions() {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+      <span>Calls</span>
+      <Divider orientation="vertical" />
+      <span>Contacts</span>
+    </div>
+  );
+}
+```
+
+**After (DS):**
+```tsx
+import { Separator } from '@aircall/ds';
+
+export function InlineActions() {
+  return (
+    <div className="flex items-center gap-2">
+      <span>Calls</span>
+      <Separator orientation="vertical" />
+      <span>Contacts</span>
+    </div>
+  );
+}
+```
+
+### 7c. Thin divider with `size="xSmall"` dropped
+
+**Before (Tractor):**
+```tsx
+import { Divider } from '@aircall/tractor';
+
+export function MenuDivider() {
+  return <Divider orientation="horizontal" size="xSmall" />;
+}
+```
+
+**After (DS):**
+```tsx
+import { Separator } from '@aircall/ds';
+
+export function MenuDivider() {
+  return <Separator orientation="horizontal" />;
+}
+```
+
+> Both `xSmall` (1 px) and DS default (1 px) are identical. Drop `size` without any replacement.
+
+### 7d. Custom color via `bg` → `className`
+
+**Before (Tractor):**
+```tsx
+import { Divider } from '@aircall/tractor';
+
+export function BoldDivider() {
+  return <Divider orientation="horizontal" size="small" bg="neutral-700" />;
+}
+```
+
+**After (DS):**
+```tsx
+import { Separator } from '@aircall/ds';
+
+export function BoldDivider() {
+  return (
+    <Separator
+      orientation="horizontal"
+      className="bg-neutral-700 data-[orientation=horizontal]:h-0.5"
+    />
+  );
+}
+```
+
+> `size="small"` (2 px) has no direct DS equivalent — use `data-[orientation=horizontal]:h-0.5` to restore the 2 px thickness.
+
+## 8. Common mistakes
+
+### Mistake 1: Relying on the default orientation matching Tractor's default
+
+```tsx
+// WRONG — Tractor default is "vertical"; DS default is "horizontal"; omitting orientation
+// silently changes the rendered layout
+<Separator />
+
+// CORRECT — always pass orientation explicitly
+<Separator orientation="vertical" />
+```
+
+Tractor's `Divider` defaulted to `orientation="vertical"`. The DS `Separator` defaults to `orientation="horizontal"` (matching the Base UI primitive default). Omitting the prop after renaming the component causes a horizontal line to appear where a vertical one was expected — no warning, no error.
+
+Source: `packages/ds/src/components/separator.tsx` — `orientation = 'horizontal'` is the destructured default.
+
+---
+
+### Mistake 2: Passing the `size` prop expecting thickness control
+
+```tsx
+// WRONG — DS Separator has no `size` prop; it spreads onto the DOM element as a string attribute
+<Separator orientation="horizontal" size="small" />
+
+// CORRECT — drop `size`; for 2 px thickness add a Tailwind class
+<Separator orientation="horizontal" className="data-[orientation=horizontal]:h-0.5" />
+```
+
+`SeparatorProps` extends `SeparatorPrimitive.Props`, which has no `size` field. Because `Separator` spreads unknown props onto the Base UI primitive, `size="small"` becomes a non-standard DOM attribute, triggering a React warning and failing strict DOM validation.
+
+Source: `packages/ds/src/components/separator.tsx` — `SeparatorProps` extends `SeparatorPrimitive.Props` with no additional fields.
+
+---
+
+### Mistake 3: Passing a Tractor design-token string to `bg` or `color`
+
+```tsx
+// WRONG — DS Separator has no `bg` prop; passing it spreads a raw string onto the DOM
+<Separator orientation="vertical" bg="graphic-default" />
+
+// CORRECT — use a Tailwind bg-* utility via className
+<Separator orientation="vertical" className="bg-border" />
+```
+
+Tractor's `Divider` was built on `Box`, which accepted Tractor design-token strings for `bg`. `Separator` is a Base UI element with no styled-system layer — there is no `bg` prop. Passing it results in `bg="graphic-default"` becoming an invalid HTML attribute on the rendered DOM element.
+
+Source: `packages/ds/src/components/separator.tsx` — root renders `<SeparatorPrimitive>` directly; `bg` is not in `SeparatorPrimitive.Props`.

package/skills/aircall-ds/migrate-tractor/dropdown-menu/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: aircall-ds/migrate-tractor/dropdown-menu
+description: >
+  Migrate Tractor Dropdown and ActionMenu to the @aircall/ds DropdownMenu compound.
+  Load when a file imports Dropdown, ActionMenu, or ActionMenuItem from @aircall/tractor.
+  Covers trigger render prop, destructive item variant, icon placement, 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/dropdown-menu.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 dropdown-menu-specific steps below.
+
+## 1. Component mapping
+
+Tractor `Dropdown` (labelled button trigger) and `ActionMenu` (icon-only "•••" trigger) both map to the same DS `DropdownMenu` compound. The visual difference is achieved through the `Button` variant/size passed to `DropdownMenuTrigger`'s `render` prop.
+
+| Tractor part | DS compound part | Role |
+| --- | --- | --- |
+| `<Dropdown>` / `<ActionMenu>` | `<DropdownMenu>` | State owner (open, modal) |
+| _(trigger button)_ | `<DropdownMenuTrigger>` | Clickable trigger — accepts any button via `render` |
+| `<DropdownItem>` / `<ActionMenuItem>` | `<DropdownMenuItem>` | Individual action item |
+| _(no equivalent)_ | `<DropdownMenuContent>` | Floating panel container |
+| _(no equivalent)_ | `<DropdownMenuGroup>` | Required wrapper around a labelled section |
+| _(no equivalent)_ | `<DropdownMenuLabel>` | Section heading — must be inside `DropdownMenuGroup` |
+| _(no equivalent)_ | `<DropdownMenuSeparator>` | Horizontal rule between sections |
+| _(no equivalent)_ | `<DropdownMenuAddon>` | Trailing right-aligned slot inside an item |
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+DropdownMenu, DropdownMenuContent, DropdownMenuGroup,
+DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator,
+DropdownMenuTrigger, DropdownMenuAddon,
+DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent,
+DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem,
+DropdownMenuPortal, DropdownMenuShortcut,
+Button
+```
+
+## 3. Imports
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+  Button,
+} from '@aircall/ds';
+```
+
+For ActionMenu (icon trigger + icon items), also import from `@aircall/react-icons`:
+
+```tsx
+import { MoreVerticalFill, EditPencilFill, DeleteTrashFill } from '@aircall/react-icons';
+```
+
+## 4. Prop and pattern changes
+
+| Tractor | DS | Notes |
+| --- | --- | --- |
+| `<Dropdown label="Options">` | `<DropdownMenuTrigger render={<Button variant="outline" size="lg" />}>Options</DropdownMenuTrigger>` | Trigger button is composed via `render` prop |
+| `<ActionMenu>` | `<DropdownMenuTrigger render={<Button variant="ghost" size="icon" />}><MoreVerticalFill /></DropdownMenuTrigger>` | Icon-only trigger uses `size="icon"` |
+| `<ActionMenuItem variant="critical">` | `<DropdownMenuItem variant="destructive">` | Use `variant` prop, not `className` |
+| `icon={EditOutlined}` on `ActionMenuItem` | Icon as first child of `DropdownMenuItem` | Render icon directly inside the item |
+| `<DropdownSection label="X">` | `<DropdownMenuGroup><DropdownMenuLabel>X</DropdownMenuLabel>…</DropdownMenuGroup>` | Label must be inside a `DropdownMenuGroup` |
+
+## 5. Before / After — plain Dropdown
+
+### Before (Tractor)
+
+```tsx
+import { Dropdown, DropdownItem } from '@aircall/tractor';
+
+<Dropdown label="Options">
+  <DropdownItem onClick={handleEdit}>Edit</DropdownItem>
+  <DropdownItem onClick={handleDelete}>Delete</DropdownItem>
+</Dropdown>
+```
+
+### After (DS)
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+  Button,
+} from '@aircall/ds';
+
+<DropdownMenu>
+  <DropdownMenuTrigger render={<Button variant="outline" size="lg" />}>
+    Options
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem onClick={handleEdit}>Edit</DropdownMenuItem>
+    <DropdownMenuItem onClick={handleDelete}>Delete</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+## 6. Before / After — ActionMenu (icon trigger + icon items)
+
+### Before (Tractor)
+
+```tsx
+import { ActionMenu, ActionMenuItem } from '@aircall/tractor';
+
+<ActionMenu>
+  <ActionMenuItem icon={EditOutlined} onClick={handleEdit}>Edit</ActionMenuItem>
+  <ActionMenuItem icon={DeleteOutlined} variant="critical" onClick={handleDelete}>Delete</ActionMenuItem>
+</ActionMenu>
+```
+
+### After (DS)
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+  Button,
+} from '@aircall/ds';
+import { MoreVerticalFill, EditPencilFill, DeleteTrashFill } from '@aircall/react-icons';
+
+<DropdownMenu>
+  <DropdownMenuTrigger render={<Button variant="ghost" size="icon" />}>
+    <MoreVerticalFill className="size-4" />
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem onClick={handleEdit}>
+      <EditPencilFill className="mr-2 size-4" />
+      Edit
+    </DropdownMenuItem>
+    <DropdownMenuItem variant="destructive" onClick={handleDelete}>
+      <DeleteTrashFill className="mr-2 size-4" />
+      Delete
+    </DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+## 7. Sections with labels
+
+`DropdownMenuLabel` must be placed inside a `DropdownMenuGroup` alongside its items. A label as a direct child of `DropdownMenuContent` is not accessibility-correct in Base UI.
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+  Button,
+} from '@aircall/ds';
+
+<DropdownMenu>
+  <DropdownMenuTrigger render={<Button variant="outline" size="lg" />}>
+    Account
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuGroup>
+      <DropdownMenuLabel>Account</DropdownMenuLabel>
+      <DropdownMenuItem>Profile</DropdownMenuItem>
+      <DropdownMenuItem>Settings</DropdownMenuItem>
+    </DropdownMenuGroup>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem>Logout</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+## 8. Common Mistakes
+
+### Mistake 1 — Using `className="text-destructive"` instead of `variant="destructive"`
+
+```tsx
+// Wrong
+<DropdownMenuItem className="text-destructive" onClick={handleDelete}>
+  Delete
+</DropdownMenuItem>
+
+// Correct
+<DropdownMenuItem variant="destructive" onClick={handleDelete}>
+  Delete
+</DropdownMenuItem>
+```
+
+`DropdownMenuItem` has a first-class `variant` prop (`'default' | 'destructive'`). Using `variant="destructive"` applies the correct destructive text colour, hover background, and dark-mode overrides via `data-[variant=destructive]` selectors. A bare `className="text-destructive"` only sets the text colour and loses the focus-state and dark-mode styling baked into the variant.
+Source: `packages/ds/src/components/dropdown-menu.tsx`
+
+---
+
+### Mistake 2 — Placing `DropdownMenuLabel` as a direct child of `DropdownMenuContent`
+
+```tsx
+// Wrong
+<DropdownMenuContent>
+  <DropdownMenuLabel>Account</DropdownMenuLabel>
+  <DropdownMenuItem>Profile</DropdownMenuItem>
+</DropdownMenuContent>
+
+// Correct
+<DropdownMenuContent>
+  <DropdownMenuGroup>
+    <DropdownMenuLabel>Account</DropdownMenuLabel>
+    <DropdownMenuItem>Profile</DropdownMenuItem>
+  </DropdownMenuGroup>
+</DropdownMenuContent>
+```
+
+`DropdownMenuLabel` renders a Base UI `MenuPrimitive.GroupLabel`, which must be a sibling of its items inside a `MenuPrimitive.Group`. Placing it directly in `DropdownMenuContent` breaks the ARIA group association that screen readers depend on.
+Source: `packages/ds/src/components/dropdown-menu.tsx`
+
+---
+
+### Mistake 3 — Omitting the `render` prop on `DropdownMenuTrigger`
+
+```tsx
+// Wrong
+<DropdownMenuTrigger>
+  Options
+</DropdownMenuTrigger>
+
+// Correct
+<DropdownMenuTrigger render={<Button variant="outline" size="lg" />}>
+  Options
+</DropdownMenuTrigger>
+```
+
+Without a `render` prop, `DropdownMenuTrigger` renders a plain unstyled `<button>`. In the DS, trigger appearance is composed by passing a `Button` via the Base UI `render` prop — the button's variant and size control the visual style. This follows the DS-wide `render` prop pattern that replaces the old `asChild` prop.
+Source: `packages/ds/src/components/dropdown-menu.tsx`
+
+---
+
+### Mistake 4 — Passing icon as a prop instead of rendering it as a child
+
+```tsx
+// Wrong
+import { ActionMenu, ActionMenuItem } from '@aircall/tractor';
+<ActionMenuItem icon={EditOutlined}>Edit</ActionMenuItem>
+
+// Correct
+import { DropdownMenuItem } from '@aircall/ds';
+import { EditPencilFill } from '@aircall/react-icons';
+<DropdownMenuItem>
+  <EditPencilFill className="mr-2 size-4" />
+  Edit
+</DropdownMenuItem>
+```
+
+Tractor `ActionMenuItem` accepted an `icon` prop. DS `DropdownMenuItem` has no `icon` prop — the icon is placed as the first child. The `[&_svg:not([class*='size-'])]:size-4` selector on the item auto-sizes icon children that lack an explicit size class.
+Source: `packages/ds/src/components/dropdown-menu.tsx`