@cntwg/html-helper 0.0.21 → 0.0.23

package/lib/html-ctrls/fields.js

@@ -1,4 +1,4 @@
-// [v0.1.013-20240705]
+// [v0.1.017-20241119]
 
 // === module init block ===
 
@@ -12,7 +12,7 @@ const {
   isHTMLElement, createNewHtmlElement,
   valueToIDString, valueToClassList,
   readAsAttrValue,
-  showHtmlElement, hideHtmlElement,
+  showHTMLElement, hideHTMLElement,
 } = require('../html-helper-lib.js');
 
 const {
@@ -27,8 +27,22 @@ const lpAllowedValues = new Map([
   [ 'default', 0 ],
 ]);
 
-function getInputFieldTypeDescr(value){
-  let fldType = readAsString(value, true);
+/**
+ * @typedef {Object} ifcTypeDesc
+ * @property {string} type - type
+ * @property {string} subtype - subtype
+ * @description An input field type description
+ */
+
+/**
+ * @function getInputFieldTypeDescr
+ * @param {string} value
+ * @returns {ifcTypeDesc}
+ * @inner
+ * @description Returns field description by a given type.
+ */
+function getInputFieldTypeDescr(value) {
+  let fldType = readAsString(value, { useTrim: true });
   if (fldType === '') fldType = 'default';
   let fldSubType = '';
   switch (fldType) {
@@ -44,17 +58,24 @@ function getInputFieldTypeDescr(value){
     case 'field':
     case 'default': {
       fldType = 'text';
+      fldSubType = 'field';
       break;
     }
     default: {
       fldType = '';
-      break;
     }
   };
   return { type: fldType, subtype: fldSubType };
 };
 
-function getLabelPositionID(value){
+/**
+ * @function getLabelPositionID
+ * @param {string} value
+ * @returns {number}
+ * @inner
+ * @description Returns label position ID by its name.
+ */
+function getLabelPositionID(value) {
   let key = readAsString(value, true);
   if (!lpAllowedValues.has(key)) key = 'default';
   return lpAllowedValues.get(key);
@@ -75,32 +96,53 @@ function getLabelPositionID(value){
  */
 
 /**
- * @description This class implements an instance of an input field element
+ * @classdesc This class implements an interface of an input field element
  */
 class THtmlInputField {
-  #_host = null;
-  #_label = null;
-  #_field = null;
+  /** @property {?HTMLElement} */
+  #_host;// = null;
+  /** @property {?HTMLElement} */
+  #_label;// = null;
+  /** @property {?HTMLElement} */
+  #_field;// = null;
   #_id = '';
   #_value = '';
+  /** @property {object} */
   #_options = null;
-  #_status = null;
-  #_events = null;
+  /**
+   * @typedef {Object} statIFCtrl
+   * @property {string} fldType
+   * @property {string} fldSubType
+   * @property {boolean} isReadOnly
+   * @property {boolean} isModified
+   * @inner
+   * @description A controller status
+   */
+  /** @property {statIFCtrl} */
+  #_status;// = null;
+  /** @property {Map} */
+  #_events;// = null;
 
   /**
-   * @param {ID_STRING} name - <*reserved*>
-   * @param {object} eholds
-   * @param {HTMLElement} eholds.host
-   * @param {HTMLElement} eholds.label
-   * @param {HTMLElement} eholds.field
+   * @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.
+   */
+
+  /**
+   * @param {string} name - <*reserved*>
+   * @param {ifcElementsDesc} eholds - elements set
    * @param {object} [opt]
-   * @param {ID_STRING} [opt.idPref]
-   * @param {(string|array)} [opt.baseClassID]
+   * @param {string} [opt.idPref]
+   * @param {(string|string[])} [opt.baseClassID]
    * @param {string} [opt.hint]
-   * @param {object} [opt.type]
-   * @param {bool} [opt.readonly=true]
+   * @param {string} [opt.type]
+   * @param {boolean} [opt.readonly=true]
+   * @description Creates an instance of an input field element
    */
-  constructor(name, eholds, opt){
+  constructor(name, eholds, opt) {
     // load elements
     const _eholds = isPlainObject(eholds) ? eholds : {};
     let { host, label, field } = _eholds;
@@ -126,6 +168,7 @@ class THtmlInputField {
     // save options
     this.#_options = _options;
     // save status
+    /** @type {statIFCtrl} */
     this.#_status = {
       fldType,
       fldSubType,
@@ -142,31 +185,39 @@ class THtmlInputField {
   }
 
   /**
-   * @property {bool}
+   * @property {boolean}
    * @readonly
+   * @description Indicates whether element value was modified.
    */
-  get isModified(){
+  get isModified() {
     return this.#_status.isModified;
   }
 
   /**
+   * @since v0.0.23
    * @property {string}
+   * @readonly
+   * @description Returns an input element origin type.
    */
-  get value(){
+  get type() {
+    return this.#_status.fldType;
+  }
+
+  /**
+   * @property {string}
+   * @fires THtmlInputField#value-empty
+   * @description Containes an element value.
+   */
+  get value() {
     const field = this.#_field;
-    let result = '';
-    if (field) {
-      const { fldType } = this.#_status;
-      result = fldType === 'checkbox' ?  field.checked : field.value;
-    };
+    const result = this.type === 'checkbox' ?  field.checked : field.value;
     return result;
   }
 
-  set value(value){
+  set value(value) {
     const field = this.#_field;
     if (value !== undefined) {
-      const { fldType } = this.#_status;
-      if (fldType === 'checkbox') {
+      if (this.type === 'checkbox') {
         field.checked = value;
         this.#_status.isModified = false;
       } else {
@@ -190,9 +241,9 @@ class THtmlInputField {
   }
 
   /**
-   * @param {ID_STRING}
-   * @param {...any}
-   * @returns {none}
+   * @param {string} name - event name
+   * @param {...any} args
+   * @returns {void}
    * @private
    * @see triggerEventHandler
    */
@@ -201,8 +252,8 @@ class THtmlInputField {
   };
 
   /**
-   * @param {object}
-   * @returns {none}
+   * @param {object} e
+   * @returns {void}
    * @private
    * @fires THtmlInputField#value-changed
    */
@@ -213,8 +264,8 @@ class THtmlInputField {
     // // TODO:
     /**
      * @event THtmlInputField#value-changed
-     * @type {object}
-     * @property {ID_STRING} type
+     * @type {Object}
+     * @property {string} type - event type
      * @property {object} target
      */
     this.#_triggerEvent('value-changed', {
@@ -224,8 +275,8 @@ class THtmlInputField {
   };
 
   /**
-   * @param {object}
-   * @returns {none}
+   * @param {object} e
+   * @returns {void}
    * @private
    * @fires THtmlInputField#value-empty
    */
@@ -238,8 +289,8 @@ class THtmlInputField {
     if (target.value === '') {
       /**
        * @event THtmlInputField#value-empty
-       * @type {object}
-       * @property {ID_STRING} type
+       * @type {Object}
+       * @property {string} type - event type
        * @property {object} target
        */
       this.#_triggerEvent('value-empty', {
@@ -250,8 +301,8 @@ class THtmlInputField {
   };
 
   /**
-   * @param {object}
-   * @returns {none}
+   * @param {object} e
+   * @returns {void}
    * @private
    */
   #_switchFieldStatusOnBlur = (e) => {
@@ -261,11 +312,11 @@ class THtmlInputField {
   };
 
   /**
-   * @param {HTMLElement}
-   * @returns {bool}
+   * @param {HTMLElement} target - target element
+   * @returns {boolean}
    * @description Tries to attach an element to a given target.
    */
-  attachTo(target){
+  attachTo(target) {
     const host = this.#_host;
     let result = false;
     if (
@@ -279,58 +330,53 @@ class THtmlInputField {
   }
 
   /**
-   * @param {none}
-   * @returns {bool}
+   * @returns {boolean}
    * @description Checks if a value of an element is not set.
    */
-  isEmpty(){
+  isEmpty() {
     return isEmptyString(this.value);
   }
 
   /**
-   * @param {none}
-   * @returns {bool}
+   * @returns {boolean}
    * @description Checks if a value of an element is set.
    */
-  isNotEmpty(){
+  isNotEmpty() {
     return isNotEmptyString(this.value);
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Shows an element.
    */
-  show(){
-    showHtmlElement(this.#_host);
+  show() {
+    showHTMLElement(this.#_host);
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Hides an element.
    */
-  hide(){
-    hideHtmlElement(this.#_host);
+  hide() {
+    hideHTMLElement(this.#_host);
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description not implemented yet.
    */
-  clear(){
+  clear() {
     // // TODO:
   }
 
   /**
-   * @param {ID_STRING}
-   * @param {object}
+   * @param {string} name - <*reserved*>
+   * @param {object} opt
    * @returns {?THtmlInputField}
    * @static
    * @description Creates a new element.
    */
-  static create(name, opt){
+  static create(name, opt) {
     const eholds = THtmlInputField.createElement(name, opt, true);
     const { field } = eholds;
     return (
@@ -341,23 +387,23 @@ class THtmlInputField {
   }
 
   /**
-   * @param {ID_STRING}
+   * @param {string} name
    * @param {object} [opt]
    * @param {object} [opt.host]
-   * @param {ID_STRING} [opt.idPref]
+   * @param {string} [opt.idPref]
    * @param {object} [opt.label]
    * @param {object} [opt.labelPosition]
-   * @param {bool} [opt.useDelim]
+   * @param {boolean} [opt.useDelim]
    * @param {object} [opt.baseClassID]
    * @param {string} [opt.hint]
    * @param {object} [opt.type]
-   * @param {bool} [opt.readonly]
-   * @param {bool} [doRetChild=false]
-   * @returns {(HTMLElement|object)}
+   * @param {boolean} [opt.readonly]
+   * @param {boolean} [doRetChild=false]
+   * @returns {(HTMLElement|ifcElementsDesc)}
    * @static
    * @description Creates a new elements.
    */
-  static createElement(name, opt, doRetChild){
+  static createElement(name, opt, doRetChild) {
     const id = valueToIDString(name);
     const _options = isPlainObject(opt) ? opt : {};
     let fldSubType = '';
@@ -448,12 +494,12 @@ class THtmlInputField {
   }
 
   /**
-   * @param {ID_STRING}
-   * @param {func}
-   * @returns {none}
+   * @param {string} name - event name
+   * @param {func} evnt - callback function
+   * @returns {void}
    * @description Sets a callback function to handle event.
    */
-  on(name, evnt){
+  on(name, evnt) {
     pushEventHandler(this.#_events, name, evnt);
   }