@coherent.js/forms 1.0.0-beta.3 → 1.0.0-beta.6

package/README.md

@@ -0,0 +1,304 @@
+# @coherent.js/forms
+
+Comprehensive forms handling and validation utilities for Coherent.js applications.
+
+## Installation
+
+```bash
+npm install @coherent.js/forms
+# or
+pnpm add @coherent.js/forms
+# or
+yarn add @coherent.js/forms
+```
+
+## Overview
+
+The `@coherent.js/forms` package provides powerful form handling capabilities including:
+
+- Form state management
+- Validation with built-in validators
+- Error handling and display
+- Form serialization and submission
+- Integration with Coherent.js components
+
+## Quick Start
+
+```javascript
+import { createForm } from '@coherent.js/forms';
+import { validators } from '@coherent.js/state';
+
+const contactForm = createForm({
+  fields: {
+    email: {
+      value: '',
+      validators: [validators.email('Please enter a valid email')]
+    },
+    message: {
+      value: '',
+      validators: [validators.minLength(10, 'Message must be at least 10 characters')]
+    }
+  }
+});
+
+function ContactForm() {
+  const handleSubmit = async (event) => {
+    event.preventDefault();
+    
+    if (contactForm.validate()) {
+      // Form is valid, submit data
+      await submitFormData(contactForm.values);
+      contactForm.reset();
+    }
+  };
+
+  return {
+    form: {
+      onsubmit: handleSubmit,
+      children: [
+        {
+          input: {
+            type: 'email',
+            value: contactForm.fields.email.value,
+            oninput: (e) => contactForm.setField('email', e.target.value),
+            className: contactForm.fields.email.error ? 'error' : ''
+          }
+        },
+        {
+          span: {
+            text: contactForm.fields.email.error || '',
+            className: 'error-message'
+          }
+        },
+        {
+          textarea: {
+            value: contactForm.fields.message.value,
+            oninput: (e) => contactForm.setField('message', e.target.value),
+            className: contactForm.fields.message.error ? 'error' : ''
+          }
+        },
+        {
+          span: {
+            text: contactForm.fields.message.error || '',
+            className: 'error-message'
+          }
+        },
+        {
+          button: {
+            type: 'submit',
+            text: 'Send Message',
+            disabled: contactForm.isSubmitting
+          }
+        }
+      ]
+    }
+  };
+}
+```
+
+## Features
+
+### Form State Management
+
+Automatically manage form state including values, errors, and submission status:
+
+```javascript
+const form = createForm({
+  fields: {
+    username: { value: '' },
+    password: { value: '' }
+  }
+});
+
+// Access form values
+console.log(form.values); // { username: '', password: '' }
+
+// Update field values
+form.setField('username', 'john_doe');
+
+// Check form validity
+console.log(form.isValid); // true/false
+
+// Check submission status
+console.log(form.isSubmitting); // true/false
+```
+
+### Validation
+
+Built-in validators with custom validation support:
+
+```javascript
+import { validators } from '@coherent.js/state';
+
+const form = createForm({
+  fields: {
+    email: {
+      value: '',
+      validators: [
+        validators.required('Email is required'),
+        validators.email('Please enter a valid email')
+      ]
+    },
+    age: {
+      value: '',
+      validators: [
+        validators.required('Age is required'),
+        validators.min(18, 'Must be at least 18 years old')
+      ]
+    }
+  }
+});
+
+// Custom validator
+const customValidator = (value) => {
+  if (value && value.length < 5) {
+    return 'Value must be at least 5 characters';
+  }
+  return null; // null means valid
+};
+
+const formWithCustomValidation = createForm({
+  fields: {
+    customField: {
+      value: '',
+      validators: [customValidator]
+    }
+  }
+});
+```
+
+### Async Validation
+
+Support for asynchronous validation (e.g., checking if username is available):
+
+```javascript
+const asyncValidator = async (value) => {
+  if (!value) return null;
+  
+  const response = await fetch(`/api/check-username/${value}`);
+  const exists = await response.json();
+  
+  return exists ? 'Username is already taken' : null;
+};
+
+const signupForm = createForm({
+  fields: {
+    username: {
+      value: '',
+      validators: [asyncValidator]
+    }
+  }
+});
+```
+
+## API Reference
+
+### createForm(options)
+
+Create a new form instance.
+
+**Parameters:**
+- `options.fields` - Object defining form fields and their initial state
+- `options.onSubmit` - Optional function to handle form submission
+
+**Returns:** Form instance with methods and properties
+
+### Form Instance Properties
+
+- `values` - Current form values
+- `fields` - Field state objects with value, error, touched, etc.
+- `isValid` - Boolean indicating if form is valid
+- `isSubmitting` - Boolean indicating if form is being submitted
+- `errors` - Object containing field errors
+
+### Form Instance Methods
+
+- `setField(name, value)` - Update a field's value
+- `validate()` - Validate all fields, returns boolean
+- `reset()` - Reset form to initial state
+- `submit()` - Trigger form submission
+
+## Integration with @coherent.js/state
+
+The forms package integrates seamlessly with the reactive state system:
+
+```javascript
+import { createForm } from '@coherent.js/forms';
+import { observable } from '@coherent.js/state';
+
+// Create reactive form
+const form = createForm({
+  fields: {
+    search: { value: '' }
+  }
+});
+
+// Create observable for search results
+const searchResults = observable([]);
+
+// Update search results when form changes
+form.fields.search.watch((newValue) => {
+  if (newValue.length > 2) {
+    performSearch(newValue).then(results => {
+      searchResults.value = results;
+    });
+  }
+});
+```
+
+## Examples
+
+### Login Form
+
+```javascript
+import { createForm } from '@coherent.js/forms';
+import { validators } from '@coherent.js/state';
+
+const loginForm = createForm({
+  fields: {
+    email: {
+      value: '',
+      validators: [
+        validators.required('Email is required'),
+        validators.email('Please enter a valid email')
+      ]
+    },
+    password: {
+      value: '',
+      validators: [
+        validators.required('Password is required'),
+        validators.minLength(8, 'Password must be at least 8 characters')
+      ]
+    }
+  },
+  async onSubmit(values) {
+    try {
+      const response = await fetch('/api/login', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(values)
+      });
+      
+      if (response.ok) {
+        // Handle successful login
+        window.location.href = '/dashboard';
+      } else {
+        // Handle login error
+        throw new Error('Invalid credentials');
+      }
+    } catch (error) {
+      loginForm.setError('login', error.message);
+    }
+  }
+});
+```
+
+## Related Packages
+
+- [@coherent.js/state](../state/README.md) - Reactive state management
+- [@coherent.js/core](../core/README.md) - Core framework
+- [@coherent.js/client](../client/README.md) - Client-side utilities
+
+## License
+
+MIT

