@cntwg/html-helper 0.0.21 → 0.0.23

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+#### *v0.0.23*
+
+Pre-release version.
+
+> - `html-helper-lib.md` updated;
+> - `html-ctrls-list.md` updated;
+> - `html-ctrls-btn.md` updated;
+> - `html-ctrls-fields.md` updated;
+> - added property `type` to `THtmlInputField` class;
+> - change pattern for an element manipulation functions (*see docs for details*);
+> - deprecate a `force` option in an `options` parameter of the `THtmlStubItemsSet` class constructor;
+> - some other fixes.
+
+#### *v0.0.22*
+
+Pre-release version.
+
+> - `html-helper-lib.md` updated;
+> - add functions `valueToElementID` into `html-helper-lib.js` module;
+> - improve behavior for `createNewHtmlElement` function.
+
 #### *v0.0.21*
 
 Pre-release version.
@@ -8,6 +29,7 @@ Pre-release version.
 > - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.2.1;
 > - remove some deprecates (*see docs for details*);
 > - change behavior for `loadItems` method of `THtmlStubItemsSet` class in handling `options` parameter (*see docs for details*);
+> - add functions `readAsTagName` and `readAsAttrName` into `html-helper-lib.js` module;
 > - added 'components' property for module exports;
 > - some other fixes.
 

package/README.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.5|
+>|***rev.*:**|0.1.7|
 >|:---|---:|
->|date:|2024-07-13|
+>|date:|2024-11-20|
 
 ## Introduction
 
@@ -16,20 +16,20 @@ This module contains the following components:
 
 - classes for working with instances maintaining a buttons set support such as:
   - `THtmlButtonsSet`,
-	- `THtmlListButtonsController`,
-	- `THtmlButtonsControllerARCSet`.
+  - `THtmlButtonsControllerARCSet`.
 
 > *For more details see `html-ctrls-btn.md` in module `doc` directory*.
 
 - classes for working with instances maintaining a lists support such as:
-	- `THtmlItemsListContainer`,
-	- `THtmlItemsListController`,
-	- `THtmlStubItemsSet`.
+  - `THtmlItemsListContainer`,
+  - `THtmlItemsListController`,
+  - `THtmlListButtonsController`,
+  - `THtmlStubItemsSet`.
 
 > *For more details see `html-ctrls-list.md` in module `doc` directory*.
 
 - classes for working with instances maintaining an input fields support such as:
-	- `THtmlInputField` (experimental, beta stage).
+  - `THtmlInputField` (experimental, beta stage).
 
 > *For more details see `html-ctrls-fields.md` in module `doc` directory*.
 

package/doc/html-ctrls-btn.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.11|
+>|***rev.*:**|0.1.15|
 >|:---|---:|
->|date:|2024-07-13|
+>|date:|2024-11-15|
 
 ## Introduction
 
@@ -14,8 +14,20 @@ By module, constants that is provided listed in the following table:
 |:---|---:|
 |`BTS_DEF_GROUP_NAME`|'all'|
 
+## Module functions
+
+<a name="isHTMLButton"></a>
+#### **isHTMLButton(obj)** => `boolean`
+
+This function checks whether or not a given object represents an HTML-button element and if so returns `true` or `false` if else.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `any` | --- | some element to be checked |
+
 ## Module classes
 
+<a name="THtmlButtonsSet"></a>
 ### **THtmlButtonsSet**
 
 This class provide a manageable collection which used to group buttons placed on an HTML-form and controls those groups and all its members.
@@ -30,145 +42,164 @@ The class constructor receives no arguments.
 
 #### class properties
 
