SEAM Form Components: Fields, Form Builder & Validation

SEAM’s form layer is built around a single composable pattern: a fields array drives Form, which delegates each entry to the correct low-level component (InputField, SelectField, or TextareaField). Every component returns an HTML string. Validation is handled separately by FormValidator, a class that binds to a rendered form element by ID and applies a declarative schema on each user interaction.

Form

Form accepts an id, a fields array, and an optional actions HTML string for submit/cancel buttons. It inspects each field’s type property and routes rendering to the appropriate sub-component.

import { Form } from '../../shared/components/ui/Form.js';

Supported field types

`type` value	Rendered as
`text`	`InputField` with `type="text"`
`email`	`InputField` with `type="email"`
`password`	`InputField` with `type="password"`
`number`	`InputField` with `type="number"`
`date`	`InputField` with `type="date"`
`select`	`SelectField`
`textarea`	`TextareaField`

Props

string

required

The id attribute written onto the <form> element. Used by FormValidator and FormData to reference the form.

fields

array

required

Array of field descriptor objects. Each object is spread directly into the corresponding sub-component, so any prop accepted by InputField, SelectField, or TextareaField can be placed here alongside the required type key.

{
  type: 'text' | 'email' | 'password' | 'number' | 'date' | 'select' | 'textarea',
  name: string,       // maps to name/id attributes
  label?: string,
  placeholder?: string,
  value?: string,
  required?: boolean,
  disabled?: boolean,
  options?: Array<{ value: string|number, label: string }>, // select only
  rows?: number,      // textarea only
  maxLength?: number, // textarea only
}

actions

string

default:"\"\""

Optional HTML string rendered inside a flex column container below the fields. Typically contains a submit button.

Real-world example — Add User form (from `users.page.js`)

The following fields array is passed directly to FormModal, which internally calls Form:

fields: [
    { name: 'name',            label: 'Nombre',               type: 'text',     placeholder: 'Juan Pérez',         required: true },
    { name: 'email',           label: 'Email',                type: 'email',    placeholder: 'juan@example.com',   required: true },
    { name: 'password',        label: 'Contraseña',           type: 'password', placeholder: '••••••••',           required: true },
    { name: 'confirmPassword', label: 'Confirmar Contraseña', type: 'password', placeholder: '••••••••',           required: true },
    { name: 'idRole',          label: 'Rol',                  type: 'select',   options: roleOptions,              required: true },
],

InputField

InputField renders a single <input> element with a label, success/error state icons, and an inline error message container. All visual states are driven entirely by props — no JavaScript is needed to switch states at render time.

import { InputField } from '../../shared/components/ui/InputField.js';

Props

type

string

default:"\"text\""

HTML input type. Any value accepted by the <input type> attribute is valid (text, email, password, number, date, etc.).

name

string

required

Written to both the id and name attributes of the <input>. Also used to derive the IDs of the error and icon elements ({name}-error, {name}-error-icon, {name}-success-icon).

label

string

default:"\"\""

Text shown in the <label> element above the input. If empty, no label is rendered.

placeholder

string

default:"\"\""

Placeholder text passed directly to the <input>.

value

string

default:"\"\""

Pre-filled value for edit forms.

required

boolean

default:"false"

Adds the HTML required attribute and renders a red asterisk next to the label.

disabled

boolean

default:"false"

Adds the HTML disabled attribute and applies muted styling.

withError

boolean

default:"false"

When true, reserves space for an error message paragraph (<p id="{name}-error">) and the icon slots. Set this whenever the field will be managed by FormValidator.

error

string

default:"\"\""

If non-empty, immediately renders the field in error state with the border tinted red and the error message visible.

success

boolean

default:"false"

If true (and no error is present), renders the field with an emerald border and a check icon.

Usage

import { InputField } from '../../shared/components/ui/InputField.js';

document.getElementById('root').innerHTML = InputField({
    type: 'email',
    name: 'email',
    label: 'Email',
    placeholder: 'juan@example.com',
    required: true,
    withError: true,
});

SelectField

