forms.md

Form Utilities

A TypeScript library for form validation, data mapping, and form manipulation with strong typing support.

Overview

The form utilities provide:

• Building a Form Page - The end-to-end shape: template, load, validate, save. Start here
• Validation - FormValidator takes over the form's submit event, and adds HTML5 validation, error summaries, and custom rules
• Reading & Writing - Read and write form data with automatic type conversion
• Form API - How RelaxJS supports the Form-Associated Custom Elements standard
• Patterns - Common patterns for multi-step forms, file uploads, and state management
• Creating Form Components - 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

const form = document.querySelector('form');
const validator = new FormValidator(form, {
    useSummary: true,
    autoValidate: true
});

Reading Form Data

const form = document.querySelector('form');
const data = readData(form);
// Returns typed object with automatic conversion

Writing Form Data

const form = document.querySelector('form');
const userData = {
    name: 'John',
    email: 'john@example.com',
    preferences: {
        notifications: true
    }
};
setFormData(form, userData);

Mapping to Class Instance

class UserDTO {
    name: string = '';
    email: string = '';
    age: number = 0;
}

const form = document.querySelector('form');
const user = mapFormToClass(form, new UserDTO());

Complete Example

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);
    }
});