@aircall/blocks 0.6.0 → 0.9.0

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

@@ -0,0 +1,347 @@
+---
+name: aircall-blocks/migrate-dashboard/empty-states
+description: >
+  Migrate @dashboard/library MessageScreen family (ComingSoonScreen,
+  RestrictedAccessScreen, NotFoundScreen, NoDataScreen, NoSupportScreen,
+  UnknownErrorScreen) to @aircall/blocks composable empty-state blocks.
+  Load when a file imports any of those from @dashboard/library.
+type: sub-skill
+library: aircall-blocks
+library_version: "0.5.1"
+requires:
+  - aircall-blocks/setup
+  - aircall-blocks/migrate-dashboard
+sources:
+  - "aircall/hydra:docs/migration-guides/tractor-to-ds/recipes/empty-states.md"
+---
+
+This skill builds on aircall-blocks/migrate-dashboard.
+
+## 1. Variant mapping
+
+| `@dashboard/library` | `@aircall/blocks` root | Old asset | New icon |
+| --- | --- | --- | --- |
+| `ComingSoonScreen` | `ComingSoonEmptyState` | `aircall-placeholder.svg` | `Sprout` |
+| `RestrictedAccessScreen` | `RestrictedAccessEmptyState` | `lock.svg` | `LockKeyhole` |
+| `NotFoundScreen` | `NotFoundEmptyState` | `not-found.svg` | `Search` |
+| `NoDataScreen` | `NoDataEmptyState` | `no-data.svg` | `Search` |
+| `NoSupportScreen` | `NoSupportEmptyState` | `settings.svg` | `Settings` |
+| `UnknownErrorScreen` | `UnknownErrorEmptyState` | `warning.svg` | `TriangleAlert` |
+
+Each preset exports four individually importable parts — `*EmptyState` (root), `*Media`, `*Title`, `*Description` — all from `@aircall/blocks`.
+
+## 2. Prop mapping
+
+| `MessageScreen` prop | New equivalent |
+| --- | --- |
+| `title` | children of `*Title` — omit to use the baked-in design copy |
+| `subtitle` (string or element) | children of `*Description` |
+| `buttonText` + `onClick` | `EmptyStateButton` inside `EmptyStateActions` |
+| `image` | fixed per variant — drop it |
+| `data-test` | pass to the root: `<NotFoundEmptyState data-test="…">` |
+| `w` / `h` / `backgroundColor` | drop — constrain the parent instead |
+
+## 3. Before / After examples
+
+### 3a. NotFoundScreen → NotFoundEmptyState
+
+**Before (`@dashboard/library`):**
+```tsx
+import { NotFoundScreen } from '@dashboard/library';
+
+<NotFoundScreen
+  title="We couldn't find that page"
+  subtitle="It may have been moved, deleted, or the link may be incorrect."
+  buttonText="Go to inbox"
+  onClick={goToInbox}
+/>
+```
+
+**After (`@aircall/blocks`):**
+```tsx
+import {
+  NotFoundEmptyState,
+  NotFoundMedia,
+  NotFoundTitle,
+  NotFoundDescription,
+  EmptyStateHeader,
+  EmptyStateActions,
+  EmptyStateButton
+} from '@aircall/blocks';
+
+<NotFoundEmptyState>
+  <EmptyStateHeader>
+    <NotFoundMedia />
+    <NotFoundTitle />
+    <NotFoundDescription />
+  </EmptyStateHeader>
+  <EmptyStateActions>
+    <EmptyStateButton variant="outline" onClick={goToInbox}>
+      Go to inbox
+    </EmptyStateButton>
+  </EmptyStateActions>
+</NotFoundEmptyState>
+```
+
+The `*Title` and `*Description` ship the Figma copy as defaults — drop `title`/`subtitle` props to adopt them, or override by passing children.
+
+### 3b. ComingSoonScreen → ComingSoonEmptyState (two buttons)
+
+**Before (`@dashboard/library`):**
+```tsx
+import { ComingSoonScreen } from '@dashboard/library';
+
+<ComingSoonScreen
+  title="Coming soon!"
+  subtitle="You'll be able to access this feature in the near future."
+  buttonText="Go back"
+  onClick={goBack}
+/>
+```
+
+**After (`@aircall/blocks`):**
+```tsx
+import {
+  ComingSoonEmptyState,
+  ComingSoonMedia,
+  ComingSoonTitle,
+  ComingSoonDescription,
+  EmptyStateHeader,
+  EmptyStateActions,
+  EmptyStateButton,
+  EmptyStateExternalLink
+} from '@aircall/blocks';
+
+<ComingSoonEmptyState>
+  <EmptyStateHeader>
+    <ComingSoonMedia />
+    <ComingSoonTitle />
+    <ComingSoonDescription />
+  </EmptyStateHeader>
+  <EmptyStateActions>
+    <EmptyStateButton variant="outline" onClick={goBack}>Go back</EmptyStateButton>
+  </EmptyStateActions>
+  <EmptyStateExternalLink href={docsUrl} />
+</ComingSoonEmptyState>
+```
+
+`EmptyStateExternalLink` is a sibling of `EmptyStateActions` (not inside it) so it sits on its own line below the buttons.
+
+### 3c. UnknownErrorScreen → UnknownErrorEmptyState (error state)
+
+**Before (`@dashboard/library`):**
+```tsx
+import { UnknownErrorScreen } from '@dashboard/library';
+
+<UnknownErrorScreen
+  title="Something went wrong"
+  subtitle="Please try again."
+  buttonText="Try again"
+  onClick={reload}
+/>
+```
+
+**After (`@aircall/blocks`):**
+```tsx
+import {
+  UnknownErrorEmptyState,
+  UnknownErrorMedia,
+  UnknownErrorTitle,
+  UnknownErrorDescription,
+  EmptyStateHeader,
+  EmptyStateActions,
+  EmptyStateButton
+} from '@aircall/blocks';
+
+<UnknownErrorEmptyState>
+  <EmptyStateHeader>
+    <UnknownErrorMedia />
+    <UnknownErrorTitle />
+    <UnknownErrorDescription />
+  </EmptyStateHeader>
+  <EmptyStateActions>
+    <EmptyStateButton variant="default" onClick={reload}>Try again</EmptyStateButton>
+  </EmptyStateActions>
+</UnknownErrorEmptyState>
+```
+
+`UnknownErrorEmptyState` carries `role="alert"` — it announces assertively to screen readers when it mounts. `NoDataEmptyState` carries `role="status"` (polite). The others are static page content with no live region.
+
+### 3d. RestrictedAccessScreen → RestrictedAccessEmptyState (learn more link)
+
+**Before (`@dashboard/library`):**
+```tsx
+import { RestrictedAccessScreen } from '@dashboard/library';
+
+<RestrictedAccessScreen
+  title="You don't have access to this page."
+  subtitle="Contact an admin on your team to get access."
+  buttonText="Learn more"
+  onClick={() => window.open(docsUrl)}
+/>
+```
+
+**After (`@aircall/blocks`):**
+```tsx
+import {
+  RestrictedAccessEmptyState,
+  RestrictedAccessMedia,
+  RestrictedAccessTitle,
+  RestrictedAccessDescription,
+  EmptyStateHeader,
+  EmptyStateExternalLink
+} from '@aircall/blocks';
+
+<RestrictedAccessEmptyState>
+  <EmptyStateHeader>
+    <RestrictedAccessMedia />
+    <RestrictedAccessTitle />
+    <RestrictedAccessDescription />
+  </EmptyStateHeader>
+  <EmptyStateExternalLink href={docsUrl} />
+</RestrictedAccessEmptyState>
+```
+
+Use `EmptyStateExternalLink` (renders a real `<a target="_blank">`) instead of an `onClick` that calls `window.open`.
+
+### 3e. Custom / one-off empty state (no variant)
+
+When migrating a bespoke `MessageScreen` usage (custom `image` prop), use the generic family directly:
+
+```tsx
+import {
+  EmptyState,
+  EmptyStateHeader,
+  EmptyStateMedia,
+  EmptyStateTitle,
+  EmptyStateDescription,
+  EmptyStateActions,
+  EmptyStateButton
+} from '@aircall/blocks';
+import { Sparkles } from '@aircall/react-icons';
+
+<EmptyState>
+  <EmptyStateHeader>
+    <EmptyStateMedia>
+      <Sparkles />
+    </EmptyStateMedia>
+    <EmptyStateTitle>No integrations yet</EmptyStateTitle>
+    <EmptyStateDescription>Connect your first integration to get started.</EmptyStateDescription>
+  </EmptyStateHeader>
+  <EmptyStateActions>
+    <EmptyStateButton variant="default" onClick={openCatalog}>Browse catalog</EmptyStateButton>
+  </EmptyStateActions>
+</EmptyState>
+```
+
+Icons must come from `@aircall/react-icons`, never from `lucide-react` directly.
+
+## 4. Common Mistakes
+
+### Mistake 1: Passing `title`/`subtitle` as props to the root
+
+```tsx
+// WRONG — the root block has no title/subtitle props; they are silently ignored
+<NotFoundEmptyState title="Page not found" subtitle="Check the URL." />
+
+// CORRECT — pass custom copy as children of the *Title / *Description parts
+<NotFoundEmptyState>
+  <EmptyStateHeader>
+    <NotFoundMedia />
+    <NotFoundTitle>Page not found</NotFoundTitle>
+    <NotFoundDescription>Check the URL.</NotFoundDescription>
+  </EmptyStateHeader>
+</NotFoundEmptyState>
+```
+
+Mechanism: the old `MessageScreen` was a single component that accepted flat string props. The new blocks are a composable family; the root only accepts layout-level props (`data-test`, `role`, `className`, …). Title and description are separate sub-components.
+
+Source: `packages/blocks/src/components/empty-state.tsx` — `EmptyState.Props` extends `React.ComponentProps<typeof Empty>`, which has no `title` or `subtitle`.
+
+---
+
+### Mistake 2: Placing `EmptyStateExternalLink` inside `EmptyStateActions`
+
+```tsx
+// WRONG — the link ends up in the same flex row as the buttons
+<EmptyStateActions>
+  <EmptyStateButton variant="outline" onClick={goBack}>Go back</EmptyStateButton>
+  <EmptyStateExternalLink href={docsUrl} />
+</EmptyStateActions>
+
+// CORRECT — place it as a sibling after EmptyStateActions
+<EmptyStateActions>
+  <EmptyStateButton variant="outline" onClick={goBack}>Go back</EmptyStateButton>
+</EmptyStateActions>
+<EmptyStateExternalLink href={docsUrl} />
+```
+
+Mechanism: `EmptyStateActions` is a flex row (`flex-row flex-wrap justify-center gap-3`). Placing the link inside it makes it appear inline with the buttons at the same level, breaking the stacked design where the link sits on its own line below.
+
+Source: `packages/blocks/src/components/empty-state.tsx` — `EmptyStateActions` renders `EmptyContent` with `flex-row` class; `EmptyStateExternalLink` is meant to be a sibling in the `EmptyState` root's column flow.
+
+---
+
+### Mistake 3: Setting `size` on `EmptyStateButton`
+
+```tsx
+// WRONG — size is locked; passing it is a type error and overrides the design spec
+<EmptyStateButton variant="outline" size="sm" onClick={goBack}>Go back</EmptyStateButton>
+
+// CORRECT — omit size; only variant is yours to choose
+<EmptyStateButton variant="outline" onClick={goBack}>Go back</EmptyStateButton>
+```
+
+Mechanism: `EmptyStateButtonProps` is `Omit<React.ComponentProps<typeof Button>, 'size'>` — `size` is explicitly removed from the type. The button always renders at `size="default"` to keep all empty states visually consistent regardless of the surrounding UI.
+
+Source: `packages/blocks/src/components/empty-state.tsx` — `EmptyStateButton` wraps `Button` with `size="default"` hardcoded; the `size` key is stripped from the exported props type.
+
+---
+
+### Mistake 4: Carrying over `w`, `h`, or `backgroundColor` from `Gap` props
+
+```tsx
+// WRONG — these props do not exist on the new blocks root
+<NotFoundEmptyState w="100%" h="100%" backgroundColor="neutral-100" />
+
+// CORRECT — the block fills its container and centers automatically; constrain the parent
+<div className="h-full w-full">
+  <NotFoundEmptyState />
+</div>
+```
+
+Mechanism: the old `MessageScreen` extended `GapProps` (Tractor) which exposed `w`/`h`/`backgroundColor` to fill the viewport. The new `*EmptyState` roots extend `React.ComponentProps<typeof Empty>` (DS), which is a plain `<div>` with Tailwind layout — these props do not exist.
+
+Source: `packages/blocks/src/components/empty-state.tsx` — `EmptyStateProps` extends `React.ComponentProps<typeof Empty>`; `packages/blocks/src/components/coming-soon.tsx` — `ComingSoonEmptyState` is `ComingSoon.Root` with the same props shape.
+
+---
+
+### Mistake 5: Importing icons from `lucide-react` directly in generic empty states
+
+```tsx
+// WRONG — imports lucide-react directly, bypassing Aircall's icon layer
+import { Sparkles } from 'lucide-react';
+import { EmptyState, EmptyStateHeader, EmptyStateMedia, EmptyStateTitle } from '@aircall/blocks';
+
+<EmptyState>
+  <EmptyStateHeader>
+    <EmptyStateMedia><Sparkles /></EmptyStateMedia>
+    <EmptyStateTitle>No integrations yet</EmptyStateTitle>
+  </EmptyStateHeader>
+</EmptyState>
+
+// CORRECT — always import from @aircall/react-icons
+import { Sparkles } from '@aircall/react-icons';
+import { EmptyState, EmptyStateHeader, EmptyStateMedia, EmptyStateTitle } from '@aircall/blocks';
+
+<EmptyState>
+  <EmptyStateHeader>
+    <EmptyStateMedia><Sparkles /></EmptyStateMedia>
+    <EmptyStateTitle>No integrations yet</EmptyStateTitle>
+  </EmptyStateHeader>
+</EmptyState>
+```
+
+Mechanism: `@aircall/react-icons` re-exports all lucide icons plus Aircall custom icons; importing from `lucide-react` directly bypasses any Aircall overrides and breaks the single icon source-of-truth. All six built-in presets source their icons through `@aircall/react-icons` — custom media slots should follow the same convention.
+
+Source: `packages/blocks/src/components/coming-soon.tsx` — imports `Sprout` from `@aircall/react-icons`, not from `lucide-react`.

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