SelectField renders a fully custom dropdown that replaces the native <select>. It stores the chosen value in a hidden <input> so FormData and FormValidator work without any special handling. Both single and multi-select modes are supported.

import { SelectField, initSelectFields } from '../../shared/components/ui/SelectField.js';

After injecting SelectField HTML into the DOM you must call initSelectFields() to activate the dropdown logic. FormModal and ComponentInitializer both do this automatically.

Props

name

string

required

Written to the hidden <input name> attribute and used to derive all element IDs.

label

string

default:"\"\""

Text shown above the trigger button.

options

array

required

Array of { value: string | number, label: string } objects that populate the dropdown list.

value

string | string[]

default:"\"\""

Pre-selected value(s). Pass a comma-separated string or an array when multiple is true.

placeholder

string

default:"\"Selecciona una opción\""

Text shown in the trigger button when nothing is selected.

multiple

boolean

default:"false"

Enables multi-select mode. Selected items are displayed as dismissible badges below the trigger. The hidden input stores values as a comma-separated string.

required

boolean

default:"false"

Adds required to the hidden input and renders a red asterisk next to the label.

disabled

boolean

default:"false"

Disables the trigger button.

withError

boolean

default:"false"

Reserves space for an inline error message. Required when FormValidator manages the field.

error

string

default:"\"\""

Immediately renders the field in error state.

className

string

default:"\"\""

Extra CSS classes added to the outermost wrapper <div>.

Global helpers

Two functions are exposed on window for programmatic error management:

window.setSelectError(selectId, 'Este campo es requerido');
// Highlights the trigger with a red border and shows the error message.

window.initSelectFields();
// Re-scans the DOM for [data-select-init] elements and binds their logic.

TextareaField

TextareaField renders a resizable <textarea> with label, inline validation, and an optional live character counter.

import { TextareaField } from '../../shared/components/ui/TextareaField.js';

Props

name

string

required

Written to both the id and name attributes of the <textarea>.

label

string

default:"\"\""

Text shown in the <label> element above the textarea.

placeholder

string

default:"\"\""

Placeholder text.

value

string

default:"\"\""

Pre-filled content for edit forms.

rows

number

default:"4"

Number of visible text rows.

required

boolean

default:"false"

Adds the HTML required attribute and a red asterisk.

disabled

boolean

default:"false"

Disables the textarea.

withError

boolean

default:"false"

Reserves the error message slot for FormValidator integration.

error

string

default:"\"\""

Immediately renders an error state.

maxLength

number | string

default:"\"\""

Adds the HTML maxlength attribute and automatically enables the character counter.

showCounter

boolean

default:"false"

Forces the character counter to appear even without a maxLength.

The character counter is updated by a single delegated input listener registered once on document. It looks for a [data-char-count-for="{name}"] element and updates its text on every keystroke.

FormValidator

FormValidator is a class that binds to a rendered <form> element and validates its fields against a declarative schema. It reacts to input and focusout events, writes inline error messages to the DOM, and can toggle a submit button’s disabled state automatically.

import { FormValidator } from '../../shared/utils/FormValidator.js';

Constructor

const validator = new FormValidator(formId, schema, options);

formId

string

required

The id attribute of the <form> element to bind to.

schema

object

required

A map of field names to rule objects. See Schema rules below.

options.buttonId

string

The id of a submit button. When provided, FormValidator keeps the button disabled until every field in the schema passes validation.

options.validateOnInput

boolean

default:"true"

Validate a field every time its value changes.

options.validateOnBlur

boolean

default:"true"

Validate a field when it loses focus.

options.errorIdSuffix

string

default:"\"-error\""

Suffix appended to a field’s name to locate its error <p> element in the DOM (e.g. email → email-error).

Methods

attach()

method

Binds event listeners to the form. Call this once after the form HTML has been injected into the DOM. Calling it again on the same instance is a no-op.

validate()

method

Imperatively validates all fields in the schema, writes error messages for any that fail, and returns true if the entire form is valid.

clearErrors()

method

Clears all inline error messages without validating.

Schema rules

Each field name maps to a rules object. Rules are evaluated in declaration order and validation stops at the first failure.

