@aircall/ds 0.13.0 → 0.15.0

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

@@ -0,0 +1,322 @@
+---
+name: aircall-ds/migrate-tractor/toast
+description: >
+  Migrate Tractor useToast, toasts (pubsub), and ToastManager to the @aircall/ds
+  toast imperative API and Toaster component. Load when a file imports useToast,
+  toasts, ToastManager, or Toast 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:packages/ds/src/components/sonner.tsx"
+---
+
+This skill builds on aircall-ds/migrate-tractor.
+
+## 1. Component / API mapping
+
+Tractor had a context-based system (`ToastManager` provider + `useToast` hook or `toasts` pubsub object). DS replaces it with [sonner](https://sonner.emilkowal.ski/), exposed as an imperative `toast` function and a `<Toaster>` mount point.
+
+| Tractor part | DS replacement | Notes |
+| --- | --- | --- |
+| `<ToastManager>` in app root | `<Toaster>` in app root | Place once near the root; no children needed |
+| `useToast()` → `toast.showToast({ … })` | `toast(message, options?)` | Direct import — no hook, no context |
+| `toasts.showToast({ … })` (pubsub) | `toast(message, options?)` | Same replacement; the pubsub layer is gone |
+| `toast.showToast({ variant: 'success' })` | `toast.success(message)` | Convenience method per variant |
+| `toast.showToast({ variant: 'info' })` | `toast.info(message)` | |
+| `toast.showToast({ variant: 'critical' })` | `toast.error(message)` | Tractor `critical` → DS `error` |
+| `toast.showToast({ variant: 'warning' })` | `toast.warning(message)` | |
+| `toast.showToast({ dismissIn: N })` | `toast(msg, { duration: N })` | Same unit (ms) |
+| `toast.showToast({ message: <ReactNode> })` | `toast(message)` | Pass string or JSX directly |
+| cleanup fn returned by `showToast` | `toast.dismiss(id)` | Call with the id returned by `toast()` |
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Toaster, toast
+```
+
+## 3. Imports
+
+```tsx
+import { Toaster, toast } from '@aircall/ds';
+```
+
+`toast` is an imperative function (not a React hook) — it can be called from anywhere: event handlers, async callbacks, utility functions, without `useToast` or a context consumer.
+
+## 4. Mount the Toaster once
+
+Place `<Toaster>` once in the component tree, typically at app root. It renders the toast portal and applies DS theming (rounded corners, semantic colour tokens, design-system icons).
+
+```tsx
+import { Toaster } from '@aircall/ds';
+
+function App() {
+  return (
+    <>
+      <Toaster />
+      {/* rest of the app */}
+    </>
+  );
+}
+```
+
+`Toaster` accepts all [sonner `ToasterProps`](https://sonner.emilkowal.ski/getting-started) — e.g. `position`, `richColors`, `closeButton`, `duration`.
+
+## 5. Trigger toasts imperatively
+
+```tsx
+import { toast } from '@aircall/ds';
+
+// Generic (default styling)
+toast('Settings saved');
+
+// Variant convenience methods
+toast.success('Call recorded successfully');
+toast.info('Sync in progress');
+toast.error('Could not reach the server');    // Tractor: variant="critical"
+toast.warning('Your plan is almost at capacity');
+
+// With duration (ms)
+toast.success('Done', { duration: 3000 });
+
+// With a description
+toast.success('Recording saved', {
+  description: 'The file has been uploaded to your workspace.'
+});
+
+// Capture id to dismiss later
+const id = toast.loading('Uploading…');
+// … async work …
+toast.dismiss(id);
+toast.success('Upload complete');
+```
+
+## 6. Before / After examples
+
+### 6a. Provider setup
+
+**Before (Tractor):**
+```tsx
+import { ToastManager } from '@aircall/tractor';
+
+function App({ children }: { children: React.ReactNode }) {
+  return (
+    <ToastManager placement="bottom">
+      {children}
+    </ToastManager>
+  );
+}
+```
+
+**After (DS):**
+```tsx
+import { Toaster } from '@aircall/ds';
+
+function App({ children }: { children: React.ReactNode }) {
+  return (
+    <>
+      <Toaster position="bottom-center" />
+      {children}
+    </>
+  );
+}
+```
+
+### 6b. Hook-based trigger → imperative call
+
+**Before (Tractor):**
+```tsx
+import { useToast } from '@aircall/tractor';
+
+function SaveButton() {
+  const toast = useToast();
+
+  const handleSave = async () => {
+    await save();
+    toast.showToast({
+      variant: 'success',
+      icon: true,
+      dismissIn: 3000,
+      message: 'Settings saved'
+    });
+  };
+
+  return <button onClick={handleSave}>Save</button>;
+}
+```
+
+**After (DS):**
+```tsx
+import { toast } from '@aircall/ds';
+
+function SaveButton() {
+  const handleSave = async () => {
+    await save();
+    toast.success('Settings saved', { duration: 3000 });
+  };
+
+  return <button onClick={handleSave}>Save</button>;
+}
+```
+
+### 6c. Pubsub trigger → imperative call
+
+**Before (Tractor):**
+```tsx
+import { toasts } from '@aircall/tractor';
+
+async function handleUpload(file: File) {
+  try {
+    await upload(file);
+    toasts.showToast({ variant: 'success', message: 'File uploaded', dismissIn: 4000 });
+  } catch {
+    toasts.showToast({ variant: 'critical', message: 'Upload failed' });
+  }
+}
+```
+
+**After (DS):**
+```tsx
+import { toast } from '@aircall/ds';
+
+async function handleUpload(file: File) {
+  try {
+    await upload(file);
+    toast.success('File uploaded', { duration: 4000 });
+  } catch {
+    toast.error('Upload failed');
+  }
+}
+```
+
+### 6d. Loading state with manual dismiss
+
+**Before (Tractor):**
+```tsx
+import { useToast } from '@aircall/tractor';
+
+function SyncButton() {
+  const { showToast } = useToast();
+
+  const handleSync = async () => {
+    const dismiss = showToast({ variant: 'info', message: 'Syncing…', dismissIn: 0 });
+    await syncData();
+    dismiss();
+    showToast({ variant: 'success', message: 'Sync complete', dismissIn: 3000 });
+  };
+
+  return <button onClick={handleSync}>Sync</button>;
+}
+```
+
+**After (DS):**
+```tsx
+import { toast } from '@aircall/ds';
+
+function SyncButton() {
+  const handleSync = async () => {
+    const id = toast.loading('Syncing…');
+    await syncData();
+    toast.dismiss(id);
+    toast.success('Sync complete', { duration: 3000 });
+  };
+
+  return <button onClick={handleSync}>Sync</button>;
+}
+```
+
+## 7. Common Mistakes
+
+### Mistake 1 — Keeping `<ToastManager>` with children wrapping the app
+
+**Wrong:**
+```tsx
+import { ToastManager } from '@aircall/tractor';
+
+<ToastManager placement="bottom">
+  <App />
+</ToastManager>
+```
+
+**Correct:**
+```tsx
+import { Toaster } from '@aircall/ds';
+
+<>
+  <Toaster position="bottom-center" />
+  <App />
+</>
+```
+
+`<Toaster>` is a portal mount point, not a layout wrapper — it renders the toast container into a portal and takes no children. Wrapping the app in it gains nothing; sonner manages the DOM insertion independently.
+
+Source: `packages/ds/src/components/sonner.tsx`
+
+---
+
+### Mistake 2 — Mapping Tractor `critical` variant to `toast.success` or plain `toast`
+
+**Wrong:**
+```tsx
+// Tractor variant="critical" silently maps to wrong DS call
+toast('Payment method declined');
+toast.success('Payment method declined');
+```
+
+**Correct:**
+```tsx
+toast.error('Payment method declined');
+```
+
+Tractor named its destructive variant `"critical"`. DS (via sonner) uses `error`. The `toast()` default call produces a plain (default-styled) toast with no semantic colour — it does not inherit critical/error styling. Only `toast.error()` applies the destructive background and icon token.
+
+Source: `packages/ds/src/components/sonner.tsx` — `classNames.error = '!bg-destructive-background !border-destructive/35 …'`.
+
+---
+
+### Mistake 3 — Calling `useToast()` expecting a hook
+
+**Wrong:**
+```tsx
+import { useToast } from '@aircall/ds';   // does not exist
+
+function MyComponent() {
+  const toast = useToast();               // build error
+  toast.showToast({ variant: 'info', message: 'Hello' });
+}
+```
+
+**Correct:**
+```tsx
+import { toast } from '@aircall/ds';
+
+function MyComponent() {
+  toast.info('Hello');
+}
+```
+
+`@aircall/ds` exports no `useToast` hook — `toast` is a plain function, not a hook. Importing `useToast` from `@aircall/ds` causes a build-time error. The `toast` function is call-anywhere: event handlers, async functions, plain modules outside React.
+
+Source: `packages/ds/src/components/sonner.tsx` — `export { Toaster, toast }`, re-exported from `sonner`.
+
+---
+
+### Mistake 4 — Using `dismissIn` option key instead of `duration`
+
+**Wrong:**
+```tsx
+toast.success('Done', { dismissIn: 3000 });
+```
+
+**Correct:**
+```tsx
+toast.success('Done', { duration: 3000 });
+```
+
+Tractor's `showToast` accepted a `dismissIn` property (milliseconds). Sonner's option key is `duration`. Passing `dismissIn` is silently ignored — the toast will use the default duration (~4 s) regardless of the value passed.
+
+Source: `packages/ds/src/components/sonner.tsx` — wraps sonner `Toaster`; see [sonner API](https://sonner.emilkowal.ski/toast) for `duration`.

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

@@ -0,0 +1,204 @@
+---
+name: aircall-ds/migrate-tractor/tooltip
+description: >
+  Migrate Tractor Tooltip to the @aircall/ds Tooltip compound (Tooltip,
+  TooltipTrigger, TooltipContent, TooltipProvider). Load when a file imports
+  Tooltip 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/tooltip.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 tooltip-specific steps below.
+
+## 1. Component mapping
+
+| Tractor | @aircall/ds |
+| --- | --- |
+| `Tooltip` (self-contained, `content` prop) | `Tooltip` (Root state owner) |
+| — | `TooltipTrigger` (the element that activates the tooltip) |
+| `content` prop (tooltip text) | `TooltipContent` (children, compound part) |
+| — | `TooltipProvider` (once at app root; sets delay for all tooltips) |
+| `placement` prop | `side` + `align` props on `TooltipContent` |
+
+## 2. Imports
+
+```tsx
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, Button } from '@aircall/ds';
+```
+
+For icon-only triggers, import icons from `@aircall/react-icons`:
+
+```tsx
+import { Info } from '@aircall/react-icons';
+```
+
+## 3. Provider (once, at the app root)
+
+Wrap the app with `TooltipProvider` once. All `Tooltip` instances inside share the delay.
+
+```tsx
+// Before — no equivalent; Tractor's Tooltip managed its own timing internally
+
+// After — add once near the root (e.g. in App.tsx or a layout component)
+import { TooltipProvider } from '@aircall/ds';
+
+<TooltipProvider delay={0}>
+  <App />
+</TooltipProvider>
+```
+
+The prop is `delay` (Base UI), not `delayDuration` (Radix). Default is `0`.
+
+## 4. Before / After
+
+### Basic text trigger
+
+```tsx
+// Before
+import { Tooltip, Button } from '@aircall/tractor';
+
+<Tooltip content="Helpful hint">
+  <Button variant="ghost">Help</Button>
+</Tooltip>
+
+// After
+import { Tooltip, TooltipTrigger, TooltipContent, Button } from '@aircall/ds';
+
+<Tooltip>
+  <TooltipTrigger render={<Button variant="ghost" />}>Help</TooltipTrigger>
+  <TooltipContent>Helpful hint</TooltipContent>
+</Tooltip>
+```
+
+### Icon-only trigger (most common pattern)
+
+```tsx
+// Before
+import { Tooltip, IconButton } from '@aircall/tractor';
+import { InfoIcon } from '@aircall/react-icons';
+
+<Tooltip content="More information" placement="bottom">
+  <IconButton label="More information" icon={<InfoIcon />} />
+</Tooltip>
+
+// After
+import { Tooltip, TooltipTrigger, TooltipContent, Button } from '@aircall/ds';
+import { Info } from '@aircall/react-icons';
+
+<Tooltip>
+  <TooltipTrigger render={<Button variant="ghost" size="icon" aria-label="More information" />}>
+    <Info className="size-4" />
+  </TooltipTrigger>
+  <TooltipContent side="bottom">More information</TooltipContent>
+</Tooltip>
+```
+
+Key changes:
+- `content` prop is gone — tooltip text moves to children of `TooltipContent`
+- The trigger element is wrapped in `TooltipTrigger` with the DS component passed via `render`
+- `placement` → `side` on `TooltipContent` (default `side="top"`, `sideOffset={4}`)
+- Icon-only triggers must have an explicit `aria-label` — the tooltip text is not exposed as the control's accessible name
+- The arrow and `accent-foreground` styling are built in — do not re-skin them
+
+### Controlled placement
+
+```tsx
+// Before
+import { Tooltip } from '@aircall/tractor';
+
+<Tooltip content="Save changes" placement="right">
+  <button>Save</button>
+</Tooltip>
+
+// After
+import { Tooltip, TooltipTrigger, TooltipContent } from '@aircall/ds';
+
+<Tooltip>
+  <TooltipTrigger>Save</TooltipTrigger>
+  <TooltipContent side="right">Save changes</TooltipContent>
+</Tooltip>
+```
+
+`align` defaults to `"center"`. Use `align="start"` or `align="end"` to fine-tune alignment along the cross axis.
+
+---
+
+## 5. Common mistakes
+
+### Mistake 1 — Passing tooltip text via a `content` prop instead of `TooltipContent` children
+
+```tsx
+// ❌ Wrong — content prop is a Tractor API; DS ignores it silently
+<Tooltip content="Helpful hint">
+  <TooltipTrigger>Help</TooltipTrigger>
+</Tooltip>
+
+// ✅ Correct — tooltip text is children of TooltipContent
+<Tooltip>
+  <TooltipTrigger>Help</TooltipTrigger>
+  <TooltipContent>Helpful hint</TooltipContent>
+</Tooltip>
+```
+
+DS `Tooltip` is a Base UI compound — the tooltip label lives in `TooltipContent`, not on the root. The `content` prop is silently discarded and no tooltip is shown.
+
+Source: `packages/ds/src/components/tooltip.tsx`
+
+### Mistake 2 — Using `placement` instead of `side` on `TooltipContent`
+
+```tsx
+// ❌ Wrong — placement is the Tractor/Radix prop name; DS ignores it
+<TooltipContent placement="bottom">Helpful hint</TooltipContent>
+
+// ✅ Correct — use side (and optionally align) on TooltipContent
+<TooltipContent side="bottom" align="start">Helpful hint</TooltipContent>
+```
+
+`TooltipContent` exposes `side`, `sideOffset`, `align`, and `alignOffset` (picked from `TooltipPrimitive.Positioner.Props`). `placement` is not forwarded and the tooltip will render at the default `side="top"` position.
+
+Source: `packages/ds/src/components/tooltip.tsx`
+
+### Mistake 3 — Omitting `TooltipProvider` or using `delayDuration` instead of `delay`
+
+```tsx
+// ❌ Wrong — no provider mounted; all tooltips will fail to open
+<App />
+
+// ❌ Wrong — delayDuration is the Radix prop; Base UI ignores it
+<TooltipProvider delayDuration={300}>
+  <App />
+</TooltipProvider>
+
+// ✅ Correct — mount once with the Base UI prop name
+<TooltipProvider delay={0}>
+  <App />
+</TooltipProvider>
+```
+
+`TooltipProvider` is required for all DS tooltips (Base UI mandates a Provider context). The prop is `delay` (milliseconds), not `delayDuration`. Omitting the provider causes tooltips to never open; using `delayDuration` silently falls back to Base UI's internal default.
+
+Source: `packages/ds/src/components/tooltip.tsx`
+
+### Mistake 4 — Missing `aria-label` on an icon-only trigger
+
+```tsx
+// ❌ Wrong — no accessible name; tooltip text is not the control's name
+<TooltipTrigger render={<Button variant="ghost" size="icon" />}>
+  <Info className="size-4" />
+</TooltipTrigger>
+
+// ✅ Correct — aria-label names the control independently of the tooltip
+<TooltipTrigger render={<Button variant="ghost" size="icon" aria-label="More information" />}>
+  <Info className="size-4" />
+</TooltipTrigger>
+```
+
+The tooltip text shown in `TooltipContent` is a supplemental hint, not the accessible name of the trigger element. Screen readers announce the control by its label, not by the tooltip. Icon-only buttons must carry an explicit `aria-label`.
+
+Source: `packages/ds/src/components/tooltip.tsx`