html-form-field 0.2.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/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.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-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

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
     }
 }