form-utils (JavaScript)

Small, dependency‑free helpers to improve form UX and simplify common patterns:

Auto‑wire typical form behaviors (trim inputs, validate, optional XHR submit)
File input niceties (mirror selected filename, preview images)
"Submit on click/change" forms via CSS classes
Lightweight XHR flow with a minimal JSON response convention
Radio groups with label state syncing

Quick usage

Minimal setup; adjust paths as needed.

<!-- Example HTML -->
<form class="form-xhr form-onchange" method="post" action="/upload">
  <div>
    <input type="file" name="file" data-file-preview-target="preview-img" />
    <input type="text" name="file-path" placeholder="Selected file…" />
    <img id="preview-img" alt="Preview" />
  </div>

  <div class="radio-container">
    <label class="radio-input-wrapper">
      <input type="radio" name="size" value="s" /> Small
    </label>
    <label class="radio-input-wrapper">
      <input type="radio" name="size" value="m" /> Medium
    </label>
  </div>

  <button type="submit">Submit</button>
</form>

<script type="module">
  import FormUtils from "./form-utils.js";
  // Initialize helpers for the whole document (or pass a container element)
  await FormUtils.init();
</script>

What this does:

Trims all text/number inputs and textareas before submit
Validates the form; if valid:
- .form-xhr → submits with XMLHttpRequest and processes a simple JSON response
- otherwise → performs a normal form submit
.form-onchange → also triggers submit when any field changes
.form-onclick → also triggers submit when the form is clicked
File input:
- Mirrors the chosen filename to a sibling input[name="file-path"]
- If the file is an image and data-file-preview-target points to an <img>, previews it
Radio UI:
- In a .radio-container, toggles .radio-checked on labels whose input is checked

Markup conventions

Classes used by the helpers:
- form-xhr — submit via XHR instead of regular navigation
- form-onclick — dispatch a submit event when the form is clicked
- form-onchange — dispatch a submit event when any field changes
- radio-container — wrapper enabling radio label syncing
- radio-input-wrapper — wrapper around each radio/checkbox input
- radio-checked — added to a label when its input is checked
File preview:
- Add data-file-preview-target="some-id" on the file input
- Provide <img id="some-id"> to receive the preview
- Optional: add a sibling input[name="file-path"] to mirror the filename

JSON response convention (XHR)

When a .form-xhr form is submitted, the response is expected to be JSON. Non‑2xx statuses are logged as errors. A minimal, extensible convention is supported:

{
  "::function": [
    { "name": "log", "params": { "ok": true } }
  ]
}

Currently supported actions:

log — console.log(params)

Unrecognized actions are ignored without error.

API (overview)

All methods are static on FormUtils:

init(container?) — wires up inputs, selects, forms, and radio groups within container (or document)
clearFocus() — blurs the active element
readPath(event) — mirrors selected filename into a sibling input[name="file-path"]
readImage(event) — previews chosen image into the <img> referenced by data-file-preview-target
dispatchSubmitEvent(event) — dispatches a synthetic submit on the current form
trimInputs(form) — trims text/number inputs and textareas
checkValidity(event) — validates; normal submit or XHR depending on presence of .form-xhr
ajaxRequest(form) / ajaxResponse(xhr) — XHR submit and response handling
initRadios(container?) / radioChangeListener(event) — label state syncing for radio groups

Notes:

Assumes a browser environment (DOM APIs available).
Non‑blocking and dependency‑free.

License

See the repository‑level LICENSE file.

3.9 KiB Raw Blame History Unescape Escape