@teamnovu/kit-vue-forms 0.0.1

package/PLAN.md

@@ -0,0 +1,209 @@
+# Vue Forms Library - MVP Plan
+
+## Overview
+
+A type-safe Vue 3 form library with immutable state management, validation, and subform support. The library uses a direct form instance pattern (no provide/inject) to maintain full type safety throughout the component tree.
+
+## Core Architecture
+
+### Direct Form Instance Pattern
+- Forms are created with `createForm<T>()` and passed directly to components
+- Full TypeScript type safety maintained throughout the component tree
+- No context loss from provide/inject patterns
+
+### Subform Extraction Pattern
+```typescript
+// Reusable components work with subforms
+const addressSubform = form.getSubform('address')
+// addressSubform has type FormInstance<Address>
+
+<AddressForm :form="addressSubform" />
+```
+
+This allows components to be reusable across different parent forms while maintaining type safety.
+
+## API Design
+
+### Form Creation
+```typescript
+const form = createForm<UserData>({
+  initialData: { name: '', email: '', address: { street: '', city: '' } },
+  validationSchema: userSchema,
+  strategy: 'onTouch'
+})
+```
+
+### Form Instance Interface
+```typescript
+interface FormInstance<T> {
+  // Data access
+  getValue<K extends keyof T>(path: K): T[K]
+  setValue<K extends keyof T>(path: K, value: T[K]): void
+  
+  // Field management
+  getField<K extends keyof T>(path: K): FieldInstance<T[K]>
+  
+  // Subform extraction
+  getSubform<K extends keyof T>(path: K): FormInstance<T[K]>
+  
+  // State queries
+  isDirty(): boolean
+  isTouched(): boolean
+  isValid(): boolean
+  
+  // Operations
+  validate(): Promise<ValidationResult>
+  reset(): void
+  submit(): Promise<void>
+  
+  // Error access
+  getErrors(path?: keyof T): ErrorMessage[]
+  hasErrors(path?: keyof T): boolean
+}
+```
+
+### Field Instance Interface
+```typescript
+interface FieldInstance<T> {
+  // Reactive value with getter/setter
+  value: Ref<T>
+  
+  // State
+  touched: Ref<boolean>
+  dirty: Ref<boolean>
+  errors: Ref<ErrorMessage[]>
+  
+  // Handlers
+  onBlur(): void
+  onFocus(): void
+  
+  // Field-specific validation
+  validate(): Promise<ValidationResult>
+}
+```
+
+## Directory Structure
+
+```
+src/
+├── types/
+│   ├── form.ts              # Form instance types
+│   ├── field.ts             # Field instance types
+│   ├── validation.ts        # Validation types
+│   └── index.ts
+├── core/
+│   ├── form-instance.ts     # Form instance implementation
+│   ├── field-instance.ts    # Field instance implementation
+│   ├── subform-instance.ts  # Subform implementation
+│   └── validation-engine.ts # Validation logic
+├── factories/
+│   └── create-form.ts       # Main form factory
+├── utils/
+│   ├── immutable.ts         # Immutable helpers
+│   ├── path.ts              # Object path utilities
+│   └── type-helpers.ts      # TypeScript utility types
+└── index.ts                 # Main exports
+```
+
+## Core Features
+
+### 1. Immutable State Management
+- Store initial data as immutable
+- Working copy is immutable from outside (readonly)
+- Computed getter/setter on working copy
+- Full clone on creation
+
+### 2. Form State Tracking
+- **Touched**: Field has been interacted with at least once
+- **Dirty**: Computed property checking if value ≠ initial state
+- State propagation from subforms to parent forms
+
+### 3. Validation System
+- **Strategies**: `onTouch`, `onFormOpen`, `none`, `preSubmit`
+- **Zod Integration**: Primary validation with Zod schemas
+- **Backend Validation**: API errors merged with Zod errors
+- **Error Bag Structure**:
+  ```typescript
+  {
+    general: ErrorMessage[],
+    propertyErrors: Record<string, ErrorMessage[]>
+  }
+  ```
+
+### 4. Subform Support
+- Extract subforms with `getSubform(path)`
+- Type-safe subform instances
+- Automatic value propagation from subforms to parent
+- Reusable components across different parent forms
+
+### 5. Array Functionality (Future)
+- `pushValue()`, `removeValue()`, `getKeys()`
+- Similar to vee-validate's field array API
+
+## MVP Implementation Order
+
+### Phase 1: Core Infrastructure
+1. **Project Setup**
+   - Package.json with proper exports
+   - TypeScript configuration
+   - Vite build setup
+   - Basic documentation structure
+
+2. **Type System**
+   - Core interfaces and types
+   - Validation types
+   - Error handling types
+
+3. **Basic Form Instance**
+   - Form creation factory
+   - Basic field management
+   - Immutable state handling
+
+### Phase 2: Essential Features
+1. **Field Management**
+   - Field instance implementation
+   - Touch and dirty state tracking
+   - Basic event handlers
+
+2. **Validation Engine**
+   - Zod integration
+   - Error collection and formatting
+   - Basic validation strategies
+
+3. **Subform System**
+   - Subform extraction
+   - Type-safe subform instances
+   - Value propagation
+
+### Phase 3: Polish & Testing
+1. **Edge Cases**
+   - Error handling
+   - Reset functionality
+   - Validation edge cases
+
+2. **Documentation**
+   - API documentation
+   - Usage examples
+   - Migration guides
+
+3. **Testing**
+   - Unit tests
+   - Integration tests
+   - Type safety tests
+
+## Key Benefits
+
+- **Type Safety**: Full TypeScript support with no type loss
+- **Immutable State**: Predictable state management
+- **Reusable Components**: Subforms enable component reuse
+- **Validation Flexibility**: Multiple validation strategies
+- **Performance**: Reactive updates only where needed
+- **Developer Experience**: Excellent IDE support and debugging
+
+## Notes
+
+- No provide/inject pattern to avoid type information loss
+- Direct form instance passing maintains type safety
+- Subform extraction enables component reusability
+- Validation strategies can be overridden per field
+- Backend validation seamlessly integrates with Zod

