@vuehookform/core 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 vuehookform
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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
+AUTHORS OR COPYRIGHT HOLDERS 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.

package/README.md

@@ -1,57 +1,44 @@
-# Vue Hook Form 📝
+# Vue Hook Form
 
-> A TypeScript-first form library for Vue 3, inspired by React Hook Form
+A TypeScript-first form library for Vue 3, inspired by React Hook Form.
 
-**Vue Hook Form** makes form handling in Vue.js feel like a superpower. Built with performance, developer experience, and type safety as top priorities.
+## Features
 
-## ✨ Features
+- **TypeScript First** - Perfect type inference with zero manual typing
+- **Zero Config** - Works out of the box with sensible defaults
+- **Performant** - Minimal re-renders using uncontrolled inputs
+- **Zod Native** - First-class Zod integration for validation
+- **Tiny Bundle** - < 5kb gzipped, tree-shakable
+- **UI Agnostic** - Works with any UI library or custom components
 
-- **🎯 TypeScript First** - Perfect type inference with zero manual typing
-- **⚡ Zero Config** - Works out of the box with sensible defaults
-- **🚀 Performant** - Minimal re-renders using uncontrolled inputs
-- **🔥 Zod Native** - First-class Zod integration for validation
-- **📦 Tiny Bundle** - Tree-shakable and dependency-free (< 10kb gzipped)
-- **🎨 UI Agnostic** - Works with any UI library or custom components
-- **🔌 Composable-First** - Built for Vue 3's Composition API
-
-## 🚀 Quick Start
-
-### Installation
+## Quick Start
 
 ```bash
 npm install @vuehookform/core zod
-# or
-bun add @vuehookform/core zod
 ```
 
-### Basic Usage
-
 ```vue
 <script setup lang="ts">
 import { useForm } from '@vuehookform/core'
 import { z } from 'zod'
 
-// 1. Define your schema
 const schema = z.object({
   email: z.email('Invalid email'),
   password: z.string().min(8, 'At least 8 characters'),
 })
 
-// 2. Initialize form
 const { register, handleSubmit, formState } = useForm({
   schema,
   mode: 'onBlur',
 })
 
-// 3. Handle submission
 const onSubmit = (data) => {
-  console.log(data) // Fully typed! { email: string, password: string }
+  console.log(data) // Fully typed: { email: string, password: string }
 }
 </script>
 
 <template>
   <form @submit="handleSubmit(onSubmit)">
-    <!-- Bind inputs with v-bind -->
     <input v-bind="register('email')" type="email" />
     <span v-if="formState.errors.email">{{ formState.errors.email }}</span>
 
@@ -63,33 +50,10 @@ const onSubmit = (data) => {
 </template>
 ```
 
-That's it! Three steps and you have a fully validated, type-safe form. 🎉
-
-## 📚 Examples
-
-This repo includes working examples showcasing all features:
-
-### Run Examples
-
-```bash
-# Install dependencies
-npm install
-
-# Start dev server
-npm run dev
-```
-
-Then open http://localhost:5173 to see:
-
-1. **Basic Form** - Simple validation, error handling, form state
-2. **Dynamic Arrays** - Add/remove nested form sections dynamically
-
-## 💡 Key Concepts
+## Key Concepts
 
 ### Schema as Source of Truth
 
-Define your form structure and validation in one place:
-
 ```typescript
 const userSchema = z.object({
   name: z.string().min(2),
@@ -97,20 +61,15 @@ const userSchema = z.object({
   age: z.number().min(18),
 })
 
-// Types are automatically inferred
 type UserForm = z.infer<typeof userSchema>
 // { name: string; email: string; age: number }
 ```
 
-### Zero-Boilerplate Dynamic Arrays
-
-Managing dynamic form sections is trivial:
+### Dynamic Arrays
 
 ```vue
 <script setup>
 const { register, fields } = useForm({ schema })
-
-// Get field array manager
 const addresses = fields('addresses')
 </script>
 
@@ -119,194 +78,60 @@ const addresses = fields('addresses')
     <input v-bind="register(`addresses.${field.index}.street`)" />
     <button @click="field.remove()">Remove</button>
   </div>
-
   <button @click="addresses.append({ street: '', city: '' })">Add Address</button>
 </template>
 ```
 
 ### Validation Modes
 
