input-duration 3.0.3 → 3.2.0

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.`);
     }
@@ -237,18 +304,20 @@ class InputDuration extends HTMLElement {
         var spanIn = document.createElement("div");
 
         spanIn.classList.add('timeCase');
+        spanIn.setAttribute('part', 'control');
 
         var template = document.createElement('template');
 
         template.innerHTML = `
-          <input type="number" class="sH D2 ts_digit" name="startHours" data-tp="1" min="-1" max="100" value="00" >
-          <span class="bds-h">:</span>
-          <input type="number" class="sM D2 ts_digit" name="startMinutes" data-tp="2" min="-1" max="60" value="00">
-          <span class="bds-m">:</span>
-          <input type="number" class="sS D2 ts_digit" name="startSeconds" data-tp="3" min="-1" max="60" value="00">
-          <span class="bds-s">.</span>
-          <input type="number" class="sMS D3 ts_digit" name="startMilliSecs" data-tp="4" min="-10" max="1010" step="10" value="000">
-          <div id="svgContainer">
+          <input type="number" class="sH D2 ts_digit" part="field field-hours" name="startHours" data-tp="1" min="-1" max="100" value="00" >
+          <span class="bds-h" part="divider divider-hours-minutes">:</span>
+          <input type="number" class="sM D2 ts_digit" part="field field-minutes" name="startMinutes" data-tp="2" min="-1" max="60" value="00">
+          <span class="bds-m" part="divider divider-minutes-seconds">:</span>
+          <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"
               role="img" viewBox="0 0 448 512">
@@ -261,27 +330,41 @@ class InputDuration extends HTMLElement {
                     color: inherit;
                     font: inherit;
                     vertical-align: middle;
+                    --input-duration-gap: 0.08em;
+                    --input-duration-padding: 0.4em 0.55em;
+                    --input-duration-border-color: #9aa6b2;
+                    --input-duration-border-radius: 0.4em;
+                    --input-duration-background: transparent;
+                    --input-duration-color: inherit;
+                    --input-duration-focus-color: #2196f3;
+                    --input-duration-focus-outline: 3px solid #2196f3;
+                    --input-duration-focus-outline-offset: 2px;
+                    --input-duration-divider-color: currentColor;
+                    --input-duration-divider-opacity: 0.7;
+                    --input-duration-disabled-color: GrayText;
+                    --input-duration-icon-color: inherit;
                 }
 
-                .timeCase {
+                .timeCase,
+                .timeCase[part~="control"] {
                     display: inline-flex;
                     align-items: center;
-                    gap: 0.08em;
+                    gap: var(--input-duration-gap);
                     max-width: 100%;
-                    padding: 0.4em 0.55em;
-                    border: 1px solid #9aa6b2;
-                    border-radius: 0.4em;
-                    background: transparent;
-                    color: inherit;
+                    padding: var(--input-duration-padding);
+                    border: 1px solid var(--input-duration-border-color);
+                    border-radius: var(--input-duration-border-radius);
+                    background: var(--input-duration-background);
+                    color: var(--input-duration-color);
                     font-variant-numeric: tabular-nums;
                     line-height: 1.4;
                     white-space: nowrap;
                 }
 
                 .timeCase:focus-within {
-                    border-color: #2196f3;
-                    outline: 3px solid #2196f3;
-                    outline-offset: 2px;
+                    border-color: var(--input-duration-focus-color);
+                    outline: var(--input-duration-focus-outline);
+                    outline-offset: var(--input-duration-focus-outline-offset);
                 }
 
                 .timeCase input {
@@ -313,8 +396,8 @@ class InputDuration extends HTMLElement {
                 }
 
                 .timeCase span {
-                    color: currentColor;
-                    opacity: 0.7;
+                    color: var(--input-duration-divider-color);
+                    opacity: var(--input-duration-divider-opacity);
                 }
 
                 #svgContainer {
@@ -325,7 +408,7 @@ class InputDuration extends HTMLElement {
                     align-items: center;
                     justify-content: center;
                     margin-left: 0.2em;
-                    color: inherit;
+                    color: var(--input-duration-icon-color);
                 }
 
                 #svgContainer svg {
@@ -336,7 +419,7 @@ class InputDuration extends HTMLElement {
 
                 .timeCase input:disabled {
                     background: transparent;
-                    color: GrayText;
+                    color: var(--input-duration-disabled-color);
                     cursor: not-allowed;
                     opacity: 0.65;
                 }
@@ -616,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', '');
+    }
 
-        // hide chronly hours inputs on page
+    /**
+     * Shows the minutes field and its adjacent divider.
+     * Removes the `no-minutes` attribute.
+     *
+     * @returns {void}
+     */
+    showMinutes() {
+        this.removeAttribute('no-minutes');
+    }
 
-        closure.shadowRoot.querySelectorAll(".timeCase input.sH").forEach(el => el.style.display = 'none');
+    /**
+     * 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', '');
+    }
 
-        // hide the hours colon on page
+    /**
+     * Shows the seconds field and its adjacent divider.
+     * Removes the `no-seconds` attribute.
+     *
+     * @returns {void}
+     */
+    showSeconds() {
+        this.removeAttribute('no-seconds');
+    }
 
-        closure.shadowRoot.querySelectorAll(".timeCase span.bds-h").forEach(el => el.style.display = 'none');
+    /**
+     * Backward-compatible alias for {@link InputDuration#hideSeconds}.
+     *
+     * @returns {void}
+     */
+    noSeconds() {
+        this.hideSeconds();
+    }
+
+    /**
+     * 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');
+    }
+
+    /**
+     * Backward-compatible alias for {@link InputDuration#hideMicroSeconds}.
+     *
+     * @returns {void}
+     */
+    noMicroSeconds() {
+        this.hideMicroSeconds();
+    }
+
+    /**
+     * 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.0.3",
+  "version": "3.2.0",
   "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",

package/readme/rendering/bob.txt

@@ -0,0 +1 @@
+x