html-form-field 0.2.0 → 0.4.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Yusuke Kawasaki
+Copyright (c) 2025-2026 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

package/README.md

@@ -1,16 +1,16 @@
 # html-form-field
 
-Unified interface for HTML form fields with synchronized binding to object properties
+Unified interface for HTML form fields with two-way 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/)
+[![Node.js CI](https://github.com/kawanet/html-form-field/actions/workflows/nodejs.yml/badge.svg?branch=main)](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
+- A single getter/setter API for text inputs, checkboxes, radio buttons, and `<select>` elements.
+- Two-way binding between a form field and an object property: assignments flow in either direction.
+- Change-detection hooks via `onWrite` (any value write) and `onChange` (user-driven change events).
+- Tiny browser build — [html-form-field.min.js](https://cdn.jsdelivr.net/npm/html-form-field/dist/html-form-field.min.js) is under 4 KB minified and under 2 KB gzipped.
+- First-class TypeScript types — see [html-form-field.d.ts](https://github.com/kawanet/html-form-field/blob/main/types/html-form-field.d.ts) for the full surface.
 
 ## SYNOPSIS
 
@@ -29,15 +29,14 @@ const ctx = {} as Context
 
 formField({form, bindTo: ctx, name: "nickname"})
 
-console.log(ctx.nickname) // reads from form field
+console.log(ctx.nickname) // reads from the form field
 
-ctx.nickname = "John" // updates form field
+ctx.nickname = "John"     // writes back to the form field
 ```
 
 #### HTML Example
 
 ```html
-
 <form>
     <ul>
         <li>Nickname: <input type="text" name="nickname" value="Alice"></li>
@@ -56,9 +55,9 @@ ctx.nickname = "John" // updates form field
 ```js
 const email = formField({form, name: "email"})
 
-console.log(email.value) // current value
+console.log(email.value)         // read the current value
 
-email.value = "john@example.com" // update value
+email.value = "john@example.com" // assign a new value
 ```
 
 #### Multiple Selections
@@ -66,19 +65,17 @@ email.value = "john@example.com" // update value
 ```js
 const favo = formField({form, name: "favo", delim: ","})
 
-favo.toggle("tech") // toggle checkbox
-
-favo.toggle("travel", true)
+favo.toggle("tech")           // toggle one checkbox
+favo.toggle("travel", true)   // force-check
+favo.toggle("trading", false) // force-uncheck
 
-favo.toggle("trading", false)
+console.log(favo.has("travel")) // is this option currently selected?
 
-console.log(favo.has("travel")) // check if selected
-
-// Shortcut to item by index. Equivalent to items().at(index))
+// Shortcut for 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)
+// Shortcut for items().find(v => v.value === value)
 const travelItem = favo.itemOf("travel")
 console.log(travelItem.checked)
 ```
@@ -96,7 +93,29 @@ formField({
 })
 ```
 
-## LINKS
+## SEE ALSO
 
 - https://www.npmjs.com/package/html-form-field
 - https://github.com/kawanet/html-form-field
+
+## MIT LICENSE
+
+Copyright (c) 2025-2026 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/browser/import.js

@@ -0,0 +1,2 @@
+/* globals formField */
+exports.formField = formField;

package/browser/package.json

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

package/dist/html-form-field.cjs

@@ -147,6 +147,10 @@ class OptionItem extends BaseFormItem {
     }
 }
 
+function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
+
+
+
 const DELIM = ","; // or use Unit Separator `\x1F` instead
 
 const isString = (v) => ("string" === typeof v);
@@ -170,20 +174,29 @@ const getNodeList = ({form, name}) => {
     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}`)
+    if (!nodeList.length && isHTMLElement(form) && form.matches(selector)) {
+        return [form] 
     }
 
+    // No throw on a 0-match result here: a freshly rendered form may not yet
+    // contain the controls (dynamic radio/checkbox groups, lazy-populated
+    // <select>, etc.). The error surfaces lazily from `items()` instead.
     return nodeList
 };
 
-const updateEventListener = (nodeList, handler) => {
+// Detach `change` listeners from elements that were part of the previous
+// `_fields` snapshot. Pair this with `addEventListeners` on the new
+// snapshot inside `reload()` so a control that dropped out of the
+// selector (renamed, removed from the DOM, or moved out of the form)
+// stops firing this field's handlers.
+const removeEventListeners = (nodeList, handler) => {
     for (const node of nodeList) {
         node.removeEventListener("change", handler);
+    }
+};
+
+const addEventListeners = (nodeList, handler) => {
+    for (const node of nodeList) {
         node.addEventListener("change", handler);
     }
 };
@@ -222,6 +235,11 @@ class FormBridgeImpl {
     
 
     
+    // `null` when the most recent getNodeList() returned zero matches.
+    // Methods that need item-level access (items, value, current, etc.)
+    // surface the error lazily; closest() still works because it walks
+    // from `_fields[0]`, which is simply `undefined` in this state.
+    
     
 
     constructor(options = {} ) {
@@ -234,9 +252,9 @@ class FormBridgeImpl {
             triggerOnChange(this);
         };
 
-        const nodeList = getNodeList(options);
-        updateEventListener(nodeList, _onChange);
-        this._items = formItemList(this, nodeList);
+        const fields = this._fields = Array.from(getNodeList(options));
+        addEventListeners(fields, _onChange);
+        this._items = fields.length ? formItemList(this, fields) : null;
 
         const defaults = options.defaults;
         if (defaults) {
@@ -296,16 +314,41 @@ class FormBridgeImpl {
     }
 
     reload() {
-        const nodeList = getNodeList(this.options);
-        const _onChange = this._onChange;
-        updateEventListener(nodeList, _onChange);
-        this._items = formItemList(this, nodeList);
+        // Detach handlers from the previous snapshot first — `getNodeList()`
+        // can now legitimately return fewer (or zero) controls, and any
+        // node that drops out of the selector must stop firing this
+        // field's `change` listener.
+        removeEventListeners(this._fields, this._onChange);
+        const fields = this._fields = Array.from(getNodeList(this.options));
+        addEventListeners(fields, this._onChange);
+        this._items = fields.length ? formItemList(this, fields) : null;
     }
 
     items() {
+        if (!this._items) {
+            throw new Error(`Not found: name=${JSON.stringify(this.name)}`)
+        }
         return this._items
     }
 
+    /**
+     * Walk up from the field's first element (inclusive) and return the
+     * closest ancestor matching the selector. Useful for reaching the
+     * container element when the field is a `<select>` (so you can
+     * append `<option>` elements before calling `reload()`) or when
+     * the field is part of a checkbox/radio group inside a wrapper.
+     *
+     * For multi-element fields (checkbox/radio groups), the walk starts
+     * from the first element only — callers that need a different
+     * starting point can use `items().at(i)?.node.closest(selector)`.
+     *
+     * Returns `null` when no ancestor matches, matching the contract
+     * of `Element.closest()`.
+     */
+    closest(selector) {
+        return _nullishCoalesce(_optionalChain([this, 'access', _ => _._fields, 'access', _2 => _2[0], 'optionalAccess', _3 => _3.closest, 'call', _4 => _4(selector)]), () => ( null))
+    }
+
     toggle(value, checked) {
         let result;
         const delim = this.options.delim || DELIM;

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

@@ -1 +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),this._items=i(this,n);const o=e.defaults;if(o)for(const e of o)if(this.setValue(e))break}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}({});
+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 l(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 l 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 c=e=>"string"==typeof e,h=e=>null==e?"":c(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);return!i.length&&"function"==typeof e.matches&&e.matches(n)?[e]:i},d=(e,t)=>{for(const s of e)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=this._fields=Array.from(u(e));d(n,s),this._items=n.length?i(this,n):null;const o=e.defaults;if(o)for(const e of o)if(this.setValue(e))break}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&&c(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(){((e,t)=>{for(const s of e)s.removeEventListener("change",t)})(this._fields,this._onChange);const e=this._fields=Array.from(u(this.options));d(e,this._onChange),this._items=e.length?i(this,e):null}items(){if(!this._items)throw new Error(`Not found: name=${JSON.stringify(this.name)}`);return this._items}closest(e){return t=function(e){let t,s=e[0],n=1;for(;n<e.length;){const i=e[n],o=e[n+1];if(n+=2,("optionalAccess"===i||"optionalCall"===i)&&null==s)return;"access"===i||"optionalAccess"===i?(t=s,s=o(s)):"call"!==i&&"optionalCall"!==i||(s=o((...e)=>s.call(t,...e)),t=void 0)}return s}([this,"access",e=>e._fields,"access",e=>e[0],"optionalAccess",e=>e.closest,"call",t=>t(e)]),s=()=>null,null!=t?t:s();var t,s}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}({});

package/dist/html-form-field.mjs

@@ -145,6 +145,10 @@ class OptionItem extends BaseFormItem {
     }
 }
 
+function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
+
+
+
 const DELIM = ","; // or use Unit Separator `\x1F` instead
 
 const isString = (v) => ("string" === typeof v);
@@ -168,20 +172,29 @@ const getNodeList = ({form, name}) => {
     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}`)
+    if (!nodeList.length && isHTMLElement(form) && form.matches(selector)) {
+        return [form] 
     }
 
+    // No throw on a 0-match result here: a freshly rendered form may not yet
+    // contain the controls (dynamic radio/checkbox groups, lazy-populated
+    // <select>, etc.). The error surfaces lazily from `items()` instead.
     return nodeList
 };
 
-const updateEventListener = (nodeList, handler) => {
+// Detach `change` listeners from elements that were part of the previous
+// `_fields` snapshot. Pair this with `addEventListeners` on the new
+// snapshot inside `reload()` so a control that dropped out of the
+// selector (renamed, removed from the DOM, or moved out of the form)
+// stops firing this field's handlers.
+const removeEventListeners = (nodeList, handler) => {
     for (const node of nodeList) {
         node.removeEventListener("change", handler);
+    }
+};
+
+const addEventListeners = (nodeList, handler) => {
+    for (const node of nodeList) {
         node.addEventListener("change", handler);
     }
 };
@@ -220,6 +233,11 @@ class FormBridgeImpl {
     
 
     
+    // `null` when the most recent getNodeList() returned zero matches.
+    // Methods that need item-level access (items, value, current, etc.)
+    // surface the error lazily; closest() still works because it walks
+    // from `_fields[0]`, which is simply `undefined` in this state.
+    
     
 
     constructor(options = {} ) {
@@ -232,9 +250,9 @@ class FormBridgeImpl {
             triggerOnChange(this);
         };
 
-        const nodeList = getNodeList(options);
-        updateEventListener(nodeList, _onChange);
-        this._items = formItemList(this, nodeList);
+        const fields = this._fields = Array.from(getNodeList(options));
+        addEventListeners(fields, _onChange);
+        this._items = fields.length ? formItemList(this, fields) : null;
 
         const defaults = options.defaults;
         if (defaults) {
@@ -294,16 +312,41 @@ class FormBridgeImpl {
     }
 
     reload() {
-        const nodeList = getNodeList(this.options);
-        const _onChange = this._onChange;
-        updateEventListener(nodeList, _onChange);
-        this._items = formItemList(this, nodeList);
+        // Detach handlers from the previous snapshot first — `getNodeList()`
+        // can now legitimately return fewer (or zero) controls, and any
+        // node that drops out of the selector must stop firing this
+        // field's `change` listener.
+        removeEventListeners(this._fields, this._onChange);
+        const fields = this._fields = Array.from(getNodeList(this.options));
+        addEventListeners(fields, this._onChange);
+        this._items = fields.length ? formItemList(this, fields) : null;
     }
 
     items() {
+        if (!this._items) {
+            throw new Error(`Not found: name=${JSON.stringify(this.name)}`)
+        }
         return this._items
     }
 
+    /**
+     * Walk up from the field's first element (inclusive) and return the
+     * closest ancestor matching the selector. Useful for reaching the
+     * container element when the field is a `<select>` (so you can
+     * append `<option>` elements before calling `reload()`) or when
+     * the field is part of a checkbox/radio group inside a wrapper.
+     *
+     * For multi-element fields (checkbox/radio groups), the walk starts
+     * from the first element only — callers that need a different
+     * starting point can use `items().at(i)?.node.closest(selector)`.
+     *
+     * Returns `null` when no ancestor matches, matching the contract
+     * of `Element.closest()`.
+     */
+    closest(selector) {
+        return _nullishCoalesce(_optionalChain([this, 'access', _ => _._fields, 'access', _2 => _2[0], 'optionalAccess', _3 => _3.closest, 'call', _4 => _4(selector)]), () => ( null))
+    }
+
     toggle(value, checked) {
         let result;
         const delim = this.options.delim || DELIM;

package/package.json

@@ -1,47 +1,52 @@
 {
   "name": "html-form-field",
   "description": "Unified interface for HTML form fields with synchronized binding to object properties",
-  "version": "0.2.0",
-  "author": "Kawanet",
-  "c8": {
-    "reporter": [
-      "text",
-      "lcov"
-    ],
-    "include": [
-      "src/**/*.ts"
-    ],
-    "reportsDir": "coverage"
+  "version": "0.4.1",
+  "author": "@kawanet",
+  "bugs": {
+    "url": "https://github.com/kawanet/html-form-field/issues"
   },
+  "contributors": [
+    "kawanet <u-suke@kawa.net>"
+  ],
   "devDependencies": {
     "@rollup/plugin-alias": "^5.1.1",
+    "@rollup/plugin-commonjs": "^28.0.6",
     "@rollup/plugin-multi-entry": "^7.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
-    "@rollup/plugin-sucrase": "^5.0.2",
+    "@rollup/plugin-sucrase": "^5.1.0",
     "@rollup/plugin-terser": "^0.4.4",
-    "@types/jsdom": "^27.0.0",
+    "@types/jsdom": "^28.0.3",
     "@types/node": "^24.9.1",
-    "c8": "^10.1.3",
-    "chai": "^6.2.0",
-    "html-ele": "^0.0.1",
-    "jsdom": "^27.0.1",
-    "mocha": "^11.7.4",
-    "rollup": "^4.52.5",
-    "terser": "^5.44.0",
+    "html-ele": "^0.1.1",
+    "jsdom": "^29.1.1",
+    "mocha": "^11.7.6",
+    "rollup": "^4.60.4",
+    "terser": "^5.48.0",
     "typescript": "^5.9.3"
   },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=22",
+      "onFail": "warn"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "exports": {
     ".": {
+      "types": "./types/html-form-field.d.ts",
       "require": "./dist/html-form-field.cjs",
-      "import": {
-        "types": "./types/html-form-field.d.ts",
-        "default": "./dist/html-form-field.mjs"
-      }
+      "import": "./dist/html-form-field.mjs"
     }
   },
   "files": [
     "LICENSE",
     "README.md",
+    "browser/import.js",
+    "browser/package.json",
     "dist/html-form-field.cjs",
     "dist/html-form-field.min.js",
     "dist/html-form-field.mjs",
@@ -49,16 +54,30 @@
     "src/*.ts",
     "types/*.d.ts"
   ],
+  "homepage": "https://github.com/kawanet/html-form-field",
+  "keywords": [
+    "checkbox",
+    "form",
+    "html",
+    "input",
+    "radio",
+    "select",
+    "textarea"
+  ],
   "license": "MIT",
-  "main": "./src/index.ts",
+  "main": "./dist/html-form-field.cjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kawanet/html-form-field.git"
+  },
   "scripts": {
     "build": "make -C builder",
     "fixpack": "fixpack",
-    "prepare": "make -C builder clean all test",
-    "test": "node --test",
-    "test:coverage": "c8 node --test"
+    "prepack": "make -C builder is-buildable",
+    "prepare": "make -C builder is-not-buildable 2> /dev/null || make -C builder clean all test",
+    "test": "make -C builder test"
   },
   "sideEffects": false,
   "type": "module",
-  "types": "types/html-form-field.d.ts"
+  "types": "./types/html-form-field.d.ts"
 }

package/src/form-field.ts

@@ -1,4 +1,4 @@
-import type {formField as NS, FormField, FormFieldOptions} from "../types/html-form-field.d.ts"
+import type {formField as NS, FormField, FormFieldOptions} from "html-form-field"
 import {formItemList} from "./form-item.ts"
 
 type FieldEventHandler = (this: NS.FieldElement, ev: Event) => void
@@ -26,20 +26,29 @@ const getNodeList = <T>({form, name}: {form: ParentNode, name: NS.StringKeys<T>}
     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}`)
+    if (!nodeList.length && isHTMLElement(form) && form.matches(selector)) {
+        return [form] as NS.FieldElement[]
     }
 
+    // No throw on a 0-match result here: a freshly rendered form may not yet
+    // contain the controls (dynamic radio/checkbox groups, lazy-populated
+    // <select>, etc.). The error surfaces lazily from `items()` instead.
     return nodeList
 }
 
-const updateEventListener = (nodeList: Iterable<NS.FieldElement>, handler: FieldEventHandler) => {
+// Detach `change` listeners from elements that were part of the previous
+// `_fields` snapshot. Pair this with `addEventListeners` on the new
+// snapshot inside `reload()` so a control that dropped out of the
+// selector (renamed, removed from the DOM, or moved out of the form)
+// stops firing this field's handlers.
+const removeEventListeners = (nodeList: Iterable<NS.FieldElement>, handler: FieldEventHandler) => {
     for (const node of nodeList) {
         node.removeEventListener("change", handler)
+    }
+}
+
+const addEventListeners = (nodeList: Iterable<NS.FieldElement>, handler: FieldEventHandler) => {
+    for (const node of nodeList) {
         node.addEventListener("change", handler)
     }
 }
@@ -77,7 +86,12 @@ class FormBridgeImpl<T = any> implements FormField<T> {
     readonly options: FormFieldOptions<T>
     readonly name: FormField<T>["name"]
 
-    private _items: NS.FormItem[]
+    private _fields: NS.FieldElement[]
+    // `null` when the most recent getNodeList() returned zero matches.
+    // Methods that need item-level access (items, value, current, etc.)
+    // surface the error lazily; closest() still works because it walks
+    // from `_fields[0]`, which is simply `undefined` in this state.
+    private _items: NS.FormItem[] | null
     private readonly _onChange: FieldEventHandler
 
     constructor(options: FormFieldOptions<T> = {} as FormFieldOptions<T>) {
@@ -90,9 +104,9 @@ class FormBridgeImpl<T = any> implements FormField<T> {
             triggerOnChange(this)
         }
 
-        const nodeList = getNodeList(options)
-        updateEventListener(nodeList, _onChange)
-        this._items = formItemList(this, nodeList)
+        const fields = this._fields = Array.from(getNodeList(options))
+        addEventListeners(fields, _onChange)
+        this._items = fields.length ? formItemList(this, fields) : null
 
         const defaults = options.defaults
         if (defaults) {
@@ -152,16 +166,41 @@ class FormBridgeImpl<T = any> implements FormField<T> {
     }
 
     reload(): void {
-        const nodeList = getNodeList(this.options)
-        const _onChange = this._onChange
-        updateEventListener(nodeList, _onChange)
-        this._items = formItemList(this, nodeList)
+        // Detach handlers from the previous snapshot first — `getNodeList()`
+        // can now legitimately return fewer (or zero) controls, and any
+        // node that drops out of the selector must stop firing this
+        // field's `change` listener.
+        removeEventListeners(this._fields, this._onChange)
+        const fields = this._fields = Array.from(getNodeList(this.options))
+        addEventListeners(fields, this._onChange)
+        this._items = fields.length ? formItemList(this, fields) : null
     }
 
     items(): NS.FormItem[] {
+        if (!this._items) {
+            throw new Error(`Not found: name=${JSON.stringify(this.name)}`)
+        }
         return this._items
     }
 
+    /**
+     * Walk up from the field's first element (inclusive) and return the
+     * closest ancestor matching the selector. Useful for reaching the
+     * container element when the field is a `<select>` (so you can
+     * append `<option>` elements before calling `reload()`) or when
+     * the field is part of a checkbox/radio group inside a wrapper.
+     *
+     * For multi-element fields (checkbox/radio groups), the walk starts
+     * from the first element only — callers that need a different
+     * starting point can use `items().at(i)?.node.closest(selector)`.
+     *
+     * Returns `null` when no ancestor matches, matching the contract
+     * of `Element.closest()`.
+     */
+    closest<E extends Element = Element>(selector: string): E | null {
+        return this._fields[0]?.closest<E>(selector) ?? null
+    }
+
     toggle(value: string, checked?: boolean): boolean {
         let result: boolean
         const delim = this.options.delim || DELIM

package/src/form-item.ts

@@ -1,4 +1,4 @@
-import type {FormField, formField as NS} from "../types/html-form-field.d.ts"
+import type {FormField, formField as NS} from "html-form-field"
 
 const triggerOnWrite = (field: FormField) => {
     const onWrite = field.options.onWrite

package/src/index.ts

@@ -1,5 +1,9 @@
-export {formField} from "./form-field.ts"
-export type {FormField, FormFieldOptions} from "../types/html-form-field.d.ts"
-import type {formField as NS} from "../types/html-form-field.d.ts"
+// Self-reference via the package name so `tsc --noEmit` resolves these
+// types through `package.json` `exports` — the same path an external
+// consumer would take. If the `exports.types` mapping ever breaks, the
+// build fails here.
+import type * as declared from "html-form-field"
 
-export type formField = typeof NS
+export {formField} from "./form-field.ts"
+export type {FormField, FormFieldOptions} from "html-form-field"
+export type formField = typeof declared.formField

package/types/html-form-field.d.ts

@@ -1,71 +1,83 @@
 /**
- * html-form-field - Unified interface for HTML form fields with synchronized binding to object properties
+ * html-form-field — Unified interface for HTML form fields with two-way
+ * binding to object properties.
+ *
+ * @author kawanet
+ * @see https://github.com/kawanet/html-form-field
  */
+
 declare namespace formField {
+    /** Form field elements addressable by `name=`. */
     type FieldElement = HTMLInputElement | HTMLTextAreaElement | HTMLButtonElement | HTMLSelectElement
 
+    /** Individual item elements managed inside a field (a checkbox/radio in a group, or an `<option>` in a `<select>`). */
     type ItemElement = HTMLInputElement | HTMLTextAreaElement | HTMLButtonElement | HTMLOptionElement
 
     /**
-     * Extract string keys of T
-     * - If T is undefined: string (allow any name)
-     * - If T is an object: union of keys K where T[K] extends string (strict)
+     * Extracts the string-valued keys of `T`.
+     *
+     * - `T = undefined`: any `string` is accepted (no bound object means no key constraint).
+     * - `T` is an object: the union of keys `K` where `T[K]` extends `string`.
      */
     type StringKeys<T> = [T] extends [undefined]
         ? string
         : { [K in keyof T]: K extends string ? (T[K] extends string ? K : never) : never }[keyof T];
 
+    /** Handler invoked when a field value is written. See `FormFieldOptions.onWrite`. */
     type OnWrite<T> = FormFieldOptions<T>["onWrite"]
 
+    /** Handler invoked on a user-driven `change` event. See `FormFieldOptions.onChange`. */
     type OnChange<T> = FormFieldOptions<T>["onChange"]
 
     interface FormFieldOptions<T = any> {
         /**
-         * form element or container element which includes field elements
+         * The form element, or any container element that holds the field elements.
          */
         form: HTMLFormElement | FieldElement | ParentNode
 
         /**
-         * name of the field element
-         * - When `bindTo` is supplied, TypeScript infers `T` from that object and `name` is restricted
-         *   to keys of the bound object whose value type is `string`.
-         * - When `bindTo` is not supplied (or `T` is not inferred), any string is allowed.
+         * `name=` attribute of the field to bind.
+         *
+         * When `bindTo` is supplied, TypeScript infers `T` from that object and `name` is
+         * restricted to keys of the bound object whose value type is `string`. Without
+         * `bindTo`, any string is accepted.
          */
         name: StringKeys<T>
 
         /**
-         * Object to synchronize form values.
-         * Only properties matching field names obtained via item() will have getters/setters defined.
-         * The getter always references the value of the DOM field,
-         * and the setter updates the DOM and triggers onWrite.
-         * Other properties are not affected.
+         * Object to synchronize with the form field.
+         *
+         * A getter/setter is installed on the property matching `name`: the getter reads
+         * the live DOM value, the setter writes back to the DOM and fires `onWrite`. Other
+         * properties on the object are left untouched.
          */
         bindTo?: T
 
         /**
-         * Called when the value is changed by user interaction,
-         * or when assigning to a bound object's property.
-         * Fires before onChange.
+         * Called whenever the field value is written — either by a setter
+         * (`field.value = ...` or assignment to a bound property) or by a user-driven
+         * `change` event. Fires before `onChange`.
          */
         onWrite?: (field: FormField<T>) => void
 
         /**
-         * Called when the value is changed by user interaction (change event).
-         * Not triggered by setter assignments. Fires after onWrite.
+         * Called only on a user-driven `change` event. Setter assignments do not trigger
+         * this handler. Fires after `onWrite`.
          */
         onChange?: (item: FormField<T>) => void
 
         /**
-         * delimiter for multiple values (for checkboxes, multi-select)
-         * Default: `,` (comma). Use Unit Separator `\x1F` instead,
-         * if your values may include commas to reduce collisions.
+         * Delimiter joining multiple values for checkbox groups and multi-select fields.
+         * Defaults to `,` (comma). Use Unit Separator (`\x1F`) if your values may contain
+         * commas.
          */
         delim?: string
 
         /**
-         * Default values to attempt at initialization (in order).
-         * For checkbox/radio/select fields, tries the first value; if no matching option exists,
-         * falls back to the next value, and so on until a match is found.
+         * Candidate initial values, tried in order.
+         *
+         * For checkbox / radio / select fields, the first value with a matching option is
+         * applied; if none matches, the next candidate is tried, and so on.
          */
         defaults?: string[]
     }
@@ -73,108 +85,110 @@ declare namespace formField {
     interface FormField<T = any> {
         readonly options: FormFieldOptions<T>
 
-        /**
-         * name of the field element (input, select, textarea)
-         */
+        /** `name=` attribute of the bound field. */
         readonly name: StringKeys<T>
 
         /**
-         * getter/setter of the value.
-         * setter triggers onWrite handler.
-         * Note: even for checkbox groups / multiple-select, the exposed type is string.
-         * Multiple values are represented as a single string joined by options.delim (default ',').
+         * Getter/setter for the field value. Assignment fires the `onWrite` handler.
+         *
+         * For checkbox groups and multi-select fields the value is exposed as a single
+         * string formed by joining the selected values with `options.delim` (default `,`).
          */
         value: string
 
         /**
-         * rebind the field element (input, select, textarea).
-         * Call this when the set of option elements changes (for example when checkboxes,
-         * radio buttons, or select <option> elements are added or removed) so that the
-         * FormField re-scans and rebinds its items to reflect the current DOM.
+         * Re-scan the form for items matching `name` and rebind them. Call this after
+         * the underlying DOM changes — for example when checkboxes, radio buttons, or
+         * `<option>` elements are added or removed — so the `FormField` reflects the
+         * current state of the form.
          */
         reload(): void
 
         /**
-         * list of all items (including disabled items)
-         * - for checkbox, radio, select: returns all options
-         * - for other types: returns all item(s)
+         * All items belonging to the field, including disabled ones.
+         *
+         * - checkbox / radio / select: every option in the group.
+         * - other field types: the single underlying item.
          */
         items(): FormItem[]
 
         /**
-         * list of active items (excluding disabled items)
-         * - for checkbox, radio: returns checked and not-disabled items
-         * - for select: returns selected and not-disabled options
-         * - for other types: returns all not-disabled item(s)
+         * Active items only — disabled items are excluded.
+         *
+         * - checkbox / radio: items that are currently checked and enabled.
+         * - select: options that are currently selected and enabled.
+         * - other field types: the single underlying item, if enabled.
          */
         current(): FormItem[]
 
         /**
-         * select/deselect an option (for checkbox, multi-select)
+         * Toggle the selection of an item (checkbox or multi-select). With `checked`
+         * supplied, sets the state explicitly; without it, flips the current state.
+         * Returns the new selection state.
          */
         toggle(value: string, checked?: boolean): boolean
 
-        /**
-         * check if an option is selected (for checkbox, multi-select)
-         */
+        /** Returns `true` if the given value is currently selected. */
         has(value: string): boolean
 
         /**
-         * Shortcut to access an item by index (operates on items()).
-         * Equivalent to items().at(index). Returns undefined if out of range.
+         * Shortcut for `items().at(index)`. Returns `undefined` when out of range.
          */
         itemAt(index: number): FormItem | undefined
 
         /**
-         * 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.
+         * Shortcut for `items().find(v => v.value === value)`. Returns the first match,
+         * or `undefined` if no item has the given value.
          */
         itemOf(value: string): FormItem | undefined
+
+        /**
+         * Walk up from the field's first element (inclusive) and return the closest
+         * ancestor that matches `selector`, mirroring `Element.closest()`.
+         *
+         * The primary use case is reaching the container element so you can mutate
+         * the DOM and then call `reload()`. For example, to populate an initially
+         * empty `<select>`:
+         *
+         * ```ts
+         * const cityField = formField({form, name: "city"})
+         * const select = cityField.closest<HTMLSelectElement>("select")
+         * select.add(new Option("Tokyo", "tokyo"))
+         * cityField.reload()
+         * ```
+         *
+         * For multi-element fields (checkbox/radio groups), the walk starts from
+         * the first element only. Returns `null` if no ancestor matches.
+         */
+        closest<E extends Element = Element>(selector: string): E | null
     }
 
     interface FormItem<E extends ItemElement = ItemElement> {
-        /**
-         * underlying HTML element (input, option, textarea)
-         */
+        /** Underlying HTML element (`<input>`, `<option>`, `<textarea>`, ...). */
         readonly node: E
 
-        /**
-         * getter/setter of the `value` property
-         * setter triggers onWrite handler
-         */
+        /** Getter/setter for the item's `value` property. Assignment fires `onWrite`. */
         value: string
 
-        /**
-         * method to set the `value` property silently
-         * does not trigger onWrite handler
-         */
+        /** Set `value` without firing `onWrite`. */
         setValue(value: string): void
 
-        /**
-         * whether the option is checkable (radio, checkbox, select)
-         */
+        /** Whether the item is a checkable type (radio, checkbox, or `<option>`). */
         readonly checkable: boolean
 
         /**
-         * whether the option is selected (radio, checkbox, select)
-         * setter triggers onWrite handler
+         * Selection state for radio buttons, checkboxes, and `<option>` elements.
+         * Assignment fires `onWrite`.
          */
         checked: boolean | undefined
 
-        /**
-         * method to set the `checked` property silently
-         * does not trigger onWrite handler
-         */
+        /** Set `checked` without firing `onWrite`. */
         setChecked(checked: boolean): void
 
-        /**
-         * getter/setter of the `disabled` property
-         */
+        /** Getter/setter for the `disabled` property. */
         disabled: boolean
 
-        /**
-         * text content of the option (if applicable)
-         */
+        /** Visible label text of the item, when the underlying element exposes one. */
         readonly label: string | undefined
     }
 }
@@ -183,4 +197,13 @@ export type FormField<T = any> = formField.FormField<T>
 
 export type FormFieldOptions<T = any> = formField.FormFieldOptions<T>
 
+/**
+ * Construct a `FormField` bound to the form control(s) with the given `name`.
+ *
+ * Construction itself does not throw when zero controls match — the resulting
+ * field can still call `closest()` to locate the surrounding container so the
+ * caller can populate a dynamic group and then `reload()`. Methods that
+ * actually need an item (`items()`, `value`, `current()`, `toggle()`, …) throw
+ * `Not found: name=...` lazily until at least one control is matched.
+ */
 export const formField: <T = any>(options: FormFieldOptions<T>) => FormField<T>