-The table below describes a properties of a `THtmlButtonsSet` class:
-
-|property name|property type|read only|description|
-|:---|---|---|:---|
-|`ItemNames`|`array`|yes|contains a list of all buttons names|
-|`GroupNames`|`array`|yes|contains a list of all buttons groups|
-
-#### class methods
-
-##### **hasItem(name)**
-
-This method returns `true` if item named by `name` exist in the collection and `false` if else.
-
-##### **addItem(name, item\[, groups])**
-
-This method adds a "button" element given by `item` named by `name` to a set members and returns `true` if succeed. If `groups` is given the `item` will be added to a groups members listed by `groups` but only if such a group was already declared.
-
-##### **addItemToGroup(name, args)**
-
-This method adds an existing item addressed by 'name' to a members of a groups listed by 'args'. If succeed `true` is returned.
-
-##### **delItem(name)**
-
-This method deletes a "button" element named by `name` and returned `true` if succeed.
-
-##### **delItemFromGroup(name, args)**
-
-This method deletes an existing item addressed by 'name' from a members of a groups listed by 'args'. If succeed `true` is returned.
+<a name="THtmlButtonsSet+ItemNames"></a>
+##### **ItemNames**
 
-##### **renameItem(oldName, newName)**
+| property type | read only | description |
+|---|---|:---|
+| `string[]` | yes | contains a list of all buttons names |
 
-This method renames a "button" element addressed by `oldName` to its `newName`.
+<a name="THtmlButtonsSet+GroupNames"></a>
+##### **GroupNames**
 
-##### **enableItem(name)**
+| property type | read only | description |
+|---|---|:---|
+| `string[]` | yes | contains a list of all buttons groups |
 
-This methods activates a "button" element named by `name`.
+#### class methods
 
-##### **disableItem(name)**
+<a name="THtmlButtonsSet+hasItem"></a>
+##### **hasItem(name)** => `boolean`
 
-This methods inactivates a "button" element named by `name`.
+This method returns `true` if item named by `name` exist in the collection and `false` if else.
 
-##### **hasGroup(name)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an element name |
 
-This method returns `true` if an items group named by `name` exist in the collection and `false` if else.
+<a name="THtmlButtonsSet+addItem"></a>
+##### **addItem(name, item\[, group_1\[, group_2\[, group_N]]])** => `boolean`
 
-##### **addGroup(name)**
+This method adds a "button" element given by `item` named by `name` to a set members and returns `true` if succeed. If any of a `group` is given the `item` will be added to that group if such was already declared.
 
-This method adds a group given by `name`. If succeed `true` is returned.
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an element name |
+| `item` | `HTMLElement` | --- | an element |
+| `group[1...N]` | `string` | --- | a group name |
 
-##### **delGroup(name)**
+<a name="THtmlButtonsSet+addItemToGroup"></a>
+##### **addItemToGroup(name, group_1\[, group_2\[, group_N]])** => `boolean`
 
-This method deletes the group given by `name`. If succeed `true` is returned.
+This method adds an existing item addressed by `name` to a members of a groups received by a `group` parameters. If succeed `true` is returned.
 
-##### **renameGroup(oldName, newName)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an element name |
+| `group[1...N]` | `string` | --- | a group name |
 
-This method renames a group addressed by `oldName` to its `newName`.
+<a name="THtmlButtonsSet+delItem"></a>
+##### **delItem(name)** => `boolean`
 
-##### **enableGroup(name)**
+This method deletes a "button" element named by `name` and returned `true` if succeed.
 
-This method activates all "button" elements present in a group named by `name`.
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an element name |
 
-##### **disableGroup(name)**
+<a name="THtmlButtonsSet+delItemFromGroup"></a>
+##### **delItemFromGroup(name, group_1\[, group_2\[, group_N]])** => `boolean`
 
-This method inactivates all "button" elements present in a group named by `name`.
+This method deletes an existing item addressed by `name` from a groups received by a `group` parameters. If succeed `true` is returned.
 
-#### class methods (*static*)
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an element name |
+| `group[1...N]` | `string` | --- | a group name |
 
-##### **isHTMLButton(object)**
+<a name="THtmlButtonsSet+renameItem"></a>
+##### **renameItem(name, value)** => `boolean`
 
