@aircall/blocks 0.12.0 → 0.14.0

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

@@ -29,32 +29,51 @@ Campaign Creation (`CampaignWizardPage`) and Add Contacts (`AddContactsPage`) ar
 
 ## 2. DashboardStandalonePage (full-page flows)
 
+Four-part nesting: the outer `DashboardStandalonePage` is the `page-background` shell
+(8px inset, flex row); `DashboardStandalonePageContent` is the rounded content **panel**
+that holds the header + scroll area; the header carries a centered title (+ optional
+description) with edge-pinned actions; `DashboardStandalonePageMain` is the scroll area.
+
 ```tsx
 import {
   DashboardStandalonePage,
+  DashboardStandalonePageContent,
   DashboardStandalonePageHeader,
   DashboardStandalonePageTitle,
+  DashboardStandalonePageDescription,
   DashboardStandalonePageActions,
   DashboardStandalonePageAction,
-  DashboardStandalonePageContent
+  DashboardStandalonePageMain
 } from '@aircall/blocks';
 
 <DashboardStandalonePage>
-  <DashboardStandalonePageHeader>
-    <DashboardStandalonePageTitle>Create campaign</DashboardStandalonePageTitle>
-    <DashboardStandalonePageActions>
-      <DashboardStandalonePageAction onClick={onCancel}>Cancel</DashboardStandalonePageAction>
-    </DashboardStandalonePageActions>
-  </DashboardStandalonePageHeader>
   <DashboardStandalonePageContent>
-    {/* a centered, width-capped Card — see below */}
+    <DashboardStandalonePageHeader>
+      <DashboardStandalonePageTitle>Create campaign</DashboardStandalonePageTitle>
+      {/* optional subtitle under the title */}
+      <DashboardStandalonePageDescription>Set up your outbound campaign</DashboardStandalonePageDescription>
+      {/* actions pin to an edge; side="start" pins left, default "end" pins right */}
+      <DashboardStandalonePageActions>
+        <DashboardStandalonePageAction onClick={onCancel}>Cancel</DashboardStandalonePageAction>
+      </DashboardStandalonePageActions>
+    </DashboardStandalonePageHeader>
+    <DashboardStandalonePageMain>
+      {/* a centered, width-capped Card — see below */}
+    </DashboardStandalonePageMain>
   </DashboardStandalonePageContent>
 </DashboardStandalonePage>
 ```
 
-### What goes inside `DashboardStandalonePageContent` — a centered, width-capped Card
+- **Header** is a fixed 64px bar; the title (+ description) is optically centered and
+  actions are pinned to the left/right edges via `side` — declare them in any order.
+- **Split layouts:** put a second panel (e.g. a `ChatbotPanel`) as a sibling of
+  `DashboardStandalonePageContent`; they share the shell's 8px gap. Hide a secondary
+  side panel below the `md` breakpoint (`className="hidden md:flex"`) so the main flow
+  gets the full width on narrow screens.
+
+### What goes inside `DashboardStandalonePageMain` — a centered, width-capped Card
 
-`DashboardStandalonePageContent` is a full-bleed scroll area; it does **not** constrain
+`DashboardStandalonePageMain` is a full-bleed scroll area; it does **not** constrain
 width. The actual content is a centered container (`mx-auto` + a `max-w-*` cap) wrapping
 one or more `Card`s — the consistent pattern across the `DashboardStandalonePage` stories.
 Don't let content run full-width, and don't reach for `Paper`/raw page wrappers.
@@ -62,7 +81,7 @@ Don't let content run full-width, and don't reach for `Paper`/raw page wrappers.
 ```tsx
 import { Card, CardHeader, CardContent, CardFooter } from '@aircall/ds';
 
-<DashboardStandalonePageContent>
+<DashboardStandalonePageMain>
   {/* single-column form / wizard */}
   <div className="mx-auto max-w-2xl pt-4">
     <Card>
@@ -71,13 +90,19 @@ import { Card, CardHeader, CardContent, CardFooter } from '@aircall/ds';
       <CardFooter className="justify-end gap-2">{/* Back / Next / Submit */}</CardFooter>
     </Card>
   </div>
-</DashboardStandalonePageContent>
+</DashboardStandalonePageMain>
 ```
 
 Width cap by layout:
 - **Single-column form / wizard** → `mx-auto max-w-2xl pt-4` around one `Card` (CampaignWizard pattern).
 - **Wide / two-column** (form + summary aside) → `mx-auto flex max-w-7xl flex-col gap-6 pt-8 lg:flex-row`, a `Card` per column.
 
