react-formsteps-core 0.1.0

package/LICENSE

@@ -0,0 +1,36 @@
+Copyright (c) 2025 Franxx
+GitHub: https://github.com/franklinjunior23
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software to use it for personal, educational, or open source projects,
+subject to the following conditions:
+
+1. ATTRIBUTION REQUIRED: The above copyright notice and this permission notice
+   must be included in all copies or substantial portions of the Software.
+
+2. NON-COMMERCIAL: This software may not be sold, sublicensed, or used as part
+   of any commercial product or service without explicit written permission
+   from the original author (Franxx).
+
+3. NO REBRANDING: You may not remove or alter the original authorship credits,
+   rename this library and republish it as your own, or claim original
+   authorship of this work.
+
+4. NO REPUBLISHING: You may not publish this package or any modified version
+   of it to npm, GitHub Packages, or any other package registry under a
+   different name or ownership without explicit written permission from
+   the original author.
+
+5. CONTRIBUTIONS WELCOME: Contributions via pull requests are welcome. By
+   submitting a contribution, you agree that the original author (Franxx)
+   retains full ownership and copyright of the project, including your
+   contributions.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For commercial use or any other permissions contact the author directly.

package/README.md

@@ -0,0 +1,312 @@
+# react-formsteps
+
+> Headless, type-safe multi-step form library for React — built on [react-hook-form](https://react-hook-form.com/) and [Zod](https://zod.dev/).
+
+[![npm version](https://img.shields.io/npm/v/react-formsteps-core?style=flat-square&color=blue)](https://www.npmjs.com/package/react-formsteps-core)
+[![npm version](https://img.shields.io/npm/v/react-formsteps-ui?style=flat-square&color=blue)](https://www.npmjs.com/package/react-formsteps-ui)
+[![license](https://img.shields.io/badge/license-Custom-orange?style=flat-square)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
+
+---
+
+## Packages
+
+| Package                                           | Version                                                                             | Description                                 |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------- |
+| [`react-formsteps-core`](./packages/core) | ![npm](https://img.shields.io/npm/v/react-formsteps-core?style=flat-square) | Headless hooks + context. No UI, no styles. |
+| [`react-formsteps-ui`](./packages/ui)     | ![npm](https://img.shields.io/npm/v/react-formsteps-ui?style=flat-square)   | Optional pre-built React components.        |
+
+---
+
+## Features
+
+- **Headless** — zero UI imposed. Works with any design system.
+- **Per-step validation** — validates only the current step's Zod schema before advancing.
+- **Type-safe** — strict TypeScript throughout. Types flow from Zod schemas into your fields.
+- **Built on react-hook-form** — full compatibility with the RHF ecosystem.
+- **Flexible** — use the hooks alone or drop in the ready-made components.
+- **Tiny** — tree-shakeable, no CSS bundled.
+
+---
+
+## Installation
+
+### Core only (headless)
+
+```bash
+# npm
+npm install react-formsteps-core react-hook-form zod @hookform/resolvers
+
+# pnpm
+pnpm add react-formsteps-core react-hook-form zod @hookform/resolvers
+
+# yarn
+yarn add react-formsteps-core react-hook-form zod @hookform/resolvers
+```
+
+### With UI components
+
+```bash
+# npm
+npm install react-formsteps-core react-formsteps-ui react-hook-form zod @hookform/resolvers
+
+# pnpm
+pnpm add react-formsteps-core react-formsteps-ui react-hook-form zod @hookform/resolvers
+```
+
+### Peer dependencies
+
+| Dependency            | Version |
+| --------------------- | ------- |
+| `react`               | `>=18`  |
+| `react-dom`           | `>=18`  |
+| `react-hook-form`     | `>=7`   |
+| `zod`                 | `>=3`   |
+| `@hookform/resolvers` | `>=3`   |
+
+---
+
+## Quick start
+
+### Headless — `useSteps` + `useStepForm`
+
+```tsx
+import { useSteps, useStepForm } from 'react-formsteps-core';
+import { z } from 'zod';
+
+const schemas = [
+  z.object({ firstName: z.string().min(1, 'Required'), lastName: z.string().min(1, 'Required') }),
+  z.object({ email: z.string().email('Enter a valid email') }),
+  z.object({ password: z.string().min(8, 'Min. 8 characters') }),
+];
+
+export function RegistrationForm() {
+  const { currentStep, next, prev, isFirst, isLast, progress, totalSteps } = useSteps({
+    totalSteps: schemas.length,
+  });
+
+  const { form, nextWithValidation, isValidating } = useStepForm({
+    schema: schemas[currentStep],
+    onNext: (data) => console.log('Step data:', data),
+  });
+
+  const handleNext = async () => {
+    const ok = await nextWithValidation();
+    if (ok && !isLast) next();
+    if (ok && isLast) console.log('All done!', form.getValues());
+  };
+
+  return (
+    <form>
+      {/* Progress */}
+      <div>
+        Step {currentStep + 1} of {totalSteps} — {progress}%
+      </div>
+      <progress value={progress} max={100} />
+
+      {/* Step 1 */}
+      {currentStep === 0 && (
+        <>
+          <input {...form.register('firstName')} placeholder="First name" />
+          <input {...form.register('lastName')} placeholder="Last name" />
+        </>
+      )}
+
+      {/* Step 2 */}
+      {currentStep === 1 && <input {...form.register('email')} placeholder="Email" />}
+
+      {/* Step 3 */}
+      {currentStep === 2 && (
+        <input {...form.register('password')} type="password" placeholder="Password" />
+      )}
+
+      {/* Navigation */}
+      <button type="button" onClick={prev} disabled={isFirst}>
+        Back
+      </button>
+      <button type="button" onClick={handleNext} disabled={isValidating}>
+        {isLast ? 'Submit' : 'Next'}
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+### With UI components — `<Steps>` + `<Step>`
+
+```tsx
+import { Steps, Step, StepBar, StepNav } from 'react-formsteps-ui';
+import { z } from 'zod';
+
+const schema1 = z.object({ name: z.string().min(1, 'Required') });
+const schema2 = z.object({ email: z.string().email() });
+const schema3 = z.object({ password: z.string().min(8) });
+
+export function RegistrationForm() {
+  return (
+    <Steps
+      schemas={[schema1, schema2, schema3]}
+      onSubmit={(data) => console.log('Submitted:', data)}
+    >
+      <Step title="Personal info">{/* your fields */}</Step>
+
+      <Step title="Contact">{/* your fields */}</Step>
+
+      <Step title="Security">{/* your fields */}</Step>
+    </Steps>
+  );
+}
+```
+
+---
+
+## API
+
+### `useSteps(options)`
+
+Manages step navigation state.
+
+```ts
+const {
+  currentStep,  // number — 0-indexed
+  totalSteps,   // number
+  isFirst,      // boolean
+  isLast,       // boolean
+  next,         // () => void
+  prev,         // () => void
+  goTo,         // (index: number) => void
+  progress,     // number — 0 to 100
+} = useSteps({ totalSteps: 3, initialStep?: 0, onComplete?: () => void });
+```
+
+| Option        | Type         | Default | Description                                              |
+| ------------- | ------------ | ------- | -------------------------------------------------------- |
+| `totalSteps`  | `number`     | —       | **Required.** Must be a positive integer                 |
+| `initialStep` | `number`     | `0`     | Starting step index                                      |
+| `onComplete`  | `() => void` | —       | Called once when the user first arrives at the last step |
+
+---
+
+### `useStepForm(options)`
+
+Integrates react-hook-form with per-step Zod validation.
+
+```ts
+const {
+  form,               // UseFormReturn<z.infer<typeof schema>>
+  nextWithValidation, // () => Promise<boolean>
+  isValidating,       // boolean
+} = useStepForm({ schema, defaultValues?, onNext? });
+```
+
+| Option          | Type                        | Description                                   |
+| --------------- | --------------------------- | --------------------------------------------- |
+| `schema`        | `ZodType`                   | **Required.** Zod schema for the current step |
+| `defaultValues` | `Partial<z.infer<TSchema>>` | Initial field values                          |
+| `onNext`        | `(data) => void`            | Called with validated data when advancing     |
+
+---
+
+### `useStepsContext()`
+
+Access step state from any component inside a `<Steps>` or `<StepsProvider>`.
+
+```ts
+import { useStepsContext } from 'react-formsteps-core';
+
+const { currentStep, totalSteps, next, prev, goTo, formData } = useStepsContext();
+```
+
+---
+
+### `<StepsProvider>` — headless context
+
+Use the context without the UI package.
+
+```tsx
+import { StepsProvider, useStepsContext } from 'react-formsteps-core';
+
+<StepsProvider schemas={[schema1, schema2]} onSubmit={handleSubmit}>
+  <MyCustomWizard />
+</StepsProvider>;
+```
+
+---
+
+### Utilities
+
+```ts
+import { validateStep, mergeSchemas, validateAllSteps } from 'react-formsteps-core';
+
+// Validate a single step — never throws
+const result = await validateStep(schema, data);
+// { success: boolean, data?, errors?: Record<string, string> }
+
+// Merge multiple ZodObject schemas into one
+const fullSchema = mergeSchemas([step1Schema, step2Schema, step3Schema]);
+
+// Validate all accumulated data against merged schemas
+const result = await validateAllSteps(schemas, allData);
+```
+
+---
+
+### UI Components
+
+| Component   | Description                                                 |
+| ----------- | ----------------------------------------------------------- |
+| `<Steps>`   | Root provider. Pass `schemas` and `onSubmit`.               |
+| `<Step>`    | Wrapper for each step's content. Accepts optional `title`.  |
+| `<StepBar>` | Progress bar with optional step labels.                     |
+| `<StepNav>` | Back / Next / Submit buttons with built-in validation gate. |
+
+---
+
+## TypeScript
+
+All APIs are fully typed. Enable `strict: true` in your `tsconfig.json` for the best experience.
+
+```json
+{
+  "compilerOptions": {
+    "strict": true
+  }
+}
+```
+
+Import types directly:
+
+```ts
+import type {
+  StepSchema,
+  StepConfig,
+  StepsContextValue,
+  UseStepsOptions,
+  UseStepsReturn,
+  UseStepFormOptions,
+  UseStepFormReturn,
+  StepsProviderProps,
+} from 'react-formsteps-core';
+```
+
+---
+
+## Contributing
+
+Contributions via pull requests are welcome. Please open an issue first to discuss significant changes.
+
+By submitting a contribution you agree that the original author (Franxx) retains full ownership and copyright of the project, including your contributions.
+
+---
+
+## License
+
+Copyright (c) 2025 Franxx — see [LICENSE](./LICENSE) for full terms.
+
+This software is free for personal, educational, and open source use. **Commercial use requires explicit written permission from the author.** See the license for details.
+
+---
+
+<p align="center">Made by <a href="https://github.com/franklinjunior23">Franxx</a></p>

package/dist/index.d.mts

@@ -0,0 +1,85 @@
+import { ZodType, z, ZodObject } from 'zod';
+import { UseFormReturn, FieldValues } from 'react-hook-form';
+import React$1 from 'react';
+
+type StepSchema = ZodType<Record<string, unknown>>;
+interface StepConfig {
+    id: string;
+    label?: string;
+    schema?: StepSchema;
+}
+interface StepsContextValue {
+    currentStep: number;
+    totalSteps: number;
+    isFirst: boolean;
+    isLast: boolean;
+    next: () => void;
+    prev: () => void;
+    goTo: (index: number) => void;
+    formData: Record<string, unknown>;
+    setStepData: (step: number, data: Record<string, unknown>) => void;
+    schemas: StepSchema[];
+}
+interface UseStepsOptions {
+    totalSteps: number;
+    initialStep?: number;
+    onComplete?: () => void;
+}
+interface UseStepsReturn {
+    currentStep: number;
+    totalSteps: number;
+    isFirst: boolean;
+    isLast: boolean;
+    next: () => void;
+    prev: () => void;
+    goTo: (index: number) => void;
+    progress: number;
+}
+interface UseStepFormOptions<TSchema extends ZodType = ZodType> {
+    schema: TSchema;
+    defaultValues?: Partial<z.infer<TSchema>>;
+    onNext?: (data: z.infer<TSchema>) => void;
+}
+interface UseStepFormReturn<TSchema extends ZodType = ZodType> {
+    form: UseFormReturn<z.infer<TSchema> & FieldValues>;
+    nextWithValidation: () => Promise<boolean>;
+    isValidating: boolean;
+}
+interface StepsProviderProps {
+    children: React.ReactNode;
+    schemas: StepSchema[];
+    onSubmit?: (data: Record<string, unknown>) => void;
+    initialStep?: number;
+}
+
+declare function useSteps({ totalSteps, initialStep, onComplete, }: UseStepsOptions): UseStepsReturn;
+
+declare function useStepForm<TSchema extends ZodType>({ schema, defaultValues, onNext, }: UseStepFormOptions<TSchema>): UseStepFormReturn<TSchema>;
+
+declare const StepsContext: React$1.Context<StepsContextValue | null>;
+declare function useStepsContext(): StepsContextValue;
+declare function StepsProvider({ children, schemas, initialStep }: StepsProviderProps): React$1.FunctionComponentElement<React$1.ProviderProps<StepsContextValue | null>>;
+
+interface ValidateStepResult {
+    success: boolean;
+    errors?: Record<string, string>;
+    data?: Record<string, unknown>;
+}
+declare function validateStep(schema: ZodType, data: Record<string, unknown>): Promise<ValidateStepResult>;
+
+type AnyZodObject = ZodObject<any, any, any>;
+/**
+ * Merges multiple Zod schemas into a single ZodObject schema.
+ * Only merges ZodObject schemas; other schema types are skipped.
+ */
+declare function mergeSchemas(schemas: ZodType[]): AnyZodObject;
+/**
+ * Validates all accumulated form data against the merged schema.
+ */
+declare function validateAllSteps(schemas: ZodType[], data: Record<string, unknown>): Promise<{
+    success: boolean;
+    data?: Record<string, unknown>;
+    errors?: Record<string, string>;
+}>;
+
+export { type StepConfig, type StepSchema, StepsContext, type StepsContextValue, StepsProvider, type StepsProviderProps, type UseStepFormOptions, type UseStepFormReturn, type UseStepsOptions, type UseStepsReturn, mergeSchemas, useStepForm, useSteps, useStepsContext, validateAllSteps, validateStep };

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+import { ZodType, z, ZodObject } from 'zod';
+import { UseFormReturn, FieldValues } from 'react-hook-form';
+import React$1 from 'react';
+
+type StepSchema = ZodType<Record<string, unknown>>;
+interface StepConfig {
+    id: string;
+    label?: string;
+    schema?: StepSchema;
+}
+interface StepsContextValue {
+    currentStep: number;
+    totalSteps: number;
+    isFirst: boolean;
+    isLast: boolean;
+    next: () => void;
+    prev: () => void;
+    goTo: (index: number) => void;
+    formData: Record<string, unknown>;
+    setStepData: (step: number, data: Record<string, unknown>) => void;
+    schemas: StepSchema[];
+}
+interface UseStepsOptions {
+    totalSteps: number;
+    initialStep?: number;
+    onComplete?: () => void;
+}
+interface UseStepsReturn {
+    currentStep: number;
+    totalSteps: number;
+    isFirst: boolean;
+    isLast: boolean;
+    next: () => void;
+    prev: () => void;
+    goTo: (index: number) => void;
+    progress: number;
+}
+interface UseStepFormOptions<TSchema extends ZodType = ZodType> {
+    schema: TSchema;
+    defaultValues?: Partial<z.infer<TSchema>>;
+    onNext?: (data: z.infer<TSchema>) => void;
+}
+interface UseStepFormReturn<TSchema extends ZodType = ZodType> {
+    form: UseFormReturn<z.infer<TSchema> & FieldValues>;
+    nextWithValidation: () => Promise<boolean>;
+    isValidating: boolean;
+}
+interface StepsProviderProps {
+    children: React.ReactNode;
+    schemas: StepSchema[];
+    onSubmit?: (data: Record<string, unknown>) => void;
+    initialStep?: number;
+}
+
+declare function useSteps({ totalSteps, initialStep, onComplete, }: UseStepsOptions): UseStepsReturn;
+
+declare function useStepForm<TSchema extends ZodType>({ schema, defaultValues, onNext, }: UseStepFormOptions<TSchema>): UseStepFormReturn<TSchema>;
+
+declare const StepsContext: React$1.Context<StepsContextValue | null>;
+declare function useStepsContext(): StepsContextValue;
+declare function StepsProvider({ children, schemas, initialStep }: StepsProviderProps): React$1.FunctionComponentElement<React$1.ProviderProps<StepsContextValue | null>>;
+
+interface ValidateStepResult {
+    success: boolean;
+    errors?: Record<string, string>;
+    data?: Record<string, unknown>;
+}
+declare function validateStep(schema: ZodType, data: Record<string, unknown>): Promise<ValidateStepResult>;
+
+type AnyZodObject = ZodObject<any, any, any>;
+/**
+ * Merges multiple Zod schemas into a single ZodObject schema.
+ * Only merges ZodObject schemas; other schema types are skipped.
+ */
+declare function mergeSchemas(schemas: ZodType[]): AnyZodObject;
+/**
+ * Validates all accumulated form data against the merged schema.
+ */
+declare function validateAllSteps(schemas: ZodType[], data: Record<string, unknown>): Promise<{
+    success: boolean;
+    data?: Record<string, unknown>;
+    errors?: Record<string, string>;
+}>;
+
+export { type StepConfig, type StepSchema, StepsContext, type StepsContextValue, StepsProvider, type StepsProviderProps, type UseStepFormOptions, type UseStepFormReturn, type UseStepsOptions, type UseStepsReturn, mergeSchemas, useStepForm, useSteps, useStepsContext, validateAllSteps, validateStep };

package/dist/index.js

@@ -0,0 +1,229 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  StepsContext: () => StepsContext,
+  StepsProvider: () => StepsProvider,
+  mergeSchemas: () => mergeSchemas,
+  useStepForm: () => useStepForm,
+  useSteps: () => useSteps,
+  useStepsContext: () => useStepsContext,
+  validateAllSteps: () => validateAllSteps,
+  validateStep: () => validateStep
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/hooks/useSteps.ts
+var import_react = require("react");
+function useSteps({
+  totalSteps,
+  initialStep = 0,
+  onComplete
+}) {
+  if (totalSteps <= 0) {
+    throw new Error("[useSteps] totalSteps must be a positive integer");
+  }
+  const [currentStep, setCurrentStep] = (0, import_react.useState)(initialStep);
+  const next = (0, import_react.useCallback)(() => {
+    setCurrentStep((prev2) => {
+      const nextStep = Math.min(prev2 + 1, totalSteps - 1);
+      if (nextStep === totalSteps - 1 && prev2 !== totalSteps - 1) {
+        onComplete?.();
+      }
+      return nextStep;
+    });
+  }, [totalSteps, onComplete]);
+  const prev = (0, import_react.useCallback)(() => {
+    setCurrentStep((prev2) => Math.max(prev2 - 1, 0));
+  }, []);
+  const goTo = (0, import_react.useCallback)(
+    (index) => {
+      if (index >= 0 && index < totalSteps) {
+        setCurrentStep(index);
+      }
+    },
+    [totalSteps]
+  );
+  const progress = totalSteps > 1 ? Math.round(currentStep / (totalSteps - 1) * 100) : 100;
+  return {
+    currentStep,
+    totalSteps,
+    isFirst: currentStep === 0,
+    isLast: currentStep === totalSteps - 1,
+    next,
+    prev,
+    goTo,
+    progress
+  };
+}
+
+// src/hooks/useStepForm.ts
+var import_react2 = require("react");
+var import_react_hook_form = require("react-hook-form");
+var import_zod = require("@hookform/resolvers/zod");
+function useStepForm({
+  schema,
+  defaultValues,
+  onNext
+}) {
+  const [isValidating, setIsValidating] = (0, import_react2.useState)(false);
+  const form = (0, import_react_hook_form.useForm)({
+    resolver: (0, import_zod.zodResolver)(schema),
+    // Cast needed: react-hook-form expects FieldValues but z.infer<TSchema> satisfies it at runtime
+    defaultValues,
+    mode: "onSubmit"
+  });
+  const nextWithValidation = (0, import_react2.useCallback)(async () => {
+    setIsValidating(true);
+    try {
+      const isValid = await form.trigger();
+      if (isValid) {
+        const data = form.getValues();
+        onNext?.(data);
+        return true;
+      }
+      return false;
+    } finally {
+      setIsValidating(false);
+    }
+  }, [form, onNext]);
+  return {
+    form,
+    nextWithValidation,
+    isValidating
+  };
+}
+
+// src/context/StepsContext.ts
+var import_react3 = __toESM(require("react"));
+var StepsContext = (0, import_react3.createContext)(null);
+function useStepsContext() {
+  const ctx = (0, import_react3.useContext)(StepsContext);
+  if (!ctx) {
+    throw new Error("useStepsContext must be used within a StepsProvider");
+  }
+  return ctx;
+}
+function StepsProvider({ children, schemas, initialStep = 0 }) {
+  const totalSteps = schemas.length;
+  const [currentStep, setCurrentStep] = (0, import_react3.useState)(initialStep);
+  const [formData, setFormData] = (0, import_react3.useState)({});
+  const next = (0, import_react3.useCallback)(
+    () => setCurrentStep((s) => Math.min(s + 1, totalSteps - 1)),
+    [totalSteps]
+  );
+  const prev = (0, import_react3.useCallback)(() => setCurrentStep((s) => Math.max(s - 1, 0)), []);
+  const goTo = (0, import_react3.useCallback)(
+    (index) => {
+      if (index >= 0 && index < totalSteps) setCurrentStep(index);
+    },
+    [totalSteps]
+  );
+  const setStepData = (0, import_react3.useCallback)((_step, data) => {
+    setFormData((prev2) => ({ ...prev2, ...data }));
+  }, []);
+  const contextValue = (0, import_react3.useMemo)(
+    () => ({
+      currentStep,
+      totalSteps,
+      isFirst: currentStep === 0,
+      isLast: currentStep === totalSteps - 1,
+      next,
+      prev,
+      goTo,
+      formData,
+      setStepData,
+      schemas
+    }),
+    [currentStep, totalSteps, next, prev, goTo, formData, setStepData, schemas]
+  );
+  return import_react3.default.createElement(StepsContext.Provider, { value: contextValue }, children);
+}
+
+// src/utils/validateStep.ts
+var import_zod2 = require("zod");
+async function validateStep(schema, data) {
+  try {
+    const parsed = await schema.parseAsync(data);
+    return { success: true, data: parsed };
+  } catch (err) {
+    if (err instanceof import_zod2.ZodError) {
+      const errors = {};
+      for (const issue of err.issues) {
+        const path = issue.path.join(".");
+        errors[path] = issue.message;
+      }
+      return { success: false, errors };
+    }
+    return { success: false, errors: { _root: "Validation failed" } };
+  }
+}
+
+// src/utils/mergeSchemas.ts
+var import_zod3 = require("zod");
+function mergeSchemas(schemas) {
+  let merged = import_zod3.z.object({});
+  for (const schema of schemas) {
+    if (schema instanceof import_zod3.ZodObject) {
+      merged = merged.merge(schema);
+    }
+  }
+  return merged;
+}
+async function validateAllSteps(schemas, data) {
+  const mergedSchema = mergeSchemas(schemas);
+  try {
+    const parsed = await mergedSchema.parseAsync(data);
+    return { success: true, data: parsed };
+  } catch (err) {
+    const { ZodError: ZodError2 } = await import("zod");
+    if (err instanceof ZodError2) {
+      const errors = {};
+      for (const issue of err.issues) {
+        errors[issue.path.join(".")] = issue.message;
+      }
+      return { success: false, errors };
+    }
+    return { success: false };
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StepsContext,
+  StepsProvider,
+  mergeSchemas,
+  useStepForm,
+  useSteps,
+  useStepsContext,
+  validateAllSteps,
+  validateStep
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/hooks/useSteps.ts","../src/hooks/useStepForm.ts","../src/context/StepsContext.ts","../src/utils/validateStep.ts","../src/utils/mergeSchemas.ts"],"sourcesContent":["// Hooks\nexport { useSteps } from './hooks/useSteps';\nexport { useStepForm } from './hooks/useStepForm';\n\n// Context\nexport { StepsContext, useStepsContext, StepsProvider } from './context/StepsContext';\n\n// Utils\nexport { validateStep } from './utils/validateStep';\nexport { mergeSchemas, validateAllSteps } from './utils/mergeSchemas';\n\n// Types\nexport type {\n  StepConfig,\n  StepSchema,\n  StepsContextValue,\n  UseStepsOptions,\n  UseStepsReturn,\n  UseStepFormOptions,\n  UseStepFormReturn,\n  StepsProviderProps,\n} from './types';\n","import { useState, useCallback } from 'react';\nimport { UseStepsOptions, UseStepsReturn } from '../types';\n\nexport function useSteps({\n  totalSteps,\n  initialStep = 0,\n  onComplete,\n}: UseStepsOptions): UseStepsReturn {\n  if (totalSteps <= 0) {\n    throw new Error('[useSteps] totalSteps must be a positive integer');\n  }\n\n  const [currentStep, setCurrentStep] = useState(initialStep);\n\n  const next = useCallback(() => {\n    setCurrentStep((prev) => {\n      const nextStep = Math.min(prev + 1, totalSteps - 1);\n      if (nextStep === totalSteps - 1 && prev !== totalSteps - 1) {\n        onComplete?.();\n      }\n      return nextStep;\n    });\n  }, [totalSteps, onComplete]);\n\n  const prev = useCallback(() => {\n    setCurrentStep((prev) => Math.max(prev - 1, 0));\n  }, []);\n\n  const goTo = useCallback(\n    (index: number) => {\n      if (index >= 0 && index < totalSteps) {\n        setCurrentStep(index);\n      }\n    },\n    [totalSteps]\n  );\n\n  const progress = totalSteps > 1 ? Math.round((currentStep / (totalSteps - 1)) * 100) : 100;\n\n  return {\n    currentStep,\n    totalSteps,\n    isFirst: currentStep === 0,\n    isLast: currentStep === totalSteps - 1,\n    next,\n    prev,\n    goTo,\n    progress,\n  };\n}\n","import { useState, useCallback } from 'react';\nimport { useForm } from 'react-hook-form';\nimport { zodResolver } from '@hookform/resolvers/zod';\nimport { ZodType, z } from 'zod';\nimport { UseStepFormOptions, UseStepFormReturn } from '../types';\n\nexport function useStepForm<TSchema extends ZodType>({\n  schema,\n  defaultValues,\n  onNext,\n}: UseStepFormOptions<TSchema>): UseStepFormReturn<TSchema> {\n  const [isValidating, setIsValidating] = useState(false);\n\n  const form = useForm<z.infer<TSchema>>({\n    resolver: zodResolver(schema),\n    // Cast needed: react-hook-form expects FieldValues but z.infer<TSchema> satisfies it at runtime\n    defaultValues: defaultValues as z.infer<TSchema>,\n    mode: 'onSubmit',\n  });\n\n  const nextWithValidation = useCallback(async (): Promise<boolean> => {\n    setIsValidating(true);\n    try {\n      const isValid = await form.trigger();\n      if (isValid) {\n        const data = form.getValues();\n        onNext?.(data);\n        return true;\n      }\n      return false;\n    } finally {\n      setIsValidating(false);\n    }\n  }, [form, onNext]);\n\n  return {\n    form,\n    nextWithValidation,\n    isValidating,\n  };\n}\n","import React, { createContext, useContext, useState, useCallback, useMemo } from 'react';\nimport { StepsContextValue, StepsProviderProps } from '../types';\n\nexport const StepsContext = createContext<StepsContextValue | null>(null);\n\nexport function useStepsContext(): StepsContextValue {\n  const ctx = useContext(StepsContext);\n  if (!ctx) {\n    throw new Error('useStepsContext must be used within a StepsProvider');\n  }\n  return ctx;\n}\n\nexport function StepsProvider({ children, schemas, initialStep = 0 }: StepsProviderProps) {\n  // We derive totalSteps from schemas length for headless usage\n  const totalSteps = schemas.length;\n  const [currentStep, setCurrentStep] = useState(initialStep);\n  const [formData, setFormData] = useState<Record<string, unknown>>({});\n\n  const next = useCallback(\n    () => setCurrentStep((s) => Math.min(s + 1, totalSteps - 1)),\n    [totalSteps]\n  );\n  const prev = useCallback(() => setCurrentStep((s) => Math.max(s - 1, 0)), []);\n  const goTo = useCallback(\n    (index: number) => {\n      if (index >= 0 && index < totalSteps) setCurrentStep(index);\n    },\n    [totalSteps]\n  );\n\n  const setStepData = useCallback((_step: number, data: Record<string, unknown>) => {\n    setFormData((prev) => ({ ...prev, ...data }));\n  }, []);\n\n  const contextValue: StepsContextValue = useMemo(\n    () => ({\n      currentStep,\n      totalSteps,\n      isFirst: currentStep === 0,\n      isLast: currentStep === totalSteps - 1,\n      next,\n      prev,\n      goTo,\n      formData,\n      setStepData,\n      schemas,\n    }),\n    [currentStep, totalSteps, next, prev, goTo, formData, setStepData, schemas]\n  );\n\n  return React.createElement(StepsContext.Provider, { value: contextValue }, children);\n}\n","import { ZodType, ZodError } from 'zod';\n\nexport interface ValidateStepResult {\n  success: boolean;\n  errors?: Record<string, string>;\n  data?: Record<string, unknown>;\n}\n\nexport async function validateStep(\n  schema: ZodType,\n  data: Record<string, unknown>\n): Promise<ValidateStepResult> {\n  try {\n    const parsed = await schema.parseAsync(data);\n    return { success: true, data: parsed as Record<string, unknown> };\n  } catch (err) {\n    if (err instanceof ZodError) {\n      const errors: Record<string, string> = {};\n      for (const issue of err.issues) {\n        const path = issue.path.join('.');\n        errors[path] = issue.message;\n      }\n      return { success: false, errors };\n    }\n    return { success: false, errors: { _root: 'Validation failed' } };\n  }\n}\n","import { z, ZodType, ZodObject, ZodTypeAny } from 'zod';\n\n// ZodObject generics (shape, unknownKeys, catchall) vary across schemas after `.merge()`,\n// making a precise generic type impractical here. `any` is intentional and safe.\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype AnyZodObject = ZodObject<any, any, any>;\n\n/**\n * Merges multiple Zod schemas into a single ZodObject schema.\n * Only merges ZodObject schemas; other schema types are skipped.\n */\nexport function mergeSchemas(schemas: ZodType[]): AnyZodObject {\n  let merged: AnyZodObject = z.object({});\n\n  for (const schema of schemas) {\n    if (schema instanceof ZodObject) {\n      merged = merged.merge(schema as ZodObject<Record<string, ZodTypeAny>>);\n    }\n  }\n\n  return merged;\n}\n\n/**\n * Validates all accumulated form data against the merged schema.\n */\nexport async function validateAllSteps(\n  schemas: ZodType[],\n  data: Record<string, unknown>\n): Promise<{ success: boolean; data?: Record<string, unknown>; errors?: Record<string, string> }> {\n  const mergedSchema = mergeSchemas(schemas);\n  try {\n    const parsed = await mergedSchema.parseAsync(data);\n    return { success: true, data: parsed as Record<string, unknown> };\n  } catch (err) {\n    const { ZodError } = await import('zod');\n    if (err instanceof ZodError) {\n      const errors: Record<string, string> = {};\n      for (const issue of err.issues) {\n        errors[issue.path.join('.')] = issue.message;\n      }\n      return { success: false, errors };\n    }\n    return { success: false };\n  }\n}\n"],"mappings":"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","names":["prev","import_react","import_react","prev","React","import_zod","import_zod","ZodError"]}

package/dist/index.mjs

@@ -0,0 +1,185 @@
+// src/hooks/useSteps.ts
+import { useState, useCallback } from "react";
+function useSteps({
+  totalSteps,
+  initialStep = 0,
+  onComplete
+}) {
+  if (totalSteps <= 0) {
+    throw new Error("[useSteps] totalSteps must be a positive integer");
+  }
+  const [currentStep, setCurrentStep] = useState(initialStep);
+  const next = useCallback(() => {
+    setCurrentStep((prev2) => {
+      const nextStep = Math.min(prev2 + 1, totalSteps - 1);
+      if (nextStep === totalSteps - 1 && prev2 !== totalSteps - 1) {
+        onComplete?.();
+      }
+      return nextStep;
+    });
+  }, [totalSteps, onComplete]);
+  const prev = useCallback(() => {
+    setCurrentStep((prev2) => Math.max(prev2 - 1, 0));
+  }, []);
+  const goTo = useCallback(
+    (index) => {
+      if (index >= 0 && index < totalSteps) {
+        setCurrentStep(index);
+      }
+    },
+    [totalSteps]
+  );
+  const progress = totalSteps > 1 ? Math.round(currentStep / (totalSteps - 1) * 100) : 100;
+  return {
+    currentStep,
+    totalSteps,
+    isFirst: currentStep === 0,
+    isLast: currentStep === totalSteps - 1,
+    next,
+    prev,
+    goTo,
+    progress
+  };
+}
+
+// src/hooks/useStepForm.ts
+import { useState as useState2, useCallback as useCallback2 } from "react";
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+function useStepForm({
+  schema,
+  defaultValues,
+  onNext
+}) {
+  const [isValidating, setIsValidating] = useState2(false);
+  const form = useForm({
+    resolver: zodResolver(schema),
+    // Cast needed: react-hook-form expects FieldValues but z.infer<TSchema> satisfies it at runtime
+    defaultValues,
+    mode: "onSubmit"
+  });
+  const nextWithValidation = useCallback2(async () => {
+    setIsValidating(true);
+    try {
+      const isValid = await form.trigger();
+      if (isValid) {
+        const data = form.getValues();
+        onNext?.(data);
+        return true;
+      }
+      return false;
+    } finally {
+      setIsValidating(false);
+    }
+  }, [form, onNext]);
+  return {
+    form,
+    nextWithValidation,
+    isValidating
+  };
+}
+
+// src/context/StepsContext.ts
+import React, { createContext, useContext, useState as useState3, useCallback as useCallback3, useMemo } from "react";
+var StepsContext = createContext(null);
+function useStepsContext() {
+  const ctx = useContext(StepsContext);
+  if (!ctx) {
+    throw new Error("useStepsContext must be used within a StepsProvider");
+  }
+  return ctx;
+}
+function StepsProvider({ children, schemas, initialStep = 0 }) {
+  const totalSteps = schemas.length;
+  const [currentStep, setCurrentStep] = useState3(initialStep);
+  const [formData, setFormData] = useState3({});
+  const next = useCallback3(
+    () => setCurrentStep((s) => Math.min(s + 1, totalSteps - 1)),
+    [totalSteps]
+  );
+  const prev = useCallback3(() => setCurrentStep((s) => Math.max(s - 1, 0)), []);
+  const goTo = useCallback3(
+    (index) => {
+      if (index >= 0 && index < totalSteps) setCurrentStep(index);
+    },
+    [totalSteps]
+  );
+  const setStepData = useCallback3((_step, data) => {
+    setFormData((prev2) => ({ ...prev2, ...data }));
+  }, []);
+  const contextValue = useMemo(
+    () => ({
+      currentStep,
+      totalSteps,
+      isFirst: currentStep === 0,
+      isLast: currentStep === totalSteps - 1,
+      next,
+      prev,
+      goTo,
+      formData,
+      setStepData,
+      schemas
+    }),
+    [currentStep, totalSteps, next, prev, goTo, formData, setStepData, schemas]
+  );
+  return React.createElement(StepsContext.Provider, { value: contextValue }, children);
+}
+
+// src/utils/validateStep.ts
+import { ZodError } from "zod";
+async function validateStep(schema, data) {
+  try {
+    const parsed = await schema.parseAsync(data);
+    return { success: true, data: parsed };
+  } catch (err) {
+    if (err instanceof ZodError) {
+      const errors = {};
+      for (const issue of err.issues) {
+        const path = issue.path.join(".");
+        errors[path] = issue.message;
+      }
+      return { success: false, errors };
+    }
+    return { success: false, errors: { _root: "Validation failed" } };
+  }
+}
+
+// src/utils/mergeSchemas.ts
+import { z, ZodObject } from "zod";
+function mergeSchemas(schemas) {
+  let merged = z.object({});
+  for (const schema of schemas) {
+    if (schema instanceof ZodObject) {
+      merged = merged.merge(schema);
+    }
+  }
+  return merged;
+}
+async function validateAllSteps(schemas, data) {
+  const mergedSchema = mergeSchemas(schemas);
+  try {
+    const parsed = await mergedSchema.parseAsync(data);
+    return { success: true, data: parsed };
+  } catch (err) {
+    const { ZodError: ZodError2 } = await import("zod");
+    if (err instanceof ZodError2) {
+      const errors = {};
+      for (const issue of err.issues) {
+        errors[issue.path.join(".")] = issue.message;
+      }
+      return { success: false, errors };
+    }
+    return { success: false };
+  }
+}
+export {
+  StepsContext,
+  StepsProvider,
+  mergeSchemas,
+  useStepForm,
+  useSteps,
+  useStepsContext,
+  validateAllSteps,
+  validateStep
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/useSteps.ts","../src/hooks/useStepForm.ts","../src/context/StepsContext.ts","../src/utils/validateStep.ts","../src/utils/mergeSchemas.ts"],"sourcesContent":["import { useState, useCallback } from 'react';\nimport { UseStepsOptions, UseStepsReturn } from '../types';\n\nexport function useSteps({\n  totalSteps,\n  initialStep = 0,\n  onComplete,\n}: UseStepsOptions): UseStepsReturn {\n  if (totalSteps <= 0) {\n    throw new Error('[useSteps] totalSteps must be a positive integer');\n  }\n\n  const [currentStep, setCurrentStep] = useState(initialStep);\n\n  const next = useCallback(() => {\n    setCurrentStep((prev) => {\n      const nextStep = Math.min(prev + 1, totalSteps - 1);\n      if (nextStep === totalSteps - 1 && prev !== totalSteps - 1) {\n        onComplete?.();\n      }\n      return nextStep;\n    });\n  }, [totalSteps, onComplete]);\n\n  const prev = useCallback(() => {\n    setCurrentStep((prev) => Math.max(prev - 1, 0));\n  }, []);\n\n  const goTo = useCallback(\n    (index: number) => {\n      if (index >= 0 && index < totalSteps) {\n        setCurrentStep(index);\n      }\n    },\n    [totalSteps]\n  );\n\n  const progress = totalSteps > 1 ? Math.round((currentStep / (totalSteps - 1)) * 100) : 100;\n\n  return {\n    currentStep,\n    totalSteps,\n    isFirst: currentStep === 0,\n    isLast: currentStep === totalSteps - 1,\n    next,\n    prev,\n    goTo,\n    progress,\n  };\n}\n","import { useState, useCallback } from 'react';\nimport { useForm } from 'react-hook-form';\nimport { zodResolver } from '@hookform/resolvers/zod';\nimport { ZodType, z } from 'zod';\nimport { UseStepFormOptions, UseStepFormReturn } from '../types';\n\nexport function useStepForm<TSchema extends ZodType>({\n  schema,\n  defaultValues,\n  onNext,\n}: UseStepFormOptions<TSchema>): UseStepFormReturn<TSchema> {\n  const [isValidating, setIsValidating] = useState(false);\n\n  const form = useForm<z.infer<TSchema>>({\n    resolver: zodResolver(schema),\n    // Cast needed: react-hook-form expects FieldValues but z.infer<TSchema> satisfies it at runtime\n    defaultValues: defaultValues as z.infer<TSchema>,\n    mode: 'onSubmit',\n  });\n\n  const nextWithValidation = useCallback(async (): Promise<boolean> => {\n    setIsValidating(true);\n    try {\n      const isValid = await form.trigger();\n      if (isValid) {\n        const data = form.getValues();\n        onNext?.(data);\n        return true;\n      }\n      return false;\n    } finally {\n      setIsValidating(false);\n    }\n  }, [form, onNext]);\n\n  return {\n    form,\n    nextWithValidation,\n    isValidating,\n  };\n}\n","import React, { createContext, useContext, useState, useCallback, useMemo } from 'react';\nimport { StepsContextValue, StepsProviderProps } from '../types';\n\nexport const StepsContext = createContext<StepsContextValue | null>(null);\n\nexport function useStepsContext(): StepsContextValue {\n  const ctx = useContext(StepsContext);\n  if (!ctx) {\n    throw new Error('useStepsContext must be used within a StepsProvider');\n  }\n  return ctx;\n}\n\nexport function StepsProvider({ children, schemas, initialStep = 0 }: StepsProviderProps) {\n  // We derive totalSteps from schemas length for headless usage\n  const totalSteps = schemas.length;\n  const [currentStep, setCurrentStep] = useState(initialStep);\n  const [formData, setFormData] = useState<Record<string, unknown>>({});\n\n  const next = useCallback(\n    () => setCurrentStep((s) => Math.min(s + 1, totalSteps - 1)),\n    [totalSteps]\n  );\n  const prev = useCallback(() => setCurrentStep((s) => Math.max(s - 1, 0)), []);\n  const goTo = useCallback(\n    (index: number) => {\n      if (index >= 0 && index < totalSteps) setCurrentStep(index);\n    },\n    [totalSteps]\n  );\n\n  const setStepData = useCallback((_step: number, data: Record<string, unknown>) => {\n    setFormData((prev) => ({ ...prev, ...data }));\n  }, []);\n\n  const contextValue: StepsContextValue = useMemo(\n    () => ({\n      currentStep,\n      totalSteps,\n      isFirst: currentStep === 0,\n      isLast: currentStep === totalSteps - 1,\n      next,\n      prev,\n      goTo,\n      formData,\n      setStepData,\n      schemas,\n    }),\n    [currentStep, totalSteps, next, prev, goTo, formData, setStepData, schemas]\n  );\n\n  return React.createElement(StepsContext.Provider, { value: contextValue }, children);\n}\n","import { ZodType, ZodError } from 'zod';\n\nexport interface ValidateStepResult {\n  success: boolean;\n  errors?: Record<string, string>;\n  data?: Record<string, unknown>;\n}\n\nexport async function validateStep(\n  schema: ZodType,\n  data: Record<string, unknown>\n): Promise<ValidateStepResult> {\n  try {\n    const parsed = await schema.parseAsync(data);\n    return { success: true, data: parsed as Record<string, unknown> };\n  } catch (err) {\n    if (err instanceof ZodError) {\n      const errors: Record<string, string> = {};\n      for (const issue of err.issues) {\n        const path = issue.path.join('.');\n        errors[path] = issue.message;\n      }\n      return { success: false, errors };\n    }\n    return { success: false, errors: { _root: 'Validation failed' } };\n  }\n}\n","import { z, ZodType, ZodObject, ZodTypeAny } from 'zod';\n\n// ZodObject generics (shape, unknownKeys, catchall) vary across schemas after `.merge()`,\n// making a precise generic type impractical here. `any` is intentional and safe.\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype AnyZodObject = ZodObject<any, any, any>;\n\n/**\n * Merges multiple Zod schemas into a single ZodObject schema.\n * Only merges ZodObject schemas; other schema types are skipped.\n */\nexport function mergeSchemas(schemas: ZodType[]): AnyZodObject {\n  let merged: AnyZodObject = z.object({});\n\n  for (const schema of schemas) {\n    if (schema instanceof ZodObject) {\n      merged = merged.merge(schema as ZodObject<Record<string, ZodTypeAny>>);\n    }\n  }\n\n  return merged;\n}\n\n/**\n * Validates all accumulated form data against the merged schema.\n */\nexport async function validateAllSteps(\n  schemas: ZodType[],\n  data: Record<string, unknown>\n): Promise<{ success: boolean; data?: Record<string, unknown>; errors?: Record<string, string> }> {\n  const mergedSchema = mergeSchemas(schemas);\n  try {\n    const parsed = await mergedSchema.parseAsync(data);\n    return { success: true, data: parsed as Record<string, unknown> };\n  } catch (err) {\n    const { ZodError } = await import('zod');\n    if (err instanceof ZodError) {\n      const errors: Record<string, string> = {};\n      for (const issue of err.issues) {\n        errors[issue.path.join('.')] = issue.message;\n      }\n      return { success: false, errors };\n    }\n    return { success: false };\n  }\n}\n"],"mappings":"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","names":["prev","useState","useCallback","useState","useCallback","prev","ZodError"]}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "react-formsteps-core",
+  "version": "0.1.0",
+  "description": "Headless multi-step form logic for React",
+  "keywords": [
+    "react",
+    "form",
+    "wizard",
+    "steps",
+    "headless"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "lint": "eslint src --ext .ts,.tsx"
+  },
+  "peerDependencies": {
+    "@hookform/resolvers": ">=3",
+    "react": ">=18",
+    "react-dom": ">=18",
+    "react-hook-form": ">=7",
+    "zod": ">=3"
+  },
+  "devDependencies": {
+    "@hookform/resolvers": "^3.3.4",
+    "@testing-library/react": "^14.2.2",
+    "@testing-library/react-hooks": "^8.0.1",
+    "@types/react": "^18.2.73",
+    "@types/react-dom": "^18.2.23",
+    "@vitest/coverage-v8": "^4.1.0",
+    "jsdom": "^29.0.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-hook-form": "^7.51.2",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5",
+    "vitest": "^1.4.0",
+    "zod": "^3.22.4"
+  }
+}