-This method checks if the given object represents a "button" element and if so `true` is returned.
+This method renames a "button" element addressed by `name` to its new name given by a `value` parameter.
 
-### **THtmlListButtonsController**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an element name |
+| `value` | `string` | --- | some new name for the element |
 
-This class provide a buttons controller to use with a list components to performs actions for list elements selection.
+<a name="THtmlButtonsSet+enableItem"></a>
+##### **enableItem(name)** => `void`
 
-#### class constructor
+This methods activates a "button" element named by `name`.
 
-The class constructor creates a new instance of the class.
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an element name |
 
-##### constructor parameters
+<a name="THtmlButtonsSet+disableItem"></a>
+##### **disableItem(name)** => `void`
 
-The class constructor receives an `options` parameter which structure has listed below:
+This methods inactivates a "button" element named by `name`.
 
-|option name|option type|default value|description|
+| parameter name | value type | default value | description |
 |:---|---|---:|:---|
-|`btnFirst`|`HTMLElement`|---|define HTML-button which will select the first element|
-|`btnPrev`|`HTMLElement`|---|define HTML-button which will select the previous element|
-|`btnNext`|`HTMLElement`|---|define HTML-button which will select the next element|
-|`btnLast`|`HTMLElement`|---|define HTML-button which will select the last element|
+| `name` | `string` | --- | an element name |
 
-#### class properties
-
-This class has none.
+<a name="THtmlButtonsSet+hasGroup"></a>
+##### **hasGroup(name)** => `boolean`
 
-#### class methods
+This method returns `true` if an items group named by `name` exist in the collection and `false` if else.
 
-##### **disableAll()**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | a group name |
 
-This method disables all buttons that holds by the controller.
+<a name="THtmlButtonsSet+addGroup"></a>
+##### **addGroup(name)** => `boolean`
 
-##### **disableBkwd()**
+This method adds a group given by `name`. If succeed `true` is returned.
 
-This method disables all buttons in *'move backward'* group (*i.e. `btnFirst` and `btnPrev`*) that holds by the controller.
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | a group name |
 
-##### **disableFrwd()**
+<a name="THtmlButtonsSet+delGroup"></a>
+##### **delGroup(name)** => `boolean`
 
-This method disables all buttons in *'move forward'* group (*i.e. `btnNext` and `btnLast`*) that holds by the controller.
+This method deletes the group given by `name`. If succeed `true` is returned.
 
-##### **enableAll()**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | a group name |
 
-This method enables all buttons that holds by the controller.
+<a name="THtmlButtonsSet+renameGroup"></a>
+##### **renameGroup(name, value)** => `boolean`
 
-##### **enableBkwd()**
+This method renames a group addressed by `name` to its new name given by a `value` parameter.
 
-This method enables all buttons in *'move backward'* group (*i.e. `btnFirst` and `btnPrev`*) that holds by the controller.
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | a group name |
+| `value` | `string` | --- | some new name for the group |
 
-##### **enableFrwd()**
+<a name="THtmlButtonsSet+enableGroup"></a>
+##### **enableGroup(name)** => `void`
 
-This method enables all buttons in *'move forward'* group (*i.e. `btnNext` and `btnLast`*) that holds by the controller.
+This method activates all "button" elements present in a group named by `name`.
 
-#### class methods (*special*)
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | a group name |
 
-##### **on(name, event)**
+<a name="THtmlButtonsSet+disableGroup"></a>
+##### **disableGroup(name)** => `void`
 
-This method sets event handler addressed by `name` parameter for the class instance.
+This method inactivates all "button" elements present in a group named by `name`.
 
-> Note: for current implementation you can't reset or set new event handler (*especially another one*) if a handler with the same name exists already.
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | a group name |
 
-#### class events
+#### class properties (*static*)
 
-The class generates the events listed in the table bellow:
+<a name="THtmlButtonsSet.isHTMLButton"></a>
+##### **isHTMLButton**
 
-|event name|description|
-|:---|:---|
-|`btn-first-pressed`|fired if the `btnFirst` was pressed|
-|`btn-prev-pressed`|fired if the `btnPrev` was pressed|
-|`btn-next-pressed`|fired if the `btnNext` was pressed|
-|`btn-last-pressed`|fired if the `btnLast` was pressed|
+| property type | read only | description |
+|---|---|:---|
+| `function` | yes | contains a default function that verified validity of an element. The function receives element and returns result for validation as a `boolean`. |
 
+<a name="THtmlButtonsControllerARCSet"></a>
 ### **THtmlButtonsControllerARCSet**
 
 This class provide a buttons controller to use with a form components to performs apply/reject actions on a form data when editing.
@@ -181,11 +212,11 @@ The class constructor creates a new instance of the class.
 
 The class constructor receives an `options` parameter which structure has listed below:
 
-|option name|option type|default value|description|
+| option name | option type | default value | description |
 |:---|---|---:|:---|
-|`btnApply`|`HTMLElement`|---|define HTML-button which will accept all changes|
-|`btnReset`|`HTMLElement`|---|define HTML-button that will require reset all changes to data if made|
-|`btnCancel`|`HTMLElement`|---|define HTML-button that will require reject all changes and close the form|
+| `btnApply` | `HTMLElement` | --- | define HTML-button which will accept all changes |
+| `btnReset` | `HTMLElement` | --- | define HTML-button that will require reset all changes to data if made |
+| `btnCancel` | `HTMLElement` | --- | define HTML-button that will require reject all changes and close the form |
 
 
 #### class properties
@@ -194,27 +225,37 @@ This class has none.
 
 #### class methods
 
-##### **disableAll()**
+<a name="THtmlButtonsControllerARCSet+disableAll"></a>
+##### **disableAll()** => `void`
 
 This method disables all buttons that holds by the controller.
 
-##### **disableMain()**
+<a name="THtmlButtonsControllerARCSet+disableMain"></a>
+##### **disableMain()** => `void`
 
 This method disables all buttons in *'main'* group (*i.e. `btnApply` and `btnReset`*) that holds by the controller.
 
-##### **enableAll()**
+<a name="THtmlButtonsControllerARCSet+enableAll"></a>
+##### **enableAll()** => `void`
 
 This method enables all buttons that holds by the controller.
 
-##### **enableMain()**
+<a name="THtmlButtonsControllerARCSet+enableMain"></a>
+##### **enableMain()** => `void`
 
 This method enables all buttons in *'main'* group (*i.e. `btnApply` and `btnReset`*) that holds by the controller.
 
 #### class methods (*special*)
 
-##### **on(name, event)**
+<a name="THtmlButtonsControllerARCSet+on"></a>
+##### **on(name, event)** => `void`
 
-This method sets event handler addressed by `name` parameter for the class instance.
+This method sets event handler addressed by a `name` parameter.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an event name |
+| `event` | `function` | --- | a callback function |
 
 > Note: for current implementation you can't reset or set new event handler (*especially another one*) if a handler with the same name exists already.
 
@@ -222,8 +263,8 @@ This method sets event handler addressed by `name` parameter for the class insta
 
 The class generates the events listed in the table bellow:
 
-|event name|description|
+| event name | description |
 |:---|:---|
-|`btn-apply-pressed`|fired if the `btnApply` was pressed|
-|`btn-reset-pressed`|fired if the `btnReset` was pressed|
-|`btn-cancel-pressed`|fired if the `btnCancel` was pressed|
+| `btn-apply-pressed` | fired if the `btnApply` was pressed |
+| `btn-reset-pressed` | fired if the `btnReset` was pressed |
+| `btn-cancel-pressed` | fired if the `btnCancel` was pressed |