@relax.js/core 1.0.0

package/docs/forms/reading-writing.md

@@ -0,0 +1,365 @@
+# Reading & Writing Form Data
+
+Functions for reading and writing form data with automatic type conversion.
+
+## mapFormToClass
+
+Maps form field values to a class instance's properties with type conversion. Provides full type safety by populating an existing typed object.
+
+```typescript
+import { mapFormToClass } from 'relaxjs/forms';
+
+class UserDTO {
+    name: string = '';
+    email: string = '';
+    age: number = 0;
+    newsletter: boolean = false;
+}
+
+const form = document.querySelector('form');
+const user = mapFormToClass(form, new UserDTO());
+console.log(user.name, user.age, user.newsletter);
+```
+
+### Options
+
+```typescript
+// Options object (inline, not a named interface)
+{
+    throwOnMissingProperty?: boolean;  // Throw if form field has no matching property
+    throwOnMissingField?: boolean;     // Throw if class property has no matching field
+}
+```
+
+### Strict Validation Mode
+
+Catch mismatches between form fields and your data model:
+
+```typescript
+const user = mapFormToClass(form, new UserDTO(), {
+    throwOnMissingProperty: true,  // Catch typos in form field names
+    throwOnMissingField: true      // Ensure all DTO fields are in form
+});
+```
+
+### Type Conversion
+
+Automatic conversion based on input types:
+
+| Input Type | Converted To |
+|------------|--------------|
+| `checkbox` | `boolean` |
+| `number` | `number` |
+| `date` | `Date` |
+
+```typescript
+class ProductDTO {
+    name: string = '';
+    price: number = 0;
+    inStock: boolean = false;
+    releaseDate: Date | null = null;
+}
+
+const product = mapFormToClass(form, new ProductDTO());
+// product.price is number, product.inStock is boolean
+```
+
+## readData
+
+Reads all form data into a plain object with automatic type conversion. Use when you don't need strict typing.
+
+```typescript
+import { readData } from 'relaxjs/forms';
+
+const form = document.querySelector('form');
+const data = readData(form);
+```
+
+### Type Conversion
+
+Type conversion is determined by:
+1. `data-type` attribute if present (`number`, `boolean`, `string`, `Date`)
+2. Input type (`checkbox`, `number`, `date`, etc.)
+3. Falls back to string
+
+```html
+<form>
+    <input name="username" value="john" />
+    <input name="age" type="number" value="25" />
+    <input name="active" type="checkbox" checked />
+    <input name="salary" data-type="number" value="50000" />
+    <select name="colors" multiple>
+        <option value="red" selected>Red</option>
+        <option value="blue" selected>Blue</option>
+    </select>
+</form>
+```
+
+```typescript
+const data = readData(form);
+// Returns: {
+//     username: 'john',
+//     age: 25,
+//     active: true,
+//     salary: 50000,
+//     colors: ['red', 'blue']
+// }
+```
+
+### Checkbox Handling
+
+Unchecked checkboxes are included as `false` in the result. Checked checkboxes with no explicit `value` attribute (which submit as `'on'` in FormData) are correctly converted to `true`.
+
+```html
+<input name="active" type="checkbox" checked />
+<input name="terms" type="checkbox" />
+```
+
+```typescript
+const data = readData(form);
+// Returns: { active: true, terms: false }
+```
+
+### Custom Form Components
+
+Works with form-associated custom elements:
+
+```html
+<form>
+    <r-input name="email" value="test@example.com"></r-input>
+    <r-checkbox name="terms" checked></r-checkbox>
+</form>
+```
+
+```typescript
+const data = readData(form);
+// Returns: { email: 'test@example.com', terms: true }
+```
+
+## setFormData
+
+Populates form fields from a data object using the `name` attribute.
+
+```typescript
+import { setFormData } from 'relaxjs/forms';
+
+const form = document.querySelector('form');
+const data = { name: 'John', email: 'john@example.com' };
+setFormData(form, data);
+```
+
+### Nested Objects (Dot Notation)
+
+```html
+<form>
+    <input name="user.name" />
+    <input name="user.contact.email" />
+</form>
+```
+
+```typescript
+const data = {
+    user: {
+        name: 'John',
+        contact: {
+            email: 'john@example.com'
+        }
+    }
+};
+setFormData(form, data);
+```
+
+### Date and DateTime
+
+`setFormData` formats `Date` objects to the correct string format for each input type:
+
+```html
+<input type="date" name="birthday" />
+<input type="datetime-local" name="meeting" />
+```
+
+```typescript
+setFormData(form, {
+    birthday: new Date('2000-01-15'),     // Sets "2000-01-15"
+    meeting: new Date('2024-06-15T14:30') // Sets "2024-06-15T14:30"
+});
+```
+
+### Select Multiple
+
+Array values are set directly on `<select multiple>` elements:
+
+```html
+<select name="colors" multiple>
+    <option value="red">Red</option>
+    <option value="green">Green</option>
+    <option value="blue">Blue</option>
+</select>
+```
+
+```typescript
+setFormData(form, { colors: ['red', 'blue'] });
+// Selects "red" and "blue", deselects "green"
+```
+
+### Simple Arrays ([] Notation)
+
+For checkboxes, multi-select, and text inputs:
+
+```html
+<form>
+    <input name="hobbies[]" type="checkbox" value="Reading" />
+    <input name="hobbies[]" type="checkbox" value="Cycling" />
+    <input name="hobbies[]" type="checkbox" value="Cooking" />
+</form>
+```
+
+```typescript
+const data = {
+    hobbies: ['Reading', 'Cooking']
+};
+setFormData(form, data);
+// Checks "Reading" and "Cooking" checkboxes
+```
+
+### Array of Objects (Indexed Notation)
+
+```html
+<form>
+    <input name="users[0].name" />
+    <input name="users[0].email" />
+    <input name="users[1].name" />
+    <input name="users[1].email" />
+</form>
+```
+
+```typescript
+const data = {
+    users: [
+        { name: 'John', email: 'john@example.com' },
+        { name: 'Jane', email: 'jane@example.com' }
+    ]
+};
+setFormData(form, data);
+```
+
+### Complex Data Structures
+
+```html
+<form id="product-form">
+    <input name="product.name" placeholder="Product Name">
+    <input name="product.price" type="number" placeholder="Price">
+
+    <input name="categories[]" type="checkbox" value="electronics">
+    <input name="categories[]" type="checkbox" value="gadgets">
+
+    <input name="variants[0].size" placeholder="Size">
+    <input name="variants[0].color" placeholder="Color">
+    <input name="variants[1].size" placeholder="Size">
+    <input name="variants[1].color" placeholder="Color">
+
+    <input name="supplier.company" placeholder="Company">
+    <input name="supplier.contact.email" placeholder="Email">
+</form>
+```
+
+```typescript
+const productData = {
+    product: {
+        name: 'Wireless Headphones',
+        price: 99.99
+    },
+    categories: ['electronics', 'gadgets'],
+    variants: [
+        { size: 'M', color: 'black' },
+        { size: 'L', color: 'white' }
+    ],
+    supplier: {
+        company: 'TechCorp',
+        contact: {
+            email: 'orders@techcorp.com'
+        }
+    }
+};
+
+setFormData(form, productData);
+
+// Later, extract the data
+const extractedData = readData(form);
+// Result matches the original structure
+```
+
+## Type Converters
+
+### Built-in Converters
+
+| Converter | Input | Output |
+|-----------|-------|--------|
+| `BooleanConverter` | `'true'`, `'on'`, `'1'`, any positive number string -> `true`; `'false'`, `'off'`, `'0'` -> `false` | `boolean` |
+| `NumberConverter` | Numeric string | `number` |
+| `DateConverter` | ISO or locale-formatted date string | `Date` |
+
+#### Locale-Aware Date Parsing
+
+`DateConverter` detects the current locale and parses dates in the local format:
+
+| Locale | Format | Example |
+|--------|--------|---------|
+| `en` (US) | `MM/DD/YYYY` | `01/15/2024` |
+| `sv` (Swedish) | `YYYY-MM-DD` | `2024-01-15` |
+| `de` (German) | `DD.MM.YYYY` | `15.01.2024` |
+
+ISO format (`2024-01-15`) is always accepted regardless of locale.
+
+### Custom Type via `data-type` Attribute
+
+Use the `data-type` attribute to override conversion for any field:
+
+```html
+<input name="salary" data-type="number" value="50000" />
+<input name="active" data-type="boolean" value="true" />
+<input name="birthday" data-type="Date" value="2000-01-15" />
+```
+
+```typescript
+const data = readData(form);
+console.log(data.salary);   // number: 50000
+console.log(data.active);   // boolean: true
+console.log(data.birthday); // Date object
+```
+
+Supported `data-type` values: `number`, `boolean`, `string`, `Date`.
+
+### Date and Time Handling
+
+```html
+<input name="startDate" type="date">
+<input name="startTime" type="time">
+<input name="duration" type="time" step="900"> <!-- 15 min steps -->
+```
+
+```typescript
+// Custom handling for combining date and time
+document.querySelector('[name="startTime"]').getData = function() {
+    const dateInput = form.querySelector('[name="startDate"]') as HTMLInputElement;
+    const timeInput = this as HTMLInputElement;
+
+    if (dateInput.value && timeInput.value) {
+        return new Date(`${dateInput.value}T${timeInput.value}`);
+    }
+    return null;
+};
+```
+
+### Input Type Conversion Table
+
+| Input Type | Converted To |
+|------------|--------------|
+| `checkbox` | `boolean` |
+| `number` | `number` |
+| `date` | `Date` |
+| `datetime-local` | `Date` |
+| `month` | `Date` (first of month) |
+| `week` | `{ year, week }` |
+| `time` | `{ hours, minutes, seconds }` |
+| Default | `string` |

