input-duration 3.0.3 → 3.1.0

package/README.md

@@ -54,12 +54,15 @@ HTML's built-in `<input type="time">` is for choosing a time of day, not enterin
 The component supplies its own segmented layout instead of the browser's native time-picker UI, so the displayed format does not change with browser or locale. It is built from native number inputs, however, so details such as the on-screen keyboard and interaction can still vary by device and browser; this is consistency of the value's presentation, not a guarantee of pixel-identical rendering. Milliseconds can be entered as three digits; the input's step controls increment in 10 ms intervals.
 
 The control's styles are scoped inside its Shadow DOM, so global styles and resets from Tailwind or other CSS libraries do not leak into its internal layout. The control inherits its font and text color from its surrounding page.
+
 <br>
 <p>
 <div>
   </div>
     <div align="center">
   <a href="https://stephanluis.github.io/input-duration/" target="_blank">Demo</a>
+·
+  <a href="https://stephanluis.github.io/input-duration/bootstrap.html" target="_blank">Bootstrap Demo</a>
 ·
       <a href="https://codesandbox.io/s/peaceful-waterfall-6mxpg2?file=/index.html" target="_blank">
   Fiddle
@@ -86,7 +89,41 @@ The goal is a small JavaScript duration input that gives countdowns and elapsed-
 
 <i>Does this lose any functionality?</i> No! `document.querySelector('#bob').value` has a getter and setter, so values can be set and retrieved from JavaScript or the HTML attribute.
 
-<img src="readme/safariBad.png" alt="Example comparing a native time input with input-duration" width="80%"/>
+### Screenshots
+
+The desktop comparisons show how a native time input represents a time of day, while `input-duration` displays an elapsed duration in a fixed format.
+
+<p> 💔 the native time input on the left; 🏁 `input-duration` is shown on the right.</p>
+
+<h4>Chrome</h4>
+<img src="readme/rendering/chromeBoth.png" alt="Chrome comparison of a native time input and input-duration" width="100%"/>
+
+<h4>Safari</h4>
+<img src="readme/rendering/safariBoth.png" alt="Safari comparison of a native time input and input-duration" width="100%"/>
+
+The mobile screenshots show the native time picker alongside `input-duration` on each platform.
+
+<table>
+  <thead>
+    <tr>
+      <th>Device</th>
+      <th> 💔 Native time input<br/></th>
+      <th> 🏁 input-duration</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th>Android</th>
+      <td><img src="readme/rendering/androidBad.png" alt="Android native time picker" width="200"/></td>
+      <td><img src="readme/rendering/androidGood.png" alt="input-duration on Android with the numeric keyboard" width="200"/></td>
+    </tr>
+    <tr>
+      <th>iOS</th>
+      <td><img src="readme/rendering/iosBad.png" alt="iOS native time picker" width="200"/></td>
+      <td><img src="readme/rendering/iosGood.png" alt="input-duration on iOS with the numeric keyboard" width="200"/></td>
+    </tr>
+  </tbody>
+</table>
 
 Native time inputs are useful when the user is choosing a time on a clock. A duration is different: `30:00:00.125` means thirty hours, not 6 AM the next day. Keeping those concepts separate avoids date, timezone, and 12/24-hour display concerns when collecting a duration.
 
@@ -115,6 +152,8 @@ Here's why:
     </li>
     <li><a href="#usage">Usage</a></li>
     <li><a href="#roadmap">Roadmap</a></li>
+    <li><a href="#related-duration-controls">Related duration controls</a></li>
+    <li><a href="#future-partners">Future partners</a></li>
      <li><a href="#cross-browser-testing">Cross-browser testing</a></li>
     <li><a href="#contributing">Contributing</a></li>
     <li><a href="#license">License</a></li>