-Control when validation runs:
-
 ```typescript
 useForm({
   schema,
-  mode: 'onSubmit', // Only validate on submit (default)
-  // mode: 'onBlur',      // Validate when field loses focus
-  // mode: 'onChange',    // Validate on every keystroke
-  // mode: 'onTouched',   // Validate after field is touched
+  mode: 'onSubmit',  // Only validate on submit (default)
+  // mode: 'onBlur',    // Validate when field loses focus
+  // mode: 'onChange',  // Validate on every keystroke
+  // mode: 'onTouched', // Validate after field is touched
 })
 ```
 
-## 🎨 API Reference
+## API Reference
 
 ### `useForm(options)`
 
-Main composable for form management.
-
-**Options:**
-
 ```typescript
-{
-  schema: ZodSchema          // Zod schema for validation
-  defaultValues?: Partial<T> // Initial form values
-  mode?: ValidationMode      // When to validate
-}
-```
-
-**Returns:**
-
-```typescript
-{
-  register: (name, options?) => RegisterReturn
-  handleSubmit: (onValid, onInvalid?) => (e) => Promise<void>
-  formState: ComputedRef<FormState>
-  fields: (name) => FieldArray
-  setValue: (name, value) => void
-  getValue: (name) => any
-  reset: (values?) => void
-  watch: (name?) => ComputedRef<any>
-  validate: (name?) => Promise<boolean>
-}
-```
-
-### `register(name, options?)`
-
-Register an input field for validation and state management.
-
-```vue
-<input v-bind="register('email')" />
-<input v-bind="register('email', { controlled: true })" />
-```
-
-### `handleSubmit(onValid, onInvalid?)`
-
-Create submit handler with validation.
-
-```typescript
-const onSubmit = handleSubmit(
-  (data) => {
-    // Called with validated data
-    console.log(data)
-  },
-  (errors) => {
-    // Optional: called when validation fails
-    console.log(errors)
-  },
-)
+const {
+  register,      // Register input field
+  handleSubmit,  // Create submit handler with validation
+  formState,     // Reactive form state (errors, isSubmitting, etc.)
+  fields,        // Manage dynamic field arrays
+  setValue,      // Programmatically set field value
+  getValue,      // Get current field value
+  reset,         // Reset form to default values
+  watch,         // Watch field value changes
+  validate,      // Manually trigger validation
+} = useForm({
+  schema,                    // Zod schema for validation
+  defaultValues: {},         // Initial form values
+  mode: 'onSubmit',          // When to validate
+})
 ```
 
 ### `fields(name)`
 
-Manage dynamic field arrays.
-
 ```typescript
 const addresses = fields('addresses')
 
-addresses.append({ street: '', city: '' }) // Add item
-addresses.remove(0) // Remove by index
-addresses.insert(1, value) // Insert at index
-addresses.swap(0, 1) // Swap two items
-addresses.move(0, 2) // Move item
+addresses.append({ street: '', city: '' })
+addresses.remove(0)
+addresses.insert(1, value)
+addresses.swap(0, 1)
+addresses.move(0, 2)
 ```
 
