@aircall/blocks 0.16.0 → 0.18.0

package/skills/aircall-blocks/migrate-dashboard/form-wizard/SKILL.md

@@ -7,7 +7,6 @@ description: >
   FormWizard, useFormWizard, or FormField from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.5.1"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard
@@ -247,6 +246,46 @@ spread the control bundle onto the matching DS primitive.
 | combobox (single) | `FormComboboxField` | switch | `FormSwitchField` |
 | combobox (multi) | `FormMultiComboboxField` | number | `FormNumericField` |
 | textarea | `FormTextareaField` | slider | `FormSliderField` |
+| toggle group | `FormToggleGroupField` | | |
+
+### Building a wrapper for an unlisted primitive (`FormFieldBase`)
+
+For a DS primitive without a shipped `Form*Field`, build one on `FormFieldBase` — it owns the field binding + the shared `Field`/`Label`/`Description`/`Error` shell; you supply a `buildControl` that maps the typed field to the control bundle. This is the shape every shipped wrapper follows (here re-creating `FormSwitchField`, which already ships — copy the pattern for a genuinely new primitive):
+
+```tsx
+import { FormFieldBase, type BoundForm, type FormFieldValidators, type TypedField } from '@aircall/blocks';
+import { Switch } from '@aircall/ds';
+import type { DeepKeysOfType } from '@tanstack/react-form';
+
+type SwitchControl = {
+  switchProps: { checked: boolean; onCheckedChange: (checked: boolean) => void; onBlur: () => void };
+};
+
+function switchControl(field: TypedField<boolean>): SwitchControl {
+  return {
+    switchProps: {
+      checked: field.state.value,
+      onCheckedChange: checked => field.handleChange(checked),
+      onBlur: field.handleBlur,
+    },
+  };
+}
+
+function FormSwitchField<
+  TForm extends BoundForm,
+  TName extends DeepKeysOfType<TForm['state']['values'], boolean> // only boolean fields
+>(props: {
+  form: TForm;
+  name: TName;
+  label: string;
+  validators?: FormFieldValidators<TForm['state']['values'], TName>;
+  children: (field: TypedField<boolean>, control: SwitchControl) => React.ReactNode;
+}) {
+  return <FormFieldBase<boolean, SwitchControl> {...props} buildControl={switchControl} />;
+}
+```
+
+`DeepKeysOfType<…, boolean>` restricts `name` to fields whose value type matches the control (here `boolean`), so the form stays type-safe.
 
 ## Multi-step gotchas
 

package/skills/aircall-blocks/migrate-dashboard/info-popup/SKILL.md

@@ -6,7 +6,6 @@ description: >
   or InfoPopupContent from @dashboard/library or from the local shared info-popup.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.6.0"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard

package/skills/aircall-blocks/migrate-dashboard/layout/SKILL.md

@@ -6,7 +6,6 @@ description: >
   Load when a file imports GridLayout, GridItem, or Gap from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.5.1"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard

package/skills/aircall-blocks/migrate-dashboard/list/SKILL.md

@@ -7,7 +7,6 @@ description: >
   or ListItemActions from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.5.1"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard

package/skills/aircall-blocks/migrate-dashboard/loading/SKILL.md

@@ -6,7 +6,6 @@ description: >
   file imports Loading, Loader, or Spinner from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.5.1"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard

package/skills/aircall-blocks/migrate-dashboard/page-header/SKILL.md

@@ -9,7 +9,6 @@ description: >
   imports PageHeader or PageHeaderLink from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.5.1"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard

