@cntwg/html-helper 0.0.27 → 0.1.0

package/lib/html-ctrls/list.js

@@ -1,1108 +0,0 @@
-// [v0.1.072-20250827]
-
-// === module init block ===
-
-const {
-  readAsNumber,
-  isPlainObject,
-  //TItemsListEx,
-} = require('@ygracs/bsfoc-lib-js');
-
-const {
-  TItemsListEx,
-} = require('@ygracs/lists-lib-js');
-
-const {
-  isHTMLElement, isSelectedHTMLElement, isHiddenHTMLElement,
-  showHTMLElement, hideHTMLElement,
-  selectHTMLElement, unselectHTMLElement,
-  markHTMLElementAsCurrent, unmarkCurrentHTMLElement,
-  readAsAttrValue, valueToClassList,
-  CSS_CLASS_STRING,
-} = require('../html-helper-lib.js');
-
-const { THtmlStubItemsSet } = require('./lists-stubs.js');
-
-const {
-  pushEventHandler, triggerEventHandler,
-} = require('./mod-hfunc.js');
-
-const {
-  //CSS_CLASS_SELECTED,
-  CSS_CLASS_DISABLED,
-  //CSS_CLASS_HIDDEN,
-  //CSS_CLASS_CURRENT,
-  //CSS_CLASS_ACTIVE,
-} = CSS_CLASS_STRING;
-
-// === module inner block ===
-
-/**
- * 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 {object}
- * @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 ===
-
-/***
- * (* constant definitions *)
- */
-
-const ILC_SMODE_DEF = 0;
-const ILC_SMODE_SHFT = 1;
-const ILC_SMODE_CTRL = 2;
-
-/***
- * (* function definitions *)
- */
-
-/***
- * (* class definitions *)
- */
-
-/**
- * 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]
- */
-
-/**
- * @classdesc This class implements an interfaco for a list container
- */
-class THtmlItemsListContainer {
-  /** @type {?HTMLElement} */
-  #_host;
-  /** @type {TItemsListEx} */
-  #_items;
-  /** @type {OPT_hlconsett} */
-  #_options;// = null;
-  /**
-   * 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') {
-      _options.autoHideNewItems = autoHideNewItems = false;
-    };
-    if (typeof markCurrentItem !== 'boolean') {
-      _options.markCurrentItem = markCurrentItem = false;
-    };
-    itemBaseClassID = valueToClassList(itemBaseClassID, true);
-    _options.itemBaseClassID = itemBaseClassID;
-    // init status
-    /** @type {statILCont} */
-    const _status = {
-      curIndex: _items.curIndex,
-      curItem: _items.curItem,
-    };
-    this.#_status = _status;
-    // save options
-    this.#_options = _options;
-  }
-
-  /**
-   * Contains a Qty of an elements
-   * @type {number}
-   * @readonly
-   */
-  get count() {
-    return this.#_items.count;
-  }
-
-  /**
-   * Contains an 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 {any} value - index value
-   * @returns {boolean}
-   */
-  chkIndex(value) {
-    return this.#_items.chkIndex(value);
-  }
-
-  /**
-   * Checks if a given value is a valid index and
-   * it fits an index range within an instance.
-   * @param {any} value - value to check
-   * @param {boolean} [opt=false] - defines a type of result
-   * @returns {(boolean|number)}
-   * @see TItemsListEx.chkIndexEx
-   */
-  chkIndexEx(...args) {
-    return this.#_items.chkIndexEx(...args);
-  }
-
-  /**
-   * Returns an index of a given element.
-   * @param {HTMLElement} item  - element to search
-   * @returns {number}
-   */
-  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.#_options.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.#_options.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
-   * @param {boolean} [opt=false]
-   * @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.#_options;
-      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]
-   * @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));
-  }
-
-};
-
-/**
- * @typedef {Object} OPT_hlctlsett
- * @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]
- * @property {boolean} [showStubsIfEmpty=false] - indicates whether to show stubs if empty
- * @property {boolean} [allowGroupSelection=false] - indicates whether
- *    a selection of the elements group is allowed
- * @property {boolean} [allowSelectionLocks=false] - indicates whether locking
- *    of an element selection is allowed
- * @property {OPT_stubconsett} [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 {
-  /** @type {?HTMLElement} */
-  #_host;
-  /** @type {THtmlStubItemsSet} */
-  #_stubs;
-  /** @type {Set<HTMLElement>} */
-  #_selects;
-  /** @property {OPT_hlctlsett} */
-  #_options;// = null;
-  /**
-   * A controler status
-   * @typedef {Object} statILCtrl
-   * @property {boolean} isSelectionLocked
-   * @property {boolean} isStubItemShown
-   * @property {boolean} isHostEnabled
-   * @property {boolean} catchEventOnHost
-   * @property {boolean} execDelItem
-   * @property {number} execDelItemDI
-   * @property {number} execDelItemCI
-   * @inner
-   */
-  /** @property {statILCtrl} */
-  #_status;
-  /** @property {Map<string, Function>} */
-  #_events;
-
-  /**
-   * Creates a new instance of the class.
-   * @param {?HTMLElement} host - host element
-   * @param {OPT_hlctlsett} [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);
-    // load options
-    let {
-      //autoHideNewItems, // [*] processed by parent
-      //markCurrentItem, // [*] processed by parent
-      //itemBaseClassID, // [*] processed by parent
-      showStubsIfEmpty,
-      allowGroupSelection,
-      allowSelectionLocks,
-      stubs: stubsList,
-    } = _options;
-    if (typeof showStubsIfEmpty !== 'boolean') {
-      _options.showStubsIfEmpty = showStubsIfEmpty = false;
-    };
-    if (typeof allowGroupSelection !== 'boolean') {
-      _options.allowGroupSelection = allowGroupSelection = false;
-    };
-    if (typeof allowSelectionLocks !== 'boolean') {
-      _options.allowSelectionLocks = allowSelectionLocks = false;
-    };
-    // save options
-    this.#_options = _options;
-    // init status flags set
-    /** @type {statILCtrl} */
-    const _status = {
-      isSelectionLocked: false,
-      isStubItemShown: false,
-      isHostEnabled: isHostEnabled,
-      catchEventOnHost: false,
-      execDelItem: false,
-      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
-    this.#_selects = new Set();
-    // init events controller
-    this.#_events = new Map();
-    if (isHostEnabled) {
-      // set on_click()-event controler
-      /**/// use bubblig stage
-      _host.addEventListener('click', this.#_on_will_select_item);
-      _status.catchEventOnHost = true;
-    };
-    // save status flags set
-    this.#_status = _status;
-  }
-
-  /**
-   * @param {object} e - event
-   * @returns {void}
-   * @private
-   */
-  #_on_will_select_item = (e) => {
-    //console.log('THtmlItemsListController._on_will_select_item() ==> was called...');
-    //e.preventDefault(); /* need to reconsider reason for use */
-    const {
-      eventPhase,
-      target,
-      currentTarget,
-      ctrlKey,
-      shiftKey,
-    } = e;
-    //console.log('CHECK: e => ditail:['+e.detail+']');
-    //console.log('CHECK: e => phase:['+eventPhase+']');
-    const onClickNum = readAsNumber(e.detail, 0);
-    const host = this.#_host;
-    const { isSelectionLocked, catchEventOnHost } = this.#_status;
-    let curItem = null;
-    switch (eventPhase) {
-      //* // NOTE: currently on eventPhase = 2 and 3
-      //*case 1:
-        /**/// capturing stage
-      case 2: {
-        /**/// target stage
-        if (target !== host) curItem = target;
-        break;
-      }
-      case 3: {
-        /**/// bubblig stage
-        curItem = catchEventOnHost ? target : currentTarget;
-        break;
-      }
-      default: {}
-    };
-    if (
-      !isSelectionLocked
-      && curItem instanceof HTMLElement
-      && (onClickNum === 0 || onClickNum === 1)
-      && !curItem.classList.contains(CSS_CLASS_DISABLED)
-    ) {
-      //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,
-        forceCI: true,
-      });
-    };
-  };
-
-  /**
-   * @param {string} name - event name
-   * @param {...any} args
-   * @returns {void}
-   * @private
-   * @see triggerEventHandler
-   */
-  #_triggerEvent = (name, ...args) => {
-    triggerEventHandler(this.#_events, name, ...args);
-  };
-
-  /**
-   * Returns a list of the selected elements
-   * @type {HTMLElement[]}
-   * @readonly
-   */
-  get SelectedItems() {
-    const _selects = this.#_selects;
-    // // TODO: consider to use: `[...<value>]`
-    let result = [];
-    for (let item of _selects) {
-      if (item) result.push(item);
-    };
-    return result;
-  }
-
-  /**
-   * Returns a `THtmlStubItemsSet` instance
-   * @type {THtmlStubItemsSet}
-   * @readonly
-   */
-  get StubItems() {
-    return this.#_stubs;
-  }
-
-  /**
-   * Indicates whether a selection is locked
-   * @type {boolean}
-   * @readonly
-   */
-  get isSelectionLocked() {
-    return this.#_status.isSelectionLocked;
-  }
-
-  /**
-   * Clears an instance content.
-   * @returns {void}
-   * @fires THtmlItemsListController#list-clear
-   */
-  clear() {
-    // // TODO: clear event handler on elements if set
-    super.clear();
-    this.#_selects.clear();
-    if (this.#_options.showStubsIfEmpty) {
-      // show default stub-item
-      this.#_status.isStubItemShown = this.#_stubs.showDefItem();
-    };
-    /**
-     * @event THtmlItemsListController#list-clear
-     * @type {void}
-     */
-    this.#_triggerEvent('list-clear');
-  }
-
-  /**
-   * Locks an element selection.
-   * @returns {void}
-   */
-  lockItemsSelection() {
-    if (this.#_options.allowSelectionLocks) {
-      this.#_status.isSelectionLocked = true;
-    };
-  }
-
-  /**
-   * Unlocks an element selection.
-   * @returns {void}
-   */
-  unlockItemsSelection() {
-    this.#_status.isSelectionLocked = false;
-  }
-
-  /**
-   * Sets a current index.
-   * @param {(number|string)} index - element index
-   * @returns {boolean}
-   * @fires THtmlItemsListController#current-item-chosen
-   * @private
-   */
-  #_setCurIndex(index) {
-    const isSUCCEED = super.setCurIndex(index);
-    /**
-     * @event THtmlItemsListController#current-item-chosen
-     * @type {Object}
-     * @property {number} index - element index
-     * @property {?HTMLElement} item - element
-     */
-    if (isSUCCEED) this.#_triggerEvent('current-item-chosen', {
-      index: Number(index),
-      item: null,
-    });
-    return isSUCCEED;
-  };
-
-  /**
-   * Sets a current index.
-   * @param {(number|string)} index - element index
-   * @returns {boolean}
-   */
-  setCurIndex(index) {
-    return this.selectItem(index, true);
-  }
-
-  /**
-   * Resets a current index.
-   * @returns {void}
-   */
-  rstCurIndex() {
-    const {
-      execDelItem,
-      execDelItemDI,
-      execDelItemCI,
-    } = this.#_status;
-    if (execDelItem) {
-      let index = execDelItemCI;
-      if (execDelItemCI !== -1) index--;
-      if (index !== -1 && execDelItemDI !== execDelItemCI) {
-        this.unselectItem(index);
-      };
-    };
-    super.rstCurIndex();
-  }
-
-  /**
-   * Adds an element to an instance members.
-   * @param {HTMLElement} item - some element
-   * @param {boolean} [opt=false]
-   * @returns {number}
-   * @fires THtmlItemsListController#first-item-added
-   * @fires THtmlItemsListController#item-added
-   */
-  addItem(item, opt) {
-    const index = super.addItem(item, false);
-    if (index !== -1) {
-      const { autoHideNewItems, showStubsIfEmpty } = this.#_options;
-      const _status = this.#_status;
-      const { catchEventOnHost, isStubItemShown } = _status;
-      if (!catchEventOnHost) {
-        // set event handler on element if it is not set on host
-        item.addEventListener('click', this.#_on_will_select_item);
-      };
-      // TODO: consider if a "boolean" <opt> is enough
-      const forceCI = typeof opt === 'boolean' ? opt : false;
-      if (!autoHideNewItems) {
-        if (index === 0) {
-          if (
-            showStubsIfEmpty
-            && isStubItemShown
-            && this.#_stubs.hideDefItem()
-          ) {
-            // hide default stub-item
-            _status.isStubItemShown = false;
-          };
-          /**
-           * @event THtmlItemsListController#first-item-added
-           * @type {Object}
-           * @property {number} index - element index
-           * @property {?HTMLElement} item - element
-           */
-          this.#_triggerEvent('first-item-added', {
-            index: index,
-            item: item,
-          });
-        };
-        /**
-         * @event THtmlItemsListController#item-added
-         * @type {Object}
-         * @property {number} index - element index
-         * @property {?HTMLElement} item - element
-         */
-        this.#_triggerEvent('item-added', {
-          index: index,
-          item: item,
-        });
-      };
-      if (forceCI) {
-        this.#_selectItemEx(item, {
-          ctrlKey: false,
-          shiftKey: false,
-          forceCI: forceCI,
-        });
-      };
-    };
-    return index;
-  }
-
-  /**
-   * Deletes an element from an instance members.
-   * @param {(number|string)} index - element index
-   * @param {any} [opt]
-   * @returns {boolean}
-   * @fires THtmlItemsListController#list-clear
-   * @fires THtmlItemsListController#item-removed
-   */
-  delItem(index, opt) {
-    const item = super.getItem(index);
-    let isSUCCEED = item !== undefined;
-    const _status = this.#_status;
-    if (isSUCCEED) {
-      _status.execDelItem = true;
-      _status.execDelItemCI = this.curIndex;
-      _status.execDelItemDI = Number(index);
-      isSUCCEED = super.delItem(index, opt, false);
-      if (isSUCCEED) {
-        const _options = this.#_options;
-        if (!_status.catchEventOnHost && isHTMLElement(item)) {
-          // remove event handler on element if it was set by addItem()
-          item.removeEventListener('click', this.#_on_will_select_item);
-        };
-        if (this.isEmpty()) {
-          this.#_selects.clear();
-          if (_options.showStubsIfEmpty) {
-            // show default stub-item
-            _status.isStubItemShown = this.#_stubs.showDefItem();
-          };
-          /**
-           * @see THtmlItemsListController#list-clear
-           */
-          this.#_triggerEvent('list-clear');
-        } else {
-          this.#_selects.delete(item);
-          /**
-           * @event THtmlItemsListController#item-removed
-           * @type {Object}
-           * @property {number} index - element index
-           * @property {?HTMLElement} item - element
-           */
-          this.#_triggerEvent('item-removed', {
-            index: Number(index),
-            item: item,
-          });
-          const current = this.curIndex;
-          if (current === -1) {
-            this.rstCurIndex();
-          } else {
-            this.setCurIndex(current);
-          };
-        };
-      };
-      _status.execDelItemDI = -1;
-      _status.execDelItemCI = -1;
-      _status.execDelItem = false;
-    };
-    return isSUCCEED;
-  }
-
-  /**
-   * Selects an element.
-   * @param {(number|string)} index - element index
-   * @returns {boolean}
-   * @private
-   * @fires THtmlItemsListController#item-selected
-   */
-  #_selectItem(index) {
-    const item = super.getItem(index);
-    const isSUCCEED = selectHTMLElement(item);
-    if (isSUCCEED) {
-      this.#_selects.add(item);
-      /**
-       * @event THtmlItemsListController#item-selected
-       * @type {Object}
-       * @property {number} index - element index
-       * @property {?HTMLElement} item - element
-       */
-      this.#_triggerEvent('item-selected', {
-        index: Number(index),
-        item: item,
-      });
-    };
-    return isSUCCEED;
-  }
-
-  /**
-   * Selects an element.
-   * @param {?HTMLElement} item - element
-   * @param {object} [opt]
-   * @param {boolean} [opt.ctrlKey=false]
-   * @param {boolean} [opt.shiftKey=false]
-   * @param {boolean} [opt.forceCI=false]
-   * @returns {void}
-   * @private
-   */
-  #_selectItemEx(item, opt){
-    const _selects = this.#_selects;
-    let {
-      ctrlKey = false,
-      shiftKey = false,
-      forceCI = false,
-    } = opt;
-    let mode = ILC_SMODE_DEF;
-    let doUnSelGrp = false;
-    let indexCI = this.curIndex;
-    let indexNI = this.srchIndex(item);
-    if (indexCI !== -1) {
-      if (this.#_options.allowGroupSelection) {
-        if (shiftKey) {
-          mode = ILC_SMODE_SHFT;
-          if (_selects.size > 0) doUnSelGrp = true;
-        } else if (ctrlKey) {
-          mode = ILC_SMODE_CTRL;
-        } else if (_selects.size > 0) {
-          doUnSelGrp = true;
-        };
-      } else if (_selects.size > 0) {
-        doUnSelGrp = true;
-      };
-    };
-    if (doUnSelGrp) {
-      for (let item of _selects) {
-        this.unselectItem(this.srchIndex(item));
-      };
-      _selects.clear();
-    };
-    switch (mode) {
-      case ILC_SMODE_SHFT: {
-        if (indexCI > indexNI) [ indexCI, indexNI ] = [ indexNI, indexCI ];
-        for (let i = indexCI; i < indexNI + 1; i++) {
-          this.#_selectItem(i);
-        };
-        break;
-      }
-      case ILC_SMODE_CTRL: {
-        this.#_selectItem(this.srchIndex(item));
-        break;
-      }
-      default: {
-        if (this.#_selectItem(this.srchIndex(item))) {
-          if (forceCI) this.#_setCurIndex(indexNI);
-        };
-        break;
-      }
-    };
-  }
-
-  /**
-   * Selects an element.
-   * @param {(number|string)} index - element index
-   * @param {boolean} [opt=false]
-   * @returns {boolean}
-   */
-  selectItem(index, opt) {
-    const item = super.getItem(index);
-    let isSUCCEED = isHTMLElement(item);
-    if (isSUCCEED) {
-      const forceCI = typeof opt === 'boolean' ? opt : false;
-      this.#_selectItemEx(item, {
-        ctrlKey: false,
-        shiftKey: false,
-        forceCI: forceCI,
-      });
-    };
-    return isSUCCEED;
-  }
-
-  /**
-   * Unselects an element.
-   * @param {(number|string)} index - element index
-   * @returns {boolean}
-   * @fires THtmlItemsListController#item-unselected
-   */
-  unselectItem(index) {
-    const item = super.getItem(index);
-    let isSUCCEED = unselectHTMLElement(item);
-    if (isSUCCEED) {
-      this.#_selects.delete(item);
-      /**
-       * @event THtmlItemsListController#item-unselected
-       * @type {Object}
-       * @property {number} index - element index
-       * @property {?HTMLElement} item - element
-       */
-      this.#_triggerEvent('item-unselected', {
-        index: Number(index),
-        item: item,
-      });
-    };
-    return isSUCCEED;
-  }
-
-  /**
-   * Hides an element.
-   * @param {(number|string)} index - element index
-   * @returns {boolean}
-   * @fires THtmlItemsListController#item-hidden
-   */
-  hideItem(index) {
-    const item = super.getItem(index);
-    let isSUCCEED = hideHTMLElement(item);
-    if (isSUCCEED) {
-      /**
-       * @event THtmlItemsListController#item-hidden
-       * @type {Object}
-       * @property {number} index - element index
-       * @property {?HTMLElement} item - element
-       */
-      this.#_triggerEvent('item-hidden', {
-        index: Number(index),
-        item: item,
-      });
-    };
-    return isSUCCEED;
-  }
-
-  /**
-   * Shows an element.
-   * @param {(number|string)} index - element index
-   * @returns {boolean}
-   * @fires THtmlItemsListController#item-shown
-   */
-  showItem(index) {
-    const item = super.getItem(index);
-    let isSUCCEED = showHTMLElement(item);
-    if (isSUCCEED) {
-      /**
-       * @event THtmlItemsListController#item-shown
-       * @type {Object}
-       * @property {number} index - element index
-       * @property {?HTMLElement} item - element
-       */
-      this.#_triggerEvent('item-shown', {
-        index: Number(index),
-        item: item,
-      });
-    };
-    return isSUCCEED;
-  }
-
-  /**
-   * Sets a callback function to handle event.
-   * @param {string} name - event name
-   * @param {func} evnt
-   * @returns {void}
-   */
-  on(name, evnt) {
-    pushEventHandler(this.#_events, name, evnt);
-  }
-
-};
-
-// === module exports block ===
-
-exports.THtmlStubItemsSet = THtmlStubItemsSet;
-exports.THtmlItemsListContainer = THtmlItemsListContainer;
-exports.THtmlItemsListController = THtmlItemsListController;