@eifi1/ui-kit 0.7.1 → 0.8.0

package/src/i18n/locales/it.ts

@@ -42,6 +42,7 @@ export function uiKitLabelsIt(numberLocale = "it-IT"): UiKitLabels {
     },
     pageContents: { title: "In questa pagina" },
     common: {
+      dismiss: "Chiudi",
       close: "Chiudi",
       clear: "Cancella",
       search: "Cerca",
@@ -125,6 +126,9 @@ export function uiKitLabelsIt(numberLocale = "it-IT"): UiKitLabels {
       month: (monthYear) => monthYear,
     },
     datePicker: {
+      apply: "Applica",
+      cancel: "Annulla",
+      presets: "Intervalli rapidi",
       panel: "Scegli una data",
       rangePanel: "Scegli un intervallo di date",
       clear: "Cancella",
@@ -241,6 +245,12 @@ export function uiKitLabelsIt(numberLocale = "it-IT"): UiKitLabels {
       size: (bytes) => formatFileSize(bytes, numberLocale),
     },
     filePicker: {
+      dropzone: "Caricamento file",
+      browse: "Sfoglia",
+      empty: "Trascina qui un file",
+      emptyMultiple: "Trascina qui i file",
+      hint: (accept) => (accept ? `Accettati: ${accept}` : "Qualsiasi tipo di file"),
+      busy: "Caricamento…",
       rejectedPick: (count) =>
         count === 1 ? "Il file non è stato aggiunto" : `Nessuno dei ${count} file è stato aggiunto`,
       // "file" is invariable in Italian ("1 file", "3 file"); only the verb agrees.
@@ -260,6 +270,7 @@ export function uiKitLabelsIt(numberLocale = "it-IT"): UiKitLabels {
       cleared: "Tutti i file rimossi",
     },
     wizard: {
+      done: "Fine",
       cancel: "Annulla",
       back: "Indietro",
       next: "Avanti",
@@ -354,6 +365,20 @@ export function uiKitLabelsIt(numberLocale = "it-IT"): UiKitLabels {
       empty: "Nessun dato",
       legend: "Serie",
     },
+    confirmDialog: {
+      confirm: "Conferma",
+      cancel: "Annulla",
+    },
+    floatingPanel: {
+      close: "Chiudi",
+    },
+    copyButton: {
+      copy: "Copia",
+      copied: "Copiato",
+      failed: "Copia non riuscita",
+      copiedAnnouncement: "Copiato negli appunti",
+      failedAnnouncement: "Impossibile copiare negli appunti",
+    },
   };
 }
 

package/src/i18n/locales/zh.ts

@@ -40,6 +40,7 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
     },
     pageContents: { title: "本页目录" },
     common: {
+      dismiss: "关闭",
       close: "关闭",
       clear: "清除",
       search: "搜索",
@@ -120,6 +121,9 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
       month: (monthYear) => monthYear,
     },
     datePicker: {
+      apply: "应用",
+      cancel: "取消",
+      presets: "快捷范围",
       panel: "选择日期",
       rangePanel: "选择日期范围",
       clear: "清除",
@@ -235,6 +239,12 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
       size: (bytes) => formatFileSize(bytes, numberLocale),
     },
     filePicker: {
+      dropzone: "文件上传",
+      browse: "浏览",
+      empty: "将文件拖放到此处",
+      emptyMultiple: "将文件拖放到此处",
+      hint: (accept) => (accept ? `支持：${accept}` : "任意文件类型"),
+      busy: "正在上传…",
       rejectedPick: (count) => (count === 1 ? "未添加该文件" : `${count} 个文件均未添加`),
       rejectedType: (name) => `“${name}”的文件类型不受支持`,
       rejectedTypeOnly: (accept) => `仅限 ${accept} 文件`,
@@ -250,6 +260,7 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
       cleared: "已移除所有文件",
     },
     wizard: {
+      done: "完成",
       cancel: "取消",
       back: "上一步",
       next: "下一步",
@@ -342,6 +353,20 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
       empty: "无数据",
       legend: "数据系列",
     },
+    confirmDialog: {
+      confirm: "确认",
+      cancel: "取消",
+    },
+    floatingPanel: {
+      close: "关闭",
+    },
+    copyButton: {
+      copy: "复制",
+      copied: "已复制",
+      failed: "复制失败",
+      copiedAnnouncement: "已复制到剪贴板",
+      failedAnnouncement: "无法复制到剪贴板",
+    },
   };
 }
 

