@aircall/ds 0.13.0 → 0.15.0

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

@@ -0,0 +1,276 @@
+---
+name: aircall-ds/migrate-tractor/accordion
+description: >
+  Migrate Tractor Accordion and AccordionSection to the @aircall/ds Accordion
+  compound (AccordionItem, AccordionTrigger, AccordionContent). Load when a file
+  imports Accordion or AccordionSection 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/accordion.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 accordion-specific steps below.
+
+## 1. Component mapping
+
+Tractor `Accordion` accepted `AccordionSection` children that bundled header, chevron, and body in a single component. DS splits each section into three named parts:
+
+| Tractor | @aircall/ds |
+| --- | --- |
+| `Accordion` | `Accordion` (state owner) |
+| `AccordionSection` | `AccordionItem` + `AccordionTrigger` + `AccordionContent` |
+| _(built into AccordionSection)_ | `AccordionTrigger` (header + built-in chevron) |
+| _(built into AccordionSection)_ | `AccordionContent` (body panel) |
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Accordion, AccordionItem, AccordionTrigger, AccordionContent
+```
+
+All names used in the Before/After section below exist in the published public API.
+
+## 3. Imports
+
+```tsx
+import {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from '@aircall/ds';
+```
+
+## 4. Prop changes
+
+| Tractor | DS | Notes |
+| --- | --- | --- |
+| _(implicit — one open at a time)_ | default (no extra prop needed) | Single-open is the DS default |
+| _(allowMultiple or equivalent)_ | `multiple` on `<Accordion>` | Boolean — allows multiple items open simultaneously |
+| _(section key)_ | `value` on `<AccordionItem>` | Required; `number` or `string`; index works for static lists |
+| _(section disabled)_ | `disabled` on `<AccordionItem>` | Disables the trigger and keeps the panel closed |
+| `defaultExpanded` / open sections | `defaultValue` on `<Accordion>` | Always an array, even in single-open mode: `defaultValue={[0]}` |
+| controlled open | `value` + `onValueChange` on `<Accordion>` | `value` is an array; `onValueChange` receives `(number \| string)[]` |
+
+## 5. Before / After
+
+### Static list (most common)
+
+```tsx
+// Before
+import { Accordion, AccordionSection } from '@aircall/tractor';
+
+<Accordion>
+  <AccordionSection title="General">
+    <p>General settings content.</p>
+  </AccordionSection>
+  <AccordionSection title="Billing">
+    <p>Billing details content.</p>
+  </AccordionSection>
+</Accordion>
+
+// After
+import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@aircall/ds';
+
+<Accordion defaultValue={[0]}>
+  <AccordionItem value={0}>
+    <AccordionTrigger>General</AccordionTrigger>
+    <AccordionContent>
+      <p>General settings content.</p>
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value={1}>
+    <AccordionTrigger>Billing</AccordionTrigger>
+    <AccordionContent>
+      <p>Billing details content.</p>
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+Key changes:
+- Each `AccordionSection` becomes three components: `AccordionItem` (identity + state), `AccordionTrigger` (header label), `AccordionContent` (body)
+- `title` prop on `AccordionSection` becomes the children of `AccordionTrigger`
+- Every `AccordionItem` requires a `value` prop — the index is fine for static lists
+- `defaultValue` is always an array on `Accordion`
+
+### Dynamic list (map over data)
+
+```tsx
+// Before
+import { Accordion, AccordionSection } from '@aircall/tractor';
+
+<Accordion>
+  {sections.map(section => (
+    <AccordionSection key={section.id} title={section.title}>
+      {section.body}
+    </AccordionSection>
+  ))}
+</Accordion>
+
+// After
+import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@aircall/ds';
+
+<Accordion defaultValue={[0]}>
+  {sections.map((section, index) => (
+    <AccordionItem key={section.id} value={index}>
+      <AccordionTrigger>{section.title}</AccordionTrigger>
+      <AccordionContent>{section.body}</AccordionContent>
+    </AccordionItem>
+  ))}
+</Accordion>
+```
+
+### Multiple sections open simultaneously
+
+```tsx
+// After — allow more than one panel open at a time
+<Accordion multiple defaultValue={[0, 1]}>
+  <AccordionItem value={0}>
+    <AccordionTrigger>General</AccordionTrigger>
+    <AccordionContent>General settings content.</AccordionContent>
+  </AccordionItem>
+  <AccordionItem value={1}>
+    <AccordionTrigger>Billing</AccordionTrigger>
+    <AccordionContent>Billing details content.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+### Controlled
+
+```tsx
+// After — controlled open state
+const [openSections, setOpenSections] = React.useState<number[]>([0]);
+
+<Accordion value={openSections} onValueChange={setOpenSections}>
+  <AccordionItem value={0}>
+    <AccordionTrigger>General</AccordionTrigger>
+    <AccordionContent>General settings content.</AccordionContent>
+  </AccordionItem>
+  <AccordionItem value={1}>
+    <AccordionTrigger>Billing</AccordionTrigger>
+    <AccordionContent>Billing details content.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+### Disabled section
+
+```tsx
+// After — disable one item
+<Accordion defaultValue={[0]}>
+  <AccordionItem value={0}>
+    <AccordionTrigger>General</AccordionTrigger>
+    <AccordionContent>General settings content.</AccordionContent>
+  </AccordionItem>
+  <AccordionItem value={1} disabled>
+    <AccordionTrigger>Billing</AccordionTrigger>
+    <AccordionContent>Billing details content.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+### Width / spacing
+
+`Accordion` has no layout props. Apply width via `className`:
+
+```tsx
+<Accordion defaultValue={[0]} className="w-[450px]">
+  ...
+</Accordion>
+```
+
+---
+
+## 6. Common Mistakes
+
+### Mistake 1 — Adding a custom chevron inside `AccordionTrigger`
+
+```tsx
+// Wrong — AccordionTrigger renders its own chevron; adding another doubles it
+<AccordionTrigger>
+  General
+  <ChevronDownIcon />
+</AccordionTrigger>
+
+// Correct — pass only the header label as children
+<AccordionTrigger>General</AccordionTrigger>
+```
+
+`AccordionTrigger` internally renders a `ChevronDownIcon` / `ChevronUpIcon` pair that swaps on open/close state. Adding your own icon duplicates it visually. Pass only the label text (or non-icon content) as children.
+
+Source: `packages/ds/src/components/accordion.tsx`
+
+---
+
+### Mistake 2 — Passing `defaultValue` / `value` as a scalar instead of an array
+
+```tsx
+// Wrong — scalar causes a TypeScript error and the panel does not open
+<Accordion defaultValue={0}>
+  <AccordionItem value={0}>
+    <AccordionTrigger>General</AccordionTrigger>
+    <AccordionContent>General settings content.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+
+// Correct — always wrap in an array, even for a single default item
+<Accordion defaultValue={[0]}>
+  <AccordionItem value={0}>
+    <AccordionTrigger>General</AccordionTrigger>
+    <AccordionContent>General settings content.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+Both `defaultValue` and `value` on `Accordion` are typed as `(number | string)[]`. Passing a bare scalar is a type error and the Base UI primitive will not open the panel.
+
+Source: `packages/ds/src/components/accordion.tsx`
+
+---
+
+### Mistake 3 — Omitting the `value` prop on `AccordionItem`
+
+```tsx
+// Wrong — AccordionItem without value cannot be identified for open/close state
+<AccordionItem>
+  <AccordionTrigger>General</AccordionTrigger>
+  <AccordionContent>General settings content.</AccordionContent>
+</AccordionItem>
+
+// Correct — every AccordionItem needs a unique value
+<AccordionItem value={0}>
+  <AccordionTrigger>General</AccordionTrigger>
+  <AccordionContent>General settings content.</AccordionContent>
+</AccordionItem>
+```
+
+`value` is required by the Base UI Accordion primitive to track which items are open. Without it the item cannot be matched against `defaultValue` / `value` on the root `Accordion`, so the panel stays permanently closed and toggling has no effect.
+
+Source: `packages/ds/src/components/accordion.tsx`
+
+---
+
+### Mistake 4 — Using `type="multiple"` instead of the `multiple` boolean
+
+```tsx
+// Wrong — type prop does not exist on DS Accordion; silently ignored
+<Accordion type="multiple" defaultValue={[0, 1]}>
+  ...
+</Accordion>
+
+// Correct — DS uses a boolean `multiple` prop (same convention as ToggleGroup)
+<Accordion multiple defaultValue={[0, 1]}>
+  ...
+</Accordion>
+```
+
+Tractor (and some other libraries) use `type="single" | "multiple"` to control this behavior. DS uses the simpler boolean `multiple` prop. Passing `type="multiple"` is silently ignored — the accordion reverts to single-open mode with no TypeScript error.
+
+Source: `packages/ds/src/components/accordion.tsx`

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

@@ -0,0 +1,225 @@
+---
+name: aircall-ds/migrate-tractor/alert
+description: >
+  Migrate Tractor Banner (Banner, BannerHeading, BannerIcon, BannerParagraph) to
+  @aircall/ds Alert (rounded) vs Banner (inline). Load when a file imports Banner*
+  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/alert-and-banner.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 alert-specific steps below.
+
+## 1. Alert vs Banner — pick the right component
+
+Tractor `Banner` maps to **two** DS components. Choose based on visual shape:
+
+| If the Tractor `Banner` looks like… | Use DS component |
+| --- | --- |
+| Rounded card-style callout (`rounded-3xl`, full border) | `Alert` |
+| Full-width inline strip with accent edge (square corners, border on one side) | `Banner` |
+
+`Banner` re-exports the `Alert*` sub-parts under `Banner*` aliases — the children grammar is identical. Pick the container; the parts follow.
+
+## 2. Sub-part mapping
+
+| Tractor | DS (`Alert`) | DS (`Banner`) |
+| --- | --- | --- |
+| `BannerHeading` | `AlertTitle` | `BannerTitle` |
+| `BannerIcon` | first `<svg>` child — **no wrapper** | same |
+| `BannerSuffix` | `AlertAction` | `BannerAction` |
+| `BannerParagraph` (body text) | `AlertDescription` | `BannerDescription` |
+
+> **Icon is a direct child, not a part.** `Alert`/`Banner` detect a leading icon via `has-[>svg]` CSS. Render the icon as the **first child** — never wrap it. There is no `AlertIcon` or `BannerIcon` component in DS.
+
+## 3. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Alert, AlertAction, AlertDescription, AlertTitle,
+Banner, BannerAction, BannerDescription, BannerTitle,
+```
+
+All eight names exist in the published public API. Do not use any other Alert/Banner parts.
+
+## 4. Imports
+
+```tsx
+import {
+  Alert, AlertTitle, AlertDescription, AlertAction,
+  Banner, BannerTitle, BannerDescription, BannerAction,
+  Button,
+} from '@aircall/ds';
+import { Info, AlertTriangle, X } from '@aircall/react-icons';
+```
+
+## 5. Before / After
+
+### Before (Tractor)
+
+```tsx
+import { Banner, BannerHeading, BannerIcon, BannerParagraph, BannerSuffix } from '@aircall/tractor';
+
+// Rounded callout
+<Banner variant="informative">
+  <BannerIcon><Info /></BannerIcon>
+  <BannerHeading>Heads up</BannerHeading>
+  <BannerParagraph>Your trial ends in 3 days.</BannerParagraph>
+  <BannerSuffix><button onClick={onDismiss}>✕</button></BannerSuffix>
+</Banner>
+
+// Full-width inline strip
+<Banner variant="critical">
+  <BannerIcon><AlertTriangle /></BannerIcon>
+  <BannerHeading>Limited connectivity</BannerHeading>
+  <BannerParagraph>Some calls may not connect.</BannerParagraph>
+  <BannerSuffix><button onClick={onRetry}>Retry</button></BannerSuffix>
+</Banner>
+```
+
+### After (DS)
+
+```tsx
+import {
+  Alert, AlertTitle, AlertDescription, AlertAction,
+  Banner, BannerTitle, BannerDescription, BannerAction,
+  Button,
+} from '@aircall/ds';
+import { Info, AlertTriangle, X } from '@aircall/react-icons';
+
+// Rounded callout → Alert
+<Alert variant="info">
+  <Info />                       {/* BannerIcon → first <svg> child, no wrapper */}
+  <AlertTitle>Heads up</AlertTitle>
+  <AlertDescription>Your trial ends in 3 days.</AlertDescription>
+  <AlertAction>
+    <Button variant="ghost" size="icon-sm" onClick={onDismiss}><X /></Button>
+  </AlertAction>
+</Alert>
+
+// Full-width inline strip → Banner
+<Banner variant="error" borderDirection="top">
+  <AlertTriangle />
+  <BannerTitle>Limited connectivity</BannerTitle>
+  <BannerDescription>Some calls may not connect.</BannerDescription>
+  <BannerAction>
+    <Button variant="outline" size="sm" onClick={onRetry}>Retry</Button>
+  </BannerAction>
+</Banner>
+```
+
+## 6. Variant mapping
+
+| Tractor variant | DS variant |
+| --- | --- |
+| `informative` | `info` |
+| `critical` | `error` |
+| `warning` | `warning` |
+| `positive` / `success` | `success` |
+| (default / none) | `default` |
+
+Both `Alert` and `Banner` share the same set: `default` / `info` / `success` / `warning` / `error`.
+
+## 7. `Banner`-only prop: `borderDirection`
+
+`Banner` accepts `borderDirection="top" | "bottom"` to place the accent border. `Alert` has no border-side prop — it is fully bordered and rounded.
+
+## 8. Common Mistakes
+
+### Mistake 1 — Wrapping the icon in a part component
+
+```tsx
+// Wrong
+<Alert variant="info">
+  <AlertIcon><Info /></AlertIcon>   {/* AlertIcon does not exist in @aircall/ds */}
+  ...
+</Alert>
+
+// Correct
+<Alert variant="info">
+  <Info />                           {/* bare <svg> first child activates the grid */}
+  ...
+</Alert>
+```
+
+`Alert`/`Banner` use `has-[>svg]` to detect the icon slot. Wrapping the SVG in any element breaks the CSS selector and the icon fails to render in the correct grid area.
+Source: `packages/ds/src/components/alert.tsx`
+
+---
+
+### Mistake 2 — Using `destructive` instead of `error`
+
+```tsx
+// Wrong
+<Alert variant="destructive">...</Alert>   {/* destructive is a Button variant, not Alert */}
+
+// Correct
+<Alert variant="error">...</Alert>         {/* maps Tractor critical */}
+```
+
+`destructive` is a `Button` variant. `Alert`/`Banner` only accept `default | info | success | warning | error`. Passing an unknown variant silently falls through to `default` styling.
+Source: `packages/ds/src/components/alert.tsx`
+
+---
+
+### Mistake 3 — Using `AlertAction`/`BannerAction` for the icon instead of the suffix
+
+```tsx
+// Wrong
+<Alert variant="warning">
+  <AlertAction><AlertTriangle /></AlertAction>  {/* icon in the trailing action slot */}
+  <AlertTitle>Watch out</AlertTitle>
+</Alert>
+
+// Correct
+<Alert variant="warning">
+  <AlertTriangle />         {/* first <svg> child → leading icon slot */}
+  <AlertTitle>Watch out</AlertTitle>
+</Alert>
+```
+
+`AlertAction`/`BannerAction` is the **trailing** slot (self-positions right, vertically centered). It is for close buttons or CTAs, not the leading icon. Placing the icon there yields wrong layout.
+Source: `packages/ds/src/components/alert.tsx`
+
+---
+
+### Mistake 4 — Setting icon color manually
+
+```tsx
+// Wrong
+<Alert variant="info">
+  <Info className="text-blue-500" />   {/* manual color overrides variant-driven color */}
+  ...
+</Alert>
+
+// Correct
+<Alert variant="info">
+  <Info />                              {/* variant applies [&>svg]:text-info automatically */}
+  ...
+</Alert>
+```
+
+`Alert`/`Banner` apply `[&>svg]:text-<variant>` on the root. Explicit color classes on the icon fight the cascade and cause inconsistency across themes.
+Source: `packages/ds/src/components/alert.tsx`
+
+---
+
+### Mistake 5 — Using `borderDirection` on `Alert`
+
+```tsx
+// Wrong
+<Alert variant="warning" borderDirection="top">...</Alert>  {/* prop not supported on Alert */}
+
+// Correct
+<Banner variant="warning" borderDirection="top">            {/* Banner is the inline strip */}
+  ...
+</Banner>
+```
+
+`borderDirection` is a `Banner`-only prop (inline strip component). `Alert` is always fully bordered and rounded; it has no border-side prop. The prop is silently ignored on `Alert`.
+Source: `packages/ds/src/components/banner.tsx`