@twobirds/microcomponents 0.2.1 → 0.2.3

package/dist/state/formValues.d.ts

@@ -1,70 +1,117 @@
 /**
- * @module Form Values
- *
- * This module exports a single function {@link formValues} that traverses a DOM element
- * (usually an HTMLFormElement), collecting all input fields and creating a two-way bound
- * observable inside the target object:
- * - When input values change, the observable object updates accordingly.
- * - When the observable property values change, the input field values update in the DOM.
- *
- * **Prerequisites:**
- * - Input fields must have a `name` attribute.
- * - Names must be unique within the form.
- *
- * @example
- * ```ts
- * import { DC } from '@twobirds/microcomponents';
- * import { formValues } from '@twobirds/microcomponents/formValues';
- *
- * class MyMC extends DC {
- *   constructor(target: HTMLElement) {
- *     super(target);
- *     this.target.innerHTML = '<form><input name="textinput" value="" /></form>';
- *
- *     // link the form property to the DOM input fields
- *     formValues(this, 'form', this.target);
- *
- *     // changing the form property updates the DOM automatically
- *     this.form.textinput = 'Hello world!';
- *   }
- * }
- * ```
- */
+Two-way binding between DOM form controls (`input`, `select`, `textarea`) and an observable
+object property. Reads reflect live DOM values; writes update the controls synchronously.
+Most likely you will only need the the first variant mentioned in the examples below.
+
+@module Form Values
+
+@example Plugin — chainable instance method on DC components
+```ts
+import { DC, defineCE, formValuePlugin } from '@twobirds/microcomponents';
+
+formValuePlugin(DC);
+
+class CheckoutForm extends DC {
+    static assets = ['targetHtml'];
+
+    oneAssets() {
+        this
+            .formValues(this.target, 'formData')
+            .subscribe('formData', (data) => console.log(data))
+            .bind('formData', this.target);
+    }
+}
+
+defineCE('checkout-form', CheckoutForm);
+```
+
+@example Standalone function — bind a plain object to a form in the DOM
+```ts
+import { formValues } from '@twobirds/microcomponents/formValues';
+
+const state = {};
+formValues(state, 'formData', document.getElementById('myForm'));
+console.log(state.formData.username); // reads <input name="username"> value
+state.formData.role = 'admin';        // writes back to the <select> control
+```
+*/
 /**
- * Attaches a form-values observable to a target object property, allowing two-way binding
- * between the DOM form controls and the object's state.
- *
- * @param targetObject - The object to which the form values will be attached as an observable.
- * @param propertyName - The name of the property on the target object that will hold the form data.
- * @param dom - The DOM element or shadow root (typically a form) whose inputs should be observed and bound.
- *
- * @example
- * ```html
- * <form id="myForm">
- *   <input type="text" name="username" value="">
- *   <select name="role"><option value="admin">Admin</option><option value="user">User</option></select>
- *   <textarea name="bio"></textarea>
- *   <input type="checkbox" name="active">
- *   <input type="radio" name="gender" value="male"> Male
- *   <input type="radio" name="gender" value="female"> Female
- * </form>
- * ```
- *
- * ```ts
- * import { formValues } from '@twobirds/microcomponents/formValues';
- *
- * const state = {};
- * formValues(state, 'formData', document.getElementById('myForm'));
- *
- * // Read values from the form
- * console.log(state.formData.username);  // string
- * console.log(state.formData.role);      // "admin" or "user"
- * console.log(state.formData.active);    // boolean
- *
- * // Write values to the form (updates DOM automatically)
- * state.formData.username = 'john_doe';
- * state.formData.gender = 'male';
- * ```
- */
+@hidden
+
+Attaches a form-values observable to a target object property, enabling two-way binding
+between DOM form controls and the object's state.
+
+Scans the given DOM subtree for `input`, `select`, and `textarea` elements with a `name`
+attribute and creates live getters/setters on the resulting observable. Input events trigger
+automatic notifications so subscribers react to user changes.
+
+@param targetObject - The object that will receive the form-data property.
+@param propertyName - The property name under which the bound form data is stored.
+@param dom - HTMLElement or ShadowRoot containing the form controls.
+
+@example Bind a plain object to an HTML form element
+```ts
+import { formValues } from '@twobirds/microcomponents/formValues';
+
+const state = {};
+formValues(state, 'formData', document.getElementById('myForm'));
+console.log(state.formData.username); // reads <input name="username"> value
+state.formData.role = 'admin';        // writes back to the <select> control
+```
+
+@example Subscribe to form changes inside a component
+```ts
+import { DC, defineCE, formValues } from '@twobirds/microcomponents';
+
+class MyForm extends DC {
+    static assets = ['targetHtml'];
+
+    oneAssets() {
+        formValues(this, 'formData', this.target);
+        this.formData.subscribe((data) => console.log('form changed:', data));
+    }
+}
+
+defineCE('my-form', MyForm);
+```
+*/
 export declare function formValues<T extends object>(targetObject: T, propertyName: keyof T & string, dom: HTMLElement | ShadowRoot): void;
