{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "form-workflow",
  "title": "FormWorkflow",
  "description": "A validated, recoverable form workflow with server errors, autosave, unsaved-change warnings, and multi-step flows.",
  "dependencies": [
    "@hookform/resolvers@^5.8.0",
    "react-hook-form@^7.85.0",
    "zod@^4.4.3"
  ],
  "files": [
    {
      "path": "registry/form-workflow/form-workflow.tsx",
      "content": "\"use client\"\n\nimport { zodResolver } from \"@hookform/resolvers/zod\"\nimport {\n  Children,\n  isValidElement,\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n  type CSSProperties,\n  type ReactNode,\n} from \"react\"\nimport {\n  FormProvider,\n  useForm,\n  useWatch,\n  type DefaultValues,\n  type FieldErrors,\n  type FieldPath,\n  type FieldValues,\n} from \"react-hook-form\"\nimport { z } from \"zod\"\n\nexport interface FormSubmissionResult {\n  success: boolean\n  message?: string\n  fieldErrors?: Record<string, string>\n  formError?: string\n}\n\nexport interface FormAutosaveConfig<TValues> {\n  onSave: (values: TValues) => Promise<FormSubmissionResult | void>\n  delay?: number\n  enabled?: boolean\n}\n\nexport interface FormWorkflowProps<\n  TInput extends FieldValues,\n  TOutput extends FieldValues = TInput,\n> {\n  schema: z.ZodType<TOutput, TInput>\n  defaultValues: TInput\n  onSubmit: (values: TOutput) => Promise<FormSubmissionResult>\n  children: ReactNode\n  mode?: \"single\" | \"multi-step\"\n  autosave?: FormAutosaveConfig<TOutput>\n  warnOnUnsavedChanges?: boolean\n  successBehavior?: \"message\" | \"reset\" | \"preserve\"\n}\n\nexport interface FormWorkflowStepProps {\n  title: string\n  children: ReactNode\n  description?: string\n  fields?: string[]\n}\n\ntype AutosaveStatus = \"idle\" | \"saving\" | \"saved\" | \"error\"\ntype SubmissionStatus = \"idle\" | \"submitting\" | \"success\" | \"error\"\n\nfunction fieldErrorEntries(errors: FieldErrors): Array<[string, string]> {\n  const entries: Array<[string, string]> = []\n\n  const visit = (value: unknown, path: string) => {\n    if (!value || typeof value !== \"object\") return\n    const candidate = value as Record<string, unknown>\n    if (typeof candidate.message === \"string\") {\n      entries.push([path, candidate.message])\n      return\n    }\n    Object.entries(candidate).forEach(([key, child]) => {\n      if (key === \"ref\" || key === \"type\" || key === \"types\") return\n      visit(child, path ? `${path}.${key}` : key)\n    })\n  }\n\n  Object.entries(errors).forEach(([key, value]) => visit(value, key))\n  return entries\n}\n\nexport function FormWorkflowStep({\n  title,\n  description,\n  children,\n}: FormWorkflowStepProps) {\n  return (\n    <fieldset className=\"grid min-w-0 gap-5 border-0 p-0\">\n      <legend className=\"text-lg font-semibold\">{title}</legend>\n      {description ? (\n        <p className=\"text-muted-foreground -mt-3 text-sm\">{description}</p>\n      ) : null}\n      {children}\n    </fieldset>\n  )\n}\n\nfunction getStepFields(step: ReactNode) {\n  if (!isValidElement<FormWorkflowStepProps>(step)) return []\n  return step.props.fields ?? []\n}\n\nfunction getStepTitle(step: ReactNode, index: number) {\n  if (!isValidElement<FormWorkflowStepProps>(step)) return `Step ${index + 1}`\n  return step.props.title\n}\n\nexport function FormWorkflow<\n  TInput extends FieldValues,\n  TOutput extends FieldValues = TInput,\n>({\n  schema,\n  defaultValues,\n  onSubmit,\n  children,\n  mode = \"single\",\n  autosave,\n  warnOnUnsavedChanges = false,\n  successBehavior = \"message\",\n}: FormWorkflowProps<TInput, TOutput>) {\n  const form = useForm<TInput, unknown, TOutput>({\n    resolver: zodResolver<TInput, unknown, TOutput>(schema),\n    defaultValues: defaultValues as DefaultValues<TInput>,\n    shouldFocusError: false,\n  })\n  const {\n    control,\n    formState,\n    getValues,\n    handleSubmit,\n    reset,\n    setError,\n    trigger,\n  } = form\n  const values = useWatch({ control })\n  const steps = useMemo(() => Children.toArray(children), [children])\n  const [currentStep, setCurrentStep] = useState(0)\n  const [formError, setFormError] = useState<string>()\n  const [successMessage, setSuccessMessage] = useState<string>()\n  const [submissionStatus, setSubmissionStatus] =\n    useState<SubmissionStatus>(\"idle\")\n  const [autosaveStatus, setAutosaveStatus] = useState<AutosaveStatus>(\"idle\")\n  const [autosaveError, setAutosaveError] = useState<string>()\n  const summaryRef = useRef<HTMLDivElement>(null)\n  const submitInFlight = useRef(false)\n  const autosaveInFlight = useRef(false)\n  const autosaveTimer = useRef<number | undefined>(undefined)\n  const mounted = useRef(false)\n\n  const isMultiStep = mode === \"multi-step\" && steps.length > 1\n  const visibleContent = isMultiStep ? steps[currentStep] : children\n  const errorEntries = fieldErrorEntries(formState.errors)\n  const hasErrors = Boolean(formError) || errorEntries.length > 0\n\n  const focusSummary = useCallback(() => {\n    window.requestAnimationFrame(() => summaryRef.current?.focus())\n  }, [])\n\n  const clearMessages = () => {\n    setFormError(undefined)\n    setSuccessMessage(undefined)\n    setSubmissionStatus(\"idle\")\n  }\n\n  const applySubmissionFailure = useCallback(\n    (result: FormSubmissionResult) => {\n      Object.entries(result.fieldErrors ?? {}).forEach(([field, message]) =>\n        setError(field as FieldPath<TInput>, {\n          type: \"server\",\n          message,\n        }),\n      )\n      setFormError(\n        result.formError ??\n          (Object.keys(result.fieldErrors ?? {}).length === 0\n            ? (result.message ?? \"The form could not be saved.\")\n            : undefined),\n      )\n      setSubmissionStatus(\"error\")\n      focusSummary()\n    },\n    [focusSummary, setError],\n  )\n\n  const submitValid = async (submittedValues: TOutput) => {\n    if (submitInFlight.current) return\n    submitInFlight.current = true\n    setSubmissionStatus(\"submitting\")\n    setFormError(undefined)\n    setSuccessMessage(undefined)\n\n    try {\n      const result = await onSubmit(submittedValues)\n      if (!result.success) {\n        applySubmissionFailure(result)\n        return\n      }\n\n      const message = result.message ?? \"Changes saved.\"\n      setSuccessMessage(message)\n      setSubmissionStatus(\"success\")\n      if (successBehavior === \"reset\") {\n        reset(defaultValues as DefaultValues<TInput>)\n        setCurrentStep(0)\n      } else {\n        reset(getValues() as DefaultValues<TInput>, { keepValues: true })\n      }\n    } catch {\n      applySubmissionFailure({\n        success: false,\n        formError: \"The form could not be saved. Try again.\",\n      })\n    } finally {\n      submitInFlight.current = false\n    }\n  }\n\n  const submitInvalid = (errors: FieldErrors<TInput>) => {\n    setSubmissionStatus(\"error\")\n    setFormError(undefined)\n    if (isMultiStep) {\n      const firstError = fieldErrorEntries(errors)[0]?.[0]\n      const errorStep = steps.findIndex((step) =>\n        getStepFields(step).some(\n          (field) =>\n            firstError === field || firstError?.startsWith(`${field}.`),\n        ),\n      )\n      if (errorStep >= 0) setCurrentStep(errorStep)\n    }\n    focusSummary()\n  }\n\n  const saveDraft = useCallback(async () => {\n    if (\n      !autosave ||\n      autosave.enabled === false ||\n      autosaveInFlight.current ||\n      submitInFlight.current\n    ) {\n      return\n    }\n\n    const parsed = schema.safeParse(getValues())\n    if (!parsed.success) return\n\n    autosaveInFlight.current = true\n    setAutosaveStatus(\"saving\")\n    setAutosaveError(undefined)\n    try {\n      const result = await autosave.onSave(parsed.data)\n      if (result && !result.success) {\n        setAutosaveStatus(\"error\")\n        setAutosaveError(\n          result.formError ?? result.message ?? \"Draft could not be saved.\",\n        )\n        return\n      }\n      setAutosaveStatus(\"saved\")\n      reset(getValues() as DefaultValues<TInput>, { keepValues: true })\n    } catch {\n      setAutosaveStatus(\"error\")\n      setAutosaveError(\"Draft could not be saved.\")\n    } finally {\n      autosaveInFlight.current = false\n    }\n  }, [autosave, getValues, reset, schema])\n\n  useEffect(() => {\n    if (!mounted.current) {\n      mounted.current = true\n      return\n    }\n    if (\n      !autosave ||\n      autosave.enabled === false ||\n      !formState.isDirty ||\n      formState.isSubmitting\n    ) {\n      return\n    }\n\n    if (autosaveTimer.current) window.clearTimeout(autosaveTimer.current)\n    autosaveTimer.current = window.setTimeout(\n      () => void saveDraft(),\n      autosave.delay ?? 800,\n    )\n    return () => {\n      if (autosaveTimer.current) window.clearTimeout(autosaveTimer.current)\n    }\n  }, [autosave, formState.isDirty, formState.isSubmitting, saveDraft, values])\n\n  useEffect(() => {\n    if (!warnOnUnsavedChanges || !formState.isDirty) return\n\n    const beforeUnload = (event: BeforeUnloadEvent) => {\n      event.preventDefault()\n      event.returnValue = \"\"\n    }\n    const click = (event: MouseEvent) => {\n      const target = event.target\n      if (!(target instanceof Element)) return\n      const anchor = target.closest(\"a[href]\")\n      if (!anchor || anchor.getAttribute(\"target\") === \"_blank\") return\n      if (!window.confirm(\"You have unsaved changes. Leave this page?\")) {\n        event.preventDefault()\n        event.stopPropagation()\n      }\n    }\n\n    window.addEventListener(\"beforeunload\", beforeUnload)\n    document.addEventListener(\"click\", click, true)\n    return () => {\n      window.removeEventListener(\"beforeunload\", beforeUnload)\n      document.removeEventListener(\"click\", click, true)\n    }\n  }, [formState.isDirty, warnOnUnsavedChanges])\n\n  const nextStep = async () => {\n    const fields = getStepFields(steps[currentStep]) as FieldPath<TInput>[]\n    const valid = fields.length === 0 ? true : await trigger(fields)\n    if (!valid) {\n      setSubmissionStatus(\"error\")\n      focusSummary()\n      return\n    }\n    clearMessages()\n    setCurrentStep((step) => Math.min(step + 1, steps.length - 1))\n  }\n\n  return (\n    <FormProvider {...form}>\n      <form\n        className=\"grid min-w-0 gap-6\"\n        data-mode={mode}\n        data-slot=\"form-workflow\"\n        noValidate\n        onChange={clearMessages}\n        onSubmit={(event) =>\n          void handleSubmit(submitValid, submitInvalid)(event)\n        }\n      >\n        {isMultiStep ? (\n          <div className=\"grid gap-2\" aria-label=\"Form progress\">\n            <p className=\"text-muted-foreground m-0 font-mono text-xs\">\n              Step {currentStep + 1} of {steps.length}\n            </p>\n            <ol\n              className=\"grid list-none grid-cols-[repeat(var(--step-count),minmax(0,1fr))] gap-2 p-0\"\n              style={{ \"--step-count\": steps.length } as CSSProperties}\n            >\n              {steps.map((step, index) => (\n                <li\n                  aria-current={index === currentStep ? \"step\" : undefined}\n                  className=\"bg-muted data-[complete=true]:bg-primary data-[current=true]:bg-primary h-1.5 rounded-full\"\n                  data-complete={index < currentStep}\n                  data-current={index === currentStep}\n                  key={`${getStepTitle(step, index)}-${index}`}\n                >\n                  <span className=\"sr-only\">\n                    {getStepTitle(step, index)}\n                    {index === currentStep ? \", current step\" : \"\"}\n                  </span>\n                </li>\n              ))}\n            </ol>\n          </div>\n        ) : null}\n\n        {hasErrors ? (\n          <div\n            aria-labelledby=\"form-workflow-errors-title\"\n            className=\"border-destructive/40 bg-destructive/5 text-foreground rounded-lg border p-5\"\n            data-slot=\"form-workflow-error-summary\"\n            ref={summaryRef}\n            role=\"alert\"\n            tabIndex={-1}\n          >\n            <h2\n              className=\"m-0 text-base font-semibold\"\n              id=\"form-workflow-errors-title\"\n            >\n              Check the form\n            </h2>\n            {formError ? (\n              <p className=\"mt-2 mb-0 text-sm\">{formError}</p>\n            ) : null}\n            {errorEntries.length > 0 ? (\n              <ul className=\"mt-3 mb-0 grid gap-1 pl-5 text-sm\">\n                {errorEntries.map(([field, message]) => (\n                  <li key={field}>\n                    <button\n                      className=\"focus-visible:ring-ring rounded text-left hover:underline focus-visible:ring-2\"\n                      onClick={() => form.setFocus(field as FieldPath<TInput>)}\n                      type=\"button\"\n                    >\n                      {message}\n                    </button>\n                  </li>\n                ))}\n              </ul>\n            ) : null}\n          </div>\n        ) : null}\n\n        {visibleContent}\n\n        {autosave ? (\n          <div\n            aria-live=\"polite\"\n            className=\"text-muted-foreground flex min-h-11 items-center justify-between gap-4 rounded-md border px-4 text-sm\"\n            data-status={autosaveStatus}\n          >\n            <span>\n              {autosaveStatus === \"saving\"\n                ? \"Saving draft…\"\n                : autosaveStatus === \"saved\"\n                  ? \"Draft saved\"\n                  : autosaveStatus === \"error\"\n                    ? autosaveError\n                    : \"Changes save automatically\"}\n            </span>\n            {autosaveStatus === \"error\" ? (\n              <button\n                className=\"hover:bg-muted focus-visible:ring-ring min-h-9 rounded-md border px-3 font-semibold focus-visible:ring-2\"\n                onClick={() => void saveDraft()}\n                type=\"button\"\n              >\n                Retry autosave\n              </button>\n            ) : null}\n          </div>\n        ) : null}\n\n        {submissionStatus === \"success\" && successMessage ? (\n          <p\n            aria-live=\"polite\"\n            className=\"border-primary/30 bg-primary/5 m-0 rounded-md border p-4 text-sm font-medium\"\n            role=\"status\"\n          >\n            {successMessage}\n          </p>\n        ) : null}\n\n        <div className=\"flex items-center justify-between gap-3 max-sm:flex-col-reverse max-sm:items-stretch\">\n          {isMultiStep && currentStep > 0 ? (\n            <button\n              className=\"bg-background hover:bg-muted focus-visible:ring-ring min-h-11 rounded-md border px-4 font-semibold focus-visible:ring-2\"\n              onClick={() => {\n                clearMessages()\n                setCurrentStep((step) => Math.max(0, step - 1))\n              }}\n              type=\"button\"\n            >\n              Previous step\n            </button>\n          ) : (\n            <span />\n          )}\n\n          {isMultiStep && currentStep < steps.length - 1 ? (\n            <button\n              className=\"bg-primary text-primary-foreground hover:bg-primary/90 focus-visible:ring-ring min-h-11 rounded-md px-4 font-semibold focus-visible:ring-2\"\n              onClick={(event) => {\n                event.preventDefault()\n                void nextStep()\n              }}\n              type=\"button\"\n            >\n              Continue\n            </button>\n          ) : (\n            <button\n              className=\"bg-primary text-primary-foreground hover:bg-primary/90 focus-visible:ring-ring min-h-11 rounded-md px-4 font-semibold focus-visible:ring-2 disabled:cursor-not-allowed disabled:opacity-55\"\n              disabled={\n                formState.isSubmitting || submissionStatus === \"submitting\"\n              }\n              type=\"submit\"\n            >\n              {formState.isSubmitting || submissionStatus === \"submitting\"\n                ? \"Saving…\"\n                : \"Save changes\"}\n            </button>\n          )}\n        </div>\n      </form>\n    </FormProvider>\n  )\n}\n",
      "type": "registry:component",
      "target": "components/form-workflow.tsx"
    }
  ],
  "type": "registry:component"
}