@trackunit/react-form-wizard 1.10.18 → 1.10.19

package/index.cjs.js

@@ -356,20 +356,108 @@ const cvaFormWizardLayout = cssClassVarianceUtilities.cvaMerge([
 const cvaStepContainer = cssClassVarianceUtilities.cvaMerge(["h-full", "grid", "bg-white", "overflow-hidden"]);
 
 /**
- * The FormWizard component is used for forms in multiple steps.
- * Use the useFormWizard hook to generate the props for this component.
+ * The `<FormWizard>` component renders multi-step forms with a sidebar navigation.
+ * Use the `useFormWizard` hook to generate the props for this component.
  *
- * The useFormWizard hook takes a form schema which is a zod schema that contains all the steps.
- * Each step will get a prop that is the form for that step and can be used to register inputs.
- * This allows for a coherent form structure that can be used to validate the form as steps and as a whole.
+ * The wizard uses Zod schemas for validation, where each schema property represents a step.
+ * Each step receives its own form instance for registering inputs, enabling per-step and
+ * full-form validation.
  *
- * The FormWizard component is a wrapper that renders the sidebar and the step wrapper.
- * The sidebar is a list of steps that can be navigated to.
- * The step wrapper is a list of steps that are rendered.
+ * **Note:** In production, the schema should be returned from a hook to allow translations
+ * for error messages.
  *
- * The FormWizard component also handles the navigation between steps.
+ * ### When to use
+ * - Complex forms that benefit from being split into logical steps
+ * - Onboarding flows or setup wizards
+ * - Forms where later steps depend on earlier input
  *
- * ** In production code, the schema should be returned from a hook, to allow the use of translations for error messages in the schema. **
+ * ### When not to use
+ * - Simple forms with few fields - use regular form components
+ * - Forms that should show all fields at once
+ *
+ * @example Basic usage with useFormWizard hook
+ * ```tsx
+ * import { FormWizard, useFormWizard } from "@trackunit/react-form-wizard";
+ * import { z } from "zod";
+ *
+ * const formSchema = z.object({
+ *   basicInfo: z.object({
+ *     name: z.string().min(1, "Name is required"),
+ *     email: z.string().email("Invalid email"),
+ *   }),
+ *   preferences: z.object({
+ *     notifications: z.boolean(),
+ *     theme: z.enum(["light", "dark"]),
+ *   }),
+ * });
+ *
+ * const MyWizard = () => {
+ *   const wizardProps = useFormWizard({
+ *     fullFormSchema: formSchema,
+ *     steps: {
+ *       basicInfo: {
+ *         title: "Basic Information",
+ *         component: BasicInfoStep,
+ *       },
+ *       preferences: {
+ *         title: "Preferences",
+ *         component: PreferencesStep,
+ *       },
+ *     },
+ *     onSubmit: (data) => console.log("Form submitted:", data),
+ *   });
+ *
+ *   return <FormWizard {...wizardProps} basePath="/setup" />;
+ * };
+ * ```
+ * @example Step component pattern
+ * ```tsx
+ * import { FormWizardStepProps } from "@trackunit/react-form-wizard";
+ * import { TextField, EmailField } from "@trackunit/react-form-components";
+ *
+ * const BasicInfoStep = ({ form }: FormWizardStepProps) => {
+ *   const { register, formState: { errors } } = form;
+ *
+ *   return (
+ *     <div className="space-y-4">
+ *       <TextField
+ *         label="Name"
+ *         {...register("name")}
+ *         errorMessage={errors.name?.message}
+ *       />
+ *       <EmailField
+ *         label="Email"
+ *         {...register("email")}
+ *         errorMessage={errors.email?.message}
+ *       />
+ *     </div>
+ *   );
+ * };
+ * ```
+ * @example With conditional steps
+ * ```tsx
+ * import { FormWizard, useFormWizard } from "@trackunit/react-form-wizard";
+ *
+ * const wizardProps = useFormWizard({
+ *   fullFormSchema: formSchema,
+ *   steps: {
+ *     accountType: {
+ *       title: "Account Type",
+ *       component: AccountTypeStep,
+ *     },
+ *     businessDetails: {
+ *       title: "Business Details",
+ *       component: BusinessDetailsStep,
+ *       shouldRender: (formState) => formState.accountType?.type === "business",
+ *     },
+ *     confirmation: {
+ *       title: "Confirmation",
+ *       component: ConfirmationStep,
+ *     },
+ *   },
+ *   onSubmit: handleSubmit,
+ * });
+ * ```
  */
 const FormWizard = ({ lastStepPrimaryActionLabel, isEdit, steps, fullFormSchema, onCancel, className, "data-testid": dataTestId, basePath, }) => {
     const navigate = reactRouter.useNavigate();

package/index.esm.js

@@ -354,20 +354,108 @@ const cvaFormWizardLayout = cvaMerge([
 const cvaStepContainer = cvaMerge(["h-full", "grid", "bg-white", "overflow-hidden"]);
 
 /**
- * The FormWizard component is used for forms in multiple steps.
- * Use the useFormWizard hook to generate the props for this component.
+ * The `<FormWizard>` component renders multi-step forms with a sidebar navigation.
+ * Use the `useFormWizard` hook to generate the props for this component.
  *
- * The useFormWizard hook takes a form schema which is a zod schema that contains all the steps.
- * Each step will get a prop that is the form for that step and can be used to register inputs.
- * This allows for a coherent form structure that can be used to validate the form as steps and as a whole.
+ * The wizard uses Zod schemas for validation, where each schema property represents a step.
+ * Each step receives its own form instance for registering inputs, enabling per-step and
+ * full-form validation.
  *
- * The FormWizard component is a wrapper that renders the sidebar and the step wrapper.
- * The sidebar is a list of steps that can be navigated to.
- * The step wrapper is a list of steps that are rendered.
+ * **Note:** In production, the schema should be returned from a hook to allow translations
+ * for error messages.
  *
- * The FormWizard component also handles the navigation between steps.
+ * ### When to use
+ * - Complex forms that benefit from being split into logical steps
+ * - Onboarding flows or setup wizards
+ * - Forms where later steps depend on earlier input
  *
- * ** In production code, the schema should be returned from a hook, to allow the use of translations for error messages in the schema. **
+ * ### When not to use
+ * - Simple forms with few fields - use regular form components
+ * - Forms that should show all fields at once
+ *
+ * @example Basic usage with useFormWizard hook
+ * ```tsx
+ * import { FormWizard, useFormWizard } from "@trackunit/react-form-wizard";
+ * import { z } from "zod";
+ *
+ * const formSchema = z.object({
+ *   basicInfo: z.object({
+ *     name: z.string().min(1, "Name is required"),
+ *     email: z.string().email("Invalid email"),
+ *   }),
+ *   preferences: z.object({
+ *     notifications: z.boolean(),
+ *     theme: z.enum(["light", "dark"]),
+ *   }),
+ * });
+ *
+ * const MyWizard = () => {
+ *   const wizardProps = useFormWizard({
+ *     fullFormSchema: formSchema,
+ *     steps: {
+ *       basicInfo: {
+ *         title: "Basic Information",
+ *         component: BasicInfoStep,
+ *       },
+ *       preferences: {
+ *         title: "Preferences",
+ *         component: PreferencesStep,
+ *       },
+ *     },
+ *     onSubmit: (data) => console.log("Form submitted:", data),
+ *   });
+ *
+ *   return <FormWizard {...wizardProps} basePath="/setup" />;
+ * };
+ * ```
+ * @example Step component pattern
+ * ```tsx
+ * import { FormWizardStepProps } from "@trackunit/react-form-wizard";
+ * import { TextField, EmailField } from "@trackunit/react-form-components";
+ *
+ * const BasicInfoStep = ({ form }: FormWizardStepProps) => {
+ *   const { register, formState: { errors } } = form;
+ *
+ *   return (
+ *     <div className="space-y-4">
+ *       <TextField
+ *         label="Name"
+ *         {...register("name")}
+ *         errorMessage={errors.name?.message}
+ *       />
+ *       <EmailField
+ *         label="Email"
+ *         {...register("email")}
+ *         errorMessage={errors.email?.message}
+ *       />
+ *     </div>
+ *   );
+ * };
+ * ```
+ * @example With conditional steps
+ * ```tsx
+ * import { FormWizard, useFormWizard } from "@trackunit/react-form-wizard";
+ *
+ * const wizardProps = useFormWizard({
+ *   fullFormSchema: formSchema,
+ *   steps: {
+ *     accountType: {
+ *       title: "Account Type",
+ *       component: AccountTypeStep,
+ *     },
+ *     businessDetails: {
+ *       title: "Business Details",
+ *       component: BusinessDetailsStep,
+ *       shouldRender: (formState) => formState.accountType?.type === "business",
+ *     },
+ *     confirmation: {
+ *       title: "Confirmation",
+ *       component: ConfirmationStep,
+ *     },
+ *   },
+ *   onSubmit: handleSubmit,
+ * });
+ * ```
  */
 const FormWizard = ({ lastStepPrimaryActionLabel, isEdit, steps, fullFormSchema, onCancel, className, "data-testid": dataTestId, basePath, }) => {
     const navigate = useNavigate();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-form-wizard",
-  "version": "1.10.18",
+  "version": "1.10.19",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "dependencies": {
@@ -10,10 +10,10 @@
     "react-hook-form": "7.62.0",
     "@tanstack/react-router": "1.114.29",
     "@tanstack/router-core": "1.114.29",
-    "@trackunit/shared-utils": "1.12.15",
-    "@trackunit/css-class-variance-utilities": "1.10.15",
-    "@trackunit/react-components": "1.14.18",
-    "@trackunit/i18n-library-translation": "1.10.15"
+    "@trackunit/shared-utils": "1.12.16",
+    "@trackunit/css-class-variance-utilities": "1.10.16",
+    "@trackunit/react-components": "1.14.19",
+    "@trackunit/i18n-library-translation": "1.10.16"
   },
   "engines": {
     "node": ">=24.x",

package/src/FormWizard/FormWizard.d.ts

@@ -5,19 +5,107 @@ export type FormWizardStepFormReturnMap<TFullSchema extends AnyZodObject> = Part
     [TStepKey in keyof z.infer<TFullSchema>]: UseFormReturn<z.TypeOf<TFullSchema>[TStepKey]>;
 }>;
 /**
- * The FormWizard component is used for forms in multiple steps.
- * Use the useFormWizard hook to generate the props for this component.
+ * The `<FormWizard>` component renders multi-step forms with a sidebar navigation.
+ * Use the `useFormWizard` hook to generate the props for this component.
  *
- * The useFormWizard hook takes a form schema which is a zod schema that contains all the steps.
- * Each step will get a prop that is the form for that step and can be used to register inputs.
- * This allows for a coherent form structure that can be used to validate the form as steps and as a whole.
+ * The wizard uses Zod schemas for validation, where each schema property represents a step.
+ * Each step receives its own form instance for registering inputs, enabling per-step and
+ * full-form validation.
  *
- * The FormWizard component is a wrapper that renders the sidebar and the step wrapper.
- * The sidebar is a list of steps that can be navigated to.
- * The step wrapper is a list of steps that are rendered.
+ * **Note:** In production, the schema should be returned from a hook to allow translations
+ * for error messages.
  *
- * The FormWizard component also handles the navigation between steps.
+ * ### When to use
+ * - Complex forms that benefit from being split into logical steps
+ * - Onboarding flows or setup wizards
+ * - Forms where later steps depend on earlier input
  *
- * ** In production code, the schema should be returned from a hook, to allow the use of translations for error messages in the schema. **
+ * ### When not to use
+ * - Simple forms with few fields - use regular form components
+ * - Forms that should show all fields at once
+ *
+ * @example Basic usage with useFormWizard hook
+ * ```tsx
+ * import { FormWizard, useFormWizard } from "@trackunit/react-form-wizard";
+ * import { z } from "zod";
+ *
+ * const formSchema = z.object({
+ *   basicInfo: z.object({
+ *     name: z.string().min(1, "Name is required"),
+ *     email: z.string().email("Invalid email"),
+ *   }),
+ *   preferences: z.object({
+ *     notifications: z.boolean(),
+ *     theme: z.enum(["light", "dark"]),
+ *   }),
+ * });
+ *
+ * const MyWizard = () => {
+ *   const wizardProps = useFormWizard({
+ *     fullFormSchema: formSchema,
+ *     steps: {
+ *       basicInfo: {
+ *         title: "Basic Information",
+ *         component: BasicInfoStep,
+ *       },
+ *       preferences: {
+ *         title: "Preferences",
+ *         component: PreferencesStep,
+ *       },
+ *     },
+ *     onSubmit: (data) => console.log("Form submitted:", data),
+ *   });
+ *
+ *   return <FormWizard {...wizardProps} basePath="/setup" />;
+ * };
+ * ```
+ * @example Step component pattern
+ * ```tsx
+ * import { FormWizardStepProps } from "@trackunit/react-form-wizard";
+ * import { TextField, EmailField } from "@trackunit/react-form-components";
+ *
+ * const BasicInfoStep = ({ form }: FormWizardStepProps) => {
+ *   const { register, formState: { errors } } = form;
+ *
+ *   return (
+ *     <div className="space-y-4">
+ *       <TextField
+ *         label="Name"
+ *         {...register("name")}
+ *         errorMessage={errors.name?.message}
+ *       />
+ *       <EmailField
+ *         label="Email"
+ *         {...register("email")}
+ *         errorMessage={errors.email?.message}
+ *       />
+ *     </div>
+ *   );
+ * };
+ * ```
+ * @example With conditional steps
+ * ```tsx
+ * import { FormWizard, useFormWizard } from "@trackunit/react-form-wizard";
+ *
+ * const wizardProps = useFormWizard({
+ *   fullFormSchema: formSchema,
+ *   steps: {
+ *     accountType: {
+ *       title: "Account Type",
+ *       component: AccountTypeStep,
+ *     },
+ *     businessDetails: {
+ *       title: "Business Details",
+ *       component: BusinessDetailsStep,
+ *       shouldRender: (formState) => formState.accountType?.type === "business",
+ *     },
+ *     confirmation: {
+ *       title: "Confirmation",
+ *       component: ConfirmationStep,
+ *     },
+ *   },
+ *   onSubmit: handleSubmit,
+ * });
+ * ```
  */
 export declare const FormWizard: <TFullSchema extends AnyZodObject, TComponentStepDefinitions extends StepDefinitions<TFullSchema>>({ lastStepPrimaryActionLabel, isEdit, steps, fullFormSchema, onCancel, className, "data-testid": dataTestId, basePath, }: FromWizardComponentProps<TFullSchema, TComponentStepDefinitions>) => import("react/jsx-runtime").JSX.Element;