package/dist/index.js

@@ -1664,7 +1664,7 @@ var enhancedForm = createForm();
 
 // src/advanced-validation.js
 import { ReactiveState, observable, computed } from "@coherent.js/state/src/reactive-state.js";
-import { globalErrorHandler } from "@coherent.js/core/src/utils/_error-handler.js";
+import { globalErrorHandler } from "@coherent.js/core/src/utils/error-handler.js";
 var validationRules = {
   required: (value, params = true) => {
     if (!params) return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coherent.js/forms",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.6",
   "description": "SSR + Hydration form system for Coherent.js applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,8 +22,8 @@
   "author": "Coherent.js Team",
   "license": "MIT",
   "peerDependencies": {
-    "@coherent.js/core": "1.0.0-beta.3",
-    "@coherent.js/state": "1.0.0-beta.3"
+    "@coherent.js/core": "1.0.0-beta.6",
+    "@coherent.js/state": "1.0.0-beta.6"
   },
   "repository": {
     "type": "git",
@@ -38,6 +38,7 @@
     "README.md",
     "types/"
   ],
+  "sideEffects": false,
   "scripts": {
     "build": "node build.mjs",
     "clean": "rm -rf dist"

package/types/index.d.ts

@@ -3,132 +3,455 @@
  * @module @coherent.js/forms
  */
 
-// ===== Form Builder Types =====
+import type { CoherentNode, CoherentElement, StrictCoherentElement } from '@coherent.js/core';
 
-export interface FormField {
-  type: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'date' | 'time' | 'datetime-local' | 'checkbox' | 'radio' | 'select' | 'textarea';
+// ============================================================================
+// Form Field Types
+// ============================================================================
+
+/**
+ * Available form field input types
+ */
+export type FormFieldType =
+  | 'text'
+  | 'email'
+  | 'password'
+  | 'number'
+  | 'tel'
+  | 'url'
+  | 'date'
+  | 'time'
+  | 'datetime-local'
+  | 'checkbox'
+  | 'radio'
+  | 'select'
+  | 'textarea'
+  | 'file'
+  | 'hidden'
+  | 'color'
+  | 'range'
+  | 'search'
+  | 'month'
+  | 'week';
+
+/**
+ * Option for select and radio fields
+ */
+export interface SelectOption {
+  value: string | number;
+  label: string;
+  disabled?: boolean;
+}
+
+/**
+ * Typed form field definition with generic value type
+ * @template T - The type of the field value
+ */
+export interface FormField<T = unknown> {
+  /** Field input type */
+  type: FormFieldType;
+  /** Field name (used as form data key) */
   name: string;
+  /** Human-readable label */
   label?: string;
+  /** Placeholder text */
   placeholder?: string;
+  /** Whether field is required */
   required?: boolean;
-  value?: any;
-  options?: Array<{ value: string; label: string }>;
+  /** Whether field is disabled */
+  disabled?: boolean;
+  /** Whether field is readonly */
+  readonly?: boolean;
+  /** Default/initial value */
+  defaultValue?: T;
+  /** Current value */
+  value?: T;
+  /** Options for select/radio fields */
+  options?: SelectOption[];
+  /** Validation rules */
   validators?: Validator[];
-  attributes?: Record<string, any>;
+  /** Field-specific validation configuration */
+  validation?: FieldValidation<T>;
+  /** Additional HTML attributes */
+  attributes?: Record<string, unknown>;
+  /** Transform function to convert raw input to typed value */
+  transform?: (value: unknown) => T;
 }
 
+/**
+ * Field validation configuration with typed value
+ * @template T - The type of the field value
+ */
+export interface FieldValidation<T = unknown> {
+  /** Required validation with optional custom message */
+  required?: boolean | string;
+  /** Minimum length for string values */
+  minLength?: number | { value: number; message: string };
+  /** Maximum length for string values */
+  maxLength?: number | { value: number; message: string };
+  /** Minimum value for number values */
+  min?: number | { value: number; message: string };
+  /** Maximum value for number values */
+  max?: number | { value: number; message: string };
+  /** Regular expression pattern validation */
+  pattern?: RegExp | { value: RegExp; message: string };
+  /** Custom validation function */
+  custom?: (value: T, formData: Record<string, unknown>) => boolean | string | Promise<boolean | string>;
+  /** Validate on change (real-time) */
+  validateOnChange?: boolean;
+  /** Validate on blur */
+  validateOnBlur?: boolean;
+  /** Debounce time in milliseconds for validation */
+  debounce?: number;
+}
+
+// ============================================================================
+// Form Builder Types
+// ============================================================================
+
+/**
+ * Form configuration options
+ */
 export interface FormConfig {
-  fields: FormField[];
+  /** Form fields */
+  fields?: FormField[];
+  /** Form action URL */
   action?: string;
+  /** Form submission method */
   method?: 'get' | 'post';
+  /** Form CSS class name */
   className?: string;
+  /** Submit button text */
   submitText?: string;
+  /** Form submit handler */
   onSubmit?: (data: FormData) => void | Promise<void>;
+  /** Form encoding type */
+  enctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain';
+  /** Whether to disable browser validation */
+  novalidate?: boolean;
+  /** Form ID */
+  id?: string;
 }
 
-export class FormBuilder {
-  constructor(config: FormConfig);
-  addField(field: FormField): this;
-  removeField(name: string): this;
-  build(): object;
-  render(): object;
+/**
+ * Typed form builder with generic form data shape
+ * @template T - The shape of the form data
+ */
+export interface FormBuilder<T extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * Add a field to the form
+   * @template K - The key in the form data
+   */
+  addField<K extends keyof T>(name: K, field: Omit<FormField<T[K]>, 'name'>): FormBuilder<T>;
+
+  /**
+   * Remove a field from the form
+   */
+  removeField(name: keyof T): FormBuilder<T>;
+
+  /**
+   * Set the form action URL
+   */
+  setAction(action: string): FormBuilder<T>;
+
+  /**
+   * Set the form submission method
+   */
+  setMethod(method: 'get' | 'post'): FormBuilder<T>;
+
+  /**
+   * Set the form submit handler
+   */
+  onSubmit(handler: (data: T) => void | Promise<void>): FormBuilder<T>;
+
+  /**
+   * Build the form as a CoherentNode
+   */
+  build(): CoherentNode;
+
+  /**
+   * Render the form (alias for build)
+   */
+  render(): CoherentNode;
+
+  /**
+   * Validate form data
+   */
+  validate(data: unknown): { valid: boolean; errors: Record<keyof T, string[]> };
+
+  /**
+   * Get current field definitions
+   */
+  getFields(): FormField[];
 }
 
-export function createFormBuilder(config: FormConfig): FormBuilder;
-export function buildForm(config: FormConfig): object;
+/**
+ * Create a typed form builder
+ * @template T - The shape of the form data
+ */
+export function createFormBuilder<T extends Record<string, unknown> = Record<string, unknown>>(
+  config?: FormConfig
+): FormBuilder<T>;
+
+/**
+ * Build a form from configuration
+ */
+export function buildForm(config: FormConfig): CoherentNode;
+
+/**
+ * Render a single form field
+ */
+export function renderField<T = unknown>(field: FormField<T>): CoherentNode;
+
+/**
+ * Validate a single field value
+ * @returns Error message or null if valid
+ */
+export function validateField<T>(field: FormField<T>, value: unknown): string | null;
+
+// ============================================================================
+// Form Builder Class
+// ============================================================================
+
+/**
+ * Form builder class implementation
+ */
+export class FormBuilder<T extends Record<string, unknown> = Record<string, unknown>> {
+  constructor(config?: FormConfig);
+  addField<K extends keyof T>(name: K, field: Omit<FormField<T[K]>, 'name'>): this;
+  removeField(name: keyof T): this;
+  setAction(action: string): this;
+  setMethod(method: 'get' | 'post'): this;
+  onSubmit(handler: (data: T) => void | Promise<void>): this;
+  build(): CoherentNode;
+  render(): CoherentNode;
+  validate(data: unknown): { valid: boolean; errors: Record<keyof T, string[]> };
+  getFields(): FormField[];
+}
 
-// ===== Form Hydration Types =====
+// ============================================================================
+// Form Hydration Types
+// ============================================================================
 
+/**
+ * Options for hydrating a form on the client
+ */
 export interface HydrationOptions {
+  /** Enable validation */
   validation?: boolean;
+  /** Enable real-time validation as user types */
   realTimeValidation?: boolean;
+  /** Form submit handler */
   onSubmit?: (event: Event, data: FormData) => void | Promise<void>;
+  /** Validation error handler */
   onValidate?: (errors: ValidationErrors) => void;
+  /** Prevent default form submission */
+  preventSubmit?: boolean;
 }
 
+/**
+ * Hydrated form interface for client-side interaction
+ */
 export interface HydratedForm {
+  /** The form DOM element */
   element: HTMLFormElement;
+  /** Validate all form fields */
   validate(): ValidationResult;
+  /** Reset form to initial values */
   reset(): void;
+  /** Get current form data */
   getData(): FormData;
-  setData(data: Record<string, any>): void;
+  /** Get form data as object */
+  getValues<T = Record<string, unknown>>(): T;
+  /** Set form field values */
+  setData(data: Record<string, unknown>): void;
+  /** Set a single field value */
+  setValue(name: string, value: unknown): void;
+  /** Destroy hydration and clean up event listeners */
   destroy(): void;
+  /** Check if form is valid */
+  isValid(): boolean;
+  /** Get validation errors */
+  getErrors(): ValidationErrors;
 }
 
-export function hydrateForm(formElement: HTMLFormElement | string, options?: HydrationOptions): HydratedForm;
+/**
+ * Hydrate a form element for client-side interactivity
+ */
+export function hydrateForm(
+  formElement: HTMLFormElement | string,
+  options?: HydrationOptions
+): HydratedForm;
 
-// ===== Validation Types =====
+// ============================================================================
+// Validation Types
+// ============================================================================
 
+/**
+ * Validation result
+ */
 export interface ValidationResult {
+  /** Whether all fields are valid */
   valid: boolean;
+  /** Validation errors by field name */
   errors: ValidationErrors;
 }
 
+/**
+ * Validation errors mapped by field name
+ */
 export interface ValidationErrors {
   [fieldName: string]: string[];
 }
 
+/**
+ * Validator function type
+ */
 export interface Validator {
-  (value: any): boolean | string | Promise<boolean | string>;
+  (value: unknown): boolean | string | Promise<boolean | string>;
 }
 
+/**
+ * Form validator class
+ */
 export class FormValidator {
   constructor(rules: Record<string, Validator[]>);
-  validate(data: Record<string, any>): ValidationResult;
-  validateAsync(data: Record<string, any>): Promise<ValidationResult>;
+  /** Synchronous validation */
+  validate(data: Record<string, unknown>): ValidationResult;
+  /** Asynchronous validation */
+  validateAsync(data: Record<string, unknown>): Promise<ValidationResult>;
+  /** Add a validation rule */
   addRule(field: string, validator: Validator): void;
+  /** Remove a validation rule */
   removeRule(field: string, validator: Validator): void;
+  /** Clear all rules for a field */
+  clearRules(field: string): void;
 }
 
+/**
+ * Create a form validator
+ */
 export function createValidator(rules: Record<string, Validator[]>): FormValidator;
-export function validate(data: Record<string, any>, rules: Record<string, Validator[]>): ValidationResult;
 
-// ===== Built-in Validators =====
+/**
+ * Validate data against rules
+ */
+export function validate(
+  data: Record<string, unknown>,
+  rules: Record<string, Validator[]>
+): ValidationResult;
+
+// ============================================================================
+// Built-in Validators
+// ============================================================================
 
+/**
+ * Built-in validator functions
+ */
 export const validators: {
+  /** Require a value to be present */
   required(message?: string): Validator;
+  /** Validate email format */
   email(message?: string): Validator;
+  /** Minimum string length */
   minLength(length: number, message?: string): Validator;
+  /** Maximum string length */
   maxLength(length: number, message?: string): Validator;
+  /** Minimum numeric value */
   min(value: number, message?: string): Validator;
+  /** Maximum numeric value */
   max(value: number, message?: string): Validator;
+  /** Pattern matching */
   pattern(regex: RegExp, message?: string): Validator;
+  /** Match another field's value */
   matches(field: string, message?: string): Validator;
+  /** Validate URL format */
   url(message?: string): Validator;
+  /** Validate as number */
   number(message?: string): Validator;
+  /** Validate as integer */
   integer(message?: string): Validator;
+  /** Validate as positive number */
   positive(message?: string): Validator;
+  /** Validate as negative number */
   negative(message?: string): Validator;
+  /** Validate date format */
   date(message?: string): Validator;
-  custom(fn: (value: any) => boolean | string, message?: string): Validator;
-  async(fn: (value: any) => Promise<boolean | string>): Validator;
+  /** Custom validation function */
+  custom(fn: (value: unknown) => boolean | string, message?: string): Validator;
+  /** Async validation function */
+  async(fn: (value: unknown) => Promise<boolean | string>): Validator;
 };
 
+/** Alias for validators */
 export const formValidators: typeof validators;
 
-// ===== Advanced Validation =====
+// ============================================================================
+// Advanced Validation
+// ============================================================================
 
+/**
+ * Validation rule configuration
+ */
 export interface ValidationRule {
+  /** The validator function */
   validator: Validator;
+  /** Custom error message */
   message?: string;
+  /** Whether this is an async validator */
   async?: boolean;
 }
 
-export interface FieldValidation {
-  rules: ValidationRule[];
-  validateOnChange?: boolean;
-  validateOnBlur?: boolean;
-  debounce?: number;
-}
+/**
+ * Create an async validator
+ */
+export function createAsyncValidator(
+  fn: (value: unknown) => Promise<boolean | string>
+): Validator;
 
-export function createAsyncValidator(fn: (value: any) => Promise<boolean | string>): Validator;
+/**
+ * Combine multiple validators into one
+ */
 export function combineValidators(...validators: Validator[]): Validator;
-export function conditionalValidator(condition: (data: Record<string, any>) => boolean, validator: Validator): Validator;
 
-// ===== Deprecated SPA-only Functions (for backward compatibility) =====
+/**
+ * Create a conditional validator
+ */
+export function conditionalValidator(
+  condition: (data: Record<string, unknown>) => boolean,
+  validator: Validator
+): Validator;
+
+// ============================================================================
+// Form Utilities
+// ============================================================================
+
+/**
+ * Parse FormData to typed object
+ */
+export function parseFormData<T extends Record<string, unknown>>(formData: FormData): T;
+
+/**
+ * Serialize object to FormData
+ */
+export function toFormData(data: Record<string, unknown>): FormData;
+
+/**
+ * Create a form group (fieldset)
+ */
+export function createFieldGroup(
+  legend: string,
+  fields: FormField[]
+): CoherentNode;
+
+// ============================================================================
+// Deprecated Functions (Backward Compatibility)
+// ============================================================================
 
 /** @deprecated Use createFormBuilder() on server + hydrateForm() on client */
-export function createForm(config: FormConfig): object;
+export function createForm(config: FormConfig): CoherentNode;
 
 /** @deprecated Use validators with hydrateForm() instead */
-export function enhancedForm(config: FormConfig & { validation?: Record<string, Validator[]> }): object;
+export function enhancedForm(
+  config: FormConfig & { validation?: Record<string, Validator[]> }
+): CoherentNode;