@aircall/blocks 0.13.0 → 0.14.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Anchor, Badge, Button, CounterBadge, DropdownMenu, DropdownMenuAddon, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, Field, FieldDescription, FieldError, FieldLabel, FieldLabelAside, FieldLabelInfo, FieldLabelRow, HoverCard, HoverCardContent, HoverCardTrigger, InputGroup, InputGroupButton, InputGroupTextarea, Item, ItemActions, ItemContent, ItemGroup, ItemMedia, ItemTitle, Popover, PopoverContent, PopoverTrigger, Separator, Sidebar, SidebarGroup, SidebarGroupLabel, SidebarMenu, SidebarMenuAction, SidebarMenuButton, SidebarMenuItem, SidebarProvider, Spinner, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, TabsList, ToggleGroup, ToggleGroupItem, Tooltip, TooltipContent, TooltipTrigger, cn, registerI18nNamespace, useDsTranslation, useSidebar } from "@aircall/ds";
+import { Anchor, Badge, Button, CounterBadge, DropdownMenu, DropdownMenuAddon, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, Field, FieldContent, FieldDescription, FieldError, FieldLabel, FieldLabelAside, FieldLabelInfo, FieldLabelRow, HoverCard, HoverCardContent, HoverCardTrigger, InputGroup, InputGroupButton, InputGroupTextarea, Item, ItemActions, ItemContent, ItemGroup, ItemMedia, ItemTitle, Popover, PopoverContent, PopoverTrigger, Separator, Sidebar, SidebarGroup, SidebarGroupLabel, SidebarMenu, SidebarMenuAction, SidebarMenuButton, SidebarMenuItem, SidebarProvider, Spinner, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, TabsList, ToggleGroup, ToggleGroupItem, Tooltip, TooltipContent, TooltipTrigger, cn, registerI18nNamespace, useDsTranslation, useSidebar } from "@aircall/ds";
 import * as React from "react";
 import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -1734,17 +1734,27 @@ const DashboardStandalonePage = React.forwardRef((componentProps, forwardRef) =>
 	return /* @__PURE__ */ jsx("div", {
 		ref: forwardRef,
 		"data-slot": "dashboard-standalone-page",
-		className: cn("flex h-screen flex-col bg-neutral-200 dark:bg-neutral-950", className),
+		className: cn("flex h-screen gap-2 overflow-hidden bg-page-background p-2", className),
 		...props
 	});
 });
 DashboardStandalonePage.displayName = "DashboardStandalonePage";
+const DashboardStandalonePageContent = React.forwardRef((componentProps, forwardRef) => {
+	const { className, ...props } = componentProps;
+	return /* @__PURE__ */ jsx("div", {
+		ref: forwardRef,
+		"data-slot": "dashboard-standalone-page-content",
+		className: cn("flex min-w-0 flex-1 flex-col overflow-hidden rounded-xl bg-page-surface border border-border", className),
+		...props
+	});
+});
+DashboardStandalonePageContent.displayName = "DashboardStandalonePageContent";
 const DashboardStandalonePageHeader = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("header", {
 		ref: forwardRef,
 		"data-slot": "dashboard-standalone-page-header",
-		className: cn("grid h-16 shrink-0 grid-cols-[1fr_auto_1fr] items-center gap-4 border-b border-border bg-background px-4 md:px-6", className),
+		className: cn("relative flex h-16 shrink-0 flex-col items-center justify-center gap-0.5 border-b border-border bg-background px-16 text-center", className),
 		...props
 	});
 });
@@ -1754,18 +1764,28 @@ const DashboardStandalonePageTitle = React.forwardRef((componentProps, forwardRe
 	return /* @__PURE__ */ jsx("h1", {
 		ref: forwardRef,
 		"data-slot": "dashboard-standalone-page-title",
-		className: cn("col-start-2 row-start-1 truncate text-center text-base font-bold text-foreground", className),
+		className: cn("max-w-xl truncate text-center text-xl leading-tight font-bold text-foreground", className),
 		...props
 	});
 });
 DashboardStandalonePageTitle.displayName = "DashboardStandalonePageTitle";
