@eifi1/ui-kit 0.12.0 → 0.13.1

package/src/rhf/fields.tsx

@@ -34,7 +34,9 @@
  * omitted, none — then give the field an `aria-label`), `hint` (standing advice under
  * the field, attached to it with `aria-describedby`), `required` (the label's mark,
  * and `aria-required` where the control takes it — validation is `rules`' or the
- * resolver's), `rules`, `disabled`, and `className` for the item's box.
+ * resolver's), `rules`, `disabled` (the control only — the value is still submitted;
+ * `excludeWhenDisabled` for react-hook-form's drop-the-value semantics), and
+ * `className` for the item's box.
  *
  * {@link RhfField} is the shell they are all built on, for a control the kit does not
  * ship (an address autocomplete): it takes a `render` and wires the rest.
@@ -80,9 +82,17 @@ export interface RhfFieldBaseProps<
   /** Draws the label's required mark and sets `aria-required` where the control
    *  takes it. Whether the field IS required is `rules`' or the resolver's to say. */
   required?: boolean;
-  /** Disables the field — through react-hook-form, so its value is left out of the
-   *  submitted values as a disabled input's would be. */
+  /** Disables the control and KEEPS the value: a field locked to a preset (a lease's
+   *  preselected unit, a fixed period) still submits it, and `rules` still run.
+   *  react-hook-form's own Controller `disabled` drops the value from `handleSubmit`'s
+   *  data instead, which a locked preset must never do (kastlan, 0.12). To get that,
+   *  add `excludeWhenDisabled`. A form-wide `useForm({ disabled })` still disables
+   *  every field the RHF way. */
   disabled?: boolean;
+  /** With `disabled`: disable through react-hook-form, so the value is left out of
+   *  the submitted data and validation skips it, like a disabled native input in a
+   *  plain form post. Default `false`. */
+  excludeWhenDisabled?: boolean;
   /** Classes for the item's box (a `grid gap-1`). */
   className?: string;
 }
@@ -187,6 +197,7 @@ export function RhfField<
   hint,
   required,
   disabled,
+  excludeWhenDisabled,
   className,
   render,
   asControl = true,
@@ -198,11 +209,16 @@ export function RhfField<
       control={control}
       name={name}
       rules={rules}