package/skills/aircall-blocks/migrate-dashboard/setting-card/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: aircall-blocks/migrate-dashboard/setting-card
+description: >
+  Migrate @dashboard/library Paper and PaperForm (settings-page surfaces) to the
+  @aircall/blocks SettingCard family (SettingCard, SettingCardHeader, SettingCardTitle,
+  SettingCardDescription, SettingCardAction, SettingCardContent) plus useForm + CardSaveBar
+  for the save bar. Load when a file imports Paper or PaperForm from @dashboard/library and
+  the surface is a settings section (title / description / optional toggle or action /
+  optional save bar). The errorBoundary is handled OUTSIDE the card — it does not migrate.
+type: sub-skill
+library: aircall-blocks
+requires:
+  - aircall-blocks/setup
+  - aircall-blocks/migrate-dashboard
+sources:
+  - "aircall/hydra:packages/blocks/src/components/setting-card.tsx"
+  - "aircall/hydra:packages/blocks/src/components/card-save-bar.tsx"
+---
+
+This skill builds on aircall-blocks/migrate-dashboard.
+
+`Paper` / `PaperForm` are the `@dashboard/library` settings-page surfaces (title, subtitle,
+optional header action, content, optional save-bar footer). Their target is **`SettingCard`**
+(`@aircall/blocks`) — a thin composition over the DS `Card` that adds the settings level
+backgrounds and the level-aware title. For a **non-settings** card (a tile or generic
+container with no title/toggle semantics) use the raw `Card` primitives instead — load
+`@aircall/blocks#aircall-blocks/migrate-dashboard/card`.
+
+## 1. Component mapping
+
+| @dashboard/library | @aircall/blocks / @aircall/ds |
+| --- | --- |
+| `Paper` (root surface) | `SettingCard` |
+| `Paper` `title` prop | `SettingCardTitle` inside `SettingCardHeader` |
+| `Paper` `subtitle` prop | `SettingCardDescription` inside `SettingCardHeader` |
+| `Paper` `titleSide` prop | `SettingCardAction` inside `SettingCardHeader` |
+| `Paper` `children` (body) | `SettingCardContent` |
+| `Paper` `footer` (save/discard bar) | `useForm` + `CardSaveBar` (form on the outer level) |
+| `Paper` `footer` (generic) | plain children after `SettingCardContent`, or a DS `CardFooter` |
+| `Paper` `banner` prop | inline DS `Banner` before `SettingCardHeader` |
+| `Paper` `disabled` / `disabledText` | app-level — dim the card + render a lock label; `SettingCard` has no `disabled` prop |
+| `Paper` `fluid` prop | content is already full-width — drop it |
+| `Paper` `errorBoundary` prop | **stays in the app, OUTSIDE `SettingCard`** — see §3. Does NOT migrate. |
+| `Paper` `BoxProps` spread | drop — `className` for genuine one-offs only |
+| `PaperForm` (form + save bar) | `<form>` (outer) + `useForm` + `SettingCard` + `CardSaveBar` |
+| `PaperForm` `formProps` (`react-final-form`) | `useForm` (TanStack Form) — `defaultValues`, `onSubmit: async ({ value })` |
+| `PaperForm` `getErrorMessage` / `submitError` | catch in `onSubmit`, store in state, render an `Alert` above the content |
+| `PaperForm` `shouldBlockNavigation` | app-level (navigation blocker) — not part of blocks |
+| `PaperForm` `submitButtonText` / `undoButtonText` | `CardSaveBar` `submitLabel` / `resetLabel` |
+
+## 2. Imports
+
+```tsx
+// blocks — SettingCard family + TanStack Form + save bar
+import {
+  SettingCard,
+  SettingCardHeader,
+  SettingCardTitle,
+  SettingCardDescription,
+  SettingCardAction,
+  SettingCardContent,
+  useForm,
+  CardSaveBar
+} from '@aircall/blocks';
+
+// DS primitives used inside (Button, Switch, Alert, Banner, fields …)
+import { Button, Switch, Alert } from '@aircall/ds';
+```
+
+## 3. The errorBoundary stays OUTSIDE SettingCard
+
+`Paper` wrapped **its children** in `ScopedErrorBoundary` (plus an optional
+`ErrorContextProvider`) via the `errorBoundary` prop. Those are **app-level**
+`@dashboard/library` components — `ScopedErrorBoundary` is react-router-aware and reads
+`ErrorContext`; neither migrates to blocks/ds. `SettingCard` is a presentational layout
+primitive and deliberately has **no** `errorBoundary` prop.
+
+So keep the boundary in the app and wrap the **content** (not the whole card), matching
+`Paper`'s scope — a content crash still leaves the card title/description visible:
+
+```tsx
+import { ScopedErrorBoundary, ErrorContextProvider } from '@dashboard/library';
+
+<SettingCard>
+  <SettingCardHeader>
+    <SettingCardTitle>Redaction</SettingCardTitle>
+    <SettingCardDescription>Mask sensitive data in transcripts.</SettingCardDescription>
+  </SettingCardHeader>
+  <SettingCardContent>
+    {/* errorBoundary lives here, around the fallible content — NOT on SettingCard */}
+    <ScopedErrorBoundary message="Couldn't load redaction settings" showRetryButton>
+      <RedactionCategories />
+    </ScopedErrorBoundary>
+  </SettingCardContent>
+</SettingCard>
+```
+
+If `Paper`'s `errorBoundary` config carried a `context`, keep the
+`ErrorContextProvider` wrapper too (same nesting as `Paper` did — provider outside the
+boundary):
+
+```tsx
+<ErrorContextProvider value={ctx}>
+  <ScopedErrorBoundary {...cfg}>{content}</ScopedErrorBoundary>
+</ErrorContextProvider>
+```
+
+> If the whole section (header included) should be replaced on error, wrap the entire
+> `<SettingCard>` instead. Default to wrapping only the content — that is what `Paper` did.
+
+## 4. Before / After
+
+### 4a. Basic Paper — settings surface
+
+**Before:**
+```tsx
+import { Paper } from '@dashboard/library';
+
+<Paper title="General settings" subtitle="Manage your workspace preferences.">
+  <WorkspacePreferences />
+</Paper>
+```
+
+**After:**
+```tsx
+import { SettingCard, SettingCardHeader, SettingCardTitle, SettingCardDescription, SettingCardContent } from '@aircall/blocks';
+
+<SettingCard>
+  <SettingCardHeader>
+    <SettingCardTitle>General settings</SettingCardTitle>
+    <SettingCardDescription>Manage your workspace preferences.</SettingCardDescription>
+  </SettingCardHeader>
+  <SettingCardContent>
+    <WorkspacePreferences />
+  </SettingCardContent>
+</SettingCard>
+```
+
+- `title` → `SettingCardTitle`, `subtitle` → `SettingCardDescription`, both inside `SettingCardHeader`.
+- Body → `SettingCardContent`. Drop the `BoxProps` spread — `SettingCard` owns the surface.
+
+### 4b. Paper with a header action / toggle (titleSide)
+
+**Before:**
+```tsx
+<Paper
+  title="Call recording"
+  subtitle="Record inbound and outbound calls."
+  titleSide={<Switch checked={enabled} onChange={setEnabled} />}
+>
+  {enabled && <RecordingOptions />}
+</Paper>
+```
+
+**After:**
+```tsx
+<SettingCard>
+  <SettingCardHeader>
+    <SettingCardTitle>Call recording</SettingCardTitle>
+    <SettingCardDescription>Record inbound and outbound calls.</SettingCardDescription>
+    <SettingCardAction>
+      <Switch checked={enabled} onCheckedChange={setEnabled} />
+    </SettingCardAction>
+  </SettingCardHeader>
+  {enabled && (
+    <SettingCardContent>
+      <RecordingOptions />
+    </SettingCardContent>
+  )}
+</SettingCard>
+```
+
+- `titleSide` → `SettingCardAction` (inside `SettingCardHeader`; the header grid pins it top-right).
+- DS `Switch` uses `onCheckedChange`, not tractor's `onChange`.
+- **Progressive disclosure is consumer-controlled**: render `SettingCardContent` only when the toggle is on (`{enabled && …}`). `SettingCard` has no internal toggle→content coupling, so gated data/fields never mount while off.
+
+### 4c. Nested settings (levels are automatic)
+
+A `SettingCard` rendered inside another card's `SettingCardContent` auto-detects **level 2**
+(white background + border, 16px medium title); the top card is **level 1** (muted,
+borderless, 18px bold). No prop needed. For a rare 3rd level, force `level={1}` on the
+deepest card to reuse the level-1 background (its title stays 16px medium automatically).
+
+### 4d. PaperForm — form with save/discard bar
+
+**Before:**
+```tsx
+import { PaperForm } from '@dashboard/library';
+
+<PaperForm
+  title="Profile"
+  subtitle="Update your display name."
+  formProps={{ initialValues: { name: '' }, onSubmit: async (values) => save(values) }}
+  submitButtonText="Save"
+  undoButtonText="Discard"
+>
+  {({ values }) => <input name="name" defaultValue={values.name} />}
+</PaperForm>
+```
+
+**After:**
+```tsx
+import { SettingCard, SettingCardHeader, SettingCardTitle, SettingCardDescription, SettingCardContent, useForm, FormInputField } from '@aircall/blocks';
+import { FieldGroup, Input } from '@aircall/ds';
+
+function ProfileForm() {
+  const form = useForm({
+    defaultValues: { name: '' },
+    onSubmit: async ({ value }) => { await save(value); }
+  });
+
+  return (
+    // Form on the OUTER level — SettingCard stays presentational.
+    <form onSubmit={e => { e.preventDefault(); void form.handleSubmit(); }}>
+      <SettingCard>
+        <SettingCardHeader>
+          <SettingCardTitle>Profile</SettingCardTitle>
+          <SettingCardDescription>Update your display name.</SettingCardDescription>
+        </SettingCardHeader>
+        <SettingCardContent>
+          <FieldGroup>
+            <FormInputField form={form} name="name" label="Display name">
+              {(_field, { inputProps }) => <Input {...inputProps} />}
+            </FormInputField>
+          </FieldGroup>
+        </SettingCardContent>
+        <form.AppForm>
+          <form.CardSaveBar submitLabel="Save" resetLabel="Discard" />
+        </form.AppForm>
+      </SettingCard>
+    </form>
+  );
+}
+```
+
+Key changes:
+- `react-final-form` `formProps` + render-prop → `useForm` from `@aircall/blocks` (TanStack Form): `defaultValues` (not `initialValues`), `onSubmit` receives `{ value }`.
+- Hand-wired inputs → `Form*Field` wrappers driven by the form (never per-field `useState`).
+- Put the `<form>` on the **outer level** (wrapping `SettingCard`), and drop **`form.CardSaveBar`** in as the last child of `SettingCard`. It reads `isDirty`/`canSubmit`/`isSubmitting` from context, slides in when dirty, and carries `data-slot="card-footer"` so the card auto-collapses its bottom padding and the bar sits flush. **No `className` is needed on any part** - the card's own layout (row gap + auto `pb-0`) handles both the clean and dirty states.
+- `submitButtonText`/`undoButtonText` → `CardSaveBar` `submitLabel`/`resetLabel`.
+
+**Submit error (`getErrorMessage` / `submitError`).** No built-in equivalent — catch in
+`onSubmit`, store it, and render an `Alert` above the content:
+
+```tsx
+const [submitError, setSubmitError] = useState<string | null>(null);
+const form = useForm({
+  defaultValues: { name: '' },
+  onSubmit: async ({ value }) => {
+    try { await save(value); setSubmitError(null); }
+    catch (e) { setSubmitError(getErrorMessage(e)); }
+  }
+});
+// In JSX, above the fields inside SettingCardContent:
+{submitError && <Alert variant="error">{submitError}</Alert>}
+```
+
+> DS `Alert`'s error variant is `error` (not tractor's `critical`). Full set: `default` / `info` / `success` / `warning` / `error`.