+const DashboardStandalonePageDescription = React.forwardRef((componentProps, forwardRef) => {
+	const { className, ...props } = componentProps;
+	return /* @__PURE__ */ jsx("p", {
+		ref: forwardRef,
+		"data-slot": "dashboard-standalone-page-description",
+		className: cn("max-w-xl truncate text-center text-sm leading-tight font-medium text-muted-foreground", className),
+		...props
+	});
+});
+DashboardStandalonePageDescription.displayName = "DashboardStandalonePageDescription";
 const DashboardStandalonePageActions = React.forwardRef((componentProps, forwardRef) => {
 	const { side = "end", className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
 		ref: forwardRef,
 		"data-slot": "dashboard-standalone-page-actions",
 		"data-side": side,
-		className: cn("row-start-1 flex min-w-0 items-center gap-2", side === "start" ? "col-start-1 justify-start" : "col-start-3 justify-end", className),
+		className: cn("absolute inset-y-0 flex items-center gap-2", side === "start" ? "left-4" : "right-4", className),
 		...props
 	});
 });
@@ -1780,16 +1800,16 @@ const DashboardStandalonePageAction = React.forwardRef((componentProps, forwardR
 	});
 });
 DashboardStandalonePageAction.displayName = "DashboardStandalonePageAction";
-const DashboardStandalonePageContent = React.forwardRef((componentProps, forwardRef) => {
+const DashboardStandalonePageMain = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("main", {
 		ref: forwardRef,
-		"data-slot": "dashboard-standalone-page-content",
+		"data-slot": "dashboard-standalone-page-main",
 		className: cn("min-h-0 flex-1 overflow-auto p-4 md:p-6", className),
 		...props
 	});
 });
-DashboardStandalonePageContent.displayName = "DashboardStandalonePageContent";
+DashboardStandalonePageMain.displayName = "DashboardStandalonePageMain";
 
 //#endregion
 //#region src/components/dashboard-page.tsx