-      disabled={disabled}
+      disabled={excludeWhenDisabled ? disabled : undefined}
       render={({ field, fieldState }) => (
         <FormItem className={className}>
           {showLabel && hasContent(label) && <RhfLabel required={required}>{label}</RhfLabel>}
-          <ControlSlot field={field} fieldState={fieldState} render={render} asControl={asControl} />
+          <ControlSlot
+            field={disabled && !field.disabled ? { ...field, disabled: true } : field}
+            fieldState={fieldState}
+            render={render}
+            asControl={asControl}
+          />
           {hasContent(hint) && <FormDescription>{hint}</FormDescription>}
           {message && <FormMessage />}
         </FormItem>
@@ -230,8 +246,17 @@ function useFocusHandle(ref: ControllerRenderProps["ref"], find: () => HTMLEleme
 
 type OwnInputProps = Omit<
   InputProps,
-  "name" | "value" | "defaultValue" | "onChange" | "onBlur" | "ref" | "label" | "error" | "invalid" | "className" | "disabled" | "required"
->;
+  "name" | "value" | "defaultValue" | "onChange" | "onBlur" | "ref" | "label" | "error" | "invalid" | "className" | "disabled" | "required" | "inputClassName"
+> & {
+  /**
+   * Classes for the `<input>` — `className` is the item's box (kastlan 42: a
+   * `font-mono` IBAN, a `tabular-nums` reference number). {@link RhfTextarea} and
+   * {@link RhfNumberField} had it; this one only reached `Input`'s prop of the same
+   * name by accident of the rest-spread, undocumented and one refactor from being
+   * dropped. Declared, it is part of the contract the three share.
+   */
+  inputClassName?: string;
+};
 
 export type RhfTextFieldProps<
   TFieldValues extends FieldValues = FieldValues,
@@ -252,12 +277,13 @@ export function RhfTextField<
   hint,
   required,
   disabled,
+  excludeWhenDisabled,
   className,
   ...inputProps
 }: RhfTextFieldProps<TFieldValues, TName, TTransformed>) {
   return (
     <RhfField
-      {...{ name, control, rules, label, hint, required, disabled, className }}
+      {...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className }}
       render={({ field, invalid }) => (
         <Input
           aria-required={required || undefined}
@@ -302,13 +328,14 @@ export function RhfTextarea<
   hint,
   required,
   disabled,
+  excludeWhenDisabled,
   className,
   inputClassName,
   ...areaProps
 }: RhfTextareaProps<TFieldValues, TName, TTransformed>) {
   return (
     <RhfField
-      {...{ name, control, rules, label, hint, required, disabled, className }}
+      {...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className }}
       render={({ field, invalid }) => (
         <Textarea
           aria-required={required || undefined}
@@ -382,6 +409,7 @@ export function RhfNumberField<
   hint,
   required,
   disabled,
+  excludeWhenDisabled,
   className,
   emptyValue = null,
   nullable = true,
@@ -389,7 +417,7 @@ export function RhfNumberField<
 }: RhfNumberFieldProps<TFieldValues, TName, TTransformed>) {
   return (
     <RhfField
-      {...{ name, control, rules, label, hint, required, disabled, className }}
+      {...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className }}
       render={({ field, invalid, id }) => (
         // FormControl clones this element with `id` / `aria-describedby` /
         // `aria-invalid`, which NumberControl hands on to the field.
@@ -449,6 +477,46 @@ function NumberControl({
   );
 }
 
+export type RhfIntegerFieldProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+  TTransformed = TFieldValues,
+> = RhfNumberFieldProps<TFieldValues, TName, TTransformed>;
+
+/**
+ * {@link RhfNumberField} for a whole number — a floor, a room count, a year, a
+ * notice period in months. Every such call site in kastlan (item 41) spelled out the
+ * same three props, `digits={0} calculator={false} emptyValue=""`, and a preset
+ * written thirty times is one that is eventually written wrong once:
+ *
+ *  - `digits={0}`: rounds on commit, so "2.5" rooms settles to 3 instead of reaching
+ *    an `Integer` column and failing server-side;
+ *  - `calculator={false}`: a count is typed, not worked out — the trigger is noise
+ *    beside a two-digit field;
+ *  - `emptyValue=""`: kastlan's integer schemas are `z.coerce.number()` over `""`,
+ *    written against the native number inputs these fields replaced.
+ *
+ * Each is only a default: pass the prop to override it (`emptyValue={null}` for a
+ * nullable column). Everything else is {@link RhfNumberField}'s.
+ */
+export function RhfIntegerField<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+  TTransformed = TFieldValues,
+>(props: RhfIntegerFieldProps<TFieldValues, TName, TTransformed>) {
+  // `??` / `=== undefined` rather than a spread over the defaults, so a caller
+  // forwarding its own optional prop (`digits={props.digits}`) still gets the preset,
+  // while an explicit `emptyValue={null}` keeps its null.
+  return (
+    <RhfNumberField
+      {...props}
+      digits={props.digits ?? 0}
+      calculator={props.calculator ?? false}
+      emptyValue={props.emptyValue === undefined ? "" : props.emptyValue}
+    />
+  );
+}
+
 // ── money ────────────────────────────────────────────────────────────────────
 
 export type RhfMoneyFieldProps<
@@ -476,6 +544,15 @@ export type RhfMoneyFieldProps<
   valueAs?: "number" | "string";
   /** What an emptied field stores when `valueAs` is `"number"`. Default `null`. */
   emptyValue?: null | "";
+  /** Decimals the amount settles to on blur, Enter or a calculator result. Default:
+   *  the currency's minor unit (CHF 2, JPY 0). ⚠️ A unit price or a rate needs its
+   *  column's scale here (`digits={4}` for 1.789 €/l), or it is stored rounded to
+   *  cents without a word (keksdose G2). See {@link AmountInput}'s `digits`. */
+  digits?: number;
+  /** Clamp the settled amount (a release capped at the deposit's balance). Validate
+   *  with `rules` as well if a clamp needs explaining. */
+  min?: number;
+  max?: number;
 };
 
 /** The amount a text reads as, or `undefined` for a draft that is not one yet. */
@@ -573,12 +650,13 @@ export function RhfMoneyField<
   hint,
   required,
   disabled,
+  excludeWhenDisabled,
   className,
   ...amountProps
 }: RhfMoneyFieldProps<TFieldValues, TName, TTransformed>) {
   return (
     <RhfField
-      {...{ name, control, rules, label, hint, required, disabled, className }}
+      {...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className }}
       asControl={false}
       render={({ field, invalid, id, describedBy }) => (
         <MoneyControl
@@ -662,6 +740,7 @@ export function RhfDateField<
   hint,
   required,
   disabled,
+  excludeWhenDisabled,
   className,
   inputClassName,
   emptyValue = "",
@@ -669,7 +748,7 @@ export function RhfDateField<
 }: RhfDateFieldProps<TFieldValues, TName, TTransformed>) {
   return (
     <RhfField
-      {...{ name, control, rules, label, hint, required, disabled, className }}
+      {...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className }}
       render={({ field, invalid, id }) => (
         // FormControl clones this element with `aria-describedby` / `aria-invalid`,
         // which DateControl hands on to the picker's trigger.
@@ -726,6 +805,7 @@ export function RhfSelect<
   hint,
   required,
   disabled,
+  excludeWhenDisabled,
   className,
   options,
   children,
@@ -736,7 +816,7 @@ export function RhfSelect<
 }: RhfSelectProps<TFieldValues, TName, TTransformed>) {
   return (
     <RhfField
-      {...{ name, control, rules, label, hint, required, disabled, className }}
+      {...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className }}
       render={({ field, invalid }) => (
         <Select
           aria-required={required || undefined}
@@ -793,12 +873,13 @@ export function RhfCheckbox<
   hint,
   required,
   disabled,
+  excludeWhenDisabled,
   className,
   ...boxProps
 }: RhfCheckboxProps<TFieldValues, TName, TTransformed>) {
   return (
     <RhfField
-      {...{ name, control, rules, required, disabled, className }}
+      {...{ name, control, rules, required, disabled, excludeWhenDisabled, className }}
       showLabel={false}
       render={({ field, invalid }) => (
         <Checkbox
@@ -923,6 +1004,7 @@ export function RhfCombobox<
   hint,
   required,
   disabled,
+  excludeWhenDisabled,
   className,
   clearValue = null,
   comboClassName,
@@ -930,7 +1012,7 @@ export function RhfCombobox<
 }: RhfComboboxProps<TFieldValues, TName, V, TTransformed>) {
   return (
     <RhfField
-      {...{ name, control, rules, label, hint, required, disabled, className }}
+      {...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className }}
       asControl={false}
       message={false}
       render={({ field, invalid, error, id, describedBy }) => (
@@ -987,13 +1069,14 @@ export function RhfTextCombobox<
   hint,
   required,
   disabled,
+  excludeWhenDisabled,
   className,
   comboClassName,
   ...comboProps
 }: RhfTextComboboxProps<TFieldValues, TName, TTransformed>) {
   return (
     <RhfField
-      {...{ name, control, rules, label, hint, required, disabled, className }}
+      {...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className }}
       asControl={false}
       message={false}
       render={({ field, invalid, error, id, describedBy }) => (

package/src/rhf.ts

@@ -9,7 +9,7 @@
 export * from "./rhf/form";
 // The react-hook-form bridge to the wizard's Next gate (useWizard lives in /wizard).
 export * from "./rhf/use-rhf-wizard-step";
-// Bound fields — one line per field (RhfTextField, RhfNumberField, RhfMoneyField,
+// Bound fields — one line per field (RhfTextField, RhfNumberField, RhfIntegerField, RhfMoneyField,
 // RhfDateField, RhfTextarea, RhfSelect, RhfCheckbox, RhfCombobox, RhfTextCombobox)
 // and RhfField, the shell they are built on.
 export * from "./rhf/fields";

package/src/search/command-palette.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useId, useMemo, useRef, useState } from "react";
+import { useEffect, useEffectEvent, useId, useMemo, useRef, useState } from "react";
 import type { ReactNode } from "react";
 import { createPortal } from "react-dom";
 import { CornerDownLeft, Search, X } from "lucide-react";
@@ -54,9 +54,12 @@ function groupItems(items: CommandItem[]) {
     }
     byGroup.get(item.group)!.push(item);
   }
+  const flat = order.flatMap((g) => byGroup.get(g)!).filter((item) => item.kind !== "status");
   return {
     groups: order.map((g) => ({ group: g, items: byGroup.get(g)! })),
-    flat: order.flatMap((g) => byGroup.get(g)!).filter((item) => item.kind !== "status"),
+    flat,
+    /** Each selectable item's position in `flat` — its `data-index` and keyboard slot. */
+    flatIndex: new Map(flat.map((item, index) => [item, index])),
   };
 }
 
@@ -279,8 +282,9 @@ export function CommandPalette({
   const dialogRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLInputElement>(null);
   const listRef = useRef<HTMLUListElement>(null);
-  const searchRef = useRef(search);
-  searchRef.current = search;
+  // The latest `search`, callable from the debounced effect without being one of its
+  // dependencies — `revision` is what re-runs it (see the prop's docstring).
+  const runSearch = useEffectEvent((q: string) => search(q));
   const reqId = useRef(0);
   /** What the provider's last answer was: a promise (`false`), an array (`true`), or
    *  not known yet. Only a provider known to be async shows "Searching…" while the
@@ -305,17 +309,24 @@ export function CommandPalette({
   useBodyScrollLock(open);
 
   // Reset when opened — the palette's OWN text only; a controlled query belongs to
-  // its owner (see the prop).
+  // its owner (see the prop). Adjusted during render on the closed-to-open transition
+  // (starting from "closed", so a palette mounted open resets too). `controlled` is
+  // read at the open, not watched: a caller switching modes while the palette is open
+  // is not a reason to wipe what is typed.
+  const [wasOpen, setWasOpen] = useState(false);
+  if (open !== wasOpen) {
+    setWasOpen(open);
+    if (open) {
+      if (!controlled) setOwnQuery("");
+      // An uncommitted draft does not outlive the open it was typed in.
+      setDraft(controlled ? query : "");
+      setActive(0);
+    }
+  }
+  // The ref half of that reset: results from a previous open do not carry a
+  // highlight into this one.
   useEffect(() => {
-    if (!open) return;
-    if (!controlled) setOwnQuery("");
-    // An uncommitted draft does not outlive the open it was typed in.
-    setDraft(controlled ? query : "");
-    setActive(0);
-    shownQuery.current = null;
-    // `controlled` is read at the open, not watched: a caller switching modes while
-    // the palette is open is not a reason to wipe what is typed.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
+    if (open) shownQuery.current = null;
   }, [open]);
 
   // Debounced, race-safe search.
@@ -325,7 +336,7 @@ export function CommandPalette({
     if (syncRef.current === false) setLoading(true);
     const run = async () => {
       try {
-        const answer = searchRef.current(query);
+        const answer = runSearch(query);
         syncRef.current = !isThenable(answer);
         if (!syncRef.current) setLoading(true);
         const r = await answer;
@@ -359,7 +370,7 @@ export function CommandPalette({
   }, [query, open, revision]);
 
   // Group results, preserving first-seen group order; keep a flat list for nav.
-  const { groups, flat } = useMemo(() => groupItems(results), [results]);
+  const { groups, flat, flatIndex } = useMemo(() => groupItems(results), [results]);
   useEffect(() => {
     activeIdRef.current = flat[active]?.id;
   });
@@ -404,8 +415,8 @@ export function CommandPalette({
   if (!open) return null;
 
   const comfortable = density === "comfortable";
-  let flatIndex = -1;
   return createPortal(
+    // eslint-disable-next-line jsx-a11y/no-static-element-interactions -- pointer-only backdrop dismiss; Escape is the keyboard path
     <div
       className={cn(
         "fixed inset-0 z-[70] flex items-start justify-center bg-black/40",
@@ -546,8 +557,7 @@ export function CommandPalette({
                       </li>
                     );
                   }
-                  flatIndex += 1;
-                  const idx = flatIndex;
+                  const idx = flatIndex.get(item) ?? -1;
                   const isActive = idx === active;
                   const redact = item.redact ?? redactLabels;
                   // Written once and worn by either tag below, so the anchor and the

package/src/shell/app-shell.tsx

@@ -765,7 +765,6 @@ function SidebarGroup({
   // group UNFOLDS into view on load rather than appearing already open.
   const here = subActive || onOwnPage;
   useEffect(() => {
-    // eslint-disable-next-line react-hooks/set-state-in-effect -- follows the route, see above
     if (here) setOpenGroup(item.to);
   }, [here, item.to, setOpenGroup]);
   const expanded = inline && open;
@@ -931,6 +930,9 @@ function SidebarFlyout({ item, children }: { item: AppShellNavItem; children: Re
   );
 
   return (
+    // Not a control: hover and focus-within on the nav link inside. Focus (the
+    // keyboard path) opens it exactly as hover does, Escape closes it.
+    // eslint-disable-next-line jsx-a11y/no-static-element-interactions -- hover/focus-within wrapper around a real link
     <div
       ref={wrapperRef}
       className="relative"
@@ -943,6 +945,9 @@ function SidebarFlyout({ item, children }: { item: AppShellNavItem; children: Re
       {open &&
         pos &&
         createPortal(
+          // Keeps the flyout open while the pointer crosses into it; keyboard users
+          // reach it by focus, which the wrapper above already handles.
+          // eslint-disable-next-line jsx-a11y/no-static-element-interactions -- pointer-only hover bridge
           <div
             dir={dir}
             style={{ position: "fixed", ...pos }}

package/src/shell/topbar-action-menu.tsx

@@ -58,9 +58,15 @@ export interface TopBarMenuHeader {
   title: ReactNode;
   /** The muted second line — an email, a role. */
   subtitle?: ReactNode;
-  /** Anything below — a role chip. A link or button here stays out of the arrow keys
-   *  and in the Tab order, like the footer's. */
-  extra?: ReactNode;
+  /**
+   * Anything below — a role chip. A link or button here stays out of the arrow keys
+   * and in the Tab order, like the footer's.
+   *
+   * Pass a function to get `close`, as `footer` does — keksdose F7: its admin role
+   * chip links to the admin area, and a router link does not unmount the menu, so
+   * without `close` the panel stayed open over the page it had just navigated to.
+   */
+  extra?: ReactNode | ((close: () => void) => ReactNode);
 }
 
 /** What a control is, as far as `HoverMenu` is concerned, when it lives in the header
@@ -225,6 +231,7 @@ export function TopBarActionMenu({
     >
       {(close) => {
         const footerBody = typeof footer === "function" ? footer(close) : footer;
+        const headerExtra = typeof header?.extra === "function" ? header.extra(close) : header?.extra;
         const footerClass =
           "flex flex-wrap gap-x-3 gap-y-1 text-xs text-[var(--text-muted)] [&_a:hover]:text-[var(--text-primary)] [&_a]:rounded-sm [&_a:focus-visible]:outline-none [&_a:focus-visible]:ring-2 [&_a:focus-visible]:ring-[var(--brand)]";
         return (
@@ -236,7 +243,7 @@ export function TopBarActionMenu({
                 {header.subtitle != null && (
                   <div className="truncate text-xs text-[var(--text-muted)]">{header.subtitle}</div>
                 )}
-                {header.extra != null && <div className="mt-1">{header.extra}</div>}
+                {headerExtra != null && headerExtra !== false && <div className="mt-1">{headerExtra}</div>}
               </MenuSection>
             )}
             {heading && (

package/src/tour/tour.tsx

@@ -157,11 +157,15 @@ export function TourProvider({
   const [activeId, setActiveId] = useState<string | null>(null);
   const optsRef = useRef<StartOptions>({});
   // Live mirrors so the step-control callbacks can stay stable (identity-safe for
-  // consumers) while still reading the current steps/index.
+  // consumers) while still reading the current steps/index. Synced in a layout
+  // effect — after the commit, before paint and before any passive effect or event
+  // can call them — rather than written during render.
   const stepsRef = useRef<TourStep[] | null>(null);
-  stepsRef.current = steps;
   const indexRef = useRef(0);
-  indexRef.current = index;
+  useLayoutEffect(() => {
+    stepsRef.current = steps;
+    indexRef.current = index;
+  }, [steps, index]);
   const active = !!steps && steps.length > 0;
   const total = steps?.length ?? 0;
 
@@ -277,6 +281,15 @@ function TourOverlay({
   const isLast = index === steps.length - 1;
   const [rect, setRect] = useState<Rect | null>(null);
   const [ready, setReady] = useState(false);
+  // A new step starts unlocated: reset during render when the step changes, so the
+  // previous step's spotlight never paints over the new one. The effect below then
+  // locates it.
+  const [locating, setLocating] = useState({ index, step });
+  if (locating.index !== index || locating.step !== step) {
+    setLocating({ index, step });
+    setReady(false);
+    setRect(null);
+  }
   // The overlay is portalled to <body>, out of whatever `dir` subtree the app set, so it
   // takes the direction of the element it spotlights (the document's for a centered
   // step). Arrow keys and start/end placement read it.
@@ -287,8 +300,6 @@ function TourOverlay({
   useEffect(() => {
     let cancelled = false;
     let raf = 0;
-    setReady(false);
-    setRect(null);
     void (async () => {
       await step.beforeStep?.();
       if (cancelled) return;

package/src/wizard/use-wizard.ts

@@ -14,7 +14,7 @@
  * The committing step is the last one unless a step says `commits: true`; the
  * steps after that one are post-commit steps (see `WizardStepConfig.commits`).
  */
-import { useCallback, useEffect, useReducer, useRef, useState } from "react";
+import { useCallback, useEffect, useLayoutEffect, useReducer, useRef, useState } from "react";
 import { useSearchParams } from "react-router";
 import { useKitLabels } from "../i18n/kit-labels";
 import { DEFAULT_WIZARD_LABELS } from "./types";
@@ -163,8 +163,12 @@ export function useWizard<TData extends Record<string, unknown>>(
     missingRequiredMessage,
     onValidationFailed,
   } = options;
+  // The latest `steps`, for the stable callbacks below. Synced after commit (before
+  // paint, and before any handler can run) rather than written during render.
   const stepsRef = useRef<WizardStepConfig[]>(steps);
-  stepsRef.current = steps;
+  useLayoutEffect(() => {
+    stepsRef.current = steps;
+  }, [steps]);
   // A hook, not a component, but it produces two sentences of its own — the
   // "fill in the required fields" toast and the fallback submit error — and both
   // reach the user. So it reads the provider like any component does; only the two
@@ -239,8 +243,8 @@ export function useWizard<TData extends Record<string, unknown>>(
   // it back.
   const clearStepUrl = useStepUrl(urlParam, state.currentStepIndex);
 
-  // `steps`, not `stepsRef.current`: during render the two are the same array, and
-  // reading a ref in render is what the hooks linter (rightly) objects to.
+  // `steps`, not `stepsRef.current`: reading a ref in render is what the hooks
+  // linter (rightly) objects to, and the ref only catches up after the commit.
   const currentStep = steps[state.currentStepIndex];
   const isFirstStep = state.currentStepIndex === 0;
   const isLastStep = state.currentStepIndex === steps.length - 1;

package/src/wizard/wizard-step.tsx

@@ -14,6 +14,16 @@ export interface WizardStepProps {
   /** The line under the title: what the step asks for, or why. Rendered only with a
    *  `title` or on its own when there is none. */
   description?: ReactNode;
+  /**
+   * Controls for the step as a whole, at the end of the header row beside the title —
+   * kastlan 43: the buildings step's "Add building" had nowhere to go but UNDER the
+   * list it adds to, where it falls below the fold once there are three buildings.
+   * A header action is where every other kit surface (`PageHeader`, `Card`) puts it.
+   *
+   * Wraps under the title on a narrow screen rather than squeezing it. Renders the
+   * header on its own if there is no `title` either.
+   */
+  actions?: ReactNode;
   /** The heading's level. Default 3: the page has its `h1` and the wizard's own
    *  chrome sits at `h2` (the review step, the cancel dialog), so a step is under it. */
   headingLevel?: 2 | 3 | 4;
@@ -30,20 +40,42 @@ export function WizardStep({
   title,
   description,
   headingLevel = 3,
+  actions,
 }: WizardStepProps) {
   const hasTitle = title !== undefined && title !== null && title !== false && title !== "";
   const hasDescription =
     description !== undefined && description !== null && description !== false && description !== "";
+  const hasActions = actions !== undefined && actions !== null && actions !== false && actions !== "";
   const Heading = HEADING[headingLevel];
+  const heading = (
+    <>
+      {hasTitle && <Heading className="text-lg font-semibold text-[var(--text-primary)]">{title}</Heading>}
+      {hasDescription && <p className="text-sm text-[var(--text-muted)]">{description}</p>}
+    </>
+  );
   return (
     <div className={cn("space-y-6", className)}>
-      {(hasTitle || hasDescription) && (
-        <div data-slot="wizard-step-header" className="space-y-1">
-          {hasTitle && (
-            <Heading className="text-lg font-semibold text-[var(--text-primary)]">{title}</Heading>
-          )}
-          {hasDescription && <p className="text-sm text-[var(--text-muted)]">{description}</p>}
+      {hasActions ? (
+        // One row: the text takes the room, the actions keep their width at the end
+        // and wrap below it when there is not enough — `basis-64` is the width the
+        // title asks for before that happens (a zero basis would never wrap and
+        // squeeze the title to a word a line instead). `items-start` so a two-line
+        // description does not pull the button down to its middle; `ms-auto` keeps
+        // the actions at the end with no title, and when they wrap.
+        <div data-slot="wizard-step-header" className="flex flex-wrap items-start justify-between gap-x-4 gap-y-2">
+          {(hasTitle || hasDescription) && <div className="min-w-0 grow basis-64 space-y-1">{heading}</div>}
+          <div data-slot="wizard-step-actions" className="ms-auto flex shrink-0 flex-wrap items-center gap-2">
+            {actions}
+          </div>
         </div>
+      ) : (
+        // Without actions the header is exactly what it was, so a step that passes
+        // none renders as before.
+        (hasTitle || hasDescription) && (
+          <div data-slot="wizard-step-header" className="space-y-1">
+            {heading}
+          </div>
+        )
       )}
       {children}
     </div>