-## 🏗️ Project Structure
-
-```
-src/
-├── lib/              # Library source code
-│   ├── index.ts      # Public exports
-│   ├── useForm.ts    # Main composable
-│   ├── types.ts      # TypeScript definitions
-│   └── utils/        # Helper functions
-├── examples/         # Demo applications
-│   ├── BasicForm.vue
-│   └── DynamicArrays.vue
-└── App.vue          # Example showcase
-```
-
-## 🎯 Why Vue Hook Form?
-
-### vs VeeValidate
-
-- **Less boilerplate** - One composable manages entire form
-- **Better performance** - Uncontrolled inputs by default
-- **Simpler API** - Form-level vs field-level management
-
-### vs FormKit
-
-- **Lighter** - < 10kb vs 50kb+
-- **Less opinionated** - No UI components required
-- **Native Zod** - First-class integration, not an adapter
-
-### vs Vuelidate
-
-- **Type-safe** - Perfect TypeScript inference
-- **Built-in arrays** - Dynamic fields work out of the box
-- **Modern** - Built for Composition API
-
-## 🔧 Development
-
-### Setup
-
-```bash
-npm install
-```
-
-### Run Dev Server
-
-```bash
-npm run dev
-```
-
-### Type Check
-
-```bash
-npm run type-check
-```
-
-### Lint
-
-```bash
-npm run lint
-```
-
-### Build
-
-```bash
-npm run build
-```
-
-## 📖 Documentation
-
-For detailed implementation notes, architecture decisions, and future roadmap, see [CORE_CONCEPTS.md](./CORE_CONCEPTS.md).
-
-## 🤝 Contributing
-
-Contributions welcome! This is a proof-of-concept library demonstrating:
-
-- Form-level state management
-- Zod-first validation
-- TypeScript-first design
-- Performance-optimized architecture
-
-Feel free to:
-
-- Report bugs
-- Suggest features
-- Submit PRs
-- Ask questions
-
-## 📝 License
-
-MIT - Build something awesome!
-
-## 🙏 Inspiration
+## Contributing
 