package/dist/composables/useField.d.ts

@@ -0,0 +1,12 @@
+import { MaybeRef, MaybeRefOrGetter } from 'vue';
+import { FormField } from '../types/form';
+import { ValidationErrors } from '../types/validation';
+export interface UseFieldOptions<T, K extends string> {
+    value?: MaybeRef<T>;
+    initialValue?: MaybeRefOrGetter<Readonly<T>>;
+    type?: MaybeRef<string>;
+    required?: MaybeRef<boolean>;
+    path: K;
+    errors?: MaybeRef<ValidationErrors>;
+}
+export declare function useField<T, K extends string>(options: UseFieldOptions<T, K>): FormField<T, K>;

package/dist/composables/useFieldRegistry.d.ts

@@ -0,0 +1,15 @@
+import { FormDataDefault, FormField, FormState } from '../types/form';
+import { Paths, PickProps } from '../types/util';
+import { UseFieldOptions } from './useField';
+type FieldRegistryCache<T> = Record<Paths<T>, FormField<any, string>>;
+export type ResolvedFormField<T, K extends Paths<T>> = FormField<PickProps<T, K>, K>;
+export type DefineFieldOptions<F, K extends string> = Pick<UseFieldOptions<F, K>, 'path' | 'type' | 'required'>;
+export declare function useFieldRegistry<T extends FormDataDefault>(formState: FormState<T>): {
+    fields: FieldRegistryCache<T>;
+    getField: <K extends Paths<T>>(path: K) => ResolvedFormField<T, K> | undefined;
+    getFields: () => ResolvedFormField<T, Paths<T>>[];
+    registerField: <K extends Paths<T>>(field: ResolvedFormField<T, K>) => void;
+    defineField: <K extends Paths<T>>(options: DefineFieldOptions<PickProps<T, K>, K>) => FormField<PickProps<any, K>, K>;
+};
+export type FieldRegistry<T extends FormDataDefault> = ReturnType<typeof useFieldRegistry<T>>;
+export {};