@@ -2433,7 +2453,7 @@ function toFieldErrors(errors) {
 
 //#endregion
 //#region src/components/form-field.tsx
-function FormFieldShell({ label, description, necessityIndicator, id, children }) {
+function FormFieldShell({ label, description, necessityIndicator, id, children, orientation = "vertical", controlPosition = "end", controlVariant = "fill" }) {
 	const errors = useFieldContext().state.meta.errors;
 	const labelContent = typeof label === "string" ? label : label?.content;
 	const labelInfo = typeof label === "object" ? label.info : void 0;
@@ -2455,16 +2475,44 @@ function FormFieldShell({ label, description, necessityIndicator, id, children }
 		variant: descriptionVariant,
 		children: descriptionContent
 	});
-	return /* @__PURE__ */ jsxs(Field, {
-		"data-invalid": errors.length > 0 ? true : void 0,
+	const invalid = errors.length > 0 ? true : void 0;
+	const instructionalDesc = descriptionVariant === "instructional" ? descriptionNode : null;
+	const contextualDesc = descriptionVariant === "contextual" ? descriptionNode : null;
+	const errorNode = /* @__PURE__ */ jsx(FieldError, { errors: toFieldErrors(errors) });
+	if (orientation === "vertical") return /* @__PURE__ */ jsxs(Field, {
+		"data-invalid": invalid,
 		children: [
 			labelRow,
-			descriptionVariant === "instructional" && descriptionNode,
+			instructionalDesc,
 			children,
-			descriptionVariant === "contextual" && descriptionNode,
-			/* @__PURE__ */ jsx(FieldError, { errors: toFieldErrors(errors) })
+			contextualDesc,
+			errorNode
 		]
 	});
+	if (controlVariant === "inline") {
+		const textSide = descriptionContent !== void 0 || errors.length > 0 ? /* @__PURE__ */ jsxs(FieldContent, { children: [
+			labelRow,
+			instructionalDesc,
+			contextualDesc,
+			errorNode
+		] }) : labelRow;
+		return /* @__PURE__ */ jsxs(Field, {
+			orientation,
+			"data-invalid": invalid,
+			children: [controlPosition === "start" ? children : textSide, controlPosition === "start" ? textSide : children]
+		});
+	}
+	const labelCol = /* @__PURE__ */ jsxs(FieldContent, { children: [labelRow, instructionalDesc] });
+	const controlCol = /* @__PURE__ */ jsxs(FieldContent, { children: [
+		children,
+		contextualDesc,
+		errorNode
+	] });
+	return /* @__PURE__ */ jsxs(Field, {
+		orientation,
+		"data-invalid": invalid,
+		children: [controlPosition === "start" ? controlCol : labelCol, controlPosition === "start" ? labelCol : controlCol]
+	});
 }
 /**
 * Shared runtime binder for the per-primitive wrappers (FormSelectField, FormInputField, …).
@@ -2472,7 +2520,7 @@ function FormFieldShell({ label, description, necessityIndicator, id, children }
 * the AppField + shared shell. `TData`/`TControl` carry the precise field + bundle shapes through.
 */
 function FormFieldBase(props) {
-	const { form, name, validators, listeners, defaultValue, asyncDebounceMs, asyncAlways, label, description, necessityIndicator, buildControl, children } = props;
+	const { form, name, validators, listeners, defaultValue, asyncDebounceMs, asyncAlways, label, description, necessityIndicator, orientation, controlPosition, controlVariant, buildControl, children } = props;
 	const id = `${React.useId()}-${name}`;
 	const AppField = form.AppField;
 	return /* @__PURE__ */ jsx(AppField, {
@@ -2486,6 +2534,9 @@ function FormFieldBase(props) {
 			label,
 			description,
 			necessityIndicator,
+			orientation,
+			controlPosition,
+			controlVariant,
 			id,
 			children: children(field, buildControl(field, id))
 		})
@@ -2791,14 +2842,21 @@ function switchControl(field, id) {
 * with a `switchProps` bundle. `name` is restricted to the form's **boolean** fields — a
 * string/number `name` is a type error.
 *
+* In a horizontal/responsive layout the switch is a bare, natural-width control beside its label
+* (`controlPosition` picks the side — defaults to `'start'`, i.e. switch on the left).
+*
 * @example
 * <FormSwitchField form={form} name="enabled" label="Enabled" validators={{ onChange }}>
 *   {(field, { switchProps }) => <Switch {...switchProps} />}
 * </FormSwitchField>
 */
 function FormSwitchField(props) {
+	const { orientation = "horizontal", controlPosition = "start", ...rest } = props;
 	return /* @__PURE__ */ jsx(FormFieldBase, {
-		...props,
+		...rest,
+		orientation,
+		controlPosition,
+		controlVariant: "inline",
 		buildControl: switchControl
 	});
 }
@@ -3222,4 +3280,4 @@ function DashboardSidebarNav({ groups, renderLink }) {
 }
 
 //#endregion
-export { BetaBadge, CardSaveBar, ChatbotExpandSuggestion, ChatbotInput, ChatbotPage, ChatbotPageBody, ChatbotPageContent, ChatbotPageConversation, ChatbotPageFooter, ChatbotPageHeading, ChatbotPageInputBar, ChatbotPanel, ChatbotPanelHeader, ChatbotPanelSuggestion, ChatbotPanelTrigger, ChatbotResponseBlock, ChatbotResponseLoading, ChatbotSidebar, ChatbotUserMessage, ComingSoonDescription, ComingSoonEmptyState, ComingSoonMedia, ComingSoonTitle, CommonForm, CopyButton, CopyButtonIcon, CopyButtonLabel, DashboardPage, DashboardPageBanner, DashboardPageContent, DashboardPageHeader, DashboardPageHeaderAction, DashboardPageHeaderActions, DashboardPageHeaderDescription, DashboardPageHeaderNav, DashboardPageHeaderNavBack, DashboardPageHeaderPrefix, DashboardPageHeaderSubtitle, DashboardPageHeaderTitle, DashboardPageHeaderTitleGroup, DashboardPageMain, DashboardPageTabs, DashboardSidebar, DashboardSidebarContent, DashboardSidebarFooter, DashboardSidebarGroup, DashboardSidebarGroupLabel, DashboardSidebarHeader, DashboardSidebarMenu, DashboardSidebarMenuBadge, DashboardSidebarMenuButton, DashboardSidebarMenuItem, DashboardSidebarNav, DashboardSidebarProvider, DashboardSidebarSubmenu, DashboardSidebarSubmenuItem, DashboardSidebarSubmenuSeparator, DashboardSidebarTrigger, DashboardStandalonePage, DashboardStandalonePageAction, DashboardStandalonePageActions, DashboardStandalonePageContent, DashboardStandalonePageHeader, DashboardStandalonePageTitle, DeprecatedBadge, EmptyState, EmptyStateActions, EmptyStateButton, EmptyStateDescription, EmptyStateExternalLink, EmptyStateHeader, EmptyStateMedia, EmptyStateTitle, FormArrayField, FormComboboxField, FormFieldBase, FormFieldShell, FormInputField, FormMultiComboboxField, FormNumericField, FormOTPField, FormRadioGroupField, FormSelectField, FormSliderField, FormSwitchField, FormTextareaField, FormToggleGroupField, NewBadge, NoDataDescription, NoDataEmptyState, NoDataMedia, NoDataTitle, NoSupportDescription, NoSupportEmptyState, NoSupportMedia, NoSupportTitle, NotFoundDescription, NotFoundEmptyState, NotFoundMedia, NotFoundTitle, ProfessionalBadge, RestrictedAccessDescription, RestrictedAccessEmptyState, RestrictedAccessMedia, RestrictedAccessTitle, RoleBadge, SaveBar, SubmitButton, TrialBadge, UnknownErrorDescription, UnknownErrorEmptyState, UnknownErrorMedia, UnknownErrorTitle, fieldContext, formContext, toFieldErrors, useCopyToClipboard, useSidebar as useDashboardSidebar, useFieldContext, useForm, useFormContext, withFieldGroup, withForm };
+export { BetaBadge, CardSaveBar, ChatbotExpandSuggestion, ChatbotInput, ChatbotPage, ChatbotPageBody, ChatbotPageContent, ChatbotPageConversation, ChatbotPageFooter, ChatbotPageHeading, ChatbotPageInputBar, ChatbotPanel, ChatbotPanelHeader, ChatbotPanelSuggestion, ChatbotPanelTrigger, ChatbotResponseBlock, ChatbotResponseLoading, ChatbotSidebar, ChatbotUserMessage, ComingSoonDescription, ComingSoonEmptyState, ComingSoonMedia, ComingSoonTitle, CommonForm, CopyButton, CopyButtonIcon, CopyButtonLabel, DashboardPage, DashboardPageBanner, DashboardPageContent, DashboardPageHeader, DashboardPageHeaderAction, DashboardPageHeaderActions, DashboardPageHeaderDescription, DashboardPageHeaderNav, DashboardPageHeaderNavBack, DashboardPageHeaderPrefix, DashboardPageHeaderSubtitle, DashboardPageHeaderTitle, DashboardPageHeaderTitleGroup, DashboardPageMain, DashboardPageTabs, DashboardSidebar, DashboardSidebarContent, DashboardSidebarFooter, DashboardSidebarGroup, DashboardSidebarGroupLabel, DashboardSidebarHeader, DashboardSidebarMenu, DashboardSidebarMenuBadge, DashboardSidebarMenuButton, DashboardSidebarMenuItem, DashboardSidebarNav, DashboardSidebarProvider, DashboardSidebarSubmenu, DashboardSidebarSubmenuItem, DashboardSidebarSubmenuSeparator, DashboardSidebarTrigger, DashboardStandalonePage, DashboardStandalonePageAction, DashboardStandalonePageActions, DashboardStandalonePageContent, DashboardStandalonePageDescription, DashboardStandalonePageHeader, DashboardStandalonePageMain, DashboardStandalonePageTitle, DeprecatedBadge, EmptyState, EmptyStateActions, EmptyStateButton, EmptyStateDescription, EmptyStateExternalLink, EmptyStateHeader, EmptyStateMedia, EmptyStateTitle, FormArrayField, FormComboboxField, FormFieldBase, FormFieldShell, FormInputField, FormMultiComboboxField, FormNumericField, FormOTPField, FormRadioGroupField, FormSelectField, FormSliderField, FormSwitchField, FormTextareaField, FormToggleGroupField, NewBadge, NoDataDescription, NoDataEmptyState, NoDataMedia, NoDataTitle, NoSupportDescription, NoSupportEmptyState, NoSupportMedia, NoSupportTitle, NotFoundDescription, NotFoundEmptyState, NotFoundMedia, NotFoundTitle, ProfessionalBadge, RestrictedAccessDescription, RestrictedAccessEmptyState, RestrictedAccessMedia, RestrictedAccessTitle, RoleBadge, SaveBar, SubmitButton, TrialBadge, UnknownErrorDescription, UnknownErrorEmptyState, UnknownErrorMedia, UnknownErrorTitle, fieldContext, formContext, toFieldErrors, useCopyToClipboard, useSidebar as useDashboardSidebar, useFieldContext, useForm, useFormContext, withFieldGroup, withForm };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aircall/blocks",
-  "version": "0.13.0",
+  "version": "0.14.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.19.0",
+    "@aircall/ds": "0.20.0",
     "@aircall/hooks": "0.5.1"
   },
   "keywords": [

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

@@ -80,7 +80,7 @@ utils/data home or must stay in the consuming app.
 
 **UI with no blocks/ds equivalent yet**: some `@dashboard/library` UI components have
 no target in `@aircall/blocks` or `@aircall/ds` yet (e.g. `PieChart` and other charts,
-`AudioPlayer`, `TileLegend`). If a UI component is not in the routing table below and
+`TileLegend`). If a UI component is not in the routing table below and
 not listed above, leave it imported from `@dashboard/library` for now — do not force a
 migration or invent a target.
 
@@ -100,6 +100,7 @@ migration or invent a target.
 | `List` + `ListItem` | `ItemGroup`, `Item`, `ItemMedia`, `ItemContent`, `ItemActions` (@aircall/ds) | load @aircall/blocks#aircall-blocks/migrate-dashboard/list | available |
 | `Tile` + `TileHeader` + `TileValue` | `Card` (+ parts) as the tile container (@aircall/ds) | load @aircall/blocks#aircall-blocks/migrate-dashboard/tile | available |
 | `GridLayout` + `GridItem` + `Gap` | native `<div>` + Tailwind grid/flex/gap utilities (NO component import needed — these are layout primitives) (@aircall/ds) | load @aircall/blocks#aircall-blocks/migrate-dashboard/layout | available |
+| `AudioPlayer` | `Audio`, `AudioPlayerRow`, `AudioPlayerButton`, `AudioPlayerBar`, `AudioPlayerTime`, `AudioPlayerSpeed`, `AudioPlayerSkip`, `AudioPlayerManager`, `useAudioPlayer` (@aircall/ds) | load @aircall/ds#aircall-ds/migrate-audio-player | available |
 | `InfoPopup` + `InfoPopupTrigger` + `InfoPopupContent` | `HoverCard`, `HoverCardTrigger`, `HoverCardContent` (@aircall/ds) | load @aircall/blocks#aircall-blocks/migrate-dashboard/info-popup | available |
 | `CopyToClipboardButton` + `CopyToClipboardText` | `CopyButton`, `CopyButtonIcon`, `CopyButtonLabel` (@aircall/blocks) | load @aircall/blocks#aircall-blocks/migrate-dashboard/copy-button | available |
 | `ToggleRow` | `Field` (orientation="horizontal") + `Switch` + `FieldLabel` + optional `FieldDescription` (@aircall/ds) | load @aircall/blocks#aircall-blocks/migrate-dashboard/toggle-row | available |

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.