@cntwg/html-ctrls-lists 0.0.32 → 0.0.33

package/lib/list-cont.js

@@ -0,0 +1,538 @@
+// [v0.2.091-20260510]
+
+// === module init block ===
+
+const {
+  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,
+} = require('@cntwg/html-helper');
+
+// === module inner block ===
+
+/**
+ * @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 ===
+
+/**
+ * An options set for `THtmlItemsListContainer`-class
+ * @typedef {Object} ITHtmlItemsListContainerOptions
+ * @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
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {ITHtmlItemsListContainerOptions}
+ */
+module.exports.ITHtmlItemsListContainerOptions = {};
+
+/**
+ * @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
+   * @property {number} [targetScopeForEID] - \[since v0.0.33] **reserved**
+   */
+  /** @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 {ITHtmlItemsListContainerOptions} [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
+    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;

package/lib/list-ctrl.d.ts

@@ -0,0 +1,85 @@
+/**
+ * An options set for `THtmlItemsListController`-class
+ */
+export type IHtmlItemsListControllerOptions = {
+    /**
+     * - indicates whether to hide a new element
+     */
+    autoHideNewItems?: boolean;
+    /**
+     * - indicates whether to mark a current element
+     */
+    markCurrentItem?: boolean;
+    /**
+     * - contains a base class
+     * attributes applayed to each a newly added list member
+     */
+    itemBaseClassID?: string | string[];
+    /**
+     * - indicates a target scope chosen to select an ID-attribute of the element
+     * @since 0.0.33
+     */
+    targetScopeForEID?: string | number;
+    /**
+     * - indicates whether to show stubs if empty
+     */
+    showStubsIfEmpty?: boolean;
+    /**
+     * - indicates whether a selection of the elements group is allowed
+     */
+    allowGroupSelection?: boolean;
+    /**
+     * - indicates whether locking of an element selection is allowed
+     */
+    allowSelectionLocks?: boolean;
+    /**
+     * - stub elements options
+     */
+    stubs?: IStubItemsSetOptions | undefined;
+};
+export const IHtmlItemsListControllerOptions: IHtmlItemsListControllerOptions;
+import type { IStubItemsSetOptions } from "./lists-stubs";
+
+/**
+ * This class enhanced a capabilities implemented
+ * in the `THtmlItemsListContainer` class
+ */
+export class THtmlItemsListController extends THtmlItemsListContainer {
+    /**
+     * Creates a new instance of the class.
+     */
+    constructor(host: HTMLElement | null, opt?: IHtmlItemsListControllerOptions);
+    /**
+     * Returns a list of the selected elements
+     */
+    get SelectedItems(): HTMLElement[];
+    /**
+     * Returns a `THtmlStubItemsSet` instance
+     */
+    get StubItems(): THtmlStubItemsSet;
+    /**
+     * Indicates whether a selection is locked
+     */
+    get isSelectionLocked(): boolean;
+    /**
+     * Locks an element selection.
+     */
+    lockItemsSelection(): void;
+    /**
+     * Unlocks an element selection.
+     */
+    unlockItemsSelection(): void;
+    /**
+     * Deletes an element from an instance members.
+     * @fires THtmlItemsListController#list-clear
+     * @fires THtmlItemsListController#item-removed
+     */
+    delItem(index: number | string, opt?: any): boolean;
+    /**
+     * Sets a callback function to handle event.
+     */
+    on(name: string, evnt: Function): void;
+    #private;
+}
+import { THtmlItemsListContainer } from "./list-cont";
+import { THtmlStubItemsSet } from "./lists-stubs";