@startsimpli/forms 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,52 @@
+import { ZodSchema } from 'zod';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1 from 'react';
+
+interface UseFormOptions<T> {
+    initial?: Partial<T>;
+}
+interface UseFormReturn<T extends Record<string, unknown>> {
+    /** Current form values. Partial because fields may not be set yet.
+     *  For the fully validated T, use the data passed to handleSubmit's onValid callback. */
+    values: Partial<T>;
+    errors: Partial<Record<keyof T, string>>;
+    isSubmitting: boolean;
+    isDirty: boolean;
+    setFieldValue: <K extends keyof T>(field: K, value: T[K]) => void;
+    setError: (field: keyof T, message: string) => void;
+    clearError: (field: keyof T) => void;
+    /** Returns a submit handler. The onValid callback receives the fully validated T from schema.safeParse. */
+    handleSubmit: (onValid: (data: T) => Promise<void>) => (e?: React.FormEvent) => Promise<void>;
+    reset: (values?: Partial<T>) => void;
+}
+declare function useForm<T extends Record<string, unknown>>(schema: ZodSchema<T>, options?: UseFormOptions<T>): UseFormReturn<T>;
+
+interface FormFieldProps {
+    label: string;
+    error?: string;
+    required?: boolean;
+    children: React$1.ReactNode;
+    className?: string;
+}
+declare function FormField({ label, error, required, children, className, }: FormFieldProps): react_jsx_runtime.JSX.Element;
+
+interface FormSectionProps {
+    title?: string;
+    children: React$1.ReactNode;
+    className?: string;
+}
+declare function FormSection({ title, children, className, }: FormSectionProps): react_jsx_runtime.JSX.Element;
+
+interface FormErrorProps {
+    message: string;
+    className?: string;
+}
+declare function FormError({ message, className }: FormErrorProps): react_jsx_runtime.JSX.Element;
+
+interface FormRowProps {
+    children: React$1.ReactNode;
+    className?: string;
+}
+declare function FormRow({ children, className }: FormRowProps): react_jsx_runtime.JSX.Element;
+
+export { FormError, type FormErrorProps, FormField, type FormFieldProps, FormRow, type FormRowProps, FormSection, type FormSectionProps, type UseFormOptions, type UseFormReturn, useForm };

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import { ZodSchema } from 'zod';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1 from 'react';
+
+interface UseFormOptions<T> {
+    initial?: Partial<T>;
+}
+interface UseFormReturn<T extends Record<string, unknown>> {
+    /** Current form values. Partial because fields may not be set yet.
+     *  For the fully validated T, use the data passed to handleSubmit's onValid callback. */
+    values: Partial<T>;
+    errors: Partial<Record<keyof T, string>>;
+    isSubmitting: boolean;
+    isDirty: boolean;
+    setFieldValue: <K extends keyof T>(field: K, value: T[K]) => void;
+    setError: (field: keyof T, message: string) => void;
+    clearError: (field: keyof T) => void;
+    /** Returns a submit handler. The onValid callback receives the fully validated T from schema.safeParse. */
+    handleSubmit: (onValid: (data: T) => Promise<void>) => (e?: React.FormEvent) => Promise<void>;
+    reset: (values?: Partial<T>) => void;
+}
+declare function useForm<T extends Record<string, unknown>>(schema: ZodSchema<T>, options?: UseFormOptions<T>): UseFormReturn<T>;
+
+interface FormFieldProps {
+    label: string;
+    error?: string;
+    required?: boolean;
+    children: React$1.ReactNode;
+    className?: string;
+}
+declare function FormField({ label, error, required, children, className, }: FormFieldProps): react_jsx_runtime.JSX.Element;
+
+interface FormSectionProps {
+    title?: string;
+    children: React$1.ReactNode;
+    className?: string;
+}
+declare function FormSection({ title, children, className, }: FormSectionProps): react_jsx_runtime.JSX.Element;
+
+interface FormErrorProps {
+    message: string;
+    className?: string;
+}
+declare function FormError({ message, className }: FormErrorProps): react_jsx_runtime.JSX.Element;
+
+interface FormRowProps {
+    children: React$1.ReactNode;
+    className?: string;
+}
+declare function FormRow({ children, className }: FormRowProps): react_jsx_runtime.JSX.Element;
+
+export { FormError, type FormErrorProps, FormField, type FormFieldProps, FormRow, type FormRowProps, FormSection, type FormSectionProps, type UseFormOptions, type UseFormReturn, useForm };

package/dist/index.js

