@aircall/ds 0.14.0 → 0.15.0

package/skills/aircall-ds/migrate-tractor/sheet-vs-drawer/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: aircall-ds/migrate-tractor/sheet-vs-drawer
+description: >
+  Migrate Tractor Drawer (desktop side panel) to @aircall/ds Sheet or Drawer.
+  Covers SheetContent side prop, DrawerPopup vs DrawerContent confusion, and
+  the render prop pattern for Trigger/Close. Load when a file imports Drawer
+  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/sheet-vs-drawer.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 sheet-vs-drawer-specific steps below.
+
+## 1. Which component to use
+
+DS ships two distinct side-panel components. The Tractor `Drawer` maps to **`Sheet`** for desktop side panels — not to DS's `Drawer`. DS's own `Drawer` is reserved for mobile-style panels with swipe-to-dismiss edge gestures.
+
+| Use case | DS component | Built on |
+| --- | --- | --- |
+| Persistent side panel (navigation, filters, settings) | `Sheet` | Base UI Dialog |
+| Mobile-style swipe-to-dismiss edge panel | `Drawer` | Base UI Drawer (Coss UI) |
+
+When in doubt, use `Sheet`.
+
+## 2. Component mapping — Tractor Drawer → DS Sheet
+
+| Tractor | @aircall/ds |
+| --- | --- |
+| `Drawer` (root + state) | `Sheet` |
+| `DrawerHeader` | `SheetHeader` |
+| `DrawerTitle` | `SheetTitle` |
+| `DrawerBody` / body content | plain children inside `SheetContent` |
+| `DrawerFooter` | `SheetFooter` |
+| — | `SheetContent` (the panel popup; carries the `side` prop) |
+| — | `SheetTrigger` (uncontrolled open trigger) |
+| — | `SheetClose` (any element that closes the sheet) |
+| — | `SheetDescription` (optional accessible subtitle) |
+
+## 3. Component mapping — DS Drawer parts (swipe use case only)
+
+| DS Drawer part | Role |
+| --- | --- |
+| `Drawer` | Root state owner; accepts `position` and `open`/`onOpenChange` |
+| `DrawerPopup` | The panel surface — **use this, not `DrawerContent`** |
+| `DrawerHeader` | Header section inside `DrawerPopup` |
+| `DrawerTitle` | Accessible title inside `DrawerHeader` |
+| `DrawerFooter` | Footer section inside `DrawerPopup` |
+| `DrawerClose` | Any element that closes the drawer |
+| `DrawerTrigger` | Uncontrolled open trigger |
+
+## 4. Before / After — Sheet (desktop side panel)
+
+### Before (Tractor)
+
+```tsx
+import { Drawer, DrawerHeader, DrawerTitle, DrawerBody, DrawerFooter, Button } from '@aircall/tractor';
+
+<Drawer isOpen={isOpen} onClose={() => setIsOpen(false)} position="right">
+  <DrawerHeader>
+    <DrawerTitle>Filters</DrawerTitle>
+  </DrawerHeader>
+  <DrawerBody>
+    <p>Refine the call list.</p>
+  </DrawerBody>
+  <DrawerFooter>
+    <Button variant="outline" onClick={() => setIsOpen(false)}>Cancel</Button>
+    <Button onClick={onApply}>Apply</Button>
+  </DrawerFooter>
+</Drawer>
+```
+
+### After (DS Sheet)
+
+```tsx
+import {
+  Sheet,
+  SheetClose,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+  Button
+} from '@aircall/ds';
+
+<Sheet open={isOpen} onOpenChange={setIsOpen}>
+  <SheetContent side="right">
+    <SheetHeader>
+      <SheetTitle>Filters</SheetTitle>
+      <SheetDescription>Refine the call list.</SheetDescription>
+    </SheetHeader>
+
+    <p className="text-sm">Refine the call list.</p>
+
+    <SheetFooter>
+      <SheetClose render={<Button variant="outline" size="lg" />}>
+        Cancel
+      </SheetClose>
+      <Button size="lg" onClick={onApply}>Apply</Button>
+    </SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+Key changes:
+- `isOpen` → `open`; `onClose()` → `onOpenChange(boolean)`
+- Tractor `position="right"` → `SheetContent side="right"` (prop moved to the panel part)
+- `DrawerBody` is removed — body content is plain children inside `SheetContent`
+- `SheetClose` wraps any button that closes the sheet; pass the DS `Button` via `render` and put the label as children of `SheetClose`
+- `SheetContent` renders a default "×" close button; hide it with `showCloseButton={false}` when you want to force explicit footer actions
+
+### Uncontrolled with a trigger
+
+```tsx
+import { Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetFooter, SheetClose, Button } from '@aircall/ds';
+
+<Sheet>
+  <SheetTrigger render={<Button size="lg" />}>Open filters</SheetTrigger>
+  <SheetContent side="right">
+    <SheetHeader>
+      <SheetTitle>Filters</SheetTitle>
+    </SheetHeader>
+    <p className="text-sm">Adjust your filters.</p>
+    <SheetFooter>
+      <SheetClose render={<Button variant="outline" size="lg" />}>Close</SheetClose>
+    </SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+## 5. Before / After — Drawer (swipe-to-dismiss, mobile)
+
+### After (DS Drawer)
+
+```tsx
+import {
+  Drawer,
+  DrawerClose,
+  DrawerFooter,
+  DrawerHeader,
+  DrawerPopup,
+  DrawerTitle,
+  DrawerTrigger,
+  Button
+} from '@aircall/ds';
+
+<Drawer open={isOpen} onOpenChange={setIsOpen} position="right">
+  <DrawerPopup>
+    <DrawerHeader>
+      <DrawerTitle>Action sheet</DrawerTitle>
+    </DrawerHeader>
+    <div className="p-4">
+      <p className="text-sm">Swipe to dismiss.</p>
+    </div>
+    <DrawerFooter>
+      <DrawerClose render={<Button size="lg" />}>Done</DrawerClose>
+    </DrawerFooter>
+  </DrawerPopup>
+</Drawer>
+```
+
+---
+
+## 6. Common mistakes
+
+### Mistake 1 — Using `position` on `SheetContent` instead of `side`
+
+```tsx
+// ❌ Wrong — position is a Tractor prop; SheetContent has no position prop
+<SheetContent position="right">…</SheetContent>
+
+// ✅ Correct — the edge is controlled by side on SheetContent
+<SheetContent side="right">…</SheetContent>
+```
+
+`SheetContent` accepts `side?: 'top' | 'right' | 'bottom' | 'left'`. The Tractor `position` prop is silently dropped; the sheet defaults to `side="right"` so the bug is invisible until a non-right position is needed.
+
+Source: `packages/ds/src/components/sheet.tsx`
+
+---
+
+### Mistake 2 — Using `DrawerContent` as the panel wrapper instead of `DrawerPopup`
+
+```tsx
+// ❌ Wrong — DrawerContent is a thin inner drag-interaction primitive, not the panel
+import { Drawer, DrawerContent } from '@aircall/ds';
+
+<Drawer open={isOpen} onOpenChange={setIsOpen}>
+  <DrawerContent>
+    <p>Body</p>
+  </DrawerContent>
+</Drawer>
+
+// ✅ Correct — DrawerPopup is the full panel surface with backdrop, viewport, and styling
+import { Drawer, DrawerPopup } from '@aircall/ds';
+
+<Drawer open={isOpen} onOpenChange={setIsOpen}>
+  <DrawerPopup>
+    <p>Body</p>
+  </DrawerPopup>
+</Drawer>
+```
+
+`DrawerContent` is a Base UI primitive that enables text selection within drag targets — it is not a panel container. `DrawerPopup` composes the backdrop, viewport, and panel surface and is the correct high-level wrapper.
+
+Source: `packages/ds/src/components/drawer.tsx`
+
+---
+
+### Mistake 3 — Using `asChild` on SheetTrigger or SheetClose instead of `render`
+
+```tsx
+// ❌ Wrong — asChild is a Radix pattern; DS uses Base UI's render prop
+<SheetClose asChild>
+  <Button variant="outline" size="lg">Cancel</Button>
+</SheetClose>
+
+// ✅ Correct — pass the DS Button via render; label goes as children of SheetClose
+<SheetClose render={<Button variant="outline" size="lg" />}>
+  Cancel
+</SheetClose>
+```
+
+DS is built on Base UI, which uses a `render` prop instead of Radix's `asChild`. `asChild` is silently ignored — `SheetClose` still renders its own default element, the Button is never mounted, and the close handler is lost.
+
+Source: `packages/ds/src/components/sheet.tsx`
+
+---
+
+### Mistake 4 — Mapping Tractor Drawer to DS Drawer for a desktop side panel
+
+```tsx
+// ❌ Wrong — DS Drawer is for swipe-to-dismiss mobile panels, not desktop side panels
+import { Drawer, DrawerPopup } from '@aircall/ds';
+
+<Drawer open={isOpen} onOpenChange={setIsOpen} position="right">
+  <DrawerPopup>…</DrawerPopup>
+</Drawer>
+
+// ✅ Correct — Tractor Drawer (desktop) maps to DS Sheet
+import { Sheet, SheetContent } from '@aircall/ds';
+
+<Sheet open={isOpen} onOpenChange={setIsOpen}>
+  <SheetContent side="right">…</SheetContent>
+</Sheet>
+```
+
+The naming is intentionally different: Tractor's `Drawer` was a general side panel. DS splits the concept in two — `Sheet` for persistent desktop panels and `Drawer` for mobile swipe gestures. Using DS `Drawer` for desktop panels adds unnecessary drag/swipe infrastructure and may produce unexpected dismiss behavior on touch devices.
+
+Source: `packages/ds/src/components/sheet.tsx`
+
+---
+
+### Mistake 5 — Using `onClose` instead of `onOpenChange`
+
+```tsx
+// ❌ Wrong — onClose is a Tractor prop; DS ignores it silently
+<Sheet open={isOpen} onClose={() => setIsOpen(false)}>…</Sheet>
+
+// ✅ Correct — onOpenChange receives the new boolean state
+<Sheet open={isOpen} onOpenChange={setIsOpen}>…</Sheet>
+```
+
+`onOpenChange` fires with `false` when the sheet closes (backdrop click, Escape, or `SheetClose`). The Tractor `onClose()` callback is not forwarded and the sheet becomes uncontrollable — it opens but never closes.
+
+Source: `packages/ds/src/components/sheet.tsx`

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

