@cntwg/html-ctrls-lists 0.0.30 → 0.0.32

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.057-20260505]
 
 // === 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,
@@ -280,4 +297,4 @@ class THtmlStubItemsSet {
   }
 
 };
-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,32 +1,23 @@
-// [v0.1.065-20260110]
+// [v0.1.068-20260422]
 
 // === 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 *)
+/**
+ * 
+ * @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) {
@@ -51,16 +42,4 @@ function readOnClickEventInfo(e) {
   };
   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

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/html-ctrls-lists",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "description": "An HTML-form component: lists",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -14,35 +14,40 @@
     "component"
   ],
   "main": "./index.js",
+  "types": "./index.d.ts",
   "files": [
     "doc/*.md",
     "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.0.30",
-    "@cntwg/html-helper": "~0.1.2",
+    "@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.1.2"
+    "@ygracs/lists-lib-js": "~0.2.1"
   },
   "devDependencies": {
     "@ygracs/test-helper": "~0.0.2-b",
-    "jest": "^30.2.0",
-    "jest-environment-jsdom": "^30.2.0",
+    "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"
   }
 }