@vuehookform/core 0.1.0

package/README.md

@@ -0,0 +1,312 @@
+# Vue 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
+
+- **🎯 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
+
+```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 }
+}
+</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>
+
+    <input v-bind="register('password')" type="password" />
+    <span v-if="formState.errors.password">{{ formState.errors.password }}</span>
+
+    <button type="submit" :disabled="formState.isSubmitting">Submit</button>
+  </form>
+</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
+
+### Schema as Source of Truth
+
+Define your form structure and validation in one place:
+
+```typescript
+const userSchema = z.object({
+  name: z.string().min(2),
+  email: z.email(),
+  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:
+
+```vue
+<script setup>
+const { register, fields } = useForm({ schema })
+
+// Get field array manager
+const addresses = fields('addresses')
+</script>
+
+<template>
+  <div v-for="field in addresses.value" :key="field.key">
+    <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
+})
+```
+
+## 🎨 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)
+  },
+)
+```
+
+### `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
+```
+
+## 🏗️ 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
+
+- [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
+
+---
+
+**Made with ❤️ for the Vue community**

package/dist/context.d.ts

@@ -0,0 +1,38 @@
+import { InjectionKey } from 'vue';
+import { UseFormReturn } from './types';
+import { ZodType } from 'zod';
+/**
+ * Injection key for form context
+ */
+export declare const FormContextKey: InjectionKey<UseFormReturn<ZodType>>;
+/**
+ * Provide form methods to child components via Vue's dependency injection.
+ *
+ * Call this in a parent component's setup function after calling useForm().
+ *
+ * @example
+ * ```ts
+ * // Parent component
+ * const form = useForm({ schema })
+ * provideForm(form)
+ * ```
+ *
+ * @param methods - The return value from useForm()
+ */
+export declare function provideForm<TSchema extends ZodType>(methods: UseFormReturn<TSchema>): void;
+/**
+ * Access form methods in a child component via Vue's dependency injection.
+ *
+ * Must be used within a component tree where provideForm() has been called.
+ *
+ * @example
+ * ```ts
+ * // Child component
+ * const { register, formState } = useFormContext()
+ * ```
+ *
+ * @returns The form methods from the parent component's useForm() call
+ * @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/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/lib/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,KAAK,CAAA;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAA;AAElC;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,YAAY,CAAC,aAAa,CAAC,OAAO,CAAC,CAAyB,CAAA;AAEzF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,OAAO,SAAS,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,IAAI,CAE1F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,OAAO,SAAS,OAAO,KAAK,aAAa,CAAC,OAAO,CAAC,CAWhF"}

package/dist/core/formContext.d.ts

@@ -0,0 +1,35 @@
+import { Ref, ShallowRef } from 'vue';
+import { ZodType } from 'zod';
+import { UseFormOptions, FieldErrors, InferSchema, RegisterOptions, FieldArrayItem } from '../types';
+/**
+ * Internal state for field array management
+ */
+export interface FieldArrayState {
+    items: Ref<FieldArrayItem[]>;
+    values: unknown[];
+}
+/**
+ * Shared form context containing all reactive state
+ * This is passed to sub-modules via dependency injection
+ */
+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>>;
+    isSubmitting: Ref<boolean>;
+    isLoading: Ref<boolean>;
+    submitCount: Ref<number>;
+    fieldRefs: Map<string, Ref<HTMLInputElement | null>>;
+    fieldOptions: Map<string, RegisterOptions>;
+    fieldArrays: Map<string, FieldArrayState>;
+    debounceTimers: Map<string, ReturnType<typeof setTimeout>>;
+    validationRequestIds: Map<string, number>;
+    options: UseFormOptions<ZodType>;
+}
+/**
+ * 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/formContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formContext.d.ts","sourceRoot":"","sources":["../../src/lib/core/formContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,GAAG,EAAE,KAAK,UAAU,EAAE,MAAM,KAAK,CAAA;AAC1E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAA;AAClC,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,WAAW,EACX,eAAe,EACf,cAAc,EACf,MAAM,UAAU,CAAA;AAEjB;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,GAAG,CAAC,cAAc,EAAE,CAAC,CAAA;IAC5B,MAAM,EAAE,OAAO,EAAE,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,UAAU;IAErC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAGtC,MAAM,EAAE,UAAU,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC,CAAA;IAC3C,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAC3C,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACzC,YAAY,EAAE,GAAG,CAAC,OAAO,CAAC,CAAA;IAC1B,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,CAAA;IACvB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAGxB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC,CAAA;IACpD,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IAC1C,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IAGzC,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAA;IAC1D,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAGzC,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,CAAA;CACjC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,SAAS,OAAO,EACvD,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,GAC/B,WAAW,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAgEnC"}

package/dist/core/useFieldArray.d.ts

@@ -0,0 +1,9 @@
+import { FormContext } from './formContext';
+import { FieldArray, Path } from '../types';
+/**
+ * Create field array management functions
+ */
+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/useFieldArray.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFieldArray.d.ts","sourceRoot":"","sources":["../../src/lib/core/useFieldArray.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,KAAK,EAAE,UAAU,EAAkB,IAAI,EAAE,MAAM,UAAU,CAAA;AAGhE;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAChD,GAAG,EAAE,WAAW,CAAC,UAAU,CAAC,EAC5B,QAAQ,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC;aAKlC,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,QAAQ,KAAK,KAAG,UAAU;EAyKzE"}

package/dist/core/useFieldRegistration.d.ts

@@ -0,0 +1,10 @@
+import { FormContext } from './formContext';
+import { RegisterOptions, RegisterReturn, Path } from '../types';
+/**
+ * Create field registration functions
+ */
+export declare function createFieldRegistration<FormValues>(ctx: FormContext<FormValues>, validate: (fieldPath?: string) => Promise<boolean>): {
+    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/useFieldRegistration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFieldRegistration.d.ts","sourceRoot":"","sources":["../../src/lib/core/useFieldRegistration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EAEd,IAAI,EACL,MAAM,UAAU,CAAA;AAGjB;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAChD,GAAG,EAAE,WAAW,CAAC,UAAU,CAAC,EAC5B,QAAQ,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC;eAKhC,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,QACxC,KAAK,oBACO,eAAe,KAChC,cAAc;iBA6LG,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,QAAQ,KAAK,KAAG,IAAI;EAcvE"}

package/dist/core/useValidation.d.ts

@@ -0,0 +1,8 @@
+import { FormContext } from './formContext';
+/**
+ * Create validation functions for form
+ */
+export declare function createValidation<FormValues>(ctx: FormContext<FormValues>): {
+    validate: (fieldPath?: string) => Promise<boolean>;
+};
+//# sourceMappingURL=useValidation.d.ts.map

package/dist/core/useValidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useValidation.d.ts","sourceRoot":"","sources":["../../src/lib/core/useValidation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAsEhD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,GAAG,EAAE,WAAW,CAAC,UAAU,CAAC;2BAInC,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;EAuD9D"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Vue Hook Form - TypeScript-first form library for Vue 3
+ *
+ * @example
+ * ```ts
+ * import { useForm } from './lib'
+ * import { z } from 'zod'
+ *
+ * const schema = z.object({
+ *   email: z.email(),
+ *   name: z.string().min(2)
+ * })
+ *
+ * const { register, handleSubmit, formState } = useForm({ schema })
+ * ```
+ */
+export { useForm } from './useForm';
+export { provideForm, useFormContext, FormContextKey } from './context';
+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/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AACvE,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAA;AAC3D,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAC/H,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAE1F,YAAY,EACV,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,EACd,SAAS,EACT,UAAU,EACV,WAAW,EACX,UAAU,EACV,eAAe,EACf,UAAU,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,IAAI,EACJ,SAAS,EACT,WAAW,EACX,eAAe,EACf,YAAY,EACZ,kBAAkB,GACnB,MAAM,SAAS,CAAA"}