@cntwg/html-ctrls-lists 0.0.27

package/lib/lists-btn.js

@@ -0,0 +1,214 @@
+// [v0.1.058-20250928]
+
+// === module init block ===
+
+const {
+  isPlainObject,
+} = require('@ygracs/bsfoc-lib-js');
+
+const {
+  isHTMLButton,
+  eventHelper, // [!] not oficialy exported yet
+  CSS_CLASS_STRING,
+} = require('@cntwg/html-helper');
+
+const {
+  THtmlButtonsSet,
+} = require('@cntwg/html-helper');
+
+const {
+  readOnClickEventInfo,
+} = require('./mod-hfunc.js');
+
+// === module inner block ===
+
+const {
+  pushEventHandler, triggerEventHandler,
+} = eventHelper;
+
+const {
+  CSS_CLASS_DISABLED,
+} = CSS_CLASS_STRING;
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
+const BTS_DEF_GROUP_NAME = 'all';
+
+/***
+ * (* function definitions *)
+ */
+
+/***
+ * (* class definitions *)
+ */
+
+/**
+ * A description for list buttons set.
+ * @typedef {Object} listButtonsSetDesc
+ * @property {?HTMLElement} btnFirst - button 'move to first'
+ * @property {?HTMLElement} btnPrev - button 'move to previous'
+ * @property {?HTMLElement} btnNext - button 'move to next'
+ * @property {?HTMLElement} btnLast - button 'move to last'
+ */
+
+/**
+ * @classdesc This class implements an interface of a pre-defined
+ *            buttons set that is used in pair with a list elements.
+ *            A set provide a buttons: <next>, <previous>, <first> and <last>.
+ */
+class THtmlListButtonsController {
+  /** @type {THtmlButtonsSet} */
+  #_btnSet;
+  /** @type {Map<string, Function>} */
+  #_events;
+
+  /**
+   * Creates an instance of a buttons set.
+   * @param {listButtonsSetDesc} [opt] - an options
+   */
+  constructor(opt) {
+    // load controls
+    /** @type {listButtonsSetDesc} */
+    let {
+      btnFirst,
+      btnPrev,
+      btnNext,
+      btnLast,
+    } = isPlainObject(opt) ? opt : {};
+    if (!isHTMLButton(btnFirst)) btnFirst = null;
+    if (!isHTMLButton(btnPrev)) btnPrev = null;
+    if (!isHTMLButton(btnNext)) btnNext = null;
+    if (!isHTMLButton(btnLast)) btnLast = null;
+    // init buttons set
+    const _btnSet = new THtmlButtonsSet();
+    this.#_btnSet = _btnSet;
+    _btnSet.addGroup('move_frwd');
+    _btnSet.addGroup('move_bkwd');
+    _btnSet.addGroup('dsbl_ctrls');
+    if (btnFirst && btnLast) {
+      _btnSet.addItem('btn_frst', btnFirst, 'move_bkwd');
+      _btnSet.addItem('btn_last', btnLast, 'move_frwd');
+      btnFirst.addEventListener('click', e => this.#_on_btn_pressed(e, 'first'));
+      btnLast.addEventListener('click', e => this.#_on_btn_pressed(e, 'last'));
+    } else {
+      _btnSet.addItem('btn_frst', btnFirst, 'dsbl_ctrls');
+      _btnSet.addItem('btn_last', btnLast, 'dsbl_ctrls');
+    };
+    if (btnPrev && btnNext) {
+      _btnSet.addItem('btn_prev', btnPrev, 'move_bkwd');
+      _btnSet.addItem('btn_next', btnNext, 'move_frwd');
+      btnPrev.addEventListener('click', e => this.#_on_btn_pressed(e, 'prev'));
+      btnNext.addEventListener('click', e => this.#_on_btn_pressed(e, 'next'));
+    } else {
+      _btnSet.addItem('btn_prev', btnPrev, 'dsbl_ctrls');
+      _btnSet.addItem('btn_next', btnNext, 'dsbl_ctrls');
+    };
+    _btnSet.disableGroup('move_frwd');
+    _btnSet.disableGroup('move_bkwd');
+    _btnSet.disableGroup('dsbl_ctrls');
+    // init events controller
+    this.#_events = new Map();
+  }
+
+  /**
+   * @param {object} e - event
+   * @param {string} key - button ID
+   * @returns {void}
+   * @private
+   */
+  #_on_btn_pressed = (e, key) => {
+    //console.log(`THtmlListButtonsController._on_btn_pressed().key(${key}) ==> was called...`);
+    //e.preventDefault(); /* need to reconsider reason for use */
+    const { item, onClickNum } = readOnClickEventInfo(e);
+    if (
+      item instanceof HTMLElement
+      && (onClickNum === 0 || onClickNum === 1)
+      && !item.classList.contains(CSS_CLASS_DISABLED)
+    ) {
+      this.#_triggerEvent(`btn-${key}-pressed`, e);
+    };
+  }
+
+  /**
+   * @param {string} name - event name
+   * @param {...any} args
+   * @returns {void}
+   * @private
+   * @see triggerEventHandler
+   */
+  #_triggerEvent = (name, ...args) => {
+    triggerEventHandler(this.#_events, name, ...args);
+  }
+
+  /**
+   * Disables all buttons.
+   * @returns {void}
+   */
+  disableAll() {
+    const _btnSet = this.#_btnSet;
+    _btnSet.disableGroup('move_bkwd');
+    _btnSet.disableGroup('move_frwd');
+  }
+
+  /**
+   * Disables all buttons in 'move_bkwd' group.
+   * @returns {void}
+   */
+  disableBkwd() {
+    this.#_btnSet.disableGroup('move_bkwd');
+  }
+
+  /**
+   * Disables all buttons in 'move_frwd' group.
+   * @returns {void}
+   */
+  disableFrwd() {
+    this.#_btnSet.disableGroup('move_frwd');
+  }
+
+  /**
+   * Enables all buttons.
+   * @returns {void}
+   */
+  enableAll() {
+    const _btnSet = this.#_btnSet;
+    _btnSet.enableGroup('move_bkwd');
+    _btnSet.enableGroup('move_frwd');
+  }
+
+  /**
+   * Enables all buttons in 'move_bkwd' group.
+   * @returns {void}
+   */
+  enableBkwd() {
+    this.#_btnSet.enableGroup('move_bkwd');
+  }
+
+  /**
+   * Enables all buttons in 'move_frwd' group.
+   * @returns {void}
+   */
+  enableFrwd() {
+    this.#_btnSet.enableGroup('move_frwd');
+  }
+
+  /**
+   * Sets a callback function to handle event.
+   * @param {string} name - event name
+   * @param {func} evnt - callback function
+   * @returns {void}
+   */
+  on(name, evnt) {
+    pushEventHandler(this.#_events, name, evnt);
+  }
+};
+
+// === module exports block ===
+
+exports.THtmlListButtonsController = THtmlListButtonsController;
+
+exports.BTS_DEF_GROUP_NAME = BTS_DEF_GROUP_NAME;

package/lib/lists-stubs.js

@@ -0,0 +1,298 @@
+// [v0.1.051-20251002]
+
+// === module init block ===
+
+const {
+  isArray, isObject, isPlainObject,
+} = require('@ygracs/bsfoc-lib-js');
+
+const {
+  isHTMLElement,
+} = require('@cntwg/html-helper');
+
+// === module inner block ===
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
+/***
+ * (* function definitions *)
+ */
+
+/***
+ * (* class definitions *)
+ */
+
+/**
+ * A settings to load a stub-elements.
+ * @typedef {Object} OPT_ldstubs
+ * @property {string} [defaultItem] - <*deprecated*> a default element name
+ * @property {boolean} [useClear=true] - to clear before load an elements
+ * @property {boolean} [force=false] - run in a force mode
+ * @todo [since v0.0.26] `defaultItem`-option deprecated
+ */
+
+/**
+ * A stub-elements description list.
+ * @typedef {Object} OBJ_stubEList
+ * @property {Array} items - array of `name`-`element` pairs
+ * @property {string} [defaultItem] - a default element name
+ */
+
+/**
+ * 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
+ */
+
+/**
+ * @classdesc This class implements an interface of a stub-items set
+ */
+class THtmlStubItemsSet {
+  /** @type {?HTMLElement} */
+  #_host;
+  /** @type {Map<string, HTMLElement>} */
+  #_items;
+  /** @type {string} */
+  #_defItem;
+  #_shownItem = null;
+
+  /**
+   * Creates an instance of a stub-items set
+   * @param {HTMLElement} host - host element
+   * @param {(array|OPT_stubconsett|OBJ_stubEList)} [opt] - options
+   * @todo [since v0.0.26] use of an `array`-type as a value of an `opt` is deprecated
+   */
+  constructor(host, opt) {
+    this.#_host = isHTMLElement(host) ? host : null;
+    this.#_items = new Map();
+    this.#_defItem = '';
+    this.#_shownItem = null;
+    if (isObject(opt)) {
+      /** @type {(OPT_stubconsett|OBJ_stubEList)} */
+      const obj = isArray(opt) ? { items: opt } : opt;
+      const { items, defaultItem, force } = obj;
+      this.loadItems({
+        items,
+        defaultItem,
+      }, {
+        force,
+      });
+    };
+  }
+
+  /**
+   * Defines a default element name
+   * @type {string}
+   */
+  get defItem() {
+    return this.#_defItem;
+  }
+
+  set defItem(name) {
+    this.setDefItem(name);
+  }
+
+  /**
+   * Contains a Qty of an elements
+   * @type {number}
+   * @readonly
+   */
+  get count() {
+    return this.#_items.size;
+  }
+
+  /**
+   * Clears an instance content.
+   * @returns {void}
+   * @todo check if any item is shown
+   */
+  clear() {
+    this.#_items.clear();
+    this.#_defItem = '';
+    this.#_shownItem = null;
+  }
+
+  /**
+   * Sets a default item.
+   * @param {string} name - an element name
+   * @returns {boolean}
+   */
+  setDefItem(name) {
+    let isACCEPTED = false;
+    if (typeof name === 'string') {
+      const _name = name.trim();
+      isACCEPTED = this.#_items.has(_name);
+      if (isACCEPTED) this.#_defItem = _name;
+    };
+    return isACCEPTED;
+  }
+
+  /**
+   * Resets a default item.
+   * @returns {void}
+   * @todo check if item is shown
+   */
+  rstDefItem() {
+    this.#_defItem = '';
+  }
+
+  /**
+   * Checks if an item exists.
+   * @param {string} name - an element name
+   * @returns {boolean}
+   */
+  hasItem(name) {
+    const _name = typeof name === 'string' ? name.trim() : '';
+    return this.#_items.has(_name);
+  }
+
+  /**
+   * Checks if any items exists.
+   * @returns {boolean}
+   */
+  hasItems() {
+    return this.#_items.size > 0;
+  }
+
+  /**
+   * Returns an item by its name.
+   * @param {string} name - an element name
+   * @returns {?HTMLElement}
+   */
+  getItem(name) {
+    const _name = typeof name === 'string' ? name.trim() : '';
+    const item = this.#_items.has(_name) ? this.#_items.get(_name) : null;
+    return isHTMLElement(item) ? item : null;
+  }
+
+  /**
+   * Adds an item to an instance members.
+   * @param {string} name - an element name
+   * @param {HTMLElement} item - an element
+   * @param {boolean} [opt=false] - flag indicating a force mode
+   * @returns {boolean}
+   */
+  addItem(name, item, opt) {
+    const _name = typeof name === 'string' ? name.trim() : '';
+    let isSUCCEED = false;
+    if (_name !== '' && isHTMLElement(item)) {
+      const force = typeof opt === 'boolean' ? opt : false;
+      if (force || !this.#_items.has(_name)) {
+        this.#_items.set(_name, item);
+        isSUCCEED = true;
+      };
+    };
+    return isSUCCEED;
+  }
+
+  /**
+   * Deletes an item from an instance members.
+   * @param {string} name - an element name
+   * @returns {boolean}
+   * @todo check if item is shown
+   */
+  delItem(name) {
+    let _name = '';
+    let isSUCCEED = (
+      typeof name === 'string'
+      && ((_name = name.trim()) !== '')
+    );
+    if (isSUCCEED) {
+      this.#_items.delete(_name);
+      // // TODO: check if item is shown
+    };
+    return isSUCCEED;
+  }
+
+  /**
+   * Shows an item.
+   * @param {string} name - an element name
+   * @returns {boolean}
+   */
+  showItem(name) {
+    const item = this.getItem(name);
+    const isSUCCEED = this.#_host && item ? true : false;
+    if (isSUCCEED) this.#_host.append(item);
+    return isSUCCEED;
+  }
+
+  /**
+   * Shows a default item.
+   * @returns {boolean}
+   */
+  showDefItem() {
+    return this.showItem(this.#_defItem);
+  }
+
+  /**
+   * Hides an item.
+   * @param {string} name - an element name
+   * @returns {boolean}
+   */
+  hideItem(name) {
+    const item = this.getItem(name);
+    const isSUCCEED = this.#_host && item ? true : false;
+    if (isSUCCEED && this.#_host.contains(item)) item.remove();
+    return isSUCCEED;
+  }
+
+  /**
+   * Hides a default item.
+   * @returns {boolean}
+   */
+  hideDefItem() {
+    return this.hideItem(this.#_defItem);
+  }
+
+  /**
+   * Adds an items to an instance members.
+   * @param {(Array|OBJ_stubEList)} data - an array of entries or special object
+   * @param {(boolean|OPT_ldstubs)} [opt] - an options
+   * @returns {number}
+   * @todo [since 0.0.25] deprecate use of `opt` as `boolean`
+   * @todo [since v0.0.26] for `OPT_ldstubs` a `defaultItem`-option deprecated
+   */
+  loadItems(data, opt) {
+    /** @type {OBJ_stubEList} */
+    let {
+      items,
+      defaultItem,
+    } = isPlainObject(data) ? data : { items: data };
+    /** @type {OPT_ldstubs} */
+    let _options = isPlainObject(opt) ? opt : { useClear: opt };
+    let {
+      useClear,
+      force,
+    } = _options;
+    if (typeof useClear !== 'boolean') useClear = true;
+    if (typeof force !== 'boolean') force = false;
+    if (defaultItem === undefined) defaultItem = _options.defaultItem;  /* deprecated */
+    const setDefs = defaultItem !== undefined;
+    let count = 0;
+    if (isArray(items)) {
+      if (useClear) this.clear();
+      items.forEach((obj) => {
+        if (isArray(obj)) {
+          const [ name, item ] = obj;
+          if (this.addItem(name, item, force)) count++;
+        } else if (isPlainObject(obj)) {
+          const { name, item } = obj;
+          if (this.addItem(name, item, force)) count++;
+        };
+      });
+    };
+    if (setDefs && count > 0) this.setDefItem(defaultItem);
+    return count;
+  }
+
+};
+
+// === module exports block ===
+
+exports.THtmlStubItemsSet = THtmlStubItemsSet;

package/lib/mod-hfunc.js

@@ -0,0 +1,66 @@
+// [v0.1.064-20250831]
+
+// === module init block ===
+
+const {
+  eventHelper, // [!] not oficialy exported yet
+} = require('@cntwg/html-helper');
+
+// === module inner block ===
+
+const {
+  pushEventHandler, removeEventHandler,
+  triggerEventHandler,
+} = eventHelper;
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
+/***
+ * (* function definitions *)
+ */
+
+/**
+ * @function readOnClickEventInfo
+ * @param {object}
+ * @returns {object}
+ * @inner
+ */
+function readOnClickEventInfo(e) {
+  let item = null;
+  const { eventPhase, detail: onClickNum } = e;
+  //console.log('CHECK: e => ditail:['+onClickNum+']');
+  //console.log('CHECK: e => phase:['+eventPhase+']');
+  switch (eventPhase) {
+    //*case 1:
+    //* // NOTE: currently on eventPhase = 2 and 3
+    case 2: {
+      /**/// capturing stage
+      item = e.target;
+      break;
+    }
+    case 3: {
+      /**/// bubblig stage
+      item = e.currentTarget;
+      break;
+    }
+    default: {}
+  };
+  return { item, onClickNum };
+};
+
+/***
+ * (* class definitions *)
+ */
+
+// === module exports block ===
+
+module.exports.readOnClickEventInfo = readOnClickEventInfo;
+
+// * re-exported *
+module.exports.pushEventHandler = pushEventHandler;
+module.exports.removeEventHandler = removeEventHandler;
+module.exports.triggerEventHandler = triggerEventHandler;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@cntwg/html-ctrls-lists",
+  "version": "0.0.27",
+  "description": "An HTML-form component: lists",
+  "author": "ygracs <cs70th-om@rambler.ru>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/cntwg/html-ctrls-lists.git"
+  },
+  "keywords": [
+    "electron",
+    "html",
+    "component"
+  ],
+  "main": "./index.js",
+  "files": [
+    "doc/*.md",
+    "lib/lists-stubs.js",
+    "lib/lists-btn.js",
+    "lib/list.js",
+    "lib/mod-hfunc.js",
+    "index.js",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "jest",
+    "test-lc2:bs": "jest THtmlItemsListController/base",
+    "test-lc2:ec": "jest THtmlItemsListController/events",
+    "build-doc-md": "jsdoc2md",
+    "build-doc-html": "jsdoc"
+  },
+  "imports": {
+    "#lib/*": "./lib/*",
+    "#test-dir/*": "./__test__/*"
+  },
+  "dependencies": {
+    "@cntwg/html-ctrls-buttons": "^0.0.27",
+    "@cntwg/html-helper": "^0.0.27",
+    "@ygracs/bsfoc-lib-js": "^0.3.0",
+    "@ygracs/lists-lib-js": "^0.1.0"
+  },
+  "devDependencies": {
+    "jest": "^30.2.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "jsdoc-to-markdown": "^9.1.2",
+    "minimist": "^1.2.8"
+  }
+}