+/**
+Attaches a convenience method `formValues()` to the prototype of a microcomponent class so that
+form controls can be bound directly on the instance without importing the standalone function.
+
+This plugin also pulls in all observable methods from {@link observePlugin} — `notify()`,
+`subscribe()`, and `bind()` — so you can chain them fluently after binding form data.
+
+Call it once at module level before defining any component classes. The plugin is idempotent —
+subsequent calls are no-ops.
+
+@param Class - A constructor function whose prototype chain includes {@link Core.McBase}.
+
+@example
+```ts
+import { DC, defineCE, formValuePlugin } from '@twobirds/microcomponents';
+
+formValuePlugin(DC);
+
+class CheckoutForm extends DC {
+    static assets = ['targetHtml'];
+
+    oneAssets() {
+        this
+            .formValues(this.target, 'formData')
+            .subscribe('formData', (data) => console.log(data))
+            .bind('formData', this.target);
+    }
+}
+
+defineCE('checkout-form', CheckoutForm);
+```
+*/
+export declare function formValuePlugin(Class: any): void;
+declare module '../core/MC' {
+    interface McBase<TTarget extends object = object> {
+        formValues(target: object, propName: string): this;
+    }
+}
 //# sourceMappingURL=formValues.d.ts.map

package/dist/state/formValues.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formValues.d.ts","sourceRoot":"","sources":["../../src/state/formValues.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AA4SH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EAC1C,YAAY,EAAE,CAAC,EACf,YAAY,EAAE,MAAM,CAAC,GAAG,MAAM,EAC9B,GAAG,EAAE,WAAW,GAAG,UAAU,QAuB7B"}
+{"version":3,"file":"formValues.d.ts","sourceRoot":"","sources":["../../src/state/formValues.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoCE;AA8SF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuCE;AACF,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EAC1C,YAAY,EAAE,CAAC,EACf,YAAY,EAAE,MAAM,CAAC,GAAG,MAAM,EAC9B,GAAG,EAAE,WAAW,GAAG,UAAU,QAuB7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BE;AACF,wBAAgB,eAAe,CAAC,KAAK,EAAE,GAAG,QA2BzC;AAED,OAAO,QAAQ,YAAY,CAAC;IAC3B,UAAiB,MAAM,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;QACtD,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;KACnD;CACD"}

package/dist/state/formValues.js

@@ -1,38 +1,44 @@
 /**
- * @module Form Values
- *
- * This module exports a single function {@link formValues} that traverses a DOM element
- * (usually an HTMLFormElement), collecting all input fields and creating a two-way bound
- * observable inside the target object:
- * - When input values change, the observable object updates accordingly.
- * - When the observable property values change, the input field values update in the DOM.
- *
- * **Prerequisites:**
- * - Input fields must have a `name` attribute.
- * - Names must be unique within the form.
- *
- * @example
- * ```ts
- * import { DC } from '@twobirds/microcomponents';
- * import { formValues } from '@twobirds/microcomponents/formValues';
- *
- * class MyMC extends DC {
- *   constructor(target: HTMLElement) {
- *     super(target);
- *     this.target.innerHTML = '<form><input name="textinput" value="" /></form>';
- *
- *     // link the form property to the DOM input fields
- *     formValues(this, 'form', this.target);
- *
- *     // changing the form property updates the DOM automatically
- *     this.form.textinput = 'Hello world!';
- *   }
- * }
- * ```
- */
+Two-way binding between DOM form controls (`input`, `select`, `textarea`) and an observable
+object property. Reads reflect live DOM values; writes update the controls synchronously.
+Most likely you will only need the the first variant mentioned in the examples below.
+
+@module Form Values
+
+@example Plugin — chainable instance method on DC components
+```ts
+import { DC, defineCE, formValuePlugin } from '@twobirds/microcomponents';
+
+formValuePlugin(DC);
+
+class CheckoutForm extends DC {
+    static assets = ['targetHtml'];
+
+    oneAssets() {
+        this
+            .formValues(this.target, 'formData')
+            .subscribe('formData', (data) => console.log(data))
+            .bind('formData', this.target);
+    }
+}
+
+defineCE('checkout-form', CheckoutForm);
+```
+
+@example Standalone function — bind a plain object to a form in the DOM
+```ts
+import { formValues } from '@twobirds/microcomponents/formValues';
+
+const state = {};
+formValues(state, 'formData', document.getElementById('myForm'));
+console.log(state.formData.username); // reads <input name="username"> value
+state.formData.role = 'admin';        // writes back to the <select> control
+```
+*/
 import { DC } from '../core/MC.js';
 import { copyGettersSetters, isBrowser } from '../utils/helpers.js';
-import { observe } from './observables.js';
+import { observe, observePlugin } from './observables.js';
+observePlugin(DC);
 /**
 Extracts the lowercase tag name of an element (e.g., 'input', 'select', 'textarea').
 @param inputElement - The HTML element to extract the tag name from.
@@ -177,7 +183,7 @@ class SelectHandler extends InputBase {
             .forEach((o) => {
             ret.push(o.value);
         });
-        return this.#multi ? ret.join(',') : ret[0];
+        return this.#multi ? ret : ret[0];
     }
     /**
      * Sets the selected option(s) by value.
@@ -279,41 +285,45 @@ const getInputHandlers = (e) => {
     return handlers;
 };
 /**
- * Attaches a form-values observable to a target object property, allowing two-way binding
- * between the DOM form controls and the object's state.
- *
- * @param targetObject - The object to which the form values will be attached as an observable.
- * @param propertyName - The name of the property on the target object that will hold the form data.
- * @param dom - The DOM element or shadow root (typically a form) whose inputs should be observed and bound.
- *
- * @example
- * ```html
- * <form id="myForm">
- *   <input type="text" name="username" value="">
- *   <select name="role"><option value="admin">Admin</option><option value="user">User</option></select>
- *   <textarea name="bio"></textarea>
- *   <input type="checkbox" name="active">
- *   <input type="radio" name="gender" value="male"> Male
- *   <input type="radio" name="gender" value="female"> Female
- * </form>
- * ```
- *
- * ```ts
- * import { formValues } from '@twobirds/microcomponents/formValues';
- *
- * const state = {};
- * formValues(state, 'formData', document.getElementById('myForm'));
- *
- * // Read values from the form
- * console.log(state.formData.username);  // string
- * console.log(state.formData.role);      // "admin" or "user"
- * console.log(state.formData.active);    // boolean
- *
- * // Write values to the form (updates DOM automatically)
- * state.formData.username = 'john_doe';
- * state.formData.gender = 'male';
- * ```
- */
+@hidden
+
+Attaches a form-values observable to a target object property, enabling two-way binding
+between DOM form controls and the object's state.
+
+Scans the given DOM subtree for `input`, `select`, and `textarea` elements with a `name`
+attribute and creates live getters/setters on the resulting observable. Input events trigger
+automatic notifications so subscribers react to user changes.
+
+@param targetObject - The object that will receive the form-data property.
+@param propertyName - The property name under which the bound form data is stored.
+@param dom - HTMLElement or ShadowRoot containing the form controls.
+
+@example Bind a plain object to an HTML form element
+```ts
+import { formValues } from '@twobirds/microcomponents/formValues';
+
+const state = {};
+formValues(state, 'formData', document.getElementById('myForm'));
+console.log(state.formData.username); // reads <input name="username"> value
+state.formData.role = 'admin';        // writes back to the <select> control
+```
+
+@example Subscribe to form changes inside a component
+```ts
+import { DC, defineCE, formValues } from '@twobirds/microcomponents';
+
+class MyForm extends DC {
+    static assets = ['targetHtml'];
+
+    oneAssets() {
+        formValues(this, 'formData', this.target);
+        this.formData.subscribe((data) => console.log('form changed:', data));
+    }
+}
+
+defineCE('my-form', MyForm);
+```
+*/
 export function formValues(targetObject, propertyName, dom) {
     /* v8 ignore next */
     if (!isBrowser())
@@ -332,3 +342,59 @@ export function formValues(targetObject, propertyName, dom) {
         });
     });
 }
