@cntwg/html-helper 0.0.20 → 0.0.21

package/lib/html-ctrls/buttons.js

@@ -1,4 +1,4 @@
-// [v0.1.049-20230614]
+// [v0.1.050-20240705]
 
 // === module init block ===
 
@@ -54,13 +54,29 @@ function isHTMLButton(obj){
   return result;
 }
 
-// === module main block (function definitions) ===
+// === module main block ===
 
-// === module main block (class definitions) ===
+/***
+ * (* constant definitions *)
+ */
 
+/***
+ * (* function definitions *)
+ */
+
+/***
+ * (* class definitions *)
+ */
+
+/**
+ * @description This class implements an instance of a buttons set
+ */
 class THtmlButtonsSet {
   #_btnCol = null;
 
+  /**
+   * @param {none}
+   */
   constructor(){
     // define default functions for manipulators
     const __user_index_getter = (value) => {
@@ -79,82 +95,181 @@ class THtmlButtonsSet {
     });
   }
 
+  /**
+   * @property {array}
+   * @readonly
+   * @see TItemsICollection.ItemNames
+   */
   get ItemNames(){
     return this.#_btnCol.ItemNames;
   }
 
+  /**
+   * @property {array}
+   * @readonly
+   * @see TItemsICollection.CategoryNames
+   */
   get GroupNames(){
     return this.#_btnCol.CategoryNames;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {bool}
+   * @see TItemsICollection.hasItem
+   * @description Checks whether a target item with a given name exists.
+   */
   hasItem(name){
     return this.#_btnCol.hasItem(name);
   }
 
+  /**
+   * @see TItemsICollection.addItem
+   * @description Adds buttons to a set members.
+   */
   addItem(...args){
     return this.#_btnCol.addItem(...args);
   }
 
+  /**
+   * @see TItemsICollection.addItemToCategory
+   * @description Adds button to a listed groups.
+   */
   addItemToGroup(...args){
     return this.#_btnCol.addItemToCategory(...args);
   }
 
+  /**
+   * @param {ID_STRING}
+   * @see TItemsICollection.delItem
+   * @description Deletes button from a set members.
+   */
   delItem(name){
     return this.#_btnCol.delItem(name);
   }
 
+  /**
+   * @see TItemsICollection.delItemFromGroup
+   * @description Deletes button from a listed groups.
+   */
   delItemFromGroup(...args){
     return this.#_btnCol.delItemFromGroup(...args);
   }
 
+  /**
+   * @param {ID_STRING} - old name
+   * @param {ID_STRING} - new name
+   * @see TItemsICollection.renameItem
+   * @description Renames button in a set.
+   */
   renameItem(oldName, newName){
     return this.#_btnCol.renameItem(oldName, newName, false);
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {none}
+   * @description Tries to enable button.
+   */
   enableItem(name){
     unlockHtmlElement(this.#_btnCol.getItem(name));
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {none}
+   * @description Tries to disable button.
+   */
   disableItem(name){
     lockHtmlElement(this.#_btnCol.getItem(name));
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {bool}
+   * @see TItemsICollection.hasCategory
+   * @description Checks whether a target group with a given name exists.
+   */
   hasGroup(name){
     return this.#_btnCol.hasCategory(name);
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {bool}
+   * @see TItemsICollection.addCategory
+   * @description Adds a group with a given name.
+   */
   addGroup(name){
     return this.#_btnCol.addCategory(name);
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {bool}
+   * @see TItemsICollection.delCategory
+   * @description Deletes a group with a given name.
+   */
   delGroup(name){
     return this.#_btnCol.delCategory(name);
   }
 
+  /**
+   * @param {ID_STRING} - old name
+   * @param {ID_STRING} - new name
+   * @returns {bool}
+   * @see TItemsICollection.renameCategory
+   * @description Renames group in a set.
+   */
   renameGroup(oldName, newName){
     return this.#_btnCol.renameCategory(oldName, newName, false);
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {none}
+   * @description Enables all buttons in a given group.
+   */
   enableGroup(value){
     const group = this.#_btnCol.getCategory(value);
     valueToArray(group).forEach(item => unlockHtmlElement(item));
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {none}
+   * @description Disables all buttons in a given group.
+   */
   disableGroup(value){
     const group = this.#_btnCol.getCategory(value);
     valueToArray(group).forEach(item => lockHtmlElement(item));
   }
 
+  /**
+   * @returns {function}
+   * @static
+   * @description Returns a function wich do a validation check.
+   */
   static get isHTMLButton(){
     return isHTMLButton;
   }
 
 };
 
+/**
+ * @description This class implements an instance of a pre-defined buttons set.
+ *              A set provide a three button: <apply>, <reset> and <cancel>.
+ */
 class THtmlButtonsControllerARCSet {
   #_btnSet = null;
   #_events = null;
 
+  /**
+   * @param {object} opt
+   * @param {HTMLElement} opt.btnApply
+   * @param {HTMLElement} opt.btnReset
+   * @param {HTMLElement} opt.btnCancel
+   */
   constructor(opt) {
     // load options
     const _options = isPlainObject(opt) ? opt : {};
@@ -194,6 +309,12 @@ class THtmlButtonsControllerARCSet {
     this.#_events = new Map();
   }
 
+  /**
+   * @param {object}
+   * @param {ID_STRING}
+   * @returns {none}
+   * @private
+   */
   #_on_btn_pressed = (e, key) => {
     //console.log(`THtmlListButtonsController._on_btn_pressed().key(${key}) ==> was called...`);
     //e.preventDefault(); /* need to reconsider reason for use */
@@ -207,26 +328,59 @@ class THtmlButtonsControllerARCSet {
     };
   }
 
+  /**
+   * @param {ID_STRING}
+   * @param {...any}
+   * @returns {none}
+   * @private
+   * @see triggerEventHandler
+   */
   #_triggerEvent = (name, ...args) => {
     triggerEventHandler(this.#_events, name, ...args);
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Disables all buttons in 'main' group.
+   */
   disableMain(){
     this.#_btnSet.disableGroup('main');
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Enables all buttons in 'main' group.
+   */
   enableMain(){
     this.#_btnSet.enableGroup('main');
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Disables all buttons.
+   */
   disableAll(){
     this.#_btnSet.disableGroup('all');
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Enables all buttons.
+   */
   enableAll(){
     this.#_btnSet.enableGroup('all');
   }
 
+  /**
+   * @param {ID_STRING}
+   * @param {func}
+   * @returns {none}
+   * @description Sets a callback function to handle event.
+   */
   on(name, evnt){
     pushEventHandler(this.#_events, name, evnt);
   }

package/lib/html-ctrls/fields.js

@@ -1,4 +1,4 @@
-// [v0.1.011-20230704]
+// [v0.1.013-20240705]
 
 // === module init block ===
 
@@ -28,7 +28,7 @@ const lpAllowedValues = new Map([
 ]);
 
 function getInputFieldTypeDescr(value){
-  let fldType = readAsString(value, '', true);
+  let fldType = readAsString(value, true);
   if (fldType === '') fldType = 'default';
   let fldSubType = '';
   switch (fldType) {
@@ -55,7 +55,7 @@ function getInputFieldTypeDescr(value){
 };
 
 function getLabelPositionID(value){
-  let key = readAsString(value, '', true);
+  let key = readAsString(value, true);
   if (!lpAllowedValues.has(key)) key = 'default';
   return lpAllowedValues.get(key);
 };
@@ -74,6 +74,9 @@ function getLabelPositionID(value){
  * (* class definitions *)
  */
 
+/**
+ * @description This class implements an instance of an input field element
+ */
 class THtmlInputField {
   #_host = null;
   #_label = null;
@@ -84,6 +87,19 @@ class THtmlInputField {
   #_status = null;
   #_events = null;
 
+  /**
+   * @param {ID_STRING} name - <*reserved*>
+   * @param {object} eholds
+   * @param {HTMLElement} eholds.host
+   * @param {HTMLElement} eholds.label
+   * @param {HTMLElement} eholds.field
+   * @param {object} [opt]
+   * @param {ID_STRING} [opt.idPref]
+   * @param {(string|array)} [opt.baseClassID]
+   * @param {string} [opt.hint]
+   * @param {object} [opt.type]
+   * @param {bool} [opt.readonly=true]
+   */
   constructor(name, eholds, opt){
     // load elements
     const _eholds = isPlainObject(eholds) ? eholds : {};
@@ -125,10 +141,17 @@ class THtmlInputField {
     this.#_events = new Map();
   }
 
+  /**
+   * @property {bool}
+   * @readonly
+   */
   get isModified(){
     return this.#_status.isModified;
   }
 
+  /**
+   * @property {string}
+   */
   get value(){
     const field = this.#_field;
     let result = '';
@@ -147,13 +170,16 @@ class THtmlInputField {
         field.checked = value;
         this.#_status.isModified = false;
       } else {
-        let _value = readAsString(value, '', {
+        let _value = readAsString(value, {
           boolToString: true,
           numberToString: true,
         });
         field.value = _value;
         this.#_status.isModified = false;
         if (_value === '') {
+          /**
+           * @see THtmlInputField#value-empty
+           */
           this.#_triggerEvent('value-empty', {
             type: 'value-empty',
             target: null,
@@ -163,21 +189,46 @@ class THtmlInputField {
     };
   }
 
+  /**
+   * @param {ID_STRING}
+   * @param {...any}
+   * @returns {none}
+   * @private
+   * @see triggerEventHandler
+   */
   #_triggerEvent = (name, ...args) => {
     triggerEventHandler(this.#_events, name, ...args);
   };
 
+  /**
+   * @param {object}
+   * @returns {none}
+   * @private
+   * @fires THtmlInputField#value-changed
+   */
   #_saveFieldData = (e) => {
     e.preventDefault();
     const target = e.target;
     //***/console.log(':'+e.type+':'+target.getAttribute('id')+':\n:saveFieldData() => received OnChange-event');
     // // TODO:
+    /**
+     * @event THtmlInputField#value-changed
+     * @type {object}
+     * @property {ID_STRING} type
+     * @property {object} target
+     */
     this.#_triggerEvent('value-changed', {
       type: 'value-changed',
       target,
     });
   };
 
+  /**
+   * @param {object}
+   * @returns {none}
+   * @private
+   * @fires THtmlInputField#value-empty
+   */
   #_switchFieldStatusOnInput = (e) => {
     e.preventDefault();
     const target = e.target;
@@ -185,6 +236,12 @@ class THtmlInputField {
     this.#_status.isModified = true;
     // // TODO:
     if (target.value === '') {
+      /**
+       * @event THtmlInputField#value-empty
+       * @type {object}
+       * @property {ID_STRING} type
+       * @property {object} target
+       */
       this.#_triggerEvent('value-empty', {
         type: 'value-empty',
         target,
@@ -192,12 +249,22 @@ class THtmlInputField {
     };
   };
 
+  /**
+   * @param {object}
+   * @returns {none}
+   * @private
+   */
   #_switchFieldStatusOnBlur = (e) => {
     e.preventDefault();
     //***/console.log(':'+e.type+':'+e.target.getAttribute('id')+':\n:switchFieldStatusOnBlur() => received OnBlur-event');
     // // TODO:
   };
 
+  /**
+   * @param {HTMLElement}
+   * @returns {bool}
+   * @description Tries to attach an element to a given target.
+   */
   attachTo(target){
     const host = this.#_host;
     let result = false;
@@ -211,26 +278,58 @@ class THtmlInputField {
     return result;
   }
 
+  /**
+   * @param {none}
+   * @returns {bool}
+   * @description Checks if a value of an element is not set.
+   */
   isEmpty(){
     return isEmptyString(this.value);
   }
 
+  /**
+   * @param {none}
+   * @returns {bool}
+   * @description Checks if a value of an element is set.
+   */
   isNotEmpty(){
     return isNotEmptyString(this.value);
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Shows an element.
+   */
   show(){
     showHtmlElement(this.#_host);
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Hides an element.
+   */
   hide(){
     hideHtmlElement(this.#_host);
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description not implemented yet.
+   */
   clear(){
     // // TODO:
   }
 
+  /**
+   * @param {ID_STRING}
+   * @param {object}
+   * @returns {?THtmlInputField}
+   * @static
+   * @description Creates a new element.
+   */
   static create(name, opt){
     const eholds = THtmlInputField.createElement(name, opt, true);
     const { field } = eholds;
@@ -241,6 +340,23 @@ class THtmlInputField {
     );
   }
 
+  /**
+   * @param {ID_STRING}
+   * @param {object} [opt]
+   * @param {object} [opt.host]
+   * @param {ID_STRING} [opt.idPref]
+   * @param {object} [opt.label]
+   * @param {object} [opt.labelPosition]
+   * @param {bool} [opt.useDelim]
+   * @param {object} [opt.baseClassID]
+   * @param {string} [opt.hint]
+   * @param {object} [opt.type]
+   * @param {bool} [opt.readonly]
+   * @param {bool} [doRetChild=false]
+   * @returns {(HTMLElement|object)}
+   * @static
+   * @description Creates a new elements.
+   */
   static createElement(name, opt, doRetChild){
     const id = valueToIDString(name);
     const _options = isPlainObject(opt) ? opt : {};
@@ -268,12 +384,12 @@ class THtmlInputField {
     bcidLabel = valueToClassList(bcidLabel);
     bcidField = valueToClassList(bcidField);
     idPref = valueToIDString(idPref);
-    hint = readAsString(hint, '', true);
+    hint = readAsString(hint, true);
     ({ type: fldType, subtype: fldSubType } = getInputFieldTypeDescr(fldType));
     if (fldSubType === 'switch') bcidField.push('switch');
     labelPosition = getLabelPositionID(labelPosition);
     if (typeof useDelim !== 'boolean') useDelim = true;
-    label = readAsString(label, '', true);
+    label = readAsString(label, true);
     if (label !== '') label = `${label}${useDelim ? ':' : ''}`;
     isReadOnly = readAsBool(isReadOnly, true);
     let fldID = idPref === '' ? id : `${idPref}-${id}`;
@@ -331,6 +447,12 @@ class THtmlInputField {
     );
   }
 
+  /**
+   * @param {ID_STRING}
+   * @param {func}
+   * @returns {none}
+   * @description Sets a callback function to handle event.
+   */
   on(name, evnt){
     pushEventHandler(this.#_events, name, evnt);
   }