@relax.js/core 1.0.3 → 1.0.4

package/docs/forms/form-api.md

@@ -1,94 +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+
+# 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

@@ -1,99 +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);
-    }
-});
-```
+# 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);
+    }
+});
+```