+/**
+Attaches a convenience method `formValues()` to the prototype of a microcomponent class so that
+form controls can be bound directly on the instance without importing the standalone function.
+
+This plugin also pulls in all observable methods from {@link observePlugin} — `notify()`,
+`subscribe()`, and `bind()` — so you can chain them fluently after binding form data.
+
+Call it once at module level before defining any component classes. The plugin is idempotent —
+subsequent calls are no-ops.
+
+@param Class - A constructor function whose prototype chain includes {@link Core.McBase}.
+
+@example
+```ts
+import { DC, defineCE, formValuePlugin } from '@twobirds/microcomponents';
+
+formValuePlugin(DC);
+
+class CheckoutForm extends DC {
+    static assets = ['targetHtml'];
+
+    oneAssets() {
+        this
+            .formValues(this.target, 'formData')
+            .subscribe('formData', (data) => console.log(data))
+            .bind('formData', this.target);
+    }
+}
+
+defineCE('checkout-form', CheckoutForm);
+```
+*/
+export function formValuePlugin(Class) {
+    const McBaseProto = Object.getPrototypeOf(Class.prototype);
+    if (!Object.hasOwn(McBaseProto, 'formValues')) {
+        Object.assign(McBaseProto, {
+            /**
+* Bind all named form controls inside a DOM subtree to an observable property on this instance.
+* Ensures the property becomes observable and stays in sync with input changes.
+* @param target - HTMLElement or ShadowRoot containing the form controls.
+* @param propName - The name of the property that will hold the bound form data.
+* @returns This instance for chaining.
+
+@example
+```ts
+this.formValues(this.target, 'formData');
+// now this.formData.username reflects <input name="username"> live
+```
+            */
+            formValues: function (target, propName) {
+                formValues(this, propName, target);
+                return this; // chainable
+            },
+        });
+    }
+}

package/dist/state/index.d.ts

@@ -0,0 +1,7 @@
+/**
+@module State
+*/
+export { observe, observePlugin, isAlreadyObserved } from './observables.js';
+export type { Observable, Callback, Observed, ObservedKey, Unobserved } from './observables.js';
+export { formValues, formValuePlugin } from './formValues.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/state/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA;;EAEE;AACF,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAChG,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/state/index.js

@@ -0,0 +1,5 @@
+/**
+@module State
+*/
+export { observe, observePlugin, isAlreadyObserved } from './observables.js';
+export { formValues, formValuePlugin } from './formValues.js';