@aircall/blocks 0.10.1 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aircall/blocks",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "type": "module",
   "private": false,
   "sideEffects": [
@@ -81,7 +81,7 @@
     "vite": "7.3.1",
     "vitest": "4.0.17",
     "zod": "4.4.3",
-    "@aircall/ds": "0.17.1",
+    "@aircall/ds": "0.18.0",
     "@aircall/hooks": "0.5.1"
   },
   "keywords": [

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

@@ -169,15 +169,34 @@ cross-step validation.
 
 | `FormFieldProps` | After |
 |---|---|
-| `name` / `label` | `name` / `label` on the `Form*Field` |
+| `name` | `name` on the `Form*Field` |
+| `label` | `label` — a string, or `{ content, aside?, info? }` (see below) |
+| helper/description text | `description` — a string, or `{ content, variant? }` (see below) |
 | `validate` | `validators.onChange` / `onSubmit` on the `Form*Field` |
 | `defaultValue` | `defaultValues[name]` in `useForm` |
 | `getErrorMessage(e)` | return the translated string from the validator |
 
+**`label`** — a string is the label text. The object form adds label-row affordances:
+- `label={{ content, info }}` — `info` is an `(i)` icon opening a popover of purely additive context
+  (hide it when ~90% of users don't need it).
+- `label={{ content, aside }}` — `aside` is free-form content pinned to the **right** of the row (a
+  "Where do I find this?" link, a popover, plain text, …). You pass the node — an `Anchor`, a
+  `Popover`, whatever — and blocks wraps it in `FieldLabelAside` for alignment + typography, forcing
+  no styling of its own.
+
+**`description`** — a string renders as the **`instructional`** variant (under the label, always
+visible — the default). Pass `{ content, variant: 'contextual' }` to move it **below the control**,
+where it is **hidden when the field is invalid** (the error takes its slot). Never mix both kinds on
+one field.
+
+**`necessityIndicator="required" | "optional"`** — mark only the exceptions (the few optional fields
+in a mostly-required form, or vice versa); never mix both markers in one form.
+
 ## Fields reference
 
 `@aircall/blocks` ships typed wrappers for all common DS controls; each takes `form`,
-`name`, `label`, optional `validators`, and a render-prop `(field, control) => …` —
+`name`, `label`, optional `validators`, optional `description` / `necessityIndicator`
+(see Prop mapping above), and a render-prop `(field, control) => …` —
 spread the control bundle onto the matching DS primitive.
 
 | Input | Block | Input | Block |

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

@@ -5,7 +5,8 @@ description: >
   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.
+  providers it relies on. Covers both standalone apps and module-federation
+  consumers where the host already loads DS globals.
 type: core
 library: aircall-blocks
 library_version: "0.5.1"
@@ -29,8 +30,27 @@ Install blocks alongside DS:
 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:
+How you import the CSS depends on whether your app is standalone or a
+**module-federation consumer** whose host already loads DS globals.
+
+### Standalone app (owns its own Preflight)
+
+`@aircall/blocks/globals.css` is a **delta build** — it contains only blocks-specific tokens
+and utility classes; it does NOT bundle DS. Import DS globals first (Preflight + DS tokens +
+DS utilities), then blocks globals (blocks-specific delta). Always import in this order.
+
+```css
+/* style.css */
+@layer theme, base, components, utilities;
+@import 'tailwindcss/theme.css' layer(theme);
+@import 'tailwindcss/utilities.css' layer(utilities);
+@import '@aircall/ds/globals.css';
+@import '@aircall/blocks/globals.css';
+
+@source './src/**/*.{ts,tsx}';
+```
+
+Or from a JS/TS entry (no custom Tailwind classes of your own):
 
 ```tsx
 // main.tsx
@@ -38,6 +58,28 @@ import '@aircall/ds/globals.css';
 import '@aircall/blocks/globals.css';
 ```
 
+### Module-federation consumer (host already owns the Preflight)
+
+When your app is a remote loaded inside a host that already imports DS globals
+(e.g. `dashboard-v4`), **do not re-import DS or blocks globals** in your own
+CSS. The host's single Preflight applies to the whole document — re-importing
+it duplicates the base reset and causes cascade conflicts (see Common Mistakes
+below).
+
+Import only the Tailwind layers you need for your own authored utility classes:
+
+```css
+/* style.css */
+@layer theme, base, components, utilities;
+@import 'tailwindcss/theme.css' layer(theme);
+@import 'tailwindcss/utilities.css' layer(utilities);
+
+@source './**/*.{ts,tsx}';
+```
+
+> **Note on the `.css` extension**: `@import "tailwindcss/theme"` (no `.css`)
+> silently fails in webpack/Rsbuild PostCSS pipelines — the extension is required.
+
 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:
@@ -78,26 +120,82 @@ function CampaignsHeader() {
 
 ## Common Mistakes
 
+### HIGH — Re-importing DS/blocks globals in a module-federation consumer
+
+Wrong — in a consumer whose host already loads DS globals:
+
+```css
+@import 'tailwindcss';
+@import '@aircall/ds/globals.css';
+@import '@aircall/blocks/globals.css';
+```
+
+Correct — consumer owns only its own utilities, no Preflight:
+
+```css
+@layer theme, base, components, utilities;
+@import 'tailwindcss/theme.css' layer(theme);
+@import 'tailwindcss/utilities.css' layer(utilities);
+@source './**/*.{ts,tsx}';
+```
+
+In a module-federation setup, CSS from each remote lands in the **same document**
+as the host. DS globals ships a Preflight (`@layer base { * { border-color: var(--color-border); } }`)
+that sets the token-based border color globally. If the consumer also imports DS globals
+(or the full `@import 'tailwindcss'`), it emits a second `@layer base` reset. Because
+webpack/Rsbuild emits deep dependencies first and the consumer's own CSS last, the
+consumer's Preflight (`border-color: currentColor`) ends up later in the output — and
+later wins. DS component borders (Card, etc.) lose their token color and become invisible.
+
 ### HIGH — Importing blocks globals before DS globals (or omitting DS globals)
 
-Wrong:
+Wrong — wrong order, or omitting DS globals:
 
-```tsx
-import '@aircall/blocks/globals.css';
-import '@aircall/ds/globals.css';
+```css
+@import '@aircall/blocks/globals.css';
+@import '@aircall/ds/globals.css';
 ```
 
-Correct:
+```css
+/* missing DS globals entirely */
+@import '@aircall/blocks/globals.css';
+```
 
-```tsx
-import '@aircall/ds/globals.css';
-import '@aircall/blocks/globals.css';
+Correct — DS globals first, then blocks globals:
+
+```css
+@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.
+`@aircall/blocks/globals.css` is a delta build — it contains only blocks-specific tokens
+and utility classes. It depends on DS globals being loaded first to provide Preflight and
+DS token definitions. Loading blocks before DS means DS's base reset (`border-color:
+var(--color-border)`) lands after blocks and within the same `@layer base`, and component
+tokens like `--background` and `--border` may not be defined when blocks tries to use them.
 
 Source: aircall/hydra:docs/migration-guides/tractor-to-ds/00-setup.md (§3)
 
+### MEDIUM — Using bare specifiers without `.css` in Rsbuild/webpack
+
+Wrong:
+
+```css
+@import 'tailwindcss/theme';
+@import 'tailwindcss/utilities';
+```
+
+Correct:
+
+```css
+@import 'tailwindcss/theme.css';
+@import 'tailwindcss/utilities.css';
+```
+
+The bare form (no `.css`) silently produces no output in webpack/Rsbuild PostCSS
+pipelines — classes like `flex`, `gap-4`, `text-sm` are never generated. Always
+use the `.css` extension when splitting Tailwind imports.
+
 ### MEDIUM — Installing @aircall/blocks without @aircall/ds
 
 Wrong: