@cntwg/html-ctrls-lists 0.0.31 → 0.0.33

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+#### *v0.0.33*
+
+Pre-release version.
+
+> - some fixes.
+
+#### *v0.0.32*
+
+Pre-release version.
+
+> - update `html-ctrls-list.md`;
+> - update dependency on `@ygracs/lists-lib-js` module to v0.2.1;
+> - update dependency on `@cntwg/html-ctrls-buttons` module to v0.1.1;
+> - (THtmlStubItemsSet) change method behavior: `loadItems`;
+> - some fixes.
+
 #### *v0.0.31*
 
 Pre-release version.

package/doc/html-ctrls-list.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.25|
+>|***rev.*:**|0.1.27|
 >|:---|---:|
->|date:|2026-04-18|
+>|date:|2026-05-05|
 
 ## Introduction
 
@@ -119,12 +119,12 @@ This method returns `true` if the container has at least one item.
 <a name="THtmlItemsListContainer+chkIndex"></a>
 ###### **chkIndex(value)** => `boolean`
 
-> WARNING: \[since `v0.0.3x`] this method deprecated (*use [`checkIndex`](#THtmlItemsListContainer+checkIndex) method instead*).
+> WARNING: \[since `v0.0.31`] this method deprecated (*use [`checkIndex`](#THtmlItemsListContainer+checkIndex) method instead*).
 
 <a name="THtmlItemsListContainer+checkIndex"></a>
 ###### **checkIndex(value)** => `boolean`
 
-> since: \[`v0.0.3x`]
+> since: \[`v0.0.31`]
 
 This method checks if the given `value` represents a valid index value and fits the range of all possible indexes belonging to the list instance. If so `true` is returned.
 
@@ -135,7 +135,7 @@ This method checks if the given `value` represents a valid index value and fits
 <a name="THtmlItemsListContainer+tryIndex"></a>
 ###### **tryIndex(value)** => `number`
 
-> since: \[`v0.0.3x`]
+> since: \[`v0.0.31`]
 
 This method evaluates whether the given `value` represents a valid index value and fits the range of all possible indexes belonging to the list instance. If so an index value returned. If failed a `-1` will be returned.
 
@@ -159,7 +159,7 @@ The `mode` parameter treats as follows:
 - if set to `true`, the result returned by the method is an index;
 - if not given or has a type of not a `boolean`, the default value is used.
 
-> WARNING: \[since `v0.0.3x`] this method deprecated (*use [`checkIndex`](#THtmlItemsListContainer+checkIndex) or [`tryIndex`](#THtmlItemsListContainer+tryIndex) method instead*).
+> WARNING: \[since `v0.0.31`] this method deprecated (*use [`checkIndex`](#THtmlItemsListContainer+checkIndex) or [`tryIndex`](#THtmlItemsListContainer+tryIndex) method instead*).
 
 <a name="THtmlItemsListContainer+srchIndex"></a>
 ###### **srchIndex(item)** => `number`
@@ -452,12 +452,12 @@ This method returns `true` if the list has at least one item.
 <a name="THtmlItemsListController+chkIndex"></a>
 ###### **chkIndex(value)** => `boolean`
 
-> WARNING: \[since `v0.0.3x`] this method deprecated (*use [`checkIndex`](#THtmlItemsListController+checkIndex) method instead*).
+> WARNING: \[since `v0.0.31`] this method deprecated (*use [`checkIndex`](#THtmlItemsListController+checkIndex) method instead*).
 
 <a name="THtmlItemsListController+checkIndex"></a>
 ###### **checkIndex(value)** => `boolean`
 
-> since: \[`v0.0.3x`]
+> since: \[`v0.0.31`]
 
 This method checks if the given `value` represents a valid index value and fits the range of all possible indexes belonging to the list instance. If so `true` is returned.
 
@@ -468,7 +468,7 @@ This method checks if the given `value` represents a valid index value and fits
 <a name="THtmlItemsListController+tryIndex"></a>
 ###### **tryIndex(value)** => `number`
 
-> since: \[`v0.0.3x`]
+> since: \[`v0.0.31`]
 
 This method evaluates whether the given `value` represents a valid index value and fits the range of all possible indexes belonging to the list instance. If so an index value returned. If failed a `-1` will be returned.
 
@@ -490,7 +490,7 @@ If `mode` parameter set to `false` (*its default value*), the result returned by
 
 If `mode` parameter set to `true`, the result returned by the method has an index type.
 
-> WARNING: \[since `v0.0.3x`] this method deprecated (*use [`checkIndex`](#THtmlItemsListController+checkIndex) or [`tryIndex`](#THtmlItemsListController+tryIndex) method instead*).
+> WARNING: \[since `v0.0.31`] this method deprecated (*use [`checkIndex`](#THtmlItemsListController+checkIndex) or [`tryIndex`](#THtmlItemsListController+tryIndex) method instead*).
 
 <a name="THtmlItemsListController+srchIndex"></a>
 ###### **srchIndex(item)** => `number`
@@ -816,6 +816,7 @@ This class methods loads an items given by `list` in the set and returned quanti
 | `options` | `boolean`, `object` | --- | an options |
 
 > \[!] NOTE: *`[since v0.0.25]`* the use of a booleans as an `options` value is deprecated and will be dropped soon.
+> \[!] NOTE: *`[since v0.0.32]`* the use of an array as an `data` value is deprecated and will be dropped soon.
 
 If the `data` parameter is an `object` that contains the following set of values:
 

package/index.d.ts

@@ -0,0 +1,32 @@
+import {
+    THtmlStubItemsSet,
+    type IStubItemsSetOptions,
+} from "./lib/lists-stubs";
+
+import {
+    BTS_DEF_GROUP_NAME,
+    THtmlListButtonsController,
+} from "./lib/lists-btn";
+
+import {
+    THtmlItemsListContainer,
+    type ITHtmlItemsListContainerOptions,
+} from "./lib/list-cont";
+
+import {
+    THtmlItemsListController,
+    type IHtmlItemsListControllerOptions,
+} from "./lib/list-ctrl";
+
+export {
+    THtmlStubItemsSet,
+    THtmlItemsListContainer, THtmlItemsListController,
+    BTS_DEF_GROUP_NAME,
+    THtmlListButtonsController,
+};
+
+export type {
+    ITHtmlItemsListContainerOptions,
+    IHtmlItemsListControllerOptions,
+    IStubItemsSetOptions,
+};

package/index.js

@@ -1,10 +1,26 @@
-// [v0.1.031-20260309]
+// [v0.1.034-20260510]
 
 // === module init block ===
 
-const list = require('./lib/list');
+const {
+  THtmlItemsListContainer,
+  // * import types definitions *
+  ITHtmlItemsListContainerOptions,
+} = require('./lib/list-cont');
+
+const {
+  THtmlItemsListController,
+  // * import types definitions *
+  IHtmlItemsListControllerOptions,
+} = require('./lib/list-ctrl');
+
+const {
+  THtmlStubItemsSet,
+  // * import types definitions *
+  IStubItemsSetOptions,
+} = require('./lib/lists-stubs');
+
 const btn = require('./lib/lists-btn');
-const stubs = require('./lib/lists-stubs');
 
 // === module inner block ===
 
@@ -12,11 +28,16 @@ const stubs = require('./lib/lists-stubs');
 
 // === module exports block ===
 
-module.exports.THtmlStubItemsSet = stubs.THtmlStubItemsSet;
+module.exports.THtmlStubItemsSet = THtmlStubItemsSet;
 
-module.exports.THtmlItemsListContainer = list.THtmlItemsListContainer;
-module.exports.THtmlItemsListController = list.THtmlItemsListController;
+module.exports.THtmlItemsListContainer = THtmlItemsListContainer;
+module.exports.THtmlItemsListController = THtmlItemsListController;
 
 module.exports.BTS_DEF_GROUP_NAME = btn.BTS_DEF_GROUP_NAME;
 
 module.exports.THtmlListButtonsController = btn.THtmlListButtonsController;
+
+// * export types definitions *
+module.exports.ITHtmlItemsListContainerOptions = ITHtmlItemsListContainerOptions;
+module.exports.IHtmlItemsListControllerOptions = IHtmlItemsListControllerOptions;
+module.exports.IStubItemsSetOptions = IStubItemsSetOptions;

package/lib/list-cont.d.ts

@@ -0,0 +1,207 @@
+/**
+ * An options set for `THtmlItemsListContainer`-class
+ */
+export type ITHtmlItemsListContainerOptions = {
+    /**
+     * - 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;
+};
+export const ITHtmlItemsListContainerOptions: ITHtmlItemsListContainerOptions;
+
+export type ISearchListElementResultOnFail = {
+    /**
+     * - element index
+     */
+    index: number;
+    /**
+     * - found element
+     */
+    item: null;
+};
+export type ISearchListElementResultOnSuccess = {
+    /**
+     * - element index
+     */
+    index: number;
+    /**
+     * - found element
+     */
+    item: any;
+};
+export type ISearchListElementResult = ISearchListElementResultOnFail | ISearchListElementResultOnSuccess;
+
+/**
+ * This class implements an interfaco for a list container
+ */
+export class THtmlItemsListContainer {
+    /**
+     * Creates an instance of a list container
+     */
+    constructor(host: HTMLElement | null, opt?: ITHtmlItemsListContainerOptions);
+    /**
+     * Contains a Qty of an elements
+     */
+    get count(): number;
+    /**
+     * Contains an index of the current element
+     */
+    get curIndex(): number;
+    /**
+     * Returns a minimum value of an index
+     */
+    get minIndex(): number;
+    /**
+     * Returns a maximum value of an index
+     */
+    get maxIndex(): number;
+    /**
+     * Returns a value of a previous index
+     */
+    get prevIndex(): number;
+    /**
+     * Returns a value of a next index
+     */
+    get nextIndex(): number;
+    /**
+     * Returns an element in the current index
+     */
+    get curItem(): HTMLElement | null;
+    /**
+     * Clears an instance content.
+     */
+    clear(): void;
+    /**
+     * Checks if an instance contains no items.
+     */
+    isEmpty(): boolean;
+    /**
+     * Checks if an instance contains any items.
+     */
+    isNotEmpty(): boolean;
+    /**
+     * Checks if a given value is a valid index and
+     * it fits an index range within an instance.
+     * @deprecated
+     * @todo \[since v0.0.31] deprecated. Use
+     *     {@link THtmlItemsListContainer.checkIndex} instead
+     */
+    chkIndex(value: number | string): boolean;
+    /**
+     * Checks if a given value is a valid index and
+     * it fits an index range within an instance.
+     * @since 0.0.31
+     */
+    checkIndex(value: number | string): boolean;
+    /**
+     * Checks if a given value is a valid index and
+     * it fits an index range within an instance.
+     * @deprecated
+     * @todo \[since v0.0.31] deprecated. Use
+     *     {@link THtmlItemsListContainer.checkIndex} or
+     *     {@link THtmlItemsListContainer.tryIndex} instead
+     */
+    chkIndexEx(value: number | string, opt?: boolean): boolean | number;
+    /**
+     * 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
+     */
+    tryIndex(value: any): number;
+    /**
+     * Returns an index of a given element.
+     * @param {HTMLElement} item  - element to search
+     * @todo add 2nd param
+     * @see TItemsListEx.srchIndex
+     */
+    srchIndex(item: HTMLElement): number;
+    /**
+     * Returns an index of an element wich has an attribute
+     * with a given name and value.
+     */
+    srchIndexByAttr(name: string, value?: any): number;
+    /**
+     * Returns an index of an element wich has a given ID.
+     */
+    srchIndexByID(value: string): number;
+    /**
+     * Sets a current index.
+     */
+    setCurIndex(index: number | string): boolean;
+    /**
+     * Resets a current index.
+     */
+    rstCurIndex(): void;
+    /**
+     * Returns an item addressed by a given index.
+     */
+    getItem(index: number | string): HTMLElement | null;
+    /**
+     * Returns an item wich has an attribute with a given name and value.
+     */
+    getItemByAttr(name: string, value?: any): HTMLElement | null;
+    /**
+     * Returns an item wich has a given ID.
+     */
+    getItemByID(value: string): HTMLElement | null;
+    /**
+     * Adds an item to an instance.
+     */
+    addItem(item: HTMLElement, opt?: boolean): number;
+    /**
+     * Deletes an item from an instance.
+     */
+    delItem(index: number | string, opt?: any, optEx?: boolean): boolean;
+    /**
+     * Selects an item addressed by a given index.
+     */
+    selectItem(index: number | string, opt?: boolean): boolean;
+    /**
+     * Unselects an item addressed by a given index.
+     */
+    unselectItem(index: number | string): boolean;
+    /**
+     * Hides an item addressed by a given index.
+     */
+    hideItem(index: number | string): boolean;
+    /**
+     * Shows an item addressed by a given index.
+     */
+    showItem(index: number | string): boolean;
+    /**
+     * Checks whether an item is selected.
+     */
+    isSelectedItem(index: number | string): boolean;
+    /**
+     * Checks whether an item is hidden.
+     */
+    isHiddenItem(index: number | string): boolean;
+    [Symbol.iterator](): {
+        next: () => {
+            done: boolean;
+            value: HTMLElement | null;
+        } | {
+            done: boolean;
+            value: undefined;
+        };
+        return(): {
+            done: boolean;
+            value: undefined;
+        };
+    };
+    #private;
+}