-- [React Hook Form](https://react-hook-form.com/) - API design inspiration
-- [Zod](https://zod.dev/) - Schema validation
-- [VeeValidate](https://vee-validate.logaretm.com/) - Vue form validation patterns
+Contributions welcome! Feel free to report bugs, suggest features, or submit PRs.
 
----
+## License
 
-**Made with ❤️ for the Vue community**
+MIT

package/dist/context.d.ts

@@ -35,4 +35,3 @@ export declare function provideForm<TSchema extends ZodType>(methods: UseFormRet
  * @throws Error if used outside of a FormProvider context
  */
 export declare function useFormContext<TSchema extends ZodType>(): UseFormReturn<TSchema>;
-//# sourceMappingURL=context.d.ts.map

package/dist/core/formContext.d.ts

@@ -8,6 +8,14 @@ export interface FieldArrayState {
     items: Ref<FieldArrayItem[]>;
     values: unknown[];
 }
+/**
+ * Cached event handlers for a field to prevent recreation on every render
+ */
+export interface FieldHandlers {
+    onInput: (e: Event) => Promise<void>;
+    onBlur: (e: Event) => Promise<void>;
+    refCallback: (el: unknown) => void;
+}
 /**
  * Shared form context containing all reactive state
  * This is passed to sub-modules via dependency injection
@@ -16,14 +24,15 @@ export interface FormContext<FormValues> {
     formData: Record<string, unknown>;
     defaultValues: Record<string, unknown>;
     errors: ShallowRef<FieldErrors<FormValues>>;
-    touchedFields: Ref<Record<string, boolean>>;
-    dirtyFields: Ref<Record<string, boolean>>;
+    touchedFields: ShallowRef<Record<string, boolean>>;
+    dirtyFields: ShallowRef<Record<string, boolean>>;
     isSubmitting: Ref<boolean>;
     isLoading: Ref<boolean>;
     submitCount: Ref<number>;
     fieldRefs: Map<string, Ref<HTMLInputElement | null>>;
     fieldOptions: Map<string, RegisterOptions>;
     fieldArrays: Map<string, FieldArrayState>;
+    fieldHandlers: Map<string, FieldHandlers>;
     debounceTimers: Map<string, ReturnType<typeof setTimeout>>;
     validationRequestIds: Map<string, number>;
     options: UseFormOptions<ZodType>;
@@ -32,4 +41,3 @@ export interface FormContext<FormValues> {
  * Create a new form context with all reactive state initialized
  */
 export declare function createFormContext<TSchema extends ZodType>(options: UseFormOptions<TSchema>): FormContext<InferSchema<TSchema>>;
-//# sourceMappingURL=formContext.d.ts.map

package/dist/core/useFieldArray.d.ts

@@ -6,4 +6,3 @@ import { FieldArray, Path } from '../types';
 export declare function createFieldArrayManager<FormValues>(ctx: FormContext<FormValues>, validate: (fieldPath?: string) => Promise<boolean>): {
     fields: <TPath extends Path<FormValues>>(name: TPath) => FieldArray;
 };
-//# sourceMappingURL=useFieldArray.d.ts.map

package/dist/core/useFieldRegistration.d.ts

@@ -7,4 +7,3 @@ export declare function createFieldRegistration<FormValues>(ctx: FormContext<For
     register: <TPath extends Path<FormValues>>(name: TPath, registerOptions?: RegisterOptions) => RegisterReturn;
     unregister: <TPath extends Path<FormValues>>(name: TPath) => void;
 };
-//# sourceMappingURL=useFieldRegistration.d.ts.map

package/dist/core/useValidation.d.ts

@@ -5,4 +5,3 @@ import { FormContext } from './formContext';
 export declare function createValidation<FormValues>(ctx: FormContext<FormValues>): {
     validate: (fieldPath?: string) => Promise<boolean>;
 };
-//# sourceMappingURL=useValidation.d.ts.map

package/dist/index.d.ts

@@ -20,4 +20,3 @@ export { useWatch, type UseWatchOptions } from './useWatch';
 export { useController, type UseControllerOptions, type UseControllerReturn, type ControllerFieldProps } from './useController';
 export { useFormState, type UseFormStateOptions, type FormStateKey } from './useFormState';
 export type { UseFormOptions, UseFormReturn, RegisterOptions, RegisterReturn, FormState, FieldState, FieldErrors, FieldError, FieldErrorValue, FieldArray, FieldArrayItem, ValidationMode, InferSchema, Path, PathValue, ErrorOption, SetFocusOptions, ResetOptions, AsyncDefaultValues, } from './types';
-//# sourceMappingURL=index.d.ts.map

package/dist/types.d.ts

@@ -287,4 +287,3 @@ export interface UseFormReturn<TSchema extends ZodType> {
      */
     setFocus: <TPath extends Path<InferSchema<TSchema>>>(name: TPath, options?: SetFocusOptions) => void;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/useController.d.ts

@@ -61,4 +61,3 @@ export interface UseControllerReturn<TValue> {
  * ```
  */
 export declare function useController<TSchema extends ZodType, TPath extends Path<InferSchema<TSchema>>>(options: UseControllerOptions<TSchema, TPath>): UseControllerReturn<PathValue<InferSchema<TSchema>, TPath>>;
-//# sourceMappingURL=useController.d.ts.map

package/dist/useForm.d.ts

@@ -18,4 +18,3 @@ import { UseFormOptions, UseFormReturn } from './types';
  * ```
  */
 export declare function useForm<TSchema extends ZodType>(options: UseFormOptions<TSchema>): UseFormReturn<TSchema>;
-//# sourceMappingURL=useForm.d.ts.map

package/dist/useFormState.d.ts

@@ -37,4 +37,3 @@ export interface UseFormStateOptions<TSchema extends ZodType> {
  * ```
  */
 export declare function useFormState<TSchema extends ZodType>(options?: UseFormStateOptions<TSchema>): ComputedRef<Partial<FormState<InferSchema<TSchema>>>>;
-//# sourceMappingURL=useFormState.d.ts.map

package/dist/useWatch.d.ts

@@ -38,4 +38,3 @@ export interface UseWatchOptions<TSchema extends ZodType, TPath extends Path<Inf
  * ```
  */
 export declare function useWatch<TSchema extends ZodType, TPath extends Path<InferSchema<TSchema>> = Path<InferSchema<TSchema>>>(options?: UseWatchOptions<TSchema, TPath>): ComputedRef<unknown>;
-//# sourceMappingURL=useWatch.d.ts.map

package/dist/utils/paths.d.ts

@@ -2,7 +2,7 @@
  * Get value from object using dot notation path
  * @example get({ user: { name: 'John' } }, 'user.name') => 'John'
  */
-export declare function get(obj: Record<string, unknown>, path: string): unknown;
+export declare function get(obj: unknown, path: string): unknown;
 /**
  * Set value in object using dot notation path
  * @example set({}, 'user.name', 'John') => { user: { name: 'John' } }
@@ -34,4 +34,3 @@ export declare function getParentPath(path: string): string | undefined;
  * @example getFieldName('user.addresses.0.street') => 'street'
  */
 export declare function getFieldName(path: string): string;
-//# sourceMappingURL=paths.d.ts.map