input-duration 3.1.0 → 3.2.1

package/index.js

@@ -17,28 +17,72 @@
 
 /**
  * Class for the Input-Duration webcomponent
+ *
+ * Boolean attributes `no-hours`, `no-minutes`, `no-seconds`, and
+ * `no-microseconds` hide their respective fields. String attributes
+ * `hours-divider`, `minutes-divider`, `seconds-divider`, and
+ * `microseconds-divider` customize the separators; the last adds a suffix
+ * after milliseconds. Divider values are rendered as text.
+ *
+ * @example
+ * <input-duration no-microseconds hours-divider="h " microseconds-divider="ms"></input-duration>
+ *
  * @class InputDuration
  * @extends HTMLElement
  */
 
 class InputDuration extends HTMLElement {
+    /**
+     * HTML attributes that update the component when changed.
+     *
+     * @static
+     * @returns {string[]} Observed value, visibility, and divider attributes.
+     */
     static get observedAttributes() {
-        return ['value'];
+        return [
+            'value',
+            'no-hours',
+            'no-minutes',
+            'no-seconds',
+            'no-microseconds',
+            'hours-divider',
+            'minutes-divider',
+            'seconds-divider',
+            'microseconds-divider'
+        ];
     }
 
     constructor() {
 
         super();
 
+        /**
+         * Shadow root containing this component's controls.
+         * @type {ShadowRoot}
+         */
         this.myElement = this.attachShadow({ mode: 'open' });
 
         this.boot();
 
     }  // end constructor
 
+    /**
+     * Updates the rendered control when an observed attribute changes.
+     *
+     * @param {string} name - Changed attribute name.
+     * @param {?string} oldValue - Previous attribute value.
+     * @param {?string} newValue - New attribute value, or null when removed.
+     * @returns {void}
+     */
     attributeChangedCallback(name, oldValue, newValue) {
 
-        if (name !== 'value' || oldValue === newValue) {
+        if (oldValue === newValue) {
+            return;
+        }
+
+        if (name !== 'value') {
+            this.updateVisibleFields();
+            this.updateDividers();
             return;
         }
 
@@ -55,7 +99,7 @@ class InputDuration extends HTMLElement {
     /**
      * get the input-duration value, pulls values from each input
      * so in js use var x = document.querySelector("#bobPrepop").value; 
-     * @return {duration}
+     * @returns {?string} Duration in `HH:mm:ss.SSS` format, or null before initialization.
      */
 
     get value() {
@@ -79,10 +123,10 @@ class InputDuration extends HTMLElement {
 
 
     /**
-    * set the input-duration value
-    * so in js use document.querySelector("#bobPrepop").value = "05:05:05.005"
-    * @return {duration}
-    * @param {duration} can be html attribute or set in js
+    * Sets the duration using the fixed `HH:mm:ss.SSS` format.
+    *
+    * @param {string} val - Duration string, such as `05:05:05.005`.
+    * @returns {void}
     */
 
     set value(val) {
@@ -106,11 +150,23 @@ class InputDuration extends HTMLElement {
         }
     }
 
+    /**
+     * Checks whether a value follows the supported duration format and ranges.
+     *
+     * @param {*} val - Candidate value.
+     * @returns {boolean} Whether the value is valid `HH:mm:ss.SSS`.
+     */
     isValidValue(val) {
         return typeof val === 'string' &&
             /^[0-9]{2}:[0-5][0-9]:[0-5][0-9]\.[0-9]{3}$/.test(val);
     }
 
+    /**
+     * Copies a validated duration string into the four shadow inputs.
+     *
+     * @param {string} val - Valid duration in `HH:mm:ss.SSS` format.
+     * @returns {void}
+     */
     setInputValues(val) {
         const timeArray = val.split(/[.:]+/);
         const inputNames = ['startHours', 'startMinutes', 'startSeconds', 'startMilliSecs'];
@@ -122,6 +178,11 @@ class InputDuration extends HTMLElement {
         });
     }
 
+    /**
+     * Resets all duration fields to zero.
+     *
+     * @returns {void}
+     */
     resetInputs() {
         const defaults = ['00', '00', '00', '000'];
         const inputs = this.myElement.querySelectorAll('.timeCase input');
@@ -132,6 +193,12 @@ class InputDuration extends HTMLElement {
         });
     }
 
+    /**
+     * Reports a value that does not match the supported duration format.
+     *
+     * @param {*} val - Rejected value.
+     * @returns {void}
+     */
     warnInvalidValue(val) {
         console.warn(`The specified value ${val} does not conform to the required format.  The format is "HH:mm:ss.SSS" where HH is 00-99, mm is 00-59, ss is 00-59, and SSS is 000-999.`);
     }
@@ -249,6 +316,7 @@ class InputDuration extends HTMLElement {
           <input type="number" class="sS D2 ts_digit" part="field field-seconds" name="startSeconds" data-tp="3" min="-1" max="60" value="00">
           <span class="bds-s" part="divider divider-seconds-milliseconds">.</span>
           <input type="number" class="sMS D3 ts_digit" part="field field-milliseconds" name="startMilliSecs" data-tp="4" min="-10" max="1010" step="10" value="000">
+          <span class="bds-ms" part="divider divider-milliseconds-suffix" style="display: none"></span>
           <div id="svgContainer" part="icon">
               <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true"
               focusable="false" data-prefix="fal" data-icon="stopwatch" class="svg-inline--fa fa-stopwatch fa-w-14"
@@ -631,23 +699,217 @@ class InputDuration extends HTMLElement {
 
 
     /**
-     * removes the hours, so the display is mm:ss.uuu
-     * @method
+     * Hides the hours field and its adjacent divider.
+     * Sets the `no-hours` attribute.
+     *
+     * @returns {void}
      */
+    hideHours() {
+        this.setAttribute('no-hours', '');
+    }
+
+    /**
+     * Shows the hours field and its adjacent divider.
+     * Removes the `no-hours` attribute.
+     *
+     * @returns {void}
+     */
+    showHours() {
+        this.removeAttribute('no-hours');
+    }
 
+    /**
+     * Backward-compatible alias for {@link InputDuration#hideHours}.
+     *
+     * @returns {void}
+     */
     noHours() {
+        this.hideHours();
+    }
 
-        var closure = this;
+    /**
+     * Hides the minutes field and its adjacent divider.
+     * Sets the `no-minutes` attribute.
+     *
+     * @returns {void}
+     */
+    hideMinutes() {
+        this.setAttribute('no-minutes', '');
+    }
+
+    /**
+     * Shows the minutes field and its adjacent divider.
+     * Removes the `no-minutes` attribute.
+     *
+     * @returns {void}
+     */
+    showMinutes() {
+        this.removeAttribute('no-minutes');
+    }
+
+    /**
+     * Backward-compatible alias for {@link InputDuration#hideMinutes}.
+     *
+     * @returns {void}
+     */
+    noMinutes() {
+        this.hideMinutes();
+    }
+
+    /**
+     * Hides the seconds field and its adjacent divider.
+     * Sets the `no-seconds` attribute.
+     *
+     * @returns {void}
+     */
+    hideSeconds() {
+        this.setAttribute('no-seconds', '');
+    }
+
+    /**
+     * Shows the seconds field and its adjacent divider.
+     * Removes the `no-seconds` attribute.
+     *
+     * @returns {void}
+     */
+    showSeconds() {
+        this.removeAttribute('no-seconds');
+    }
 
-        // hide chronly hours inputs on page
+    /**
+     * Backward-compatible alias for {@link InputDuration#hideSeconds}.
+     *
+     * @returns {void}
+     */
+    noSeconds() {
+        this.hideSeconds();
+    }
 
-        closure.shadowRoot.querySelectorAll(".timeCase input.sH").forEach(el => el.style.display = 'none');
+    /**
+     * Hides the milliseconds field and its adjacent divider or suffix.
+     * Sets the `no-microseconds` attribute.
+     *
+     * @returns {void}
+     */
+    hideMicroSeconds() {
+        this.setAttribute('no-microseconds', '');
+    }
 
+    /**
+     * Shows the milliseconds field and its adjacent divider or suffix.
+     * Removes the `no-microseconds` attribute.
+     *
+     * @returns {void}
+     */
+    showMicroSeconds() {
+        this.removeAttribute('no-microseconds');
+    }
 
-        // hide the hours colon on page
+    /**
+     * Backward-compatible alias for {@link InputDuration#hideMicroSeconds}.
+     *
+     * @returns {void}
+     */
+    noMicroSeconds() {
+        this.hideMicroSeconds();
+    }
 
-        closure.shadowRoot.querySelectorAll(".timeCase span.bds-h").forEach(el => el.style.display = 'none');
+    /**
+     * Replaces the hours/minutes separator.
+     * Also available through the `hours-divider` attribute.
+     *
+     * @param {string} text - Divider text to display.
+     * @returns {void}
+     */
+    setHoursDivider(text) {
+        this.setAttribute('hours-divider', text);
+    }
 
+    /**
+     * Replaces the minutes/seconds separator.
+     * Also available through the `minutes-divider` attribute.
+     *
+     * @param {string} text - Divider text to display.
+     * @returns {void}
+     */
+    setMinutesDivider(text) {
+        this.setAttribute('minutes-divider', text);
+    }
+
+    /**
+     * Replaces the seconds/milliseconds separator.
+     * Also available through the `seconds-divider` attribute.
+     *
+     * @param {string} text - Divider text to display.
+     * @returns {void}
+     */
+    setSecondsDivider(text) {
+        this.setAttribute('seconds-divider', text);
+    }
+
+    /**
+     * Sets a suffix to display after milliseconds.
+     * Also available through the `microseconds-divider` attribute.
+     *
+     * @param {string} text - Suffix text to display.
+     * @returns {void}
+     */
+    setMicroSecondsDivider(text) {
+        this.setAttribute('microseconds-divider', text);
+    }
+
+    /**
+     * Synchronizes field and divider visibility with the `no-*` attributes.
+     *
+     * @returns {void}
+     */
+    updateVisibleFields() {
+        const hiddenFields = {
+            'no-hours': '.sH',
+            'no-minutes': '.sM',
+            'no-seconds': '.sS',
+            'no-microseconds': '.sMS'
+        };
+        const hiddenDividers = {
+            '.bds-h': ['no-hours', 'no-minutes'],
+            '.bds-m': ['no-seconds'],
+            '.bds-s': ['no-microseconds'],
+            '.bds-ms': ['no-microseconds']
+        };
+
+        for (const [attribute, selector] of Object.entries(hiddenFields)) {
+            const field = this.myElement.querySelector(selector);
+            field.style.display = this.hasAttribute(attribute) ? 'none' : '';
+        }
+
+        for (const [selector, attributes] of Object.entries(hiddenDividers)) {
+            const divider = this.myElement.querySelector(selector);
+            const shouldHide = attributes.some(attribute => this.hasAttribute(attribute));
+            divider.style.display = shouldHide ? 'none' : '';
+        }
+    }
+
+    /**
+     * Synchronizes divider text with the corresponding divider attributes.
+     *
+     * @returns {void}
+     */
+    updateDividers() {
+        const dividers = {
+            'hours-divider': ['.bds-h', ':'],
+            'minutes-divider': ['.bds-m', ':'],
+            'seconds-divider': ['.bds-s', '.'],
+            'microseconds-divider': ['.bds-ms', '']
+        };
+
+        for (const [attribute, [selector, defaultText]] of Object.entries(dividers)) {
+            const divider = this.myElement.querySelector(selector);
+            const text = this.getAttribute(attribute) ?? defaultText;
+            divider.textContent = text;
+            if (selector === '.bds-ms') {
+                divider.style.display = text && !this.hasAttribute('no-microseconds') ? '' : 'none';
+            }
+        }
     }
 } 
 // end class

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "input-duration",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "author": "Stephan Luis <stephan@learnsense.org>",
   "description": "A JavaScript web component for entering durations up to 99 hours in a fixed HH:mm:ss.SSS format, with millisecond precision for countdown timers and elapsed time.",
   "browser": "./index.js",
@@ -17,7 +17,7 @@
     "type": "git",
     "url": "git+https://github.com/StephanLuis/input-duration.git"
   },
-  "license": "ISC",
+  "license": "MIT",
   "devDependencies": {
     "jsdom": "^26.1.0"
   },