@cntwg/html-helper 0.0.14

package/lib/html-ctrls-list.js

@@ -0,0 +1,568 @@
+// [v0.1.036-20220902]
+
+// === module init block ===
+
+const {
+  readAsBool, readAsNumber, readAsString,
+  isEmptyString,
+  isNotEmptyString,
+  isArray, isObject,
+  isPlainObject,
+  TItemsListEx,
+} = require('@ygracs/bsfoc-lib-js');
+
+const {
+  isHTMLElement, isSelectedHTMLElement, isHiddenHTMLElement,
+  showHtmlElement, hideHtmlElement,
+  selectHtmlElement, unselectHtmlElement,
+  CSS_CLASS_STRING,
+} = require('./html-helper-lib.js');
+
+const { THtmlStubItemsSet } = require('./html-ctrls/lists-stubs.js');
+
+const {
+  CSS_CLASS_SELECTED,
+  CSS_CLASS_DISABLED,
+  CSS_CLASS_HIDDEN,
+} = CSS_CLASS_STRING;
+
+// === module extra block (helper functions) ===
+
+// === module main block (function definitions) ===
+
+// === module main block (class definitions) ===
+
+class THtmlItemsListContainer {
+  #_host = null;
+  #_items = null;
+  #_options = null;
+
+  constructor(host, opt) {
+    this.#_items = new TItemsListEx();
+    this.#_host = isHTMLElement(host) ? host : null;
+    // load options
+    const _options = isPlainObject(opt) ? opt : {};
+    let { autoHideNewItems, } = _options;
+    if (typeof autoHideNewItems !== 'boolean') autoHideNewItems = false;
+    // save options
+    _options.autoHideNewItems = autoHideNewItems;
+    this.#_options = _options;
+  }
+
+  get count(){
+    return this.#_items.count;
+  }
+
+  get curIndex(){
+    return this.#_items.curIndex;
+  }
+
+  get minIndex(){
+    return this.#_items.minIndex;
+  }
+
+  get maxIndex(){
+    return this.#_items.maxIndex;
+  }
+
+  get prevIndex(){
+    return this.#_items.prevIndex;
+  }
+
+  get nextIndex(){
+    return this.#_items.nextIndex;
+  }
+
+  get curItem(){
+    const item = this.#_items.curItem;
+    return isHTMLElement(item) ? item : null;
+  }
+
+  clear(){
+    this.#_items.clear();
+    if (this.#_host) this.#_host.innerHTML = '';
+  }
+
+  isEmpty(){
+    return this.#_items.isEmpty();
+  }
+
+  isNotEmpty(){
+    return this.#_items.isNotEmpty();
+  }
+
+  chkIndex(value){
+    return this.#_items.chkIndex(value);
+  }
+
+  chkIndexEx(...args){
+    return this.#_items.chkIndexEx(...args);
+  }
+
+  srchIndex(item){
+    return isHTMLElement(item) ? this.#_items.srchIndex(item) : -1;
+  }
+
+  srchIndexByAttr(name, value){
+    let index = -1;
+    const _name = typeof name === 'string' ? name.trim() : '';
+    const _value = readAsString(value, '', {
+      useTrim: true,
+      numberToString: true,
+      boolToString: true,
+    });
+    if (_name !== '' && _value !== '') {
+      let item = null;
+      for (let i = 0; i < this.count; i++) {
+        item = this.getItem(i);
+        if (
+          isHTMLElement(item)
+          && item.hasAttribute(_name)
+          && item.getAttribute(_name) === _value
+        ) {
+          index = i;
+          break;
+        };
+      };
+    };
+    return index;
+  };
+
+  srchIndexByID(value){
+    return this.srchIndexByAttr('id', value);
+  };
+
+  setCurIndex(index){
+    return this.#_items.setIndex(index);
+  }
+
+  rstCurIndex(){
+    this.#_items.rstIndex();
+  }
+
+  getItem(index){
+    const item = this.#_items.getItem(index);
+    return isHTMLElement(item) ? item : null;
+  }
+
+  getItemByAttr(name, value = ''){
+    let _name = '';
+    let item = null;
+    let index = -1;
+    value = readAsString(value, '', {
+      useTrim: true,
+      numberToString: true,
+      boolToString: true,
+    });
+    if (typeof name === 'string' && ((_name = name.trim()) !== '')){
+      const useAnyName = isEmptyString(name);
+      const useAnyVal = isEmptyString(value);
+      for (let i = 0; i < this.count; i++) {
+        item = this.getItem(i);
+        if (
+          isHTMLElement(item)
+          && item.hasAttribute(_name)
+          && (useAnyVal || item.getAttribute(_name) === value)
+        ) {
+          index = i;
+          break;
+        };
+      };
+    };
+    return index !== -1 ? item : null;
+  }
+
+  getItemByID(value){
+    return this.getItemByAttr('id', value);
+  }
+
+  addItem(item, opt){
+    let index = isHTMLElement(item) ? this.#_items.addItemEx(item, opt) : -1;
+    let isSUCCEED = index !== -1;
+    if (isSUCCEED) {
+      if (this.#_options.autoHideNewItems) hideHtmlElement(item);
+      if (this.#_host) this.#_host.appendChild(item);
+    };
+    return isSUCCEED ? index : -1;
+  }
+
+  delItem(index, opt){
+    let item = this.#_items.delItemEx(index, opt);
+    let isSUCCEED = isHTMLElement(item);
+    if (isSUCCEED && this.#_host && this.#_host.contains(item)) {
+      this.#_host.removeChild(item);
+    };
+    return isSUCCEED;
+  }
+
+  selectItem(index, opt){
+    let isSUCCEED = selectHtmlElement(this.#_items.getItem(index));
+    if (isSUCCEED && readAsBool(opt, false)) this.#_items.setIndex(index);
+    return isSUCCEED;
+  }
+
+  unselectItem(index){
+    return unselectHtmlElement(this.#_items.getItem(index));
+  }
+
+  hideItem(index){
+    return hideHtmlElement(this.#_items.getItem(index));
+  }
+
+  showItem(index){
+    return showHtmlElement(this.#_items.getItem(index));
+  }
+
+  isSelectedItem(index) {
+    return isSelectedHTMLElement(this.#_items.getItem(index));
+  }
+
+  isHiddenItem(index) {
+    return isHiddenHTMLElement(this.#_items.getItem(index));
+  }
+
+};
+
+class THtmlItemsListController extends THtmlItemsListContainer {
+  #_host = null;
+  #_stubs = null;
+  #_selects = null;
+  #_visibles = null;
+  #_options = null;
+  #_status = null;
+  #_events = null;
+
+  constructor(host, opt) {
+    // check host element
+    const isHostEnabled = isHTMLElement(host);
+    const _host = isHostEnabled ? host : null;
+    // check options
+    const _options = isPlainObject(opt) ? opt : {};
+    // call parent constructor
+    super(_host, _options);
+    // load options
+    let {
+      autoHideNewItems,
+      showStubsIfEmpty,
+      allowGroupSelection,
+      allowSelectionLocks,
+      stubs: stubsList,
+    } = _options;
+    if (typeof autoHideNewItems !== 'boolean') autoHideNewItems = false;
+    if (typeof showStubsIfEmpty !== 'boolean') showStubsIfEmpty = false;
+    if (typeof allowGroupSelection !== 'boolean') allowGroupSelection = false;
+    if (typeof allowSelectionLocks !== 'boolean') allowSelectionLocks = false;
+    // save options
+    _options.autoHideNewItems = autoHideNewItems;
+    _options.showStubsIfEmpty = showStubsIfEmpty;
+    _options.allowGroupSelection = allowGroupSelection;
+    _options.allowSelectionLocks = allowSelectionLocks;
+    this.#_options = _options;
+    // init status flags set
+    const _status = {
+      isSelectionLocked: false,
+      isStubItemShown: false,
+      isHostEnabled: isHostEnabled,
+      catchEventOnHost: false,
+    }
+    // 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 index of visible items
+    this.#_visibles = 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;
+  }
+
+  #_on_will_select_item = (e) => {
+    //console.log('THtmlItemsListController._on_will_select_item() ==> was called...');
+    //console.log('CHECK: e => ditail:['+e.detail+']');
+    //console.log('CHECK: e => phase:['+e.eventPhase+']');
+    //e.preventDefault(); /* need to reconsider reason for use */
+    const _status = this.#_status;
+    const { isSelectionLocked, catchEventOnHost } = _status;
+    const on_click_num = readAsNumber(e.detail, 0);
+    let curItem = null;
+    switch (e.eventPhase) {
+      //*case 1:
+      //* // NOTE: currently on eventPhase = 2 and 3
+      case 2:
+        /**/// capturing stage
+        curItem = e.target;
+        break;
+      case 3:
+        /**/// bubblig stage
+        curItem = catchEventOnHost ? e.target : e.currentTarget;
+        break;
+      default:
+        break;
+    };
+    if (
+      !isSelectionLocked
+      && curItem instanceof HTMLElement
+      && (on_click_num === 0 || on_click_num === 1)
+      && !curItem.classList.contains(CSS_CLASS_DISABLED)
+    ) {
+      const key_ctrl = readAsBool(e.ctrlKey, false);
+      const key_shft = readAsBool(e.shiftKey, false);
+      //console.log('CHECK: e => isShiftKeyPressed:['+key_ctrl+']');
+      //console.log('CHECK: e => isCtrlKeyPressed:['+key_shft+']');
+      let c_index = this.curIndex;
+      let n_index = this.srchIndex(curItem);
+      //console.log('THtmlItemsListController._on_will_select_item() ==> current:['+c_index+']');
+      //console.log('THtmlItemsListController._on_will_select_item() ==> next:['+n_index+']');
+      let act_in_mode = 0;
+      let act_unsel_grp = false;
+      if (this.#_options.allowGroupSelection) {
+        if (c_index !== -1) {
+          if (key_ctrl) {
+            act_in_mode = 2;
+          } else if (key_shft) {
+            act_in_mode = 1;
+          } else if (this.#_selects.size > 0) {
+            //console.log('THtmlItemsListController._on_will_select_item() ==> _selects.size:['+this.#_selects.size+']');
+            act_unsel_grp = true;
+          };
+        };
+      };
+      //console.log('THtmlItemsListController._on_will_select_item() ==> mode:['+act_in_mode+']');
+      //console.log('THtmlItemsListController._on_will_select_item() ==> act_unsel_grp:['+act_unsel_grp+']');
+      if (act_unsel_grp) {
+        for (let item of this.#_selects) {
+          c_index = this.srchIndex(item);
+          if (c_index !== -1) this.unselectItem(c_index);
+        };
+        c_index = -1;
+      };
+      if (act_in_mode === 1) {
+        if (c_index > n_index) [ c_index, n_index ] = [ n_index, c_index ];
+        let t_index = 0;
+        for (let item of this.#_selects) {
+          t_index = this.srchIndex(item);
+          if (t_index !== -1) this.unselectItem(t_index);
+        };
+        this.#_selects.clear();
+        for (let i = c_index; i < n_index + 1; i++) {
+          this.selectItem(i, false);
+        };
+      } else if (act_in_mode === 2) {
+        if (this.isSelectedItem(n_index)) {
+          this.unselectItem(n_index);
+        } else {
+          this.selectItem(n_index, false);
+        };
+      } else if (c_index !== n_index) {
+        if (c_index !== -1) this.unselectItem(c_index);
+        this.selectItem(n_index, true);
+      };
+    };
+  };
+
+  #_triggerEvent = (name, ...args) => {
+    const _name = typeof name === 'string' ? name.trim() : '';
+    if (_name !== '') {
+      const _events = this.#_events;
+      if (_events.has(_name)) _events.get(_name)(...args);
+    };
+  };
+
+  get SelectedItems(){
+    let result = [];
+    for (let item of this.#_selects) {
+      if (item) result.push(item);
+    };
+    return result;
+  }
+
+  get StubItems(){
+    return this.#_stubs;
+  }
+
+  get isSelectionLocked(){
+    return this.#_status.isSelectionLocked;
+  }
+
+  clear(){
+    // // TODO: clear event handler on elements if set
+    super.clear();
+    this.#_selects.clear();
+    this.#_visibles.clear();
+    if (this.#_options.showStubsIfEmpty) {
+      // show default stub-item
+      this.#_status.isStubItemShown = this.#_stubs.showDefItem();
+    };
+    this.#_triggerEvent('list-clear');
+  }
+
+  lockItemsSelection(){
+    if (this.#_options.allowSelectionLocks) {
+      this.#_status.isSelectionLocked = true;
+    };
+  }
+
+  unlockItemsSelection(){
+    this.#_status.isSelectionLocked = false;
+  }
+
+  setCurIndex(index){
+    const isSUCCEED = super.setCurIndex(index);
+    if (isSUCCEED) this.#_triggerEvent('current-item-chosen', {
+      index: Number(index),
+      item: null,
+    });
+    return isSUCCEED;
+  }
+
+  addItem(item, opt){
+    let index = super.addItem(item, false);
+    let newItem = index !== -1 ? super.getItem(index) : null;
+    if (newItem) {
+      const _options = this.#_options;
+      const _status = this.#_status;
+      if (!_status.catchEventOnHost) {
+        // set event handler on element if it is not set on host
+        newItem.addEventListener('click', this.#_on_will_select_item);
+      };
+      // TODO: consider if a "boolean" <opt> is enough
+      let setItemAsCur = typeof opt === 'boolean' ? opt : false;
+      if (_options.autoHideNewItems && !setItemAsCur) {
+        super.hideItem(index);
+      } else {
+        if (index === 0) {
+          if (
+            _options.showStubsIfEmpty
+            && _status.isStubItemShown
+            && this.#_stubs.hideDefItem()
+          ) {
+            // hide default stub-item
+            _status.isStubItemShown = false;
+          };
+          this.#_triggerEvent('first-item-added', {
+            index: index,
+            item: newItem,
+          });
+        };
+        this.#_triggerEvent('item-added', {
+          index: index,
+          item: newItem,
+        });
+      };
+      if (setItemAsCur) this.setCurIndex(index);
+    };
+    return index;
+  }
+
+  delItem(index, opt){
+    let item = super.getItem(index);
+    let isSUCCEED = isHTMLElement(item) ? super.delItem(index, opt) : false;
+    if (isSUCCEED) {
+      const _options = this.#_options;
+      const _status = this.#_status;
+      if (!_status.catchEventOnHost) {
+        // remove event handler on element if it was set by addItem()
+        item.removeEventListener('click', this.#_on_will_select_item);
+      };
+      this.#_selects.delete(item);
+      this.#_visibles.delete(item);
+      if (this.isEmpty()) {
+        if (_options.showStubsIfEmpty) {
+          // show default stub-item
+          _status.isStubItemShown = this.#_stubs.showDefItem();
+        };
+        this.#_triggerEvent('list-clear');
+      } else {
+        this.#_triggerEvent('item-removed', {
+          index: Number(index),
+          item: item,
+        });
+      };
+    };
+    return isSUCCEED;
+  }
+
+  selectItem(index, opt){
+    let item = super.getItem(index);
+    let isSUCCEED = selectHtmlElement(item);
+    if (isSUCCEED) {
+      this.#_selects.add(item);
+      this.#_triggerEvent('item-selected', {
+        index: Number(index),
+        item: item,
+      });
+      if (readAsBool(opt, false)) isSUCCEED = this.setCurIndex(index);
+    };
+    return isSUCCEED;
+  }
+
+  unselectItem(index){
+    let item = super.getItem(index);
+    let isSUCCEED = unselectHtmlElement(item);
+    if (isSUCCEED) {
+      this.#_selects.delete(item);
+      this.#_triggerEvent('item-unselected', {
+        index: Number(index),
+        item: item,
+      });
+    };
+    return isSUCCEED;
+  }
+
+  hideItem(index){
+    let item = super.getItem(index);
+    let isSUCCEED = hideHtmlElement(item);
+    if (isSUCCEED) {
+      this.#_visibles.delete(item);
+      this.#_triggerEvent('item-hidden', {
+        index: Number(index),
+        item: item,
+      });
+    };
+    return isSUCCEED;
+  }
+
+  showItem(index){
+    let item = super.getItem(index);
+    let isSUCCEED = showHtmlElement(item);
+    if (isSUCCEED) {
+      this.#_visibles.add(item);
+      this.#_triggerEvent('item-shown', {
+        index: Number(index),
+        item: item,
+      });
+    };
+    return isSUCCEED;
+  }
+
+  on(name, evnt){
+    const _name = typeof name === 'string' ? name.trim() : '';
+    if (_name !== '' && typeof evnt === 'function') {
+      const _events = this.#_events;
+      if (!_events.has(_name)) {
+        _events.set(_name, evnt);
+      } else {
+        /* NOTE:
+         *    for current you can't reset or set new one on the same event
+         */
+        //console.log('THtmlItemsListController.on() ==> event:['+name+'] - already exists...');
+      };
+    };
+  }
+
+};
+
+// === module exports block ===
+
+exports.THtmlStubItemsSet = THtmlStubItemsSet;
+exports.THtmlItemsListContainer = THtmlItemsListContainer;
+exports.THtmlItemsListController = THtmlItemsListController;