@@ -223,6 +262,35 @@ document.querySelector('#bob').value = '44:04:04.444'
 
 ``` 
 
+### Bootstrap styling
+
+The component keeps its Shadow DOM, so Bootstrap's CSS selectors do not directly style its internal fields. Instead, map Bootstrap theme variables to the component's CSS custom properties. This is additive: without overrides, the component retains its default appearance.
+
+```css
+input-duration {
+  --input-duration-border-color: var(--bs-border-color);
+  --input-duration-border-radius: var(--bs-border-radius);
+  --input-duration-background: var(--bs-body-bg);
+  --input-duration-color: var(--bs-body-color);
+  --input-duration-focus-color: var(--bs-primary);
+  --input-duration-focus-outline: 0.25rem solid rgba(var(--bs-primary-rgb), 0.25);
+}
+```
+
+The internal control and its fields, dividers, and icon are also exposed as Shadow Parts for targeted styling:
+
+```css
+input-duration::part(control) {
+  padding: 0.375rem 0.75rem;
+}
+
+input-duration::part(field) {
+  font-size: 1rem;
+}
+```
+
+Available parts are `control`, `field` (also `field-hours`, `field-minutes`, `field-seconds`, and `field-milliseconds`), `divider` (also `divider-hours-minutes`, `divider-minutes-seconds`, and `divider-seconds-milliseconds`), and `icon`. Supported CSS custom properties are `--input-duration-gap`, `--input-duration-padding`, `--input-duration-border-color`, `--input-duration-border-radius`, `--input-duration-background`, `--input-duration-color`, `--input-duration-focus-color`, `--input-duration-focus-outline`, `--input-duration-focus-outline-offset`, `--input-duration-divider-color`, `--input-duration-divider-opacity`, `--input-duration-disabled-color`, and `--input-duration-icon-color`.
+
 and
 
 ```sh
