@cntwg/html-helper 0.0.27 → 0.1.0

package/lib/html-ctrls/fields.js

@@ -1,521 +0,0 @@
-// [v0.1.023-20250827]
-
-// === module init block ===
-
-const {
-  readAsBool, readAsString,
-  isEmptyString, isNotEmptyString,
-  isPlainObject,
-} = require('@ygracs/bsfoc-lib-js');
-
-const {
-  isHTMLElement, createNewHTMLElement,
-  valueToIDString, valueToClassList,
-  readAsAttrValue,
-  showHTMLElement, hideHTMLElement,
-} = require('../html-helper-lib.js');
-
-const {
-  pushEventHandler, triggerEventHandler,
-} = require('./mod-hfunc.js');
-
-// === module inner block ===
-
-const lpAllowedValues = new Map([
-  [ 'before', 0 ],
-  [ 'after', 1 ],
-  [ 'default', 0 ],
-]);
-
-/**
- * An input field type descriptor
- * @typedef {Object} ifcTypeDesc
- * @property {string} type - field general type
- * @property {string} subtype - field sub-type
- */
-
-/**
- * Returns field description by a given type.
- * @function getInputFieldTypeDescr
- * @param {string} value - field type
- * @returns {ifcTypeDesc}
- * @inner
- */
-function getInputFieldTypeDescr(value) {
-  let fldType = readAsString(value, { useTrim: true });
-  if (fldType === '') fldType = 'default';
-  let fldSubType = '';
-  switch (fldType) {
-    case 'text':
-    case 'checkbox': {
-      break;
-    }
-    case 'switch': {
-      fldType = 'checkbox';
-      fldSubType = 'switch';
-      break;
-    }
-    case 'field':
-    case 'default': {
-      fldType = 'text';
-      fldSubType = 'field';
-      break;
-    }
-    default: {
-      fldType = '';
-    }
-  };
-  return { type: fldType, subtype: fldSubType };
-};
-
-/**
- * Returns label position ID by its name.
- * @function getLabelPositionID
- * @param {string} value - label position identifier
- * @returns {number}
- * @inner
- */
-function getLabelPositionID(value) {
-  let key = readAsString(value, { useTrim: true });
-  if (!lpAllowedValues.has(key)) key = 'default';
-  return lpAllowedValues.get(key);
-};
-
-// === module main block ===
-
-/***
- * (* constant definitions *)
- */
-
-/***
- * (* function definitions *)
- */
-
-/***
- * (* class definitions *)
- */
-
-/**
- * An options set for create ifc
- * @typedef {Object} OPT_ifcdesc
- * @property {HTMLElement} [host] - host element
- * @property {string} [idPref]
- * @property {string} [label] - text of a label
- * @property {object} [labelPosition]
- * @property {boolean} [useDelim]
- * @property {object} [baseClassID]
- * @property {string} [hint] - hint to show when empty
- * @property {string} [type] - field type
- * @property {boolean} [readonly] - mode flag
- */
-
-/**
- * An options set for `THtmlInputField`-class
- * @typedef {Object} OPT_ifcsett
- * @property {string} [idPref]
- * @property {(string|string[])} [baseClassID]
- * @property {string} [hint] - hint to show when empty
- * @property {string} [type] - field type
- * @property {boolean} [readonly=true] - mode flag
- */
-
-/**
- * A descriptor for an input field elements set.
- * @typedef {Object} ifcElementsDesc
- * @property {HTMLElement} host - host element
- * @property {HTMLElement} label - label element
- * @property {HTMLElement} field - field element
- */
-
-/**
- * @classdesc This class implements an interface of an input field element
- */
-class THtmlInputField {
-  /** @type {?HTMLElement} */
-  #_host;// = null;
-  /** @type {?HTMLElement} */
-  #_label;// = null;
-  /** @type {?HTMLElement} */
-  #_field;// = null;
-  #_id = '';
-  #_value = '';
-  /** @type {OPT_ifcsett} */
-  #_options = null;
-  /**
-   * A controller status
-   * @typedef {Object} statIFCtrl
-   * @property {string} fldType - field general type
-   * @property {string} fldSubType - field sub-type
-   * @property {boolean} isReadOnly - mode flag
-   * @property {boolean} isModified - indicates whether any changes was made
-   * @inner
-   */
-  /** @type {statIFCtrl} */
-  #_status;// = null;
-  /** @type {Map<string, Function>} */
-  #_events;// = null;
-
-  /**
-   * Creates an instance of an input field element
-   * @param {string} name - <*reserved*>
-   * @param {ifcElementsDesc} eholds - elements set
-   * @param {OPT_ifcsett} [opt] - options
-   */
-  constructor(name, eholds, opt) {
-    // load elements
-    const _eholds = isPlainObject(eholds) ? eholds : {};
-    let { host, label, field } = _eholds;
-    // save elements
-    if (!isHTMLElement(host)) host = null;
-    if (!isHTMLElement(label)) label = null;
-    if (!isHTMLElement(field)) field = null;
-    this.#_host = host;
-    this.#_label = label;
-    this.#_field = field;
-    // load options
-    const _options = isPlainObject(opt) ? opt : {};
-    let {
-      idPref,
-      baseClassID,
-      hint,
-      type: fldType,
-      readonly: isReadOnly,
-    } = _options;
-    let fldSubType = '';
-    ({ type: fldType, subtype: fldSubType } = getInputFieldTypeDescr(fldType));
-    isReadOnly = readAsBool(isReadOnly, true);
-    // save options
-    this.#_options = _options;
-    // save status
-    /** @type {statIFCtrl} */
-    this.#_status = {
-      fldType,
-      fldSubType,
-      isReadOnly,
-      isModified: false,
-    };
-    // init an event instance controller
-    if (field) {
-      field.addEventListener('change', this.#_saveFieldData);
-      field.addEventListener('input', this.#_switchFieldStatusOnInput);
-      field.addEventListener('blur', this.#_switchFieldStatusOnBlur);
-    };
-    this.#_events = new Map();
-  }
-
-  /**
-   * Indicates whether element value was modified.
-   * @type {boolean}
-   * @readonly
-   */
-  get isModified() {
-    return this.#_status.isModified;
-  }
-
-  /**
-   * Returns an input element origin type.
-   * @since v0.0.23
-   * @type {string}
-   * @readonly
-   */
-  get type() {
-    return this.#_status.fldType;
-  }
-
-  /**
-   * Containes an element value.
-   * @type {string}
-   * @fires THtmlInputField#value-empty
-   */
-  get value() {
-    const field = this.#_field;
-    const result = this.type === 'checkbox' ?  field.checked : field.value;
-    return result;
-  }
-
-  set value(value) {
-    const field = this.#_field;
-    if (value !== undefined) {
-      if (this.type === 'checkbox') {
-        field.checked = value;
-        this.#_status.isModified = false;
-      } else {
-        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,
-          });
-        };
-      };
-    };
-  }
-
-  /**
-   * @param {string} name - event name
-   * @param {...any} args
-   * @returns {void}
-   * @private
-   * @see triggerEventHandler
-   */
-  #_triggerEvent = (name, ...args) => {
-    triggerEventHandler(this.#_events, name, ...args);
-  };
-
-  /**
-   * @param {object} e - event
-   * @returns {void}
-   * @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 {string} type - event type
-     * @property {object} target
-     */
-    this.#_triggerEvent('value-changed', {
-      type: 'value-changed',
-      target,
-    });
-  };
-
-  /**
-   * @param {object} e - event
-   * @returns {void}
-   * @private
-   * @fires THtmlInputField#value-empty
-   */
-  #_switchFieldStatusOnInput = (e) => {
-    e.preventDefault();
-    const target = e.target;
-    //***/console.log(':'+e.type+':'+target.getAttribute('id')+':\n:switchFieldStatusOnInput() => received OnInput-event');
-    this.#_status.isModified = true;
-    // // TODO:
-    if (target.value === '') {
-      /**
-       * @event THtmlInputField#value-empty
-       * @type {Object}
-       * @property {string} type - event type
-       * @property {object} target
-       */
-      this.#_triggerEvent('value-empty', {
-        type: 'value-empty',
-        target,
-      });
-    };
-  };
-
-  /**
-   * @param {object} e - event
-   * @returns {void}
-   * @private
-   */
-  #_switchFieldStatusOnBlur = (e) => {
-    e.preventDefault();
-    //***/console.log(':'+e.type+':'+e.target.getAttribute('id')+':\n:switchFieldStatusOnBlur() => received OnBlur-event');
-    // // TODO:
-  };
-
-  /**
-   * Tries to attach an element to a given target.
-   * @param {HTMLElement} target - target element
-   * @returns {boolean}
-   */
-  attachTo(target) {
-    const host = this.#_host;
-    let result = false;
-    if (
-      isHTMLElement(target)
-      && isHTMLElement(host)
-    ) {
-      target.append(host);
-      result = true;
-    };
-    return result;
-  }
-
-  /**
-   * Checks if a value of an element is not set.
-   * @returns {boolean}
-   */
-  isEmpty() {
-    return isEmptyString(this.value);
-  }
-
-  /**
-   * Checks if a value of an element is set.
-   * @returns {boolean}
-   */
-  isNotEmpty() {
-    return isNotEmptyString(this.value);
-  }
-
-  /**
-   * Shows an element.
-   * @returns {void}
-   */
-  show() {
-    showHTMLElement(this.#_host);
-  }
-
-  /**
-   * Hides an element.
-   * @returns {void}
-   */
-  hide() {
-    hideHTMLElement(this.#_host);
-  }
-
-  /**
-   * @returns {void}
-   * @todo not implemented yet.
-   */
-  clear() {
-    // // TODO:
-  }
-
-  /**
-   * Creates a new instance.
-   * @param {string} name - <*reserved*>
-   * @param {OPT_ifcdesc} opt - options
-   * @returns {?THtmlInputField}
-   * @static
-   */
-  static create(name, opt) {
-    const eholds = THtmlInputField.createElement(name, opt, true);
-    const { field } = eholds;
-    return (
-      isHTMLElement(field)
-      ? new THtmlInputField(name, eholds, opt)
-      : null
-    );
-  }
-
-  /**
-   * Creates a new elements.
-   * @param {string} name
-   * @param {OPT_ifcdesc} [opt] - options
-   * @param {boolean} [doRetChild=false] - mode flag
-   * @returns {(HTMLElement|ifcElementsDesc)}
-   * @static
-   */
-  static createElement(name, opt, doRetChild) {
-    const id = valueToIDString(name);
-    const _options = isPlainObject(opt) ? opt : {};
-    let fldSubType = '';
-    /** @type {OPT_ifcdesc} */
-    let {
-      host,
-      idPref,
-      label,
-      labelPosition,
-      useDelim,
-      baseClassID,
-      hint,
-      type: fldType,
-      readonly: isReadOnly,
-    } = _options;
-    if (!isPlainObject(baseClassID)) baseClassID = {};
-    let {
-      main: bcidMain,
-      host: bcidHost,
-      label: bcidLabel,
-      field: bcidField,
-    } = baseClassID;
-    bcidMain = valueToClassList(bcidMain);
-    bcidHost = valueToClassList(bcidHost);
-    bcidLabel = valueToClassList(bcidLabel);
-    bcidField = valueToClassList(bcidField);
-    idPref = valueToIDString(idPref);
-    hint = readAsString(hint, { useTrim: 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, { useTrim: true });
-    if (label !== '') label = `${label}${useDelim ? ':' : ''}`;
-    isReadOnly = readAsBool(isReadOnly, true);
-    let fldID = idPref === '' ? id : `${idPref}-${id}`;
-    if (!isHTMLElement(host)) {
-      host = createNewHTMLElement('div', {
-        classNames: bcidHost,
-      });
-    };
-    let lblHolder = null;
-    let fldHolder = null;
-    let items = [];
-    if (host) {
-      lblHolder = host.querySelector(`label[for="${fldID}"]`);
-      if (!lblHolder) {
-        lblHolder = createNewHTMLElement('label', {
-          text: label,
-          attr: {
-            for: fldID,
-          },
-          classNames: bcidLabel,
-        });
-      };
-      fldHolder = host.querySelector(`input#${fldID}`);
-      if (!fldHolder) {
-        fldHolder = createNewHTMLElement('input', {
-          id: fldID,
-          attr: {
-            type: fldType,
-            placeholder: hint,
-          },
-          classNames: bcidField,
-        });
-      };
-      if (fldHolder) {
-        if (isReadOnly) {
-          const attr = fldType === 'checkbox' ? 'disabled' : 'readOnly';
-          fldHolder[attr] = true;
-        };
-        if (lblHolder) items.push(lblHolder);
-        items.push(fldHolder);
-      };
-      const len = items.length;
-      if (len > 0) {
-        if (len === 2 && labelPosition === 1) {
-          items = [ items[1], items[0] ];
-        };
-        host.append(...items);
-      };
-    };
-    // // TODO:
-    return (
-      readAsBool(doRetChild, false)
-      ? { host, label: lblHolder, field: fldHolder }
-      : host
-    );
-  }
-
-  /**
-   * Sets a callback function to handle event.
-   * @param {string} name - event name
-   * @param {func} evnt - callback function
-   * @returns {void}
-   */
-  on(name, evnt) {
-    pushEventHandler(this.#_events, name, evnt);
-  }
-
-};
-
-// === module exports block ===
-
-module.exports.THtmlInputField = THtmlInputField;