html-form-field 0.1.0

package/dist/html-form-field.mjs

@@ -0,0 +1,351 @@
+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)
+    }
+}
+
+export { formField };

package/dist/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "html-form-field",
+  "description": "Unified interface for HTML form fields with synchronized binding to object properties",
+  "version": "0.1.0",
+  "author": "Kawanet",
+  "c8": {
+    "reporter": [
+      "text",
+      "lcov"
+    ],
+    "include": [
+      "src/**/*.ts"
+    ],
+    "reportsDir": "coverage"
+  },
+  "devDependencies": {
+    "@rollup/plugin-alias": "^5.1.1",
+    "@rollup/plugin-multi-entry": "^7.0.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-sucrase": "^5.0.2",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@types/jsdom": "^27.0.0",
+    "@types/node": "^24.7.2",
+    "c8": "^10.1.3",
+    "chai": "^6.2.0",
+    "html-ele": "^0.0.1",
+    "jsdom": "^27.0.0",
+    "mocha": "^11.7.4",
+    "rollup": "^4.52.4",
+    "terser": "^5.44.0",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": {
+      "require": "./dist/html-form-field.cjs",
+      "import": {
+        "types": "./types/html-form-field.d.ts",
+        "default": "./dist/html-form-field.mjs"
+      }
+    }
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist/html-form-field.cjs",
+    "dist/html-form-field.min.js",
+    "dist/html-form-field.mjs",
+    "dist/package.json",
+    "src/*.ts",
+    "types/*.d.ts"
+  ],
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "scripts": {
+    "build": "make -C builder",
+    "fixpack": "fixpack",
+    "prepare": "make -C builder clean all test",
+    "test": "node --test",
+    "test:coverage": "c8 node --test"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "types": "types/html-form-field.d.ts"
+}

package/src/form-field.ts

@@ -0,0 +1,207 @@
+import type {formField as NS, FormField, FormFieldOptions} from "../types/html-form-field.d.ts"
+import {formItemList} from "./form-item.ts"
+
+type FieldEventHandler = (this: NS.FieldElement, ev: Event) => void
+
+const DELIM = "," // or use Unit Separator `\x1F` instead
+
+const isString = (v: any): v is string => ("string" === typeof v)
+
+const noNullString = (v: any): string => (v == null) ? "" : isString(v) ? v : String(v)
+
+const splitString = (v: string | string[], delim: string) => (v == null) ? [] : Array.isArray(v) ? v.map(noNullString) : noNullString(v).split(delim)
+
+const isHTMLElement = (v: ParentNode): v is HTMLElement => ("function" === typeof (v as HTMLElement).matches)
+
+export const formField: typeof NS = (options) => {
+    return new FormBridgeImpl(options)
+}
+
+const getNodeList = <T>({form, name}: {form: ParentNode, name: NS.StringKeys<T>}): Iterable<NS.FieldElement> => {
+    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<NS.FieldElement>(selector)
+    if (!nodeList.length) {
+        if (isHTMLElement(form) && form.matches(selector)) {
+            return [form] as NS.FieldElement[]
+        }
+
+        throw new Error(`Not found: name=${safeName}`)
+    }
+
+    return nodeList
+}
+
+const updateEventListener = (nodeList: Iterable<NS.FieldElement>, handler: FieldEventHandler) => {
+    for (const node of nodeList) {
+        node.removeEventListener("change", handler)
+        node.addEventListener("change", handler)
+    }
+}
+
+const triggerOnWrite = <T>(field: FormField<T>) => {
+    const onWrite = field.options.onWrite
+    if (onWrite) onWrite(field)
+}
+
+const triggerOnChange = <T>(field: FormField<T>) => {
+    const onChange = field.options.onChange
+    if (onChange) onChange(field)
+}
+
+const applyBindTo = <T>(bindTo: T, name: NS.StringKeys<T>, field: FormField<T>) => {
+    if (!bindTo) return // nothing to be bound
+
+    delete bindTo[name as keyof T]
+
+    const getValue = () => field.value
+
+    const setValue = (value: string) => {
+        field.value = value
+    }
+
+    Object.defineProperty(bindTo, name, {
+        get: getValue,
+        set: setValue,
+        enumerable: true,
+        configurable: true,
+    })
+}
+
+class FormBridgeImpl<T = any> implements FormField<T> {
+    readonly options: FormFieldOptions<T>
+    readonly name: FormField<T>["name"]
+
+    private _items: NS.FormItem[]
+    private readonly _onChange: FieldEventHandler
+
+    constructor(options: FormFieldOptions<T> = {} as FormFieldOptions<T>) {
+        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: string) {
+        this.setValue(value)
+        triggerOnWrite(this)
+    }
+
+    protected setValue(value: string | string[]): boolean {
+        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(): void {
+        const nodeList = getNodeList(this.options)
+        const _onChange = this._onChange
+        updateEventListener(nodeList, _onChange)
+        this._items = formItemList(this, nodeList)
+    }
+
+    items(): NS.FormItem[] {
+        return this._items
+    }
+
+    toggle(value: string, checked?: boolean): boolean {
+        let result: boolean
+        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: string): boolean {
+        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: number): NS.FormItem | undefined {
+        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: string): NS.FormItem | undefined {
+        return this.items().find(v => v.value === value)
+    }
+}