@eifi1/ui-kit 0.4.1 → 0.5.0

package/src/wizard/stepper-nav.tsx

@@ -0,0 +1,221 @@
+import { useId, useMemo } from "react";
+import type { ReactNode } from "react";
+import { Check } from "lucide-react";
+import { cn } from "../lib/cn";
+import { Button } from "../components/ui";
+import { Modal } from "../components/modal";
+import { alertFrameClass } from "../components/alert-banner";
+import { WizardContextProvider } from "./wizard-context";
+import { DEFAULT_WIZARD_LABELS } from "./types";
+import { useKitLabels } from "../i18n/kit-labels";
+import type { UseWizardReturn, WizardLabels } from "./types";
+
+/**
+ * The chrome around a wizard: the step indicator, the step content, and the
+ * Cancel / Back / Skip / Next / Finish bar — plus the cancel-confirmation
+ * dialog, because "are you sure you want to lose this" is part of the wizard's
+ * contract rather than something each app should re-decide.
+ *
+ * It is a component and not a set of parts for one reason: which button shows,
+ * and whether it is enabled, is a function of `wizard` state that was getting
+ * re-derived (and re-derived slightly differently) at every call site. Finish is
+ * gated on `canFinish`, Next and Skip on `nextBlocked`, and Skip only appears on
+ * an `optional` step that is not the last — that policy lives here now.
+ *
+ * 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.
+ */
+export function StepperNav<TData extends Record<string, unknown>>({
+  wizard,
+  children,
+  title,
+  description,
+  className,
+  labels,
+}: {
+  wizard: UseWizardReturn<TData>;
+  children: ReactNode;
+  title?: ReactNode;
+  description?: ReactNode;
+  className?: string;
+  labels?: Partial<WizardLabels>;
+}) {
+  const l = useKitLabels("wizard", DEFAULT_WIZARD_LABELS, labels);
+  const cancelTitleId = useId();
+
+  const contextValue = useMemo(
+    () => ({
+      registerStepValidate: wizard.registerStepValidate,
+      setNextBlocked: wizard.setNextBlocked,
+    }),
+    [wizard.registerStepValidate, wizard.setNextBlocked],
+  );
+
+  // Finish is only valid once every step before the last has been completed or
+  // skipped (derived once in useWizard). Prevents a restored last-step index
+  // (empty data after a reload) from firing an empty submit.
+  const canFinish = wizard.canFinish;
+
+  return (
+    <div className={cn("flex flex-col gap-6", className)}>
+      {(title || description) && (
+        <div>
+          {title && (
+            <h1 className="text-2xl font-bold tracking-tight text-[var(--text-primary)]">
+              {title}
+            </h1>
+          )}
+          {description && (
+            <p className="mt-1 text-sm text-[var(--text-muted)]">{description}</p>
+          )}
+        </div>
+      )}
+
+      {/* Step indicator */}
+      <nav aria-label={l.steps}>
+        <ol className="flex w-full items-center">
+          {wizard.steps.map((step, index) => {
+            const status = wizard.stepStatus(index);
+            const isLast = index === wizard.steps.length - 1;
+
+            return (
+              <li key={step.id} className={cn("flex items-center", !isLast && "flex-1")}>
+                <button
+                  type="button"
+                  onClick={() => wizard.goToStep(index)}
+                  disabled={status === "upcoming"}
+                  aria-current={status === "active" ? "step" : undefined}
+                  className={cn(
+                    "group flex flex-col items-center gap-1.5",
+                    status === "upcoming" ? "cursor-default" : "cursor-pointer",
+                  )}
+                >
+                  {/* Circle */}
+                  <span
+                    className={cn(
+                      "flex size-8 shrink-0 items-center justify-center rounded-full border-2 text-xs font-semibold transition-colors",
+                      status === "completed" &&
+                        "border-[var(--brand)] bg-[var(--brand)] text-[var(--brand-contrast)]",
+                      status === "active" &&
+                        "border-[var(--brand)] bg-[var(--bg-surface)] text-[var(--brand)]",
+                      status === "upcoming" &&
+                        "border-[var(--border)] bg-[var(--bg-surface)] text-[var(--text-placeholder)]",
+                      status === "skipped" &&
+                        "border-[var(--border)] bg-[var(--bg-surface-2)] text-[var(--text-muted)]",
+                    )}
+                  >
+                    {status === "completed" ? <Check className="size-4" /> : index + 1}
+                  </span>
+                  {/* Label — hidden on mobile, where the line below carries it */}
+                  <span
+                    className={cn(
+                      "hidden text-xs font-medium md:block",
+                      status === "active" || status === "completed"
+                        ? "text-[var(--text-primary)]"
+                        : "text-[var(--text-muted)]",
+                    )}
+                  >
+                    {step.label}
+                  </span>
+                </button>
+
+                {/* Connector line */}
+                {!isLast && (
+                  <div
+                    className={cn(
+                      "mx-2 h-0.5 flex-1",
+                      status === "completed" ? "bg-[var(--brand)]" : "bg-[var(--border)]",
+                    )}
+                  />
+                )}
+              </li>
+            );
+          })}
+        </ol>
+        {/* Mobile: the labels above are hidden, so name the current step here */}
+        <p className="mt-2 text-center text-sm font-medium text-[var(--text-primary)] md:hidden">
+          {l.step(wizard.currentStepIndex + 1, wizard.steps.length)}
+          {" — "}
+          {wizard.currentStep.label}
+        </p>
+      </nav>
+
+      {/* Step content */}
+      <WizardContextProvider value={contextValue}>
+        <div className="min-h-[300px]">{children}</div>
+      </WizardContextProvider>
+
+      {/* Submit error */}
+      {wizard.error && (
+        <div
+          role="alert"
+          className={cn(
+            "text-sm text-[var(--danger)]",
+            alertFrameClass("danger"),
+          )}
+        >
+          {wizard.error}
+        </div>
+      )}
+
+      {/* 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>
+        <div className="flex items-center gap-2">
+          {!wizard.isFirstStep && (
+            <Button variant="secondary" onClick={wizard.goBack}>
+              {l.back}
+            </Button>
+          )}
+          {wizard.currentStep.optional && !wizard.isLastStep && (
+            <Button variant="ghost" onClick={wizard.skip} disabled={wizard.nextBlocked}>
+              {l.skip}
+            </Button>
+          )}
+          {wizard.isLastStep ? (
+            <Button
+              variant="brand"
+              data-tour="wizard-finish"
+              onClick={wizard.finish}
+              disabled={wizard.isSubmitting || !canFinish}
+            >
+              {wizard.isSubmitting ? l.submitting : l.finish}
+            </Button>
+          ) : (
+            <Button
+              variant="brand"
+              data-tour="wizard-next"
+              onClick={wizard.goNext}
+              disabled={wizard.nextBlocked}
+            >
+              {l.next}
+            </Button>
+          )}
+        </div>
+      </div>
+
+      {/* Cancel confirmation */}
+      {wizard.showCancelDialog && (
+        <Modal onClose={wizard.dismissCancel} labelledBy={cancelTitleId} className="space-y-4">
+          <div className="space-y-1.5">
+            <h2 id={cancelTitleId} className="text-lg font-semibold text-[var(--text-primary)]">
+              {l.cancelTitle}
+            </h2>
+            <p className="text-sm text-[var(--text-muted)]">{l.confirmCancel}</p>
+          </div>
+          <div className="flex flex-col-reverse gap-2 sm:flex-row sm:justify-end">
+            <Button variant="secondary" onClick={wizard.dismissCancel}>
+              {l.cancelDismissLabel}
+            </Button>
+            <Button variant="danger" onClick={wizard.confirmCancel}>
+              {l.cancelConfirmLabel}
+            </Button>
+          </div>
+        </Modal>
+      )}
+    </div>
+  );
+}