package/src/i18n/swiss.ts

@@ -0,0 +1,25 @@
+/**
+ * Swiss Standard German respelling, shared by the `de-CH` and `de-CH-informal`
+ * translations. Internal: it lives outside `src/i18n/locales/` because every file there
+ * becomes a public `@eifi1/ui-kit/i18n/<code>` subpath.
+ *
+ * "ss" for every "ß" (Schliessen, Grösse) is the one systematic difference in UI text.
+ * Function labels are wrapped: their RESULT is respelled, so an argument the app passes
+ * in (a file name, a phrase to type) is respelled too — which is what a Swiss app
+ * writing "ss" everywhere wants.
+ */
+export function swiss<T>(value: T): T {
+  if (typeof value === "string") return respell(value) as T;
+  if (typeof value === "function") {
+    const fn = value as (...args: unknown[]) => unknown;
+    return ((...args: unknown[]) => swiss(fn(...args))) as T;
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, swiss(v)])) as T;
+  }
+  return value;
+}
+
+function respell(text: string): string {
+  return text.replace(/ß/g, "ss").replace(/ẞ/g, "SS");
+}

package/src/index.ts

@@ -32,6 +32,15 @@ export { useOverlayHistory } from "./hooks/use-overlay-history";
 export { useCloseTransition, OVERLAY_EXIT_MS } from "./hooks/use-close-transition";
 export { useRowSwipe } from "./hooks/use-row-swipe";
 export type { SwipeStage, RowSwipeOptions, RowSwipeReturn } from "./hooks/use-row-swipe";
+// Any element as a file drop target, screened like FileButton (kastlan).
+export { useFileDrop, dragHasFiles } from "./hooks/use-file-drop";
+export type { UseFileDropOptions, UseFileDropReturn, FileDropProps } from "./hooks/use-file-drop";
+// kastlan's search boxes each carried a hand-rolled copy, two without the cleanup.
+export { useDebounce, useDebouncedCallback } from "./hooks/use-debounce";
+export type { DebouncedCallbackOptions, DebouncedFunction } from "./hooks/use-debounce";
+// Copy that reports whether it worked — keksdose's copy buttons said "Copied" when it had not.
+export { useCopyToClipboard, copyToClipboard } from "./hooks/use-copy-to-clipboard";
+export type { CopyState, UseCopyToClipboardOptions, UseCopyToClipboardReturn } from "./hooks/use-copy-to-clipboard";
 
 // ── theme / palettes ─────────────────────────────────────────────────────────
 export * from "./theme/chart-palette";
@@ -83,6 +92,10 @@ export * from "./components/page-contents";
 export * from "./components/disclosure";
 export * from "./components/dialog-frame";
 export * from "./components/danger-confirm";
+// `useConfirm()` — the promise-based replacement for `window.confirm`, one host per app.
+export * from "./components/confirm-dialog";
+// A non-modal corner panel and its round trigger (keksdose's assistant launcher).
+export * from "./components/floating-panel";
 export * from "./components/swatch-picker";
 export * from "./components/icon-picker";
 export * from "./components/choice-card";
@@ -123,7 +136,21 @@ export * from "./components/grouped-picker";
 export * from "./components/file-dropzone";
 export * from "./components/mini-calendar";
 export * from "./components/date-picker";
+export * from "./components/tree-view";
 export * from "./components/chart";
+// 0.8.0 layout and feedback primitives the apps hand-rolled or took from shadcn/Radix.
+export * from "./components/description-list";
+export * from "./components/progress-bar";
+// Named: skeleton.tsx also holds SKELETON_CLASS, the look StatTile shares — internal.
+export { Skeleton } from "./components/skeleton";
+export type { SkeletonProps, SkeletonShape } from "./components/skeleton";
+export * from "./components/copy-button";
+export * from "./components/button-group";
+export * from "./components/table";
+export * from "./components/separator";
+// Named: scroll-area.tsx also holds the overflow hook and scrollbar class Table shares.
+export { ScrollArea } from "./components/scroll-area";
+export type { ScrollAreaProps } from "./components/scroll-area";
 
 // ── data-table suite ─────────────────────────────────────────────────────────
 export * from "./components/data-table-labels";
@@ -140,6 +167,8 @@ export type {
   ServerPagination,
   FilterState,
   MobileSwipeActions,
+  DataTableDensity,
+  DataTableChrome,
 } from "./components/data-table";
 
 // ── shell (composable app chrome) ────────────────────────────────────────────

