@aircall/blocks/README.md

Aircall Blocks — higher-level UI compositions built on @aircall/ds

# @aircall/blocks

Higher-level UI compositions built on **`@aircall/ds`** — page shells (`DashboardPage` /
`DashboardStandalonePage`), the form layer (`useForm` + the `Form*Field` TanStack Form
wrappers), empty states, and more.

```bash
pnpm add @aircall/blocks @aircall/ds
```

Import the precompiled CSS once from your entry. `@aircall/blocks/globals.css` already
bundles the entire `@aircall/ds/globals.css` — do **not** import both or you duplicate all
of DS's compiled output (Preflight, theme tokens, all DS utilities):

```tsx
// ✅ Correct — blocks already includes DS
import '@aircall/blocks/globals.css';

// ❌ Wrong — duplicates all of DS's compiled output
// import '@aircall/ds/globals.css';
// import '@aircall/blocks/globals.css';
```

If you author your own Tailwind utility classes, use a CSS entry instead of a JS import:

```css
/* style.css */
@layer theme, base, components, utilities;
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);
@import '@aircall/blocks/globals.css';
@source "./src/**/*.{ts,tsx}";
```

For module-federation consumers (your app runs as a remote inside a host that already loads
DS/blocks globals), omit both globals imports entirely.

> Importing `@aircall/blocks` registers a `blocks` i18n namespace on `@aircall/ds`'s shared
> i18next instance. To make block strings follow the user's language, mount `DsI18nProvider`
> (from `@aircall/ds`) **under** your react-i18next provider, fed the active language. See
> the `@aircall/ds` README and the `aircall-ds/setup` skill for the full provider tree.

## For AI agents — migrating off `@dashboard/library`?

This package ships **[TanStack Intent](https://tanstack.com/intent) migration skills** in
its `skills/` directory (published in the npm tarball): `aircall-blocks/migrate-dashboard`
(+ per-area recipes) for moving `@dashboard/library` screens to `@aircall/blocks` /
`@aircall/ds`, plus `aircall-blocks/setup`. Enable them (one-time, same as `@aircall/ds`):

```bash
pnpm add @aircall/blocks@latest @aircall/ds@latest @aircall/react-icons@latest # react-icons >= 0.4.0
npx @tanstack/intent install   # writes the discovery block into CLAUDE.md / AGENTS.md
# allowlist in package.json: { "intent": { "skills": ["@aircall/ds", "@aircall/blocks"] } }
```

Then the agent loads guidance on demand:

```bash
npx @tanstack/intent load "@aircall/blocks#aircall-blocks/migrate-dashboard"
```

`aircall-blocks/setup` builds on `aircall-ds/setup`, so the DS providers, `globals.css`, and
jsdom test shims documented there apply here too.