@siemens/ix 4.4.0 → 5.0.0

package/dist/collection/components/time-picker/time-picker.js

@@ -16,19 +16,19 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
                 r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { h, Host, } from "@stencil/core";
+import { h, Host, Mixin, } from "@stencil/core";
 import { DateTime } from "luxon";
+import { DefaultMixins } from "../utils/internal/component";
+import { hasKeyboardMode } from "../utils/internal/mixins/setup.mixin";
 import { OnListener } from "../utils/listener";
-const LUXON_FORMAT_PATTERNS = {
-    // h, hh, H, HH and various time formats that include hours
-    hours: /\b[Hh]\b|HH|hh|H{3,4}|h{3,4}|t|tt|ttt|tttt|T|TT|TTT|TTTT/,
-    // m, mm and time formats that include minutes
-    minutes: /\bm\b|mm|t|tt|ttt|tttt|T|TT|TTT|TTTT/,
-    // s, ss and time formats that include seconds
-    seconds: /\bs\b|ss|tt|ttt|tttt|TT|TTT|TTTT/,
-    // S, SSS (milliseconds), u/uu/uuu (fractional seconds), x/X (timestamps)
-    milliseconds: /\bS\b|SSS|u|uu|uuu/,
-};
+import { closestPassShadow } from "../utils/shadow-dom";
+import { buildTimePickerColumnNumberArrays } from "./time-picker-column-values";
+import { computeTimeWithRawUnitValue } from "./time-picker-compute-time";
+import { getTimePickerConstraintBounds, hasActiveTimePickerConstraints, isWithinTimePickerConstraints, timeOfDayRangeIntersectsInclusiveBounds, } from "./time-picker-constraints";
+import { formatTimePickerUnitValue, getTimePickerColumnSeparator, } from "./time-picker-display";
+import { isFormat12Hour, LUXON_FORMAT_PATTERNS } from "./time-picker-format";
+import { isSelectableForUnitWithinBounds } from "./time-picker-range";
+import { findNextSelectableRingValue } from "./time-picker-step-focus";
 const HOUR_INTERVAL_DEFAULT = 1;
 const MINUTE_INTERVAL_DEFAULT = 1;
 const SECOND_INTERVAL_DEFAULT = 1;
@@ -41,90 +41,17 @@ const FORMATTED_TIME_EMPTY = {
     second: '',
     millisecond: '',
 };