@@ -0,0 +1,271 @@
+---
+name: aircall-blocks/migrate-dashboard/form-wizard
+description: >
+  Migrate @dashboard/library FormWizard, useFormWizard, and FormField to a fully
+  integrated TanStack Form: one @aircall/blocks useForm + the Form*Field wrappers,
+  driven through ds Stepper for the multi-step UI. Load when a file imports
+  FormWizard, useFormWizard, or FormField from @dashboard/library.
+type: sub-skill
+library: aircall-blocks
+library_version: "0.5.1"
+requires:
+  - aircall-blocks/setup
+  - aircall-blocks/migrate-dashboard
+sources:
+  - "aircall/hydra:packages/ds/src/components/stepper.tsx"
+  - "aircall/hydra:packages/blocks/src/form/use-form.ts"
+---
+
+This skill builds on aircall-blocks/migrate-dashboard.
+
+> **Principle — the form owns state, never `useState`.** All field values, validation,
+> dirty/`canSubmit`/`isSubmitting`, and errors live in ONE `useForm`; render every field
+> via a `Form*Field` wrapper. Do not carry over `useFormWizard().data`/`editData` or raw
+> `useState` + `<Input value/onChange>` — rewrite them to the form. (`useState` is still
+> fine for non-field UI like the active step.)
+
+## Concept split
+
+`FormWizard` bundled the overlay, the stepper, and the form state. The DS stack
+separates them — and the form state becomes **one** TanStack Form spanning every
+step (the canonical TanStack [multi-step wizard](https://tanstack.com/form/latest/docs/framework/react/examples/multi-step-wizard) pattern):
+
+| @dashboard/library | Target |
+|---|---|
+| `FormWizard` overlay shell | `Dialog` from `@aircall/ds` (or render inline) |
+| `FormWizard.Stepper` / `pageIndex` / step titles | `Stepper` + `StepperProgress` + `StepperPanel` + `StepperContent` from `@aircall/ds` |
+| `useFormWizard().data` / `editData` | **one** `useForm` from `@aircall/blocks` with all steps' `defaultValues` — values accumulate across steps automatically |
+| `FormField` | a `Form*Field` from `@aircall/blocks` (`FormInputField`, `FormSelectField`, …) |
+| `navigateToNextPage` | validate the current step's fields, then advance the `Stepper` `value` |
+| `onSuccess(data)` | the single `useForm`'s `onSubmit` (fires from the last step) |
+| `onClose` / `onCancel` | `DialogClose` + `onOpenChange` |
+
+## Import mapping
+
+```tsx
+// Before
+import { FormWizard, useFormWizard, FormField } from '@dashboard/library';
+
+// After
+import { useState } from 'react';
+import {
+  Dialog, DialogContent, DialogHeader, DialogTitle, DialogClose,
+  Stepper, StepperProgress, StepperPanel, StepperContent,
+  Button, Input
+} from '@aircall/ds';
+import { useForm, FormInputField, FormSelectField } from '@aircall/blocks';
+```
+
+## Stepper API (read this — it is value-controlled)
+
+`Stepper` takes a `steps: { id; title }[]` array and is controlled by `value` /
+`onValueChange` (the active step **id**). Panels render with `StepperContent value={id}`
+inside a `StepperPanel`. `useStepper()` (no args, only inside a `Stepper`) returns
+`{ activeId, goTo, getIndex, steps }`. There is no `nextStep`/`prevStep`/`currentStep` —
+advance by setting `value` (or `goTo(id)`).
+
+## After — one form, ds Stepper, validate-per-step
+
+```tsx
+const STEPS = [
+  { id: 'details', title: 'Details' },
+  { id: 'role', title: 'Role' }
+] as const;
+
+// which fields belong to which step — used to validate before advancing
+const STEP_FIELDS: Record<string, string[]> = {
+  details: ['name'],
+  role: ['role']
+};
+
+export function CreateUserWizard({ open, onClose }: { open: boolean; onClose: () => void }) {
+  const [step, setStep] = useState<string>(STEPS[0].id);
+
+  // ONE form for the whole wizard — values from every step accumulate here
+  const form = useForm({
+    defaultValues: { name: '', role: '' },
+    onSubmit: async ({ value }) => {
+      await saveUser(value);
+      onClose();
+    }
+  });
+
+  const stepIndex = STEPS.findIndex(s => s.id === step);
+  const isLast = stepIndex === STEPS.length - 1;
+
+  // validate only the CURRENT step's fields before moving on
+  const goNext = async () => {
+    const results = await Promise.all(
+      STEP_FIELDS[step].map(name => form.validateField(name, 'submit'))
+    );
+    if (results.every(errors => errors.length === 0)) {
+      setStep(STEPS[stepIndex + 1].id);
+    }
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={v => { if (!v) onClose(); }}>
+      <DialogContent className="max-w-lg p-0">
+        <DialogHeader className="border-b px-6 py-4">
+          <DialogTitle>Create user</DialogTitle>
+          <DialogClose />
+        </DialogHeader>
+
+        <form onSubmit={e => { e.preventDefault(); void form.handleSubmit(); }}>
+          <Stepper steps={STEPS} value={step} onValueChange={setStep} className="px-6 pt-4">
+            <StepperProgress />
+            <StepperPanel className="p-6">
+              <StepperContent value="details" className="space-y-4">
+                <FormInputField form={form} name="name" label="Full name">
+                  {(_field, { inputProps }) => <Input {...inputProps} />}
+                </FormInputField>
+              </StepperContent>
+
+              <StepperContent value="role" className="space-y-4">
+                <FormSelectField form={form} name="role" label="Role">
+                  {(_field, control) => <Input {...control.inputProps} />}
+                </FormSelectField>
+              </StepperContent>
+            </StepperPanel>
+          </Stepper>
+
+          <div className="flex justify-end gap-2 border-t px-6 py-3">
+            {stepIndex > 0 && (
+              <Button type="button" variant="ghost" onClick={() => setStep(STEPS[stepIndex - 1].id)}>
+                Back
+              </Button>
+            )}
+            {isLast ? (
+              <form.AppForm>
+                <form.SubmitButton>Create user</form.SubmitButton>
+              </form.AppForm>
+            ) : (
+              <Button type="button" onClick={goNext}>Next</Button>
+            )}
+          </div>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+Why one form: `useFormWizard().data` was a single accumulator across pages — a single
+`useForm` reproduces that exactly (every field lives in one `value`), so the final step
+submits the complete object. Per-step `useForm`s would fragment that state and lose
+cross-step validation.
+
+## Prop mapping
+
+| `FormWizardProps` / `useFormWizard` | After |
+|---|---|
+| `initialData` | the single `useForm({ defaultValues })` |
+| `onSuccess(data)` | `onSubmit` on that `useForm` (runs from the last step) |
+| `onClose` / `onCancel` | `DialogClose` + `onOpenChange` on `Dialog` |
+| `pageIndex` / current page | `value` (active step id) on `Stepper` |
+| `navigateToNextPage` | validate step fields, then `setStep(next.id)` |
+| `navigateToPreviousPage` | `setStep(prev.id)` |
+| `FormWizard.Page stepTitle` | a `{ id, title }` entry in the `steps` array |
+
+| `FormFieldProps` | After |
+|---|---|
+| `name` / `label` | `name` / `label` on the `Form*Field` |
+| `validate` | `validators.onChange` / `onSubmit` on the `Form*Field` |
+| `defaultValue` | `defaultValues[name]` in `useForm` |
+| `getErrorMessage(e)` | return the translated string from the validator |
+
+## 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) => …` —
+spread the control bundle onto the matching DS primitive.
+
+| Input | Block | Input | Block |
+|---|---|---|---|
+| text/email/password | `FormInputField` | radio group | `FormRadioGroupField` |
+| select | `FormSelectField` | OTP | `FormOTPField` |
+| combobox (single) | `FormComboboxField` | switch | `FormSwitchField` |
+| combobox (multi) | `FormMultiComboboxField` | number | `FormNumberField` |
+| textarea | `FormTextareaField` | slider | `FormSliderField` |
+
+## Common Mistakes
+
+### 1. Fabricating a `Stepper` instance API (`useStepper({steps})`, `nextStep`, `stepper=` prop)
+
+Wrong:
+```tsx
+const stepper = useStepper({ steps });          // useStepper takes no args
+<Stepper stepper={stepper}>                       // no `stepper` prop
+<StepperContent step={steps[0]}>...               // no `step` prop
+<Button onClick={stepper.nextStep}>Next</Button>  // no nextStep
+```
+
+Correct:
+```tsx
+const [step, setStep] = useState(STEPS[0].id);
+<Stepper steps={STEPS} value={step} onValueChange={setStep}>
+  <StepperPanel>
+    <StepperContent value="details">...</StepperContent>
+  </StepperPanel>
+</Stepper>
+<Button type="button" onClick={() => setStep(next.id)}>Next</Button>
+```
+
+`Stepper` is value-controlled by step **id**; `useStepper()` (no args, inside the tree) exposes `{ activeId, goTo, getIndex, steps }`. The invented instance API does not exist and won't compile.
+
+Source: `packages/ds/src/components/stepper.tsx`
+
+### 2. One `useForm` per step instead of one for the wizard
+
+Wrong:
+```tsx
+function DetailsStep() { const form = useForm({ defaultValues: { name: '' }, ... }); }
+function RoleStep()    { const form = useForm({ defaultValues: { role: '' }, ... }); }
+```
+
+Correct:
+```tsx
+// one form at the wizard level holds every step's fields
+const form = useForm({ defaultValues: { name: '', role: '' }, onSubmit });
+```
+
+`useFormWizard().data` was one accumulator. Per-step forms fragment the value, drop earlier steps on submit, and prevent cross-step validation.
+
+Source: `packages/blocks/src/form/use-form.ts`
+
+### 3. Advancing without validating the current step
+
+Wrong:
+```tsx
+<Button onClick={() => setStep(next.id)}>Next</Button>  // skips validation
+```
+
+Correct:
+```tsx
+const goNext = async () => {
+  const r = await Promise.all(STEP_FIELDS[step].map(n => form.validateField(n, 'submit')));
+  if (r.every(e => e.length === 0)) setStep(next.id);
+};
+```
+
+`form.validateField(name, cause)` returns the field's errors; gating `setStep` on them reproduces `FormWizard`'s per-page validation. Without it the user advances past empty/invalid required fields.
+
+Source: `packages/blocks/src/form/use-form.ts`
+
+### 4. `CardSaveBar`/`SubmitButton` passed `form` as a prop or placed outside `form.AppForm`
+
+Wrong:
+```tsx
+<CardSaveBar form={form} />
+```
+
+Correct:
+```tsx
+<form.AppForm>
+  <form.SubmitButton>Create user</form.SubmitButton>
+</form.AppForm>
+```
+
+`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`