@cntwg/html-ctrls-lists 0.0.27

package/lib/list.js

@@ -0,0 +1,1137 @@
+// [v0.1.074-20251004]
+
+// === module init block ===
+
+const {
+  readAsNumber,
+  isPlainObject,
+} = require('@ygracs/bsfoc-lib-js');
+
+const {
+  TItemsListEx,
+} = require('@ygracs/lists-lib-js');
+
+const {
+  isHTMLElement, isSelectedHTMLElement, isHiddenHTMLElement,
+  showHTMLElement, hideHTMLElement,
+  selectHTMLElement, unselectHTMLElement,
+  markHTMLElementAsCurrent, unmarkCurrentHTMLElement,
+  readAsAttrValue, valueToClassList,
+  eventHelper, // [!] not oficialy exported yet
+  CSS_CLASS_STRING,
+} = require('@cntwg/html-helper');
+
+const { THtmlStubItemsSet } = require('./lists-stubs.js');
+
+// === module inner block ===
+
+const {
+  pushEventHandler, triggerEventHandler,
+} = eventHelper;
+
+const {
+  CSS_CLASS_DISABLED,
+} = CSS_CLASS_STRING;
+
+/**
+ * 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] - 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;
+  /** @type {OPT_hlconsett} */
+  #_options;
+  /**
+   * 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;
+  }
+
+  [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}
+   */
+  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 {(number|string)} 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}
+   * @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.#_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 - 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.#_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] - 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));
+  }
+
+};
+
+/**
+ * A an options set for a `THtmlStubItemsSet`-class constructor
+ * @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
+ */
+
+/**
+ * An options set for `THtmlItemsListController`-class
+ * @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] - contains a base class
+ *     attributes applayed to each a newly added list member
+ * @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] - stub elements options
+ */
+
+/**
+ * @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] - indicates whether to correct a current index
+   * @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] - indicates whether to correct a current index
+   * @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;