@cntwg/html-ctrls-lists 0.0.32 → 0.0.33

package/lib/{list.js → list-ctrl.js}

@@ -1,4 +1,4 @@
-// [v0.1.088-20260505]
+// [v0.2.091-20260510]
 
 // === module init block ===
 
@@ -8,19 +8,17 @@ const {
 } = require('@ygracs/bsfoc-lib-js');
 
 const {
-  TItemsListEx,
-} = require('@ygracs/lists-lib-js');
-
-const {
-  isHTMLElement, isSelectedHTMLElement, isHiddenHTMLElement,
+  isHTMLElement,
   showHTMLElement, hideHTMLElement,
   selectHTMLElement, unselectHTMLElement,
-  markHTMLElementAsCurrent, unmarkCurrentHTMLElement,
-  readAsAttrValue, valueToClassList,
   eventHelper, // [!] not oficialy exported yet
   CSS_CLASS_STRING,
 } = require('@cntwg/html-helper');
 
+const {
+  THtmlItemsListContainer,
+} = require('./list-cont');
+
 const {
   THtmlStubItemsSet,
   // * import types definitions *
@@ -37,529 +35,24 @@ const {
   CSS_CLASS_DISABLED,
 } = CSS_CLASS_STRING;
 
-/**
- * @typedef {Object} ISearchListElementResultOnFail
- * @property {number} index - element index
- * @property {null} item - found element
- */
-
-/**
- * @typedef {Object} ISearchListElementResultOnSuccess
- * @property {number} index - element index
- * @property {any} item - found element
- */
-
-/**
- * @typedef {ISearchListElementResultOnFail|ISearchListElementResultOnSuccess} ISearchListElementResult
- */
-
-/**
- * Searches an element in a list by a given attributes of that element.
- * @function srchListElementByAttr
- * @param {TItemsListEx} list
- * @param {string} name - target attribute name
- * @param {string} [value=""] - target attribute value
- * @returns {ISearchListElementResult}
- * @inner
- */
-function srchListElementByAttr(list, name, value = '') {
-  const _value = readAsAttrValue(value);
-  let item = null;
-  let index = -1;
-  let count = list.count;
-  let isACCEPTED = false;
-  if (count > 0 && name !== '' && _value !== null) {
-    const acceptAnyVal = _value === '';
-    for (let i = 0; i < count; i++) {
-      item = list.getItem(i);
-      if (
-        isHTMLElement(item)
-        && item.hasAttribute(name)
-        && (acceptAnyVal || item.getAttribute(name) === value)
-      ) {
-        index = i;
-        isACCEPTED = true;
-        break;
-      };
-    };
-  };
-  return isACCEPTED ? { index, item } : { index, item: null };
-};
-
 // === module main block ===
 
 const ILC_SMODE_DEF = 0;
 const ILC_SMODE_SHFT = 1;
 const ILC_SMODE_CTRL = 2;
 
-/**
- * An options set for `THtmlItemsListContainer`-class
- * @typedef {Object} OPT_hlconsett
- * @property {boolean} [autoHideNewItems=false] - indicates whether to hide
- *     a new element
- * @property {boolean} [markCurrentItem=false] - indicates whether to mark
- *     a current element
- * @property {(string|string[])} [itemBaseClassID] - contains a base class
- *     attributes applayed to each a newly added list member
- */
-
-/**
- * @classdesc This class implements an interfaco for a list container
- */
-class THtmlItemsListContainer {
-  /** @type {?HTMLElement} */
-  #_host;
-  /** @type {TItemsListEx} */
-  #_items;
-  /**
-   * A container settings
-   * @typedef {Object} THtmlItemsListContainerConfig
-   * @property {boolean} autoHideNewItems - indicates whether to hide a new element
-   * @property {boolean} markCurrentItem - indicates whether to mark a new element
-   *     as a current
-   * @property {string[]} itemBaseClassID - contains a base class attributes
-   *     applayed to each a newly added list member
-   */
-  /** @type {THtmlItemsListContainerConfig} */
-  #_config;
-  /**
-   * A container status
-   * @typedef {Object} statILCont
-   * @property {number} curIndex
-   * @property {?HTMLElement} curItem
-   * @inner
-   */
-  /** @type {statILCont} */
-  #_status;
-
-  /**
-   * Creates an instance of a list container
-   * @param {?HTMLElement} host - host element
-   * @param {OPT_hlconsett} [opt] - options
-   */
-  constructor(host, opt) {
-    // check host
-    this.#_host = isHTMLElement(host) ? host : null;
-    // init items container
-    const _items = new TItemsListEx();
-    this.#_items = _items;
-    // load options
-    /** @type {OPT_hlconsett} */
-    const _options = isPlainObject(opt) ? opt : {};
-    let {
-      autoHideNewItems,
-      markCurrentItem,
-      itemBaseClassID,
-    } = _options;
-    if (typeof autoHideNewItems !== 'boolean') {
-      autoHideNewItems = false;
-      // // TODO: next line planned to be removed
-      _options.autoHideNewItems = autoHideNewItems;
-    };
-    if (typeof markCurrentItem !== 'boolean') {
-      markCurrentItem = false;
-      // // TODO: next line planned to be removed
-      _options.markCurrentItem = markCurrentItem;
-    };
-    itemBaseClassID = valueToClassList(itemBaseClassID, true);
-    // // TODO: next line planned to be removed
-    _options.itemBaseClassID = itemBaseClassID;
-    // init status
-    /** @type {statILCont} */
-    const _status = {
-      curIndex: _items.curIndex,
-      curItem: _items.curItem,
-    };
-    this.#_status = _status;
-    // save options
-    this.#_config = {
-      autoHideNewItems,
-      markCurrentItem,
-      itemBaseClassID,
-    };
-  }
-
-  [Symbol.iterator]() {
-    let index = 0;
-    return {
-      next: () => {
-        if (index < this.count) {
-          return { done: false, value: this.getItem(index++) };
-        } else {
-          return { done: true, value: undefined };
-        };
-      },
-      return() {
-        return { done: true, value: undefined };
-      },
-    };
-  }
-
-  /**
-   * Contains a Qty of an elements
-   * @type {number}
-   * @readonly
-   */
-  get count() {
-    return this.#_items.count;
-  }
-
-  /**
-   * Contains an index of the current element
-   * @type {number}
-   * @readonly
-   */
-  get curIndex() {
-    return this.#_items.curIndex;
-  }
-
-  /**
-   * Returns a minimum value of an index
-   * @type {number}
-   * @readonly
-   */
-  get minIndex() {
-    return this.#_items.minIndex;
-  }
-
-  /**
-   * Returns a maximum value of an index
-   * @type {number}
-   * @readonly
-   */
-  get maxIndex() {
-    return this.#_items.maxIndex;
-  }
-
-  /**
-   * Returns a value of a previous index
-   * @type {number}
-   * @readonly
-   */
-  get prevIndex() {
-    return this.#_items.prevIndex;
-  }
-
-  /**
-   * Returns a value of a next index
-   * @type {number}
-   * @readonly
-   */
-  get nextIndex() {
-    return this.#_items.nextIndex;
-  }
-
-  /**
-   * Returns an element in the current index
-   * @type {?HTMLElement}
-   * @readonly
-   */
-  get curItem() {
-    const item = this.#_items.curItem;
-    return isHTMLElement(item) ? item : null;
-  }
-
-  /**
-   * Clears an instance content.
-   * @returns {void}
-   */
-  clear() {
-    this.#_items.clear();
-    const _status = this.#_status;
-    _status.curIndex = this.curIndex;
-    _status.curItem = this.curItem;
-    const _host = this.#_host;
-    if (_host) _host.innerHTML = '';
-  }
-
-  /**
-   * Checks if an instance contains no items.
-   * @returns {boolean}
-   */
-  isEmpty() {
-    return this.#_items.isEmpty();
-  }
-
-  /**
-   * Checks if an instance contains any items.
-   * @returns {boolean}
-   */
-  isNotEmpty() {
-    return this.#_items.isNotEmpty();
-  }
-
-  /**
-   * Checks if a given value is a valid index and
-   * it fits an index range within an instance.
-   * @param {number|string} value - index value
-   * @returns {boolean}
-   * @deprecated
-   * @todo \[since v0.0.31] deprecated. Use
-   *     {@link THtmlItemsListContainer.checkIndex} instead
-   */
-  chkIndex(value) {
-    return this.#_items.checkIndex(value);
-  }
-
-  /**
-   * Checks if a given value is a valid index and
-   * it fits an index range within an instance.
-   * @since 0.0.31
-   * @param {number|string} value - index value
-   * @returns {boolean}
-   */
-  checkIndex(value) {
-    return this.#_items.checkIndex(value);
-  }
-
-  /**
-   * Checks if a given value is a valid index and
-   * it fits an index range within an instance.
-   * @param {number|string} value - value to check
-   * @param {boolean} [opt=false] - defines a type of result
-   * @returns {boolean|number}
-   * @deprecated
-   * @todo \[since v0.0.31] deprecated. Use
-   *     {@link THtmlItemsListContainer.checkIndex} or
-   *     {@link THtmlItemsListContainer.tryIndex} instead
-   */
-  chkIndexEx(value, opt) {
-    return opt ? this.#_items.tryIndex(value) : this.#_items.checkIndex(value);
-  }
-
-  /**
-   * Returns an index in case a given value is a valid index value and not exceeds
-   * an index range within the list. If failed a `-1` returned
-   * @since 0.0.31
-   * @param {any} value - value to evaluate
-   * @returns {number}
-   */
-  tryIndex(value) {
-    return this.#_items.tryIndex(value);
-  }
-
-  /**
-   * Returns an index of a given element.
-   * @param {HTMLElement} item  - element to search
-   * @returns {number}
-   * @todo add 2nd param
-   * @see TItemsListEx.srchIndex
-   */
-  srchIndex(item) {
-    return isHTMLElement(item) ? this.#_items.srchIndex(item) : -1;
-  }
-
-  /**
-   * Returns an index of an element wich has an attribute
-   * with a given name and value.
-   * @param {string} name - attribute name
-   * @param {any} [value=""] - attribute value
-   * @returns {number}
-   */
-  srchIndexByAttr(name, value = '') {
-    const _name = typeof name === 'string' ? name.trim() : '';
-    const { index } = srchListElementByAttr(this.#_items, _name, value);
-    return index;
-  };
-
-  /**
-   * Returns an index of an element wich has a given ID.
-   * @param {string} value - element ID
-   * @returns {number}
-   */
-  srchIndexByID(value) {
-    const { index } = srchListElementByAttr(this.#_items, 'id', value);
-    return index;
-  };
-
-  /**
-   * Sets a current index.
-   * @param {number|string} index - element index
-   * @returns {boolean}
-   */
-  setCurIndex(index) {
-    const isSUCCEED = this.#_items.setIndex(index);
-    if (isSUCCEED) {
-      const markCurrentItem = this.#_config.markCurrentItem;
-      const _status = this.#_status;
-      if (markCurrentItem && _status.curIndex !== -1) {
-        unmarkCurrentHTMLElement(_status.curItem);
-      };
-      const item = this.getItem(index);
-      _status.curIndex = Number(index);
-      _status.curItem = item;
-      if (markCurrentItem) markHTMLElementAsCurrent(item);
-    };
-    return isSUCCEED;
-  }
-
-  /**
-   * Resets a current index.
-   * @returns {void}
-   */
-  rstCurIndex() {
-    const _status = this.#_status;
-    if (this.#_config.markCurrentItem && _status.curIndex !== -1) {
-      unmarkCurrentHTMLElement(_status.curItem);
-    };
-    this.#_items.rstIndex();
-    _status.curIndex = this.#_items.curIndex;
-    _status.curItem = this.curItem;
-  }
-
-  /**
-   * Returns an item addressed by a given index.
-   * @param {number|string} index - element index
-   * @returns {?HTMLElement}
-   */
-  getItem(index) {
-    const item = this.#_items.getItem(index);
-    return isHTMLElement(item) ? item : null;
-  }
-
-  /**
-   * Returns an item wich has an attribute with a given name and value.
-   * @param {string} name - attribute name
-   * @param {any} [value=""] - attribute value
-   * @returns {?HTMLElement}
-   */
-  getItemByAttr(name, value = '') {
-    const _name = typeof name === 'string' ? name.trim() : '';
-    const { item } = srchListElementByAttr(this.#_items, _name, value);
-    return item;
-  }
-
-  /**
-   * Returns an item wich has a given ID.
-   * @param {string} value - element ID
-   * @returns {?HTMLElement}
-   */
-  getItemByID(value) {
-    const { item } = srchListElementByAttr(this.#_items, 'id', value);
-    return item;
-  }
-
-  /**
-   * Adds an item to an instance.
-   * @param {HTMLElement} item - some element
-   * @param {boolean} [opt=false] - indicates whether to correct a current index
-   * @returns {number}
-   */
-  addItem(item, opt) {
-    const forceCI = typeof opt === 'boolean' ? opt : false;
-    const index = (
-      isHTMLElement(item)
-      ? this.#_items.addItemEx(item, false)
-      : -1
-    );
-    const isSUCCEED = index !== -1;
-    if (isSUCCEED) {
-      const { autoHideNewItems, itemBaseClassID } = this.#_config;
-      if (autoHideNewItems) hideHTMLElement(item);
-      if (itemBaseClassID.length > 0) item.classList.add(...itemBaseClassID);
-      if (forceCI) this.setCurIndex(index);
-      const _host = this.#_host;
-      if (_host) _host.append(item);
-    };
-    return isSUCCEED ? index : -1;
-  }
-
-  /**
-   * Deletes an item from an instance.
-   * @param {number|string} index - element index
-   * @param {any} [opt]
-   * @param {boolean} [optEx=true]
-   * @returns {boolean}
-   */
-  delItem(index, opt, optEx) {
-    const _items = this.#_items;
-    const item = _items.delItemEx(index, opt);
-    const isSUCCEED = item !== undefined;
-    if (isSUCCEED) {
-      if (this.#_host && isHTMLElement(item)) item.remove();
-      const doProcEx = typeof optEx === 'boolean' ? optEx : true;
-      if (doProcEx) {
-        const index = _items.curIndex;
-        if (index === -1) {
-          this.rstCurIndex();
-        } else {
-          this.setCurIndex(index);
-        };
-      };
-    };
-    return isSUCCEED;
-  }
-
-  /**
-   * Selects an item addressed by a given index.
-   * @param {number|string} index - element index
-   * @param {boolean} [opt=false] - indicates whether to correct a current index
-   * @returns {boolean}
-   */
-  selectItem(index, opt) {
-    const forceCI = typeof opt === 'boolean' ? opt : false;
-    const isSUCCEED = selectHTMLElement(this.#_items.getItem(index));
-    if (isSUCCEED && forceCI) this.setCurIndex(index);
-    return isSUCCEED;
-  }
-
-  /**
-   * Unselects an item addressed by a given index.
-   * @param {number|string} index - element index
-   * @returns {boolean}
-   */
-  unselectItem(index) {
-    return unselectHTMLElement(this.#_items.getItem(index));
-  }
-
-  /**
-   * Hides an item addressed by a given index.
-   * @param {number|string} index - element index
-   * @returns {boolean}
-   */
-  hideItem(index) {
-    return hideHTMLElement(this.#_items.getItem(index));
-  }
-
-  /**
-   * Shows an item addressed by a given index.
-   * @param {number|string} index - element index
-   * @returns {boolean}
-   */
-  showItem(index) {
-    return showHTMLElement(this.#_items.getItem(index));
-  }
-
-  /**
-   * Checks whether an item is selected.
-   * @param {number|string} index - element index
-   * @returns {boolean}
-   */
-  isSelectedItem(index) {
-    return isSelectedHTMLElement(this.#_items.getItem(index));
-  }
-
-  /**
-   * Checks whether an item is hidden.
-   * @param {number|string} index - element index
-   * @returns {boolean}
-   */
-  isHiddenItem(index) {
-    return isHiddenHTMLElement(this.#_items.getItem(index));
-  }
-
-};
-module.exports.THtmlItemsListContainer = THtmlItemsListContainer;
-
+// // NOTE: @extends ITHtmlItemsListContainerOptions
 /**
  * An options set for `THtmlItemsListController`-class
- * @typedef {Object} OPT_hlctlsett
+ * @typedef {Object} IHtmlItemsListControllerOptions
  * @property {boolean} [autoHideNewItems=false] - indicates whether to hide
  *     a new element
  * @property {boolean} [markCurrentItem=false] - indicates whether to mark
  *     a current element
  * @property {string|string[]} [itemBaseClassID] - contains a base class
  *     attributes applayed to each a newly added list member
+ * @property {number|string} [targetScopeForEID] - \[since v0.0.33] indicates
+ *     a target scope chosen to select an ID-attribute of the element
  * @property {boolean} [showStubsIfEmpty=false] - indicates whether to show
  *     stubs if empty
  * @property {boolean} [allowGroupSelection=false] - indicates whether
@@ -568,6 +61,11 @@ module.exports.THtmlItemsListContainer = THtmlItemsListContainer;
  *    of an element selection is allowed
  * @property {IStubItemsSetOptions} [stubs] - stub elements options
  */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {IHtmlItemsListControllerOptions}
+ */
+module.exports.IHtmlItemsListControllerOptions = {};
 
 /**
  * @augments THtmlItemsListContainer
@@ -581,7 +79,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   #_stubs;
   /** @type {Set<HTMLElement>} */
   #_selects;
-  /** @property {OPT_hlctlsett} */
+  /** @property {IHtmlItemsListControllerOptions} */
   #_options;// = null;
   /**
    * A controler status
@@ -603,17 +101,15 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   /**
    * Creates a new instance of the class.
    * @param {?HTMLElement} host - host element
-   * @param {OPT_hlctlsett} [opt] - options
+   * @param {IHtmlItemsListControllerOptions} [opt] - options
    */
   constructor(host, opt) {
-    // check host element
-    const isHostEnabled = isHTMLElement(host);
-    const _host = isHostEnabled ? host : null;
     // check options
-    /** @type {OPT_hlctlsett} */
     const _options = isPlainObject(opt) ? opt : {};
     // call parent constructor
-    super(_host, _options);
+    super(host, _options);
+    // check host
+    const _host = this.#_host = isHTMLElement(host) ? host : null;
     // load options
     let {
       //autoHideNewItems, // [*] processed by parent
@@ -625,17 +121,24 @@ class THtmlItemsListController extends THtmlItemsListContainer {
       stubs: stubsList,
     } = _options;
     if (typeof showStubsIfEmpty !== 'boolean') {
-      _options.showStubsIfEmpty = showStubsIfEmpty = false;
+      showStubsIfEmpty = false;
+      // // TODO: next line planned to be removed
+      _options.showStubsIfEmpty = showStubsIfEmpty;
     };
     if (typeof allowGroupSelection !== 'boolean') {
-      _options.allowGroupSelection = allowGroupSelection = false;
+      allowGroupSelection = false;
+      // // TODO: next line planned to be removed
+      _options.allowGroupSelection = allowGroupSelection;
     };
     if (typeof allowSelectionLocks !== 'boolean') {
-      _options.allowSelectionLocks = allowSelectionLocks = false;
+      allowSelectionLocks = false;
+      // // TODO: next line planned to be removed
+      _options.allowSelectionLocks = allowSelectionLocks;
     };
     // save options
     this.#_options = _options;
     // init status flags set
+    const isHostEnabled = isHTMLElement(_host);
     /** @type {statILCtrl} */
     const _status = {
       isSelectionLocked: false,
@@ -646,8 +149,6 @@ class THtmlItemsListController extends THtmlItemsListContainer {
       execDelItemDI: -1,
       execDelItemCI: -1,
     }
-    // bind ref to host
-    this.#_host = _host;
     // init stub items set
     this.#_stubs = new THtmlStubItemsSet(_host, stubsList);
     // init index of selected items
@@ -709,6 +210,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
       //console.log(`CHECK: e => tag:[${curItem.tagName}]`);
       if (host) {
         // find an actual list element in case when some inner element was clicking
+        /** @type {?HTMLElement} */
         let tmpItem = curItem;
         while (tmpItem) {
           //console.log(`CHECK: e => target.tag:[${tmpItem.tagName}]`);
@@ -1007,7 +509,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
-   * 
+   *
    * @typedef {Object} OPT_selectStat
    * @property {boolean} [ctrlKey=false]
    * @property {boolean} [shiftKey=false]