@@ -0,0 +1,190 @@
+---
+name: aircall-ds/migrate-tractor/skeleton
+description: >
+  Migrate Tractor Skeleton to the @aircall/ds Skeleton. Load when a file
+  imports Skeleton from @aircall/tractor. Covers the removal of shape/animation/mode
+  props and the className-based sizing pattern that replaces Tractor's BoxProps.
+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/skeleton.tsx"
+---
+
+This skill builds on aircall-ds/migrate-tractor.
+
+## 1. Component mapping
+
+Tractor `Skeleton` was a styled `Box` wrapper with `shape`, `animation`, `mode`, and `animationDelay` props. DS `Skeleton` is a plain `div` with a fixed pulse animation and rounded corners — sizing and shape are controlled entirely through `className`.
+
+| Tractor part | DS replacement | Notes |
+| --- | --- | --- |
+| `<Skeleton>` | `<Skeleton>` | Direct replacement — drop Tractor-specific props |
+| `shape="squareRounded"` | _(default)_ | DS always renders with `rounded-md`; no prop needed |
+| `shape="circle"` | `className="rounded-full"` | Override the default `rounded-md` with `rounded-full` |
+| `shape="square"` | `className="rounded-none"` | Override with `rounded-none` |
+| `shape="squircle"` | `className="rounded-xl"` | Closest equivalent; pick visually |
+| `animation="shimmer"` | _(not available)_ | DS has one animation (`animate-pulse`); no shimmer variant |
+| `animation="wave"` | _(default)_ | DS default pulse covers this |
+| `animationDelay` | `className="[animation-delay:200ms]"` | Use an arbitrary Tailwind value |
+| `mode="dark"` | `className="bg-muted/60"` | DS uses `bg-muted`; adjust opacity for dark contexts |
+| BoxProps (`w`, `h`, `width`, `height`) | `className="w-… h-…"` | Pass Tailwind sizing utilities via `className` |
+
+## 2. Verified DS export (`packages/ds/src/index.ts`)
+
+```
+Skeleton
+```
+
+## 3. Imports
+
+```tsx
+import { Skeleton } from '@aircall/ds';
+```
+
+## 4. Before / After examples
+
+### 4a. Default squareRounded skeleton (text line placeholder)
+
+**Before (Tractor):**
+```tsx
+import { Skeleton } from '@aircall/tractor';
+
+<Skeleton shape="squareRounded" w="200px" h="16px" />
+```
+
+**After (DS):**
+```tsx
+import { Skeleton } from '@aircall/ds';
+
+<Skeleton className="w-[200px] h-4" />
+```
+
+The DS default already applies `rounded-md`, so `shape="squareRounded"` requires no prop. Width and height move to Tailwind utilities in `className`.
+
+### 4b. Circle skeleton (avatar placeholder)
+
+**Before (Tractor):**
+```tsx
+import { Skeleton } from '@aircall/tractor';
+
+<Skeleton shape="circle" w="40px" h="40px" />
+```
+
+**After (DS):**
+```tsx
+import { Skeleton } from '@aircall/ds';
+
+<Skeleton className="size-10 rounded-full" />
+```
+
+`shape="circle"` maps to `rounded-full`. Use `size-10` (40px) for an exact match, or `size-8` / `size-12` for other avatar sizes.
+
+### 4c. Card skeleton layout (multiple lines)
+
+**Before (Tractor):**
+```tsx
+import { Skeleton } from '@aircall/tractor';
+
+<div>
+  <Skeleton shape="circle" w="48px" h="48px" />
+  <Skeleton shape="squareRounded" w="120px" h="14px" animationDelay />
+  <Skeleton shape="squareRounded" w="80px" h="14px" animationDelay />
+</div>
+```
+
+**After (DS):**
+```tsx
+import { Skeleton } from '@aircall/ds';
+
+<div>
+  <Skeleton className="size-12 rounded-full" />
+  <Skeleton className="w-[120px] h-3.5 [animation-delay:200ms]" />
+  <Skeleton className="w-20 h-3.5 [animation-delay:200ms]" />
+</div>
+```
+
+### 4d. Square skeleton (image placeholder)
+
+**Before (Tractor):**
+```tsx
+import { Skeleton } from '@aircall/tractor';
+
+<Skeleton shape="square" w="64px" h="64px" />
+```
+
+**After (DS):**
+```tsx
+import { Skeleton } from '@aircall/ds';
+
+<Skeleton className="size-16 rounded-none" />
+```
+
+## 5. Common Mistakes
+
+### Mistake 1 — Passing `shape` as a prop to the DS Skeleton
+
+**Wrong:**
+```tsx
+import { Skeleton } from '@aircall/ds';
+
+<Skeleton shape="circle" w="40px" h="40px" />
+```
+
+**Correct:**
+```tsx
+import { Skeleton } from '@aircall/ds';
+
+<Skeleton className="size-10 rounded-full" />
+```
+
+DS `Skeleton` extends `React.ComponentProps<'div'>` — it has no `shape` prop. Passing `shape` forwards an unknown attribute to the DOM (a React warning) and the element renders as the default `rounded-md` rectangle, not a circle.
+
+Source: `packages/ds/src/components/skeleton.tsx`
+
+---
+
+### Mistake 2 — Using BoxProps (`w`, `h`) instead of `className` for sizing
+
+**Wrong:**
+```tsx
+import { Skeleton } from '@aircall/ds';
+
+<Skeleton w="200px" h="16px" />
+```
+
+**Correct:**
+```tsx
+import { Skeleton } from '@aircall/ds';
+
+<Skeleton className="w-[200px] h-4" />
+```
+
+Tractor `Skeleton` extended `BoxProps` from `@xstyled/styled-components`, so `w` and `h` were valid styled-system props. DS `Skeleton` is a plain `div` — `w` and `h` are not recognized and will be forwarded as invalid HTML attributes, producing DOM warnings and no visual effect on sizing.
+
+Source: `packages/ds/src/components/skeleton.tsx`
+
+---
+
+### Mistake 3 — Expecting a `animation="shimmer"` variant
+
+**Wrong:**
+```tsx
+import { Skeleton } from '@aircall/ds';
+
+<Skeleton animation="shimmer" className="w-32 h-4" />
+```
+
+**Correct:**
+```tsx
+import { Skeleton } from '@aircall/ds';
+
+<Skeleton className="w-32 h-4" />
+```
+
+DS `Skeleton` has exactly one animation: `animate-pulse` (a CSS opacity pulse). There is no shimmer or wave variant. The `animation` prop does not exist on the DS component — passing it forwards the string to the DOM and triggers a React invalid-prop warning. Use the single DS animation as-is, or override with an arbitrary Tailwind animation utility if a shimmer effect is required for a specific design.
+
+Source: `packages/ds/src/components/skeleton.tsx`