html-form-field 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yusuke Kawasaki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# html-form-field
+
+Unified interface for HTML form fields with synchronized binding to object properties
+
+[![Node.js CI](https://github.com/kawanet/html-form-field/workflows/Node.js%20CI/badge.svg)](https://github.com/kawanet/html-form-field/actions/)
+[![npm version](https://img.shields.io/npm/v/html-form-field)](https://www.npmjs.com/package/html-form-field)
+[![gzip size](https://img.badgesize.io/https://cdn.jsdelivr.net/npm/html-form-field/dist/html-form-field.min.js?compression=gzip)](https://cdn.jsdelivr.net/npm/html-form-field/dist/html-form-field.min.js)
+
+- Unified getter/setter for text inputs, checkboxes, radio buttons, and select elements
+- Two-way binding between form fields and object properties (synchronized updates in both directions)
+- Built-in change detection with `onChange` and `onWrite` callbacks
+- Small browser build: [html-form-field.min.js](https://cdn.jsdelivr.net/npm/html-form-field/dist/html-form-field.min.js) under 4KB minified, under 2KB gzipped
+- Full TypeScript support - [html-form-field.d.ts](https://github.com/kawanet/html-form-field/blob/main/types/html-form-field.d.ts) for detailed specifications
+
+## SYNOPSIS
+
+```typescript
+import {formField} from "html-form-field"
+
+interface Context {
+    nickname: string
+    email: string
+    favo: string
+}
+
+const form = document.querySelector("form")
+
+const ctx = {} as Context
+
+formField({form, bindTo: ctx, name: "nickname"})
+
+console.log(ctx.nickname) // reads from form field
+
+ctx.nickname = "John" // updates form field
+```
+
+#### HTML Example
+
+```html
+
+<form>
+    <ul>
+        <li>Nickname: <input type="text" name="nickname" value="Alice"></li>
+        <li>Email: <input type="email" name="email" value="alice@example.com"></li>
+        <li>Favorites:
+            <label><input type="checkbox" name="favo" value="tech">Tech</label>
+            <label><input type="checkbox" name="favo" value="travel">Travel</label>
+            <label><input type="checkbox" name="favo" value="trading">Trading</label>
+        </li>
+    </ul>
+</form>
+```
+
+#### Value Access
+
+```js
+const email = formField({form, name: "email"})
+
+console.log(email.value) // current value
+
+email.value = "john@example.com" // update value
+```
+
+#### Multiple Selections
+
+```js
+const favo = formField({form, name: "favo", delim: ","})
+
+favo.toggle("tech") // toggle checkbox
+
+favo.toggle("travel", true)
+
+favo.toggle("trading", false)
+
+console.log(favo.has("travel")) // check if selected
+
+// Shortcut to item by index. Equivalent to items().at(index))
+const firstItem = favo.itemAt(0)
+console.log(firstItem.checked)
+
+// Shortcut to item by value. Equivalent to items().find(v => v.value === value)
+const travelItem = favo.itemOf("travel")
+console.log(travelItem.checked)
+```
+
+#### Change Handling and Default Values
+
+```js
+formField({
+    form,
+    bindTo: ctx,
+    name: "email",
+    onWrite: ({name, value}) => sessionStorage.setItem(name, value),
+    onChange: ({name, value}) => submitForm(),
+    defaults: [sessionStorage.getItem("email")],
+})
+```
+
+## LINKS
+
+- https://www.npmjs.com/package/html-form-field
+- https://github.com/kawanet/html-form-field

package/dist/html-form-field.cjs

@@ -0,0 +1,353 @@
+'use strict';
+
+const triggerOnWrite$1 = (field) => {
+    const onWrite = field.options.onWrite;
+    if (onWrite) onWrite(field);
+};
+
+const checkableMap = {
+    option: true,
+    radio: true,
+    checkbox: true,
+};
+
+
+
+const isElementOf = (v, tagName) => ((v ).tagName === tagName);
+
+const formItemList = (field, nodeList) => {
+    const list = [];
+
+    for (const node of nodeList) {
+        if (isElementOf(node, "SELECT")) {
+            for (const option of node.options) {
+                list.push(new OptionItem(field, option));
+            }
+        } else {
+            list.push(new InputItem(field, node));
+        }
+    }
+
+    return list
+};
+
+ class BaseFormItem {
+    
+    
+    
+
+     constructor(field, node) {
+        this.field = field;
+        this.node = node;
+    }
+
+    get value() {
+        return this.node.value
+    }
+
+    set value(value) {
+        this.setValue(value);
+        triggerOnWrite$1(this.field);
+    }
+
+    setValue(value) {
+        this.node.value = value;
+    }
+
+    get checked() {
+        return this.getChecked()
+    }
+
+    
+
+    set checked(checked) {
+        const prev = this.checked;
+        if (prev !== checked) {
+            this.setChecked(checked);
+            triggerOnWrite$1(this.field);
+        }
+    }
+
+    
+
+    get disabled() {
+        return this.node.disabled
+    }
+
+    set disabled(disabled) {
+        this.node.disabled = disabled;
+    }
+
+    
+}
+
+class InputItem extends BaseFormItem {
+    
+
+    constructor(entry, node) {
+        super(entry, node);
+        this.checkable = checkableMap[node.type];
+    }
+
+     getChecked() {
+        return (this.node ).checked
+    }
+
+    setChecked(checked) {
+        (this.node ).checked = checked;
+    }
+
+    get label() {
+        const node = this.node;
+        const label = node.closest("label");
+        const siblings = label && label.querySelectorAll(node.tagName);
+
+        if (siblings && siblings.length === 1) {
+            const text = pickText(label);
+            if (text) return text
+        }
+
+        const labels = node.labels;
+        for (const label of labels) {
+            const text = pickText(label);
+            if (text) return text
+        }
+
+        const text = pickText(node);
+        if (text) return text
+
+        function pickText(node) {
+            const text = node.innerText || node.textContent;
+            if (text) return text.trim()
+        }
+    }
+}
+
+class OptionItem extends BaseFormItem {
+    
+
+    constructor(entry, node) {
+        super(entry, node);
+        this.checkable = true;
+    }
+
+     getChecked() {
+        return this.node.selected
+    }
+
+    setChecked(checked) {
+        // Note: Setting false may trigger auto-selection of the first option on select-one
+        this.node.selected = checked;
+    }
+
+    get label() {
+        const node = this.node;
+        const text = node.label || node.textContent;
+        if (text) return text.trim()
+    }
+}
+
+const DELIM = ","; // or use Unit Separator `\x1F` instead
+
+const isString = (v) => ("string" === typeof v);
+
+const noNullString = (v) => (v == null) ? "" : isString(v) ? v : String(v);
+
+const splitString = (v, delim) => (v == null) ? [] : Array.isArray(v) ? v.map(noNullString) : noNullString(v).split(delim);
+
+const isHTMLElement = (v) => ("function" === typeof (v ).matches);
+
+const formField = (options) => {
+    return new FormBridgeImpl(options)
+};
+
+const getNodeList = ({form, name}) => {
+    const safeName = JSON.stringify(name);
+    if (!name) {
+        throw new Error(`Invalid name=${safeName}`)
+    }
+
+    const selector = `input[name=${safeName}], textarea[name=${safeName}], button[name=${safeName}], select[name=${safeName}]`;
+
+    const nodeList = form.querySelectorAll(selector);
+    if (!nodeList.length) {
+        if (isHTMLElement(form) && form.matches(selector)) {
+            return [form] 
+        }
+
+        throw new Error(`Not found: name=${safeName}`)
+    }
+
+    return nodeList
+};
+
+const updateEventListener = (nodeList, handler) => {
+    for (const node of nodeList) {
+        node.removeEventListener("change", handler);
+        node.addEventListener("change", handler);
+    }
+};
+
+const triggerOnWrite = (field) => {
+    const onWrite = field.options.onWrite;
+    if (onWrite) onWrite(field);
+};
+
+const triggerOnChange = (field) => {
+    const onChange = field.options.onChange;
+    if (onChange) onChange(field);
+};
+
+const applyBindTo = (bindTo, name, field) => {
+    if (!bindTo) return // nothing to be bound
+
+    delete bindTo[name ];
+
+    const getValue = () => field.value;
+
+    const setValue = (value) => {
+        field.value = value;
+    };
+
+    Object.defineProperty(bindTo, name, {
+        get: getValue,
+        set: setValue,
+        enumerable: true,
+        configurable: true,
+    });
+};
+
+class FormBridgeImpl {
+    
+    
+
+    
+    
+
+    constructor(options = {} ) {
+        this.options = options;
+        const name = this.name = options.name;
+        applyBindTo(options.bindTo, name, this);
+
+        const _onChange = this._onChange = () => {
+            triggerOnWrite(this);
+            triggerOnChange(this);
+        };
+
+        const nodeList = getNodeList(options);
+        updateEventListener(nodeList, _onChange);
+        const items = this._items = formItemList(this, nodeList);
+
+        const defaults = options.defaults;
+        if (defaults) {
+            if (items[0].checkable) {
+                for (const v of defaults) {
+                    if (this.setValue(v)) break
+                }
+            } else {
+                this.setValue(defaults);
+            }
+        }
+    }
+
+    get value() {
+        const values = this.current().map(v => v.value);
+        if (values.length > 1) {
+            const delim = this.options.delim || DELIM;
+            return values.join(delim)
+        } else {
+            return values[0]
+        }
+    }
+
+    set value(value) {
+        this.setValue(value);
+        triggerOnWrite(this);
+    }
+
+     setValue(value) {
+        const items = this.items();
+
+        if (items.length === 1 && !items[0].checkable && isString(value)) {
+            value = [value];
+        }
+
+        const delim = this.options.delim || DELIM;
+        const values = splitString(value, delim);
+        let i = 0;
+        let assigned = 0;
+
+        for (const item of items) {
+            if (item.checkable) {
+                const checked = values.includes(item.value);
+                if (checked) assigned++;
+                if (item.checked !== checked) {
+                    item.setChecked(checked);
+                }
+            } else {
+                const value = values[i++];
+                const isNull = (value == null);
+                item.setValue(isNull ? "" : value);
+                if (!isNull) assigned++;
+            }
+        }
+
+        return !!assigned
+    }
+
+    current() {
+        return this.items().filter(v => (!v.disabled && (!v.checkable || v.checked)))
+    }
+
+    reload() {
+        const nodeList = getNodeList(this.options);
+        const _onChange = this._onChange;
+        updateEventListener(nodeList, _onChange);
+        this._items = formItemList(this, nodeList);
+    }
+
+    items() {
+        return this._items
+    }
+
+    toggle(value, checked) {
+        let result;
+        const delim = this.options.delim || DELIM;
+        const values = splitString(value, delim);
+
+        for (const item of this.items()) {
+            if (values.includes(item.value)) {
+                if (checked != null) {
+                    result = checked;
+                } else {
+                    result = !item.checked;
+                }
+                item.checked = result;
+            }
+        }
+
+        return result
+    }
+
+    has(value) {
+        return !!this.current().find(v => v.value === value)
+    }
+
+    /**
+     * Shortcut to access an item by index (operates on items()).
+     * Equivalent to items().at(index). Returns undefined if out of range.
+     */
+    itemAt(index) {
+        return this.items().at(index)
+    }
+
+    /**
+     * Shortcut to access an item by value (operates on items()).
+     * Returns the first FormItem whose value equals the given value, or undefined if not found.
+     */
+    itemOf(value) {
+        return this.items().find(v => v.value === value)
+    }
+}
+
+exports.formField = formField;

package/dist/html-form-field.min.js

@@ -0,0 +1 @@
+var formField=function(e){"use strict";const t=e=>{const t=e.options.onWrite;t&&t(e)},s={option:!0,radio:!0,checkbox:!0},n=(e,t)=>e.tagName===t,i=(e,t)=>{const s=[];for(const i of t)if(n(i,"SELECT"))for(const t of i.options)s.push(new c(e,t));else s.push(new r(e,i));return s};class o{constructor(e,t){this.field=e,this.node=t}get value(){return this.node.value}set value(e){this.setValue(e),t(this.field)}setValue(e){this.node.value=e}get checked(){return this.getChecked()}set checked(e){this.checked!==e&&(this.setChecked(e),t(this.field))}get disabled(){return this.node.disabled}set disabled(e){this.node.disabled=e}}class r extends o{constructor(e,t){super(e,t),this.checkable=s[t.type]}getChecked(){return this.node.checked}setChecked(e){this.node.checked=e}get label(){const e=this.node,t=e.closest("label"),s=t&&t.querySelectorAll(e.tagName);if(s&&1===s.length){const e=o(t);if(e)return e}const n=e.labels;for(const e of n){const t=o(e);if(t)return t}const i=o(e);if(i)return i;function o(e){const t=e.innerText||e.textContent;if(t)return t.trim()}}}class c extends o{constructor(e,t){super(e,t),this.checkable=!0}getChecked(){return this.node.selected}setChecked(e){this.node.selected=e}get label(){const e=this.node,t=e.label||e.textContent;if(t)return t.trim()}}const l=e=>"string"==typeof e,h=e=>null==e?"":l(e)?e:String(e),a=(e,t)=>null==e?[]:Array.isArray(e)?e.map(h):h(e).split(t),u=({form:e,name:t})=>{const s=JSON.stringify(t);if(!t)throw new Error(`Invalid name=${s}`);const n=`input[name=${s}], textarea[name=${s}], button[name=${s}], select[name=${s}]`,i=e.querySelectorAll(n);if(!i.length){if("function"==typeof e.matches&&e.matches(n))return[e];throw new Error(`Not found: name=${s}`)}return i},d=(e,t)=>{for(const s of e)s.removeEventListener("change",t),s.addEventListener("change",t)},f=e=>{const t=e.options.onWrite;t&&t(e)};class m{constructor(e={}){this.options=e;const t=this.name=e.name;((e,t,s)=>{if(!e)return;delete e[t],Object.defineProperty(e,t,{get:()=>s.value,set:e=>{s.value=e},enumerable:!0,configurable:!0})})(e.bindTo,t,this);const s=this._onChange=()=>{f(this),(e=>{const t=e.options.onChange;t&&t(e)})(this)},n=u(e);d(n,s);const o=this._items=i(this,n),r=e.defaults;if(r)if(o[0].checkable){for(const e of r)if(this.setValue(e))break}else this.setValue(r)}get value(){const e=this.current().map(e=>e.value);if(e.length>1){const t=this.options.delim||",";return e.join(t)}return e[0]}set value(e){this.setValue(e),f(this)}setValue(e){const t=this.items();1===t.length&&!t[0].checkable&&l(e)&&(e=[e]);const s=this.options.delim||",",n=a(e,s);let i=0,o=0;for(const e of t)if(e.checkable){const t=n.includes(e.value);t&&o++,e.checked!==t&&e.setChecked(t)}else{const t=n[i++],s=null==t;e.setValue(s?"":t),s||o++}return!!o}current(){return this.items().filter(e=>!e.disabled&&(!e.checkable||e.checked))}reload(){const e=u(this.options),t=this._onChange;d(e,t),this._items=i(this,e)}items(){return this._items}toggle(e,t){let s;const n=this.options.delim||",",i=a(e,n);for(const e of this.items())i.includes(e.value)&&(s=null!=t?t:!e.checked,e.checked=s);return s}has(e){return!!this.current().find(t=>t.value===e)}itemAt(e){return this.items().at(e)}itemOf(e){return this.items().find(t=>t.value===e)}}return e.formField=e=>new m(e),"undefined"!=typeof module&&(module.exports=e),e.formField}({});