@cntwg/html-ctrls-lists 0.0.31 → 0.0.33

package/lib/lists-btn.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A description for list buttons set.
+ */
+export type listButtonsSetDesc = {
+    /**
+     * - button 'move to first'
+     */
+    btnFirst: HTMLElement | null;
+    /**
+     * - button 'move to previous'
+     */
+    btnPrev: HTMLElement | null;
+    /**
+     * - button 'move to next'
+     */
+    btnNext: HTMLElement | null;
+    /**
+     * - button 'move to last'
+     */
+    btnLast: HTMLElement | null;
+};
+export const BTS_DEF_GROUP_NAME: "all";
+
+/**
+ * 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>.
+ */
+export class THtmlListButtonsController {
+    /**
+     * Creates an instance of a buttons set.
+     */
+    constructor(opt?: listButtonsSetDesc);
+    /**
+     * Disables all buttons.
+     */
+    disableAll(): void;
+    /**
+     * Disables all buttons in 'move_bkwd' group.
+     */
+    disableBkwd(): void;
+    /**
+     * Disables all buttons in 'move_frwd' group.
+     */
+    disableFrwd(): void;
+    /**
+     * Enables all buttons.
+     */
+    enableAll(): void;
+    /**
+     * Enables all buttons in 'move_bkwd' group.
+     */
+    enableBkwd(): void;
+    /**
+     * Enables all buttons in 'move_frwd' group.
+     */
+    enableFrwd(): void;
+    /**
+     * Sets a callback function to handle event.
+     */
+    on(name: string, evnt: Function): void;
+    #private;
+}

package/lib/lists-btn.js

@@ -1,4 +1,4 @@
-// [v0.1.061-20260309]
+// [v0.1.063-20260505]
 
 // === module init block ===
 
@@ -18,7 +18,7 @@ const {
 
 const {
   readOnClickEventInfo,
-} = require('./mod-hfunc.js');
+} = require('./mod-hfunc');
 
 // === module inner block ===
 
