@cntwg/html-helper 0.0.25 → 0.0.27

package/lib/html-ctrls/fields.js

@@ -1,4 +1,4 @@
-// [v0.1.019-20250416]
+// [v0.1.023-20250827]
 
 // === module init block ===
 
@@ -19,7 +19,7 @@ const {
   pushEventHandler, triggerEventHandler,
 } = require('./mod-hfunc.js');
 
-// === module extra block (helper functions) ===
+// === module inner block ===
 
 const lpAllowedValues = new Map([
   [ 'before', 0 ],
@@ -28,18 +28,18 @@ const lpAllowedValues = new Map([
 ]);
 
 /**
+ * An input field type descriptor
  * @typedef {Object} ifcTypeDesc
- * @property {string} type - type
- * @property {string} subtype - subtype
- * @description An input field type description
+ * @property {string} type - field general type
+ * @property {string} subtype - field sub-type
  */
 
 /**
+ * Returns field description by a given type.
  * @function getInputFieldTypeDescr
- * @param {string} value
+ * @param {string} value - field type
  * @returns {ifcTypeDesc}
  * @inner
- * @description Returns field description by a given type.
  */
 function getInputFieldTypeDescr(value) {
   let fldType = readAsString(value, { useTrim: true });
@@ -69,14 +69,14 @@ function getInputFieldTypeDescr(value) {
 };
 
 /**
+ * Returns label position ID by its name.
  * @function getLabelPositionID
- * @param {string} value
+ * @param {string} value - label position identifier
  * @returns {number}
  * @inner
- * @description Returns label position ID by its name.
  */
 function getLabelPositionID(value) {
-  let key = readAsString(value, true);
+  let key = readAsString(value, { useTrim: true });
   if (!lpAllowedValues.has(key)) key = 'default';
   return lpAllowedValues.get(key);
 };
@@ -96,35 +96,35 @@ function getLabelPositionID(value) {
  */
 
 /**
+ * An options set for create ifc
  * @typedef {Object} OPT_ifcdesc
- * @property {object} [host]
+ * @property {HTMLElement} [host] - host element
  * @property {string} [idPref]
- * @property {object} [label]
+ * @property {string} [label] - text of a label
  * @property {object} [labelPosition]
  * @property {boolean} [useDelim]
  * @property {object} [baseClassID]
- * @property {string} [hint]
- * @property {object} [type]
+ * @property {string} [hint] - hint to show when empty
+ * @property {string} [type] - field type
  * @property {boolean} [readonly] - mode flag
- * @description An options set for create ifc
  */
 
 /**
+ * An options set for `THtmlInputField`-class
  * @typedef {Object} OPT_ifcsett
  * @property {string} [idPref]
  * @property {(string|string[])} [baseClassID]
- * @property {string} [hint]
- * @property {string} [type]
+ * @property {string} [hint] - hint to show when empty
+ * @property {string} [type] - field type
  * @property {boolean} [readonly=true] - mode flag
- * @description An options set for `THtmlInputField`-class
  */
 
 /**
+ * A descriptor for an input field elements set.
  * @typedef {Object} ifcElementsDesc
  * @property {HTMLElement} host - host element
  * @property {HTMLElement} label - label element
  * @property {HTMLElement} field - field element
- * @description A description for input field elements set.
  */
 
 /**
@@ -142,13 +142,13 @@ class THtmlInputField {
   /** @type {OPT_ifcsett} */
   #_options = null;
   /**
+   * A controller status
    * @typedef {Object} statIFCtrl
-   * @property {string} fldType
-   * @property {string} fldSubType
-   * @property {boolean} isReadOnly
-   * @property {boolean} isModified
+   * @property {string} fldType - field general type
+   * @property {string} fldSubType - field sub-type
+   * @property {boolean} isReadOnly - mode flag
+   * @property {boolean} isModified - indicates whether any changes was made
    * @inner
-   * @description A controller status
    */
   /** @type {statIFCtrl} */
   #_status;// = null;
@@ -156,10 +156,10 @@ class THtmlInputField {
   #_events;// = null;
 
   /**
+   * Creates an instance of an input field element
    * @param {string} name - <*reserved*>
    * @param {ifcElementsDesc} eholds - elements set
    * @param {OPT_ifcsett} [opt] - options
-   * @description Creates an instance of an input field element
    */
   constructor(name, eholds, opt) {
     // load elements
@@ -271,7 +271,7 @@ class THtmlInputField {
   };
 
   /**
-   * @param {object} e
+   * @param {object} e - event
    * @returns {void}
    * @private
    * @fires THtmlInputField#value-changed
@@ -294,7 +294,7 @@ class THtmlInputField {
   };
 
   /**
-   * @param {object} e
+   * @param {object} e - event
    * @returns {void}
    * @private
    * @fires THtmlInputField#value-empty
@@ -320,7 +320,7 @@ class THtmlInputField {
   };
 
   /**
-   * @param {object} e
+   * @param {object} e - event
    * @returns {void}
    * @private
    */
@@ -331,9 +331,9 @@ class THtmlInputField {
   };
 
   /**
+   * Tries to attach an element to a given target.
    * @param {HTMLElement} target - target element
    * @returns {boolean}
-   * @description Tries to attach an element to a given target.
    */
   attachTo(target) {
     const host = this.#_host;
@@ -349,32 +349,32 @@ class THtmlInputField {
   }
 
   /**
+   * Checks if a value of an element is not set.
    * @returns {boolean}
-   * @description Checks if a value of an element is not set.
    */
   isEmpty() {
     return isEmptyString(this.value);
   }
 
   /**
+   * Checks if a value of an element is set.
    * @returns {boolean}
-   * @description Checks if a value of an element is set.
    */
   isNotEmpty() {
     return isNotEmptyString(this.value);
   }
 
   /**
+   * Shows an element.
    * @returns {void}
-   * @description Shows an element.
    */
   show() {
     showHTMLElement(this.#_host);
   }
 
   /**
+   * Hides an element.
    * @returns {void}
-   * @description Hides an element.
    */
   hide() {
     hideHTMLElement(this.#_host);
@@ -382,18 +382,18 @@ class THtmlInputField {
 
   /**
    * @returns {void}
-   * @description not implemented yet.
+   * @todo not implemented yet.
    */
   clear() {
     // // TODO:
   }
 
   /**
+   * Creates a new instance.
    * @param {string} name - <*reserved*>
    * @param {OPT_ifcdesc} opt - options
    * @returns {?THtmlInputField}
    * @static
-   * @description Creates a new element.
    */
   static create(name, opt) {
     const eholds = THtmlInputField.createElement(name, opt, true);
@@ -406,12 +406,12 @@ class THtmlInputField {
   }
 
   /**
+   * Creates a new elements.
    * @param {string} name
    * @param {OPT_ifcdesc} [opt] - options
    * @param {boolean} [doRetChild=false] - mode flag
    * @returns {(HTMLElement|ifcElementsDesc)}
    * @static
-   * @description Creates a new elements.
    */
   static createElement(name, opt, doRetChild) {
     const id = valueToIDString(name);
@@ -441,18 +441,18 @@ class THtmlInputField {
     bcidLabel = valueToClassList(bcidLabel);
     bcidField = valueToClassList(bcidField);
     idPref = valueToIDString(idPref);
-    hint = readAsString(hint, true);
+    hint = readAsString(hint, { useTrim: true });
     ({ type: fldType, subtype: fldSubType } = getInputFieldTypeDescr(fldType));
     if (fldSubType === 'switch') bcidField.push('switch');
     labelPosition = getLabelPositionID(labelPosition);
     if (typeof useDelim !== 'boolean') useDelim = true;
-    label = readAsString(label, true);
+    label = readAsString(label, { useTrim: true });
     if (label !== '') label = `${label}${useDelim ? ':' : ''}`;
     isReadOnly = readAsBool(isReadOnly, true);
     let fldID = idPref === '' ? id : `${idPref}-${id}`;
     if (!isHTMLElement(host)) {
       host = createNewHTMLElement('div', {
-        class: bcidHost,
+        classNames: bcidHost,
       });
     };
     let lblHolder = null;
@@ -466,7 +466,7 @@ class THtmlInputField {
           attr: {
             for: fldID,
           },
-          class: bcidLabel,
+          classNames: bcidLabel,
         });
       };
       fldHolder = host.querySelector(`input#${fldID}`);
@@ -477,7 +477,7 @@ class THtmlInputField {
             type: fldType,
             placeholder: hint,
           },
-          class: bcidField,
+          classNames: bcidField,
         });
       };
       if (fldHolder) {
@@ -505,10 +505,10 @@ class THtmlInputField {
   }
 
   /**
+   * Sets a callback function to handle event.
    * @param {string} name - event name
    * @param {func} evnt - callback function
    * @returns {void}
-   * @description Sets a callback function to handle event.
    */
   on(name, evnt) {
     pushEventHandler(this.#_events, name, evnt);