@aircall/ds 0.13.0 → 0.15.0

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

@@ -0,0 +1,248 @@
+---
+name: aircall-ds/migrate-tractor/gauge
+description: >
+  Migrate Tractor Gauge (segmented audio level meter) to @aircall/ds Gauge and
+  optionally replace custom audio plumbing with the useAudioGauge hook. Load when
+  a file imports Gauge 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/gauge.md"
+---
+
+This skill builds on aircall-ds/migrate-tractor.
+
+## 1. Component mapping
+
+| Tractor part | @aircall/ds part | Notes |
+| --- | --- | --- |
+| `Gauge` | `Gauge` | Same name; value scale and segment count changed — see below |
+| `gauges` prop | _(removed)_ | DS gauge is always 8 segments; prop is gone |
+| Custom audio plumbing | `useAudioGauge` | Optional drop-in hook for mic-level meters |
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```ts
+// line 223
+export { Gauge } from './components/gauge';
+// line 358
+export * from './hooks/use-audio-gauge'; // exports: useAudioGauge, UseAudioGaugeOptions, UseAudioGaugeResult
+```
+
+Public names usable as `import { … } from '@aircall/ds'`: `Gauge`, `useAudioGauge`.
+
+## 3. Imports
+
+**Before (Tractor):**
+```tsx
+import { Gauge } from '@aircall/tractor';
+```
+
+**After (DS):**
+```tsx
+import { Gauge } from '@aircall/ds';
+// When using the built-in mic hook:
+import { Gauge, useAudioGauge } from '@aircall/ds';
+```
+
+## 4. Prop changes
+
+| Tractor prop | DS prop | Action |
+| --- | --- | --- |
+| `value: number` | `value: number` | Rescale to 0–8 range (see §5) |
+| `gauges?: number` | _(removed)_ | Delete the prop — DS always renders 8 segments |
+
+The DS `Gauge` also accepts all standard `div` props (`className`, `aria-label`, etc.) except `children`.
+
+## 5. Value scale
+
+Tractor's `value` mapped directly to "this many segments filled" out of a configurable `gauges` count. The DS `Gauge` fixes the segment count at 8 and clamps `value` to `[0, 8]`.
+
+If your code was computing a raw segment count from a `[0, 1]` level signal, multiply by 8 instead:
+
+```tsx
+// Before — mapped to 16 segments with gauges=16
+const value = Math.trunc(level * 16);
+<Gauge value={value} />
+
+// After — DS gauge is always 8 segments; apply ×2 gain to preserve speech sensitivity
+const value = Math.round(level * 8 * 2);
+<Gauge value={value} />
+```
+
+The `× 2` gain (speech calibration) matches the behavior users see today: typical speech reaches ~50% of the mic's digital range, so a pure `× 8` mapping would only nudge 1–2 segments during normal conversation. With `× 2`, loud speech saturates the meter.
+
+## 6. Visual falloff (automatic)
+
+The DS gauge adds a soft leading-edge falloff to mimic an analog meter feel:
+
+- **Head segment** (topmost filled): 35% opacity
+- **Trailing segment** (one below head): 65% opacity
+- **All other filled segments**: 100% opacity
+- When `value === 8` all segments are fully filled — no falloff
+
+This is automatic and not opt-out. No prop is needed or available.
+
+## 7. `useAudioGauge` hook (optional replacement for custom audio plumbing)
+
+When the component owns its own microphone connection, replace the custom `getUserMedia` + analyser pipeline with the DS hook. It returns `value` already calibrated to the 0–8 range.
+
+```tsx
+import { Gauge, useAudioGauge } from '@aircall/ds';
+
+function MicLevel() {
+  const { value, error } = useAudioGauge();
+  return (
+    <>
+      <Gauge value={value} />
+      {error && <p>Microphone unavailable: {error.message}</p>}
+    </>
+  );
+}
+```
+
+Hook options (all optional):
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `intervalMs` | `16` | Polling interval (~60 Hz) |
+| `fftSize` | `32` | `AnalyserNode.fftSize` — power of 2 in [32, 32768] |
+| `smoothing` | `0.3` | `AnalyserNode.smoothingTimeConstant` (0–1; higher = slower) |
+| `gain` | `2` | Multiplier on the natural 0–8 mapping; `1` = pure linear |
+
+If the component receives a `MediaStream` from outside (e.g. from a shared `useAudioInputVolume` hook), keep that hook and only rescale the value — do not replace it with `useAudioGauge`.
+
+## 8. Accessibility
+
+The DS gauge renders `role="meter"` with `aria-valuenow`, `aria-valuemin={0}`, and `aria-valuemax={8}` automatically on the root element. No extra wiring needed — Tractor's gauge had no accessibility attributes.
+
+## 9. Styling
+
+Pass Tailwind utilities via `className` for layout constraints (e.g. `className="max-w-64"`). The segment colors come from DS tokens (`bg-muted` for empty, `bg-primary` for filled) and are not configurable per-segment.
+
+## 10. Before / After examples
+
+### 10a. Gauge driven by a custom audio hook
+
+**Before (Tractor):**
+```tsx
+import { Gauge } from '@aircall/tractor';
+import { useAudioInputVolume } from '@/utils/audio/useAudioInputVolume';
+
+export const InputGauge = () => {
+  const level = useAudioInputVolume();
+  const value = Math.trunc(level * 16);
+  return <Gauge value={value} />;
+};
+```
+
+**After (DS — keep the custom hook, fix the scale):**
+```tsx
+import { Gauge } from '@aircall/ds';
+import { useAudioInputVolume } from '@/utils/audio/useAudioInputVolume';
+
+export const InputGauge = () => {
+  const level = useAudioInputVolume();
+  // 8 segments × 2 speech-calibration gain = same perceived sensitivity as before
+  const value = Math.round(level * 8 * 2);
+  return <Gauge value={value} />;
+};
+```
+
+### 10b. Gauge with a fixed `gauges` count removed
+
+**Before (Tractor):**
+```tsx
+import { Gauge } from '@aircall/tractor';
+
+export const SignalStrength = ({ level }: { level: number }) => (
+  <Gauge value={Math.trunc(level * 5)} gauges={5} />
+);
+```
+
+**After (DS — remove `gauges`, rescale to 8):**
+```tsx
+import { Gauge } from '@aircall/ds';
+
+export const SignalStrength = ({ level }: { level: number }) => (
+  <Gauge value={Math.round(level * 8)} />
+);
+```
+
+### 10c. Replacing custom audio plumbing with `useAudioGauge`
+
+**Before (Tractor):**
+```tsx
+import { Gauge } from '@aircall/tractor';
+import { useAudioInputVolume } from '@/utils/audio/useAudioInputVolume';
+
+export const InputGauge = () => {
+  const level = useAudioInputVolume();
+  const value = Math.trunc(level * 16);
+  return <Gauge value={value} />;
+};
+```
+
+**After (DS — use the built-in hook directly):**
+```tsx
+import { Gauge, useAudioGauge } from '@aircall/ds';
+
+export const InputGauge = () => {
+  const { value } = useAudioGauge();
+  return <Gauge value={value} />;
+};
+```
+
+## 11. Common mistakes
+
+### Mistake 1: Keeping the old value scale without rescaling
+
+```tsx
+// WRONG — multiplying by 16 overfills the DS gauge; values past 8 are clamped to 8
+const value = Math.trunc(level * 16);
+<Gauge value={value} />
+
+// CORRECT — DS gauge range is 0–8; multiply by 8 (×2 for speech calibration)
+const value = Math.round(level * 8 * 2);
+<Gauge value={value} />
+```
+
+The DS `Gauge` clamps `value` to `[0, 8]` internally. Passing `16` always renders a fully saturated meter — the level meter appears stuck at maximum regardless of the actual mic level.
+
+Source: `packages/ds/src/components/gauge.tsx` — `Math.max(0, Math.min(value, GAUGES))` where `GAUGES = 8`.
+
+---
+
+### Mistake 2: Passing the `gauges` prop
+
+```tsx
+// WRONG — DS Gauge has no `gauges` prop; the value is silently spread as a DOM attribute
+<Gauge value={4} gauges={8} />
+
+// CORRECT — remove the prop entirely; DS always renders 8 segments
+<Gauge value={4} />
+```
+
+`gauges` is not part of `GaugeProps`. Because `Gauge` spreads remaining props onto the root `<div>`, `gauges={8}` becomes a non-standard HTML attribute in the DOM, triggering a React warning and potentially causing test failures.
+
+Source: `packages/ds/src/components/gauge.tsx` — `GaugeProps` extends `Omit<React.ComponentProps<'div'>, 'children'>` with only `value` added; no `gauges` field.
+
+---
+
+### Mistake 3: Expecting to opt out of the leading-edge falloff
+
+```tsx
+// WRONG — there is no prop to disable falloff; this prop is silently ignored
+<Gauge value={5} disableFalloff />
+
+// CORRECT — the falloff is automatic and not configurable; no prop is needed
+<Gauge value={5} />
+```
+
+The head/trailing opacity is applied unconditionally via data-attribute CSS (`data-[state=head]:opacity-35`, `data-[state=trailing]:opacity-65`). There is no prop to disable it — accept the falloff or style the segments via a custom `className` on the root only.
+
+Source: `packages/ds/src/components/gauge.tsx` — `getSegmentState` always returns `'head'` / `'trailing'` states; no bypass path exists.

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