package/dist/composables/useForm.d.ts

@@ -0,0 +1,10 @@
+import { MaybeRef, MaybeRefOrGetter } from 'vue';
+import { Form, FormDataDefault } from '../types/form';
+import { ValidationStrategy } from '../types/validation';
+import { ValidationOptions } from './useValidation';
+export interface UseFormOptions<T extends FormDataDefault> extends ValidationOptions<T> {
+    initialData: MaybeRefOrGetter<T>;
+    validationStrategy?: MaybeRef<ValidationStrategy>;
+    keepValuesOnUnmount?: MaybeRef<boolean>;
+}
+export declare function useForm<T extends FormDataDefault>(options: UseFormOptions<T>): Form<T>;

package/dist/composables/useFormState.d.ts

@@ -0,0 +1,7 @@
+import { FormDataDefault, FormState } from '../types/form';
+import { FieldRegistry } from './useFieldRegistry';
+import { ComputedRef } from 'vue';
+export declare function useFormState<T extends FormDataDefault>(formState: FormState<T>, formFieldRegistry: FieldRegistry<T>): {
+    isDirty: ComputedRef<boolean>;
+    isTouched: ComputedRef<boolean>;
+};

package/dist/composables/useSubform.d.ts

@@ -0,0 +1,5 @@
+import { Form, FormDataDefault } from '../types/form';
+import { EntityPaths, PickEntity } from '../types/util';
+export interface SubformOptions<_T extends FormDataDefault> {
+}
+export declare function createSubformInterface<T extends FormDataDefault, K extends EntityPaths<T>>(mainForm: Form<T>, path: K, _options?: SubformOptions<PickEntity<T, K>>): Form<PickEntity<T, K>>;

package/dist/composables/useValidation.d.ts

@@ -0,0 +1,30 @@
+import { MaybeRef, Ref, ComputedRef } from 'vue';
+import { default as z } from 'zod';
+import { FormDataDefault } from '../types/form';
+import { ErrorBag, ValidationFunction, ValidationResult, Validator, ValidationErrors } from '../types/validation';
+export interface ValidatorOptions<T> {
+    schema?: MaybeRef<z.ZodType>;
+    validateFn?: MaybeRef<ValidationFunction<T>>;
+}
+export interface ValidationOptions<T> extends ValidatorOptions<T> {
+    errors?: MaybeRef<ErrorBag>;
+}
+export declare const SuccessValidationResult: ValidationResult;
+export declare function createValidator<T extends FormDataDefault>(options: ValidatorOptions<T>): Ref<Validator<T> | undefined>;
+export declare function useValidation<T extends FormDataDefault>(formState: {
+    formData: T;
+}, options: ValidationOptions<T>): {
+    validateForm: () => Promise<ValidationResult>;
+    defineValidator: (options: ValidatorOptions<T> | Ref<Validator<T>>) => Ref<Validator<T> | undefined, Validator<T> | undefined>;
+    isValid: ComputedRef<boolean>;
+    validators: Ref<Ref<Validator<T> | undefined, Validator<T> | undefined>[], Ref<Validator<T> | undefined, Validator<T> | undefined>[]>;
+    isValidated: Ref<boolean, boolean>;
+    errors: Ref<{
+        general: string[] | undefined;
+        propertyErrors: Record<string, ValidationErrors>;
+    }, {
+        general: string[] | undefined;
+        propertyErrors: Record<string, ValidationErrors>;
+    }>;
+};
+export type ValidationState<T extends FormDataDefault> = ReturnType<typeof useValidation<T>>;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { useForm } from './composables/useForm';
+export type { UseFormOptions } from './composables/useForm';
+export { useField } from './composables/useField';
+export type { UseFieldOptions } from './composables/useField';
+export type { ValidationStrategy, ValidationErrorMessage as ErrorMessage, ValidationResult, ErrorBag } from './types/validation';
+export type { DeepPartial, FormData } from './utils/type-helpers';