@aircall/ds 0.14.0 → 0.15.0

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

@@ -0,0 +1,346 @@
+---
+name: aircall-ds/migrate-tractor/tree
+description: >
+  Migrate Tractor Tree and TreeSelect to the @aircall/ds DataTree (data-driven)
+  or Tree/TreeItem/TreeItemLabel primitives (full control). Load when a file
+  imports Tree or TreeSelect 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/tree.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 tree-specific steps below.
+
+## 1. Component mapping
+
+| Tractor component | DS replacement | When to use |
+| --- | --- | --- |
+| `<Tree nodes={[…]} />` | `<DataTree items={…} getKey={…} getLabel={…} />` | Default — keep your data shape, point accessors at it |
+| `<Tree nodes={[…]} />` | `<Tree>` + `<TreeItem>` + `<TreeItemLabel>` + `useTree` | Custom rows, drag-and-drop, search highlight, inline rename |
+| `<TreeSelect />` | `<DataTree>` inside a `<Popover>` | No turn-key equivalent — compose manually |
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+DataTree
+Tree, TreeItem, TreeItemLabel, TreeDragLine
+Popover, PopoverContent, PopoverTrigger
+Button
+```
+
+## 3. Imports
+
+```tsx
+// Data-driven usage (most cases)
+import { DataTree } from '@aircall/ds';
+
+// Primitive usage (full control)
+import { Tree, TreeItem, TreeItemLabel } from '@aircall/ds';
+
+// Icons — always from @aircall/react-icons, never lucide-react directly
+import { FolderIcon, FolderOpenIcon, FileIcon } from '@aircall/react-icons';
+```
+
+## 4. Prop mapping — Tractor `Tree` → DS `DataTree`
+
+| Tractor `Tree` prop | DS `DataTree` prop | Notes |
+| --- | --- | --- |
+| `nodes` (fixed shape `{ id, label, children }`) | `items` + `getKey` + `getLabel` + `getChildren` | Keep your own data shape; accessors replace the forced schema |
+| node `prefix` (leading icon) | `getIcon={(node, { isFolder, isExpanded }) => …}` | Icon gutter is reserved; iconless rows still align |
+| node `suffix` / `description` | Return JSX from `getLabel` | `getLabel` accepts `React.ReactNode`, not just a string |
+| `selectionMode` (`'none' \| 'single' \| 'multiple'`) | `selectionMode` | Same values |
+| `selectedKeys` | `selectedKeys` | Now typed `string[]` (not `K extends PrimitiveValue`) |
+| `defaultSelectedKeys` | `defaultSelectedKeys` | Same |
+| `onItemSelected: (key, allKeys) => void` | `onSelectionChange: (keys: string[]) => void` | Receives the **full** key set, not the toggled key |
+| `expandedKeys` | `expandedKeys` | Unchanged |
+| `defaultExpandedKeys` | `defaultExpandedKeys` | Unchanged |
+| `onExpandChange` | `onExpandedChange` | Renamed — note the `d` |
+| `bordered` / `readOnly` / `disabled` | No direct equivalent | Style via `className`; remove or omit |
+
+## 5. Selection behaviour changes
+
+- **`selectionMode="multiple"`** — renders a **tri-state checkbox** per row with parent↔child cascade. Checking a folder checks every descendant; unchecking one child flips the folder to indeterminate.
+- **`selectionMode="single"`** — highlights one row on click.
+- **`selectionMode="none"`** (default) — no selection; row click toggles expansion.
+
+`onSelectionChange` receives the **full** current key set every time, not just the key that changed. If you were using the first `(key, allKeys)` argument to identify the toggled item, switch to diffing the new set against your previous state.
+
+## 6. Before / After
+
+### 6a. Basic data-driven tree
+
+**Before (Tractor):**
+```tsx
+import { Tree } from '@aircall/tractor';
+
+const nodes = [
+  { id: 'eng', label: 'Engineering', children: [{ id: 'fe', label: 'Frontend' }] }
+];
+
+<Tree nodes={nodes} />
+```
+
+**After (DS):**
+```tsx
+import { DataTree } from '@aircall/ds';
+
+const items = [
+  { id: 'eng', label: 'Engineering', children: [{ id: 'fe', label: 'Frontend' }] }
+];
+
+<DataTree
+  items={items}
+  getKey={node => node.id}
+  getLabel={node => node.label}
+  getChildren={node => node.children}
+/>
+```
+
+### 6b. Icons and rich labels (`prefix` / `suffix` / `description`)
+
+**Before (Tractor):**
+```tsx
+import { Tree } from '@aircall/tractor';
+import { FolderIcon } from '@aircall/react-icons';
+
+const nodes = [
+  {
+    id: 'eng',
+    label: 'Engineering',
+    prefix: <FolderIcon />,
+    description: 'Main team',
+    children: [{ id: 'fe', label: 'Frontend' }]
+  }
+];
+
+<Tree nodes={nodes} />
+```
+
+**After (DS):**
+```tsx
+import { DataTree } from '@aircall/ds';
+import { FolderIcon, FolderOpenIcon, FileIcon } from '@aircall/react-icons';
+
+const items = [
+  { id: 'eng', label: 'Engineering', description: 'Main team', children: [{ id: 'fe', label: 'Frontend' }] }
+];
+
+<DataTree
+  items={items}
+  getKey={n => n.id}
+  getChildren={n => n.children}
+  getIcon={(n, { isFolder, isExpanded }) =>
+    isFolder ? (isExpanded ? <FolderOpenIcon /> : <FolderIcon />) : <FileIcon />
+  }
+  getLabel={n => (
+    <span className="flex flex-col">
+      <span>{n.label}</span>
+      {n.description ? (
+        <span className="text-xs text-muted-foreground">{n.description}</span>
+      ) : null}
+    </span>
+  )}
+/>
+```
+
+### 6c. Controlled selection and expansion
+
+**Before (Tractor):**
+```tsx
+import { Tree } from '@aircall/tractor';
+
+<Tree
+  nodes={nodes}
+  selectionMode="multiple"
+  selectedKeys={selected}
+  expandedKeys={expanded}
+  onItemSelected={(key, allKeys) => setSelected(allKeys)}
+  onExpandChange={keys => setExpanded(keys)}
+/>
+```
+
+**After (DS):**
+```tsx
+import { DataTree } from '@aircall/ds';
+
+<DataTree
+  items={items}
+  getKey={n => n.id}
+  getLabel={n => n.label}
+  getChildren={n => n.children}
+  selectionMode="multiple"
+  selectedKeys={selected}
+  expandedKeys={expanded}
+  onSelectionChange={keys => setSelected(keys)}
+  onExpandedChange={keys => setExpanded(keys)}
+/>
+```
+
+### 6d. Full-control primitives (custom rows, drag-and-drop)
+
+**Before (Tractor):**
+```tsx
+import { Tree } from '@aircall/tractor';
+
+<Tree nodes={nodes} />
+```
+
+**After (DS — primitives):**
+```tsx
+import { Tree, TreeItem, TreeItemLabel } from '@aircall/ds';
+import { useTree } from '@headless-tree/react';
+import { syncDataLoaderFeature, hotkeysCoreFeature } from '@headless-tree/core';
+
+const tree = useTree<Item>({
+  rootItemId: 'root',
+  dataLoader: {
+    getItem: id => itemMap[id],
+    getChildren: id => childIds[id] ?? []
+  },
+  features: [syncDataLoaderFeature, hotkeysCoreFeature]
+});
+
+<Tree indent={20} tree={tree}>
+  {tree.getItems().map(item => (
+    <TreeItem item={item} key={item.getId()}>
+      <TreeItemLabel />
+    </TreeItem>
+  ))}
+</Tree>
+```
+
+## 7. TreeSelect
+
+Tractor's `TreeSelect` has no turn-key DS equivalent. Compose `DataTree` inside a `Popover`:
+
+```tsx
+import { DataTree, Popover, PopoverContent, PopoverTrigger, Button } from '@aircall/ds';
+
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline">Select team…</Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-72 p-2">
+    <DataTree
+      items={items}
+      getKey={n => n.id}
+      getLabel={n => n.label}
+      getChildren={n => n.children}
+      selectionMode="single"
+      selectedKeys={selected}
+      onSelectionChange={keys => {
+        setSelected(keys);
+      }}
+    />
+  </PopoverContent>
+</Popover>
+```
+
+## 8. Common Mistakes
+
+### Mistake 1 — Using `onItemSelected` instead of `onSelectionChange`
+
+```tsx
+// Wrong — onItemSelected does not exist on DataTree
+<DataTree
+  items={items}
+  getKey={n => n.id}
+  getLabel={n => n.label}
+  onItemSelected={(key, allKeys) => setSelected(allKeys)}
+/>
+
+// Correct — onSelectionChange receives the full key set
+<DataTree
+  items={items}
+  getKey={n => n.id}
+  getLabel={n => n.label}
+  onSelectionChange={keys => setSelected(keys)}
+/>
+```
+
+Tractor's `onItemSelected` passed `(toggledKey, allKeys)` as two arguments. DS `onSelectionChange` passes the full current key set as a single `string[]`. Passing `onItemSelected` to `DataTree` passes an unknown prop that is silently ignored — the selection callback never fires.
+
+Source: `packages/ds/src/components/data-tree.tsx`
+
+---
+
+### Mistake 2 — Using `onExpandChange` instead of `onExpandedChange`
+
+```tsx
+// Wrong — onExpandChange (no 'd') is not a DataTree prop
+<DataTree
+  items={items}
+  getKey={n => n.id}
+  getLabel={n => n.label}
+  expandedKeys={expanded}
+  onExpandChange={keys => setExpanded(keys)}
+/>
+
+// Correct — onExpandedChange (with 'd')
+<DataTree
+  items={items}
+  getKey={n => n.id}
+  getLabel={n => n.label}
+  expandedKeys={expanded}
+  onExpandedChange={keys => setExpanded(keys)}
+/>
+```
+
+The Tractor callback was `onExpandChange`; DS renamed it to `onExpandedChange` to match the pattern of other controlled callbacks in the library. Passing the old name results in a silent no-op — the `expandedKeys` state is never updated.
+
+Source: `packages/ds/src/components/data-tree.tsx`
+
+---
+
+### Mistake 3 — Passing `nodes` instead of `items` + accessor props
+
+```tsx
+// Wrong — DataTree has no `nodes` prop
+<DataTree nodes={myNodes} />
+
+// Correct — pass items and accessor functions
+<DataTree
+  items={myNodes}
+  getKey={n => n.id}
+  getLabel={n => n.label}
+  getChildren={n => n.children}
+/>
+```
+
+Tractor forced callers to reshape their data into `{ id, label, children }`. `DataTree` accepts your data as-is via `items` and resolves identifiers and hierarchy through the `getKey` / `getLabel` / `getChildren` accessor functions. Passing `nodes` is an unknown prop — `DataTree` renders nothing because its required `items` prop is absent.
+
+Source: `packages/ds/src/components/data-tree.tsx`
+
+---
+
+### Mistake 4 — Placing `suffix`/`description` as node-level props instead of returning JSX from `getLabel`
+
+```tsx
+// Wrong — DataTree does not read suffix or description from node objects
+<DataTree
+  items={[{ id: '1', label: 'Frontend', suffix: <Badge>3</Badge> }]}
+  getKey={n => n.id}
+  getLabel={n => n.label}
+/>
+
+// Correct — embed rich content directly in getLabel's return value
+<DataTree
+  items={[{ id: '1', label: 'Frontend', badge: 3 }]}
+  getKey={n => n.id}
+  getLabel={n => (
+    <span className="flex items-center gap-2">
+      {n.label}
+      <Badge>{n.badge}</Badge>
+    </span>
+  )}
+/>
+```
+
+Tractor reserved `suffix` and `description` as fixed node-shape keys that the tree rendered for you. `DataTree`'s `getLabel` returns `React.ReactNode`, so all rich content goes there — the node object carries only your domain data, not presentation slots.
+
+Source: `packages/ds/src/components/data-tree.tsx`

package/skills/aircall-ds/setup/SKILL.md

@@ -0,0 +1,347 @@
+---
+name: aircall-ds/setup
+description: >
+  Set up @aircall/ds (and @aircall/blocks) in an app migrating off @aircall/tractor.
+  Load when wiring DS into a project for the first time: installing the package,
+  importing the precompiled globals.css, configuring Tailwind v4 / PostCSS,
+  mounting ThemeProvider / TooltipProvider / Toaster, and running DS and Tractor
+  side by side during a progressive migration.
+type: core
+library: aircall-ds
+library_version: "0.13.0"
+sources:
+  - "aircall/hydra:docs/migration-guides/tractor-to-ds/00-setup.md"
+  - "aircall/hydra:packages/ds/package.json"
+---
+
+# Setting up @aircall/ds
+
+Get the app to a state where DS and Tractor render side by side. The migration is
+progressive: each migrated screen ships independently while `@aircall/tractor` stays
+installed until the last Tractor import is gone.
+
+All imports use the top-level `from '@aircall/ds'` form — the only surface the
+published package exposes.
+
+## Setup
+
+Install the design system and icon packages (keep Tractor and icons for now):
+
+```bash
+pnpm add @aircall/ds @aircall/react-icons
+```
+
+> **Version floor — `@aircall/react-icons` must be `>= 0.4.0`** (the version `@aircall/ds`
+> is built against). `@aircall/ds` imports country-flag icons (`CountryFlag` → `FlagUs`,
+> `FlagFr`, …) from `@aircall/react-icons`, and the ds barrel pulls them eagerly — so an
+> older react-icons (≤ 0.3.0, which lacks those exports) makes the **ds bundle fail to
+> resolve at build time** (`FlagUs is not exported`), even in files that never use
+> `CountryFlag`. ds declares the peer loosely as `*`, so npm/pnpm won't warn — upgrade
+> explicitly: `pnpm add @aircall/react-icons@latest`.
+
+Import the **precompiled** DS bundle once from your JS/TS entry. It already contains
+the reset, tokens, and every utility the DS components use — import it directly, do
+not prepend `@import 'tailwindcss'` and do not add `@source` for the DS package:
+
+```tsx
+// main.tsx
+import '@aircall/ds/globals.css';
+import '@aircall/blocks/globals.css'; // only if you use @aircall/blocks compositions
+```
+
+DS has a set of root providers, all per-feature — none is mandatory. A first migration that
+swaps only a few components needs none of them and renders on the default light theme. Add
+each one only when you use the feature it backs. Keep `TractorProvider` mounted alongside
+whichever DS providers you add:
+
+```tsx
+import { I18nextProvider, useTranslation } from 'react-i18next';
+import {
+  ThemeProvider,
+  Toaster,
+  TooltipProvider,
+  DsI18nProvider,
+  NotificationQueueProvider,
+  NotificationSlot,
+} from '@aircall/ds';
+import { TractorProvider } from '@aircall/tractor';
+import { i18n } from './i18n'; // your app's react-i18next instance
+
+function App() {
+  return (
+    <I18nextProvider i18n={i18n}>
+      <Providers>{/* Router, queries, your tree */}</Providers>
+    </I18nextProvider>
+  );
+}
+
+// DsI18nProvider MUST sit *under* react-i18next and be fed the user's active language,
+// so DS (and @aircall/blocks) strings follow the same locale. Reading it via
+// useTranslation() keeps it reactive — it re-runs when the user switches language.
+function Providers({ children }: React.PropsWithChildren) {
+  const { i18n } = useTranslation();
+  return (
+    <DsI18nProvider language={i18n.language}>
+      <TractorProvider>
+        <ThemeProvider defaultTheme="light" storageKey="my-app-theme">
+          <TooltipProvider delay={0}>
+            <NotificationQueueProvider>
+              {children}
+              <NotificationSlot slot="page" />
+              <Toaster />
+            </NotificationQueueProvider>
+          </TooltipProvider>
+        </ThemeProvider>
+      </TractorProvider>
+    </DsI18nProvider>
+  );
+}
+```
+
+| Provider          | Required for                  | Notes |
+| ----------------- | ----------------------------- | ----- |
+| `DsI18nProvider`  | DS + blocks strings following the user's language | Props: `{ language?: string; children }`. Mount it **as a descendant of your react-i18next `I18nextProvider`** and pass the user's active language (`language={i18n.language}` via `useTranslation`), so DS tracks the same locale. The DS i18n singleton self-initializes at import (falls back to `navigator.language`, then `en`), so strings still render without it — the provider drives language *changes*. Mount **exactly one**, and use **either** `DsI18nProvider` **or** `syncDsLanguage(i18n)` (mirrors + follows an i18next instance; for non-React startup) — never both (they fight over the same singleton). |
+| `ThemeProvider`   | dark/light/system themes      | `storageKey` is the per-app localStorage key. Host-mounted extensions: skip it — it writes `data-theme` on `<html>` and fights the host's theme control. |
+| `TooltipProvider` | every `<Tooltip>` in the tree | Prop is `delay` (Base UI), default `0`. Optional — tooltips still open without it; it only supplies the shared open-delay / grouping. |
+| `Toaster`         | `toast()` calls               | Render once at the root. |
+| `NotificationQueueProvider` | the notification queue / banners | Props: `{ children }`. Wrap it above every `useNotification` / `useNotificationQueue` caller and every `NotificationSlot`. |
+| `NotificationSlot` | rendering queued notifications | Props: `{ slot: string; className? }`. Not a provider — the output sink; one per slot/area (`slot="page"` at the root). Must be a descendant of `NotificationQueueProvider` or it throws. |
+
+## Core Patterns
+
+### Author your own Tailwind classes alongside DS — required once you write any
+
+The precompiled `@aircall/ds/globals.css` contains **only the utilities DS's own components
+use** — not arbitrary Tailwind classes. Any utility *your* code authors that DS doesn't
+itself ship (e.g. `px-0`, a one-off `max-w-3xl`, a custom `gap`) produces **no CSS** unless
+you run your own Tailwind build — the class sits in your JSX, the element renders unstyled,
+and nothing errors. A Tractor → DS migration almost always authors such classes (the
+`migrate-tractor/styling` recipe converts `<Flex p={2}>` / xstyled props → Tailwind
+utilities), so this is effectively **required**, not optional.
+
+Set up Tailwind v4 for *your* sources and point `@source` at your files, not at DS:
+
+```bash
+pnpm add -D tailwindcss @tailwindcss/postcss
+```
+
+```js
+// postcss.config.mjs  (auto-detected by PostCSS bundlers: Vite, rsbuild/Rspack, Next, webpack…)
+export default { plugins: { '@tailwindcss/postcss': {} } };
+```
+
+```css
+/* style.css — imported once from your JS/TS entry */
+/* Import ONLY theme + utilities — NOT the full `@import 'tailwindcss'`, which would add a
+   SECOND Preflight on top of the one @aircall/ds already ships (see the Common Mistake). */
+@import 'tailwindcss/theme';
+@import 'tailwindcss/utilities';
+@import '@aircall/ds/globals.css';     /* DS bundle: the single Preflight + tokens + DS utilities */
+@import '@aircall/blocks/globals.css'; /* if you use @aircall/blocks */
+@source "src";                          /* scan YOUR code so its classes are generated */
+```
+
+DS **design-token** utilities (`text-muted-foreground`, `bg-card`, …) come from the
+precompiled DS bundle; your build adds only the **core** utilities (`px-0`, `max-w-2xl`,
+layout, spacing) DS doesn't ship. Splitting into `tailwindcss/theme` + `tailwindcss/utilities`
+(rather than the full `tailwindcss`) is what keeps the **single** Preflight — the theme gives
+your utilities their scale, `@source` scans your code, and no base reset is duplicated.
+
+### Peers you provide
+
+`@aircall/ds` ships its internal-only libraries (`react-day-picker`, `@tanstack/react-table`,
+`date-fns`, `embla-carousel-react`, `sonner`, …) as regular **dependencies** — they install
+automatically with ds; nothing to add. The only peers YOU must provide:
+
+- `react` / `react-dom` (`^18 || ^19`)
+- **`@aircall/react-icons` (>= 0.4.0)** — see the version-floor note above.
+- `@aircall/numbers` / `@aircall/hooks` (Aircall registry; `auto-install-peers` may fetch them).
+
+## Common Mistakes
+
+### HIGH — Full `@import 'tailwindcss'` on top of the DS bundle (duplicated Preflight)
+
+Wrong — the full import re-applies Tailwind's Preflight (base reset) on top of the one the
+DS bundle already ships:
+
+```css
+@import 'tailwindcss';                 /* ← also pulls in Preflight = a SECOND base reset */
+@import '@aircall/ds/globals.css';
+```
+
+Correct — **not authoring your own classes:** just import the self-contained bundle:
+
+```tsx
+import '@aircall/ds/globals.css';
+```
+
+Correct — **authoring your own classes** (the migration case): import only the theme +
+utilities layers, never the full `tailwindcss`:
+
+```css
+@import 'tailwindcss/theme';
+@import 'tailwindcss/utilities';
+@import '@aircall/ds/globals.css';
+@source "src";
+```
+
+`@aircall/ds/globals.css` is a precompiled Tailwind v4 bundle that already includes
+Preflight. The full `@import 'tailwindcss'` ALWAYS pulls Preflight in again — a duplicated
+base reset that flips `border-color` to `currentColor` (dark borders) and changes base
+padding/margins, breaking the DS styling in light **and** dark mode. The
+`theme` + `utilities` split generates your authored utilities with **no** second reset.
+
+Source: aircall/hydra:docs/migration-guides/tractor-to-ds/00-setup.md (§3)
+
+### HIGH — Using `delayDuration` on TooltipProvider
+
+Wrong:
+
+```tsx
+<TooltipProvider delayDuration={0}>
+```
+
+Correct:
+
+```tsx
+<TooltipProvider delay={0}>
+```
+
+DS tooltips are Base UI, not Radix — the prop is `delay`. `delayDuration` is silently ignored, so tooltips keep the default timing instead of the value you set.
+
+Source: aircall/hydra:docs/migration-guides/tractor-to-ds/00-setup.md (§4)
+
+### MEDIUM — Mounting ThemeProvider inside a host-mounted extension
+
+Wrong:
+
+```tsx
+// extension mounted inside the dashboard host
+<ThemeProvider defaultTheme="light" storageKey="ext-theme">
+```
+
+Correct:
+
+```tsx
+// no ThemeProvider — inherit the host's data-theme on <html>
+<TooltipProvider delay={0}>{children}</TooltipProvider>
+```
+
+`ThemeProvider` writes `data-theme` on `<html>`; inside a host dashboard it fights the host's own theme control, causing the extension to flip themes independently. DS reads the same `data-theme` the host sets.
+
+Source: aircall/hydra:docs/migration-guides/tractor-to-ds/00-setup.md (§4)
+
+### MEDIUM — Forgetting the DS reset is global during cohabitation
+
+Wrong: assuming DS styles only affect migrated screens.
+
+Correct: budget a one-time pass to fix small Tractor base-element breakage when DS first lands; keep both providers mounted until the last Tractor import is removed.
+
+`@aircall/ds/globals.css` carries a Tailwind v4 preflight reset applied to the whole document — it is not scoped — so introducing DS can shift the appearance of un-migrated Tractor UI. Fix breakage as it surfaces rather than sandboxing the reset.
+
+Source: aircall/hydra:docs/migration-guides/tractor-to-ds/00-setup.md (§5)
+
+### HIGH — Jest/jsdom: ESM transform + `userEvent` on DS components
+
+`@aircall/ds` ships ESM and uses Tailwind v4 named-group classes (`group/input-group`, `button.group`). Default Jest setups break two ways:
+
+Wrong: leaving Jest's defaults — `import { Button } from '@aircall/ds'` fails to parse (ESM), and `userEvent.click(...)` on DS components throws in jsdom (its `nwsapi` CSS engine cannot parse the named-group selectors).
+
+Correct:
+
+```js
+// jest.config.mjs
+transformIgnorePatterns: ['node_modules/(?!(?:@aircall/ds|@aircall/blocks)/)'],
+moduleNameMapper: { '^react-day-picker$': '<rootDir>/test/stub.js' } // stub optional peers you don't use
+```
+
+and prefer `fireEvent.*` over `userEvent.*` when interacting with DS components in jsdom.
+
+Source: aircall/hydra:packages/ds/package.json
+
+### HIGH — Opening a Base UI popup in jsdom crashes even with `fireEvent` — add a selector guard
+
+`fireEvent` over `userEvent` (above) is necessary but **not sufficient** for any DS
+component that opens a floating popup: `Combobox`, `Select`, `DropdownMenu`, `Popover`,
+`Tooltip`. The moment the popup opens, the test throws:
+
+```
+SyntaxError: 'div.group,,field >svg' is not a valid selector
+  at nwsapi … getComputedStyle (jsdom) ← @floating-ui/dom getOverflowAncestors ← Base UI useAnchorPositioning
+```
+
+Cause: on open, `@floating-ui/dom` calls `getComputedStyle()` to find the element's
+overflow ancestors; jsdom matches **every** stylesheet rule against the element, and for
+a DS Tailwind v4 `:has()` / `:is(:where())` rule `nwsapi` resolves the assertion via a
+nested `querySelector` whose mangled inner selector it rejects — and that `SyntaxError`
+escapes jsdom's own `matchesDontThrow`. Real browsers handle these selectors fine.
+
+Fix — guard `querySelector`/`querySelectorAll` in your Jest setup to swallow ONLY the
+"is not a valid selector" error (the unsupported `:has()` assertion becomes "no match"):
+
+```ts
+// jest setupFilesAfterEnv
+const isBadSelector = (e: unknown) =>
+  e instanceof Error && e.message.includes('is not a valid selector');
+const EMPTY = document.createElement('div').querySelectorAll('x-none');
+
+for (const proto of [Element.prototype, Document.prototype, DocumentFragment.prototype]) {
+  const qs = proto.querySelector;
+  const qsa = proto.querySelectorAll;
+  proto.querySelector = function (s: string) {
+    try { return qs.call(this, s); } catch (e) { if (isBadSelector(e)) return null; throw e; }
+  };
+  proto.querySelectorAll = function (s: string) {
+    try { return qsa.call(this, s); } catch (e) { if (isBadSelector(e)) return EMPTY; throw e; }
+  };
+}
+```
+
+One ~20-line shim unblocks every DS popup at once. Without it, any test that opens a
+combobox/select/menu silently fails with "Unable to find element" after the crash aborts
+the render.
+
+Source: aircall/hydra:packages/ds/package.json
+
+### HIGH — DS `Switch` (and Base UI toggles) won't flip via `click` in jsdom
+
+Wrong:
+
+```tsx
+fireEvent.click(screen.getByTestId('my-switch'));   // aria-checked never changes
+await userEvent.click(screen.getByTestId('my-switch')); // also no-op
+```
+
+Correct — fire on the hidden checkbox the Switch renders as a sibling:
+
+```tsx
+const root = screen.getByTestId('my-switch');
+const input = root.parentElement!.querySelector('input[type="checkbox"]');
+fireEvent.click(input!);   // toggles + fires onCheckedChange
+```
+
+DS `Switch` is a Base UI `<span role="switch">` whose `onClick` calls `preventDefault()`
+then re-dispatches a synthetic `PointerEvent('click')` to a visually-hidden sibling
+`<input type="checkbox">` — jsdom doesn't complete that re-dispatch, so the visible span
+never updates. The hidden input's `onChange` is what actually fires `onCheckedChange`, so
+drive it directly. Same applies to any Base UI control with a hidden form input.
+
+Source: aircall/hydra:packages/ds/src/components/switch.tsx
+
+### MEDIUM — Import `DataTable` column types from `@aircall/ds`, not `@tanstack/react-table`
+
+`@aircall/ds` ships the react-table runtime as its own dependency and **re-exports** the types you author (`ColumnDef`, `SortingState`, `RowSelectionState`, `OnChangeFn`). `@tanstack/react-table` is therefore not a direct dependency of your app, so importing from it won't resolve.
+
+Wrong:
+
+```tsx
+import type { ColumnDef } from '@tanstack/react-table'; // not in your node_modules
+```
+
+Correct:
+
+```tsx
+import { DataTable, type ColumnDef } from '@aircall/ds';
+```
+
+Source: aircall/hydra:packages/ds/src/index.ts