@@ -0,0 +1,261 @@
+---
+name: aircall-ds/migrate-tractor/input
+description: >
+  Migrate Tractor TextFieldInput and PasswordInput to @aircall/ds Input, InputGroup,
+  InputGroupAddon, InputGroupButton, and InputGroupInput. Load when a file imports
+  TextFieldInput, PasswordInput, or InputGroup 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/input.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 input-specific steps below.
+
+## 1. Component mapping
+
+| Tractor component | DS replacement | Notes |
+| --- | --- | --- |
+| `<TextFieldInput>` | `<Input>` | Drop-in for plain text inputs |
+| `<PasswordInput>` | `<InputGroup>` composition | No turn-key password component in DS — compose manually |
+| Tractor input with prefix/suffix icon | `<InputGroup>` composition | Use `InputGroupAddon` for decorations |
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Input,
+InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput,
+InputGroupText, InputGroupTextarea
+```
+
+All names used in the Before/After sections below exist in the published public API.
+
+## 3. Imports
+
+**Plain input:**
+```tsx
+import { Input } from '@aircall/ds';
+```
+
+**InputGroup composition (password, prefix/suffix):**
+```tsx
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+} from '@aircall/ds';
+import { VisibilityOffFill, VisibilityOnFill } from '@aircall/react-icons';
+```
+
+Never import icons from `lucide-react` directly — always use `@aircall/react-icons`.
+
+## 4. Prop renames (TextFieldInput → Input)
+
+| Tractor prop | DS prop | Notes |
+| --- | --- | --- |
+| `size="regular"` / `size="small"` | _(removed)_ | DS `Input` is always 40px; drop the prop entirely |
+| `validationStatus="error"` | `aria-invalid={true}` | DS reads ARIA attributes for error styling |
+| `value` | `value` | Unchanged |
+| `onChange` | `onChange` | Unchanged |
+| `placeholder` | `placeholder` | Unchanged |
+| `type` | `type` | Unchanged |
+| `disabled` | `disabled` | Unchanged |
+| `readOnly` | `readOnly` | Unchanged |
+| `required` | `required` | Unchanged |
+| `autoFocus` | `autoFocus` | Unchanged |
+
+## 5. Before / After examples
+
+### 5a. Plain text input
+
+**Before (Tractor):**
+```tsx
+import { TextFieldInput } from '@aircall/tractor';
+
+<TextFieldInput
+  type="email"
+  placeholder="Enter email"
+  value={value}
+  onChange={onChange}
+  validationStatus="error"
+  size="regular"
+  required
+/>
+```
+
+**After (DS):**
+```tsx
+import { Input } from '@aircall/ds';
+
+<Input
+  type="email"
+  placeholder="Enter email"
+  value={value}
+  onChange={onChange}
+  aria-invalid={true}
+  required
+/>
+```
+
+> The `size` prop is dropped — DS `Input` is always 40px. The `validationStatus="error"` prop becomes `aria-invalid={true}`; DS picks up the red-border error styling from the ARIA attribute automatically.
+
+### 5b. PasswordInput → InputGroup composition
+
+Tractor's `PasswordInput` shipped a built-in eye-toggle button. DS has no turn-key password input; compose one with `InputGroup`, `InputGroupInput`, `InputGroupAddon`, and `InputGroupButton`.
+
+**Before (Tractor):**
+```tsx
+import { PasswordInput } from '@aircall/tractor';
+
+<PasswordInput
+  id="password"
+  value={password}
+  onChange={onChange}
+  placeholder="Enter password"
+/>
+```
+
+**After (DS):**
+```tsx
+import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput } from '@aircall/ds';
+import { VisibilityOffFill, VisibilityOnFill } from '@aircall/react-icons';
+import { useState } from 'react';
+
+function PasswordInput({ id, ...props }: React.ComponentProps<typeof InputGroupInput>) {
+  const [shown, setShown] = useState(false);
+
+  return (
+    <InputGroup>
+      <InputGroupInput
+        id={id}
+        type={shown ? 'text' : 'password'}
+        {...props}
+      />
+      <InputGroupAddon align="inline-end">
+        <InputGroupButton
+          size="icon-xs"
+          onClick={() => setShown(s => !s)}
+          aria-label={shown ? 'Hide password' : 'Show password'}
+        >
+          {shown ? <VisibilityOffFill className="size-4" /> : <VisibilityOnFill className="size-4" />}
+        </InputGroupButton>
+      </InputGroupAddon>
+    </InputGroup>
+  );
+}
+```
+
+> `InputGroupInput` is the borderless `Input` variant — the border lives on the surrounding `InputGroup`, so there is no double frame.
+
+### 5c. Input with a prefix icon (search, currency, etc.)
+
+**Before (Tractor):**
+```tsx
+import { TextFieldInput } from '@aircall/tractor';
+import { SearchOutline } from '@aircall/react-icons';
+
+<div style={{ position: 'relative' }}>
+  <SearchOutline style={{ position: 'absolute', left: 8, top: 12 }} />
+  <TextFieldInput placeholder="Search…" style={{ paddingLeft: 28 }} />
+</div>
+```
+
+**After (DS):**
+```tsx
+import { InputGroup, InputGroupAddon, InputGroupInput } from '@aircall/ds';
+import { SearchOutline } from '@aircall/react-icons';
+
+<InputGroup>
+  <InputGroupAddon align="inline-start">
+    <SearchOutline className="size-4 text-muted-foreground" />
+  </InputGroupAddon>
+  <InputGroupInput placeholder="Search…" />
+</InputGroup>
+```
+
+> No manual positioning or padding overrides needed — `InputGroupAddon` with `align="inline-start"` shifts the inner input's left padding automatically via a CSS `:has()` rule on the group.
+
+## 6. Common Mistakes
+
+### Mistake 1 — Keeping `validationStatus="error"` instead of `aria-invalid`
+
+```tsx
+// Wrong — DS Input has no validationStatus prop; the red border never appears
+<Input value={value} onChange={onChange} validationStatus="error" />
+
+// Correct — error styling is driven by the ARIA attribute
+<Input value={value} onChange={onChange} aria-invalid={true} />
+```
+
+DS `Input` does not accept a `validationStatus` prop — it is silently ignored. The error border and focus-ring color are controlled by `aria-invalid`; without it the field looks visually valid even when it is not.
+
+Source: `packages/ds/src/components/input.tsx` — `inputVariants` keys on `aria-invalid` via `aria-invalid:border-destructive`.
+
+---
+
+### Mistake 2 — Using `<Input>` inside `<InputGroup>` instead of `<InputGroupInput>`
+
+```tsx
+// Wrong — produces a double border: one from Input, one from InputGroup
+<InputGroup>
+  <Input type="password" placeholder="Enter password" />
+  <InputGroupAddon align="inline-end">…</InputGroupAddon>
+</InputGroup>
+
+// Correct — InputGroupInput strips its own border so the group border shows once
+<InputGroup>
+  <InputGroupInput type="password" placeholder="Enter password" />
+  <InputGroupAddon align="inline-end">…</InputGroupAddon>
+</InputGroup>
+```
+
+`InputGroupInput` renders a borderless, shadow-free, background-transparent `Input` (`border-0 shadow-none bg-transparent`). Using the plain `Input` inside an `InputGroup` causes a visible double frame because the regular `Input` keeps its own `border-input` border on top of the group's border.
+
+Source: `packages/ds/src/components/input-group.tsx` — `InputGroupInput` applies `border-0 shadow-none bg-transparent` via `cn`.
+
+---
+
+### Mistake 3 — Dropping `size` and forgetting to remove it when it's passed as a variable
+
+```tsx
+// Wrong — a `size` prop on DS Input is passed to the underlying <input> element
+// and renders as an HTML attribute that controls the visible character width
+<Input size={fieldSize} value={value} onChange={onChange} />
+
+// Correct — remove the size prop entirely; DS Input is always 40px
+<Input value={value} onChange={onChange} />
+```
+
+DS `Input` extends `React.ComponentProps<'input'>`, so an unrecognized `size` prop flows through to the DOM `<input size="...">` attribute, which controls the visible character width in some browsers — not a style variant. Drop any dynamic `size` variable inherited from Tractor code.
+
+Source: `packages/ds/src/components/input.tsx` — `Input` spreads `...props` onto `<input>` with no `size` interception.
+
+---
+
+### Mistake 4 — Placing a decorative icon directly inside `<InputGroup>` instead of inside `<InputGroupAddon>`
+
+```tsx
+// Wrong — a bare icon as a direct child of InputGroup receives no positioning,
+// padding, or cursor-text click-to-focus behavior
+<InputGroup>
+  <SearchOutline className="size-4" />
+  <InputGroupInput placeholder="Search…" />
+</InputGroup>
+
+// Correct — wrap the icon in InputGroupAddon with the correct align value
+<InputGroup>
+  <InputGroupAddon align="inline-start">
+    <SearchOutline className="size-4 text-muted-foreground" />
+  </InputGroupAddon>
+  <InputGroupInput placeholder="Search…" />
+</InputGroup>
+```
+
+`InputGroup` is a flex container that relies on `data-align` set by `InputGroupAddon` to apply the correct inner padding to the sibling `InputGroupInput` via a CSS `:has()` rule. A bare icon child is not an `InputGroupAddon` and sets no `data-align`, so the input's padding is not adjusted and the icon overlaps the text.
+
+Source: `packages/ds/src/components/input-group.tsx` — `has-[>[data-align=inline-start]]:[&>input]:pl-2` depends on `data-align` from `InputGroupAddon`.