@@ -33,6 +33,7 @@ const {
 // === module main block ===
 
 const BTS_DEF_GROUP_NAME = 'all';
+module.exports.BTS_DEF_GROUP_NAME = BTS_DEF_GROUP_NAME;
 
 /**
  * A description for list buttons set.
@@ -103,10 +104,9 @@ class THtmlListButtonsController {
   }
 
   /**
-   * @param {Event} e - event
+   * @param {UIEvent} 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...`);
@@ -125,7 +125,6 @@ class THtmlListButtonsController {
    * @param {string} name - event name
    * @param {...any} args
    * @returns {void}
-   * @private
    * @see triggerEventHandler
    */
   #_triggerEvent = (name, ...args) => {
@@ -194,8 +193,4 @@ class THtmlListButtonsController {
     pushEventHandler(this.#_events, name, evnt);
   }
 };
-exports.THtmlListButtonsController = THtmlListButtonsController;
-
-// === module exports block ===
-
-exports.BTS_DEF_GROUP_NAME = BTS_DEF_GROUP_NAME;
+module.exports.THtmlListButtonsController = THtmlListButtonsController;

package/lib/lists-stubs.d.ts

@@ -0,0 +1,134 @@
+/**
+ * A set of options for a `THtmlStubItemsSet`-class constructor
+ */
+export type IStubItemsSetOptions = {
+    /**
+     * - array of `name`-`element` pairs
+     */
+    items: pairOfNameAndElement[];
+    /**
+     * - a default element name
+     */
+    defaultItem?: string;
+    /**
+     * - run in a force mode
+     */
+    force?: boolean | undefined;
+};
+export const IStubItemsSetOptions: IStubItemsSetOptions;
+/**
+ * A `name`-`element` pair
+ */
+export type pairOfNameAndElement = [ name: string, item: HTMLElement ];
+/**
+ * A settings to load a stub-elements.
+ */
+export type OPT_ldstubs = {
+    /**
+     * - a default element name
+     * @deprecated
+     */
+    defaultItem?: string;
+    /**
+     * - to clear before load an elements
+     */
+    useClear?: boolean;
+    /**
+     * - run in a force mode
+     */
+    force?: boolean;
+};
+/**
+ * A stub-elements list descriptor
+ */
+export type IStubEListDesc = {
+    /**
+     * - array of `name`-`element` pairs
+     */
+    items: pairOfNameAndElement[];
+    /**
+     * - a default element name
+     */
+    defaultItem?: string;
+};
+
+/**
+ * This class implements an interface of a stub-items set
+ */
+export class THtmlStubItemsSet {
+    /**
+     * Creates an instance of a stub-items set
+     * @todo [since v0.0.26] use of an `array`-type as a value of an `opt` is deprecated
+     */
+    constructor(host: HTMLElement, opt?: pairOfNameAndElement[] | IStubEListDesc | IStubItemsSetOptions);
+    /**
+     * Defines a default element name
+     * @type {string}
+     */
+    set defItem(name: string);
+    get defItem(): string;
+    /**
+     * Contains a Qty of an elements
+     * @type {number}
+     */
+    get count(): number;
+    /**
+     * Clears an instance content.
+     * @todo check if any item is shown
+     */
+    clear(): void;
+    /**
+     * Sets a default item.
+     */
+    setDefItem(name: string): boolean;
+    /**
+     * Resets a default item.
+     * @todo check if item is shown
+     */
+    rstDefItem(): void;
+    /**
+     * Checks if an item exists.
+     */
+    hasItem(name: string): boolean;
+    /**
+     * Checks if any items exists.
+     */
+    hasItems(): boolean;
+    /**
+     * Returns an item by its name.
+     */
+    getItem(name: string): HTMLElement | null;
+    /**
+     * Adds an item to an instance members.
+     */
+    addItem(name: string, item: HTMLElement, opt?: boolean): boolean;
+    /**
+     * Deletes an item from an instance members.
+     * @todo check if item is shown
+     */
+    delItem(name: string): boolean;
+    /**
+     * Shows an item.
+     */
+    showItem(name: string): boolean;
+    /**
+     * Shows a default item.
+     */
+    showDefItem(): boolean;
+    /**
+     * Hides an item.
+     */
+    hideItem(name: string): boolean;
+    /**
+     * Hides a default item.
+     */
+    hideDefItem(): boolean;
+    /**
+     * Adds an items to an instance members.
+     * @todo [since 0.0.25] deprecate use of `opt` as `boolean`
+     * @todo [since v0.0.26] for `OPT_ldstubs` a `defaultItem`-option deprecated
+     * @todo [since 0.0.32] deprecate use of `data` as `array`
+     */
+    loadItems(data: pairOfNameAndElement[] | IStubEListDesc, opt?: boolean | OPT_ldstubs): number;
+    #private;
+}

package/lib/lists-stubs.js

@@ -1,4 +1,4 @@
-// [v0.1.053-20260309]
+// [v0.1.058-20260510]
 
 // === module init block ===
 
@@ -14,6 +14,11 @@ const {
 
 // === module main block ===
 
+/**
+ * A `name`-`element` pair
+ * @typedef {any[]} pairOfNameAndElement
+ */
+
 /**
  * A settings to load a stub-elements.
  * @typedef {Object} OPT_ldstubs
@@ -24,19 +29,24 @@ const {
  */
 
 /**
- * A stub-elements description list.
- * @typedef {Object} OBJ_stubEList
- * @property {Array} items - array of `name`-`element` pairs
+ * A stub-elements list descriptor
+ * @typedef {Object} IStubEListDesc
+ * @property {pairOfNameAndElement[]} 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
+ * A set of options for a `THtmlStubItemsSet`-class constructor
+ * @typedef {Object} IStubItemsSetOptions
+ * @property {pairOfNameAndElement[]} items - array of `name`-`element` pairs
  * @property {string} [defaultItem] - a default element name
  * @property {boolean} [force=false] - run in a force mode
  */
+/** 
+ * A virtual constant meant for support jsdoc notation:
+ * @type {IStubItemsSetOptions}
+ */
+module.exports.IStubItemsSetOptions = { items: [] };
 
 /**
  * @classdesc This class implements an interface of a stub-items set
@@ -53,7 +63,7 @@ class THtmlStubItemsSet {
   /**
    * Creates an instance of a stub-items set
    * @param {HTMLElement} host - host element
-   * @param {(any[]|OPT_stubconsett|OBJ_stubEList)} [opt] - options
+   * @param {pairOfNameAndElement[]|IStubEListDesc|IStubItemsSetOptions} [opt] - options
    * @todo [since v0.0.26] use of an `array`-type as a value of an `opt` is deprecated
    */
   constructor(host, opt) {
@@ -62,7 +72,7 @@ class THtmlStubItemsSet {
     this.#_defItem = '';
     this.#_shownItem = null;
     if (isObject(opt)) {
-      /** @type {(OPT_stubconsett|OBJ_stubEList)} */
+      /** @type {IStubItemsSetOptions} */
       const obj = isArray(opt) ? { items: opt } : opt;
       const { items, defaultItem, force } = obj;
       this.loadItems({
@@ -205,9 +215,12 @@ class THtmlStubItemsSet {
    */
   showItem(name) {
     const item = this.getItem(name);
-    const isSUCCEED = this.#_host && item ? true : false;
-    if (isSUCCEED) this.#_host.append(item);
-    return isSUCCEED;
+    let isSucceed = false;
+    if (this.#_host && item) {
+      this.#_host.append(item);
+      isSucceed = true;
+    };
+    return isSucceed;
   }
 
   /**
@@ -225,9 +238,12 @@ class THtmlStubItemsSet {
    */
   hideItem(name) {
     const item = this.getItem(name);
-    const isSUCCEED = this.#_host && item ? true : false;
-    if (isSUCCEED && this.#_host.contains(item)) item.remove();
-    return isSUCCEED;
+    let isSucceed =  false;
+    if (this.#_host && item && this.#_host.contains(item)) {
+      isSucceed =  true;
+      item.remove();
+    };
+    return isSucceed;
   }
 
   /**
@@ -240,14 +256,15 @@ class THtmlStubItemsSet {
 
   /**
    * 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
+   * @param {pairOfNameAndElement[]|IStubEListDesc} 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
+   * @todo [since 0.0.32] deprecate use of `data` as `array`
    */
   loadItems(data, opt) {
-    /** @type {OBJ_stubEList} */
+    /** @type {IStubEListDesc} */
     let {
       items,
       defaultItem,
@@ -261,7 +278,6 @@ class THtmlStubItemsSet {
     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();
@@ -275,9 +291,9 @@ class THtmlStubItemsSet {
         };
       });
     };
-    if (setDefs && count > 0) this.setDefItem(defaultItem);
+    if (defaultItem && count > 0) this.setDefItem(defaultItem);
     return count;
   }
 
 };
-exports.THtmlStubItemsSet = THtmlStubItemsSet;
+module.exports.THtmlStubItemsSet = THtmlStubItemsSet;

package/lib/mod-hfunc.d.ts

@@ -0,0 +1,18 @@
+export type IClickEventInfo = {
+    /**
+     * - some target element
+     */
+    item: object | null;
+    /**
+     * - reflects a current click count
+     */
+    onClickNum: number;
+};
+
+/**
+ * @function readOnClickEventInfo
+ * @param {UIEvent} e - event
+ * @returns {IClickEventInfo}
+ * @inner
+ */
+export function readOnClickEventInfo(e: UIEvent): IClickEventInfo;

package/lib/mod-hfunc.js

@@ -1,4 +1,4 @@
-// [v0.1.067-20260417]
+// [v0.1.068-20260422]
 
 // === module init block ===
 
@@ -6,10 +6,18 @@
 
 // === module main block ===
 
+/**
+ * 
+ * @typedef {Object} IClickEventInfo
+ * @property {?object} item - some target element
+ * @property {number} onClickNum - reflects a current click count
+ * @inner
+ */
+
 /**
  * @function readOnClickEventInfo
- * @param {Event} e
- * @returns {object}
+ * @param {UIEvent} e - event
+ * @returns {IClickEventInfo}
  * @inner
  */
 function readOnClickEventInfo(e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/html-ctrls-lists",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "description": "An HTML-form component: lists",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -14,35 +14,41 @@
     "component"
   ],
   "main": "./index.js",
+  "types": "./index.d.ts",
   "files": [
     "doc/*.md",
+    "lib/list-cont.js",
+    "lib/list-ctrl.js",
     "lib/lists-stubs.js",
     "lib/lists-btn.js",
-    "lib/list.js",
     "lib/mod-hfunc.js",
+    "lib/*.d.ts",
     "index.js",
+    "index.d.ts",
     "CHANGELOG.md"
   ],
   "scripts": {
     "test": "jest",
     "build-doc-md": "jsdoc2md",
-    "build-doc-html": "jsdoc"
+    "build-doc-html": "jsdoc",
+    "gen-dts": "npx -p typescript tsc"
   },
   "imports": {
     "#lib/*": "./lib/*",
     "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@cntwg/html-ctrls-buttons": "~0.1.0",
+    "@cntwg/html-ctrls-buttons": "~0.1.1",
     "@cntwg/html-helper": "~0.1.3",
     "@ygracs/bsfoc-lib-js": "~0.3.4",
-    "@ygracs/lists-lib-js": "~0.2.0"
+    "@ygracs/lists-lib-js": "~0.2.1"
   },
   "devDependencies": {
     "@ygracs/test-helper": "~0.0.2-b",
     "jest": "^30.3.0",
     "jest-environment-jsdom": "^30.3.0",
     "jsdoc-to-markdown": "^9.1.3",
-    "minimist": "^1.2.8"
+    "minimist": "^1.2.8",
+    "typescript": "~5.9.3"
   }
 }