-export class TimePicker {
+export class TimePicker extends Mixin(...DefaultMixins) {
     constructor() {
-        /**
-         * Format of time string.
-         * See {@link https://moment.github.io/luxon/#/formatting?id=table-of-tokens} for all available tokens.
-         * Note: Formats that combine date and time (like f or F) are not supported. Timestamp tokens x and X are not supported either.
-         */
-        this.format = 'TT';
-        /**
-         * Corner style.
-         */
-        this.corners = 'rounded';
-        /**
-         * Embedded style (for use in other components).
-         */
-        this.embedded = false;
-        /**
-         * @internal Temporary prop needed until datetime-picker is reworked for new design.
-         */
-        this.dateTimePickerAppearance = false;
-        /**
-         * Hides the header of the picker.
-         *
-         * @since 3.2.0
-         */
-        this.hideHeader = false;
-        /**
-         * Interval for hour selection.
-         *
-         * @since 3.2.0
-         */
-        this.hourInterval = HOUR_INTERVAL_DEFAULT;
-        /**
-         * Interval for minute selection.
-         *
-         * @since 3.2.0
-         */
-        this.minuteInterval = MINUTE_INTERVAL_DEFAULT;
-        /**
-         * Interval for second selection.
-         *
-         * @since 3.2.0
-         */
-        this.secondInterval = SECOND_INTERVAL_DEFAULT;
-        /**
-         * Interval for millisecond selection.
-         *
-         * @since 3.2.0
-         */
-        this.millisecondInterval = MILLISECOND_INTERVAL_DEFAULT;
-        /**
-         * Text of the time confirm button.
-         */
-        this.i18nConfirmTime = CONFIRM_BUTTON_DEFAULT;
-        /**
-         * Text for the top header.
-         */
-        this.i18nHeader = HEADER_DEFAULT;
-        /**
-         * Text for the hour column header.
-         */
-        this.i18nHourColumnHeader = 'hr';
-        /**
-         * Text for the minute column header.
-         */
-        // eslint-disable-next-line @stencil-community/decorators-style
-        this.i18nMinuteColumnHeader = 'min';
-        /**
-         * Text for the second column header.
-         */
-        // eslint-disable-next-line @stencil-community/decorators-style
-        this.i18nSecondColumnHeader = 'sec';
-        /**
-         * Text for the millisecond column header.
-         */
-        // eslint-disable-next-line @stencil-community/decorators-style
-        this.i18nMillisecondColumnHeader = 'ms';
-        this.formattedTime = FORMATTED_TIME_EMPTY;
-        this.timePickerDescriptors = [];
-        this.isUnitFocused = false;
-        this.focusedUnit = 'hour';
-        this.focusedValue = 0;
-        this.focusScrollAlignment = 'start';
+        super();
     }
+    hostElement;
+    /**
+     * Format of time string.
+     * See {@link https://moment.github.io/luxon/#/formatting?id=table-of-tokens} for all available tokens.
+     * Note: Formats that combine date and time (like f or F) are not supported. Timestamp tokens x and X are not supported either.
+     */
+    format = 'TT';
     watchFormatIntervalPropHandler(newValue) {
         if (!newValue) {
             return;
@@ -132,6 +59,30 @@ export class TimePicker {
         this.initPicker();
         this.updateScrollPositions();
     }
+    /**
+     * Corner style.
+     */
+    corners = 'rounded';
+    /**
+     * Embedded style (for use in other components).
+     */
+    embedded = false;
+    /**
+     * @internal Temporary prop needed until datetime-picker is reworked for new design.
+     */
+    dateTimePickerAppearance = false;
+    /**
+     * Hides the header of the picker.
+     *
+     * @since 3.2.0
+     */
+    hideHeader = false;
+    /**
+     * Interval for hour selection.
+     *
+     * @since 3.2.0
+     */
+    hourInterval = HOUR_INTERVAL_DEFAULT;
     watchHourIntervalPropHandler(newValue) {
         if (Number.isInteger(newValue) &&
             newValue >= 0 &&
@@ -142,6 +93,12 @@ export class TimePicker {
         this.printIntervalError('hour', newValue);
         this.hourInterval = HOUR_INTERVAL_DEFAULT;
     }
+    /**
+     * Interval for minute selection.
+     *
+     * @since 3.2.0
+     */
+    minuteInterval = MINUTE_INTERVAL_DEFAULT;
     watchMinuteIntervalPropHandler(newValue) {
         if (newValue >= 0 && newValue <= 59) {
             this.setTimePickerDescriptors();
@@ -150,6 +107,12 @@ export class TimePicker {
         this.printIntervalError('minute', newValue);
         this.minuteInterval = MINUTE_INTERVAL_DEFAULT;
     }
+    /**
+     * Interval for second selection.
+     *
+     * @since 3.2.0
+     */
+    secondInterval = SECOND_INTERVAL_DEFAULT;
     watchSecondIntervalPropHandler(newValue) {
         if (newValue >= 0 && newValue <= 59) {
             this.setTimePickerDescriptors();
@@ -158,6 +121,12 @@ export class TimePicker {
         this.printIntervalError('second', newValue);
         this.secondInterval = SECOND_INTERVAL_DEFAULT;
     }
+    /**
+     * Interval for millisecond selection.
+     *
+     * @since 3.2.0
+     */
+    millisecondInterval = MILLISECOND_INTERVAL_DEFAULT;
     watchMillisecondIntervalPropHandler(newValue) {
         if (newValue >= 0 && newValue <= 999) {
             this.setTimePickerDescriptors();
@@ -169,13 +138,79 @@ export class TimePicker {
     printIntervalError(intervalName, value) {
         console.error(`Value ${value} is not valid for ${intervalName}-interval. Falling back to default.`);
     }
+    warnIfConstraintTimeInvalid(prop, value, omitUnparsableWarning) {
+        const trimmed = value?.trim();
+        if (!trimmed) {
+            return;
+        }
+        const parsed = DateTime.fromFormat(trimmed, this.format);
+        if (parsed.isValid) {
+            return;
+        }
+        if (omitUnparsableWarning) {
+            return;
+        }
+        const detail = [parsed.invalidReason, parsed.invalidExplanation]
+            .filter(Boolean)
+            .join(': ');
+        console.warn(`[ix-time-picker] ${prop}="${trimmed}" does not match format "${this.format}". ` +
+            'The constraint is ignored until the value matches `format`.' +
+            (detail ? ` (${detail})` : ''));
+    }
+    warnIfConstraintRangeInverted(minValue, maxValue) {
+        const minTrimmed = minValue?.trim();
+        const maxTrimmed = maxValue?.trim();
+        if (!minTrimmed || !maxTrimmed) {
+            return;
+        }
+        const minParsed = DateTime.fromFormat(minTrimmed, this.format);
+        const maxParsed = DateTime.fromFormat(maxTrimmed, this.format);
+        if (!minParsed.isValid || !maxParsed.isValid) {
+            return;
+        }
+        if (minParsed > maxParsed) {
+            console.warn(`[ix-time-picker] minTime="${minTrimmed}" is later than maxTime="${maxTrimmed}" for format "${this.format}". ` +
+                'Both constraints are ignored.');
+        }
+    }
+    warnConstraintTimesIfInvalid(options) {
+        const omit = options?.omitUnparsableConstraintWarnings ?? false;
+        this.warnIfConstraintTimeInvalid('minTime', this.minTime, omit);
+        this.warnIfConstraintTimeInvalid('maxTime', this.maxTime, omit);
+        this.warnIfConstraintRangeInverted(this.minTime, this.maxTime);
+    }
+    /**
+     * Selected time value.
+     * Format has to match the `format` property.
+     */
+    time;
     watchTimePropHandler(newValue) {
+        if (newValue === undefined || newValue === '') {
+            this._time = this.getDefaultTime();
+            return;
+        }
         const timeFormat = DateTime.fromFormat(newValue, this.format);
         if (!timeFormat.isValid) {
             throw new Error('Format is not supported or not correct');
         }
         this._time = timeFormat;
     }
+    /** Earliest selectable time (`format` tokens). Invalid non-empty values are ignored.
+     *
+     * @since 5.0.0 */
+    minTime;
+    /** Latest selectable time (`format` tokens). Invalid non-empty values are ignored.
+     *
+     * @since 5.0.0 */
+    maxTime;
+    watchMinTimePropHandler() {
+        this.warnConstraintTimesIfInvalid();
+        this.syncKeyboardFocusWithConstraints();
+    }
+    watchMaxTimePropHandler() {
+        this.warnConstraintTimesIfInvalid();
+        this.syncKeyboardFocusWithConstraints();
+    }
     /**
      * Get default time value
      * @returns DateTime.now() for empty state (no selection)
@@ -183,27 +218,72 @@ export class TimePicker {
     getDefaultTime() {
         return DateTime.now();
     }
+    /**
+     * Text of the time confirm button.
+     */
+    i18nConfirmTime = CONFIRM_BUTTON_DEFAULT;
+    /**
+     * Text for the top header.
+     */
+    i18nHeader = HEADER_DEFAULT;
+    /**
+     * Text for the hour column header.
+     */
+    i18nHourColumnHeader = 'hr';
+    /**
+     * Text for the minute column header.
+     */
+    // eslint-disable-next-line @stencil-community/decorators-style
+    i18nMinuteColumnHeader = 'min';
+    /**
+     * Text for the second column header.
+     */
+    // eslint-disable-next-line @stencil-community/decorators-style
+    i18nSecondColumnHeader = 'sec';
+    /**
+     * Text for the millisecond column header.
+     */
+    // eslint-disable-next-line @stencil-community/decorators-style
+    i18nMillisecondColumnHeader = 'ms';
+    /**
+     * Time event. Emitted when the user confirms the selected time.
+     */
+    timeSelect;
+    /**
+     * Time change event. Emitted when the selected time changes while interacting with the picker.
+     */
+    timeChange;
     /**
      * Get the current time based on the wanted format
      */
     async getCurrentTime() {
-        var _a;
-        return (_a = this._time) === null || _a === void 0 ? void 0 : _a.toFormat(this.format);
+        return this._time?.toFormat(this.format);
     }
+    _time;
     onTimeChange() {
         const formattedTimeOld = this.formattedTime;
         this.setTimeRef();
         this.formattedTime = this.getFormattedTime();
         this.updateScrollPositions(formattedTimeOld);
     }
+    timeRef;
+    formattedTime = FORMATTED_TIME_EMPTY;
+    timePickerDescriptors = [];
+    isUnitFocused = false;
+    focusedUnit = 'hour';
+    focusedValue = 0;
+    visibilityObserver;
+    focusScrollAlignment = 'start';
     componentWillLoad() {
         this.initPicker();
     }
     initPicker() {
         let parsedTime;
+        let timePropDoesNotMatchFormat = false;
         if (this.time) {
             parsedTime = DateTime.fromFormat(this.time, this.format);
             if (!parsedTime.isValid) {
+                timePropDoesNotMatchFormat = true;
                 console.error(`Invalid time format. The configured format does not match the format of the passed time. ${parsedTime.invalidReason}: ${parsedTime.invalidExplanation}`);
                 parsedTime = this.getDefaultTime();
             }
@@ -213,28 +293,40 @@ export class TimePicker {
         }
         this._time = parsedTime;
         this.setTimeRef();
+        this.formattedTime = this.getFormattedTime();
         this.setTimePickerDescriptors();
         this.setInitialFocusedValueAndUnit();
         this.watchHourIntervalPropHandler(this.hourInterval);
         this.watchMinuteIntervalPropHandler(this.minuteInterval);
         this.watchSecondIntervalPropHandler(this.secondInterval);
         this.watchMillisecondIntervalPropHandler(this.millisecondInterval);
+        this.warnConstraintTimesIfInvalid({
+            omitUnparsableConstraintWarnings: timePropDoesNotMatchFormat,
+        });
     }
     componentDidLoad() {
+        super.componentDidLoad?.();
         this.updateScrollPositions();
         this.setupVisibilityObserver();
     }
     componentDidRender() {
-        if (this.isUnitFocused) {
-            const elementContainer = this.getElementContainer(this.focusedUnit, this.focusedValue);
-            const elementList = this.getElementList(this.focusedUnit);
-            if (elementContainer) {
+        if (!this.isUnitFocused) {
+            return;
+        }
+        const elementContainer = this.getElementContainer(this.focusedUnit, this.focusedValue);
+        const elementList = this.getElementList(this.focusedUnit);
+        if (!elementContainer) {
+            return;
+        }
+        if (hasKeyboardMode()) {
+            const active = this.hostElement.shadowRoot?.activeElement;
+            if (active !== elementContainer) {
                 elementContainer.focus({ preventScroll: true });
-                if (!this.isElementVisible(elementContainer, elementList)) {
-                    this.scrollElementIntoView(elementContainer, elementList, this.focusScrollAlignment);
-                }
             }
         }
+        if (!this.isElementVisible(elementContainer, elementList)) {
+            this.scrollElementIntoView(elementContainer, elementList, this.focusScrollAlignment);
+        }
     }
     disconnectedCallback() {
         if (this.visibilityObserver) {
@@ -245,44 +337,29 @@ export class TimePicker {
         if (!this.isUnitFocused) {
             return;
         }
-        let newValue = this.focusedValue;
         let shouldPreventDefault = true;
-        let newValueInterval;
-        switch (this.focusedUnit) {
-            case 'hour':
-                newValueInterval = this.hourInterval;
-                break;
-            case 'minute':
-                newValueInterval = this.minuteInterval;
-                break;
-            case 'second':
-                newValueInterval = this.secondInterval;
-                break;
-            case 'millisecond':
-                newValueInterval = this.millisecondInterval;
-                break;
-        }
         switch (event.key) {
             case 'Tab':
                 shouldPreventDefault = false;
                 this.isUnitFocused = false;
                 break;
             case 'ArrowUp':
-                newValue -= newValueInterval;
                 this.focusScrollAlignment = 'start';
-                this.updateFocusedValue(newValue);
-                this.updateDescriptorFocusedValue(this.focusedUnit, this.focusedValue);
+                this.stepFocusedValue(-1);
                 break;
             case 'ArrowDown':
-                newValue += newValueInterval;
                 this.focusScrollAlignment = 'end';
-                this.updateFocusedValue(newValue);
-                this.updateDescriptorFocusedValue(this.focusedUnit, this.focusedValue);
+                this.stepFocusedValue(1);
                 break;
             case 'Enter':
-            case ' ':
-                this.select(this.focusedUnit, this.focusedValue);
+            case ' ': {
+                const { bounds } = this.getUnitSelectionContext();
+                const base = this.buildCandidateBaseBeforeUnit(this.focusedUnit);
+                if (this.canSelectUnitValue(this.focusedUnit, this.focusedValue, bounds, base)) {
+                    this.select(this.focusedUnit, this.focusedValue);
+                }
                 break;
+            }
             default:
                 return;
         }
@@ -291,17 +368,22 @@ export class TimePicker {
         }
     }
     onUnitCellBlur(unit, event) {
-        var _a;
         const relatedTarget = event.relatedTarget;
+        const relatedUnit = relatedTarget?.dataset?.elementContainerId?.split('-')[0];
+        const movingWithinSameColumn = relatedUnit === unit;
         // Check if column lost focus to scroll back to selected value
-        if (relatedTarget) {
-            const relatedUnit = (_a = relatedTarget.dataset.elementContainerId) === null || _a === void 0 ? void 0 : _a.split('-')[0];
+        if (relatedTarget && !movingWithinSameColumn) {
             if (relatedUnit !== unit) {
                 this.elementListScrollToTop(unit, Number(this.formattedTime[unit]), 'smooth');
             }
         }
+        // Still within this column (e.g. roving focus between cells)
+        if (movingWithinSameColumn) {
+            return;
+        }
         this.isUnitFocused = false;
-        const focusedValue = Number(this.formattedTime[unit]);
+        const focusedValue = this.resolvePreservedFocusedValueOnColumnBlur(unit);
+        this.focusedValue = focusedValue;
         this.updateDescriptorFocusedValue(unit, focusedValue);
     }
     onUnitCellFocus(unit, value) {
@@ -311,12 +393,10 @@ export class TimePicker {
         this.updateDescriptorFocusedValue(unit, value);
     }
     getElementList(unit) {
-        var _a;
-        return (_a = this.hostElement.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector(`[data-element-list-id="${unit}"]`);
+        return this.hostElement.shadowRoot?.querySelector(`[data-element-list-id="${unit}"]`);
     }
     getElementContainer(unit, number) {
-        var _a;
-        return (_a = this.hostElement.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector(`[data-element-container-id="${unit}-${number}"]`);
+        return this.hostElement.shadowRoot?.querySelector(`[data-element-container-id="${unit}-${number}"]`);
     }
     isElementVisible(element, container) {
         const elementRect = element.getBoundingClientRect();
@@ -337,42 +417,21 @@ export class TimePicker {
                 elementRect.top - containerRect.top - SCROLL_BUFFER;
         }
     }
-    updateFocusedValue(value) {
-        const numberArray = this.getNumberArrayForUnit(this.focusedUnit);
-        const maxValue = numberArray[numberArray.length - 1];
-        const minValue = numberArray[0];
-        if (value > maxValue) {
-            value = minValue;
-            this.focusScrollAlignment = 'start';
-        }
-        else if (value < minValue) {
-            value = maxValue;
-            this.focusScrollAlignment = 'end';
-        }
-        this.focusedValue = value;
-    }
     setInitialFocusedValueAndUnit() {
         const firstVisibleDescriptor = this.timePickerDescriptors.find((descriptor) => !descriptor.hidden);
         if (!firstVisibleDescriptor) {
             return;
         }
-        const selectedValue = Number(this.formattedTime[firstVisibleDescriptor.unit]);
-        const isValidSelection = firstVisibleDescriptor.numberArray.includes(selectedValue);
-        this.focusedValue = isValidSelection
-            ? selectedValue
-            : firstVisibleDescriptor.numberArray[0];
+        this.focusedValue = this.getConstrainedFocusedValueForUnit(firstVisibleDescriptor.unit, firstVisibleDescriptor.numberArray);
         this.focusedUnit = firstVisibleDescriptor.unit;
     }
     setupVisibilityObserver() {
-        let dropdownElement = this.hostElement;
-        while (dropdownElement && dropdownElement.tagName !== 'IX-DROPDOWN') {
-            dropdownElement = dropdownElement.parentElement;
-        }
-        if (!dropdownElement) {
+        const dropdown = closestPassShadow(this.hostElement, 'ix-dropdown');
+        if (!dropdown) {
             return;
         }
         this.visibilityObserver = new MutationObserver((mutations) => this.mutationObserverCallback(mutations));
-        this.visibilityObserver.observe(dropdownElement, {
+        this.visibilityObserver.observe(dropdown, {
             attributes: true,
             attributeFilter: ['class', 'style'],
         });
@@ -402,8 +461,7 @@ export class TimePicker {
         }
     }
     areElementsRendered() {
-        var _a;
-        const elementLists = (_a = this.hostElement.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelectorAll('.element-list');
+        const elementLists = this.hostElement.shadowRoot?.querySelectorAll('.element-list');
         if (!elementLists || elementLists.length === 0) {
             return false;
         }
@@ -422,33 +480,6 @@ export class TimePicker {
             millisecond: this._time.toFormat('S'),
         };
     }
-    timeUpdate(unit, value) {
-        let maxValue = DateTime.now().endOf('day').get(unit);
-        if (unit === 'hour') {
-            if (this.timeRef === 'PM') {
-                // 12 PM should remain 12, other PM hours add 12
-                value = value === 12 ? 12 : value + 12;
-            }
-            else if (this.timeRef === 'AM') {
-                // 12 AM should be 0, other AM hours remain as is
-                value = value === 12 ? 0 : value;
-                maxValue = 12;
-            }
-        }
-        if (value > maxValue) {
-            value = maxValue;
-        }
-        else if (value < 0) {
-            value = 0;
-        }
-        if (!this._time) {
-            this._time = DateTime.now().startOf('day');
-        }
-        this._time = this._time.set({
-            [unit]: value,
-        });
-        return value;
-    }
     changeTimeReference(newTimeRef) {
         if (this.timeRef === newTimeRef) {
             return;
@@ -456,6 +487,8 @@ export class TimePicker {
         if (!this._time) {
             this._time = DateTime.now().startOf('day');
         }
+        const previousTime = this._time;
+        const previousRef = this.timeRef;
         this.timeRef = newTimeRef;
         const currentHour = this._time.hour;
         if (newTimeRef === 'PM' && currentHour < 12) {
@@ -464,83 +497,256 @@ export class TimePicker {
         else if (newTimeRef === 'AM' && currentHour >= 12) {
             this._time = this._time.minus({ hours: 12 });
         }
+        if (!this.isWithinTimeConstraints(this._time)) {
+            this._time = previousTime;
+            this.timeRef = previousRef;
+            return;
+        }
         this.timeChange.emit(this._time.toFormat(this.format));
     }
-    isFormat12Hour(format) {
-        // Remove any text that's inside quotes (literal text in Luxon format strings)
-        let cleanFormat = '';
-        let inQuote = false;
-        for (let i = 0; i < format.length; i++) {
-            const char = format[i];
-            if (char === "'") {
-                inQuote = !inQuote;
+    /** `_time` or “now” (constraints, AM/PM, confirm). */
+    referenceOrNow() {
+        return this._time ?? DateTime.now();
+    }
+    setTimeRef() {
+        const uses12HourFormat = isFormat12Hour(this.format);
+        if (!uses12HourFormat) {
+            this.timeRef = undefined;
+            return;
+        }
+        const clock = this.referenceOrNow();
+        this.timeRef = clock.hour >= 12 ? 'PM' : 'AM';
+    }
+    getConstraintBounds(referenceClock) {
+        const baseDay = (referenceClock ?? this.referenceOrNow()).startOf('day');
+        return getTimePickerConstraintBounds(this.minTime, this.maxTime, this.format, baseDay);
+    }
+    /** Bounds and `selectionBase` from {@link referenceOrNow}. */
+    getUnitSelectionContext() {
+        const referenceClock = this.referenceOrNow();
+        return {
+            bounds: this.getConstraintBounds(referenceClock),
+            selectionBase: this._time ?? referenceClock.startOf('day'),
+        };
+    }
+    isWithinTimeConstraints(candidate) {
+        const { min, max } = this.getConstraintBounds();
+        return isWithinTimePickerConstraints(candidate, min, max);
+    }
+    canSelectUnitValue(unit, rawValue, bounds, selectionBase) {
+        const base = selectionBase ?? this._time ?? DateTime.now().startOf('day');
+        const effectiveBounds = bounds ?? this.getConstraintBounds();
+        if (unit === 'hour' &&
+            hasActiveTimePickerConstraints(effectiveBounds.min, effectiveBounds.max)) {
+            const dayStart = base.startOf('day');
+            const hourStart = computeTimeWithRawUnitValue(dayStart, 'hour', rawValue, this.timeRef);
+            if (!hourStart) {
+                return false;
+            }
+            const hourEnd = hourStart.set({
+                minute: 59,
+                second: 59,
+                millisecond: 999,
+            });
+            return timeOfDayRangeIntersectsInclusiveBounds(hourStart, hourEnd, effectiveBounds.min, effectiveBounds.max);
+        }
+        const candidate = computeTimeWithRawUnitValue(base, unit, rawValue, this.timeRef);
+        if (!candidate) {
+            return false;
+        }
+        if (bounds) {
+            return this.isSelectableForUnitWithinBounds(unit, candidate, bounds);
+        }
+        return this.isWithinTimeConstraints(candidate);
+    }
+    isSelectableForUnitWithinBounds(unit, candidate, bounds) {
+        return isSelectableForUnitWithinBounds(unit, candidate, bounds);
+    }
+    /** Provisional `unit` for cross-column base: roving cell, earlier descriptors, else displayed digits. */
+    getProvisionalRawValue(unit) {
+        if (this.focusedUnit === unit) {
+            return this.focusedValue;
+        }
+        const order = this.timePickerDescriptors.map((d) => d.unit);
+        const iFocused = order.indexOf(this.focusedUnit);
+        const iUnit = order.indexOf(unit);
+        if (iUnit !== -1 && iFocused !== -1 && iUnit < iFocused) {
+            const d = this.timePickerDescriptors.find((x) => x.unit === unit);
+            if (d) {
+                return d.focusedValue;
             }
-            else if (!inQuote) {
-                cleanFormat += char;
+        }
+        const raw = this.formattedTime?.[unit];
+        if (raw === '' || raw === undefined) {
+            return 0;
+        }
+        return Number(raw);
+    }
+    /** Base time for `canSelect`/`select` on `targetUnit`: committed hour; mid-columns via {@link getProvisionalRawValue}. */
+    buildCandidateBaseBeforeUnit(targetUnit) {
+        const { selectionBase } = this.getUnitSelectionContext();
+        const order = this.timePickerDescriptors.map((d) => d.unit);
+        const targetIndex = order.indexOf(targetUnit);
+        if (targetIndex <= 0) {
+            return selectionBase;
+        }
+        let base = this._time ?? selectionBase;
+        for (let i = 1; i < targetIndex; i++) {
+            const unit = order[i];
+            if (unit === undefined) {
+                continue;
+            }
+            const raw = this.getProvisionalRawValue(unit);
+            const next = computeTimeWithRawUnitValue(base, unit, raw, this.timeRef);
+            if (next) {
+                base = next;
             }
         }
-        // Check for specific 12-hour format tokens
-        // Case-sensitive matching to distinguish between 'h' and 'H'
-        return /h|a|t/.test(cleanFormat);
+        return base;
     }
-    setTimeRef() {
-        const uses12HourFormat = this.isFormat12Hour(this.format);
-        if (uses12HourFormat && this._time) {
-            this.timeRef = this._time.hour >= 12 ? 'PM' : 'AM';
+    getConstrainedFocusedValueForUnitWithBase(unit, numberArray, baseBeforeUnit) {
+        const { bounds } = this.getUnitSelectionContext();
+        const pickFirstSelectable = () => {
+            const found = numberArray.find((n) => this.canSelectUnitValue(unit, n, bounds, baseBeforeUnit));
+            return found ?? null;
+        };
+        const selected = Number(this.formattedTime[unit]);
+        if (!numberArray.includes(selected)) {
+            return pickFirstSelectable() ?? numberArray[0];
         }
-        else {
-            this.timeRef = undefined;
+        if (this.canSelectUnitValue(unit, selected, bounds, baseBeforeUnit)) {
+            return selected;
         }
+        return pickFirstSelectable() ?? numberArray[0];
     }
-    getInitialFocusedValueForUnit(unit, numberArray) {
-        const selectedValue = Number(this.formattedTime[unit]);
-        return numberArray.includes(selectedValue) ? selectedValue : numberArray[0];
+    getConstrainedFocusedValueForUnit(unit, numberArray) {
+        return this.getConstrainedFocusedValueForUnitWithBase(unit, numberArray, this.buildCandidateBaseBeforeUnit(unit));
     }
-    setTimePickerDescriptors() {
-        let hourNumbers = [];
-        let minuteNumbers = [];
-        let secondNumbers = [];
-        let millisecondsNumbers = [];
-        if (this.timeRef !== undefined) {
-            hourNumbers = Array.from({ length: Math.ceil(12 / this.hourInterval) }, (_, i) => i * this.hourInterval + 1).filter((hour) => hour <= 12);
+    resolvePreservedFocusedValueOnColumnBlur(unit) {
+        const arr = this.getNumberArrayForUnit(unit);
+        const { bounds } = this.getUnitSelectionContext();
+        const base = this.buildCandidateBaseBeforeUnit(unit);
+        const current = this.focusedValue;
+        if (arr.includes(current) &&
+            this.canSelectUnitValue(unit, current, bounds, base)) {
+            return current;
         }
-        else {
-            hourNumbers = Array.from({ length: Math.ceil(24 / this.hourInterval) }, (_, i) => i * this.hourInterval);
+        return this.getConstrainedFocusedValueForUnit(unit, arr);
+    }
+    syncKeyboardFocusWithConstraints() {
+        if (!this.timePickerDescriptors.length) {
+            return;
+        }
+        for (const d of this.timePickerDescriptors) {
+            const next = this.getConstrainedFocusedValueForUnit(d.unit, d.numberArray);
+            if (next !== d.focusedValue) {
+                this.updateDescriptorFocusedValue(d.unit, next);
+            }
         }
-        minuteNumbers = Array.from({ length: Math.ceil(60 / this.minuteInterval) }, (_, i) => i * this.minuteInterval);
-        secondNumbers = Array.from({ length: Math.ceil(60 / this.secondInterval) }, (_, i) => i * this.secondInterval);
-        millisecondsNumbers = Array.from({ length: Math.ceil(1000 / this.millisecondInterval) }, (_, i) => i * this.millisecondInterval);
-        this.timePickerDescriptors = [
+        const arr = this.getNumberArrayForUnit(this.focusedUnit);
+        if (arr.length) {
+            const nextFocused = this.getConstrainedFocusedValueForUnit(this.focusedUnit, arr);
+            if (nextFocused !== this.focusedValue) {
+                this.focusedValue = nextFocused;
+            }
+        }
+    }
+    findFirstSelectableInUnit(unit) {
+        const arr = this.getNumberArrayForUnit(unit);
+        const { bounds } = this.getUnitSelectionContext();
+        const base = this.buildCandidateBaseBeforeUnit(unit);
+        const found = arr.find((n) => this.canSelectUnitValue(unit, n, bounds, base));
+        return found ?? null;
+    }
+    getColumnTabStopValue(unit) {
+        const d = this.timePickerDescriptors.find((x) => x.unit === unit);
+        const arr = d?.numberArray ?? [];
+        if (!d || !arr.length) {
+            return null;
+        }
+        const { bounds } = this.getUnitSelectionContext();
+        const base = this.buildCandidateBaseBeforeUnit(unit);
+        const candidate = d.focusedValue;
+        if (arr.includes(candidate) &&
+            this.canSelectUnitValue(unit, candidate, bounds, base)) {
+            return candidate;
+        }
+        return this.findFirstSelectableInUnit(unit);
+    }
+    stepFocusedValue(direction) {
+        const unit = this.focusedUnit;
+        const arr = this.getNumberArrayForUnit(unit);
+        const { bounds } = this.getUnitSelectionContext();
+        const base = this.buildCandidateBaseBeforeUnit(unit);
+        const next = findNextSelectableRingValue(arr, this.focusedValue, direction, (candidate) => this.canSelectUnitValue(unit, candidate, bounds, base));
+        if (next === null) {
+            return;
+        }
+        this.focusedValue = next;
+        this.updateDescriptorFocusedValue(unit, next);
+    }
+    isConfirmDisabled() {
+        const referenceClock = this.referenceOrNow();
+        const { min, max } = this.getConstraintBounds(referenceClock);
+        if (!hasActiveTimePickerConstraints(min, max)) {
+            return false;
+        }
+        return !isWithinTimePickerConstraints(referenceClock, min, max);
+    }
+    setTimePickerDescriptors() {
+        const { hourNumbers, minuteNumbers, secondNumbers, millisecondsNumbers } = buildTimePickerColumnNumberArrays({
+            hourInterval: this.hourInterval,
+            minuteInterval: this.minuteInterval,
+            secondInterval: this.secondInterval,
+            millisecondInterval: this.millisecondInterval,
+        }, this.timeRef);
+        const { selectionBase } = this.getUnitSelectionContext();
+        const columns = [
             {
                 unit: 'hour',
                 header: this.i18nHourColumnHeader,
                 hidden: !LUXON_FORMAT_PATTERNS.hours.test(this.format),
                 numberArray: hourNumbers,
-                focusedValue: this.getInitialFocusedValueForUnit('hour', hourNumbers),
             },
             {
                 unit: 'minute',
                 header: this.i18nMinuteColumnHeader,
                 hidden: !LUXON_FORMAT_PATTERNS.minutes.test(this.format),
                 numberArray: minuteNumbers,
-                focusedValue: this.getInitialFocusedValueForUnit('minute', minuteNumbers),
             },
             {
                 unit: 'second',
                 header: this.i18nSecondColumnHeader,
                 hidden: !LUXON_FORMAT_PATTERNS.seconds.test(this.format),
                 numberArray: secondNumbers,
-                focusedValue: this.getInitialFocusedValueForUnit('second', secondNumbers),
             },
             {
                 unit: 'millisecond',
                 header: this.i18nMillisecondColumnHeader,
                 hidden: !LUXON_FORMAT_PATTERNS.milliseconds.test(this.format),
                 numberArray: millisecondsNumbers,
-                focusedValue: this.getInitialFocusedValueForUnit('millisecond', millisecondsNumbers),
             },
         ];
-        this.timePickerDescriptors = this.timePickerDescriptors.filter((item) => !item.hidden);
+        let base = selectionBase;
+        const descriptors = [];
+        for (const col of columns) {
+            if (col.hidden) {
+                continue;
+            }
+            const focusedValue = this.getConstrainedFocusedValueForUnitWithBase(col.unit, col.numberArray, base);
+            descriptors.push({
+                unit: col.unit,
+                header: col.header,
+                hidden: false,
+                numberArray: col.numberArray,
+                focusedValue,
+            });
+            const next = computeTimeWithRawUnitValue(base, col.unit, focusedValue, this.timeRef);
+            if (next) {
+                base = next;
+            }
+        }
+        this.timePickerDescriptors = descriptors;
     }
     getNumberArrayForUnit(unit) {
         const descriptor = this.timePickerDescriptors.find((descriptor) => descriptor.unit === unit);
@@ -549,12 +755,40 @@ export class TimePicker {
     isSelected(unit, number) {
         return this.formattedTime[unit] === String(number);
     }
+    /** Roving tabindex: one tab stop per column; active column only the focused cell has `tabindex=0`. */
+    getUnitCellTabIndex(unit, number) {
+        const { bounds } = this.getUnitSelectionContext();
+        const base = this.buildCandidateBaseBeforeUnit(unit);
+        const cellIsSelectable = this.canSelectUnitValue(unit, number, bounds, base);
+        if (!cellIsSelectable) {
+            return -1;
+        }
+        if (this.isUnitFocused && this.focusedUnit === unit) {
+            return this.focusedValue === number ? 0 : -1;
+        }
+        const stop = this.getColumnTabStopValue(unit);
+        if (stop === null) {
+            return -1;
+        }
+        return stop === number ? 0 : -1;
+    }
     select(unit, number) {
         if (this.isSelected(unit, number)) {
             return;
         }
-        this.formattedTime = Object.assign(Object.assign({}, this.formattedTime), { [unit]: String(number) });
-        this.timeUpdate(unit, number);
+        const { bounds } = this.getUnitSelectionContext();
+        const base = this.buildCandidateBaseBeforeUnit(unit);
+        if (!this.canSelectUnitValue(unit, number, bounds, base)) {
+            return;
+        }
+        const candidate = computeTimeWithRawUnitValue(base, unit, number, this.timeRef);
+        if (!candidate) {
+            return;
+        }
+        if (this._time && candidate.toMillis() === this._time.toMillis()) {
+            return;
+        }
+        this._time = candidate;
         this.elementListScrollToTop(unit, number, 'smooth');
         this.timeChange.emit(this._time.toFormat(this.format));
     }
@@ -563,7 +797,10 @@ export class TimePicker {
         if (descriptorIndex !== -1) {
             this.timePickerDescriptors = [
                 ...this.timePickerDescriptors.slice(0, descriptorIndex),
-                Object.assign(Object.assign({}, this.timePickerDescriptors[descriptorIndex]), { focusedValue: value }),
+                {
+                    ...this.timePickerDescriptors[descriptorIndex],
+                    focusedValue: value,
+                },
                 ...this.timePickerDescriptors.slice(descriptorIndex + 1),
             ];
         }
@@ -604,52 +841,45 @@ export class TimePicker {
         }
     }
     formatUnitValue(unit, value) {
-        if (unit === 'millisecond') {
-            return value.toString().padStart(3, '0');
-        }
-        return value < 10 ? `0${value}` : value.toString();
+        return formatTimePickerUnitValue(unit, value);
     }
     getColumnSeparator(currentIndex) {
-        if (currentIndex + 1 < this.timePickerDescriptors.length) {
-            const nextUnit = this.timePickerDescriptors[currentIndex + 1].unit;
-            return nextUnit === 'millisecond' ? '.' : ':';
-        }
-        return ':';
-    }
-    getElementContainerTabIndex(number, descriptorUnit) {
-        const descriptor = this.timePickerDescriptors.find((d) => d.unit === descriptorUnit);
-        if (number === (descriptor === null || descriptor === void 0 ? void 0 : descriptor.focusedValue)) {
-            return '0';
-        }
-        return '-1';
+        return getTimePickerColumnSeparator(currentIndex, this.timePickerDescriptors);
     }
     render() {
-        return (h(Host, { key: 'bf0e82d6cc6f70a2bd0e07070779b597a51f985e' }, h("ix-date-time-card", { key: 'efe51b660fa864e91aaa9c8fd202413fa097a226', embedded: this.embedded, timePickerAppearance: true, corners: this.corners, hasFooter: !this.dateTimePickerAppearance, hideHeader: this.hideHeader }, h("div", { key: 'bb5e54a50faae4fdc6bddca52d3cd887781cac95', class: "header", slot: "header" }, h("ix-typography", { key: 'b8bd91e7ab853091c447852e31512eaa8311675b', format: "body" }, this.i18nHeader)), h("div", { key: '2b6d7fad8c616631a8b9d5338d40cd967d2a79df', class: "clock" }, this.timePickerDescriptors.map((descriptor, index) => (h("div", { class: "flex" }, h("div", { class: { columns: true, hidden: descriptor.hidden } }, h("div", { class: "column-header", title: descriptor.header }, descriptor.header), h("div", { "data-element-list-id": descriptor.unit, class: "element-list", tabIndex: -1 }, descriptor.numberArray.map((number) => {
-            return (h("button", { "data-element-container-id": `${descriptor.unit}-${number}`, class: {
-                    selected: this.isSelected(descriptor.unit, number),
-                    'element-container': true,
-                }, onClick: () => {
-                    this.select(descriptor.unit, number);
-                }, onFocus: () => this.onUnitCellFocus(descriptor.unit, number), onBlur: (e) => this.onUnitCellBlur(descriptor.unit, e), tabindex: this.getElementContainerTabIndex(number, descriptor.unit), "aria-label": `${descriptor.header}: ${number}` }, this.formatUnitValue(descriptor.unit, number)));
-        }), h("div", { class: "element-list-padding" }))), index !== this.timePickerDescriptors.length - 1 && (h("div", { class: {
-                'column-separator': true,
-                hidden: descriptor.hidden,
-            } }, this.getColumnSeparator(index)))))), this.timeRef && (h("div", { key: 'f4b91233c7d069751b67b0e78b88e7130460dd48', class: "flex" }, h("div", { key: '2594a5881fb34d210893763d0cb2619902b5b931', class: "column-separator" }), h("div", { key: '66f23a06c1335cdcdd4c5c3892d8271cdd75be00', class: "columns" }, h("div", { key: '02945548ecd7b4aa4af27afb1dd30bd444fab251', class: "column-header", title: "AM/PM" }), h("div", { key: '7af4619130b2567eb6a7f0dd774e6222fba3ae63', class: "element-list", tabIndex: -1 }, h("button", { key: '0e3f956ea8e3c530eb96b941360a42e3a930e49f', "data-am-pm-id": "AM", class: {
+        const { bounds } = this.getUnitSelectionContext();
+        return (h(Host, { key: '148f502158a23cb3653c1f062a69cff199e93fdc' }, h("ix-date-time-card", { key: '5612a12cfb0a8b3c55c3491fcae620d63fa0bbd7', embedded: this.embedded, timePickerAppearance: true, corners: this.corners, hasFooter: !this.dateTimePickerAppearance, hideHeader: this.hideHeader }, h("div", { key: '80c1720b837cc3cef4fb4590f68dfe1ab23b8370', class: "header", slot: "header" }, h("ix-typography", { key: '087b23019ec2213c3a23b0c1c08da2328af144be', format: "body" }, this.i18nHeader)), h("div", { key: '1c4c0a0ca82ae0633fbecd5ed9453493c7b9cf98', class: "clock" }, this.timePickerDescriptors.map((descriptor, index) => {
+            return (h("div", { class: "flex" }, h("div", { class: { columns: true, hidden: descriptor.hidden }, hidden: descriptor.hidden }, h("div", { class: "column-header", title: descriptor.header }, descriptor.header), h("div", { role: "listbox", "aria-label": descriptor.header, "data-element-list-id": descriptor.unit, class: "element-list", tabindex: -1 }, descriptor.numberArray.map((number) => {
+                const cellTabIndex = this.getUnitCellTabIndex(descriptor.unit, number);
+                const disabled = !this.canSelectUnitValue(descriptor.unit, number, bounds, this.buildCandidateBaseBeforeUnit(descriptor.unit));
+                const selected = this.isSelected(descriptor.unit, number);
+                return (h("button", { role: "option", "aria-selected": selected ? 'true' : 'false', "data-element-container-id": `${descriptor.unit}-${number}`, class: {
+                        selected,
+                        'element-container': true,
+                        disabled,
+                    }, disabled: disabled, onClick: () => {
+                        this.select(descriptor.unit, number);
+                    }, onFocus: () => this.onUnitCellFocus(descriptor.unit, number), onBlur: (e) => this.onUnitCellBlur(descriptor.unit, e), "aria-label": `${descriptor.header}: ${number}`, tabindex: cellTabIndex }, this.formatUnitValue(descriptor.unit, number)));
+            }), h("div", { class: "element-list-padding" }))), index !== this.timePickerDescriptors.length - 1 && (h("div", { class: {
+                    'column-separator': true,
+                    hidden: descriptor.hidden,
+                } }, this.getColumnSeparator(index)))));
+        }), this.timeRef && (h("div", { key: 'aee3e153f67ba1365ff56d36a72d1d5561d30e2a', class: "flex" }, h("div", { key: 'd18821a7a032522e161fdd1e74a5812d2111a6ae', class: "column-separator" }), h("div", { key: '57db4e6409de2fbf5d13647304af280866845695', class: "columns" }, h("div", { key: 'd60b46a2bc28606c7708eb3dbccee6fe76df8cc5', class: "column-header", title: "AM/PM" }), h("div", { key: '2d33c518b011e25fb334cd8e1f1efa9b79cd35ff', role: "listbox", "aria-label": "AM/PM", class: "element-list", tabindex: -1 }, h("button", { key: '0ee352467596e646e3afc588ccaa80cad649c551', role: "option", "aria-selected": this.timeRef === 'AM' ? 'true' : 'false', "data-am-pm-id": "AM", class: {
                 selected: this.timeRef === 'AM',
                 'element-container': true,
-            }, onClick: () => this.changeTimeReference('AM'), tabindex: "0", "aria-label": "AM" }, "AM"), h("button", { key: '5edf7bd09a475bd976319326bfa30719724c4a05', "data-am-pm-id": "PM", class: {
+            }, onClick: () => this.changeTimeReference('AM'), tabindex: "0", "aria-label": "AM" }, "AM"), h("button", { key: '3c207b5fb9f759a101ce7d1959f93cbfda487274', role: "option", "aria-selected": this.timeRef === 'PM' ? 'true' : 'false', "data-am-pm-id": "PM", class: {
                 selected: this.timeRef === 'PM',
                 'element-container': true,
-            }, onClick: () => this.changeTimeReference('PM'), tabindex: "0", "aria-label": "PM" }, "PM")))))), h("div", { key: '2132b54d59ffda5596061f7974af5790068160ff', class: {
+            }, onClick: () => this.changeTimeReference('PM'), tabindex: "0", "aria-label": "PM" }, "PM")))))), h("div", { key: 'fc56aa00e3d0280045272303181d49fbcf473bc6', class: {
                 footer: true,
                 'footer--compact': this.timePickerDescriptors.length <= 2,
-            }, slot: "footer" }, h("ix-button", { key: 'd46dac7662296a8bcafc7fba212041f00f61f060', class: "confirm-button", onClick: () => {
-                var _a;
-                this.timeSelect.emit((_a = this._time) === null || _a === void 0 ? void 0 : _a.toFormat(this.format));
+            }, slot: "footer" }, h("ix-button", { key: '1c2361d8241d53b5f902f203b43a8bf768f8d1af', class: "confirm-button", disabled: this.isConfirmDisabled(), onClick: () => {
+                this.timeSelect.emit(this._time?.toFormat(this.format));
             } }, this.i18nConfirmTime)))));
     }
     static get is() { return "ix-time-picker"; }
     static get encapsulation() { return "shadow"; }
+    static get delegatesFocus() { return true; }
     static get originalStyleUrls() {
         return {
             "$": ["time-picker.scss"]
@@ -886,6 +1116,50 @@ export class TimePicker {
                 "reflect": false,
                 "attribute": "time"
             },
+            "minTime": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "since",
+                            "text": "5.0.0"
+                        }],
+                    "text": "Earliest selectable time (`format` tokens). Invalid non-empty values are ignored."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "min-time"
+            },
+            "maxTime": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "since",
+                            "text": "5.0.0"
+                        }],
+                    "text": "Latest selectable time (`format` tokens). Invalid non-empty values are ignored."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "max-time"
+            },
             "i18nConfirmTime": {
                 "type": "string",
                 "mutable": false,
@@ -943,7 +1217,7 @@ export class TimePicker {
                 "getter": false,
                 "setter": false,
                 "reflect": false,
-                "attribute": "i18n-column-header",
+                "attribute": "i18n-hour-column-header",
                 "defaultValue": "'hr'"
             },
             "i18nMinuteColumnHeader": {
@@ -1093,6 +1367,12 @@ export class TimePicker {
             }, {
                 "propName": "time",
                 "methodName": "watchTimePropHandler"
+            }, {
+                "propName": "minTime",
+                "methodName": "watchMinTimePropHandler"
+            }, {
+                "propName": "maxTime",
+                "methodName": "watchMaxTimePropHandler"
             }, {
                 "propName": "_time",
                 "methodName": "onTimeChange"