@@ -0,0 +1,130 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/hooks/useForm.ts
+function mapZodErrors(error) {
+  const mapped = {};
+  for (const issue of error.issues) {
+    const key = issue.path[0];
+    if (key !== void 0 && !(key in mapped)) {
+      mapped[key] = issue.message;
+    }
+  }
+  return mapped;
+}
+function useForm(schema, options) {
+  const initialValues = options?.initial ?? {};
+  const initialRef = react.useRef(initialValues);
+  const [values, setValues] = react.useState(initialValues);
+  const [errors, setErrors] = react.useState({});
+  const [isSubmitting, setIsSubmitting] = react.useState(false);
+  const [isDirty, setIsDirty] = react.useState(false);
+  const setFieldValue = react.useCallback((field, value) => {
+    setValues((prev) => ({ ...prev, [field]: value }));
+    setIsDirty(true);
+    setErrors((prev) => {
+      if (!(field in prev)) return prev;
+      const next = { ...prev };
+      delete next[field];
+      return next;
+    });
+  }, []);
+  const setError = react.useCallback((field, message) => {
+    setErrors((prev) => ({ ...prev, [field]: message }));
+  }, []);
+  const clearError = react.useCallback((field) => {
+    setErrors((prev) => {
+      if (!(field in prev)) return prev;
+      const next = { ...prev };
+      delete next[field];
+      return next;
+    });
+  }, []);
+  const handleSubmit = react.useCallback(
+    (onValid) => {
+      return async (e) => {
+        if (e) e.preventDefault();
+        const result = schema.safeParse(values);
+        if (!result.success) {
+          setErrors(mapZodErrors(result.error));
+          return;
+        }
+        setIsSubmitting(true);
+        try {
+          await onValid(result.data);
+        } finally {
+          setIsSubmitting(false);
+        }
+      };
+    },
+    [schema, values]
+  );
+  const reset = react.useCallback(
+    (newValues) => {
+      setValues(newValues ?? initialRef.current);
+      setErrors({});
+      setIsDirty(false);
+    },
+    []
+  );
+  return {
+    values,
+    errors,
+    isSubmitting,
+    isDirty,
+    setFieldValue,
+    setError,
+    clearError,
+    handleSubmit,
+    reset
+  };
+}
+function FormField({
+  label,
+  error,
+  required = false,
+  children,
+  className = ""
+}) {
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: `space-y-2 ${className}`.trim(), children: [
+    /* @__PURE__ */ jsxRuntime.jsxs("label", { className: "text-sm font-medium leading-none", children: [
+      label,
+      required && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "text-red-500 ml-0.5", children: "*" })
+    ] }),
+    children,
+    error && /* @__PURE__ */ jsxRuntime.jsx("p", { className: "text-sm text-red-600", children: error })
+  ] });
+}
+function FormSection({
+  title,
+  children,
+  className = ""
+}) {
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: `space-y-4 ${className}`.trim(), children: [
+    title && /* @__PURE__ */ jsxRuntime.jsx("h3", { className: "text-sm font-medium leading-none", children: title }),
+    /* @__PURE__ */ jsxRuntime.jsx("div", { className: "space-y-4", children })
+  ] });
+}
+function FormError({ message, className = "" }) {
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "div",
+    {
+      role: "alert",
+      className: `text-sm text-red-600 bg-red-50 p-3 rounded border border-red-200 ${className}`.trim(),
+      children: message
+    }
+  );
+}
+function FormRow({ children, className = "" }) {
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { className: `grid gap-4 sm:grid-cols-2 ${className}`.trim(), children });
+}
+
+exports.FormError = FormError;
+exports.FormField = FormField;
+exports.FormRow = FormRow;
+exports.FormSection = FormSection;
+exports.useForm = useForm;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/useForm.ts","../src/components/FormField.tsx","../src/components/FormSection.tsx","../src/components/FormError.tsx","../src/components/FormRow.tsx"],"names":["useRef","useState","useCallback","jsxs","jsx"],"mappings":"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","file":"index.js","sourcesContent":["import { useState, useCallback, useRef } from 'react'\nimport type { ZodSchema, ZodError } from 'zod'\n\nexport interface UseFormOptions<T> {\n  initial?: Partial<T>\n}\n\nexport interface UseFormReturn<T extends Record<string, unknown>> {\n  /** Current form values. Partial because fields may not be set yet.\n   *  For the fully validated T, use the data passed to handleSubmit's onValid callback. */\n  values: Partial<T>\n  errors: Partial<Record<keyof T, string>>\n  isSubmitting: boolean\n  isDirty: boolean\n  setFieldValue: <K extends keyof T>(field: K, value: T[K]) => void\n  setError: (field: keyof T, message: string) => void\n  clearError: (field: keyof T) => void\n  /** Returns a submit handler. The onValid callback receives the fully validated T from schema.safeParse. */\n  handleSubmit: (onValid: (data: T) => Promise<void>) => (e?: React.FormEvent) => Promise<void>\n  reset: (values?: Partial<T>) => void\n}\n\nfunction mapZodErrors<T extends Record<string, unknown>>(\n  error: ZodError\n): Partial<Record<keyof T, string>> {\n  const mapped: Partial<Record<keyof T, string>> = {}\n  for (const issue of error.issues) {\n    const key = issue.path[0]\n    if (key !== undefined && !(key in mapped)) {\n      mapped[key as keyof T] = issue.message\n    }\n  }\n  return mapped\n}\n\nexport function useForm<T extends Record<string, unknown>>(\n  schema: ZodSchema<T>,\n  options?: UseFormOptions<T>\n): UseFormReturn<T> {\n  const initialValues = options?.initial ?? {}\n  const initialRef = useRef(initialValues)\n\n  const [values, setValues] = useState<Partial<T>>(initialValues)\n  const [errors, setErrors] = useState<Partial<Record<keyof T, string>>>({})\n  const [isSubmitting, setIsSubmitting] = useState(false)\n  const [isDirty, setIsDirty] = useState(false)\n\n  const setFieldValue = useCallback(<K extends keyof T>(field: K, value: T[K]) => {\n    setValues(prev => ({ ...prev, [field]: value }))\n    setIsDirty(true)\n    // Clear error for this field when user changes it\n    setErrors(prev => {\n      if (!(field in prev)) return prev\n      const next = { ...prev }\n      delete next[field]\n      return next\n    })\n  }, [])\n\n  const setError = useCallback((field: keyof T, message: string) => {\n    setErrors(prev => ({ ...prev, [field]: message }))\n  }, [])\n\n  const clearError = useCallback((field: keyof T) => {\n    setErrors(prev => {\n      if (!(field in prev)) return prev\n      const next = { ...prev }\n      delete next[field]\n      return next\n    })\n  }, [])\n\n  const handleSubmit = useCallback(\n    (onValid: (data: T) => Promise<void>) => {\n      return async (e?: React.FormEvent) => {\n        if (e) e.preventDefault()\n\n        const result = schema.safeParse(values)\n\n        if (!result.success) {\n          setErrors(mapZodErrors<T>(result.error))\n          return\n        }\n\n        setIsSubmitting(true)\n        try {\n          await onValid(result.data)\n        } finally {\n          setIsSubmitting(false)\n        }\n      }\n    },\n    [schema, values]\n  )\n\n  const reset = useCallback(\n    (newValues?: Partial<T>) => {\n      setValues(newValues ?? initialRef.current)\n      setErrors({})\n      setIsDirty(false)\n    },\n    []\n  )\n\n  return {\n    values,\n    errors,\n    isSubmitting,\n    isDirty,\n    setFieldValue,\n    setError,\n    clearError,\n    handleSubmit,\n    reset,\n  }\n}\n","import React from 'react'\n\nexport interface FormFieldProps {\n  label: string\n  error?: string\n  required?: boolean\n  children: React.ReactNode\n  className?: string\n}\n\nexport function FormField({\n  label,\n  error,\n  required = false,\n  children,\n  className = '',\n}: FormFieldProps) {\n  return (\n    <div className={`space-y-2 ${className}`.trim()}>\n      <label className=\"text-sm font-medium leading-none\">\n        {label}\n        {required && <span className=\"text-red-500 ml-0.5\">*</span>}\n      </label>\n      {children}\n      {error && <p className=\"text-sm text-red-600\">{error}</p>}\n    </div>\n  )\n}\n","import React from 'react'\n\nexport interface FormSectionProps {\n  title?: string\n  children: React.ReactNode\n  className?: string\n}\n\nexport function FormSection({\n  title,\n  children,\n  className = '',\n}: FormSectionProps) {\n  return (\n    <div className={`space-y-4 ${className}`.trim()}>\n      {title && (\n        <h3 className=\"text-sm font-medium leading-none\">{title}</h3>\n      )}\n      <div className=\"space-y-4\">{children}</div>\n    </div>\n  )\n}\n","import React from 'react'\n\nexport interface FormErrorProps {\n  message: string\n  className?: string\n}\n\nexport function FormError({ message, className = '' }: FormErrorProps) {\n  return (\n    <div\n      role=\"alert\"\n      className={`text-sm text-red-600 bg-red-50 p-3 rounded border border-red-200 ${className}`.trim()}\n    >\n      {message}\n    </div>\n  )\n}\n","import React from 'react'\n\nexport interface FormRowProps {\n  children: React.ReactNode\n  className?: string\n}\n\nexport function FormRow({ children, className = '' }: FormRowProps) {\n  return (\n    <div className={`grid gap-4 sm:grid-cols-2 ${className}`.trim()}>\n      {children}\n    </div>\n  )\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,124 @@
+import { useRef, useState, useCallback } from 'react';
+import { jsxs, jsx } from 'react/jsx-runtime';
+
+// src/hooks/useForm.ts
+function mapZodErrors(error) {
+  const mapped = {};
+  for (const issue of error.issues) {
+    const key = issue.path[0];
+    if (key !== void 0 && !(key in mapped)) {
+      mapped[key] = issue.message;
+    }
+  }
+  return mapped;
+}
+function useForm(schema, options) {
+  const initialValues = options?.initial ?? {};
+  const initialRef = useRef(initialValues);
+  const [values, setValues] = useState(initialValues);
+  const [errors, setErrors] = useState({});
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [isDirty, setIsDirty] = useState(false);
+  const setFieldValue = useCallback((field, value) => {
+    setValues((prev) => ({ ...prev, [field]: value }));
+    setIsDirty(true);
+    setErrors((prev) => {
+      if (!(field in prev)) return prev;
+      const next = { ...prev };
+      delete next[field];
+      return next;
+    });
+  }, []);
+  const setError = useCallback((field, message) => {
+    setErrors((prev) => ({ ...prev, [field]: message }));
+  }, []);
+  const clearError = useCallback((field) => {
+    setErrors((prev) => {
+      if (!(field in prev)) return prev;
+      const next = { ...prev };
+      delete next[field];
+      return next;
+    });
+  }, []);
+  const handleSubmit = useCallback(
+    (onValid) => {
+      return async (e) => {
+        if (e) e.preventDefault();
+        const result = schema.safeParse(values);
+        if (!result.success) {
+          setErrors(mapZodErrors(result.error));
+          return;
+        }
+        setIsSubmitting(true);
+        try {
+          await onValid(result.data);
+        } finally {
+          setIsSubmitting(false);
+        }
+      };
+    },
+    [schema, values]
+  );
+  const reset = useCallback(
+    (newValues) => {
+      setValues(newValues ?? initialRef.current);
+      setErrors({});
+      setIsDirty(false);
+    },
+    []
+  );
+  return {
+    values,
+    errors,
+    isSubmitting,
+    isDirty,
+    setFieldValue,
+    setError,
+    clearError,
+    handleSubmit,
+    reset
+  };
+}
+function FormField({
+  label,
+  error,
+  required = false,
+  children,
+  className = ""
+}) {
+  return /* @__PURE__ */ jsxs("div", { className: `space-y-2 ${className}`.trim(), children: [
+    /* @__PURE__ */ jsxs("label", { className: "text-sm font-medium leading-none", children: [
+      label,
+      required && /* @__PURE__ */ jsx("span", { className: "text-red-500 ml-0.5", children: "*" })
+    ] }),
+    children,
+    error && /* @__PURE__ */ jsx("p", { className: "text-sm text-red-600", children: error })
+  ] });
+}
+function FormSection({
+  title,
+  children,
+  className = ""
+}) {
+  return /* @__PURE__ */ jsxs("div", { className: `space-y-4 ${className}`.trim(), children: [
+    title && /* @__PURE__ */ jsx("h3", { className: "text-sm font-medium leading-none", children: title }),
+    /* @__PURE__ */ jsx("div", { className: "space-y-4", children })
+  ] });
+}
+function FormError({ message, className = "" }) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      role: "alert",
+      className: `text-sm text-red-600 bg-red-50 p-3 rounded border border-red-200 ${className}`.trim(),
+      children: message
+    }
+  );
+}
+function FormRow({ children, className = "" }) {
+  return /* @__PURE__ */ jsx("div", { className: `grid gap-4 sm:grid-cols-2 ${className}`.trim(), children });
+}
+
+export { FormError, FormField, FormRow, FormSection, useForm };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/useForm.ts","../src/components/FormField.tsx","../src/components/FormSection.tsx","../src/components/FormError.tsx","../src/components/FormRow.tsx"],"names":["jsxs","jsx"],"mappings":"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","file":"index.mjs","sourcesContent":["import { useState, useCallback, useRef } from 'react'\nimport type { ZodSchema, ZodError } from 'zod'\n\nexport interface UseFormOptions<T> {\n  initial?: Partial<T>\n}\n\nexport interface UseFormReturn<T extends Record<string, unknown>> {\n  /** Current form values. Partial because fields may not be set yet.\n   *  For the fully validated T, use the data passed to handleSubmit's onValid callback. */\n  values: Partial<T>\n  errors: Partial<Record<keyof T, string>>\n  isSubmitting: boolean\n  isDirty: boolean\n  setFieldValue: <K extends keyof T>(field: K, value: T[K]) => void\n  setError: (field: keyof T, message: string) => void\n  clearError: (field: keyof T) => void\n  /** Returns a submit handler. The onValid callback receives the fully validated T from schema.safeParse. */\n  handleSubmit: (onValid: (data: T) => Promise<void>) => (e?: React.FormEvent) => Promise<void>\n  reset: (values?: Partial<T>) => void\n}\n\nfunction mapZodErrors<T extends Record<string, unknown>>(\n  error: ZodError\n): Partial<Record<keyof T, string>> {\n  const mapped: Partial<Record<keyof T, string>> = {}\n  for (const issue of error.issues) {\n    const key = issue.path[0]\n    if (key !== undefined && !(key in mapped)) {\n      mapped[key as keyof T] = issue.message\n    }\n  }\n  return mapped\n}\n\nexport function useForm<T extends Record<string, unknown>>(\n  schema: ZodSchema<T>,\n  options?: UseFormOptions<T>\n): UseFormReturn<T> {\n  const initialValues = options?.initial ?? {}\n  const initialRef = useRef(initialValues)\n\n  const [values, setValues] = useState<Partial<T>>(initialValues)\n  const [errors, setErrors] = useState<Partial<Record<keyof T, string>>>({})\n  const [isSubmitting, setIsSubmitting] = useState(false)\n  const [isDirty, setIsDirty] = useState(false)\n\n  const setFieldValue = useCallback(<K extends keyof T>(field: K, value: T[K]) => {\n    setValues(prev => ({ ...prev, [field]: value }))\n    setIsDirty(true)\n    // Clear error for this field when user changes it\n    setErrors(prev => {\n      if (!(field in prev)) return prev\n      const next = { ...prev }\n      delete next[field]\n      return next\n    })\n  }, [])\n\n  const setError = useCallback((field: keyof T, message: string) => {\n    setErrors(prev => ({ ...prev, [field]: message }))\n  }, [])\n\n  const clearError = useCallback((field: keyof T) => {\n    setErrors(prev => {\n      if (!(field in prev)) return prev\n      const next = { ...prev }\n      delete next[field]\n      return next\n    })\n  }, [])\n\n  const handleSubmit = useCallback(\n    (onValid: (data: T) => Promise<void>) => {\n      return async (e?: React.FormEvent) => {\n        if (e) e.preventDefault()\n\n        const result = schema.safeParse(values)\n\n        if (!result.success) {\n          setErrors(mapZodErrors<T>(result.error))\n          return\n        }\n\n        setIsSubmitting(true)\n        try {\n          await onValid(result.data)\n        } finally {\n          setIsSubmitting(false)\n        }\n      }\n    },\n    [schema, values]\n  )\n\n  const reset = useCallback(\n    (newValues?: Partial<T>) => {\n      setValues(newValues ?? initialRef.current)\n      setErrors({})\n      setIsDirty(false)\n    },\n    []\n  )\n\n  return {\n    values,\n    errors,\n    isSubmitting,\n    isDirty,\n    setFieldValue,\n    setError,\n    clearError,\n    handleSubmit,\n    reset,\n  }\n}\n","import React from 'react'\n\nexport interface FormFieldProps {\n  label: string\n  error?: string\n  required?: boolean\n  children: React.ReactNode\n  className?: string\n}\n\nexport function FormField({\n  label,\n  error,\n  required = false,\n  children,\n  className = '',\n}: FormFieldProps) {\n  return (\n    <div className={`space-y-2 ${className}`.trim()}>\n      <label className=\"text-sm font-medium leading-none\">\n        {label}\n        {required && <span className=\"text-red-500 ml-0.5\">*</span>}\n      </label>\n      {children}\n      {error && <p className=\"text-sm text-red-600\">{error}</p>}\n    </div>\n  )\n}\n","import React from 'react'\n\nexport interface FormSectionProps {\n  title?: string\n  children: React.ReactNode\n  className?: string\n}\n\nexport function FormSection({\n  title,\n  children,\n  className = '',\n}: FormSectionProps) {\n  return (\n    <div className={`space-y-4 ${className}`.trim()}>\n      {title && (\n        <h3 className=\"text-sm font-medium leading-none\">{title}</h3>\n      )}\n      <div className=\"space-y-4\">{children}</div>\n    </div>\n  )\n}\n","import React from 'react'\n\nexport interface FormErrorProps {\n  message: string\n  className?: string\n}\n\nexport function FormError({ message, className = '' }: FormErrorProps) {\n  return (\n    <div\n      role=\"alert\"\n      className={`text-sm text-red-600 bg-red-50 p-3 rounded border border-red-200 ${className}`.trim()}\n    >\n      {message}\n    </div>\n  )\n}\n","import React from 'react'\n\nexport interface FormRowProps {\n  children: React.ReactNode\n  className?: string\n}\n\nexport function FormRow({ children, className = '' }: FormRowProps) {\n  return (\n    <div className={`grid gap-4 sm:grid-cols-2 ${className}`.trim()}>\n      {children}\n    </div>\n  )\n}\n"]}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@startsimpli/forms",
+  "version": "0.1.1",
+  "description": "Thin form state management with Zod validation for StartSimpli apps",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "zod": ">=3"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.0.0",
+    "@types/react": "^18.2.0",
+    "jsdom": "^24.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0",
+    "zod": "^3.22.0"
+  },
+  "module": "./dist/index.mjs"
+}

package/src/__tests__/useForm.test.ts

@@ -0,0 +1,178 @@
+import { renderHook, act } from '@testing-library/react'
+import { z } from 'zod'
+import { useForm } from '../hooks/useForm'
+
+const testSchema = z.object({
+  name: z.string().min(1, 'Name is required'),
+  email: z.string().email('Invalid email'),
+  age: z.number().min(0, 'Age must be positive').optional(),
+})
+
+type TestData = z.infer<typeof testSchema>
+
+describe('useForm', () => {
+  it('setFieldValue clears the error for that field', () => {
+    const { result } = renderHook(() => useForm(testSchema))
+
+    // Manually set an error on the name field
+    act(() => {
+      result.current.setError('name', 'Name is required')
+    })
+    expect(result.current.errors.name).toBe('Name is required')
+
+    // Setting the field value should clear the error
+    act(() => {
+      result.current.setFieldValue('name', 'Alice')
+    })
+    expect(result.current.errors.name).toBeUndefined()
+    expect(result.current.values.name).toBe('Alice')
+  })
+
+  it('handleSubmit with invalid data sets field errors and does NOT call onValid', async () => {
+    const onValid = vi.fn()
+    const { result } = renderHook(() => useForm(testSchema))
+
+    // Submit with empty values — name and email are required
+    await act(async () => {
+      const submitFn = result.current.handleSubmit(onValid)
+      await submitFn()
+    })
+
+    expect(onValid).not.toHaveBeenCalled()
+    expect(result.current.errors.name).toBeDefined()
+    expect(result.current.errors.email).toBeDefined()
+  })
+
+  it('handleSubmit with valid data calls onValid and sets isSubmitting during call', async () => {
+    let submittingDuringCall = false
+    const onValid = vi.fn(async () => {
+      // Capture isSubmitting state during the callback
+      submittingDuringCall = true
+      // Simulate async work
+      await new Promise(resolve => setTimeout(resolve, 10))
+    })
+
+    const { result } = renderHook(() =>
+      useForm(testSchema, {
+        initial: { name: 'Alice', email: 'alice@example.com' },
+      })
+    )
+
+    // isSubmitting should be false before submission
+    expect(result.current.isSubmitting).toBe(false)
+
+    await act(async () => {
+      const submitFn = result.current.handleSubmit(async (data) => {
+        // Check isSubmitting is true during execution
+        submittingDuringCall = result.current.isSubmitting
+        await onValid(data)
+      })
+      await submitFn()
+    })
+
+    expect(onValid).toHaveBeenCalledWith({
+      name: 'Alice',
+      email: 'alice@example.com',
+    })
+    // isSubmitting should be back to false after completion
+    expect(result.current.isSubmitting).toBe(false)
+  })
+
+  it('reset() clears values and errors', () => {
+    const { result } = renderHook(() =>
+      useForm(testSchema, {
+        initial: { name: 'Bob', email: 'bob@test.com' },
+      })
+    )
+
+    // Modify values and set errors
+    act(() => {
+      result.current.setFieldValue('name', 'Changed')
+      result.current.setError('email', 'Bad email')
+    })
+
+    expect(result.current.values.name).toBe('Changed')
+    expect(result.current.errors.email).toBe('Bad email')
+    expect(result.current.isDirty).toBe(true)
+
+    // Reset should restore initial values and clear errors
+    act(() => {
+      result.current.reset()
+    })
+
+    expect(result.current.values.name).toBe('Bob')
+    expect(result.current.values.email).toBe('bob@test.com')
+    expect(result.current.errors).toEqual({})
+    expect(result.current.isDirty).toBe(false)
+  })
+
+  it('Zod error messages appear correctly in errors map', async () => {
+    const onValid = vi.fn()
+    const { result } = renderHook(() =>
+      useForm(testSchema, {
+        initial: { name: '', email: 'not-an-email' },
+      })
+    )
+
+    await act(async () => {
+      const submitFn = result.current.handleSubmit(onValid)
+      await submitFn()
+    })
+
+    expect(onValid).not.toHaveBeenCalled()
+    expect(result.current.errors.name).toBe('Name is required')
+    expect(result.current.errors.email).toBe('Invalid email')
+  })
+
+  it('handleSubmit prevents default on form events', async () => {
+    const onValid = vi.fn()
+    const preventDefault = vi.fn()
+    const { result } = renderHook(() =>
+      useForm(testSchema, {
+        initial: { name: 'Test', email: 'test@test.com' },
+      })
+    )
+
+    await act(async () => {
+      const submitFn = result.current.handleSubmit(onValid)
+      await submitFn({ preventDefault } as unknown as React.FormEvent)
+    })
+
+    expect(preventDefault).toHaveBeenCalled()
+  })
+
+  it('clearError removes a specific field error', () => {
+    const { result } = renderHook(() => useForm(testSchema))
+
+    act(() => {
+      result.current.setError('name', 'Error 1')
+      result.current.setError('email', 'Error 2')
+    })
+
+    expect(result.current.errors.name).toBe('Error 1')
+    expect(result.current.errors.email).toBe('Error 2')
+
+    act(() => {
+      result.current.clearError('name')
+    })
+
+    expect(result.current.errors.name).toBeUndefined()
+    expect(result.current.errors.email).toBe('Error 2')
+  })
+
+  it('reset with new values uses those instead of initial', () => {
+    const { result } = renderHook(() =>
+      useForm(testSchema, {
+        initial: { name: 'Original', email: 'orig@test.com' },
+      })
+    )
+
+    act(() => {
+      result.current.reset({ name: 'New', email: 'new@test.com' })
+    })
+
+    expect(result.current.values.name).toBe('New')
+    expect(result.current.values.email).toBe('new@test.com')
+    expect(result.current.isDirty).toBe(false)
+  })
+})

package/src/components/FormError.tsx

@@ -0,0 +1,17 @@
+import React from 'react'
+
+export interface FormErrorProps {
+  message: string
+  className?: string
+}
+
+export function FormError({ message, className = '' }: FormErrorProps) {
+  return (
+    <div
+      role="alert"
+      className={`text-sm text-red-600 bg-red-50 p-3 rounded border border-red-200 ${className}`.trim()}
+    >
+      {message}
+    </div>
+  )
+}

package/src/components/FormField.tsx

@@ -0,0 +1,28 @@
+import React from 'react'
+
+export interface FormFieldProps {
+  label: string
+  error?: string
+  required?: boolean
+  children: React.ReactNode
+  className?: string
+}
+
+export function FormField({
+  label,
+  error,
+  required = false,
+  children,
+  className = '',
+}: FormFieldProps) {
+  return (
+    <div className={`space-y-2 ${className}`.trim()}>
+      <label className="text-sm font-medium leading-none">
+        {label}
+        {required && <span className="text-red-500 ml-0.5">*</span>}
+      </label>
+      {children}
+      {error && <p className="text-sm text-red-600">{error}</p>}
+    </div>
+  )
+}

package/src/components/FormRow.tsx

@@ -0,0 +1,14 @@
+import React from 'react'
+
+export interface FormRowProps {
+  children: React.ReactNode
+  className?: string
+}
+
+export function FormRow({ children, className = '' }: FormRowProps) {
+  return (
+    <div className={`grid gap-4 sm:grid-cols-2 ${className}`.trim()}>
+      {children}
+    </div>
+  )
+}

package/src/components/FormSection.tsx

@@ -0,0 +1,22 @@
+import React from 'react'
+
+export interface FormSectionProps {
+  title?: string
+  children: React.ReactNode
+  className?: string
+}
+
+export function FormSection({
+  title,
+  children,
+  className = '',
+}: FormSectionProps) {
+  return (
+    <div className={`space-y-4 ${className}`.trim()}>
+      {title && (
+        <h3 className="text-sm font-medium leading-none">{title}</h3>
+      )}
+      <div className="space-y-4">{children}</div>
+    </div>
+  )
+}

package/src/hooks/useForm.ts

@@ -0,0 +1,116 @@
+import { useState, useCallback, useRef } from 'react'
+import type { ZodSchema, ZodError } from 'zod'
+
+export interface UseFormOptions<T> {
+  initial?: Partial<T>
+}
+
+export interface UseFormReturn<T extends Record<string, unknown>> {
+  /** Current form values. Partial because fields may not be set yet.
+   *  For the fully validated T, use the data passed to handleSubmit's onValid callback. */
+  values: Partial<T>
+  errors: Partial<Record<keyof T, string>>
+  isSubmitting: boolean
+  isDirty: boolean
+  setFieldValue: <K extends keyof T>(field: K, value: T[K]) => void
+  setError: (field: keyof T, message: string) => void
+  clearError: (field: keyof T) => void
+  /** Returns a submit handler. The onValid callback receives the fully validated T from schema.safeParse. */
+  handleSubmit: (onValid: (data: T) => Promise<void>) => (e?: React.FormEvent) => Promise<void>
+  reset: (values?: Partial<T>) => void
+}
+
+function mapZodErrors<T extends Record<string, unknown>>(
+  error: ZodError
+): Partial<Record<keyof T, string>> {
+  const mapped: Partial<Record<keyof T, string>> = {}
+  for (const issue of error.issues) {
+    const key = issue.path[0]
+    if (key !== undefined && !(key in mapped)) {
+      mapped[key as keyof T] = issue.message
+    }
+  }
+  return mapped
+}
+
+export function useForm<T extends Record<string, unknown>>(
+  schema: ZodSchema<T>,
+  options?: UseFormOptions<T>
+): UseFormReturn<T> {
+  const initialValues = options?.initial ?? {}
+  const initialRef = useRef(initialValues)
+
+  const [values, setValues] = useState<Partial<T>>(initialValues)
+  const [errors, setErrors] = useState<Partial<Record<keyof T, string>>>({})
+  const [isSubmitting, setIsSubmitting] = useState(false)
+  const [isDirty, setIsDirty] = useState(false)
+
+  const setFieldValue = useCallback(<K extends keyof T>(field: K, value: T[K]) => {
+    setValues(prev => ({ ...prev, [field]: value }))
+    setIsDirty(true)
+    // Clear error for this field when user changes it
+    setErrors(prev => {
+      if (!(field in prev)) return prev
+      const next = { ...prev }
+      delete next[field]
+      return next
+    })
+  }, [])
+
+  const setError = useCallback((field: keyof T, message: string) => {
+    setErrors(prev => ({ ...prev, [field]: message }))
+  }, [])
+
+  const clearError = useCallback((field: keyof T) => {
+    setErrors(prev => {
+      if (!(field in prev)) return prev
+      const next = { ...prev }
+      delete next[field]
+      return next
+    })
+  }, [])
+
+  const handleSubmit = useCallback(
+    (onValid: (data: T) => Promise<void>) => {
+      return async (e?: React.FormEvent) => {
+        if (e) e.preventDefault()
+
+        const result = schema.safeParse(values)
+
+        if (!result.success) {
+          setErrors(mapZodErrors<T>(result.error))
+          return
+        }
+
+        setIsSubmitting(true)
+        try {
+          await onValid(result.data)
+        } finally {
+          setIsSubmitting(false)
+        }
+      }
+    },
+    [schema, values]
+  )
+
+  const reset = useCallback(
+    (newValues?: Partial<T>) => {
+      setValues(newValues ?? initialRef.current)
+      setErrors({})
+      setIsDirty(false)
+    },
+    []
+  )
+
+  return {
+    values,
+    errors,
+    isSubmitting,
+    isDirty,
+    setFieldValue,
+    setError,
+    clearError,
+    handleSubmit,
+    reset,
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { useForm } from './hooks/useForm'
+export type { UseFormOptions, UseFormReturn } from './hooks/useForm'
+
+export { FormField } from './components/FormField'
+export type { FormFieldProps } from './components/FormField'
+
+export { FormSection } from './components/FormSection'
+export type { FormSectionProps } from './components/FormSection'
+
+export { FormError } from './components/FormError'
+export type { FormErrorProps } from './components/FormError'
+
+export { FormRow } from './components/FormRow'
+export type { FormRowProps } from './components/FormRow'