html-form-field 0.3.1 → 0.4.1

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,7 +1,7 @@
 {
   "name": "html-form-field",
   "description": "Unified interface for HTML form fields with synchronized binding to object properties",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "author": "@kawanet",
   "bugs": {
     "url": "https://github.com/kawanet/html-form-field/issues"

package/src/form-field.ts

@@ -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/types/html-form-field.d.ts

@@ -141,6 +141,26 @@ declare namespace formField {
          * 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> {
@@ -177,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>