# 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.

```html
<!-- 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:

```json
{
  "::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.