@@ -244,18 +312,55 @@ _For more documentation, please refer to the jscocs on  [input-duration Docs](ht
 - [x] Emperically determine <input type="time"> behaviour of Input (time) on Chrome
 - [x] Reverse engineer input behaviour (arrows, digits, 0 addition, etc.)
 - [x] Cross browser/ cross os manual tests  
-- [ ] Get Chrome behavioural specification for <input type="time">
 - [ ] Add end to end multi-browser, multi-os Selinium tests
-- [ ] Update demo page (either PM.com or JSfiddle type)
+- [X] Update demo page (either PM.com or JSfiddle type)
 - [ ] Multi-language documentation (Google translate of this page?)
     - [ ] Chinese
     - [ ] Spanish
-- [ ] min and max values (sorry for the moment you'll have to do those yourself in js)
+
+### 2026
+
+- [ ] Document and verify a versioned Chrome `<input type="time">` behavior profile: compare the [WHATWG standard](https://html.spec.whatwg.org/multipage/input.html#time-state-(type=time)) with [Blink's implementation](https://chromium.googlesource.com/chromium/src/+/main/third_party/blink/renderer/core/html/forms/time_input_type.cc) and [time-input tests](https://chromium.googlesource.com/chromium/src/+/main/third_party/blink/web_tests/fast/forms/time/) (including [multiple-field UI tests](https://chromium.googlesource.com/chromium/src/+/main/third_party/blink/web_tests/fast/forms/time-multiple-fields/)). Record Chrome version, OS, and locale; verify relevant keyboard and segment-editing behavior, then adapt `input-duration` where appropriate without assuming platform-specific time-picker UI is universal.
+- [ ] Add configurable duration segments and presentation, including optional days, hiding units, and custom dividers. Keep `HH:mm:ss.SSS` as the default. ([html-duration-picker.js](https://nadchif.github.io/html-duration-picker.js/), [input-duration-element](https://muan.github.io/input-duration-element/))
+- [ ] Support declarative minimum and maximum values with consistent validation and boundary behavior. ([html-duration-picker.js](https://nadchif.github.io/html-duration-picker.js/))
+- [ ] Improve accessibility with per-segment labels, group semantics, and documented screen-reader and keyboard behavior. ([time-input-polyfill](https://github.com/Dan503/time-input-polyfill/) demonstrates accessible time-field interactions.)
+- [ ] Participate in native HTML forms, including named submission, required/validity, disabled state, and form reset/restore behavior. ([duration-input example](https://gist.github.com/Wigny/97cc83ea5179e7b8ab5a044fb14deb9a))
+- [ ] Offer optional ISO 8601 duration serialization and `Temporal.Duration` interoperability without breaking the existing `HH:mm:ss.SSS` value format. ([WHATWG discussion](https://github.com/whatwg/html/issues/5488#issuecomment-3961032394), [duration-input example](https://gist.github.com/Wigny/97cc83ea5179e7b8ab5a044fb14deb9a))
 
 See the [open issues](https://github.com/StephanLuis/input-duration/issues) for a full list of proposed features (and known issues).
 
 <p align="right">(<a href="#top">back to top</a>)</p>
 
+<!-- RELATED DURATION CONTROLS -->
+## Related duration controls
+
+This comparison summarizes capabilities described in each project's documentation; a dash means the feature is not documented, not necessarily unsupported. "Estimated users" is approximated by npm package downloads from 2026-10-28 through 2026-11-03, not unique people; downloads can include CI, repeated installs, and automated systems, and omit CDN or other use. The Wigny entry is a gist example rather than a maintained library, so no npm download figure is available.
+
+| Control | Display / units | Value representation | Bounds | Precision / interaction | Estimated users* |
+|---|---|---|---|---|---:|
+| [input-duration](https://github.com/StephanLuis/input-duration) | Fixed `HH:mm:ss.SSS` (00–99 hours); `noHours()` can hide hours | `HH:mm:ss.SSS` string via `.value` | No public min/max options documented | Milliseconds; digit entry, arrow navigation and increment | [~748](https://api.npmjs.org/downloads/point/last-week/input-duration) |
+| [timepoint-selection](https://github.com/naomiaro/timepoint-selection) | Selectable `dd:hh:mm:ss`, `dd:hh:mm`, `hh:mm:ss`, `hh:mm`, or `mm:ss`; custom unit labels | Numeric seconds through `getValue()` / `setValue()` | Configurable maximum / rollover | Seconds; keyboard navigation, arrow increments, rollover | [~22](https://api.npmjs.org/downloads/point/last-week/timepoint-selection) |
+| [html-duration-picker.js](https://github.com/nadchif/html-duration-picker.js) | `HH:MM:SS`; optional hidden seconds | Formatted text in an enhanced native `<input>` | Configurable minimum and maximum durations | Seconds in documented formats; interaction details not specified | [~905](https://api.npmjs.org/downloads/point/last-week/html-duration-picker) |
+| [muan/input-duration-element](https://github.com/muan/input-duration-element) | Hours, minutes, seconds; customizable dividers/slots | Numeric seconds; `value` and `change` event | `max` documented; `min` and validation listed as TODOs | Demo covers durations up to 180 seconds; precision beyond seconds not specified | [~9](https://api.npmjs.org/downloads/point/last-week/input-duration-element) |
+| [segmented-input](https://github.com/jimmywarting/segmented-input) | Duration preset or custom parsing/formatting and segments | Formatted string in an enhanced native `<input>` | Per-segment `min`, `max`, and `step`; custom validity | Duration preset shown to seconds; arrow-key segment navigation and adjustment | [~4](https://api.npmjs.org/downloads/point/last-week/segmented-input) |
+| [Wigny duration-input example](https://gist.github.com/Wigny/97cc83ea5179e7b8ab5a044fb14deb9a) | Markup-defined hour, minute, and second segments | ISO 8601 duration string; form-associated custom element | No public min/max API documented | Fractional seconds; keyboard segment navigation and adjustment | N/A (gist) |
+
+These projects illustrate possible directions—such as optional units, configurable formatting, bounds, alternate value formats, and native form participation—without implying that every feature is a fit for `input-duration`.
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+<!-- FUTURE PARTNERS -->
+## Future partners
+
+Potential integration targets only; these projects are not affiliated with or endorsing `input-duration`.
+
+- [React Hook Form](https://react-hook-form.com/docs/usecontroller/controller) — provide a tested `Controller` adapter/example that synchronizes the custom element's value, events, ref, and validation.
+- [Formik](https://formik.org/docs/api/field) — add a custom `Field` example to connect duration values to Formik-managed forms.
+- [Angular Reactive Forms](https://angular.dev/api/forms/ControlValueAccessor) — provide a `ControlValueAccessor` adapter for model-to-view updates, user changes, touched state, and disabled state.
+- [Shoelace](https://shoelace.style/) — document how to use the framework-agnostic duration element alongside Shoelace form controls in a consistent design system.
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
 <!-- TESTSTATUS -->
 ## Cross-browser testing
 

package/docs/bootstrap.html

@@ -0,0 +1,104 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="description" content="See input-duration styled with Bootstrap 5 using CSS custom properties and Shadow Parts.">
+    <title>Bootstrap demo — input-duration</title>
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet">
+    <style>
+        input-duration {
+            --input-duration-gap: 0.1em;
+            --input-duration-padding: 0.375rem 0.75rem;
+            --input-duration-border-color: var(--bs-border-color);
+            --input-duration-border-radius: var(--bs-border-radius);
+            --input-duration-background: var(--bs-body-bg);
+            --input-duration-color: var(--bs-body-color);
+            --input-duration-focus-color: var(--bs-primary);
+            --input-duration-focus-outline: 0.25rem solid rgba(var(--bs-primary-rgb), 0.25);
+            --input-duration-focus-outline-offset: 0;
+        }
+
+        input-duration::part(control) {
+            min-height: calc(1.5em + 0.75rem + 2px);
+        }
+
+        input-duration::part(field) {
+            font-size: 1rem;
+        }
+    </style>
+</head>
+<body>
+    <main class="container py-5">
+        <div class="row justify-content-center">
+            <div class="col-lg-8">
+                <a class="link-secondary text-decoration-none" href="./">&larr; Main demo</a>
+                <header class="my-4">
+                    <p class="text-uppercase text-primary fw-semibold small mb-2">input-duration + Bootstrap 5</p>
+                    <h1 class="display-5 fw-semibold">A duration input that fits your Bootstrap theme</h1>
+                    <p class="lead text-secondary mt-3">
+                        The component keeps its Shadow DOM. Bootstrap’s global selectors do not reach inside it;
+                        this page maps Bootstrap theme variables to the component’s public styling hooks instead.
+                    </p>
+                </header>
+
+                <section class="card shadow-sm" aria-labelledby="example-heading">
+                    <div class="card-body p-4">
+                        <h2 class="h4 card-title" id="example-heading">Maintenance window</h2>
+                        <p class="card-text text-secondary">Set a duration of more than a day, down to milliseconds.</p>
+                        <label class="form-label fw-medium" id="duration-label">Duration</label>
+                        <div>
+                            <input-duration id="duration" value="30:00:00.042" role="group"
+                                aria-labelledby="duration-label"
+                                aria-describedby="duration-help"
+                                aria-label="Duration in hours, minutes, seconds, and milliseconds"></input-duration>
+                        </div>
+                        <div class="form-text mt-3" id="duration-help">
+                            Current value: <output id="duration-value">30:00:00.042</output>
+                        </div>
+                    </div>
+                </section>
+
+                <section class="mt-4" aria-labelledby="integration-heading">
+                    <h2 class="h5" id="integration-heading">How the styling works</h2>
+                    <p>
+                        CSS custom properties bring in Bootstrap colors, border radius, spacing, and focus-ring
+                        styling. Shadow Parts provide targeted access to the control and its internal fields.
+                    </p>
+                    <pre class="bg-body-tertiary border rounded p-3"><code>input-duration {
+  --input-duration-border-color: var(--bs-border-color);
+  --input-duration-border-radius: var(--bs-border-radius);
+  --input-duration-focus-color: var(--bs-primary);
+  --input-duration-focus-outline: 0.25rem solid rgba(var(--bs-primary-rgb), 0.25);
+}
+
+input-duration::part(field) {
+  font-size: 1rem;
+}</code></pre>
+                </section>
+
+                <footer class="border-top mt-5 pt-3 text-secondary small">
+                    <a href="https://github.com/StephanLuis/input-duration">Source on GitHub</a>
+                    <span class="mx-2" aria-hidden="true">&middot;</span>
+                    <a href="https://github.com/StephanLuis/input-duration#usage">Styling API documentation</a>
+                </footer>
+            </div>
+        </div>
+    </main>
+    <script type="module">
+        import 'https://cdn.jsdelivr.net/npm/input-duration/+esm';
+
+        const duration = document.querySelector('#duration');
+        const output = document.querySelector('#duration-value');
+
+        duration.addEventListener('input', () => {
+            output.value = duration.value;
+            output.textContent = duration.value;
+        });
+        duration.addEventListener('change', () => {
+            output.value = duration.value;
+            output.textContent = duration.value;
+        });
+    </script>
+</body>
+</html>

package/docs/index.html

@@ -89,16 +89,25 @@
             line-height: 1.6;
         }
 
-        .scenario {
-            display: inline-block;
-            margin-top: 20px;
-            padding: 10px 15px;
-            border: 1px solid #c8def4;
-            border-radius: 999px;
-            background: #e1efff;
-            color: #244e7a;
-            font-size: .95rem;
-            font-weight: 650;
+        .get-started {
+            display: table;
+            margin: 30px auto 0;
+            padding: 13px 22px;
+            border: 1px solid var(--blue);
+            border-radius: 10px;
+            background: var(--blue);
+            color: #fff;
+            font-size: 1.05rem;
+            text-decoration: none;
+        }
+
+        .get-started:hover {
+            background: #1d4f87;
+        }
+
+        .get-started:focus-visible {
+            outline: 3px solid #8bb9e8;
+            outline-offset: 3px;
         }
 
         .comparison {
@@ -234,7 +243,6 @@
             <p class="eyebrow">A small input, solves a very big problem</p>
             <h1>Time is not a duration.</h1>
             <p class="intro">You need to set a maintenance window. It’ll take 30 hours and 42 milliseconds. Surely a time picker can handle that?</p>
-            <p class="scenario">The task: run X for 30 hours and 42 milliseconds</p>
         </header>
 
         <section class="comparison" aria-label="Compare a time-of-day input with a duration input">
@@ -262,9 +270,11 @@
             That's the gap <a href="InputDuration.html">input-duration</a> fills. Read the
             <a href="https://github.com/StephanLuis/input-duration">source on GitHub</a>.
         </footer>
+        <p class="demo-link"><a href="bootstrap.html">See the Bootstrap 5 demo</a></p>
+        <a class="get-started" href="https://github.com/StephanLuis/input-duration#getting-started">Get Started</a>
     </main>
     <script type="module">
-        import 'https://cdn.jsdelivr.net/npm/input-duration@3.0.1/+esm';
+        import 'https://cdn.jsdelivr.net/npm/input-duration/+esm';
 
         const clockInput = document.querySelector('#clock-time');
         const clockResult = document.querySelector('#clock-result');

package/index.js

@@ -237,18 +237,19 @@ 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">
+          <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 +262,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 +328,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 +340,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 +351,7 @@ class InputDuration extends HTMLElement {
 
                 .timeCase input:disabled {
                     background: transparent;
-                    color: GrayText;
+                    color: var(--input-duration-disabled-color);
                     cursor: not-allowed;
                     opacity: 0.65;
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "input-duration",
-  "version": "3.0.3",
+  "version": "3.1.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