package/docs/forms/validation.md

@@ -0,0 +1,351 @@
+# Form Validation
+
+The `FormValidator` class provides form validation with HTML5 integration, error summaries, and custom validation support.
+
+## Basic Usage
+
+```typescript
+import { FormValidator } from 'relaxjs/forms';
+
+const form = document.querySelector('form');
+const validator = new FormValidator(form, {
+    submitCallback: () => saveData()
+});
+```
+
+## Configuration Options
+
+```typescript
+interface ValidatorOptions {
+    autoValidate?: boolean;           // Validate on every input event
+    useSummary?: boolean;             // Show errors in summary element
+    customChecks?: (form: HTMLFormElement) => void;  // Custom validation
+    preventDefault?: boolean;          // Always prevent form submission
+    preventDefaultOnFailed?: boolean;  // Prevent submission on failure (default: true)
+    submitCallback?: () => void;       // Called when form is valid
+}
+```
+
+## Auto-Validation
+
+Enable real-time validation as users type:
+
+```typescript
+const validator = new FormValidator(form, {
+    autoValidate: true,
+    useSummary: true
+});
+```
+
+## Error Summary Display
+
+Instead of browser tooltips, show errors in a summary element:
+
+```typescript
+const validator = new FormValidator(form, {
+    useSummary: true,
+    submitCallback: () => handleSubmit()
+});
+```
+
+The error summary is automatically created and prepended to the form with:
+- `role="alert"` for accessibility
+- `aria-live="assertive"` for screen readers
+- `class="error-summary"` for styling
+
+## Custom Validation
+
+Add business logic validation beyond HTML5 constraints:
+
+```typescript
+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');
+        }
+
+        const startDate = new Date(form.querySelector('[name="startDate"]').value);
+        const endDate = new Date(form.querySelector('[name="endDate"]').value);
+
+        if (endDate <= startDate) {
+            validator.addErrorToSummary('End Date', 'Must be after start date');
+        }
+    },
+    submitCallback: () => saveData()
+});
+```
+
+## Manual Validation
+
+Trigger validation programmatically:
+
+```typescript
+if (validator.validateForm()) {
+    // Form is valid
+    proceedToNextStep();
+}
+```
+
+## Error Summary Methods
+
+### addErrorToSummary
+
+Add a single error to the summary:
+
+```typescript
+validator.addErrorToSummary('Email', 'This email is already registered');
+```
+
+### displayErrorSummary
+
+Display multiple errors at once:
+
+```typescript
+validator.displayErrorSummary([
+    'Name: This field is required',
+    'Email: Invalid email format',
+    'Age: Must be 18 or older'
+]);
+```
+
+### clearErrorSummary
+
+Remove all errors from the summary:
+
+```typescript
+validator.clearErrorSummary();
+```
+
+## Finding Forms
+
+Use `FindForm` to locate a form relative to a custom element:
+
+```typescript
+class MyComponent extends HTMLElement {
+    connectedCallback() {
+        const form = FormValidator.FindForm(this);
+        new FormValidator(form);
+    }
+}
+```
+
+`FindForm` searches:
+1. Parent element (if it's a form)
+2. Direct children
+
+## Built-in Validators
+
+Declarative validation rules applied via the `data-validate` attribute. Multiple rules are space-separated.
+
+```html
+<input name="age" type="number" data-validate="required range(0-120)" />
+```
+
+Validation messages use the i18n system. Load the `r-validation` namespace for localized messages:
+
+```typescript
+await loadNamespace('r-validation');
+```
+
+Translation keys in the `r-validation` namespace:
+
+| Key | Message (EN) | Message (SV) |
+|-----|-------------|-------------|
+| `required` | `This field is required.` | `Detta fält är obligatoriskt.` |
+| `range` | `Number must be between {min} and {max}, was {actual}.` | `Talet måste vara mellan {min} och {max}, var {actual}.` |
+| `digits` | `Please enter only digits.` | `Ange endast siffror.` |
+
+### required
+
+Validates that the field has a non-empty value (whitespace-only fails).
+
+```html
+<input name="username" data-validate="required" />
+```
+
+### range(min-max)
+
+Validates that a numeric value falls within a range (inclusive). Supports negative numbers and decimals. Empty values are skipped (use with `required` if the field must be filled).
+
+```html
+<input name="age" type="number" data-validate="range(0-120)" />
+<input name="temperature" type="number" data-validate="range(-40-50)" />
+<input name="ratio" type="number" data-validate="range(0.0-1.0)" />
+```
+
+### digits
+
+Validates that the value contains only digits (0-9).
+
+```html
+<input name="zipCode" data-validate="digits" />
+```
+
+## Custom Validators
+
+Register your own validators using the `@RegisterValidator` decorator. The class must implement a `validate(value, context)` method.
+
+```typescript
+import { RegisterValidator, ValidationContext } from 'relaxjs/forms';
+
+@RegisterValidator('email')
+class EmailValidation {
+    validate(value: string, context: ValidationContext) {
+        if (value && !value.includes('@')) {
+            context.addError('Invalid email address');
+        }
+    }
+}
+```
+
+Restrict a validator to specific input types with the second parameter:
+
+```typescript
+@RegisterValidator('positive', ['number'])
+class PositiveValidation {
+    validate(value: string, context: ValidationContext) {
+        if (value && parseFloat(value) < 0) {
+            context.addError('Value must be positive');
+        }
+    }
+}
+```
+
+### ValidationContext
+
+The context object passed to validators:
+
+```typescript
+interface ValidationContext {
+    inputType: string;        // The HTML input type
+    dataType?: string;        // The data-type attribute value
+    addError(message: string): void;  // Report a validation error
+}
+```
+
+### Validator Registry
+
+Look up registered validators programmatically:
+
+```typescript
+import { getValidator } from 'relaxjs/forms';
+
+const entry = getValidator('required');
+// entry.validator is the class constructor
+// entry.validInputTypes lists the input types this validator applies to
+```
+
+## File Upload Validation
+
+```typescript
+class FileUploadForm {
+    private maxFileSize = 5 * 1024 * 1024; // 5MB
+    private allowedTypes = ['image/jpeg', 'image/png', 'application/pdf'];
+
+    constructor(form: HTMLFormElement) {
+        const validator = new FormValidator(form, {
+            useSummary: true,
+            customChecks: (form) => this.validateFiles(form, validator),
+            submitCallback: () => this.handleSubmit()
+        });
+    }
+
+    validateFiles(form: HTMLFormElement, validator: FormValidator) {
+        const fileInputs = form.querySelectorAll('input[type="file"]');
+
+        fileInputs.forEach(input => {
+            const files = (input as HTMLInputElement).files;
+            if (!files) return;
+
+            Array.from(files).forEach(file => {
+                if (file.size > this.maxFileSize) {
+                    validator.addErrorToSummary(
+                        input.name,
+                        `File "${file.name}" is too large (max 5MB)`
+                    );
+                }
+
+                if (!this.allowedTypes.includes(file.type)) {
+                    validator.addErrorToSummary(
+                        input.name,
+                        `File "${file.name}" has invalid type`
+                    );
+                }
+            });
+        });
+    }
+
+    handleSubmit() {
+        const formData = new FormData(form);
+        // Upload files...
+    }
+}
+```
+
+## Robust Error Handling
+
+```typescript
+class RobustFormHandler {
+    private validator: FormValidator;
+
+    constructor(private form: HTMLFormElement) {
+        this.validator = new FormValidator(form, {
+            useSummary: true,
+            customChecks: (form) => this.comprehensiveValidation(form),
+            submitCallback: () => this.handleSubmissionWithRetry()
+        });
+    }
+
+    comprehensiveValidation(form: HTMLFormElement) {
+        try {
+            this.validateRequiredFields(form);
+            this.validateDataFormats(form);
+            this.validateBusinessRules(form);
+        } catch (error) {
+            console.error('Validation error:', error);
+            this.validator.addErrorToSummary('System', 'Validation failed. Please try again.');
+        }
+    }
+
+    validateDataFormats(form: HTMLFormElement) {
+        const emails = form.querySelectorAll('input[type="email"]');
+        emails.forEach(input => {
+            if (input.value && !this.isValidEmail(input.value)) {
+                this.validator.addErrorToSummary(input.name, 'Invalid email format');
+            }
+        });
+
+        const phones = form.querySelectorAll('input[data-type="phone"]');
+        phones.forEach(input => {
+            if (input.value && !this.isValidPhone(input.value)) {
+                this.validator.addErrorToSummary(input.name, 'Invalid phone number');
+            }
+        });
+    }
+
+    async handleSubmissionWithRetry() {
+        const maxRetries = 3;
+        let attempt = 0;
+
+        while (attempt < maxRetries) {
+            try {
+                const data = readData(this.form);
+                await this.submitToAPI(data);
+                this.showSuccess();
+                return;
+            } catch (error) {
+                attempt++;
+                if (attempt >= maxRetries) {
+                    this.validator.addErrorToSummary('Submission', 'Failed to submit after multiple attempts');
+                } else {
+                    await this.delay(1000 * attempt);
+                }
+            }
+        }
+    }
+}
+```