package/src/lib/dates.ts

@@ -185,3 +185,51 @@ export function dateRangePresets(): DateRangePreset[] {
     { key: "last_year", from: startOfYearIso(-1), to: endOfYearIso(-1) },
   ];
 }
+
+/** The last `n` WHOLE calendar months before the current one, as an inclusive
+ *  `{ from, to }` — on 15 May, `n = 3` is 1 February … 30 April. Local-calendar, like
+ *  everything here; `now` is for tests and for a host with its own clock. */
+export function lastFullMonthsRange(n: number, now: Date = new Date()): { from: string; to: string } {
+  const from = new Date(now.getFullYear(), now.getMonth() - n, 1);
+  // Day 0 of the current month is the last day of the previous one.
+  const to = new Date(now.getFullYear(), now.getMonth(), 0);
+  return { from: toLocalIso(from), to: toLocalIso(to) };
+}
+
+/** The last `n` WHOLE calendar years before the current one — in 2026, `n = 2` is
+ *  1 January 2024 … 31 December 2025. */
+export function lastFullYearsRange(n: number, now: Date = new Date()): { from: string; to: string } {
+  const year = now.getFullYear();
+  return { from: `${year - n}-01-01`, to: `${year - 1}-12-31` };
+}
+
+export interface CalendarMonthPresetOptions {
+  /** How many whole months each month preset spans. Default `[3, 6]`. */
+  months?: readonly number[];
+  /** How many whole years each year preset spans. Default `[2]`. */
+  years?: readonly number[];
+  /** The day to count back from. Default: now, on the local calendar. */
+  now?: Date;
+}
+
+/**
+ * Month-ALIGNED presets, beside the rolling-day ones of {@link dateRangePresets}.
+ *
+ * kastlan's accounting reports are closed by the month: "the last three months" there
+ * means February, March and April, never "the 90 days up to this morning", which
+ * starts mid-month and ends with a day that is still being booked. `last_3_months`
+ * above is the rolling kind and stays that way for the data table's filter, so these
+ * are separate keys rather than a changed meaning under an old one.
+ *
+ * Keys are `last_<n>_full_months` and `last_<n>_full_years`; the host labels them (the
+ * same arrangement as `dateRangePresets`' keys and its `table.preset_*` strings). With
+ * `DateRangePicker`, pass the key as the preset's `id` so the choice keeps its
+ * identity while the dates are recomputed on every render.
+ */
+export function calendarMonthPresets(options: CalendarMonthPresetOptions = {}): DateRangePreset[] {
+  const { months = [3, 6], years = [2], now = new Date() } = options;
+  return [
+    ...months.map((n) => ({ key: `last_${n}_full_months`, ...lastFullMonthsRange(n, now) })),
+    ...years.map((n) => ({ key: `last_${n}_full_years`, ...lastFullYearsRange(n, now) })),
+  ];
+}

package/src/search/command-palette.tsx

@@ -91,6 +91,20 @@ interface CommandPaletteProps {
    * another keystroke. That is the ordinary first open on a cold cache.
    */
   revision?: unknown;
+  /**
+   * The search text, CONTROLLED. Keksdose binds it to the URL's `q`, so a search
+   * survives a reload, can be shared as a link, and Back walks through it — none of
+   * which state inside the palette can do.
+   *
+   * Leave it out and the palette keeps its own, as before, starting empty on every
+   * open. Given, it is never reset on open: the owner decides what an open shows, and
+   * a palette that blanked the URL's `q` each time would fight its own address bar.
+   * `onQueryChange` is then how a keystroke gets anywhere, since it is the only writer.
+   */
+  query?: string;
+  /** Every edit of the field's text. Fires in both modes — uncontrolled, it only
+   *  observes. */
+  onQueryChange?: (query: string) => void;
   labels?: Partial<CommandPaletteLabels>;
 }
 
