@aquera/nile-elements 2.0.18 → 2.0.20

package/dist/src/nile-calendar/nile-calendar.js

@@ -12,11 +12,148 @@ import { classMap } from 'lit/directives/class-map.js';
 import { watch } from '../internal/watch';
 import NileElement from '../internal/nile-element';
 import { ClearMode } from './nile-calendar.enum';
+import { TIMEZONES, isValidTimezone, isClockTime, utcFromFields, localDateFromFields, formatYear4, DEFAULT_START_YEAR, DEFAULT_END_YEAR } from './timezones';
+import { setAnimation } from '../utilities/animation-registry';
+/*  one exact moment on the timeline Eg: 2026-03-01T10:00:00Z, …+05:30  */
+const INSTANT_VALUE_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2})?(?:\.\d{1,3})?(?:Z|[+-]\d{2}:?\d{2})$/;
+/** an instant plus the zone it was picked in. Eg: 2026-03-01T10:00:00.000[GMT+05:30 Asia/Kolkata] */
+const BRACKETED_VALUE_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{3}))?\[GMT([+-])(\d{2}):(\d{2})\s+([^\]]+)\]$/;
+export function instantFromValueString(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    if (!INSTANT_VALUE_RE.test(trimmed))
+        return null;
+    const ms = new Date(trimmed).getTime();
+    return isNaN(ms) ? null : ms;
+}
+/** digits on a clock face, 2026-03-01T10:00:00 */
+const OFFSETLESS_VALUE_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?(?:\.(\d{1,3}))?$/;
+/** Digits as written, with no zone conversion. */
+export function wallClockFromOffsetLess(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const m = OFFSETLESS_VALUE_RE.exec(raw.trim());
+    if (!m)
+        return null;
+    const year = Number(m[1]);
+    const month0 = Number(m[2]) - 1;
+    const day = Number(m[3]);
+    if (month0 < 0 || month0 > 11 || day < 1)
+        return null;
+    if (!isClockTime(Number(m[4]), Number(m[5]), Number(m[6] ?? 0), Number(m[7] ?? 0)))
+        return null;
+    const lastDay = new Date(utcFromFields(year, month0 + 1, 0)).getUTCDate();
+    const t = utcFromFields(year, month0, Math.min(day, lastDay), Number(m[4]), Number(m[5]), Number(m[6] ?? 0), Number(m[7] ?? 0));
+    if (isNaN(t))
+        return null;
+    const u = new Date(t);
+    return {
+        year: u.getUTCFullYear(),
+        month: u.getUTCMonth() + 1,
+        day: u.getUTCDate(),
+        hours: u.getUTCHours(),
+        minutes: u.getUTCMinutes(),
+        seconds: u.getUTCSeconds(),
+        ms: u.getUTCMilliseconds(),
+    };
+}
+export function wallClockInZone(epochMs, zone) {
+    const formatter = new Intl.DateTimeFormat('en-US', {
+        timeZone: zone,
+        hourCycle: 'h23',
+        year: 'numeric', month: '2-digit', day: '2-digit',
+        hour: '2-digit', minute: '2-digit', second: '2-digit',
+    });
+    const parts = {};
+    for (const part of formatter.formatToParts(new Date(epochMs))) {
+        if (part.type !== 'literal')
+            parts[part.type] = Number(part.value);
+    }
+    return {
+        year: parts.year,
+        month: parts.month,
+        day: parts.day,
+        hours: parts.hour === 24 ? 0 : parts.hour,
+        minutes: parts.minute,
+        seconds: parts.second,
+        ms: ((epochMs % 1000) + 1000) % 1000,
+    };
+}
+export function instantFromBracketedValue(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const m = BRACKETED_VALUE_RE.exec(raw.trim());
+    if (!m)
+        return null;
+    const [, y, mo, d, h, mi, s, ms, sign, oh, om, rawZone] = m;
+    const zone = rawZone.trim();
+    if (!isValidTimezone(zone))
+        return null;
+    const wall = {
+        year: Number(y), month: Number(mo), day: Number(d),
+        hours: Number(h), minutes: Number(mi), seconds: Number(s), ms: Number(ms ?? 0),
+    };
+    // ISO end-of-day: exactly 24:00:00(.000) is the next day's 00:00:00; any other hour 24 or above is not a time
+    const endOfDay = wall.hours === 24;
+    if (wall.hours > 24 || (endOfDay && (wall.minutes !== 0 || wall.seconds !== 0 || wall.ms !== 0)))
+        return null;
+    const offsetMs = (sign === '-' ? -1 : 1) * (Number(oh) * 3600000 + Number(om) * 60000);
+    const wallMs = utcFromFields(wall.year, wall.month - 1, wall.day, wall.hours, wall.minutes, wall.seconds, wall.ms);
+    const candidate = wallMs - offsetMs;
+    const readBack = wallClockInZone(candidate, zone);
+    // the digits the zone must read back: the written ones, or the rolled-over next day for 24:00:00
+    const expected = endOfDay ? wallClockInZone(wallMs, 'UTC') : wall;
+    const digitsAgree = readBack.year === expected.year && readBack.month === expected.month &&
+        readBack.day === expected.day && readBack.hours === expected.hours &&
+        readBack.minutes === expected.minutes && readBack.seconds === expected.seconds &&
+        readBack.ms === expected.ms;
+    if (!digitsAgree)
+        return null;
+    return { epochMs: candidate, timezone: zone };
+}
 /**
  * Nile icon component.
  *
  * @tag nile-calendar
  *
+ * @csspart calendar-container - The outer container.
+ * @csspart calendar-switcher - The Absolute / Relative tab switcher.
+ * @csspart button-container - The default variant's button row.
+ * @csspart calendar-wrapper - Wraps the month grid.
+ * @csspart trigger - The month and year dropdown triggers.
+ * @csspart calendar-day-N - A day cell, where N is the day of the month.
+ * @csspart current-date-dot - The marker on today's date.
+ *
+ * Parts that exist only in `variant="date-time-picker"`:
+ * @csspart calendar-config - The row holding the type switcher.
+ * @csspart calendar - One month's header and grid.
+ * @csspart calendar-header - The month header row.
+ * @csspart calendar-header-prev - The previous-month icon.
+ * @csspart calendar-header-next - The next-month icon.
+ * @csspart calendar-header-center - The month and year area.
+ * @csspart days-container - The grid of day cells.
+ * @csspart day-name - A weekday label (Sun, Mon, ...).
+ * @csspart calendar-day-label - The number inside a day cell.
+ * @csspart tp-chevron - The expand / collapse control.
+ * @csspart tp-scroll-area - The scrolling area under the grid.
+ * @csspart tp-scroll-content - The content inside the scrolling area.
+ * @csspart tp-time-fields - The row of time inputs.
+ * @csspart tp-time-field - One time input (hours, minutes, seconds, milliseconds).
+ * @csspart tp-stepper - The up/down stepper inside a time input.
+ * @csspart tp-stepper-btn - Either stepper button.
+ * @csspart tp-stepper-btn-up - The increase button.
+ * @csspart tp-stepper-btn-down - The decrease button.
+ * @csspart tp-timezone - The timezone section.
+ * @csspart tp-timezone-header - The timezone label row.
+ * @csspart tp-timezone-label - The "Timezone" label.
+ * @csspart tp-timezone-local-link - The "Use local timezone" link.
+ * @csspart tp-timezone-select - The timezone select.
+ * @csspart tp-footer - The footer.
+ * @csspart tp-footer-actions - The Reset and Apply group.
+ * @csspart tp-set-to-now-button - The "Set to now" button.
+ * @csspart clear-button - The Reset button.
+ * @csspart apply-button - The Apply button.
  */
 let NileCalendar = class NileCalendar extends NileElement {
     constructor() {
@@ -25,6 +162,7 @@ let NileCalendar = class NileCalendar extends NileElement {
         this.allowedDates = JSON.stringify({});
         this.range = false;
         this.hideTypes = false;
+        this.showTypes = false;
         this.doubleClickUnselect = false;
         this.allowClear = false;
         this.type = 'absolute';
@@ -33,6 +171,7 @@ let NileCalendar = class NileCalendar extends NileElement {
         this.showMonthDropdown = false;
         this.showYearDropdown = false;
         this.dateFormat = 'MM/DD/YYYY';
+        this.structuredInput = false;
         this.startDate = null;
         this.endDate = null;
         this.isSelectingStart = true;
@@ -41,6 +180,145 @@ let NileCalendar = class NileCalendar extends NileElement {
         this.currentYear = new Date().getFullYear();
         this.allowedDatesLocal = null;
         this.disabled = false;
+        this.variant = 'default';
+        this.timezone = 'UTC';
+        /** the timezone the consumer configured; Reset restores this (internal changes never overwrite it) */
+        this.configuredTimezone = 'UTC';
+        /** the zone the component itself is assigning, so updated() can tell it from a consumer change */
+        this.internalTimezone = null;
+        this.hideTimeFields = [];
+        this.expanded = false;
+        this.tpLockedHeight = null;
+        this.tpHours = null;
+        this.tpMinutes = null;
+        this.tpSeconds = null;
+        this.tpMilliseconds = null;
+        this.tpFocusedTimeField = null;
+        /** the day the keyboard last moved to; owns the grid's single tab stop (roving tabindex) */
+        this.tpFocusDate = null;
+        this.tpEditingText = '';
+        this.seedInstant = null;
+        this.seedFieldsKey = null;
+        this.seedZone = null;
+        /** the `.base--date-time-picker` element the observer currently watches */
+        this.tpObservedBase = null;
+        this.maskValuesMap = new WeakMap();
+        this.boundMaskInputs = [];
+        this.onMaskKeydown = (e) => {
+            if (this.disabled || e.ctrlKey || e.metaKey || e.altKey)
+                return;
+            const nav = ['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End',
+                'Tab', 'Enter', 'Shift', 'Control', 'Meta', 'Alt', 'CapsLock'];
+            if (nav.includes(e.key))
+                return;
+            const nileInput = e.currentTarget;
+            const native = nileInput?.input;
+            if (!nileInput || !native)
+                return;
+            const kind = nileInput.classList.contains('time-input') ? 'time' : 'date';
+            const layout = this.maskLayoutFor(kind);
+            const values = this.maskValuesFor(native, layout);
+            const { slotPos } = this.computeMaskDisplay(values, layout);
+            const selStart = native.selectionStart ?? 0;
+            const selEnd = native.selectionEnd ?? selStart;
+            const writeMask = (display, caret) => {
+                native.value = display;
+                nileInput.value = display;
+                try {
+                    native.setSelectionRange(caret, caret);
+                }
+                catch { /* noop */ }
+            };
+            const caretAfter = (target) => {
+                const after = this.computeMaskDisplay(values, layout);
+                const np = after.slotPos[target + 1];
+                if (np !== undefined && np !== -1)
+                    return np;
+                return after.display.length;
+            };
+            if (e.key >= '0' && e.key <= '9') {
+                e.preventDefault();
+                let target = slotPos.findIndex(p => p !== -1 && p >= selStart);
+                if (target === -1)
+                    target = values.findIndex(v => v === ''); // append at the first gap
+                if (target === -1)
+                    return; // every slot full and caret past the end
+                values[target] = e.key;
+                this.clampMaskSegment(values, layout, target);
+                writeMask(this.computeMaskDisplay(values, layout).display, caretAfter(target));
+                return;
+            }
+            if (e.key === 'Backspace') {
+                e.preventDefault();
+                if (selStart !== selEnd) {
+                    for (let i = 0; i < values.length; i++) {
+                        if (slotPos[i] !== -1 && slotPos[i] >= selStart && slotPos[i] < selEnd)
+                            values[i] = '';
+                    }
+                    writeMask(this.computeMaskDisplay(values, layout).display, selStart);
+                    return;
+                }
+                let target = -1;
+                for (let i = 0; i < values.length; i++) {
+                    if (values[i] !== '' && slotPos[i] !== -1 && slotPos[i] < selStart)
+                        target = i;
+                }
+                if (target === -1)
+                    return;
+                values[target] = '';
+                const after = this.computeMaskDisplay(values, layout);
+                writeMask(after.display, after.slotPos[target] !== -1 ? after.slotPos[target] : Math.max(0, selStart - 1));
+                return;
+            }
+            if (e.key === 'Delete') {
+                e.preventDefault();
+                let target = -1;
+                for (let i = 0; i < values.length; i++) {
+                    if (values[i] !== '' && slotPos[i] !== -1 && slotPos[i] >= selStart) {
+                        target = i;
+                        break;
+                    }
+                }
+                if (target === -1)
+                    return;
+                values[target] = '';
+                const after = this.computeMaskDisplay(values, layout);
+                writeMask(after.display, after.slotPos[target] !== -1 ? after.slotPos[target] : selStart);
+                return;
+            }
+            if (e.key.length === 1)
+                e.preventDefault(); // block any other printable key
+        };
+        this.onMaskBlur = (e) => {
+            const nileInput = e.currentTarget;
+            const native = nileInput?.input;
+            if (!nileInput || !native)
+                return;
+            const kind = nileInput.classList.contains('time-input') ? 'time' : 'date';
+            const layout = this.maskLayoutFor(kind);
+            const values = this.maskValuesFor(native, layout);
+            if (!values.some(v => v !== '')) {
+                native.value = '';
+                nileInput.value = '';
+                nileInput.emit?.('nile-change', { value: '' });
+                return;
+            }
+            // left-pad any partially-typed segment, then clamp each into range
+            const segStarts = [...new Set(layout.slots.map(s => s.segStart))];
+            for (const start of segStarts) {
+                const idxs = layout.slots.map((s, i) => (s.segStart === start ? i : -1)).filter(i => i !== -1);
+                const digits = idxs.map(i => values[i]).filter(c => c !== '');
+                if (digits.length > 0 && digits.length < idxs.length) {
+                    const padded = digits.join('').padStart(idxs.length, '0');
+                    idxs.forEach((i, k) => { values[i] = padded[k]; });
+                }
+            }
+            segStarts.forEach(start => this.clampMaskSegment(values, layout, start));
+            const { display } = this.computeMaskDisplay(values, layout);
+            native.value = display;
+            nileInput.value = display;
+            nileInput.emit?.('nile-change', { value: display });
+        };
     }
     /**
      * The styles for NileCalendar
@@ -49,42 +327,182 @@ let NileCalendar = class NileCalendar extends NileElement {
     static get styles() {
         return [styles];
     }
+    setTimezoneInternally(tz) {
+        if (tz !== this.timezone)
+            this.internalTimezone = tz;
+        this.timezone = tz;
+    }
+    /** every field shown, minus the keys in hideTimeFields (a non-array value counts as an empty list) */
+    get resolvedTimeFields() {
+        const merged = {
+            hours: true,
+            minutes: true,
+            seconds: true,
+            milliseconds: true,
+            timezone: true,
+        };
+        const hidden = Array.isArray(this.hideTimeFields) ? this.hideTimeFields : [];
+        for (const key of hidden)
+            merged[key] = false;
+        return merged;
+    }
+    get tpFewFieldsNoTz() {
+        const f = this.resolvedTimeFields;
+        if (f.timezone !== false)
+            return false;
+        const timeCount = ['hours', 'minutes', 'seconds', 'milliseconds'].filter(k => f[k] !== false).length;
+        return timeCount <= 2;
+    }
     connectedCallback() {
         super.connectedCallback();
+        // before initializeValue: a zoned/bracketed value seeds the zone internally and must not become the configured one
+        if (!this.hasUpdated)
+            this.configuredTimezone = this.timezone;
         this.initializeValue();
+        // firstUpdated runs once; a re-attach (DOM move) must restore the structuredInput listeners disconnectedCallback removed (no-op unless structuredInput)
+        if (this.hasUpdated)
+            this.bindStructuredInput();
+        // disconnectedCallback dropped the observer; an already-rendered picker panel needs it back (updated() won't run on a bare re-attach)
+        if (this.hasUpdated && this.variant === 'date-time-picker')
+            this.observeCollapsedBase();
         this.emit('nile-init');
     }
     disconnectedCallback() {
         super.disconnectedCallback();
+        this.releasePanelObserver();
+        this.unbindStructuredInput();
         this.emit('nile-destroy');
     }
+    firstUpdated() {
+        this.bindStructuredInput();
+    }
     updated(changedProperties) {
         super.updated(changedProperties);
+        if (changedProperties.has('timezone')) {
+            if (this.timezone !== this.internalTimezone)
+                this.configuredTimezone = this.timezone;
+            this.internalTimezone = null;
+        }
+        if (changedProperties.has('timezone') &&
+            !changedProperties.has('valueAttribute') &&
+            this.seedInstant !== null) {
+            if (this.seedZone !== null) {
+                if (this.timezone !== this.seedZone)
+                    this.clearInstantSeed();
+            }
+            else if (this.seedFieldsKey === this.instantSeedFieldsKey()) {
+                if (isValidTimezone(this.timezone)) {
+                    this.seedFromInstant(this.seedInstant, this.timezone);
+                }
+                else {
+                    this.clearInstantSeed();
+                    this.initializeValue();
+                }
+            }
+            else {
+                this.clearInstantSeed();
+            }
+        }
+        if (changedProperties.has('structuredInput') ||
+            changedProperties.has('variant') ||
+            changedProperties.has('range') ||
+            changedProperties.has('showManualInputs') ||
+            changedProperties.has('type') ||
+            changedProperties.has('dateFormat')) {
+            this.bindStructuredInput();
+        }
         if (changedProperties.has('valueAttribute')) {
             if (!this.valueAttribute) {
                 this.value = null;
                 this.startDate = null;
                 this.endDate = null;
                 this.isSelectingStart = true;
+                if (this.variant === 'date-time-picker')
+                    this.resetTimeUnits();
             }
-            const date = new Date(this.valueAttribute || '');
+            const date = this.dateFromValueString(this.valueAttribute || '');
             if (!isNaN(date.getTime())) {
-                const offset = date.getTimezoneOffset();
-                this.value = new Date(date.getTime() - offset * 60 * 1000);
+                this.value = date;
                 this.currentMonth = this.value.getMonth();
                 this.currentYear = this.value.getFullYear();
             }
             this.initializeValue();
         }
+        if (this.variant === 'date-time-picker') {
+            this.applyMonthYearDropdownAnimation();
+            this.captureCollapsedHeight();
+        }
+        else {
+            this.releasePanelObserver(); // the default variant has no picker panel to watch (a variant switch removed it)
+        }
+    }
+    releasePanelObserver() {
+        this.tpResizeObserver?.disconnect();
+        this.tpResizeObserver = undefined;
+        this.tpObservedBase = null;
+    }
+    /** (re)points the observer at the rendered panel; a no-op while it already watches that element */
+    observeCollapsedBase() {
+        const base = this.shadowRoot?.querySelector('.base--date-time-picker');
+        if (!base) {
+            this.releasePanelObserver();
+            return null;
+        }
+        if (this.tpObservedBase !== base) {
+            this.tpResizeObserver?.disconnect();
+            this.tpResizeObserver = new ResizeObserver(() => this.measurePanel(base));
+            this.tpResizeObserver.observe(base);
+            this.tpObservedBase = base;
+        }
+        return base;
+    }
+    captureCollapsedHeight() {
+        const base = this.observeCollapsedBase();
+        if (base)
+            this.measurePanel(base);
+    }
+    measurePanel(base) {
+        if (this.expanded)
+            return;
+        const h = `${base.offsetHeight}px`;
+        if (h !== this.tpLockedHeight)
+            this.tpLockedHeight = h;
+    }
+    applyMonthYearDropdownAnimation() {
+        const apply = (root) => {
+            root?.querySelectorAll('.month-dropdown, .year-dropdown').forEach(dd => {
+                setAnimation(dd, 'dropdown.show', {
+                    keyframes: [
+                        { opacity: 0, scale: 0.9, translate: '0 -14px' },
+                        { opacity: 1, scale: 1, translate: '0 0' },
+                    ],
+                    options: { duration: 280, easing: 'cubic-bezier(0.16, 1, 0.3, 1)' },
+                });
+                setAnimation(dd, 'dropdown.hide', {
+                    keyframes: [
+                        { opacity: 1, scale: 1, translate: '0 0' },
+                        { opacity: 0, scale: 0.9, translate: '0 -14px' },
+                    ],
+                    options: { duration: 160, easing: 'ease' },
+                });
+            });
+        };
+        apply(this.shadowRoot);
+        const inner = this.shadowRoot?.querySelector('.tp-inner-calendar');
+        if (inner) {
+            const innerApply = () => apply(inner.shadowRoot);
+            if (inner.updateComplete)
+                inner.updateComplete.then(innerApply);
+            else
+                innerApply();
+        }
     }
     get monthNames() {
         return Array.from({ length: 12 }, (_, i) => new Date(0, i).toLocaleString('default', { month: 'long' }));
     }
     get yearOptions() {
-        const fallbackStart = 2000;
-        const fallbackEnd = 2050;
-        const start = this.startYear ?? fallbackStart;
-        const end = this.endYear ?? fallbackEnd;
+        const start = this.startYear ?? DEFAULT_START_YEAR;
+        const end = this.endYear ?? DEFAULT_END_YEAR;
         if (start > end)
             return [];
         return Array.from({ length: end - start + 1 }, (_, i) => start + i);
@@ -97,6 +515,42 @@ let NileCalendar = class NileCalendar extends NileElement {
         this.currentYear = year;
         this.emit('nile-year-change', { year });
     }
+    /** brings the currently-selected month/year option into view when a dropdown opens */
+    scrollSelectedIntoView(selector) {
+        const selected = this.shadowRoot?.querySelector(selector);
+        if (!selected)
+            return;
+        const container = selected.closest('.month-scroll-wrapper, .year-scroll-wrapper');
+        if (!container) {
+            selected.scrollIntoView({ block: 'center' });
+            return;
+        }
+        const target = container.scrollTop +
+            (selected.getBoundingClientRect().top -
+                container.getBoundingClientRect().top) -
+            (container.clientHeight - selected.clientHeight) / 2;
+        const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+        if (prefersReducedMotion) {
+            container.scrollTop = target;
+            return;
+        }
+        this.smoothScrollTo(container, target, 450);
+    }
+    smoothScrollTo(el, to, duration) {
+        const start = el.scrollTop;
+        const change = to - start;
+        if (change === 0)
+            return;
+        const startTime = performance.now();
+        const ease = (t) => t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
+        const step = (now) => {
+            const t = Math.min(1, (now - startTime) / duration);
+            el.scrollTop = start + change * ease(t);
+            if (t < 1)
+                requestAnimationFrame(step);
+        };
+        requestAnimationFrame(step);
+    }
     checkValidAllowedDate() {
         let newDateRange;
         try {
@@ -119,15 +573,25 @@ let NileCalendar = class NileCalendar extends NileElement {
             this.allowedDatesLocal = newDateRange;
         }
     }
+    /**
+     * The year range month navigation enforces. An explicit `startYear` / `endYear` always wins; the date-time-picker
+     * variant falls back to the dropdown's 2000-2050 for an unset side, while the default calendar leaves it open as published.
+     */
+    get minYear() {
+        return this.variant === 'date-time-picker' ? this.startYear ?? DEFAULT_START_YEAR : this.startYear;
+    }
+    get maxYear() {
+        return this.variant === 'date-time-picker' ? this.endYear ?? DEFAULT_END_YEAR : this.endYear;
+    }
     isPrevDisabled() {
         return (this.currentMonth === 0 &&
-            this.startYear !== undefined &&
-            this.currentYear <= this.startYear);
+            this.minYear !== undefined &&
+            this.currentYear <= this.minYear);
     }
     isNextDisabled() {
         return (this.currentMonth === 11 &&
-            this.endYear !== undefined &&
-            this.currentYear >= this.endYear);
+            this.maxYear !== undefined &&
+            this.currentYear >= this.maxYear);
     }
     formatDate(date) {
         if (!date)
@@ -136,7 +600,8 @@ let NileCalendar = class NileCalendar extends NileElement {
         const mm = String(date.getMonth() + 1).padStart(2, '0');
         const dd = String(date.getDate()).padStart(2, '0');
         let formatted = this.dateFormat;
-        formatted = formatted.replace(/YYYY/g, String(yyyy));
+        // the date-time-picker variant pads years 0-99 to four digits; the default calendar prints the year as published
+        formatted = formatted.replace(/YYYY/g, this.variant === 'date-time-picker' ? formatYear4(yyyy) : String(yyyy));
         formatted = formatted.replace(/MM/g, mm);
         formatted = formatted.replace(/DD/g, dd);
         formatted = formatted.replace(/YY/g, String(yyyy).slice(-2));
@@ -154,10 +619,17 @@ let NileCalendar = class NileCalendar extends NileElement {
         const match = input.match(regex);
         if (!match || !match.groups)
             return null;
-        const year = match.groups.year.length === 2 ? Number(`20${match.groups.year}`) : Number(match.groups.year);
+        const dtp = this.variant === 'date-time-picker';
+        const typedYear = match.groups.year;
+        let year = typedYear.length === 2 ? Number(`20${typedYear}`) : Number(typedYear);
+        // date-time-picker only: an existing bound keeps its century while the visible two digits are unchanged; with no existing bound a typed YY is 2000-2099 (the default calendar reads it as published)
+        if (dtp && typedYear.length === 2 && existingDate && Math.abs(existingDate.getFullYear()) % 100 === Number(typedYear)) {
+            year = existingDate.getFullYear();
+        }
         const month = Number(match.groups.month) - 1;
         const day = Number(match.groups.day);
-        const date = new Date(year, month, day);
+        // new Date(y, ...) remaps years 0-99 to 1900-1999 as published; only the variant keeps the literal year
+        const date = dtp ? localDateFromFields(year, month, day) : new Date(year, month, day);
         if (existingDate) {
             date.setHours(existingDate.getHours(), existingDate.getMinutes(), existingDate.getSeconds());
         }
@@ -188,10 +660,131 @@ let NileCalendar = class NileCalendar extends NileElement {
             this.requestUpdate();
         }
     }
+    unbindStructuredInput() {
+        for (const inp of this.boundMaskInputs) {
+            inp.removeEventListener('keydown', this.onMaskKeydown, true);
+            inp.removeEventListener('focusout', this.onMaskBlur);
+        }
+        this.boundMaskInputs = [];
+    }
+    bindStructuredInput() {
+        this.unbindStructuredInput();
+        if (!this.structuredInput)
+            return;
+        const inputs = this.shadowRoot?.querySelectorAll('.calender-input nile-input');
+        inputs?.forEach(inp => {
+            inp.addEventListener('keydown', this.onMaskKeydown, true);
+            inp.addEventListener('focusout', this.onMaskBlur);
+            this.boundMaskInputs.push(inp);
+        });
+    }
+    dateMaskSegments() {
+        const spec = (token) => {
+            switch (token) {
+                case 'YYYY': return { kind: 'year', len: 4, min: 0, max: 9999 };
+                case 'YY': return { kind: 'year', len: 2, min: 0, max: 99 };
+                case 'MM': return { kind: 'month', len: 2, min: 1, max: 12 };
+                default: return { kind: 'day', len: 2, min: 1, max: 31 }; // DD
+            }
+        };
+        const fmt = this.dateFormat || 'MM/DD/YYYY';
+        const re = /YYYY|YY|MM|DD/g;
+        const found = [];
+        let m;
+        while ((m = re.exec(fmt)) !== null)
+            found.push({ token: m[0], index: m.index });
+        return found.map((f, i) => {
+            const sep = fmt.slice(f.index + f.token.length, i + 1 < found.length ? found[i + 1].index : fmt.length);
+            return { ...spec(f.token), after: i < found.length - 1 ? sep : '' };
+        });
+    }
+    timeMaskSegments() {
+        return [
+            { kind: 'hour', len: 2, min: 0, max: 23, after: ':' },
+            { kind: 'minute', len: 2, min: 0, max: 59, after: ':' },
+            { kind: 'second', len: 2, min: 0, max: 59, after: '' },
+        ];
+    }
+    buildMaskLayout(segs) {
+        const tokens = [];
+        const slots = [];
+        for (const seg of segs) {
+            const segStart = slots.length;
+            for (let k = 0; k < seg.len; k++) {
+                tokens.push({ slot: slots.length });
+                slots.push({ kind: seg.kind, min: seg.min, max: seg.max, len: seg.len, segStart });
+            }
+            for (const ch of seg.after)
+                tokens.push({ lit: ch });
+        }
+        return { tokens, slots, length: tokens.length };
+    }
+    maskLayoutFor(kind) {
+        return this.buildMaskLayout(kind === 'time' ? this.timeMaskSegments() : this.dateMaskSegments());
+    }
+    computeMaskDisplay(values, layout) {
+        let lastFilled = -1;
+        values.forEach((v, i) => { if (v !== '')
+            lastFilled = i; });
+        let s = '';
+        const slotPos = new Array(layout.slots.length).fill(-1);
+        for (const t of layout.tokens) {
+            if ('slot' in t) {
+                if (t.slot > lastFilled)
+                    break; // stop at the trailing empties
+                slotPos[t.slot] = s.length;
+                if (values[t.slot])
+                    s += values[t.slot];
+            }
+            else {
+                s += t.lit;
+            }
+        }
+        return { display: lastFilled === -1 ? '' : s, slotPos, lastFilled };
+    }
+    initMaskValues(text, layout) {
+        const digits = (text || '').replace(/\D/g, '').slice(0, layout.slots.length);
+        return layout.slots.map((_s, i) => digits[i] ?? '');
+    }
+    /** clamp a filled segment into range (year is left unclamped) */
+    clampMaskSegment(values, layout, slotIndex) {
+        const seg = layout.slots[slotIndex];
+        if (seg.kind === 'year')
+            return;
+        const segSlots = [];
+        layout.slots.forEach((s, i) => { if (s.segStart === seg.segStart)
+            segSlots.push(i); });
+        const chars = segSlots.map(i => values[i]);
+        if (chars.some(c => c === ''))
+            return; // segment not full yet
+        const joined = chars.join('');
+        const n = Number(joined);
+        let corrected = null;
+        if (n > seg.max)
+            corrected = String(Number(joined[0])).padStart(seg.len, '0');
+        else if (n < seg.min)
+            corrected = String(seg.min).padStart(seg.len, '0');
+        if (corrected !== null)
+            segSlots.forEach((s, k) => { values[s] = corrected[k]; });
+    }
+    maskValuesFor(native, layout) {
+        let values = this.maskValuesMap.get(native);
+        if (!values || values.length !== layout.slots.length) {
+            values = this.initMaskValues(native.value, layout);
+        }
+        else if (this.computeMaskDisplay(values, layout).display !== native.value) {
+            values = this.initMaskValues(native.value, layout);
+        }
+        this.maskValuesMap.set(native, values);
+        return values;
+    }
     /**
      * Render method
      */
     render() {
+        if (this.variant === 'date-time-picker') {
+            return this.renderDateTimePicker();
+        }
         return html `
       <div
         class=${classMap({
@@ -357,7 +950,37 @@ let NileCalendar = class NileCalendar extends NileElement {
         </div>
       </div>
   
-      ${this.range ? html `
+      ${this.variant === 'date-time-picker' ? html `
+      <div>
+        <div class="unit-input-container">
+          <nile-input
+            class="manual-input duration-input"
+            ?disabled="${this.disabled}"
+            label="Duration"
+            inputmode="numeric"
+            type="text"
+            value="${this.selectedValue}"
+            @nile-input="${this.handleDurationChange}"
+            @nile-change="${this.handleDurationChange}"
+            placeholder="Enter Value"
+          ></nile-input>
+
+          <nile-select
+            class="manual-input time-input"
+            ?disabled="${this.disabled}"
+            label="Unit of time"
+            value="${this.selectedUnit}"
+            @nile-change="${this.handleUnitChange}"
+          >
+            ${this.hideDurationFields?.includes('minutes') ? '' : html `<nile-option value="minutes">Minutes</nile-option>`}
+            ${this.hideDurationFields?.includes('hours') ? '' : html `<nile-option value="hours">Hours</nile-option>`}
+            ${this.hideDurationFields?.includes('days') ? '' : html `<nile-option value="days">Days</nile-option>`}
+            ${this.hideDurationFields?.includes('weeks') ? '' : html `<nile-option value="weeks">Weeks</nile-option>`}
+            ${this.hideDurationFields?.includes('months') ? '' : html `<nile-option value="months">Months</nile-option>`}
+          </nile-select>
+        </div>
+      </div>
+      ` : this.range ? html `
       <div>
         <div class="unit-input-container">
           <nile-input 
@@ -602,13 +1225,19 @@ ${this.showMonthDropdown || this.showYearDropdown ? html `
         if (!this.allowedDatesLocal) {
             return true;
         }
-        const dateToCheck = new Date(Date.UTC(year, month, day));
+        // Date.UTC remaps years 0-99 to 1900-1999 as published; only the date-time-picker variant keeps the literal year
+        const dateToCheck = new Date(this.variant === 'date-time-picker' ? utcFromFields(year, month, day) : Date.UTC(year, month, day));
         const startDate = this.getUTCDate(this.allowedDatesLocal.startDate);
         const endDate = this.getUTCDate(this.allowedDatesLocal.endDate);
         endDate.setUTCHours(23, 59, 59, 999);
         const isWithinRange = dateToCheck >= startDate && dateToCheck <= endDate;
         return isWithinRange;
     }
+    dayCellLabel(day, month, year) {
+        return localDateFromFields(year, month, day, 12).toLocaleDateString('default', {
+            weekday: 'long', day: 'numeric', month: 'long', year: 'numeric',
+        });
+    }
     clearDate(mode) {
         const clearType = mode ??
             (this.range
@@ -616,6 +1245,7 @@ ${this.showMonthDropdown || this.showYearDropdown ? html `
                     ? ClearMode.Relative
                     : ClearMode.Range
                 : ClearMode.Single);
+        this.clearInstantSeed();
         if (clearType === ClearMode.Single) {
             this.value = null;
         }
@@ -638,7 +1268,8 @@ ${this.showMonthDropdown || this.showYearDropdown ? html `
     selectDate(day, month, year) {
         if (this.disabled)
             return;
-        const selectedDate = new Date(year, month, day);
+        // new Date(y, ...) remaps years 0-99 to 1900-1999 as published; only the date-time-picker variant keeps the literal year
+        const selectedDate = this.variant === 'date-time-picker' ? localDateFromFields(year, month, day) : new Date(year, month, day);
         if (this.range) {
             if (this.startDate && this.endDate) {
                 this.startDate = null;
@@ -678,14 +1309,20 @@ ${this.showMonthDropdown || this.showYearDropdown ? html `
      * Function to be called on initialization to set all other properties
      */
     initializeValue() {
+        this.clearInstantSeed();
         if (this.range) {
             try {
                 const rangeValue = JSON.parse(this.valueAttribute || '');
-                this.startDate = new Date(rangeValue.startDate);
-                this.endDate = new Date(rangeValue.endDate);
+                this.startDate = this.rangeBoundFromValue(rangeValue.startDate, false);
+                this.endDate = this.rangeBoundFromValue(rangeValue.endDate, true);
                 // Convert to local time
                 this.startDate = new Date(this.startDate.getTime());
                 this.endDate = new Date(this.endDate.getTime());
+                // date-time-picker variant only: open on the seeded range's start month (the default variant keeps its month)
+                if (this.variant === 'date-time-picker' && this.startDate && !isNaN(this.startDate.getTime())) {
+                    this.currentMonth = this.startDate.getMonth();
+                    this.currentYear = this.startDate.getFullYear();
+                }
                 this.value = null;
             }
             catch (e) {
@@ -693,9 +1330,58 @@ ${this.showMonthDropdown || this.showYearDropdown ? html `
             }
         }
         else {
+            if (this.variant === 'date-time-picker' && this.trySeedFromInstantValue()) {
+                return;
+            }
+            const zoned = this.variant === 'date-time-picker'
+                ? this.parseZonedValue(this.valueAttribute)
+                : null;
+            if (zoned) {
+                this.setTimezoneInternally(zoned.timezone);
+                const w = zoned.wall;
+                this.value = localDateFromFields(w.year, w.month - 1, w.day, 12, 0, 0, 0);
+                this.currentMonth = w.month - 1;
+                this.currentYear = w.year;
+                this.tpHours = w.hours;
+                this.tpMinutes = w.minutes;
+                this.tpSeconds = w.seconds;
+                this.tpMilliseconds = w.ms;
+                return;
+            }
+            if (this.variant === 'date-time-picker') {
+                const wall = wallClockFromOffsetLess(this.valueAttribute);
+                if (wall) {
+                    this.value = localDateFromFields(wall.year, wall.month - 1, wall.day, 12, 0, 0, 0);
+                    this.currentMonth = wall.month - 1;
+                    this.currentYear = wall.year;
+                    this.tpHours = wall.hours;
+                    this.tpMinutes = wall.minutes;
+                    this.tpSeconds = wall.seconds;
+                    this.tpMilliseconds = wall.ms;
+                    return;
+                }
+            }
+            if (this.variant === 'date-time-picker') {
+                const preset = this.parsePresetValue(this.valueAttribute);
+                if (preset) {
+                    this.value = preset;
+                    this.currentMonth = preset.getMonth();
+                    this.currentYear = preset.getFullYear();
+                    // seed the time-picker spinners from the preset value's wall-clock time
+                    this.tpHours = preset.getHours();
+                    this.tpMinutes = preset.getMinutes();
+                    this.tpSeconds = preset.getSeconds();
+                    this.tpMilliseconds = preset.getMilliseconds();
+                }
+                else if (this.valueAttribute) {
+                    // an unparseable value must not leave the previous selection showing (the empty-value path above already clears it)
+                    this.value = null;
+                    this.resetTimeUnits();
+                }
+                return;
+            }
             if (this.valueAttribute) {
-                let date = new Date(this.valueAttribute);
-                date = new Date(date.getTime() - date.getTimezoneOffset() * 60000);
+                const date = this.dateFromValueString(this.valueAttribute);
                 if (!isNaN(date.getTime())) {
                     this.value = date;
                     this.currentMonth = this.value.getMonth();
@@ -704,11 +1390,148 @@ ${this.showMonthDropdown || this.showYearDropdown ? html `
             }
         }
     }
+    /** Forget any retained instant, in every category. */
+    clearInstantSeed() {
+        this.seedInstant = null;
+        this.seedFieldsKey = null;
+        this.seedZone = null;
+    }
+    instantSeedFieldsKey() {
+        const v = this.value;
+        if (!v)
+            return null;
+        return (`${v.getFullYear()}-${v.getMonth()}-${v.getDate()}|` +
+            `${this.tpHours}:${this.tpMinutes}:${this.tpSeconds}.${this.tpMilliseconds}`);
+    }
+    seedFromInstant(epochMs, zone) {
+        const w = wallClockInZone(epochMs, zone);
+        this.value = localDateFromFields(w.year, w.month - 1, w.day, 12, 0, 0, 0);
+        this.currentMonth = w.month - 1;
+        this.currentYear = w.year;
+        this.tpHours = w.hours;
+        this.tpMinutes = w.minutes;
+        this.tpSeconds = w.seconds;
+        this.tpMilliseconds = w.ms;
+        this.seedInstant = epochMs;
+        this.seedFieldsKey = this.instantSeedFieldsKey();
+    }
+    trySeedFromInstantValue() {
+        const epochMs = instantFromValueString(this.valueAttribute);
+        if (epochMs !== null) {
+            if (!isValidTimezone(this.timezone))
+                return false;
+            this.seedFromInstant(epochMs, this.timezone);
+            this.seedZone = null;
+            return true;
+        }
+        const bracketed = instantFromBracketedValue(this.valueAttribute);
+        if (bracketed) {
+            this.setTimezoneInternally(bracketed.timezone);
+            this.seedFromInstant(bracketed.epochMs, bracketed.timezone);
+            this.seedZone = bracketed.timezone;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Seeds `value` from a string with the published conversion: `new Date(raw)` shifted by the host offset. Every variant
+     * keeps it, because the default calendar must behave exactly as the published component; the date-time-picker variant
+     * re-derives its value from its own parsers in `initializeValue`.
+     */
+    dateFromValueString(raw) {
+        const parsed = new Date(raw);
+        return new Date(parsed.getTime() - parsed.getTimezoneOffset() * 60000);
+    }
+    /**
+     * One bound of a `range` value. In the date-time-picker variant `YYYY-MM-DD` is a calendar day, not a UTC instant: it
+     * lands on that local day, at 00:00:00.000 for the start and 23:59:59.999 for the end (what clicking the day produces).
+     * Every other string, and every bound of the default calendar, goes through `new Date(raw)` exactly as published.
+     */
+    rangeBoundFromValue(raw, isEnd) {
+        if (this.variant === 'date-time-picker' && typeof raw === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(raw)) {
+            const day = this.parsePresetValue(raw);
+            if (day) {
+                if (isEnd)
+                    day.setHours(23, 59, 59, 999);
+                return day;
+            }
+        }
+        return new Date(raw);
+    }
+    parsePresetValue(raw) {
+        if (!raw)
+            return null;
+        const dateOnly = /^\d{4}-\d{2}-\d{2}$/.exec(raw);
+        if (dateOnly) {
+            const year = Number(raw.slice(0, 4));
+            const month = Number(raw.slice(5, 7)) - 1;
+            const day = Number(raw.slice(8, 10));
+            if (month < 0 || month > 11 || day < 1)
+                return null;
+            const lastDay = localDateFromFields(year, month + 1, 0).getDate();
+            const date = localDateFromFields(year, month, Math.min(day, lastDay));
+            return isNaN(date.getTime()) ? null : date;
+        }
+        // only an instant with an unusable zone or an undocumented string gets here; the documented formats are parsed before this
+        const date = new Date(raw);
+        return isNaN(date.getTime()) ? null : date;
+    }
+    parseZonedValue(raw) {
+        if (!raw)
+            return null;
+        const m = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{3}))?\[GMT[+-]\d{2}:\d{2}\s+([^\]]+)\]$/.exec(raw.trim());
+        if (!m)
+            return null;
+        const [, y, mo, d, h, mi, s, ms, rawZone] = m;
+        const month0 = Number(mo) - 1;
+        const hours = Number(h);
+        const minutes = Number(mi);
+        const seconds = Number(s);
+        if (month0 < 0 || month0 > 11 || hours > 23 || minutes > 59 || seconds > 59) {
+            return null;
+        }
+        const day = Number(d);
+        if (day < 1)
+            return null;
+        // clamp instead of letting an out-of-range day roll into the next month
+        const lastDay = localDateFromFields(Number(y), month0 + 1, 0).getDate();
+        const wall = {
+            year: Number(y),
+            month: month0 + 1,
+            day: Math.min(day, lastDay),
+            hours,
+            minutes,
+            seconds,
+            ms: Number(ms ?? 0),
+        };
+        const zone = rawZone.trim();
+        const timezone = isValidTimezone(zone) ? zone : 'UTC';
+        return { wall, timezone };
+    }
     /**
      * Function to handle relative date selection
      */
     handleDurationChange(event) {
         event.stopPropagation();
+        if (this.variant === 'date-time-picker') {
+            const input = event.target;
+            const cleaned = String(event.detail?.value ?? input?.value ?? '').replace(/\D/g, '');
+            if (input && input.value !== cleaned)
+                input.value = cleaned;
+            const duration = Number(cleaned);
+            if (!duration) {
+                this.selectedValue = undefined;
+                this.startDate = null;
+                this.endDate = null;
+                this.requestUpdate();
+                return;
+            }
+            this.selectedValue = duration;
+            if (this.selectedUnit && this.selectedValue) {
+                this.handleTimeValueClick(this.selectedUnit, this.selectedValue, event);
+            }
+            return;
+        }
         event.detail.value = event.detail.value.replace(/e/gi, "");
         const duration = Number(event.detail.value);
         if (!duration) {
@@ -735,12 +1558,22 @@ ${this.showMonthDropdown || this.showYearDropdown ? html `
     createRelativePeriod(unit, value) {
         const endTime = new Date();
         const startTime = new Date();
+        // only the date-time-picker variant uses exact elapsed time, month-end clamping and the too-large-duration guard; the
+        // default calendar keeps the published wall-clock arithmetic (and its behaviour for an overflowing duration)
+        const dtp = this.variant === 'date-time-picker';
         switch (unit) {
             case 'minutes':
-                startTime.setMinutes(startTime.getMinutes() - value);
+                // elapsed duration: wall-clock arithmetic (setMinutes) is off by an hour across a host DST change
+                if (dtp)
+                    startTime.setTime(endTime.getTime() - value * 60000);
+                else
+                    startTime.setMinutes(startTime.getMinutes() - value);
                 break;
             case 'hours':
-                startTime.setHours(startTime.getHours() - value);
+                if (dtp)
+                    startTime.setTime(endTime.getTime() - value * 3600000);
+                else
+                    startTime.setHours(startTime.getHours() - value);
                 break;
             case 'days':
                 startTime.setDate(startTime.getDate() - value);
@@ -749,9 +1582,25 @@ ${this.showMonthDropdown || this.showYearDropdown ? html `
                 startTime.setDate(startTime.getDate() - 7 * value); // Subtract weeks as days
                 break;
             case 'months':
-                startTime.setMonth(startTime.getMonth() - value);
+                if (dtp) {
+                    // clamp to the target month's last day: setMonth alone rolls 31 Mar - 1 month into 3 Mar
+                    const day = startTime.getDate();
+                    startTime.setDate(1);
+                    startTime.setMonth(startTime.getMonth() - value);
+                    const lastDay = localDateFromFields(startTime.getFullYear(), startTime.getMonth() + 1, 0).getDate();
+                    startTime.setDate(Math.min(day, lastDay));
+                }
+                else {
+                    startTime.setMonth(startTime.getMonth() - value);
+                }
                 break;
         }
+        // a duration too large for a Date leaves an Invalid Date; storing it would keep Apply enabled and make consumers throw (RangeError) when they format it, so in the variant it is no selection
+        if (dtp && (isNaN(startTime.getTime()) || isNaN(endTime.getTime()))) {
+            this.startDate = null;
+            this.endDate = null;
+            return { startDate: null, endDate: null };
+        }
         this.startDate = new Date(startTime.getTime());
         this.endDate = new Date(endTime.getTime());
         return {
@@ -823,7 +1672,7 @@ ${this.showMonthDropdown || this.showYearDropdown ? html `
             return;
         if (this.currentMonth === 11) {
             const newYear = this.currentYear + 1;
-            if (this.endYear !== undefined && newYear > this.endYear)
+            if (this.maxYear !== undefined && newYear > this.maxYear)
                 return;
             this.currentMonth = 0;
             this.currentYear = newYear;
@@ -837,7 +1686,7 @@ ${this.showMonthDropdown || this.showYearDropdown ? html `
             return;
         if (this.currentMonth === 0) {
             const newYear = this.currentYear - 1;
-            if (this.startYear !== undefined && newYear < this.startYear)
+            if (this.minYear !== undefined && newYear < this.minYear)
                 return;
             this.currentMonth = 11;
             this.currentYear = newYear;
@@ -858,9 +1707,15 @@ ${this.showMonthDropdown || this.showYearDropdown ? html `
         if (this.disabled)
             return;
         this.type = event.detail.value;
+        if (this.variant === 'date-time-picker' && this.type !== 'absolute')
+            this.expanded = false;
         this.emit('nile-type-change', { value: this.type });
     }
     getUTCDate(dateStr) {
+        // Date.UTC remaps years 0-99 to 1900-1999 as published; only the date-time-picker variant keeps the literal year
+        if (this.variant === 'date-time-picker') {
+            return new Date(utcFromFields(Number(dateStr.slice(0, 4)), Number(dateStr.slice(5, 7)) - 1, Number(dateStr.slice(8, 10))));
+        }
         return new Date(Date.UTC(dateStr.slice(0, 4), dateStr.slice(5, 7) - 1, dateStr.slice(8, 10)));
     }
     emitChangedData(data) {
@@ -871,6 +1726,809 @@ ${this.showMonthDropdown || this.showYearDropdown ? html `
         const daysInMonth = new Date(year, month + 1, 0).getDate();
         return Array.from({ length: daysInMonth }, (_, i) => i + 1);
     }
+    renderDateTimePicker() {
+        // the collapsed height is held while the month grid is expanded (the measured value reaches the stylesheet as a custom property)
+        const heightLocked = this.type === 'absolute' && this.expanded && !!this.tpLockedHeight;
+        return html `
+      <div
+        class=${classMap({
+            base: true,
+            'base--date-time-picker': true,
+            'base--tp-expanded': this.expanded,
+            'base--tp-fewfields': this.tpFewFieldsNoTz,
+            'base--tp-height-locked': heightLocked,
+        })}
+        style=${heightLocked ? `--nile-calendar-tp-locked-height:${this.tpLockedHeight}` : nothing}
+        part="calendar-container"
+      >
+        <div class=${classMap({
+            'calendar-config': true,
+            hidden: !this.showTypes,
+        })} part="calendar-config">
+          <div class="calendar-switcher" part="calendar-switcher">
+            <nile-tab-group centered @nile-tab-show="${this.onTypeChange}" value="${this.type}">
+              <nile-tab slot="nav" panel="absolute" tabindex="${this.disabled ? '-1' : '0'}">Absolute</nile-tab>
+              <nile-tab slot="nav" panel="relative" tabindex="${this.disabled ? '-1' : '0'}">Relative</nile-tab>
+            </nile-tab-group>
+          </div>
+        </div>
+
+        ${this.type === 'relative' ? this.renderRelativeCalendar() : this.renderDateTimePickerAbsolute()}
+
+        <div
+          class=${classMap({
+            'tp-footer': true,
+            'tp-footer--relative': this.type === 'relative',
+        })}
+          part="tp-footer"
+        >
+          ${this.type === 'absolute' ? html `
+          <nile-button
+            id="tp-set-to-now"
+            class="tp-set-to-now-button"
+            part="tp-set-to-now-button"
+            variant="secondary"
+            ?disabled="${this.disabled}"
+            @click="${this.handleSetToNow}"
+            @keydown="${(e) => { if (e.key === 'Enter' || e.key === ' ')
+            this.handleSetToNow(); }}"
+          >Set to now <nile-glyph name="ng-clock" size="16" method="stroke" color=${this.disabled ? 'var(--nile-colors-dark-500, var(--ng-colors-fg-disabled))' : nothing}></nile-glyph></nile-button>
+          <nile-lite-tooltip
+            for="tp-set-to-now"
+            content="Sets the time to the current time"
+            size="small"
+          ></nile-lite-tooltip>
+          ` : nothing}
+          <div class="tp-footer-actions" part="tp-footer-actions">
+            <nile-button
+              class="clear-button"
+              part="clear-button"
+              variant="secondary"
+              ?disabled="${this.disabled || !this.hasSelection()}"
+              @click="${this.handleReset}"
+              @keydown="${(e) => { if (e.key === 'Enter' || e.key === ' ')
+            this.handleReset(); }}"
+            >Reset</nile-button>
+            <nile-button
+              class="apply-button"
+              part="apply-button"
+              ?disabled="${this.disabled || !this.hasSelection()}"
+              @click="${this.handleApply}"
+              @keydown="${(e) => { if (e.key === 'Enter' || e.key === ' ')
+            this.handleApply(); }}"
+            >Apply</nile-button>
+          </div>
+        </div>
+      </div>
+    `;
+    }
+    renderDateTimePickerAbsolute() {
+        return html `
+      <div class="calendar-wrapper" part="calendar-wrapper">
+        <div class="calendar-container">
+          ${this.expanded
+            ? this.renderExpandedCalendar()
+            : this.renderCollapsedMonth(this.currentYear, this.currentMonth)}
+        </div>
+      </div>
+
+      <div
+        class=${classMap({
+            'tp-chevron': true,
+            'tp-chevron--expanded': this.expanded,
+        })}
+        part="tp-chevron"
+        role="button"
+        tabindex="${this.disabled ? '-1' : '0'}"
+        aria-expanded="${this.expanded}"
+        aria-label="${this.expanded ? 'Collapse calendar' : 'Expand calendar'}"
+        @click="${this.toggleExpanded}"
+        @keydown="${(e) => { if (e.key === 'Enter' || e.key === ' ')
+            this.toggleExpanded(); }}"
+      >
+        <nile-icon name="arrowdropdown" color=${this.disabled ? 'var(--nile-colors-dark-500, var(--ng-colors-fg-disabled))' : 'var(--nile-colors-dark-900, var(--ng-colors-text-primary-900))'}></nile-icon>
+      </div>
+
+      <div class="tp-scroll-area" part="tp-scroll-area">
+        <div class="tp-scroll-content" part="tp-scroll-content">
+          ${this.renderTimeFields()}
+          ${this.resolvedTimeFields.timezone ? this.renderTimezone() : ''}
+        </div>
+      </div>
+    `;
+    }
+    renderExpandedCalendar() {
+        return this.renderVariantMonth(this.currentYear, this.currentMonth, this.getFullMonthDays(this.currentYear, this.currentMonth));
+    }
+    renderCollapsedMonth(year, month) {
+        return this.renderVariantMonth(year, month, this.getCollapsedWindowDays(year, month));
+    }
+    renderVariantMonth(year, month, cells) {
+        const isSelectedDate = (day, month, year, isCurrentMonth) => {
+            if (!isCurrentMonth)
+                return '';
+            if (this.value) {
+                const isSelected = day === this.value.getDate() &&
+                    month === this.value.getMonth() &&
+                    year === this.value.getFullYear();
+                if (isSelected)
+                    return 'selected-date';
+            }
+            return '';
+        };
+        const isCurrentDate = (day, month, year) => {
+            const today = new Date();
+            return (day === today.getDate() &&
+                month + 1 === today.getMonth() + 1 &&
+                year === today.getFullYear());
+        };
+        const dayNames = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+        // roving tabindex: one reachable day (the keyboard's last day, else the selection, else today, else the first allowed day)
+        const key = (c) => `${c.year}-${c.month}-${c.day}`;
+        const reachable = cells.filter(c => c.inMonth && this.isAllowedDate(c.day, c.month, c.year));
+        const wanted = [
+            this.tpFocusDate && this.tpFocusDate,
+            this.value && { year: this.value.getFullYear(), month: this.value.getMonth(), day: this.value.getDate() },
+            (() => { const t = new Date(); return { year: t.getFullYear(), month: t.getMonth(), day: t.getDate() }; })(),
+        ];
+        let tabStop = null;
+        for (const w of wanted) {
+            if (w && reachable.some(c => key(c) === key(w))) {
+                tabStop = key(w);
+                break;
+            }
+        }
+        if (tabStop === null && reachable.length)
+            tabStop = key(reachable[0]);
+        return html `
+      <div class="calendar" part="calendar">
+        <div class="calendar-header" part="calendar-header">
+          <nile-icon
+            class="calendar-header__month-navigation"
+            part="calendar-header-prev"
+            name="var(--nile-icon-arrow-left, var(--ng-icon-chevron-left))"
+            method="var(--nile-svg-method-fill, var(--ng-svg-method-stroke))"
+            color=${this.disabled ? 'var(--nile-colors-dark-500, var(--ng-colors-fg-disabled))' : 'var(--nile-colors-dark-900, var(--ng-colors-text-primary-900))'}
+            role="button"
+            aria-label="Previous month"
+            aria-disabled="${this.disabled || this.isPrevDisabled()}"
+            tabindex="${this.disabled || this.isPrevDisabled() ? '-1' : '0'}"
+            @keydown="${(e) => { if (e.key === 'Enter' || e.key === ' ')
+            this.prevMonth(); }}"
+            @click="${this.prevMonth}"
+          >
+          </nile-icon>
+          <div class="calendar-header__center" part="calendar-header-center">
+
+${this.showMonthDropdown || this.showYearDropdown ? html `
+  ${this.showMonthDropdown ? html `
+    <nile-dropdown ?disabled="${this.disabled}" class="month-dropdown"
+      @nile-after-show="${() => this.scrollSelectedIntoView('.month-menu-item[selected]')}">
+      <span
+        slot="trigger"
+        class="calendar-header__trigger month-trigger"
+        role="button"
+        part="trigger"
+        tabindex="${this.disabled ? '-1' : '0'}"
+        @keydown="${(e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault();
+                e.currentTarget.click();
+            }
+        }}"
+      >
+        ${new Date(year, month).toLocaleString('default', { month: 'long' })}
+        <nile-icon name="arrowdropdown" color=${this.disabled ? 'var(--nile-colors-dark-500, var(--ng-colors-fg-disabled))' : 'var(--nile-colors-dark-900, var(--ng-colors-text-primary-900))'} class="calendar-header__caret"></nile-icon>
+      </span>
+      <nile-menu>
+        <div class="month-scroll-wrapper">
+          ${this.monthNames.map((m, idx) => html `
+            <nile-menu-item
+              class="month-menu-item"
+              ?selected="${idx === month}"
+              @click="${() => this.onMonthSelected(idx)}"
+            >
+              ${m}
+            </nile-menu-item>
+          `)}
+        </div>
+      </nile-menu>
+    </nile-dropdown>
+  ` : html `
+    <span
+      >${new Date(year, month).toLocaleString('default', { month: 'long' })}</span
+    >
+  `}
+  ${this.showYearDropdown ? html `
+    <nile-dropdown ?disabled="${this.disabled}" class="year-dropdown"
+      @nile-after-show="${() => this.scrollSelectedIntoView('.year-menu-item[selected]')}">
+      <span
+        slot="trigger"
+        class="calendar-header__trigger"
+        role="button"
+        part="trigger"
+        tabindex="${this.disabled ? '-1' : '0'}"
+        @keydown="${(e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault();
+                e.currentTarget.click();
+            }
+        }}"
+      >
+        ${year}
+        <nile-icon name="arrowdropdown" color=${this.disabled ? 'var(--nile-colors-dark-500, var(--ng-colors-fg-disabled))' : 'var(--nile-colors-dark-900, var(--ng-colors-text-primary-900))'} class="calendar-header__caret"></nile-icon>
+      </span>
+      <nile-menu>
+        <div class="year-scroll-wrapper">
+          ${this.yearOptions.map(y => html `
+              <nile-menu-item
+                class="year-menu-item"
+                ?selected="${y === year}"
+                @click="${() => this.onYearSelected(y)}"
+              >
+                ${y}
+              </nile-menu-item>
+            `)}
+        </div>
+      </nile-menu>
+    </nile-dropdown>
+  ` : html `
+    <span>${year}</span>
+  `}
+` : html `
+  <span
+    >${new Date(year, month).toLocaleString('default', {
+            month: 'long',
+        })}
+    ${year}</span
+  >
+`}
+</div>
+
+          <nile-icon
+            class="calendar-header__month-navigation"
+            part="calendar-header-next"
+            name="var(--nile-icon-arrow-right, var(--ng-icon-chevron-right))"
+            method="var(--nile-svg-method-fill, var(--ng-svg-method-stroke))"
+            color=${this.disabled ? 'var(--nile-colors-dark-500, var(--ng-colors-fg-disabled))' : 'var(--nile-colors-dark-900, var(--ng-colors-text-primary-900))'}
+            role="button"
+            aria-label="Next month"
+            aria-disabled="${this.disabled || this.isNextDisabled()}"
+            tabindex="${this.disabled || this.isNextDisabled() ? '-1' : '0'}"
+            @keydown="${(e) => { if (e.key === 'Enter' || e.key === ' ')
+            this.nextMonth(); }}"
+            @click="${this.nextMonth}"
+          >
+          </nile-icon>
+        </div>
+
+        <div class="days_container" part="days-container">
+        ${dayNames.map(day => html `<div class="day_name" part="day-name">${day}</div>`)}
+          ${cells.map(cell => {
+            const isCurrentMonth = cell.inMonth;
+            const datePlacement = isSelectedDate(cell.day, cell.month, cell.year, isCurrentMonth);
+            const classMapObj = {
+                'day_date': true,
+                'not-allowed': !this.isAllowedDate(cell.day, cell.month, cell.year),
+                'filler': !isCurrentMonth,
+            };
+            if (datePlacement)
+                classMapObj[datePlacement] = true;
+            const cellAllowed = this.isAllowedDate(cell.day, cell.month, cell.year);
+            const cellToday = isCurrentDate(cell.day, cell.month, cell.year) && isCurrentMonth;
+            return html `
+            <div
+              part="calendar-day-${cell.day}"
+              class=${classMap(classMapObj)}
+              role=${isCurrentMonth ? 'button' : nothing}
+              aria-hidden=${isCurrentMonth ? nothing : 'true'}
+              aria-label=${isCurrentMonth ? this.dayCellLabel(cell.day, cell.month, cell.year) : nothing}
+              aria-disabled=${isCurrentMonth && (!cellAllowed || this.disabled) ? 'true' : nothing}
+              aria-pressed=${isCurrentMonth ? String(!!datePlacement) : nothing}
+              aria-current=${cellToday ? 'date' : nothing}
+             data-tp-date="${isCurrentMonth ? key(cell) : nothing}"
+             tabindex="${isCurrentMonth && !this.disabled && key(cell) === tabStop ? '0' : '-1'}"
+              @keydown="${(e) => {
+                if (!isCurrentMonth)
+                    return;
+                if (e.key === 'Enter' || e.key === ' ') {
+                    e.preventDefault(); // Space on a role=button div would otherwise scroll the page
+                    this.tpFocusDate = { year: cell.year, month: cell.month, day: cell.day };
+                    this.tpSelectDate(cell.day, cell.month, cell.year);
+                    return;
+                }
+                this.handleDayNavigationKey(e, cell);
+            }}"
+              @click="${() => { if (isCurrentMonth) {
+                this.tpFocusDate = { year: cell.year, month: cell.month, day: cell.day };
+                this.tpSelectDate(cell.day, cell.month, cell.year);
+            } }}"
+            >
+              <span class="day-label" part="calendar-day-label">
+                ${cell.day}
+                ${isCurrentDate(cell.day, cell.month, cell.year) && isCurrentMonth ? html `<div class="current__date__dot" part="current-date-dot"></div>` : nothing}
+              </span>
+            </div>`;
+        })}
+        </div>
+      </div>
+    `;
+    }
+    getCollapsedWindowDays(year, month) {
+        const today = new Date();
+        const isCurrentMonth = today.getFullYear() === year && today.getMonth() === month;
+        const selectionInMonth = this.value instanceof Date &&
+            this.value.getFullYear() === year &&
+            this.value.getMonth() === month;
+        const centerOn = (dayOfMonth) => {
+            const anchor = localDateFromFields(year, month, dayOfMonth);
+            const s = new Date(anchor);
+            s.setDate(anchor.getDate() - anchor.getDay() - 7);
+            return s;
+        };
+        const start = selectionInMonth
+            ? centerOn(this.value.getDate())
+            : isCurrentMonth
+                ? centerOn(today.getDate())
+                : (() => {
+                    const first = localDateFromFields(year, month, 1);
+                    const s = new Date(first);
+                    s.setDate(1 - first.getDay());
+                    return s;
+                })();
+        return Array.from({ length: 21 }, (_, i) => {
+            const d = new Date(start);
+            d.setDate(start.getDate() + i);
+            return {
+                day: d.getDate(),
+                month: d.getMonth(),
+                year: d.getFullYear(),
+                inMonth: d.getMonth() === month && d.getFullYear() === year,
+            };
+        });
+    }
+    getFullMonthDays(year, month) {
+        const first = localDateFromFields(year, month, 1);
+        const leading = first.getDay();
+        const daysInMonth = localDateFromFields(year, month + 1, 0).getDate();
+        const totalCells = Math.ceil((leading + daysInMonth) / 7) * 7;
+        const start = localDateFromFields(year, month, 1 - leading);
+        return Array.from({ length: totalCells }, (_, i) => {
+            const d = new Date(start);
+            d.setDate(start.getDate() + i);
+            return {
+                day: d.getDate(),
+                month: d.getMonth(),
+                year: d.getFullYear(),
+                inMonth: d.getMonth() === month && d.getFullYear() === year,
+            };
+        });
+    }
+    /**
+     * Arrow keys move by a day / week, Home and End to the week's first and last day, PageUp and PageDown by a month
+     * (Shift: a year). The target is clamped to the month's length and to the year range; a day that the collapsed
+     * three-week window does not show expands the calendar to reveal it.
+     */
+    handleDayNavigationKey(e, cell) {
+        if (this.disabled || e.ctrlKey || e.metaKey || e.altKey)
+            return;
+        const from = localDateFromFields(cell.year, cell.month, cell.day);
+        let target = null;
+        switch (e.key) {
+            case 'ArrowLeft':
+                target = localDateFromFields(cell.year, cell.month, cell.day - 1);
+                break;
+            case 'ArrowRight':
+                target = localDateFromFields(cell.year, cell.month, cell.day + 1);
+                break;
+            case 'ArrowUp':
+                target = localDateFromFields(cell.year, cell.month, cell.day - 7);
+                break;
+            case 'ArrowDown':
+                target = localDateFromFields(cell.year, cell.month, cell.day + 7);
+                break;
+            case 'Home':
+                target = localDateFromFields(cell.year, cell.month, cell.day - from.getDay());
+                break;
+            case 'End':
+                target = localDateFromFields(cell.year, cell.month, cell.day + (6 - from.getDay()));
+                break;
+            case 'PageUp':
+            case 'PageDown': {
+                const step = (e.key === 'PageUp' ? -1 : 1) * (e.shiftKey ? 12 : 1);
+                const month = cell.month + step;
+                const last = localDateFromFields(cell.year, month + 1, 0).getDate();
+                target = localDateFromFields(cell.year, month, Math.min(cell.day, last));
+                break;
+            }
+            default: return;
+        }
+        e.preventDefault();
+        this.moveDayFocus(target);
+    }
+    moveDayFocus(target) {
+        const year = target.getFullYear();
+        const month = target.getMonth();
+        const lo = this.minYear;
+        const hi = this.maxYear;
+        if ((lo !== undefined && year < lo) || (hi !== undefined && year > hi))
+            return;
+        this.tpFocusDate = { year, month, day: target.getDate() };
+        this.currentYear = year;
+        this.currentMonth = month;
+        const sel = `[data-tp-date="${year}-${month}-${target.getDate()}"]`;
+        const focusCell = () => this.shadowRoot?.querySelector(sel)?.focus();
+        this.updateComplete.then(() => {
+            if (this.shadowRoot?.querySelector(sel)) {
+                focusCell();
+                return;
+            }
+            // not in the collapsed window: reveal the whole month
+            this.expanded = true;
+            this.updateComplete.then(focusCell).catch(() => { });
+        }).catch(() => { });
+    }
+    tpSelectDate(day, month, year) {
+        if (this.disabled)
+            return;
+        if (!this.isAllowedDate(day, month, year))
+            return;
+        const selectedDate = localDateFromFields(year, month, day);
+        // compare the calendar day only: seeded values are stored at noon, a clicked day at midnight
+        const sameDay = !!this.value &&
+            this.value.getFullYear() === year &&
+            this.value.getMonth() === month &&
+            this.value.getDate() === day;
+        if (sameDay && this.doubleClickUnselect) {
+            this.handleReset();
+            return;
+        }
+        if (!sameDay) {
+            this.resetTimeUnits();
+        }
+        this.value = selectedDate;
+    }
+    resetTimeUnits() {
+        this.tpHours = null;
+        this.tpMinutes = null;
+        this.tpSeconds = null;
+        this.tpMilliseconds = null;
+        this.tpEditingText = '';
+    }
+    renderTimeFields() {
+        const fields = this.resolvedTimeFields;
+        return html `
+      <div class=${classMap({
+            'tp-time-fields': true,
+            'tp-time-fields--stacked': this.tpFewFieldsNoTz,
+        })} part="tp-time-fields">
+        ${fields.hours ? this.renderTimeField('Hours (24H)', 'HH', 23, this.tpHours, v => { this.tpHours = v; }) : ''}
+        ${fields.minutes ? this.renderTimeField('Minutes', 'MM', 59, this.tpMinutes, v => { this.tpMinutes = v; }) : ''}
+        ${fields.seconds ? this.renderTimeField('Seconds', 'SS', 59, this.tpSeconds, v => { this.tpSeconds = v; }) : ''}
+        ${fields.milliseconds ? this.renderTimeField('Milliseconds', 'MS', 999, this.tpMilliseconds, v => { this.tpMilliseconds = v; }) : ''}
+      </div>
+    `;
+    }
+    renderTimeField(label, placeholder, max, value, setter) {
+        const maxDigits = String(max).length;
+        const normalize = (raw) => {
+            let digits = (raw || '').replace(/\D/g, '');
+            while (digits.length > maxDigits && digits[0] === '0')
+                digits = digits.slice(1);
+            if (digits.length > maxDigits)
+                digits = digits.slice(0, maxDigits);
+            if (digits === '')
+                return { text: '', value: null };
+            const num = Number(digits);
+            if (num > max) {
+                const first = Number(digits[0]);
+                return { text: String(first).padStart(maxDigits, '0'), value: first };
+            }
+            return { text: digits, value: num };
+        };
+        const apply = (e) => {
+            e.stopPropagation();
+            const input = e.target;
+            const { text, value: next } = normalize(input.value);
+            setter(next);
+            this.tpEditingText = text;
+            if (input.value !== text)
+                input.value = text;
+        };
+        const step = (delta, focusEl) => {
+            if (this.disabled)
+                return;
+            // A stepper click keeps DOM focus on whichever field was focused before, so move it here — the
+            // shared editing text must be attributed to the right input.
+            if (focusEl) {
+                const input = focusEl.closest('nile-input');
+                // `nile-input.focus()` dereferences its inner <input>, which does not exist until the input has rendered
+                // (a calendar in a closed, not-yet-attached panel never renders it). Nothing to focus then; still step.
+                if (input?.input)
+                    input.focus();
+            }
+            const span = max + 1;
+            const next = value === null
+                ? (delta === 1 ? 0 : max)
+                : ((value + delta) % span + span) % span;
+            setter(next);
+            this.tpFocusedTimeField = label;
+            this.tpEditingText = String(next).padStart(maxDigits, '0');
+        };
+        const focused = this.tpFocusedTimeField === label;
+        const displayValue = focused
+            ? this.tpEditingText
+            : value !== null || this.value
+                ? String(value ?? 0).padStart(maxDigits, '0')
+                : '';
+        return html `
+      <nile-input
+        class="tp-time-field"
+        part="tp-time-field"
+        type="text"
+        inputmode="numeric"
+        label="${label}"
+        placeholder="${placeholder}"
+        ?disabled="${this.disabled}"
+        value="${displayValue}"
+        @nile-change="${apply}"
+        @nile-input="${apply}"
+        @keydown="${(e) => {
+            if (e.key === 'ArrowUp') {
+                e.preventDefault();
+                step(1);
+            }
+            else if (e.key === 'ArrowDown') {
+                e.preventDefault();
+                step(-1);
+            }
+        }}"
+        @nile-focus="${(e) => {
+            e.stopPropagation();
+            this.tpFocusedTimeField = label;
+            this.tpEditingText = '';
+        }}"
+        @nile-blur="${(e) => { e.stopPropagation(); if (this.tpFocusedTimeField === label)
+            this.tpFocusedTimeField = null; }}"
+      >
+        <div
+          slot="suffix"
+          class="tp-stepper"
+          part="tp-stepper"
+          @mousedown="${(e) => e.preventDefault()}"
+        >
+          <div
+            class="tp-stepper-btn tp-stepper-btn--up"
+            part="tp-stepper-btn tp-stepper-btn-up"
+            role="button"
+            tabindex="${this.disabled ? '-1' : '0'}"
+            aria-label="Increase ${label}"
+            @click="${(e) => step(1, e.currentTarget)}"
+            @keydown="${(e) => { if (e.key === 'Enter' || e.key === ' ')
+            step(1, e.currentTarget); }}"
+          >
+            <nile-icon name="arrowdropdown" size="16" color=${this.disabled ? 'var(--nile-colors-dark-500, var(--ng-colors-fg-disabled))' : nothing}></nile-icon>
+          </div>
+          <div
+            class="tp-stepper-btn"
+            part="tp-stepper-btn tp-stepper-btn-down"
+            role="button"
+            tabindex="${this.disabled ? '-1' : '0'}"
+            aria-label="Decrease ${label}"
+            @click="${(e) => step(-1, e.currentTarget)}"
+            @keydown="${(e) => { if (e.key === 'Enter' || e.key === ' ')
+            step(-1, e.currentTarget); }}"
+          >
+            <nile-icon name="arrowdropdown" size="16" color=${this.disabled ? 'var(--nile-colors-dark-500, var(--ng-colors-fg-disabled))' : nothing}></nile-icon>
+          </div>
+        </div>
+      </nile-input>
+    `;
+    }
+    get timezoneOptions() {
+        const zones = typeof Intl.supportedValuesOf === 'function'
+            ? Intl.supportedValuesOf('timeZone')
+            : TIMEZONES;
+        return zones.includes('UTC') ? zones : ['UTC', ...zones];
+    }
+    renderTimezone() {
+        return html `
+      <div class="tp-timezone" part="tp-timezone">
+        <div class="tp-timezone-header" part="tp-timezone-header">
+          <span class="tp-timezone-label" part="tp-timezone-label">Timezone</span>
+          <span
+            class="tp-timezone-local-link"
+            part="tp-timezone-local-link"
+            role="button"
+            tabindex="${this.disabled ? '-1' : '0'}"
+            @click="${this.handleUseLocalTimezone}"
+            @keydown="${(e) => { if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            this.handleUseLocalTimezone();
+        } }}"
+          >Use local timezone</span>
+        </div>
+        <nile-select
+          class="tp-timezone-select"
+          part="tp-timezone-select"
+          hoist
+          placement="top"
+          ?disabled="${this.disabled}"
+          searchEnabled
+          placeholder="Select timezone"
+          .value="${this.timezone}"
+          @nile-change="${this.handleTimezoneChange}"
+        >
+          ${this.timezoneOptions.map(tz => html `<nile-option value="${tz}">${tz}</nile-option>`)}
+        </nile-select>
+      </div>
+    `;
+    }
+    handleTimezoneChange(event) {
+        event.stopPropagation();
+        const selected = (event.detail && (event.detail.value ?? event.detail)) ||
+            event.target?.value;
+        if (typeof selected === 'string' && selected) {
+            this.setTimezoneInternally(selected);
+        }
+    }
+    handleUseLocalTimezone() {
+        if (this.disabled)
+            return;
+        const local = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        if (local) {
+            this.setTimezoneInternally(local);
+        }
+    }
+    toggleExpanded() {
+        if (this.disabled)
+            return;
+        this.expanded = !this.expanded;
+    }
+    composeLocalTimezoneValue() {
+        if (!this.value)
+            return null;
+        if (this.seedInstant !== null &&
+            this.seedFieldsKey === this.instantSeedFieldsKey() &&
+            (this.seedZone === null || this.seedZone === this.timezone)) {
+            return new Date(this.seedInstant);
+        }
+        return this.wallClockToInstant(this.value.getFullYear(), this.value.getMonth(), this.value.getDate(), this.tpHours ?? 0, this.tpMinutes ?? 0, this.tpSeconds ?? 0, this.tpMilliseconds ?? 0);
+    }
+    composeValueISO(epochMs) {
+        const zone = this.timezone || 'UTC';
+        const p = (n, len = 2) => String(n).padStart(len, '0');
+        const ms = ((epochMs % 1000) + 1000) % 1000;
+        let y, mo, d, h, mi, s;
+        let offMs;
+        try {
+            const dtf = new Intl.DateTimeFormat('en-US', {
+                timeZone: zone,
+                hourCycle: 'h23',
+                year: 'numeric', month: '2-digit', day: '2-digit',
+                hour: '2-digit', minute: '2-digit', second: '2-digit',
+            });
+            const map = {};
+            for (const part of dtf.formatToParts(new Date(epochMs))) {
+                if (part.type !== 'literal')
+                    map[part.type] = Number(part.value);
+            }
+            y = map.year;
+            mo = map.month;
+            d = map.day;
+            h = map.hour;
+            mi = map.minute;
+            s = map.second;
+            offMs = this.zoneOffsetMs(epochMs - ms);
+        }
+        catch {
+            const local = new Date(epochMs);
+            y = local.getFullYear();
+            mo = local.getMonth() + 1;
+            d = local.getDate();
+            h = local.getHours();
+            mi = local.getMinutes();
+            s = local.getSeconds();
+            offMs = 0;
+        }
+        // the bracket only carries HH:mm; historical sub-minute offsets (LMT) round
+        offMs = Math.round(offMs / 60000) * 60000;
+        const sign = offMs >= 0 ? '+' : '-';
+        const abs = Math.abs(offMs);
+        const off = `${sign}${p(Math.floor(abs / 3600000))}:${p(Math.floor((abs % 3600000) / 60000))}`;
+        return (`${p(y, 4)}-${p(mo)}-${p(d)}T${p(h)}:${p(mi)}:${p(s)}.${p(ms, 3)}` +
+            `[GMT${off} ${zone}]`);
+    }
+    wallClockToInstant(y, monthIndex, day, h, m, s, ms) {
+        const guess = utcFromFields(y, monthIndex, day, h, m, s, 0);
+        try {
+            const offset1 = this.zoneOffsetMs(guess);
+            let instant = guess - offset1;
+            const offset2 = this.zoneOffsetMs(instant);
+            if (offset2 !== offset1)
+                instant = guess - offset2;
+            return new Date(instant + ms);
+        }
+        catch {
+            const composed = new Date(this.value.getTime());
+            composed.setHours(h, m, s, ms);
+            return composed;
+        }
+    }
+    zoneOffsetMs(utcMs) {
+        const dtf = new Intl.DateTimeFormat('en-US', {
+            timeZone: this.timezone,
+            hourCycle: 'h23',
+            year: 'numeric', month: '2-digit', day: '2-digit',
+            hour: '2-digit', minute: '2-digit', second: '2-digit',
+        });
+        const map = {};
+        for (const p of dtf.formatToParts(new Date(utcMs))) {
+            if (p.type !== 'literal')
+                map[p.type] = Number(p.value);
+        }
+        const asUTC = utcFromFields(map.year, map.month - 1, map.day, map.hour, map.minute, map.second);
+        return asUTC - utcMs;
+    }
+    hasSelection() {
+        if (this.type === 'relative') {
+            return Boolean(this.startDate && this.endDate);
+        }
+        return Boolean(this.value);
+    }
+    handleSetToNow() {
+        if (this.disabled)
+            return;
+        const now = new Date();
+        this.tpHours = now.getHours();
+        this.tpMinutes = now.getMinutes();
+        this.tpSeconds = now.getSeconds();
+        this.tpMilliseconds = now.getMilliseconds();
+        this.value = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+        this.currentMonth = now.getMonth();
+        this.currentYear = now.getFullYear();
+        const local = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        if (local) {
+            this.setTimezoneInternally(local);
+        }
+    }
+    handleApply() {
+        if (this.disabled || !this.hasSelection())
+            return;
+        if (this.type === 'relative') {
+            this.emitDateTimePickerChange({
+                startDate: this.startDate,
+                endDate: this.endDate,
+                timezone: 'UTC',
+            });
+            return;
+        }
+        const localTimezoneValue = this.composeLocalTimezoneValue();
+        const unixEpoch = localTimezoneValue ? localTimezoneValue.getTime() : null;
+        this.emitDateTimePickerChange({
+            value: unixEpoch === null ? null : this.composeValueISO(unixEpoch),
+            localTimezoneValue,
+            unixEpoch,
+            timezone: this.timezone,
+        });
+    }
+    handleReset() {
+        if (this.disabled)
+            return;
+        this.clearInstantSeed();
+        this.value = null;
+        this.startDate = null;
+        this.endDate = null;
+        this.selectedUnit = undefined;
+        this.selectedValue = undefined;
+        this.resetTimeUnits();
+        this.setTimezoneInternally(this.configuredTimezone);
+        this.requestUpdate();
+        this.emit('nile-clear');
+    }
+    emitDateTimePickerChange(data) {
+        this.emit('nile-change', data);
+    }
 };
 __decorate([
     property({ type: String, attribute: 'value' })
@@ -884,6 +2542,9 @@ __decorate([
 __decorate([
     property({ type: Boolean, attribute: true, reflect: true })
 ], NileCalendar.prototype, "hideTypes", void 0);
+__decorate([
+    property({ type: Boolean, attribute: true, reflect: true })
+], NileCalendar.prototype, "showTypes", void 0);
 __decorate([
     property({ type: Boolean, reflect: true })
 ], NileCalendar.prototype, "doubleClickUnselect", void 0);
@@ -920,6 +2581,9 @@ __decorate([
 __decorate([
     property({ type: String, reflect: true, attribute: true })
 ], NileCalendar.prototype, "dateFormat", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], NileCalendar.prototype, "structuredInput", void 0);
 __decorate([
     state()
 ], NileCalendar.prototype, "startDate", void 0);
@@ -947,6 +2611,42 @@ __decorate([
 __decorate([
     property({ type: Boolean, attribute: true, reflect: true })
 ], NileCalendar.prototype, "disabled", void 0);
+__decorate([
+    property({ type: String, attribute: true })
+], NileCalendar.prototype, "variant", void 0);
+__decorate([
+    property({ type: String, attribute: true })
+], NileCalendar.prototype, "timezone", void 0);
+__decorate([
+    property({ type: Array, attribute: 'hide-time-fields' })
+], NileCalendar.prototype, "hideTimeFields", void 0);
+__decorate([
+    state()
+], NileCalendar.prototype, "expanded", void 0);
+__decorate([
+    state()
+], NileCalendar.prototype, "tpLockedHeight", void 0);
+__decorate([
+    state()
+], NileCalendar.prototype, "tpHours", void 0);
+__decorate([
+    state()
+], NileCalendar.prototype, "tpMinutes", void 0);
+__decorate([
+    state()
+], NileCalendar.prototype, "tpSeconds", void 0);
+__decorate([
+    state()
+], NileCalendar.prototype, "tpMilliseconds", void 0);
+__decorate([
+    state()
+], NileCalendar.prototype, "tpFocusedTimeField", void 0);
+__decorate([
+    state()
+], NileCalendar.prototype, "tpFocusDate", void 0);
+__decorate([
+    state()
+], NileCalendar.prototype, "tpEditingText", void 0);
 __decorate([
     watch('allowedDates')
 ], NileCalendar.prototype, "checkValidAllowedDate", null);