+> **API note (renamed):** `DashboardStandalonePageContent` is now the rounded **panel**
+> wrapper (header + main), and the scroll area is `DashboardStandalonePageMain` — matching
+> the `DashboardPage` family (`Page → Content → Main`). Earlier code where
+> `DashboardStandalonePageContent` was the scroll area must move that content into
+> `DashboardStandalonePageMain` and wrap header+main in `DashboardStandalonePageContent`.
+
 ## 3. DashboardPage (standard in-app page)
 
 ```tsx
@@ -154,8 +179,10 @@ Wrong:
 Correct:
 ```tsx
 <DashboardStandalonePage>
-  <DashboardStandalonePageHeader>...</DashboardStandalonePageHeader>
-  <DashboardStandalonePageContent>{/* wizard */}</DashboardStandalonePageContent>
+  <DashboardStandalonePageContent>
+    <DashboardStandalonePageHeader>...</DashboardStandalonePageHeader>
+    <DashboardStandalonePageMain>{/* wizard */}</DashboardStandalonePageMain>
+  </DashboardStandalonePageContent>
 </DashboardStandalonePage>
 ```
 

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

@@ -155,6 +155,31 @@ Why one form: `useFormWizard().data` was a single accumulator across pages — a
 submits the complete object. Per-step `useForm`s would fragment that state and lose
 cross-step validation.
 
+## Validation UX — validate on click, don't disable
+
+The `goNext` above is the **validate-on-click** pattern, and it's the one to reach for:
+the Next button stays enabled, and clicking it validates the step and reveals what's
+wrong. This is usually the product requirement ("never disable the button — tell me on
+click"). It works because a **`'submit'`-cause validation also runs the field's
+`onChange` validator** — so `form.validateField(name, 'submit')` populates errors even
+for fields the user never touched, and each `Form*Field` renders them through its own
+`FieldError`. (Verify against `form-core`'s `defaultValidationLogic`: the `submit` case
+runs `[onChange, onBlur, onSubmit, …]`.)
+
+- **Cross-field rules** ("at least one of A or B") can't be a single-field validator.
+  Put them on the parent `useForm`'s `validators`, or `safeParse` a step schema inside
+  `goNext`, and render the message where it belongs (e.g. a section-level `FieldError`).
+- **i18n:** function validators can `return t(key)` directly; if you use a schema
+  library, build the schema in a factory that receives `t` (module-scope schemas can't
+  call `t`).
+- If the design genuinely wants the button **disabled** until valid, subscribe
+  reactively instead — but this is the exception, not the default:
+  ```tsx
+  <form.Subscribe selector={s => isStepValid(s.values)}>
+    {ok => <Button disabled={!ok} onClick={() => setStep(next.id)}>Next</Button>}
+  </form.Subscribe>
+  ```
+
 ## Prop mapping
 
 | `FormWizardProps` / `useFormWizard` | After |
@@ -192,6 +217,22 @@ 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.
 
+**Layout — `orientation` / `controlPosition`** — every wrapper defaults to a **vertical** field
+(label above the control). Two shared props flip to a side-by-side layout, reusing the DS `Field`
+orientation:
+- `orientation="horizontal"` puts the label/description beside the control. `orientation="responsive"`
+  is vertical on narrow screens and horizontal once wide — it needs a `FieldGroup` ancestor (which
+  provides the `@container/field-group` the responsive variant reads).
+- `controlPosition="start" | "end"` picks the control's side. Defaults per control:
+  `FormSwitchField` → `'start'` (switch left of its label), text/select/etc. → `'end'`.
+- `FormSwitchField` **defaults to the inline (horizontal) layout** — a switch stacked under its label
+  is rarely wanted. A settings toggle: `<FormSwitchField label description>` (switch on the left);
+  pin the switch to the right with `controlPosition="end"`. Force the old stacked look with
+  `orientation="vertical"`.
+- A responsive text field (label + description on the left, input + error on the right on desktop,
+  stacked on mobile): `<FormInputField orientation="responsive" label description … />` inside a
+  `FieldGroup`.
+
 ## Fields reference
 
 `@aircall/blocks` ships typed wrappers for all common DS controls; each takes `form`,
@@ -204,9 +245,45 @@ spread the control bundle onto the matching DS primitive.
 | text/email/password | `FormInputField` | radio group | `FormRadioGroupField` |
 | select | `FormSelectField` | OTP | `FormOTPField` |
 | combobox (single) | `FormComboboxField` | switch | `FormSwitchField` |
-| combobox (multi) | `FormMultiComboboxField` | number | `FormNumberField` |
+| combobox (multi) | `FormMultiComboboxField` | number | `FormNumericField` |
 | textarea | `FormTextareaField` | slider | `FormSliderField` |
 
+## Multi-step gotchas
+
+The `Stepper` **unmounts inactive `StepperContent`** (there's no `forceMount`). That's
+usually fine — but two consequences bite:
+
+- Field **values** persist in the form store across unmount, and so does field **meta**
+  (`isDirty` / `isTouched`) — a field's `mount()` cleanup is a no-op. So you can read
+  `form.state.fieldMeta['step1.field'].isDirty` while on step 3, and edits made on an
+  earlier step are still there when you submit. Add `forceMount` only if a step must
+  stay in the DOM.
+- **Re-basing a saved draft: do NOT use `form.reset(values)`.** `reset` clears
+  `isTouched`, and when an unmounted step later remounts its field re-seeds to the
+  (empty) default — silently wiping the user's value. To mark the current values as
+  "synced" (e.g. after an autosave / draft save) while keeping them editable, clear
+  `isDirty` per field instead:
+  ```tsx
+  for (const path of Object.keys(form.state.fieldMeta))
+    form.setFieldMeta(path, m => ({ ...m, isDirty: false }));
+  ```
+  Now `isDirty` marks exactly what changed since the last sync — ideal for sending a
+  minimal update patch on the next save.
+
+## Field groups for large steps (optional)
+
+For steps with many fields you can extract each into a `withFieldGroup` bound to a
+subtree of the form, instead of listing everything in one flat `useForm`. Two things
+to know:
+
+- `fields` accepts a **subtree key** (`fields="general"`) **or** a **`FieldsMap`**
+  (`fields={{ groupField: 'form.path' }}`) — the map lets a group bind onto a flat
+  model without restructuring it.
+- A field group has **no group-level `validators`**. Put cross-field rules on a
+  field-level validator that reads its sibling via `fieldApi.form.getFieldValue(...)`,
+  or on the parent `useForm`. Use `group.Subscribe` for reactive reads inside the group
+  (its `state.values` is the group's subset).
+
 ## Common Mistakes
 
 ### 1. Fabricating a `Stepper` instance API (`useStepper({steps})`, `nextStep`, `stepper=` prop)
@@ -288,3 +365,38 @@ Correct:
 `SubmitButton`/`CardSaveBar` are registered form components — they read `canSubmit`/`isSubmitting` from form context and must be rendered via `form.AppForm`, not handed a `form` prop. They must also sit inside the `<form>` so their `type="submit"` triggers `onSubmit`.
 
 Source: `packages/blocks/src/form/use-form.ts`
+
+### 5. Re-basing a multi-step draft with `form.reset`
+
+Wrong:
+```tsx
+await saveDraft(form.state.values);
+form.reset(form.state.values); // clears isTouched → remounted steps re-seed to empty
+```
+
+Correct:
+```tsx
+await saveDraft(form.state.values);
+for (const path of Object.keys(form.state.fieldMeta))
+  form.setFieldMeta(path, m => ({ ...m, isDirty: false })); // keeps values + isTouched
+```
+
+`form.reset` is right for a single-screen form, but inside a `Stepper` (which unmounts inactive steps) it makes fields re-seed to their defaults on the next remount, wiping user input. Clearing `isDirty` re-bases the "changed since last sync" baseline without touching values.
+
+Source: `packages/blocks/src/form/use-form.ts`
+
+## Testing (jsdom)
+
+- **Drive navigation one step at a time.** `Next` handlers are async (validation runs
+  before advancing), so fire the click, **wait for the next step to render**, then
+  continue. Two back-to-back clicks race the async nav and both land on the same step.
+  ```tsx
+  fireEvent.click(getByTestId('next'));
+  await screen.findByText('Role');   // step 2 is on screen
+  fireEvent.click(getByTestId('next'));
+  ```
+- **Assert errors without filling every field.** Because a `'submit'`-cause validation
+  runs the `onChange` validators (see "Validation UX"), clicking Next on an empty step
+  surfaces each field's `FieldError` — assert on those directly.
+- **Field meta survives step changes**, so a test can edit a field on step 1, navigate
+  to a later step, submit, and still see the step-1 value in the payload.