@aircall/blocks 0.6.0 → 0.7.0

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

@@ -0,0 +1,127 @@
+---
+name: aircall-blocks/setup
+description: >
+  Set up @aircall/blocks in an app already (or simultaneously) adopting @aircall/ds.
+  Load when wiring blocks compositions (DashboardPage, DashboardPageHeader,
+  DashboardSidebar, empty states, form fields) into a project: installing the
+  package, importing its precompiled globals.css after the DS bundle, and the DS
+  providers it relies on.
+type: core
+library: aircall-blocks
+library_version: "0.5.1"
+requires:
+  - aircall-ds/setup
+sources:
+  - "aircall/hydra:docs/migration-guides/tractor-to-ds/00-setup.md"
+  - "aircall/hydra:packages/blocks/package.json"
+---
+
+# Setting up @aircall/blocks
+
+This skill builds on aircall-ds/setup. Read it first: blocks compose `@aircall/ds`
+primitives and depend on DS being installed and its `globals.css` imported.
+
+## Setup
+
+Install blocks alongside DS:
+
+```bash
+pnpm add @aircall/blocks @aircall/ds @aircall/react-icons
+```
+
+Import the blocks bundle **after** the DS bundle from your JS/TS entry. It carries
+the page-layout grid and block-only tokens on top of DS:
+
+```tsx
+// main.tsx
+import '@aircall/ds/globals.css';
+import '@aircall/blocks/globals.css';
+```
+
+Blocks render under the same DS providers — there is no blocks-specific provider; mount the
+DS root providers from `aircall-ds/setup` as needed (`ThemeProvider` / `TooltipProvider` /
+`Toaster`). Two DS providers matter specifically once you use blocks:
+
+- **`DsI18nProvider`** (from `@aircall/ds`) — importing `@aircall/blocks` runs
+  `import './i18n/register'` at module load (`packages/blocks/src/index.ts`), which registers
+  a `blocks` namespace on DS's shared i18next instance. Block strings render localized off the
+  self-initialized DS singleton even without a provider; to make DS + blocks strings follow the
+  **user's** language (and track switches), mount `DsI18nProvider` **as a descendant of your
+  react-i18next `I18nextProvider`** and pass the active language (`language={i18n.language}`).
+  Use **either** `DsI18nProvider` **or** `syncDsLanguage(i18n)`, never both. See
+  `aircall-ds/setup` for the full provider tree and nesting order.
+- **`NotificationQueueProvider` + `NotificationSlot`** (from `@aircall/ds`) — needed only if
+  your block compositions surface notifications/banners: wrap `NotificationQueueProvider`
+  (props `{ children }`) above any notification caller, and render a `NotificationSlot
+  slot="page"` (props `{ slot: string; className? }`) inside it.
+
+Source: `packages/blocks/src/index.ts`; `@aircall/ds` `DsI18nProvider` / `NotificationQueueProvider`.
+
+## Core Patterns
+
+### Use a block composition
+
+```tsx
+import {
+  DashboardPageHeader,
+  DashboardPageHeaderTitle,
+} from '@aircall/blocks';
+
+function CampaignsHeader() {
+  return (
+    <DashboardPageHeader>
+      <DashboardPageHeaderTitle size="lg">Campaigns</DashboardPageHeaderTitle>
+    </DashboardPageHeader>
+  );
+}
+```
+
+## Common Mistakes
+
+### HIGH — Importing blocks globals before DS globals (or omitting DS globals)
+
+Wrong:
+
+```tsx
+import '@aircall/blocks/globals.css';
+import '@aircall/ds/globals.css';
+```
+
+Correct:
+
+```tsx
+import '@aircall/ds/globals.css';
+import '@aircall/blocks/globals.css';
+```
+
+The blocks bundle layers page-layout tokens on top of the DS reset/tokens; loading it first (or without DS) leaves block compositions with missing base tokens and broken layout.
+
+Source: aircall/hydra:docs/migration-guides/tractor-to-ds/00-setup.md (§3)
+
+### MEDIUM — Installing @aircall/blocks without @aircall/ds
+
+Wrong:
+
+```bash
+pnpm add @aircall/blocks
+```
+
+Correct:
+
+```bash
+pnpm add @aircall/blocks @aircall/ds
+```
+
+Blocks import from `@aircall/ds` at runtime; without it the blocks barrel fails to resolve its peer and the build breaks.
+
+Source: aircall/hydra:packages/blocks/package.json (peerDependencies)
+
+### MEDIUM — Expecting a separate BlocksProvider
+
+Wrong: searching for a `BlocksProvider` to mount.
+
+Correct: blocks render under the DS providers from aircall-ds/setup; mount those, not a blocks-specific provider.
+
+There is no blocks-specific provider; assuming one wastes time and produces dead wiring.
+
+Source: aircall/hydra:docs/migration-guides/tractor-to-ds/00-setup.md (§4)