@cntwg/html-helper 0.0.24 → 0.0.26

package/lib/html-ctrls/list.js

@@ -1,13 +1,17 @@
-// [v0.1.067-20241119]
+// [v0.1.070-20250504]
 
 // === module init block ===
 
 const {
   readAsNumber,
   isPlainObject,
-  TItemsListEx,
+  //TItemsListEx,
 } = require('@ygracs/bsfoc-lib-js');
 
+const {
+  TItemsListEx,
+} = require('@ygracs/lists-lib-js');
+
 const {
   isHTMLElement, isSelectedHTMLElement, isHiddenHTMLElement,
   showHTMLElement, hideHTMLElement,
@@ -85,15 +89,23 @@ const ILC_SMODE_CTRL = 2;
  * (* class definitions *)
  */
 
+/**
+ * @typedef {Object} OPT_hlconsett
+ * @property {boolean} [autoHideNewItems=false]
+ * @property {boolean} [markCurrentItem=false]
+ * @property {(string|string[])} [itemBaseClassID]
+ * @description An options set for `THtmlItemsListContainer`-class
+ */
+
 /**
  * @classdesc This class implements an interfaco for a list container
  */
 class THtmlItemsListContainer {
-  /** @property {?HTMLElement} */
+  /** @type {?HTMLElement} */
   #_host;
-  /** @property {TItemsListEx} */
+  /** @type {TItemsListEx} */
   #_items;
-  /** @property {object} */
+  /** @type {OPT_hlconsett} */
   #_options;// = null;
   /**
    * @typedef {Object} statILCont
@@ -102,15 +114,12 @@ class THtmlItemsListContainer {
    * @inner
    * @description A container status
    */
-  /** @property {statILCont} */
+  /** @type {statILCont} */
   #_status;
 
   /**
    * @param {HTMLElement} host
-   * @param {object} [opt]
-   * @param {boolean} [opt.autoHideNewItems=false]
-   * @param {boolean} [opt.markCurrentItem=false]
-   * @param {(string|string[])} [opt.itemBaseClassID]
+   * @param {OPT_hlconsett} [opt] - options
    * @description Creates an instance of a list container
    */
   constructor(host, opt) {
@@ -120,6 +129,7 @@ class THtmlItemsListContainer {
     const _items = new TItemsListEx();
     this.#_items = _items;
     // load options
+    /** @type {OPT_hlconsett} */
     const _options = isPlainObject(opt) ? opt : {};
     let {
       autoHideNewItems,
@@ -146,63 +156,63 @@ class THtmlItemsListContainer {
   }
 
   /**
-   * @property {number}
+   * Contains a Qty of an elements
+   * @type {number}
    * @readonly
-   * @description Contains a Qty of an elements
    */
   get count() {
     return this.#_items.count;
   }
 
   /**
-   * @property {number}
+   * Contains an of the current element
+   * @type {number}
    * @readonly
-   * @description Contains an of the current element
    */
   get curIndex() {
     return this.#_items.curIndex;
   }
 
   /**
-   * @property {number}
+   * Returns a minimum value of an index
+   * @type {number}
    * @readonly
-   * @description Returns a minimum value of an index
    */
   get minIndex() {
     return this.#_items.minIndex;
   }
 
   /**
-   * @property {number}
+   * Returns a maximum value of an index
+   * @type {number}
    * @readonly
-   * @description Returns a maximum value of an index
    */
   get maxIndex() {
     return this.#_items.maxIndex;
   }
 
   /**
-   * @property {number}
+   * Returns a value of a previous index
+   * @type {number}
    * @readonly
-   * @description Returns a value of a previous index
    */
   get prevIndex() {
     return this.#_items.prevIndex;
   }
 
   /**
-   * @property {number}
+   * Returns a value of a next index
+   * @type {number}
    * @readonly
-   * @description Returns a value of a next index
    */
   get nextIndex() {
     return this.#_items.nextIndex;
   }
 
   /**
-   * @property {?HTMLElement}
+   * Returns an element in the current index
+   * @type {?HTMLElement}
    * @readonly
-   * @description Returns an element in the current index
    */
   get curItem() {
     const item = this.#_items.curItem;
@@ -471,19 +481,31 @@ class THtmlItemsListContainer {
 
 };
 
+/**
+ * @typedef {Object} OPT_hlctlsett
+ * @property {boolean} [autoHideNewItems=false]
+ * @property {boolean} [markCurrentItem=false]
+ * @property {(string|string[])} [itemBaseClassID]
+ * @property {boolean} [showStubsIfEmpty=false]
+ * @property {boolean} [allowGroupSelection=false]
+ * @property {boolean} [allowSelectionLocks=false]
+ * @property {object} [stubs]
+ * @description An options set for `THtmlItemsListController`-class
+ */
+
 /**
  * @augments THtmlItemsListContainer
  * @classdesc This class enhanced a capabilities implemented
  *            in the `THtmlItemsListContainer` class
  */
 class THtmlItemsListController extends THtmlItemsListContainer {
-  /** @property {?HTMLElement} */
+  /** @type {?HTMLElement} */
   #_host;
-  /** @property {THtmlStubItemsSet} */
+  /** @type {THtmlStubItemsSet} */
   #_stubs;
-  /** @property {Set} */
+  /** @type {Set<HTMLElement>} */
   #_selects;
-  /** @property {object} */
+  /** @property {OPT_hlctlsett} */
   #_options;// = null;
   /**
    * @typedef {Object} statILCtrl
@@ -499,19 +521,12 @@ class THtmlItemsListController extends THtmlItemsListContainer {
    */
   /** @property {statILCtrl} */
   #_status;
-  /** @property {Map} */
+  /** @property {Map<string, Function>} */
   #_events;
 
   /**
    * @param {?HTMLElement} host
-   * @param {object} [opt]
-   * @param {boolean} [opt.autoHideNewItems=false]
-   * @param {boolean} [opt.markCurrentItem=false]
-   * @param {(string|string[])} [opt.itemBaseClassID]
-   * @param {boolean} [opt.showStubsIfEmpty=false]
-   * @param {boolean} [opt.allowGroupSelection=false]
-   * @param {boolean} [opt.allowSelectionLocks=false]
-   * @param {object} [opt.stubs]
+   * @param {OPT_hlctlsett} [opt]
    * @description Creates a new instance of the class.
    */
   constructor(host, opt) {
@@ -573,7 +588,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
-   * @param {object} e
+   * @param {object} e - event
    * @returns {void}
    * @private
    */
@@ -590,8 +605,8 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     //console.log('CHECK: e => ditail:['+e.detail+']');
     //console.log('CHECK: e => phase:['+eventPhase+']');
     const onClickNum = readAsNumber(e.detail, 0);
-    const _status = this.#_status;
-    const { isSelectionLocked, catchEventOnHost } = _status;
+    const host = this.#_host;
+    const { isSelectionLocked, catchEventOnHost } = this.#_status;
     let curItem = null;
     switch (eventPhase) {
       //* // NOTE: currently on eventPhase = 2 and 3
@@ -599,7 +614,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
         /**/// capturing stage
       case 2: {
         /**/// target stage
-        if (target !== this.#_host) curItem = target;
+        if (target !== host) curItem = target;
         break;
       }
       case 3: {
@@ -607,9 +622,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
         curItem = catchEventOnHost ? target : currentTarget;
         break;
       }
-      default: {
-        break;
-      }
+      default: {}
     };
     if (
       !isSelectionLocked
@@ -617,7 +630,19 @@ class THtmlItemsListController extends THtmlItemsListContainer {
       && (onClickNum === 0 || onClickNum === 1)
       && !curItem.classList.contains(CSS_CLASS_DISABLED)
     ) {
-      //console.log('CHECK: e => tag:['+curItem.tagName+']');
+      //console.log(`CHECK: e => tag:[${curItem.tagName}]`);
+      if (host) {
+        // find an actual list element in case when some inner element was clicking
+        let tmpItem = curItem;
+        while (tmpItem) {
+          //console.log(`CHECK: e => target.tag:[${tmpItem.tagName}]`);
+          tmpItem = tmpItem.parentElement;
+          //console.log(`CHECK: e => next.tag:[${tmpItem.tagName}]`);
+          if (tmpItem === host) break;
+          if (tmpItem) curItem = tmpItem;
+        };
+      };
+      //console.log(`CHECK: e => tag:[${curItem.tagName}]`);
       this.#_selectItemEx(curItem, {
         ctrlKey: ctrlKey,
         shiftKey: shiftKey,
@@ -638,9 +663,9 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   };
 
   /**
-   * @property {HTMLElement[]}
+   * Returns a list of the selected elements
+   * @type {HTMLElement[]}
    * @readonly
-   * @description Returns a list of the selected elements
    */
   get SelectedItems() {
     const _selects = this.#_selects;
@@ -653,18 +678,18 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
-   * @property {THtmlStubItemsSet}
+   * Returns a `THtmlStubItemsSet` instance
+   * @type {THtmlStubItemsSet}
    * @readonly
-   * @description Returns a `THtmlStubItemsSet` instance
    */
   get StubItems() {
     return this.#_stubs;
   }
 
   /**
-   * @property {boolean}
+   * Indicates whether a selection is locked
+   * @type {boolean}
    * @readonly
-   * @description Indicates whether a selection is locked
    */
   get isSelectionLocked() {
     return this.#_status.isSelectionLocked;

package/lib/html-ctrls/lists-btn.js

@@ -1,4 +1,4 @@
-// [v0.1.052-20241119]
+// [v0.1.054-20250509]
 
 // === module init block ===
 
@@ -48,9 +48,9 @@ const BTS_DEF_GROUP_NAME = 'all';
  *            A set provide a buttons: <next>, <previous>, <first> and <last>.
  */
 class THtmlListButtonsController {
-  /** @property {THtmlButtonsSet} */
+  /** @type {THtmlButtonsSet} */
   #_btnSet;
-  /** @property {Map} */
+  /** @type {Map<string, Function>} */
   #_events;
 
   /**
@@ -67,8 +67,6 @@ class THtmlListButtonsController {
    * @description Creates an instance of a buttons set.
    */
   constructor(opt) {
-    // load options
-    const _options = isPlainObject(opt) ? opt : {};
     // load controls
     /** @type {listButtonsSetDesc} */
     let {
@@ -76,7 +74,7 @@ class THtmlListButtonsController {
       btnPrev,
       btnNext,
       btnLast,
-    } = _options;
+    } = isPlainObject(opt) ? opt : {};
     if (!isHTMLButton(btnFirst)) btnFirst = null;
     if (!isHTMLButton(btnPrev)) btnPrev = null;
     if (!isHTMLButton(btnNext)) btnNext = null;

package/lib/html-ctrls/lists-stubs.js

@@ -1,4 +1,4 @@
-// [v0.1.045-20241119]
+// [v0.1.049-20250505]
 
 // === module init block ===
 
@@ -26,32 +26,47 @@ const {
  * (* class definitions *)
  */
 
+/**
+ * @typedef {Object} OPT_ldstubs
+ * @property {string} [defaultItem] - <*deprecated*> a default element name
+ * @property {boolean} [useClear=true] - to clear before load an elements
+ * @property {boolean} [force=false] - run in a force mode
+ * @description A settings to load a stub-elements.
+ * @todo [since v0.0.26] `defaultItem`-option deprecated
+ */
+
+/**
+ * @typedef {Object} OBJ_stubEList
+ * @property {Array} items - array of `name`-`element` pairs
+ * @property {string} [defaultItem] - a default element name
+ * @description A stub-elements description list.
+ */
+
+/**
+ * @typedef {Object} OPT_stubconsett
+ * @property {(any[])} items - array of `name`-`element` pairs
+ * @property {string} [defaultItem] - a default element name
+ * @property {boolean} [force=false] - run in a force mode
+ * @description A an options set for a `THtmlStubItemsSet`-class constructor
+ */
+
 /**
  * @classdesc This class implements an interface of a stub-items set
  */
 class THtmlStubItemsSet {
-  /** @property {?HTMLElement} */
+  /** @type {?HTMLElement} */
   #_host;
-  /** @property {Map} */
+  /** @type {Map<string, HTMLElement>} */
   #_items;
-  /** @property {string} */
+  /** @type {string} */
   #_defItem;
   #_shownItem = null;
 
   /**
-   * @typedef {Object} OBJ_stubEList
-   * @property {Array} items - array of `name`-`element` pairs
-   * @property {string} [defaultItem] - a default element name
-   * @description A stub-elements description list.
-   */
-
-  /**
-   * @param {HTMLElement} host
-   * @param {(array|object|OBJ_stubEList)} opt
-   * @param {(array|object)} opt.items
-   * @param {string} opt.defaultItem
-   * @param {boolean} opt.force - <*deprecated (since: v0.0.23)*>
+   * @param {HTMLElement} host - host element
+   * @param {(array|OPT_stubconsett|OBJ_stubEList)} [opt] - options
    * @description Creates an instance of a stub-items set
+   * @todo [since v0.0.26] use of an `array`-type as a value of an `opt` is deprecated
    */
   constructor(host, opt) {
     this.#_host = isHTMLElement(host) ? host : null;
@@ -59,15 +74,21 @@ class THtmlStubItemsSet {
     this.#_defItem = '';
     this.#_shownItem = null;
     if (isObject(opt)) {
+      /** @type {(OPT_stubconsett|OBJ_stubEList)} */
       const obj = isArray(opt) ? { items: opt } : opt;
       const { items, defaultItem, force } = obj;
-      this.loadItems(items, { defaultItem, force });
+      this.loadItems({
+        items,
+        defaultItem,
+      }, {
+        force,
+      });
     };
   }
 
   /**
-   * @property {string}
-   * @description Defines a default element name
+   * Defines a default element name
+   * @type {string}
    */
   get defItem() {
     return this.#_defItem;
@@ -78,9 +99,9 @@ class THtmlStubItemsSet {
   }
 
   /**
-   * @property {number}
+   * Contains a Qty of an elements
+   * @type {number}
    * @readonly
-   * @description Contains a Qty of an elements
    */
   get count() {
     return this.#_items.size;
@@ -229,40 +250,33 @@ class THtmlStubItemsSet {
   }
 
   /**
-   * @typedef {Object} OPT_ldstubs
-   * @property {string} [defaultItem] - a default element name
-   * @property {boolean} [useClear=true] - to clear before load an elements
-   * @property {boolean} [force=false] - run in a force mode
-   * @description A settings to load stub-elements.
-   */
-
-  /**
-   * @param {(Array|OBJ_stubEList)} list - an array of entries or special object
+   * @param {(Array|OBJ_stubEList)} data - an array of entries or special object
    * @param {(boolean|OPT_ldstubs)} [opt] - an options
    * @returns {number}
    * @description Adds an items to an instance members.
+   * @todo [since 0.0.25] deprecate use of `opt` as `boolean`
+   * @todo [since v0.0.26] for `OPT_ldstubs` a `defaultItem`-option deprecated
    */
-  loadItems(list, opt) {
-    let _options = opt;
-    if (typeof _options === 'boolean') _options = { useClear: _options };
-    if (!isPlainObject(_options)) _options = {};
-    /** @type {OPT_ldstubs} */
+  loadItems(data, opt) {
+    /** @type {OBJ_stubEList} */
     let {
+      items,
       defaultItem,
+    } = isPlainObject(data) ? data : { items: data };
+    /** @type {OPT_ldstubs} */
+    let _options = isPlainObject(opt) ? opt : { useClear: opt };
+    let {
       useClear,
       force,
     } = _options;
     if (typeof useClear !== 'boolean') useClear = true;
     if (typeof force !== 'boolean') force = false;
-    let _list = list;
-    if (isPlainObject(_list)) {
-      ({ items: _list, defaultItem } = _list);
-    };
+    if (defaultItem === undefined) defaultItem = _options.defaultItem;  /* deprecated */
     const setDefs = defaultItem !== undefined;
     let count = 0;
-    if (isArray(_list)) {
+    if (isArray(items)) {
       if (useClear) this.clear();
-      _list.forEach((obj) => {
+      items.forEach((obj) => {
         if (isArray(obj)) {
           const [ name, item ] = obj;
           if (this.addItem(name, item, force)) count++;