package/src/wizard/types.ts

@@ -0,0 +1,178 @@
+import type { ReactNode } from "react";
+
+export type FieldErrors = Record<string, string>;
+
+export type ValidateResult = boolean | { ok: boolean; errors?: FieldErrors };
+
+export interface WizardStepConfig {
+  /** Unique step identifier. */
+  id: string;
+  /**
+   * What the step is called in the indicator.
+   *
+   * A `ReactNode`, not a translation key: the engine never resolves strings.
+   * An app with i18n maps its own keys at the `useWizard` call — the same split
+   * `TourStep` and `DataTableLabels` already use.
+   */
+  label: ReactNode;
+  /** Whether the step can be skipped. */
+  optional?: boolean;
+  /**
+   * Validation gate before advancing.
+   * - Return `true` / `false` to just block.
+   * - Return `{ ok: false, errors: { fieldName: "message" } }` to also surface
+   *   per-field error messages via `wizard.fieldErrors`.
+   */
+  validate?: () => ValidateResult | Promise<ValidateResult>;
+}
+
+export interface UseWizardOptions<TData extends Record<string, unknown>> {
+  steps: WizardStepConfig[];
+  initialData?: Partial<TData>;
+  onComplete?: (data: TData) => void | Promise<void>;
+  onCancel?: () => void;
+  /**
+   * 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
+   * advance. Falls back to `wizard.missingRequired` from the {@link UiKitProvider},
+   * then to English.
+   */
+  missingRequiredMessage?: string;
+  /**
+   * How to surface {@link missingRequiredMessage}. Defaults to a `sonner` toast
+   * (an optional peer, imported only when this actually fires). Pass your own to
+   * route it somewhere else, or to a no-op to silence it.
+   */
+  onValidationFailed?: (message: string) => void;
+}
+
+export type StepStatus = "upcoming" | "active" | "completed" | "skipped";
+
+export interface UseWizardReturn<TData extends Record<string, unknown>> {
+  // Navigation
+  currentStepIndex: number;
+  currentStep: WizardStepConfig;
+  steps: WizardStepConfig[];
+  isFirstStep: boolean;
+  isLastStep: boolean;
+  /** True once every step before the last has been completed or skipped. */
+  canFinish: boolean;
+  goNext: () => Promise<void>;
+  goBack: () => void;
+  goToStep: (index: number) => void;
+  skip: () => void;
+  cancel: () => void;
+  finish: () => Promise<void>;
+  /** Register a validator for the mounted step (used by useRhfWizardStep). */
+  registerStepValidate: (
+    fn: () => ValidateResult | Promise<ValidateResult>,
+  ) => () => void;
+  /** True when the mounted step has blocked forward navigation (Next/Skip disabled). */
+  nextBlocked: boolean;
+  /** Set by the active step (via useWizardNextGate) to disable/enable Next+Skip. */
+  setNextBlocked: (blocked: boolean) => void;
+
+  // Step state
+  stepStatus: (index: number) => StepStatus;
+  completedSteps: Set<number>;
+
+  // Data
+  data: TData;
+  updateData: (partial: Partial<TData>) => void;
+
+  // Loading / error
+  isSubmitting: boolean;
+  error: string | null;
+  clearError: () => void;
+
+  // Per-field validation errors (populated by the last failed goNext)
+  fieldErrors: FieldErrors;
+  clearFieldErrors: () => void;
+
+  // Cancel dialog
+  showCancelDialog: boolean;
+  confirmCancel: () => void;
+  dismissCancel: () => void;
+}
+
+export interface SummaryItem {
+  label: ReactNode;
+  value: ReactNode;
+}
+
+export interface SummarySection {
+  label: ReactNode;
+  /** Which step the section's edit button jumps back to. */
+  stepIndex: number;
+  items: SummaryItem[];
+}
+
+/**
+ * Every string the wizard chrome shows. All optional with English defaults, so a
+ * monolingual app can mount `StepperNav` bare; a translated app passes the whole
+ * object once (typically from a thin app-side wrapper).
+ */
+export interface WizardLabels {
+  cancel: string;
+  back: string;
+  next: string;
+  skip: string;
+  finish: string;
+  /** Shown on Finish while `isSubmitting`. */
+  submitting: string;
+  /** `aria-label` for the step indicator's `<nav>`. */
+  steps: string;
+  /** The mobile "Step 2 of 5" line. */
+  step: (current: number, total: number) => string;
+  /** Heading of the cancel-confirmation dialog. */
+  cancelTitle: string;
+  /** Body of the cancel-confirmation dialog. */
+  confirmCancel: string;
+  /** Confirm button in the cancel dialog. */
+  cancelConfirmLabel: string;
+  /** Dismiss button in the cancel dialog ("keep editing"). */
+  cancelDismissLabel: string;
+  /** Heading above a {@link WizardSummary}. */
+  reviewTitle: string;
+  /** `aria-label` on a summary section's edit button. */
+  edit: string;
+  /**
+   * Toasted (or handed to `onValidationFailed`) when a step blocks Next without
+   * saying which field is at fault. `useWizard`'s `missingRequiredMessage` wins.
+   *
+   * This and `genericError` are OPTIONAL, unlike every key above, for the reason
+   * `TwoFactorSettingLabels.qrAlt` is: apps annotate a full translation as
+   * `const DE: WizardLabels = {…}`, and a new required key would be a compile error
+   * in each of them on the next update. The defaults below always carry both.
+   */
+  missingRequired?: string;
+  /** `wizard.error` when `onComplete` rejects with nothing readable — a thrown
+   *  non-Error, or an Error whose message is empty. Optional: see above. */
+  genericError?: 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">> = {
+  cancel: "Cancel",
+  back: "Back",
+  next: "Next",
+  skip: "Skip",
+  finish: "Finish",
+  submitting: "Creating…",
+  steps: "Steps",
+  step: (current, total) => `Step ${current} of ${total}`,
+  cancelTitle: "Discard this form?",
+  confirmCancel: "Your entries will be lost.",
+  cancelConfirmLabel: "Discard",
+  cancelDismissLabel: "Keep editing",
+  reviewTitle: "Review",
+  edit: "Edit",
+  missingRequired: "Please fill in all required fields.",
+  genericError: "An error occurred",
+};
+
+export function resolveWizardLabels(labels?: Partial<WizardLabels>): WizardLabels {
+  return labels ? { ...DEFAULT_WIZARD_LABELS, ...labels } : DEFAULT_WIZARD_LABELS;
+}