html-form-field 0.1.0 → 0.3.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

@@ -236,16 +236,12 @@ class FormBridgeImpl {
 
         const nodeList = getNodeList(options);
         updateEventListener(nodeList, _onChange);
-        const items = this._items = formItemList(this, nodeList);
+        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);
+            for (const v of defaults) {
+                if (this.setValue(v)) break
             }
         }
     }

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);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}({});
+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}({});

package/dist/html-form-field.mjs

@@ -234,16 +234,12 @@ class FormBridgeImpl {
 
         const nodeList = getNodeList(options);
         updateEventListener(nodeList, _onChange);
-        const items = this._items = formItemList(this, nodeList);
+        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);
+            for (const v of defaults) {
+                if (this.setValue(v)) break
             }
         }
     }

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.1.0",
-  "author": "Kawanet",
-  "c8": {
-    "reporter": [
-      "text",
-      "lcov"
-    ],
-    "include": [
-      "src/**/*.ts"
-    ],
-    "reportsDir": "coverage"
+  "version": "0.3.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-multi-entry": "^7.0.0",
+    "@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/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",
+    "@types/jsdom": "^28.0.3",
+    "@types/node": "^24.9.1",
+    "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
@@ -92,16 +92,12 @@ class FormBridgeImpl<T = any> implements FormField<T> {
 
         const nodeList = getNodeList(options)
         updateEventListener(nodeList, _onChange)
-        const items = this._items = formItemList(this, nodeList)
+        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)
+            for (const v of defaults) {
+                if (this.setValue(v)) break
             }
         }
     }

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,90 @@ 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
     }
 
     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
     }
 }