Field-Assist

TL;DR: Effortlessly map HTML forms to JSON objects and vice versa, or generate fully functional forms dynamically from metadata.

field-assist provides a zero-dependency, extremely lightweight toolset to:

1. Read nested JSON objects from raw HTML forms (collectValues).
2. Populate HTML forms back from complex JSON data (populateFields).
3. Generate completely structured and interactive HTML forms or Multi-Step Wizards on-the-fly (AutoForm, Wizard).

Installation

npm install field-assist

1. Manual Form Management

If you prefer building your own HTML, use collectValues and populateFields to bind data efficiently without manually querying .value from dozens of DOM elements.

HTML Setup

Use the ref attribute to define your JSON structure. You can use dot-notation for nested objects.

<form id="user-profile">
  <!-- Basic Input -->
  <label>First Name</label>
  <input ref="user.firstName" type="text" />

  <!-- Numbers with validation -->
  <label>Age</label>
  <input ref="user.age" type="number" validator="(v) => v > 0 && v < 120" />

  <!-- Checkboxes -->
  <label><input type="checkbox" ref="newsletter" /> Subscribe</label>

  <!-- Multi-select via Checkboxes -->
  <label><input type="checkbox" ref="tags" value="javascript" /> JS</label>
  <label><input type="checkbox" ref="tags" value="typescript" /> TS</label>

  <span class="error-message">Invalid Value</span>
</form>

Collecting & Populating Data

import { collectValues, populateFields } from 'field-assist';

const container = document.getElementById('user-profile');

// --- Populating ---
const initialData = {
    user: { firstName: 'John', age: 30 },
    newsletter: true,
    tags: ['javascript']
};
// Instantly maps the data into the form inputs!
populateFields(container, initialData);


// --- Collecting ---
// Automatically groups inputs into a nested object based on the 'ref' attribute.
const data = collectValues(container);

/*
data = {
  user: { firstName: 'John', age: 30 },
  newsletter: true,
  tags: ['javascript']
}
*/

Error Handling

If a field fails validation (e.g., standard HTML validity or custom validator attribute), collectValues populates an _errors key on the returned object. populateFields will then apply .is-invalid to the input and display .error-message if present in the DOM.

2. AutoForm & Wizard

You can generate complete forms from JavaScript configuration. The library guesses input types based on your default data (e.g., boolean -> checkbox, Date -> date picker, string over 40 chars -> textarea).

Basic AutoForm with In-Group Extra Text

Grouping fields provides logical separation in your UI. You can use the groups property to define titles and "in-group extra text" for instructions or sub-titles!

import { AutoForm } from 'field-assist';

const metaData = {
    'user.name': { label: 'Full Name', group: 'personal' },
    'user.dob': { label: 'Date of Birth', group: 'personal', componentType: 'date' },
    'account.email': { label: 'Email Address', group: 'account' },
    'account.theme': { 
        label: 'App Theme', 
        group: 'account', 
        componentType: 'radio', 
        options: ['Light', 'Dark'] 
    }
};

const autoForm = new AutoForm(metaData);

// Define your groups with titles and extra descriptive text
autoForm.groups = {
    personal: { 
        label: 'User Identity', 
        text: 'Please enter your real identity information for verification.' // In-group extra text
    },
    account: { 
        label: 'App Settings', 
        text: 'Configure your login and preferences here.' 
    }
};

const container = document.getElementById('form-container');
// Renders the generated form into the container
autoForm.render({}, container);

Wizard Mode (Multi-Step Form)

Change AutoForm to Wizard to make each group its own "step" in a multi-page form.

import { Wizard } from 'field-assist';

const wizard = new Wizard(metaData); // Uses the same metadata!
wizard.groups = autoForm.groups;

wizard.render({}, container);

// Navigate through steps programmatically
wizard.next();
wizard.prev();
wizard.goTo('account'); // Or use indices: wizard.goTo(1)

wizard.onPageChange = (step) => console.log('Current Step:', step.newIndex);
wizard.onDone = (data) => console.log('Finished!', data);

🎨 Comprehensive CSS Example

Because AutoForm and Wizard generate standard HTML elements with specific class names, you have full control over the appearance.

Copy and customize this starter CSS snippet. It covers the AutoForm layout, Group Titles, In-Group Extra Text, Validation Errors, and Input styling!

/* Container for the generated form */
.autoform {
    max-width: 600px;
    font-family: system-ui, sans-serif;
    color: #1e293b;
}

/* --- Group Structures --- */
.autoform .field-group {
    background: #f8fafc;
    border: 1px solid #cbd5e1;
    border-radius: 8px;
    padding: 1.5rem;
    margin-bottom: 1.5rem;
}

/* Group Title (.group-label) */
.autoform .group-label {
    font-size: 1.1rem;
    font-weight: 700;
    color: #0f172a;
    margin-bottom: 0.25rem;
    text-transform: capitalize;
}

/* In-Group Extra Text (.group-text) */
.autoform .group-text {
    font-size: 0.85rem;
    color: #64748b;
    margin-top: 0;
    margin-bottom: 1.25rem;
    font-style: italic;
}

/* --- Field Layouts --- */
.autoform .field-group > div, 
.autoform > div:not(.field-group) {
    margin-bottom: 1rem;
    display: flex;
    flex-direction: column;
}

/* Labels for individual inputs */
.autoform label {
    font-weight: 600;
    font-size: 0.85rem;
    margin-bottom: 0.4rem;
    color: #334155;
}

/* Standard Inputs */
.autoform input:not([type="radio"]):not([type="checkbox"]),
.autoform select,
.autoform textarea {
    padding: 0.5rem 0.75rem;
    border: 1px solid #cbd5e1;
    border-radius: 4px;
    font-size: 0.95rem;
    background: #ffffff;
    transition: border-color 0.2s, box-shadow 0.2s;
}

.autoform input:focus,
.autoform select:focus,
.autoform textarea:focus {
    outline: none;
    border-color: #3b82f6;
    box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
}

/* Radio and Checkbox Layouts */
.autoform .radio-button-set, 
.autoform .checkbox-group {
    display: flex;
    flex-direction: column;
    gap: 0.5rem;
}

.autoform .radio-button-set label,
.autoform .checkbox-group label {
    display: flex;
    align-items: center;
    gap: 0.5rem;
    font-weight: 400;
    cursor: pointer;
    margin: 0;
}

/* --- Validation & Errors --- */
.autoform .is-invalid {
    border-color: #ef4444 !important;
    background-color: #fef2f2 !important;
}

.autoform .is-invalid:focus {
    box-shadow: 0 0 0 3px rgba(239, 68, 68, 0.1) !important;
}

.autoform .error-message {
    display: none; /* Auto-toggled by field-assist */
    color: #ef4444;
    font-size: 0.75rem;
    margin-top: 0.25rem;
    font-weight: 600;
}

📜 Full API Documentation

See api.md for detailed function signatures and properties.

License

ISC