@relax.js/core 1.0.0

package/docs/forms/form-api.md

@@ -0,0 +1,94 @@
+# Form-Associated Custom Elements API
+
+The [Form-Associated Custom Elements](https://html.spec.whatwg.org/multipage/custom-elements.html#form-associated-custom-elements) standard lets web components participate in HTML forms just like native `<input>`, `<select>`, and `<textarea>` elements. RelaxJS form utilities fully support this API. Custom elements work transparently with `readData()`, `setFormData()`, `mapFormToClass()`, and `FormValidator`.
+
+## How the Standard Works
+
+A custom element becomes form-associated by declaring `static formAssociated = true` and using `ElementInternals`:
+
+```typescript
+class MyInput extends HTMLElement {
+    static formAssociated = true;
+    private internals: ElementInternals;
+
+    constructor() {
+        super();
+        this.internals = this.attachInternals();
+    }
+}
+```
+
+This gives the element:
+
+- Inclusion in `form.elements`: the browser tracks it like a native input
+- Participation in `FormData`: submitted values via `internals.setFormValue()`
+- Native validation: constraint checking via `internals.setValidity()`
+- Form lifecycle callbacks: `formResetCallback()`, `formDisabledCallback()`, etc.
+
+## How RelaxJS Supports It
+
+All form utilities use duck-typing rather than `instanceof` checks. This means they work with any element that exposes the right properties, whether it's a native `<input>` or a custom `<r-input>`.
+
+### Property Detection
+
+RelaxJS reads element properties via attribute and property checks:
+
+| Property | How it's detected |
+|----------|-------------------|
+| `type` | Property or `getAttribute('type')` |
+| `value` | `'value' in element` |
+| `checked` | Property (boolean) or attribute (`""`, `"true"`, `"checked"`) |
+| `disabled` | Property (boolean) or attribute (`""`, `"true"`, `"disabled"`) |
+| `multiple` | Property (boolean) or attribute (`""`, `"true"`, `"multiple"`) |
+| `selectedOptions` | `'selectedOptions' in element` |
+
+### readData()
+
+Uses `FormData` to read values, which automatically includes form-associated custom elements. Unchecked checkboxes (including custom ones with `type="checkbox"` and a `checked` property) are included as `false`.
+
+```typescript
+const data = readData(form);
+// Custom elements with name/value are included just like native inputs
+```
+
+### setFormData()
+
+Sets values by querying `[name]` attributes and using duck-typed property access:
+
+```typescript
+setFormData(form, { email: 'user@example.com', terms: true });
+// Works on both <input name="email"> and <r-input name="email">
+```
+
+For custom checkbox-like elements, `setFormData` checks `type === 'checkbox'` and sets the `checked` property. For custom select-like elements, it checks for `selectedOptions` and `multiple`.
+
+### mapFormToClass()
+
+Queries `input, select, textarea` and uses duck-typed value reading. Disabled elements (detected via attribute, not `instanceof`) are skipped, matching `FormData` behavior.
+
+### FormValidator
+
+Validates any element returned by `form.querySelectorAll('input,textarea,select')` that implements `checkValidity()`. Custom elements using `ElementInternals.setValidity()` integrate automatically.
+
+## Required Properties for Custom Elements
+
+For full compatibility with RelaxJS form utilities, custom elements should expose:
+
+| Property | Purpose |
+|----------|---------|
+| `name` | Field name for data mapping |
+| `value` | Current value (string) |
+| `disabled` | Whether the field is excluded from form data |
+| `type` | Element type (e.g., `'checkbox'`, `'text'`) for converter selection |
+| `checked` | Boolean state for checkbox/radio-like elements |
+
+See [Creating Form Components](creating-form-components.md) for complete implementation examples.
+
+## Browser Support
+
+Form-associated custom elements are supported in all modern browsers:
+
+- Chrome 77+
+- Edge 79+
+- Firefox 93+
+- Safari 16.4+

package/docs/forms/forms.md

@@ -0,0 +1,99 @@
+# Form Utilities
+
+A TypeScript library for form validation, data mapping, and form manipulation with strong typing support.
+
+## Overview
+
+The form utilities provide:
+
+- **[Validation](validation.md)** - Form validation with HTML5 integration, error summaries, and custom validators
+- **[Reading & Writing](reading-writing.md)** - Read and write form data with automatic type conversion
+- **[Form API](form-api.md)** - How RelaxJS supports the Form-Associated Custom Elements standard
+- **[Patterns](patterns.md)** - Common patterns for multi-step forms, file uploads, and state management
+- **[Creating Form Components](creating-form-components.md)** - Guide for building custom form-associated components
+
+## Form Components Support
+
+All form utilities fully support **form-associated custom elements** (the HTML Form API). Custom web components created with `ElementInternals` and `formAssociated = true` integrate seamlessly with:
+
+- `setFormData()` - Populates custom form components like standard HTML inputs
+- `readData()` - Extracts values from custom form components
+- `mapFormToClass()` - Maps custom form component values to class properties
+- `FormValidator` - Validates custom form components with native and custom validation
+
+## Quick Start
+
+### Basic Form Validation
+
+```typescript
+const form = document.querySelector('form');
+const validator = new FormValidator(form, {
+    useSummary: true,
+    autoValidate: true
+});
+```
+
+### Reading Form Data
+
+```typescript
+const form = document.querySelector('form');
+const data = readData(form);
+// Returns typed object with automatic conversion
+```
+
+### Writing Form Data
+
+```typescript
+const form = document.querySelector('form');
+const userData = {
+    name: 'John',
+    email: 'john@example.com',
+    preferences: {
+        notifications: true
+    }
+};
+setFormData(form, userData);
+```
+
+### Mapping to Class Instance
+
+```typescript
+class UserDTO {
+    name: string = '';
+    email: string = '';
+    age: number = 0;
+}
+
+const form = document.querySelector('form');
+const user = mapFormToClass(form, new UserDTO());
+```
+
+## Complete Example
+
+```typescript
+class UserRegistration {
+    name: string = '';
+    email: string = '';
+    age: number = 0;
+    isSubscribed: boolean = false;
+}
+
+const form = document.querySelector('#registration-form');
+const user = new UserRegistration();
+
+const validator = new FormValidator(form, {
+    useSummary: true,
+    customChecks: (form) => {
+        const password = form.querySelector('[name="password"]') as HTMLInputElement;
+        const confirm = form.querySelector('[name="confirmPassword"]') as HTMLInputElement;
+
+        if (password.value !== confirm.value) {
+            validator.addErrorToSummary('Password Confirmation', 'Passwords do not match');
+        }
+    },
+    submitCallback: () => {
+        mapFormToClass(form, user);
+        console.log('User data:', user);
+    }
+});
+```

package/docs/forms/patterns.md

@@ -0,0 +1,311 @@
+# Form Patterns
+
+Common patterns for building forms with RelaxJS utilities.
+
+## Multi-Step Forms
+
+```typescript
+class MultiStepForm {
+    private currentStep = 1;
+    private validators: FormValidator[] = [];
+
+    constructor() {
+        this.setupStepValidation();
+    }
+
+    setupStepValidation() {
+        document.querySelectorAll('.form-step').forEach((step, index) => {
+            const validator = new FormValidator(step as HTMLFormElement, {
+                useSummary: true,
+                preventDefault: true,
+                submitCallback: () => this.nextStep()
+            });
+            this.validators.push(validator);
+        });
+    }
+
+    nextStep() {
+        if (this.validators[this.currentStep - 1].validateForm()) {
+            this.currentStep++;
+            this.showStep(this.currentStep);
+        }
+    }
+
+    showStep(step: number) {
+        document.querySelectorAll('.form-step').forEach((el, index) => {
+            (el as HTMLElement).style.display = index + 1 === step ? 'block' : 'none';
+        });
+    }
+}
+```
+
+## Form State Management
+
+Track changes and auto-save drafts:
+
+```typescript
+class FormStateManager {
+    private formData: Record<string, unknown> = {};
+    private isDirty = false;
+
+    constructor(private form: HTMLFormElement) {
+        this.captureInitialState();
+        this.setupChangeTracking();
+    }
+
+    captureInitialState() {
+        this.formData = readData(this.form);
+    }
+
+    setupChangeTracking() {
+        this.form.addEventListener('input', () => {
+            this.isDirty = true;
+            this.updateSaveButton();
+        });
+
+        // Auto-save every 30 seconds if dirty
+        setInterval(() => {
+            if (this.isDirty) {
+                this.autoSave();
+            }
+        }, 30000);
+    }
+
+    autoSave() {
+        const currentData = readData(this.form);
+        localStorage.setItem('form-draft', JSON.stringify(currentData));
+        this.isDirty = false;
+        this.showSaveIndicator('Auto-saved');
+    }
+
+    restoreDraft() {
+        const draft = localStorage.getItem('form-draft');
+        if (draft) {
+            const data = JSON.parse(draft);
+            setFormData(this.form, data);
+        }
+    }
+
+    hasChanges(): boolean {
+        const current = readData(this.form);
+        return JSON.stringify(current) !== JSON.stringify(this.formData);
+    }
+}
+```
+
+## Web Component Integration
+
+```typescript
+class UserProfileEditor extends HTMLElement {
+    private form: HTMLFormElement;
+    private validator: FormValidator;
+    private user: UserProfile;
+
+    connectedCallback() {
+        this.innerHTML = `
+            <form>
+                <input name="displayName" placeholder="Display Name" required>
+                <input name="email" type="email" placeholder="Email" required>
+                <input name="preferences.notifications" type="checkbox"> Notifications
+                <input name="preferences.theme" type="radio" value="light"> Light
+                <input name="preferences.theme" type="radio" value="dark"> Dark
+            </form>
+        `;
+
+        this.form = FormValidator.FindForm(this);
+        this.user = new UserProfile();
+
+        this.validator = new FormValidator(this.form, {
+            useSummary: true,
+            autoValidate: true,
+            submitCallback: () => this.saveProfile()
+        });
+
+        this.loadUserData();
+    }
+
+    async loadUserData() {
+        const userData = await fetchUserProfile();
+        setFormData(this.form, userData);
+    }
+
+    saveProfile() {
+        mapFormToClass(this.form, this.user);
+
+        if (this.user.displayName.length < 2) {
+            this.validator.addErrorToSummary('Display Name', 'Must be at least 2 characters');
+            return;
+        }
+
+        updateUserProfile(this.user);
+    }
+}
+
+customElements.define('user-profile-editor', UserProfileEditor);
+```
+
+## Dynamic Survey Form
+
+Handle forms with dynamic question types:
+
+```typescript
+class SurveyResponse {
+    userId: number = 0;
+    responses: Record<string, string | number | boolean> = {};
+    completedAt: Date = new Date();
+}
+
+const surveyForm = document.querySelector('#survey-form') as HTMLFormElement;
+const response = new SurveyResponse();
+
+// Custom data extraction for complex question types
+document.querySelectorAll('[data-question-type="rating"]').forEach(element => {
+    (element as any).getData = function() {
+        const stars = this.querySelectorAll('.star.selected');
+        return stars.length;
+    };
+});
+
+const validator = new FormValidator(surveyForm, {
+    autoValidate: true,
+    customChecks: (form) => {
+        const required = form.querySelectorAll('[data-required]');
+        required.forEach(field => {
+            const input = field as HTMLInputElement;
+            if (!input.value && input.type !== 'checkbox') {
+                const questionText = field.getAttribute('data-question');
+                validator.addErrorToSummary(questionText, 'This question is required');
+            }
+        });
+    },
+    submitCallback: () => {
+        response.responses = readData(surveyForm);
+        response.completedAt = new Date();
+        submitSurvey(response);
+    }
+});
+```
+
+## Unsaved Changes Warning
+
+Warn users before leaving with unsaved changes:
+
+```typescript
+class UnsavedChangesGuard {
+    private initialData: string;
+
+    constructor(private form: HTMLFormElement) {
+        this.initialData = JSON.stringify(readData(form));
+        this.setupWarning();
+    }
+
+    setupWarning() {
+        window.addEventListener('beforeunload', (e) => {
+            if (this.hasUnsavedChanges()) {
+                e.preventDefault();
+                e.returnValue = '';
+            }
+        });
+    }
+
+    hasUnsavedChanges(): boolean {
+        return JSON.stringify(readData(this.form)) !== this.initialData;
+    }
+
+    markAsSaved() {
+        this.initialData = JSON.stringify(readData(this.form));
+    }
+}
+```
+
+## Form Reset with Confirmation
+
+```typescript
+class ResettableForm {
+    private initialData: Record<string, unknown>;
+
+    constructor(private form: HTMLFormElement) {
+        this.initialData = readData(form);
+        this.setupResetButton();
+    }
+
+    setupResetButton() {
+        const resetBtn = this.form.querySelector('[type="reset"]');
+        resetBtn?.addEventListener('click', (e) => {
+            e.preventDefault();
+            if (confirm('Are you sure you want to reset the form?')) {
+                setFormData(this.form, this.initialData);
+            }
+        });
+    }
+}
+```
+
+## Conditional Field Visibility
+
+```typescript
+class ConditionalForm {
+    constructor(private form: HTMLFormElement) {
+        this.setupConditionalFields();
+    }
+
+    setupConditionalFields() {
+        this.form.querySelectorAll('[data-show-when]').forEach(field => {
+            const condition = field.getAttribute('data-show-when');
+            const [fieldName, expectedValue] = condition.split('=');
+
+            const triggerField = this.form.querySelector(`[name="${fieldName}"]`);
+            triggerField?.addEventListener('change', () => {
+                const currentValue = (triggerField as HTMLInputElement).value;
+                (field as HTMLElement).style.display =
+                    currentValue === expectedValue ? 'block' : 'none';
+            });
+        });
+    }
+}
+```
+
+Usage:
+
+```html
+<form>
+    <select name="contactMethod">
+        <option value="email">Email</option>
+        <option value="phone">Phone</option>
+    </select>
+
+    <input name="email" data-show-when="contactMethod=email" placeholder="Email">
+    <input name="phone" data-show-when="contactMethod=phone" placeholder="Phone">
+</form>
+```
+
+## Form Data Comparison
+
+```typescript
+class FormComparison {
+    static getDiff(
+        original: Record<string, unknown>,
+        current: Record<string, unknown>
+    ): Record<string, { old: unknown; new: unknown }> {
+        const diff: Record<string, { old: unknown; new: unknown }> = {};
+
+        for (const key in current) {
+            if (JSON.stringify(original[key]) !== JSON.stringify(current[key])) {
+                diff[key] = {
+                    old: original[key],
+                    new: current[key]
+                };
+            }
+        }
+
+        return diff;
+    }
+}
+
+// Usage
+const original = readData(form);
+// ... user makes changes ...
+const current = readData(form);
+const changes = FormComparison.getDiff(original, current);
+console.log('Changed fields:', changes);
+```