@@ -119,6 +133,8 @@ export function CommandPalette({
   onClose,
   search,
   revision,
+  query: queryProp,
+  onQueryChange,
   labels,
 }: CommandPaletteProps) {
   const l = useKitLabels("commandPalette", DEFAULTS_WITHOUT_DIALOG, labels);
@@ -129,7 +145,13 @@ export function CommandPalette({
   const dialogName =
     l.dialog ??
     (l.placeholder !== DEFAULT_COMMAND_PALETTE_LABELS.placeholder ? l.placeholder : DEFAULT_DIALOG_NAME);
-  const [query, setQuery] = useState("");
+  const [ownQuery, setOwnQuery] = useState("");
+  const controlled = queryProp !== undefined;
+  const query = controlled ? queryProp : ownQuery;
+  const setQuery = (next: string) => {
+    if (!controlled) setOwnQuery(next);
+    onQueryChange?.(next);
+  };
   const [results, setResults] = useState<CommandItem[]>([]);
   const [loading, setLoading] = useState(false);
   const [failed, setFailed] = useState(false);
@@ -160,11 +182,15 @@ export function CommandPalette({
   useFocusTrap(dialogRef, { active: open, initialFocus: () => inputRef.current });
   useBodyScrollLock(open);
 
-  // Reset when opened.
+  // Reset when opened — the palette's OWN text only; a controlled query belongs to
+  // its owner (see the prop).
   useEffect(() => {
     if (!open) return;
-    setQuery("");
+    if (!controlled) setOwnQuery("");
     setActive(0);
+    // `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
   }, [open]);
 
   // Debounced, race-safe search.

package/src/wizard/stepper-nav.tsx

@@ -1,8 +1,9 @@
 import { useId, useMemo } from "react";
-import type { ReactNode } from "react";
+import type { ReactElement, ReactNode } from "react";
 import { Check } from "lucide-react";
 import { cn } from "../lib/cn";
-import { Button } from "../components/ui";
+import { Button, Spinner } from "../components/ui";
+import type { ButtonVariant } from "../components/ui";
 import { Modal } from "../components/modal";
 import { alertFrameClass } from "../components/alert-banner";
 import { WizardContextProvider } from "./wizard-context";
@@ -25,6 +26,12 @@ import type { UseWizardReturn, WizardLabels } from "./types";
  * The `<StepperNav>` is also what publishes {@link WizardContextProvider}, which
  * is how a mounted step registers its own validator. A step's
  * `useRhfWizardStep` / `useWizardStepValidate` therefore only works inside one.
+ *
+ * Which buttons show is read off `wizard` (`canCancel`, `canGoBack`, `canDone`,
+ * `isCommitStep`), so the policy options — `cancellable`, `onExit`, `commits`,
+ * `onDone` — are all set on `useWizard`. What is set HERE is how the Finish button
+ * looks and what wraps it, because that is presentation and usually depends on
+ * state the app holds (a "replace everything" toggle, a write lock).
  */
 export function StepperNav<TData extends Record<string, unknown>>({
   wizard,
@@ -33,6 +40,9 @@ export function StepperNav<TData extends Record<string, unknown>>({
   description,
   className,
   labels,
+  finishVariant = "brand",
+  finishDisabled = false,
+  renderFinish,
 }: {
   wizard: UseWizardReturn<TData>;
   children: ReactNode;
@@ -40,6 +50,30 @@ export function StepperNav<TData extends Record<string, unknown>>({
   description?: ReactNode;
   className?: string;
   labels?: Partial<WizardLabels>;
+  /** The Finish button's variant — `"danger"` for a destructive commit (an import
+   *  that replaces what is there). Default `"brand"`. Next keeps `"brand"`. */
+  finishVariant?: ButtonVariant;
+  /** Disable Finish for a reason of the app's own, on top of the kit's gates
+   *  (`canFinish`, submitting, validating). */
+  finishDisabled?: boolean;
+  /**
+   * Wrap the Finish button: receives the kit's button element — already labelled,
+   * gated and wired to `wizard.finish` — and returns what to render in its place.
+   *
+   * ```tsx
+   * renderFinish={(button) => <SaveGuard lock={lock}>{button}</SaveGuard>}
+   * ```
+   *
+   * A wrapper and not a replacement (`finishButton: (props) => …`) or a hook
+   * (`onBeforeFinish`): the app's need is to put something AROUND the commit — a
+   * write-lock tooltip, which has to sit on a wrapping element because a disabled
+   * button receives no pointer events — while the kit keeps owning what the button
+   * says and when it is enabled. A replacement would hand every app the gating to
+   * re-derive (the problem this component exists to end); `onBeforeFinish` can veto
+   * a click but cannot explain a disabled button. The element is a plain `<Button>`,
+   * so a wrapper that clones it with `disabled` works as expected.
+   */
+  renderFinish?: (button: ReactElement) => ReactNode;
 }) {
   const l = useKitLabels("wizard", DEFAULT_WIZARD_LABELS, labels);
   const cancelTitleId = useId();
@@ -57,6 +91,51 @@ export function StepperNav<TData extends Record<string, unknown>>({
   // (empty data after a reload) from firing an empty submit.
   const canFinish = wizard.canFinish;
 
+  // Pending while the step's validators run (an async server check): a spinner and
+  // `aria-busy`, and disabled — the hook's own re-entry guard still refuses a second
+  // press, this just stops it looking like the first one did nothing.
+  const pending = wizard.isValidating;
+  const stepNextLabel = wizard.currentStep.nextLabel;
+
+  let forwardButton: ReactNode = null;
+  if (wizard.isCommitStep) {
+    const finishButton = (
+      <Button
+        variant={finishVariant}
+        data-tour="wizard-finish"
+        onClick={wizard.finish}
+        disabled={wizard.isSubmitting || pending || !canFinish || finishDisabled}
+        aria-busy={wizard.isSubmitting || pending || undefined}
+      >
+        {/* Decorative: the button's text is what a reader hears. */}
+        {pending && <Spinner label={null} className="size-4" />}
+        {wizard.isSubmitting ? l.submitting : (stepNextLabel ?? l.finish)}
+      </Button>
+    );
+    forwardButton = renderFinish ? renderFinish(finishButton) : finishButton;
+  } else if (wizard.isLastStep) {
+    // The last step after a commit. Nothing to finish; Done only when the app gave
+    // an `onDone` — otherwise the step carries its own way out.
+    forwardButton = wizard.canDone ? (
+      <Button variant="brand" data-tour="wizard-done" onClick={wizard.done}>
+        {stepNextLabel ?? l.done ?? DEFAULT_WIZARD_LABELS.done}
+      </Button>
+    ) : null;
+  } else {
+    forwardButton = (
+      <Button
+        variant="brand"
+        data-tour="wizard-next"
+        onClick={wizard.goNext}
+        disabled={wizard.nextBlocked || pending}
+        aria-busy={pending || undefined}
+      >
+        {pending && <Spinner label={null} className="size-4" />}
+        {stepNextLabel ?? l.next}
+      </Button>
+    );
+  }
+
   return (
     <div className={cn("flex flex-col gap-6", className)}>
       {(title || description) && (
@@ -84,7 +163,9 @@ export function StepperNav<TData extends Record<string, unknown>>({
                 <button
                   type="button"
                   onClick={() => wizard.goToStep(index)}
-                  disabled={status === "upcoming"}
+                  // `canGoToStep` adds the commit lock: once past a committing step,
+                  // the steps up to it are done with and cannot be reopened.
+                  disabled={status === "upcoming" || !wizard.canGoToStep(index)}
                   aria-current={status === "active" ? "step" : undefined}
                   className={cn(
                     "group flex flex-col items-center gap-1.5",
@@ -161,39 +242,32 @@ export function StepperNav<TData extends Record<string, unknown>>({
 
       {/* Navigation bar */}
       <div className="flex items-center justify-between border-t border-[var(--border)] pt-4">
-        <Button variant="secondary" onClick={wizard.cancel}>
-          {l.cancel}
-        </Button>
+        {/* The empty span keeps the right-hand group on the right when Cancel is off. */}
+        {wizard.canCancel ? (
+          <Button variant="secondary" onClick={wizard.cancel}>
+            {l.cancel}
+          </Button>
+        ) : (
+          <span />
+        )}
         <div className="flex items-center gap-2">
-          {!wizard.isFirstStep && (
-            <Button variant="secondary" onClick={wizard.goBack}>
+          {wizard.canGoBack && (
+            // Disabled, not hidden, while the commit runs: it comes back if the commit
+            // fails, and a button that vanishes mid-click is its own kind of surprise.
+            <Button variant="secondary" onClick={wizard.goBack} disabled={wizard.isSubmitting}>
               {l.back}
             </Button>
           )}
-          {wizard.currentStep.optional && !wizard.isLastStep && (
-            <Button variant="ghost" onClick={wizard.skip} disabled={wizard.nextBlocked}>
-              {l.skip}
-            </Button>
-          )}
-          {wizard.isLastStep ? (
+          {wizard.currentStep.optional && !wizard.isLastStep && !wizard.isCommitStep && (
             <Button
-              variant="brand"
-              data-tour="wizard-finish"
-              onClick={wizard.finish}
-              disabled={wizard.isSubmitting || !canFinish}
+              variant="ghost"
+              onClick={wizard.skip}
+              disabled={wizard.nextBlocked || wizard.isValidating}
             >
-              {wizard.isSubmitting ? l.submitting : l.finish}
-            </Button>
-          ) : (
-            <Button
-              variant="brand"
-              data-tour="wizard-next"
-              onClick={wizard.goNext}
-              disabled={wizard.nextBlocked}
-            >
-              {l.next}
+              {l.skip}
             </Button>
           )}
+          {forwardButton}
         </div>
       </div>
 

package/src/wizard/types.ts

@@ -24,13 +24,83 @@ export interface WizardStepConfig {
    *   per-field error messages via `wizard.fieldErrors`.
    */
   validate?: () => ValidateResult | Promise<ValidateResult>;
+  /**
+   * The forward button's label on THIS step, in place of `labels.next` — "Analyse",
+   * "Import", "Send code". On the committing step (see {@link commits}) it labels
+   * Finish instead of `labels.finish`; `labels.submitting` still replaces it while
+   * the commit runs. Like `label`, a node the app has already translated.
+   */
+  nextLabel?: ReactNode;
+  /**
+   * This step's forward button COMMITS: it runs `onComplete` (via `finish`) instead
+   * of just advancing. Without the flag the last step commits, as it always has.
+   *
+   * Flag a step before the last and every step after it becomes a post-commit step —
+   * an import's "here is what happened, set up recurring rules?" page:
+   *  - a successful `onComplete` advances onto the next step (a failed one stays, with
+   *    `wizard.error`, exactly like a last-step Finish);
+   *  - from there Back, the indicator and `goBack`/`goToStep` cannot cross back over
+   *    the commit, and Cancel is hidden — there is nothing left to discard;
+   *  - the last post-commit step's button is Done, which calls `onDone` (and is not
+   *    shown when there is no `onDone`: the step then carries its own way out).
+   *
+   * Only the FIRST flagged step counts. Steps after it may still validate, skip and
+   * use `nextLabel` like any other.
+   */
+  commits?: boolean;
 }
 
+/**
+ * Where the active step lives. `true` (the default) mirrors it to `?step=N` through
+ * react-router, as every wizard before 0.8 did; `{ param }` renames that param (two
+ * wizards on one page, or a page that already uses `step`); `false` keeps it in
+ * memory only and needs no router at all.
+ *
+ * Read once, at mount: switching it on a mounted wizard has no effect.
+ */
+export type WizardUrlSync = boolean | { param?: string };
+
 export interface UseWizardOptions<TData extends Record<string, unknown>> {
   steps: WizardStepConfig[];
   initialData?: Partial<TData>;
   onComplete?: (data: TData) => void | Promise<void>;
   onCancel?: () => void;
+  /**
+   * Leave the wizard BACKWARDS: when given, Back is shown on the first step too and
+   * calls this — keksdose's import panel, whose first step's Back returns to the
+   * dropzone the file came from. No confirm dialog: going back is not discarding.
+   */
+  onExit?: () => void;
+  /**
+   * The Done button on the last step after a committing step (see
+   * {@link WizardStepConfig.commits}). Without it no Done button is rendered, and the
+   * post-commit step is expected to carry its own way out.
+   */
+  onDone?: () => void;
+  /**
+   * Whether the chrome offers Cancel at all. Default `true`. `false` hides the button
+   * (`wizard.canCancel` is false); `wizard.cancel()` still works if the app calls it.
+   */
+  cancellable?: boolean;
+  /**
+   * Whether Cancel asks first ("Discard this form?"). Default `true`. `false` makes
+   * `cancel()` call `onCancel` straight away — for a wizard that has nothing to lose
+   * yet, or one whose data is kept elsewhere.
+   */
+  confirmCancel?: boolean;
+  /**
+   * Mirror the active step to the URL. Default `true` (`?step=N`, needs a router).
+   * See {@link WizardUrlSync}.
+   *
+   * The param is WRITTEN only, never read back (see the note in `use-wizard.ts`). It
+   * is removed again when the wizard is left through the kit: a confirmed Cancel,
+   * `onExit` from the first step's Back, and Done — each before the app's callback
+   * runs, so an app that navigates away navigates from a clean URL. It is NOT removed
+   * after `onComplete` on a last step: an app navigating away there would otherwise
+   * be pulled back by the kit's own URL write. An app that stays on the page after a
+   * final Finish drops the param itself, or uses `urlSync: false`.
+   */
+  urlSync?: WizardUrlSync;
   /**
    * Shown when a step blocks with no per-field detail — an RHF step surfacing
    * its own inline messages, say — so the user learns why the wizard did not
@@ -55,14 +125,35 @@ export interface UseWizardReturn<TData extends Record<string, unknown>> {
   steps: WizardStepConfig[];
   isFirstStep: boolean;
   isLastStep: boolean;
-  /** True once every step before the last has been completed or skipped. */
+  /** True once every step before the committing one (the last, unless a step is
+   *  flagged `commits`) has been completed or skipped. */
   canFinish: boolean;
+  /** The step whose forward button commits: the first `commits` step, else the last. */
+  commitStepIndex: number;
+  /** The active step is {@link commitStepIndex}: the chrome shows Finish, not Next. */
+  isCommitStep: boolean;
+  /** `onComplete` has resolved. Once the active step is past the committing one, Back
+   *  cannot cross it and Cancel is hidden. */
+  committed: boolean;
+  /** Whether Back is offered here: not on the first step unless `onExit` was given,
+   *  and never back across a commit. (Disabled, not hidden, while `isSubmitting`.) */
+  canGoBack: boolean;
+  /** Whether Cancel is offered: `cancellable`, and not after a commit. */
+  canCancel: boolean;
+  /** Whether Done is offered: the last step, past a commit, with an `onDone`. */
+  canDone: boolean;
+  /** Whether the indicator may jump to `index` — a completed/skipped/active step on
+   *  the right side of any commit. `goToStep` refuses anything this rejects. */
+  canGoToStep: (index: number) => boolean;
   goNext: () => Promise<void>;
+  /** One step back — or, on the first step, `onExit`. Refused while submitting. */
   goBack: () => void;
   goToStep: (index: number) => void;
   skip: () => void;
   cancel: () => void;
   finish: () => Promise<void>;
+  /** Leave after the post-commit steps: drops the URL param, then calls `onDone`. */
+  done: () => void;
   /** Register a validator for the mounted step (used by useRhfWizardStep). */
   registerStepValidate: (
     fn: () => ValidateResult | Promise<ValidateResult>,
@@ -82,6 +173,9 @@ export interface UseWizardReturn<TData extends Record<string, unknown>> {
 
   // Loading / error
   isSubmitting: boolean;
+  /** A `goNext`/`finish` is running the step's validators (an async server check,
+   *  say). The chrome shows Next pending — spinner, `aria-busy`, disabled. */
+  isValidating: boolean;
   error: string | null;
   clearError: () => void;
 
@@ -102,8 +196,12 @@ export interface SummaryItem {
 
 export interface SummarySection {
   label: ReactNode;
-  /** Which step the section's edit button jumps back to. */
-  stepIndex: number;
+  /**
+   * Which step the section's edit button jumps back to. Leave it out for a section
+   * that belongs to no step — file-level counts, a total — and the card has no edit
+   * button, instead of borrowing one from whichever step it was parked under.
+   */
+  stepIndex?: number;
   items: SummaryItem[];
 }
 
@@ -149,12 +247,15 @@ export interface WizardLabels {
   /** `wizard.error` when `onComplete` rejects with nothing readable — a thrown
    *  non-Error, or an Error whose message is empty. Optional: see above. */
   genericError?: string;
+  /** The button on the last step after a committing step (`onDone`). Optional: see
+   *  `missingRequired`. */
+  done?: string;
 }
 
 /** Typed with the two optional keys made required, so code reading the defaults
  *  directly (the fallback in `useWizard`) needs no `!`. */
 export const DEFAULT_WIZARD_LABELS: WizardLabels &
-  Required<Pick<WizardLabels, "missingRequired" | "genericError">> = {
+  Required<Pick<WizardLabels, "missingRequired" | "genericError" | "done">> = {
   cancel: "Cancel",
   back: "Back",
   next: "Next",
@@ -171,6 +272,7 @@ export const DEFAULT_WIZARD_LABELS: WizardLabels &
   edit: "Edit",
   missingRequired: "Please fill in all required fields.",
   genericError: "An error occurred",
+  done: "Done",
 };
 
 export function resolveWizardLabels(labels?: Partial<WizardLabels>): WizardLabels {