Rule	Parameter	Description
`required`	`true`	Field must be non-empty after trimming.
`minLength`	`number`	Trimmed length must be at least `n` characters.
`maxLength`	`number`	Trimmed length must be at most `n` characters.
`email`	`true`	Must match `/^[^\s@]+@[^\s@]+\.[^\s@]+$/`.
`password`	`true`	Min 8 chars, at least one uppercase, one lowercase, one digit.
`text`	`true`	Only letters, spaces, accents, and `ñ`/`Ñ`.
`match`	`"fieldName"`	Value must equal the value of the named sibling field (e.g. confirm-password).
`custom`	`(val, formData) => true \| string`	Arbitrary function; return `true` for valid or an error string.

Real-world example — `USER_SCHEMA` from `users.page.js`

const USER_SCHEMA = {
    name:            { required: true, text: true, minLength: 2 },
    email:           { required: true, email: true },
    password:        { required: true, password: true },
    confirmPassword: { required: true, password: true, match: 'password' },
};

And the edit variant, which uses a custom rule so that confirmPassword is only required when a new password has been entered:

const USER_EDIT_SCHEMA = {
    name:  { required: true, text: true, minLength: 2 },
    email: { required: true, email: true },
    password: { password: true },
    confirmPassword: {
        custom: (val, _, formData) => {
            const pwd = formData.get('password') ?? '';
            if (!pwd.trim()) return true;
            if (!val.trim()) return 'Confirma la nueva contraseña';
            return val === pwd || 'Los campos no coinciden';
        }
    },
};

Attaching the validator manually

import { FormValidator } from '../../shared/utils/FormValidator.js';

// After the form HTML is in the DOM:
const validator = new FormValidator('user-form', USER_SCHEMA, {
    buttonId: 'btn-submit',   // disabled until the form is valid
});
validator.attach();

FormModal calls new FormValidator(formId, schema, { buttonId: confirmBtnId }) and validator.attach() automatically inside a setTimeout(..., 50) so the DOM is ready. You only need to manage the validator yourself when building a form without FormModal.

Validators (primitives)

The three low-level validators used by FormValidator are also exported for direct use:

import { validators } from '../../shared/utils/Validators.js';

validators.validateEmail('user@example.com');   // true | false
validators.validatePassword('Secret1');         // true | false  (min 8, 1 upper, 1 lower, 1 digit)
validators.validateText('Juan Pérez');          // true | false  (letters + accents + spaces only)

ComponentInitializer

A thin utility that calls initSelectFields() after a delay, ensuring any SelectField elements that were just rendered into the DOM are properly activated.

import { initializeComponents } from '../../shared/utils/ComponentInitializer.js';

// After injecting HTML that contains one or more SelectField components:
initializeComponents();

Getting Started

Core Concepts

Modules

UI Components

Development

SEAM Form Components: Fields, Form Builder & Validation

Form

Supported field types

Props

Real-world example — Add User form (from `users.page.js`)

InputField

Props

Usage

SelectField

Props

Global helpers

TextareaField

Props

FormValidator

Constructor

Methods

Schema rules

Real-world example — `USER_SCHEMA` from `users.page.js`

Attaching the validator manually

Validators (primitives)

ComponentInitializer

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Modules

UI Components

Development

Documentation Index

​Form

​Supported field types

​Props

​Real-world example — Add User form (from users.page.js)

​InputField

​Props

​Usage

​SelectField

​Props

​Global helpers

​TextareaField

​Props

​FormValidator

​Constructor

​Methods

​Schema rules

​Real-world example — USER_SCHEMA from users.page.js

​Attaching the validator manually

​Validators (primitives)

​ComponentInitializer

Build docs developers (and LLMs) love

Form

Supported field types

Props

Real-world example — Add User form (from `users.page.js`)

InputField

Props

Usage

SelectField

Props

Global helpers

TextareaField

Props

FormValidator

Constructor

Methods

Schema rules

Real-world example — `USER_SCHEMA` from `users.page.js`

Attaching the validator manually

Validators (primitives)

ComponentInitializer