enhance-form 0.0.1

package/README.md

@@ -0,0 +1,171 @@
+# enhance-form
+
+A custom element that progressively enhances HTML forms with AJAX submission, per-field validation, and targeted DOM updates.
+
+Without JavaScript the form works as a normal HTML form. With JavaScript, `<enhance-form>` intercepts submissions and validation, swapping parts of the page with the server response.
+
+## Install
+
+```
+npm install enhance-form
+```
+
+## Usage
+
+Import the package to register the `<enhance-form>` custom element:
+
+```js
+import "enhance-form";
+```
+
+Wrap a `<form>` element:
+
+```html
+<enhance-form target="#result" fail-target="#errors">
+  <form action="/submit" method="POST">
+    <fieldset enhance-form-group>
+      <label for="email">Email</label>
+      <input id="email" name="email" type="email" enhance-validate />
+    </fieldset>
+
+    <fieldset enhance-form-group>
+      <label for="name">Name</label>
+      <input id="name" name="name" type="text" enhance-validate />
+    </fieldset>
+
+    <button type="submit">Submit</button>
+  </form>
+</enhance-form>
+
+<div id="result"></div>
+<div id="errors"></div>
+```
+
+## Attributes
+
+### `<enhance-form>`
+
+| Attribute     | Description                                                                 |
+| ------------- | --------------------------------------------------------------------------- |
+| `target`      | CSS selector for the element to replace with the response on success (200). |
+| `fail-target` | CSS selector for the element to replace on server errors (5XX). Defaults to `target`. |
+
+### On child elements
+
+| Attribute            | Used on                  | Description                                                        |
+| -------------------- | ------------------------ | ------------------------------------------------------------------ |
+| `enhance-form-group` | `<fieldset>` or any element | Groups an input with its label and validation messages. Used to scope per-field validation replacement. |
+| `enhance-validate`   | `<input>`, `<textarea>`  | Enables per-field validation on blur.                              |
+
+## How it works
+
+### Per-field validation (blur)
+
+When a user blurs an input with the `enhance-validate` attribute:
+
+1. The component POSTs the full form data to the form's `action` URL.
+2. A `X-Enhance-Validate` request header is sent with the field name as its value.
+3. The server responds with HTML containing the form (with validation state).
+4. The component extracts the matching `[enhance-form-group]` or `<fieldset>` that contains the validated field and replaces only that group in the DOM.
+
+Empty fields are skipped. Concurrent validation requests for the same field are aborted automatically.
+
+### Form submission
+
+When the form is submitted:
+
+1. Default submission is prevented.
+2. Any in-flight per-field validation requests are aborted.
+3. The component POSTs the form data with a `X-Enhance-Submit` request header.
+4. The response is handled based on the status code:
+
+| Status | Behavior |
+| ------ | -------- |
+| **200** | The element matching `target` is replaced with the corresponding element from the response. Uses the View Transitions API if available. |
+| **4XX** | The `<form>` is replaced with the form from the response (expected to contain validation errors). The first input with `aria-invalid="true"` is focused. |
+| **5XX** | The element matching `fail-target` is replaced with the corresponding element from the response. |
+
+If the response includes an `X-Enhance-Redirect` header, the browser navigates to that URL via `window.location.assign`.
+
+## Server contract
+
+The server must inspect the custom request headers to determine what kind of request it's handling and respond accordingly.
+
+### Request headers
+
+| Header               | Value        | Meaning                                         |
+| -------------------- | ------------ | ------------------------------------------------ |
+| `X-Enhance-Submit`   | `"form"`     | This is a full form submission via the component. |
+| `X-Enhance-Validate` | Field `name` | This is a validation-only request for a single field. |
+
+When neither header is present, treat it as a normal (non-JS) form submission.
+
+### Response expectations
+
+The server should always respond with **HTML**.
+
+**On validation requests** (`X-Enhance-Validate`):
+
+Return the full form markup. The component will extract the relevant form group itself. Include any validation errors or `aria-invalid` attributes on the validated field.
+
+**On submit requests** (`X-Enhance-Submit`):
+
+| Status | What to return |
+| ------ | -------------- |
+| **200** | HTML containing an element matching the `target` selector (the success state). |
+| **4XX** | HTML containing the `<form>` with validation errors. Mark invalid inputs with `aria-invalid="true"`. |
+| **5XX** | HTML containing an element matching the `fail-target` selector (the error state). |
+
+### Response headers
+
+| Header               | Value | Effect                                          |
+| -------------------- | ----- | ------------------------------------------------ |
+| `X-Enhance-Redirect` | URL   | The browser will navigate to this URL instead of updating the DOM. |
+
+### Accessing headers in code
+
+The package exports the header names as constants:
+
+```js
+import { EnhancedHeader } from "enhance-form";
+
+EnhancedHeader.Submit   // "X-Enhance-Submit"
+EnhancedHeader.Validate // "X-Enhance-Validate"
+EnhancedHeader.Redirect // "X-Enhance-Redirect"
+```
+
+## Server example
+
+A minimal Express handler:
+
+```js
+import { EnhancedHeader } from "enhance-form";
+
+app.post("/submit", (req, res) => {
+  const isEnhancedSubmit = req.headers[EnhancedHeader.Submit.toLowerCase()];
+  const validateField = req.headers[EnhancedHeader.Validate.toLowerCase()];
+
+  const errors = validate(req.body);
+
+  if (validateField) {
+    // Return the form with validation state for the field
+    return res.status(errors ? 422 : 200).send(renderForm(req.body, errors));
+  }
+
+  if (errors) {
+    return res.status(422).send(renderForm(req.body, errors));
+  }
+
+  if (isEnhancedSubmit) {
+    // Return just the success content that matches the target selector
+    return res.send('<div id="result"><p>Saved.</p></div>');
+  }
+
+  // Non-JS fallback: normal redirect
+  res.redirect("/success");
+});
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Custom headers used by the EnhanceForm component for progressive enhancement.
+ * @constant
+ */
+export declare const EnhancedHeader: {
+    /** Response header. Will cause the browser to go to url via window.location.assign */
+    readonly Redirect: "X-Enhance-Redirect";
+    /** Request header. Indicates a full submit.  */
+    readonly Submit: "X-Enhance-Submit";
+    /** Request header. Indicates that we're only interested in doing a validation */
+    readonly Validate: "X-Enhance-Validate";
+};
+export type EnhancedFormHeader = (typeof EnhancedHeader)[keyof typeof EnhancedHeader];

package/dist/index.js

@@ -0,0 +1,278 @@
+/**
+ * Custom headers used by the EnhanceForm component for progressive enhancement.
+ * @constant
+ */
+export const EnhancedHeader = {
+    /** Response header. Will cause the browser to go to url via window.location.assign */
+    Redirect: "X-Enhance-Redirect",
+    /** Request header. Indicates a full submit.  */
+    Submit: "X-Enhance-Submit",
+    /** Request header. Indicates that we're only interested in doing a validation */
+    Validate: "X-Enhance-Validate",
+};
+const parser = new DOMParser();
+/**
+ * A custom web component that progressively enhances HTML forms with AJAX submission,
+ * client-side validation, and targeted DOM updates.
+ *
+ * @class EnhanceForm
+ * @extends HTMLElement
+ *
+ * @example
+ * ```html
+ * <enhance-form target="#results" fail-target="#error-container">
+ *   <form action="/submit" method="POST">
+ *     <fieldset enhance-form-group>
+ *      <input name="email" enhance-validate />
+ *     </fieldset>
+ *     <button type="submit">Submit</button>
+ *   </form>
+ * </enhance-form>
+ * ```
+ *
+ * @attr {string} target - CSS selector for the element to replace on successful submission
+ * @attr {string} fail-target - CSS selector for the element to replace on server errors (defaults to target)
+ */
+class EnhanceForm extends HTMLElement {
+    /** The custom element tag name */
+    static tagName = "enhance-form";
+    /** The form element contained within this component */
+    _form;
+    /** CSS selector for the target element to update on success */
+    _targetSelector;
+    /** CSS selector for the target element to update on failure */
+    _failTargetSelector;
+    /** Map of abort controllers for managing concurrent requests */
+    controllers = new Map();
+    /**
+     * Creates an instance of EnhanceForm.
+     * @throws {Error} If no form element is found within the component
+     */
+    constructor() {
+        super();
+        const form = this.querySelector("form");
+        this._targetSelector = this.getAttribute("target") || "";
+        this._failTargetSelector =
+            this.getAttribute("fail-target") || this.getAttribute("target") || "";
+        if (!form) {
+            throw new Error("No form found in <enhance-form>");
+        }
+        this._form = form;
+    }
+    /**
+     * Handles individual input field validation on blur events.
+     * Sends an AJAX request to validate the field and updates the UI with the response.
+     *
+     * @param {Event} event - The blur event from the input field
+     * @returns {Promise<void>}
+     *
+     * @remarks
+     * - Skips validation for empty inputs
+     * - Aborts any pending validation requests for the same field
+     * - Updates only the form group containing the validated input
+     */
+    async handleInputValidation(event) {
+        const target = event.target;
+        // If the input is empty, we don't want to validate it.
+        if (target.value === "")
+            return;
+        this.controllers.get(target.name)?.abort("Aborted by user");
+        this.controllers.set(target.name, new AbortController());
+        const signal = this.controllers.get(target.name)?.signal;
+        const groupSelector = `:is([enhance-form-group], fieldset):has([name="${target.name}"])`;
+        try {
+            const headers = addHeader(EnhancedHeader.Validate, target.name);
+            const { html } = await this.requestForm(headers, signal);
+            if (!html)
+                return;
+            const newFormGroup = this.replaceElements(html, groupSelector);
+            const newValidateInput = newFormGroup?.querySelector(":is(input, textarea)[enhance-validate]");
+            if (newValidateInput) {
+                this.bindEvents(newValidateInput);
+            }
+        }
+        catch (error) {
+            console.warn("Form validation:", error);
+        }
+    }
+    /**
+     * Handles form submission with AJAX.
+     * Prevents default form submission and handles the response based on status codes.
+     *
+     * @remarks
+     * Response handling:
+     * - 200: Updates the target element with the response
+     * - 4XX: Replaces the form with validation errors
+     * - 5XX: Updates the fail-target element
+     * - Redirect header: Navigates to the specified URL
+     */
+    async handleFormValidation(event) {
+        event.preventDefault();
+        try {
+            // abort any individual input validation requests.
+            this.controllers.forEach((controller) => {
+                controller.abort();
+            });
+            this.controllers.set("form", new AbortController());
+            const { html, response } = await this.requestForm(addHeader(EnhancedHeader.Submit, "form"), this.controllers.get("form")?.signal);
+            if (getHeader(response, EnhancedHeader.Redirect) !== null) {
+                this.handleRedirect(response);
+            }
+            if (!html)
+                return;
+            // We expect the same form to be returned with all 4XX errors.
+            if (response.status >= 400 && response.status <= 499) {
+                const newForm = this.replaceElements(html, "form");
+                this._form = newForm;
+                this.bindEvents();
+            }
+            // We do NOT expect the same form to be returned with 5XX errors.
+            if (response.status >= 500 && response.status <= 599) {
+                this.replaceElements(html, this._failTargetSelector, this);
+            }
+            if (response.status === 200) {
+                const target = this.closest(this._targetSelector) !== null ? this.closest(this._targetSelector) : this;
+                viewTransition(() => this.replaceElements(html, this._targetSelector, target));
+            }
+            return Promise.resolve();
+        }
+        catch (error) {
+            console.warn("Form validation:", error);
+        }
+    }
+    /**
+     * Handles redirect responses by navigating to the specified URL.
+     *
+     * @param {Response} response - The fetch response containing redirect headers
+     * @private
+     */
+    handleRedirect(response) {
+        const redirectString = getHeader(response, EnhancedHeader.Redirect);
+        if (!redirectString)
+            return;
+        window.location.assign(redirectString);
+    }
+    /**
+     * Focuses the first input field with validation errors after form submission.
+     * Also positions the cursor at the end of the input value if possible.
+     *
+     * @private
+     */
+    focusFirstInvalidInput() {
+        const firstInvalidInput = this._form.querySelector(':is(input, textarea)[aria-invalid="true"]');
+        if (!firstInvalidInput)
+            return;
+        firstInvalidInput.focus();
+        // If possible, put cursor at the end of the focused input
+        if ("setSelectionRange" in firstInvalidInput) {
+            firstInvalidInput.setSelectionRange(-1, -1);
+        }
+    }
+    /**
+     * Sends a POST request to the form action URL with the form data.
+     *
+     * @param {Headers} [headers] - Optional headers to include in the request
+     * @param {AbortSignal} [signal] - Optional abort signal for cancelling the request
+     * @returns {Promise<{response: Response, html: Document | null}>} The response and parsed HTML
+     * @private
+     *
+     * @remarks
+     * - Automatically redirects for external URLs
+     * - Parses the response as HTML
+     */
+    async requestForm(headers, signal) {
+        const response = await fetch(this._form.action, {
+            method: "POST",
+            headers,
+            body: new FormData(this._form),
+            signal,
+        });
+        if (response.redirected && !isInternalUrl(response.url)) {
+            window.location.assign(response.url);
+            return { response, html: null };
+        }
+        const html = parser.parseFromString(await response.text(), "text/html");
+        return { response, html };
+    }
+    /**
+     * Replaces an element in the DOM with a new element from the response HTML.
+     *
+     * @param {Document} html - The parsed HTML document from the server response
+     * @param {string} selector - CSS selector for the element to replace
+     * @param {Element | null} [replaceRootElement] - Optional root element to search within
+     * @returns {Element | null} The new element that was inserted, or null if replacement failed
+     * @private
+     */
+    replaceElements(html, selector, replaceRootElement) {
+        const newElement = html.querySelector(selector);
+        const currentElement = replaceRootElement || this.querySelector(selector);
+        if (newElement && currentElement) {
+            currentElement.replaceWith(newElement);
+            return newElement;
+        }
+        return null;
+    }
+    /**
+     * Binds event listeners to form inputs and the form itself.
+     *
+     * @param {HTMLInputElement} [target] - Optional specific input to bind events to
+     * @private
+     *
+     * @remarks
+     * - If target is provided, only binds blur event to that input
+     * - Otherwise, binds submit event to form and blur events to all inputs with enhance-validate attribute
+     */
+    bindEvents(target) {
+        const blurHandler = (event) => {
+            this.handleInputValidation(event);
+        };
+        if (target) {
+            target.addEventListener("blur", blurHandler);
+            return;
+        }
+        this._form.addEventListener("submit", async (event) => {
+            await this.handleFormValidation(event);
+            this.focusFirstInvalidInput();
+        });
+        const inputs = this._form.querySelectorAll(":is(input, textarea)[enhance-validate]");
+        for (const input of inputs) {
+            input.addEventListener("blur", blurHandler);
+        }
+    }
+    connectedCallback() {
+        this.bindEvents();
+    }
+}
+/**
+ * Wraps a DOM update function in a view transition if supported by the browser.
+ * Falls back to immediate execution if View Transitions API is not available.
+ *
+ * @param {() => void} fn - The function to execute during the view transition
+ */
+function viewTransition(fn) {
+    if (!document.startViewTransition) {
+        fn();
+    }
+    else {
+        document.startViewTransition(() => fn());
+    }
+}
+const isInternalUrl = (url) => {
+    try {
+        const urlObj = new URL(url);
+        return urlObj.origin === window.location.origin;
+    }
+    catch {
+        return true; // Relative URLs are considered internal
+    }
+};
+const addHeader = (name, value) => {
+    const headers = new Headers();
+    headers.append(name, value);
+    return headers;
+};
+const getHeader = (response, name) => response.headers.get(name);
+// Register the custom element if not already defined
+if (!customElements.get(EnhanceForm.tagName)) {
+    customElements.define(EnhanceForm.tagName, EnhanceForm);
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "enhance-form",
+  "version": "0.0.1",
+  "description": "A custom element that progressively enhances HTML forms with AJAX submission, per-field validation, and targeted DOM updates.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "publint": "pnpm dlx publint",
+    "prepublishOnly": "npm run lint && npm run build"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "typescript": "^5.9.3"
+  },
+  "packageManager": "pnpm@9.15.4+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0"
+}