package/skills/aircall-blocks/migrate-dashboard/tile/SKILL.md

@@ -7,7 +7,6 @@ description: >
   Tile, TileHeader, or TileValue from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.5.1"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard

package/skills/aircall-blocks/migrate-dashboard/toggle-row/SKILL.md

@@ -5,7 +5,6 @@ description: >
   Load when a file imports ToggleRow from @dashboard/library.
 type: sub-skill
 library: aircall-blocks
-library_version: "0.6.0"
 requires:
   - aircall-blocks/setup
   - aircall-blocks/migrate-dashboard

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

@@ -9,7 +9,6 @@ description: >
   consumers where the host already loads DS globals.
 type: core
 library: aircall-blocks
-library_version: "0.5.1"
 requires:
   - aircall-ds/setup
 sources:
@@ -58,6 +57,28 @@ import '@aircall/ds/globals.css';
 import '@aircall/blocks/globals.css';
 ```
 
+#### Single-compilation via `theme.css` (recommended for DS + blocks)
+
+The two precompiled bundles above each re-emit the same Tailwind utilities into `@layer
+utilities`; at equal specificity the last-loaded bundle can clobber the other's responsive
+variants (e.g. blocks' plain `.text-base` beating DS's `md:text-sm` on `Textarea`), and **no
+import order fixes it**. To avoid this, import the directive-preserving `theme.css` artifacts
+(tokens + dark variant + reset + keyframes only — **no** Preflight, **no** utilities) and let a
+single Tailwind pass generate the utilities by `@source`-scanning the library dist:
+
+```css
+/* style.css */
+@import 'tailwindcss';                      /* consumer owns the single Preflight + engine */
+@import '@aircall/ds/theme.css';
+@import '@aircall/blocks/theme.css';
+@source '../node_modules/@aircall/ds/dist/index.js';
+@source '../node_modules/@aircall/blocks/dist/index.js';
+```
+
+Here the full `@import 'tailwindcss'` is **correct** (unlike the `globals.css` case) because
+`theme.css` ships no Preflight/utilities. `globals.css` still ships unchanged for precompiled-
+bundle consumers. Full rationale: `packages/ds/docs/single-compilation-theme-css.md`.
+
 ### Module-federation consumer (host already owns the Preflight)
 
 When your app is a remote loaded inside a host that already imports DS globals