@aquera/nile-elements 2.0.18 → 2.0.20

package/src/nile-date-time-picker/nile-date-time-picker.ts

@@ -0,0 +1,1153 @@
+/**
+ * Copyright Aquera Inc 2026
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { html, CSSResultArray, TemplateResult, PropertyValues } from 'lit';
+import { customElement, property, query } from 'lit/decorators.js';
+import { ifDefined } from 'lit/directives/if-defined.js';
+import { createRef, ref } from 'lit/directives/ref.js';
+import { styles } from './nile-date-time-picker.css';
+import NileElement from '../internal/nile-element';
+import type { NileFloatingPanel } from '../nile-floating-panel';
+import '../nile-floating-panel';
+import '../nile-calendar';
+import '../nile-input';
+import { isValidTimezone, utcFromFields, localDateFromFields, DEFAULT_START_YEAR, DEFAULT_END_YEAR } from '../nile-calendar/timezones';
+import { instantFromValueString, wallClockFromOffsetLess, wallClockInZone } from '../nile-calendar/nile-calendar';
+import type { CalendarWallClock as WallClock } from '../nile-calendar/nile-calendar';
+
+type TimeUnits = 'minutes' | 'hours' | 'days' | 'weeks' | 'months';
+
+/** Accessible name for the trigger input when a consumer sets neither `label` nor `aria-label`. */
+const DEFAULT_TRIGGER_LABEL = 'Date and time';
+
+/**
+ * @tag nile-date-time-picker
+ * @event nile-change - Absolute `{ value, localTimezoneValue, unixEpoch, timezone }` (`unixEpoch` = ms since 1970, null when empty); relative `{ startDate, endDate, timezone }`.
+ * @event nile-clear
+ */
+@customElement('nile-date-time-picker')
+export class NileDateTimePicker extends NileElement {
+  public static get styles(): CSSResultArray {
+    return [styles];
+  }
+
+  @property({ type: Boolean, attribute: true, reflect: true }) showMonthDropdown = false;
+  @property({ type: Boolean, attribute: true, reflect: true }) showYearDropdown = false;
+  @property({ type: String, reflect: true }) type: 'absolute' | 'relative' = 'absolute';
+  /** Show the Absolute / Relative type switcher. Hidden by default; set to reveal it. */
+  @property({ type: Boolean, attribute: true, reflect: true }) showTypes = false;
+  @property({ type: Array, attribute: true }) hideDurationFields: string[] = [];
+  @property({ type: Array, attribute: 'hide-time-fields' }) hideTimeFields: string[] = [];
+  /** Selected date/time for the inner `nile-calendar`: an instant, an offset-less wall clock read in `timezone`, the bracketed form, or date-only — all different. `unixEpoch` is the authoritative instant. */
+  @property({ type: String }) value: string | null = null;
+  @property({ type: String, reflect: true }) timezone = 'UTC';
+  @property({ type: String }) selectedUnit?: TimeUnits;
+  @property({ type: Number }) selectedValue?: number;
+  @property({ type: Number, attribute: true, reflect: true }) startYear?: number;
+  @property({ type: Number, attribute: true, reflect: true }) endYear?: number;
+  @property({ type: String, attribute: true, reflect: true }) allowedDates = JSON.stringify({});
+  @property({ type: String, reflect: true }) dateFormat = 'DD/MM/YY';
+  @property({ type: String }) placeholder = '';
+  @property({ type: String }) label = '';
+  @property({ type: String, attribute: 'aria-label' }) accessibleLabel = '';
+  private get structuredInput(): boolean { return true; }
+  @property({ type: Boolean, reflect: true }) doubleClickUnselect = false;
+  @property({ type: Boolean, attribute: true, reflect: true }) disabled = false;
+  @property({ type: Boolean, reflect: true }) open = false;
+  @query('nile-floating-panel') panel: NileFloatingPanel;
+  private calendarRef = createRef<any>();
+  private _openSyncFromPanel = false;
+  private _skipNextSeed = false;
+  /** true once the user has typed/pasted/deleted in the mask since the last seed, so only user edits are clamped to allowedDates */
+  private _maskEdited = false;
+  /** the zone the consumer configured (first render, or any later external change), restored on Clear instead of forcing UTC */
+  private _defaultTimezone = 'UTC';
+  /** the last zone this component assigned itself, so `updated` can tell it apart from a consumer change */
+  private _internalTimezone: string | null = null;
+
+  private setTimezoneInternally(tz: string): void {
+    this._internalTimezone = tz;
+    this.timezone = tz;
+  }
+  private static readonly TIME_SPEC: ReadonlyArray<{ key: string; kind: string; len: number; max: number; ph: string }> = [
+    { key: 'hours', kind: 'HH', len: 2, max: 23, ph: 'hh' },
+    { key: 'minutes', kind: 'mm', len: 2, max: 59, ph: 'mm' },
+    { key: 'seconds', kind: 'ss', len: 2, max: 59, ph: 'ss' },
+    { key: 'milliseconds', kind: 'SSS', len: 3, max: 999, ph: 'SSS' },
+  ];
+
+  private get resolvedTimeFields(): Record<string, boolean> {
+    const hidden = Array.isArray(this.hideTimeFields) ? this.hideTimeFields : [];
+    const keys = ['hours', 'minutes', 'seconds', 'milliseconds', 'timezone'];
+    const out: Record<string, boolean> = {};
+    for (const k of keys) out[k] = !hidden.includes(k);
+    return out;
+  }
+
+  private get shownTimeFields() {
+    const f = this.resolvedTimeFields;
+    return NileDateTimePicker.TIME_SPEC.filter(t => f[t.key] !== false);
+  }
+
+  private timeSep(kind: string): string {
+    return kind === 'SSS' ? '.' : ':';
+  }
+
+  private get showTimezone(): boolean {
+    return this.resolvedTimeFields.timezone !== false;
+  }
+
+  private get defaultPlaceholder(): string {
+    const time = this.shownTimeFields;
+    let s = this.dateFormat || 'DD/MM/YY';
+    if (time.length) {
+      const timeStr = time
+        .map((t, i) => (i > 0 ? this.timeSep(t.kind) : '') + t.ph)
+        .join('');
+      s += ` - ${timeStr}`;
+    }
+    if (this.showTimezone) s += ' - timezone';
+    return s;
+  }
+  private get triggerInput(): any {
+    return (this.shadowRoot?.querySelector('nile-input') as any) ?? null;
+  }
+
+  public get calendarElement(): any {
+    return this.calendarRef.value ?? null;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    // firstUpdated runs once; a re-attach (DOM move) must restore the mask listeners disconnectedCallback removed
+    if (this.hasUpdated) this.bindStructuredInput();
+    this.emit('nile-init');
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    document.removeEventListener('keydown', this.onEscapeKeydown, true);
+    const nileInput = this.triggerInput;
+    nileInput?.removeEventListener('keydown', this.onMaskKeydown as EventListener, true);
+    nileInput?.removeEventListener('focusout', this.onMaskBlur as EventListener);
+    nileInput?.removeEventListener('paste', this.onMaskPaste as EventListener, true);
+    nileInput?.removeEventListener('beforeinput', this.onMaskBeforeInput as EventListener, true);
+    nileInput?.removeEventListener('keydown', this.onTriggerKeydown as EventListener);
+    this.emit('nile-destroy');
+  }
+
+  private syncOpenFromPanel(open: boolean) {
+    if (this.open === open) return;
+    this._openSyncFromPanel = true;
+    this.open = open;
+    this.updateComplete
+      .then(() => { this._openSyncFromPanel = false; })
+      .catch(() => { this._openSyncFromPanel = false; });
+  }
+
+  /** keep `open` in sync with the panel's own show/hide (click, outside-click, Escape) */
+  /** `performance.now()` of an Escape pressed while focus was inside the panel; 0 when there is none to honour */
+  private _escapeFromPanelAt = 0;
+
+  /**
+   * The panel hides on a document-level Escape and drops focus to <body> when the focused control disappears with it.
+   * Runs in the capture phase, before the panel's own handler, to note whether focus was inside the panel; onPanelHide
+   * then hands focus back to the trigger. Escape with focus anywhere else leaves focus where it is.
+   */
+  private onEscapeKeydown = (e: KeyboardEvent) => {
+    if (e.key === 'Tab') { this.onPanelTab(e); return; }
+    if (e.key !== 'Escape' || !this.open) return;
+    this._escapeFromPanelAt = this.focusIsInPanel() ? performance.now() : 0;
+  };
+
+  /** the element that really holds focus, however deep in shadow roots */
+  private deepActiveElement(): Element | null {
+    let active: Element | null = document.activeElement;
+    while (active?.shadowRoot?.activeElement) active = active.shadowRoot.activeElement;
+    return active;
+  }
+
+  /** tab stops inside the panel in DOM order, looking through shadow roots (the panel is portaled to <body>) */
+  private panelTabbables(): HTMLElement[] {
+    const cal = this.calendarRef.value as HTMLElement | undefined;
+    if (!cal) return [];
+    const out: HTMLElement[] = [];
+    const walk = (node: ParentNode) => {
+      for (const child of Array.from(node.children) as HTMLElement[]) {
+        if (child.hidden || child.hasAttribute('inert')) continue;
+        if (child.tabIndex >= 0 && !child.matches(':disabled') && child.getClientRects().length > 0
+          && getComputedStyle(child).visibility !== 'hidden') out.push(child);
+        if (child.shadowRoot) walk(child.shadowRoot);
+        walk(child);
+      }
+    };
+    if (cal.shadowRoot) walk(cal.shadowRoot);
+    return out;
+  }
+
+  /** the panel's way in: the day that owns the grid's tab stop, else the first control */
+  private focusIntoPanel() {
+    const tabbables = this.panelTabbables();
+    (tabbables.find(el => el.classList.contains('day_date')) ?? tabbables[0])?.focus();
+  }
+
+  /**
+   * The panel is portaled to the end of <body>, so the browser's own Tab order skips it (Chrome, Edge, Firefox) or
+   * lands in it from the wrong side. While it is open Tab from the field enters it at its first control, Shift+Tab from its first control
+   * returns to the field, and Tab from its last control hands focus back to the field so the browser's default move
+   * continues to the next page element (the panel then closes: it has been left). No trap: Shift+Tab from the field and
+   * every Tab outside the panel behave as usual.
+   */
+  private onPanelTab(e: KeyboardEvent) {
+    if (!this.open || e.ctrlKey || e.metaKey || e.altKey) return;
+    const native = this.triggerInput?.input as HTMLElement | undefined;
+    const active = this.deepActiveElement();
+    if (!native || !active) return;
+    if (active === native) {
+      if (e.shiftKey) return;
+      const tabbables = this.panelTabbables();
+      if (!tabbables.length) return;
+      e.preventDefault();
+      tabbables[0].focus();
+      return;
+    }
+    const tabbables = this.panelTabbables();
+    const at = tabbables.indexOf(active as HTMLElement);
+    if (at === -1) return;
+    if (e.shiftKey && at === 0) {
+      e.preventDefault();
+      native.focus();
+    } else if (!e.shiftKey && at === tabbables.length - 1) {
+      native.focus(); // no preventDefault: the default Tab now moves on from the field
+      this.panel?.hide?.();
+    }
+  }
+
+  /** ArrowDown / Alt+ArrowDown on the field opens the panel and moves focus into it. Enter, Space and typing are untouched. */
+  private onTriggerKeydown = (e: KeyboardEvent) => {
+    if (e.key !== 'ArrowDown' || e.defaultPrevented || e.ctrlKey || e.metaKey || e.shiftKey) return;
+    if (this.disabled || this.open) return;
+    e.preventDefault();
+    this.panel?.show?.()?.then(() => this.focusIntoPanel()).catch(() => { /* panel went away */ });
+  };
+
+  private focusIsInPanel(): boolean {
+    const cal = this.calendarRef.value as HTMLElement | undefined;
+    const active = document.activeElement;
+    if (!cal || !active) return false;
+    const popper = cal.closest('.nile-dtp-panel');
+    return active === cal || cal.contains(active) || (!!popper && (popper === active || popper.contains(active)));
+  }
+
+  /**
+   * nile-floating-panel creates the `role="dialog"` container itself, portals it out of this shadow root and gives it no
+   * name. Name it here after the field it belongs to, so the shared panel (and nile-context-menu) stays untouched.
+   */
+  private applyDialogName() {
+    const dialog = (this.calendarRef.value as HTMLElement | undefined)?.closest('[role="dialog"]');
+    if (!dialog) return;
+    const field = this.label.trim() || this.accessibleLabel.trim() || DEFAULT_TRIGGER_LABEL;
+    dialog.setAttribute('aria-label', `${field} picker`);
+  }
+
+  private onPanelShow = (e: Event) => {
+    e.stopPropagation();
+    this.applyDialogName();
+    document.addEventListener('keydown', this.onEscapeKeydown, true);
+    this.syncOpenFromPanel(true);
+    if (this._showCommittedOnOpen) this.showSelectedMonth();
+    this._showCommittedOnOpen = false;
+  };
+
+  /** set by Apply: the next open lands on the committed date, not on whatever year/month was browsed before it */
+  private _showCommittedOnOpen = false;
+
+  /**
+   * The month/year dropdowns only navigate, so after Apply the view can be left on a browsed month. Reopening then shows the
+   * committed date's month/year. Dismissing without Apply (Escape, outside click) never takes this path: the view and any
+   * pending selection stay as the user left them. With no selection the view is left alone.
+   */
+  private showSelectedMonth() {
+    const cal = this.calendarRef.value as any;
+    const selected: Date | null | undefined = this.type === 'absolute' ? cal?.value : null;
+    if (!(selected instanceof Date) || isNaN(selected.getTime())) return;
+    if (cal.currentYear === selected.getFullYear() && cal.currentMonth === selected.getMonth()) return;
+    cal.currentYear = selected.getFullYear();
+    cal.currentMonth = selected.getMonth();
+    cal.updateComplete
+      ?.then(() => cal.syncInnerCalendar?.())
+      .catch(() => { /* calendar failed to update; sync is best-effort */ });
+  }
+
+  private onPanelHide = (e: Event) => {
+    e.stopPropagation();
+    document.removeEventListener('keydown', this.onEscapeKeydown, true);
+    this.syncOpenFromPanel(false);
+    const fromPanel = this._escapeFromPanelAt && performance.now() - this._escapeFromPanelAt < 1000;
+    this._escapeFromPanelAt = 0;
+    if (fromPanel) this.triggerInput?.focus?.();
+  };
+
+  willUpdate(changedProperties: PropertyValues) {
+    super.willUpdate?.(changedProperties);
+    if (!this.hasUpdated) this._defaultTimezone = this.timezone;
+  }
+
+  firstUpdated(changedProperties: PropertyValues) {
+    super.firstUpdated?.(changedProperties);
+    this.bindStructuredInput();
+    this.seedTriggerFromValue();
+    this.applyTriggerAriaLabel();
+  }
+
+  updated(changedProperties: Map<string, unknown>) {
+    super.updated(changedProperties);
+    if (changedProperties.has('timezone')) {
+      if (this.timezone !== this._internalTimezone) this._defaultTimezone = this.timezone;
+      this._internalTimezone = null;
+    }
+    // a live change to the display layout (not the first render) leaves the trigger text in the old layout; drop any draft and redraw from the committed value
+    const layoutChanged = ['dateFormat', 'hideTimeFields']
+      .some(p => changedProperties.has(p) && changedProperties.get(p) !== undefined);
+    // switching back to Absolute must not leave Relative text in the trigger; same redraw, from the retained committed absolute `value` (or empty)
+    const typeChanged = changedProperties.has('type') && changedProperties.get('type') !== undefined;
+    if ((layoutChanged || typeChanged) && this.type === 'absolute') {
+      this._skipNextSeed = false;
+      this._maskEdited = false;
+      if (this.value) this.seedTriggerFromValue();
+      else this.clearTriggerText(true);
+    } else if (changedProperties.has('value') && !this.value && changedProperties.get('value')) {
+      // seedTriggerFromValue ignores an empty value, so a programmatic reset must clear the text itself
+      this.clearTriggerText();
+    } else if (changedProperties.has('value') || changedProperties.has('timezone')) {
+      this.seedTriggerFromValue();
+    }
+    if (changedProperties.has('open') && !this._openSyncFromPanel) {
+      if (this.open) this.panel?.show?.();
+      else this.panel?.hide?.();
+    }
+    if (changedProperties.has('accessibleLabel') || changedProperties.has('label')) {
+      this.applyTriggerAriaLabel();
+      this.applyDialogName();
+    }
+  }
+
+  private applyTriggerAriaLabel() {
+    const nileInput = this.triggerInput;
+    if (!nileInput) {
+      this.updateComplete
+        .then(() => { if (this.triggerInput) this.applyTriggerAriaLabel(); })
+        .catch(() => {});
+      return;
+    }
+    // A visible `label` names the field on its own, so `aria-label` stays off; with neither set, fall back to a built-in name (the placeholder describes the FORMAT, not the purpose).
+    const name = this.label
+      ? ''
+      : this.accessibleLabel.trim() || DEFAULT_TRIGGER_LABEL;
+    const apply = () => {
+      const native = nileInput.input as HTMLInputElement | undefined;
+      if (!native) return;
+      if (name) native.setAttribute('aria-label', name);
+      else native.removeAttribute('aria-label');
+    };
+    apply();
+    nileInput.updateComplete
+      ?.then(apply)
+      .catch(() => {  });
+  }
+
+  private seedTriggerFromValue() {
+    // a manual mask edit owns the trigger text; re-seeding would overwrite it
+    if (this._skipNextSeed) return;
+    const triggerInput = this.triggerInput;
+    if (!triggerInput || this.type !== 'absolute') return;
+    const raw = this.value;
+    if (!raw) return;
+    const zoned = this.parseZonedValue(raw);
+    if (zoned && zoned.timezone !== this.timezone) {
+      this.setTimezoneInternally(zoned.timezone);
+      return;
+    }
+    const wall = this.wallClockFromRaw(raw, zoned?.wall);
+    if (!wall) {
+      // unparseable: show nothing, as for an invalid initial value, instead of the previous selection
+      this.clearTriggerText();
+      return;
+    }
+    const text = this.formatValue({ wall, timezone: this.timezone });
+    if (!text) return;
+    this.initMaskState(text); // keep the editable slot values in sync
+    this.seedMask = [...this.maskValues];
+    this.seedYear = wall.year;
+    this._maskEdited = false;
+    triggerInput.value = text;
+  }
+
+  /** `silent` is for display-only refreshes (a dateFormat/hideTimeFields change): no `nile-input`, since the user did not type or clear */
+  private clearTriggerText(silent = false) {
+    const triggerInput = this.triggerInput;
+    this.maskValues = [];
+    this.maskSuffix = '';
+    this.seedMask = null;
+    this.seedYear = null;
+    this._yearRejected = false;
+    if (!triggerInput || !triggerInput.value) return;
+    triggerInput.value = '';
+    if (!silent) triggerInput.emit('nile-input', { value: '' });
+  }
+
+  private wallClockFromRaw(raw: string, zoned?: WallClock): WallClock | null {
+    if (zoned) return zoned;
+    const epochMs = instantFromValueString(raw);
+    if (epochMs !== null) {
+      // an instant reads in this component's zone, never the browser's; an unusable zone falls back to the browser's, as in the calendar
+      return isValidTimezone(this.timezone)
+        ? wallClockInZone(epochMs, this.timezone)
+        : this.wallClockFromDate(new Date(epochMs));
+    }
+    const trimmed = raw.trim();
+    // date-only is a calendar day: midnight of that day; anything outside the documented formats is null
+    return wallClockFromOffsetLess(/^\d{4}-\d{2}-\d{2}$/.test(trimmed) ? `${trimmed}T00:00` : trimmed);
+  }
+
+  private bindStructuredInput() {
+    const nileInput = this.triggerInput;
+    if (!nileInput) return;
+    nileInput.removeEventListener('keydown', this.onMaskKeydown as EventListener, true);
+    nileInput.removeEventListener('focusout', this.onMaskBlur as EventListener);
+    nileInput.removeEventListener('paste', this.onMaskPaste as EventListener, true);
+    nileInput.removeEventListener('beforeinput', this.onMaskBeforeInput as EventListener, true);
+    nileInput.removeEventListener('keydown', this.onTriggerKeydown as EventListener);
+    nileInput.addEventListener('keydown', this.onTriggerKeydown as EventListener);
+    if (this.structuredInput) {
+      nileInput.addEventListener('keydown', this.onMaskKeydown as EventListener, true);
+      nileInput.addEventListener('focusout', this.onMaskBlur as EventListener);
+      nileInput.addEventListener('paste', this.onMaskPaste as EventListener, true);
+      nileInput.addEventListener('beforeinput', this.onMaskBeforeInput as EventListener, true);
+    }
+  }
+
+  private maskValues: string[] = [];
+  private maskSuffix = '';
+  /** the slot values as last seeded/committed from `value`; blur clamps only segments that differ from it (the user's edits) */
+  private seedMask: string[] | null = null;
+  /** the seeded value's full year, set wherever `seedMask` is: a `YY` mask holds only its last two digits */
+  private seedYear: number | null = null;
+  /** set when a YY year with no valid two-digit form was blanked; until a year is typed (or the mask is reseeded) the calendar keeps no selection built from day and month alone */
+  private _yearRejected = false;
+
+  /**
+   * The full year for a completed year segment. A `YY` year whose two digits equal the seeded value's keeps its century
+   * (editing the day of 1999-06-15, or retyping or restoring `99`, stays 1999); any other two digits read as 2000-2099.
+   */
+  private fullYearOf(yearText: string): number {
+    const n = Number(yearText);
+    if (yearText.length !== 2) return n;
+    if (this.seedYear !== null && Math.abs(this.seedYear) % 100 === n) return this.seedYear;
+    return 2000 + n;
+  }
+
+  private maskLayout() {
+    const segs = this.maskSegments();
+    const tokens: Array<{ slot: number } | { lit: string }> = [];
+    const slots: Array<{ kind: string; max: number; len: number; segStart: number }> = [];
+    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, max: seg.max, len: seg.len, segStart });
+      }
+      for (const ch of seg.after) tokens.push({ lit: ch });
+    }
+    return { tokens, slots, length: tokens.length };
+  }
+
+  private computeDisplay(values: string[], suffix: string, layout: ReturnType<typeof this.maskLayout>) {
+    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 + suffix, slotPos, lastFilled };
+  }
+
+  private initMaskState(text: string) {
+    const layout = this.maskLayout();
+    const portion = (text || '').slice(0, layout.length);
+    this.maskSuffix = (text || '').slice(layout.length);
+    const digits = portion.replace(/\D/g, '');
+    this.maskValues = layout.slots.map((_s, i) => digits[i] ?? '');
+    this.seedMask = null; // text of unknown origin; callers that seed from `value` re-mark it
+    this.seedYear = null;
+    this._yearRejected = false;
+  }
+
+  private clampSegment(values: string[], layout: ReturnType<typeof this.maskLayout>, slotIndex: number) {
+    const seg = layout.slots[slotIndex];
+    const segSlots: number[] = [];
+    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: string | null = null;
+    if (seg.kind === 'year') {
+      const fullYear = seg.len === 2 ? this.fullYearOf(joined) : n;
+      // an unset side falls back to 2000 / 2050, the same range the calendar's arrows and year dropdown use
+      const clamped = Math.min(this.endYear ?? DEFAULT_END_YEAR, Math.max(this.startYear ?? DEFAULT_START_YEAR, fullYear));
+      if (clamped !== fullYear) {
+        const back = seg.len === 2 ? clamped - 2000 : clamped;
+        if (seg.len === 2 && (back < 0 || back > 99)) {
+          // the range lies outside what a YY mask can write (2000-2099), so no typed YY year can be in it: put back the
+          // seeded digits, or blank the year when there are none, rather than commit a year the range rules out
+          const seed = this.seedMask?.length === values.length ? this.seedMask : null;
+          segSlots.forEach(s => { values[s] = seed ? seed[s] : ''; });
+          if (!seed) this._yearRejected = true;
+          return;
+        }
+        corrected = String(back).padStart(seg.len, '0').slice(-seg.len);
+      }
+    } else {
+      const min = seg.kind === 'month' || seg.kind === 'day' ? 1 : 0;
+      if (n > seg.max) corrected = String(Number(joined[0])).padStart(seg.len, '0');
+      else if (n < min) corrected = String(min).padStart(seg.len, '0');
+    }
+    if (corrected !== null) segSlots.forEach((s, k) => { values[s] = corrected![k]; });
+  }
+
+  /** An abandoned year edit (digits typed over the old year, then the caret moved on) is normalised before another segment's edit builds on it. An untouched year, however far out of range, is left alone. */
+  private settleYear(values: string[], layout: ReturnType<typeof this.maskLayout>) {
+    const yearSlot = layout.slots.findIndex(s => s.kind === 'year');
+    if (yearSlot === -1) return;
+    const seed = this.seedMask?.length === values.length ? this.seedMask : null;
+    const changed = !!seed && layout.slots.some((s, i) => s.kind === 'year' && values[i] !== seed[i]);
+    if (changed) this.clampSegment(values, layout, yearSlot);
+  }
+
+  private clampDay(values: string[], layout: ReturnType<typeof this.maskLayout>) {
+    const collect = (kind: string) => layout.slots
+      .map((s, i) => (s.kind === kind ? i : -1)).filter(i => i !== -1);
+    const daySlots = collect('day');
+    if (!daySlots.length || daySlots.some(i => values[i] === '')) return;
+    const monthSlots = collect('month');
+    const yearSlots = collect('year');
+    const monthStr = monthSlots.map(i => values[i]).join('');
+    const yearStr = yearSlots.map(i => values[i]).join('');
+    if (monthStr.length !== monthSlots.length) return; // month not known yet
+    const month = Number(monthStr) > 12 ? String(Number(monthStr[0])).padStart(2, '0') : monthStr;
+    const fullYear = yearSlots.length && yearStr.length === yearSlots.length
+      ? (yearSlots.length === 2 ? String(this.fullYearOf(yearStr)) : yearStr)
+      : '';
+    const dayMax = this.maxDayForMonth(month, fullYear);
+    const dayStr = daySlots.map(i => values[i]).join('');
+    if (Number(dayStr) > dayMax) {
+      const corrected = String(dayMax).padStart(daySlots.length, '0');
+      daySlots.forEach((s, k) => { values[s] = corrected[k]; });
+    }
+  }
+
+  private writeMask(nileInput: any, native: HTMLInputElement, display: string, caret: number) {
+    native.value = display;
+    nileInput.value = display;
+    try { native.setSelectionRange(caret, caret); } catch { /* noop */ }
+    nileInput.updateComplete
+      ?.then(() => { try { native.setSelectionRange(caret, caret); } catch { /* noop */ } })
+      .catch(() => { /* input failed to update; caret restore is best-effort */ });
+  }
+
+  private onMaskBlur = () => {
+    if (this.type !== 'absolute') return;
+    const nileInput = this.triggerInput;
+    const native = nileInput?.input as HTMLInputElement | undefined;
+    if (!native) return;
+    const layout = this.maskLayout();
+    if (this.maskValues.length !== layout.slots.length) this.initMaskState(native.value);
+    if (!this.maskValues.some(v => v !== '')) {
+      native.value = '';
+      nileInput.value = '';
+      return;
+    }
+    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 => this.maskValues[i]).filter(c => c !== '');
+      if (digits.length > 0 && digits.length < idxs.length) {
+        const padded = digits.join('').padStart(idxs.length, '0');
+        idxs.forEach((i, k) => { this.maskValues[i] = padded[k]; });
+      }
+    }
+    // a seeded value is not a user edit: clamping it to startYear/endYear, or re-reading a YY year as 20xx into the calendar, would diverge from `value`
+    const edited = this._maskEdited;
+    if (edited) {
+      // only segments the user changed since the seed: an untouched out-of-range year must survive an edit to another segment
+      const seed = this.seedMask?.length === this.maskValues.length ? this.seedMask : null;
+      segStarts.forEach(start => {
+        const touched = !seed
+          || layout.slots.some((sl, i) => sl.segStart === start && this.maskValues[i] !== seed[i]);
+        if (touched) this.clampSegment(this.maskValues, layout, start);
+      });
+      this.clampDay(this.maskValues, layout);
+    }
+    const { display } = this.computeDisplay(this.maskValues, this.maskSuffix, layout);
+    native.value = display;
+    nileInput.value = display;
+    if (edited) this.syncCalendarFromMask();
+    this.seedMask = [...this.maskValues];
+    this._maskEdited = false;
+  };
+
+  private completedSegment(layout: ReturnType<typeof this.maskLayout>, kind: string): string | null {
+    const idxs = layout.slots
+      .map((s, i) => (s.kind === kind ? i : -1))
+      .filter(i => i !== -1);
+    if (!idxs.length || idxs.some(i => this.maskValues[i] === '')) return null;
+    return idxs.map(i => this.maskValues[i]).join('');
+  }
+
+  /**
+   * A typed date outside the calendar's allowedDates range snaps to the nearest boundary (the calendar disables
+   * those day cells but typing bypasses it). Only the date slots change; time and timezone are untouched.
+   */
+  private clampMaskToAllowedDates(cal: any, layout: ReturnType<typeof this.maskLayout>) {
+    const range = cal.allowedDatesLocal;
+    if (!range) return;
+    const dayStr = this.completedSegment(layout, 'day');
+    const monthStr = this.completedSegment(layout, 'month');
+    const yearStr = this.completedSegment(layout, 'year');
+    if (dayStr === null || monthStr === null || yearStr === null) return;
+    const yearLen = layout.slots.filter(s => s.kind === 'year').length;
+    const year = yearLen === 2 ? this.fullYearOf(yearStr) : Number(yearStr);
+    const month0 = Number(monthStr) - 1;
+    const day = Number(dayStr);
+    if (month0 < 0 || month0 > 11 || day < 1 || cal.isAllowedDate(day, month0, year)) return;
+    const typed = utcFromFields(year, month0, day);
+    const bound: Date = typed < cal.getUTCDate(range.startDate).getTime()
+      ? cal.getUTCDate(range.startDate)
+      : cal.getUTCDate(range.endDate);
+    const boundYear = bound.getUTCFullYear();
+    if (yearLen === 2 && (boundYear < 2000 || boundYear > 2099)) return; // not representable in a YY mask
+    const fill = (kind: string, text: string) => {
+      let k = 0;
+      layout.slots.forEach((s, i) => { if (s.kind === kind) this.maskValues[i] = text[k++]; });
+    };
+    fill('year', yearLen === 2 ? String(boundYear - 2000).padStart(2, '0') : String(boundYear).padStart(4, '0'));
+    if (yearLen === 2) this.seedYear = boundYear; // the year text now holds the boundary's year
+    fill('month', String(bound.getUTCMonth() + 1).padStart(2, '0'));
+    fill('day', String(bound.getUTCDate()).padStart(2, '0'));
+    const nileInput = this.triggerInput;
+    const native = nileInput?.input as HTMLInputElement | undefined;
+    if (!native) return;
+    const { display } = this.computeDisplay(this.maskValues, this.maskSuffix, layout);
+    this.writeMask(nileInput, native, display, native.selectionStart ?? display.length);
+  }
+
+  private syncCalendarFromMask() {
+    const layout = this.maskLayout();
+    if (this.maskValues.length !== layout.slots.length) return;
+    const cal = this.calendarRef.value as any;
+    if (!cal) return;
+    if (this._yearRejected) {
+      if (this.completedSegment(layout, 'year') !== null) {
+        this._yearRejected = false;
+      } else {
+        // day and month alone must not leave a committable date (carrying the calendar's own year) behind
+        cal.value = null;
+        cal.updateComplete?.then(() => cal.syncInnerCalendar?.()).catch(() => { /* best-effort */ });
+        return;
+      }
+    }
+    if (this._maskEdited) this.clampMaskToAllowedDates(cal, layout);
+
+    const monthStr = this.completedSegment(layout, 'month');
+    const dayStr = this.completedSegment(layout, 'day');
+    const yearStr = this.completedSegment(layout, 'year');
+    const yearSlots = layout.slots.filter(s => s.kind === 'year').length;
+
+    const typedMonth = monthStr === null ? null : Number(monthStr) - 1;
+    const typedYear = yearStr === null ? null : (yearSlots === 2 ? this.fullYearOf(yearStr) : Number(yearStr));
+
+    let changed = false;
+    if (typedMonth !== null && typedMonth >= 0 && typedMonth <= 11) { cal.currentMonth = typedMonth; changed = true; }
+    if (typedYear !== null) { cal.currentYear = typedYear; changed = true; }
+
+    if (dayStr !== null) {
+      const month = typedMonth ?? cal.currentMonth;
+      const year = typedYear ?? cal.currentYear;
+      const lastDay = localDateFromFields(year, month + 1, 0).getDate();
+      const date = localDateFromFields(year, month, Math.min(Number(dayStr), lastDay));
+      if (!isNaN(date.getTime())) {
+        cal.value = date;
+        cal.currentMonth = date.getMonth();
+        cal.currentYear = date.getFullYear();
+        changed = true;
+      }
+    }
+
+    const setTime = (kind: string, prop: string) => {
+      const v = this.completedSegment(layout, kind);
+      if (v !== null) { cal[prop] = Number(v); changed = true; }
+    };
+    setTime('HH', 'tpHours');
+    setTime('mm', 'tpMinutes');
+    setTime('ss', 'tpSeconds');
+    setTime('SSS', 'tpMilliseconds');
+
+    const tz = this.maskSuffix.replace(/^\s*-\s*/, '').trim();
+    if (tz) { cal.timezone = tz; changed = true; }
+
+    if (changed) {
+      cal.updateComplete
+        ?.then(() => cal.syncInnerCalendar?.())
+        .catch(() => { /* calendar failed to update; sync is best-effort */ });
+    }
+  }
+
+  /** Re-derive slot state from whatever the native input now holds, then redisplay it masked. */
+  private reflowMaskFromNative(nileInput: any, native: HTMLInputElement) {
+    const layout = this.maskLayout();
+    // initMaskState forgets the seed's century; the year digits themselves decide whether it still applies
+    const { seedYear } = this;
+    this.initMaskState(native.value);
+    this._maskEdited = true;
+    this.seedYear = seedYear;
+    const segStarts = [...new Set(layout.slots.map(s => s.segStart))];
+    segStarts.forEach(start => this.clampSegment(this.maskValues, layout, start));
+    this.clampDay(this.maskValues, layout);
+    const { display } = this.computeDisplay(this.maskValues, this.maskSuffix, layout);
+    this.writeMask(nileInput, native, display, display.length - (this.maskSuffix && this.maskValues.every(v => v !== '') ? this.maskSuffix.length : 0));
+    this.syncCalendarFromMask();
+  }
+
+  private onMaskPaste = (e: ClipboardEvent) => {
+    if (this.type !== 'absolute' || this.disabled) return;
+    const nileInput = this.triggerInput;
+    const native = nileInput?.input as HTMLInputElement | undefined;
+    if (!native) return;
+    const text = e.clipboardData?.getData('text') ?? '';
+    e.preventDefault();
+    if (!text) return;
+    const selStart = native.selectionStart ?? native.value.length;
+    const selEnd = native.selectionEnd ?? selStart;
+    const layout = this.maskLayout();
+    if (this.maskValues.length !== layout.slots.length) this.initMaskState(native.value);
+    const { slotPos } = this.computeDisplay(this.maskValues, this.maskSuffix, layout);
+    // slot index the caret/selection starts at
+    let first = slotPos.findIndex(pos => pos !== -1 && pos >= selStart);
+    if (first === -1) first = this.maskValues.findIndex(v => v === '');
+    if (first === -1) first = 0;
+    let last = first;
+    slotPos.forEach((pos, i) => { if (pos !== -1 && pos < selEnd) last = Math.max(last, i + 1); });
+    const digits = text.replace(/\D/g, '');
+    if (!digits) return;
+    this._maskEdited = true;
+    const values = [...this.maskValues];
+    if (selEnd > selStart) for (let i = first; i < Math.min(last, values.length); i++) values[i] = '';
+    for (let k = 0; k < digits.length && first + k < values.length; k++) values[first + k] = digits[k];
+    this.maskValues = values;
+    const segStarts = [...new Set(layout.slots.map(s => s.segStart))];
+    segStarts.forEach(start => this.clampSegment(this.maskValues, layout, start));
+    this.clampDay(this.maskValues, layout);
+    const out = this.computeDisplay(this.maskValues, this.maskSuffix, layout).display;
+    this.writeMask(nileInput, native, out, out.length);
+    this.syncCalendarFromMask();
+  };
+
+  /** Covers cut, undo/redo, drag-drop, IME and soft-keyboard input, none of which arrive as a usable keydown. */
+  private onMaskBeforeInput = (e: InputEvent) => {
+    if (this.type !== 'absolute' || this.disabled) return;
+    // digits typed on a desktop keyboard are handled by onMaskKeydown (which preventDefaults them)
+    const t = e.inputType;
+    if (t === 'insertFromPaste') return; // handled by onMaskPaste
+    const nileInput = this.triggerInput;
+    const native = nileInput?.input as HTMLInputElement | undefined;
+    if (!native) return;
+    const handled = ['insertText', 'insertCompositionText', 'insertReplacementText', 'insertFromDrop',
+      'deleteByCut', 'deleteByDrag', 'deleteContentBackward', 'deleteContentForward', 'historyUndo', 'historyRedo'];
+    if (!handled.includes(t)) return;
+    // let the browser apply the edit, then rebuild the slots from the resulting text
+    setTimeout(() => this.reflowMaskFromNative(nileInput, native), 0);
+  };
+
+  private onMaskKeydown = (e: KeyboardEvent) => {
+    if (this.type !== 'absolute') return;
+    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 = this.triggerInput;
+    const native = nileInput?.input as HTMLInputElement | undefined;
+    if (!native) return;
+
+    const layout = this.maskLayout();
+    if (this.maskValues.length !== layout.slots.length) this.initMaskState(native.value);
+    const values = this.maskValues;
+    const { slotPos } = this.computeDisplay(values, this.maskSuffix, layout);
+    const selStart = native.selectionStart ?? 0;
+    const selEnd = native.selectionEnd ?? selStart;
+
+    // caret position to place after editing slot `target`
+    const caretAfter = (target: number) => {
+      const after = this.computeDisplay(values, this.maskSuffix, layout);
+      const np = after.slotPos[target + 1];
+      if (np !== undefined && np !== -1) return np;
+      const suffixLen = after.lastFilled === layout.slots.length - 1 ? this.maskSuffix.length : 0;
+      return after.display.length - suffixLen;
+    };
+    const commit = (target: number, sync = true) => {
+      this.writeMask(nileInput, native, this.computeDisplay(values, this.maskSuffix, layout).display, caretAfter(target));
+      if (sync) this.syncCalendarFromMask(); // reflect a complete manual edit back into the panel
+    };
+
+    const full = this.computeDisplay(values, this.maskSuffix, layout).display;
+    const timeEndPos = full.length - this.maskSuffix.length;
+    if ((e.key === 'Backspace' || e.key === 'Delete') && this.maskSuffix && selStart > timeEndPos) {
+      e.preventDefault();
+      this.maskSuffix = '';
+      const after = this.computeDisplay(values, this.maskSuffix, layout);
+      this.writeMask(nileInput, native, after.display, after.display.length);
+      this.syncCalendarFromMask();
+      this._skipNextSeed = true;
+      this.setTimezoneInternally('UTC');
+      if (this.value) {
+        this.value = this.value.replace(
+          /\[GMT[+-]\d{2}:\d{2}\s+[^\]]+\]$/,
+          '[GMT+00:00 UTC]'
+        );
+      }
+      this.updateComplete
+        .then(() => { this._skipNextSeed = false; })
+        .catch(() => { this._skipNextSeed = false; });
+      const cal = this.calendarRef.value as any;
+      if (cal) {
+        cal.timezone = 'UTC';
+        cal.updateComplete
+          ?.then(() => cal.syncInnerCalendar?.())
+          .catch(() => { /* calendar failed to update; sync is best-effort */ });
+      }
+      return;
+    }
+
+    if ((e.key >= '0' && e.key <= '9') || e.key === 'Backspace' || e.key === 'Delete') this._maskEdited = true;
+
+    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;
+      const typed = layout.slots[target];
+      if (typed.kind === 'year') {
+        // overtyping a seeded year leaves every slot filled while it is still half old, half new: the year is only
+        // complete once its last digit lands, so range-clamping it (or the day against it) earlier would act on a number nobody typed
+        const last = layout.slots.reduce((m, s, i) => (s.segStart === typed.segStart ? i : m), target);
+        if (target !== last) { commit(target, false); return; }
+      } else {
+        this.settleYear(values, layout);
+      }
+      this.clampSegment(values, layout, target);
+      this.clampDay(values, layout);
+      commit(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] = '';
+        }
+        this.writeMask(nileInput, native, this.computeDisplay(values, this.maskSuffix, 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.computeDisplay(values, this.maskSuffix, layout);
+      this.writeMask(nileInput, native, 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.computeDisplay(values, this.maskSuffix, layout);
+      this.writeMask(nileInput, native, after.display, after.slotPos[target] !== -1 ? after.slotPos[target] : selStart);
+      return;
+    }
+    if (e.key.length === 1) e.preventDefault();
+  };
+
+  private maskSegments(): Array<{ kind: string; len: number; max: number; after: string }> {
+    const spec = (token: string): { kind: string; len: number; max: number } => {
+      switch (token) {
+        case 'YYYY': return { kind: 'year', len: 4, max: 9999 };
+        case 'YY':   return { kind: 'year', len: 2, max: 99 };
+        case 'MM':   return { kind: 'month', len: 2, max: 12 };
+        default:     return { kind: 'day', len: 2, max: 31 }; // DD
+      }
+    };
+    const fmt = this.dateFormat || 'DD/MM/YY';
+    const re = /YYYY|YY|MM|DD/g;
+    const found: Array<{ token: string; index: number }> = [];
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(fmt)) !== null) found.push({ token: m[0], index: m.index });
+    const time = this.shownTimeFields;
+    const segments = 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 : (time.length ? ' - ' : '') };
+    });
+    time.forEach((t, i) => {
+      const next = time[i + 1];
+      segments.push({ kind: t.kind, len: t.len, max: t.max, after: next ? this.timeSep(next.kind) : '' });
+    });
+    return segments;
+  }
+
+  private maxDayForMonth(month: string, fullYear: string): number {
+    if (month.length < 2) return 31;
+    const m = Number(month);
+    if (m < 1 || m > 12) return 31;
+    const days = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    if (m !== 2) return days[m - 1];
+    if (!fullYear) return 29;
+    const y = Number(fullYear);
+    const leap = (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0;
+    return leap ? 29 : 28;
+  }
+
+  public render(): TemplateResult {
+    return html`
+      <nile-floating-panel
+        part="panel"
+        exportparts="base"
+        panelClass="nile-dtp-panel"
+        trigger="click"
+        placement="bottom-start"
+        arrow="none"
+        distance="6"
+        ?disabled="${this.disabled}"
+        @nile-init="${(e: Event) => e.stopPropagation()}"
+        @nile-destroy="${(e: Event) => e.stopPropagation()}"
+        @nile-visibility-change="${(e: Event) => e.stopPropagation()}"
+        @nile-show="${this.onPanelShow}"
+        @nile-hide="${this.onPanelHide}"
+      >
+        <nile-input
+          part="trigger"
+          exportparts="base"
+          label=${ifDefined(this.label || undefined)}
+          placeholder="${this.placeholder || this.defaultPlaceholder}"
+          ?disabled="${this.disabled}"
+        >
+          <nile-glyph slot="suffix" name="ng-calendar-clock" size="16" method="stroke" color=${ifDefined(this.disabled ? 'var(--nile-colors-dark-500, var(--ng-colors-fg-disabled))' : undefined)}></nile-glyph>
+        </nile-input>
+
+        <nile-calendar
+          ${ref(this.calendarRef)}
+          variant="date-time-picker"
+          value="${ifDefined(this.value ?? undefined)}"
+          allowedDates="${this.allowedDates}"
+          ?showTypes="${this.showTypes}"
+          ?doubleClickUnselect="${this.doubleClickUnselect}"
+          type="${this.type}"
+          selectedUnit="${ifDefined(this.selectedUnit)}"
+          selectedValue="${ifDefined(this.selectedValue)}"
+          .hideDurationFields="${this.hideDurationFields}"
+          startYear="${ifDefined(this.startYear)}"
+          endYear="${ifDefined(this.endYear)}"
+          ?showMonthDropdown="${this.showMonthDropdown}"
+          ?showYearDropdown="${this.showYearDropdown}"
+          ?disabled="${this.disabled}"
+          timezone="${this.timezone}"
+          dateFormat="${this.dateFormat}"
+          .hideTimeFields="${this.hideTimeFields}"
+          @nile-init="${(e: CustomEvent) => e.stopPropagation()}"
+          @nile-destroy="${(e: CustomEvent) => e.stopPropagation()}"
+          @nile-change="${this.handleChanged}"
+          @nile-clear="${(e: CustomEvent) => { e.stopPropagation(); this.handleClear(); }}"
+          @nile-type-change="${(e: CustomEvent) => { e.stopPropagation(); this.handleTypeChange(e); }}"
+        ></nile-calendar>
+      </nile-floating-panel>
+    `;
+  }
+
+  private handleTypeChange(e: CustomEvent) {
+    const next = e.detail?.value;
+    if (next === 'absolute' || next === 'relative') this.type = next;
+    // slot state belongs to the absolute layout; drop it so a stale mask can't rewrite relative text
+    this.maskValues = [];
+    this.maskSuffix = '';
+    this._yearRejected = false;
+    this.emit('nile-type-change', e.detail);
+  }
+
+  handleChanged(event: CustomEvent) {
+    event.stopPropagation();
+    if (this.disabled) return;
+
+    const detail = event.detail;
+    const triggerInput = this.triggerInput;
+    if (triggerInput && detail) {
+      const text = this.formatValue(detail);
+      if (this.type === 'absolute') {
+        this.initMaskState(text); // keep the editable slot values in sync
+        this.seedMask = [...this.maskValues];
+        // the applied selection's own year, so a YY mask keeps its century on the next edit
+        this.seedYear = detail.wall?.year
+          ?? (detail.value instanceof Date ? detail.value.getFullYear()
+            : typeof detail.value === 'string' ? this.parseWallClock(detail.value)?.year ?? null : null);
+        this._maskEdited = false;
+        this._showCommittedOnOpen = true;
+      } else {
+        // relative range text isn't in the absolute mask layout; drop stale slot state
+        this.maskValues = [];
+        this.maskSuffix = '';
+        this._yearRejected = false;
+      }
+      triggerInput.value = text;
+      triggerInput.emit('nile-input', { value: text });
+    }
+    // keep the public value in step with the applied selection, so a later re-seed (e.g. a timezone change) can't restore the old one
+    if (this.type === 'absolute' && typeof detail?.value === 'string' && detail.value) {
+      this.value = detail.value;
+    }
+
+    this.emit('nile-change', detail);
+    (triggerInput?.input as HTMLElement | undefined)?.focus?.();
+    this.panel?.hide();
+  }
+
+  handleClear() {
+    const triggerInput = this.triggerInput;
+    if (triggerInput) {
+      triggerInput.value = '';
+      triggerInput.emit('nile-input', { value: '' });
+    }
+    this.maskValues = [];
+    this.maskSuffix = '';
+    this._yearRejected = false;
+    this.value = null;
+    this.setTimezoneInternally(this._defaultTimezone);
+    // the calendar may have drifted (zone typed in the mask, picked in its dropdown) while our own `timezone` did not change, so the template binding won't re-apply it
+    const cal = this.calendarRef.value as any;
+    if (cal) cal.timezone = this._defaultTimezone;
+    this.emit('nile-clear');
+  }
+
+  private pad(value: number, length = 2): string {
+    return String(value).padStart(length, '0');
+  }
+
+  /** Read an instant's fields in the host zone. Lossless in this direction. */
+  private wallClockFromDate(date: Date): WallClock {
+    return {
+      year: date.getFullYear(), month: date.getMonth() + 1, day: date.getDate(),
+      hours: date.getHours(), minutes: date.getMinutes(),
+      seconds: date.getSeconds(), ms: date.getMilliseconds(),
+    };
+  }
+
+  private formatDatePartFields(wall: WallClock): string {
+    const yyyy = String(wall.year);
+    // the structured mask has exactly four year slots, so years 0-999 must print four digits (a bare `100` would be re-read as `1000` on blur)
+    const year4 = wall.year >= 0 && wall.year < 1000 ? yyyy.padStart(4, '0') : yyyy;
+    return (this.dateFormat || 'DD/MM/YY')
+      .replace(/YYYY/g, year4)
+      .replace(/YY/g, yyyy.padStart(2, '0').slice(-2))
+      .replace(/MM/g, this.pad(wall.month))
+      .replace(/DD/g, this.pad(wall.day));
+  }
+
+  private formatWallClock(wall: WallClock): string {
+    const valueFor: Record<string, string> = {
+      HH: this.pad(wall.hours),
+      mm: this.pad(wall.minutes),
+      ss: this.pad(wall.seconds),
+      SSS: this.pad(wall.ms, 3),
+    };
+    const time = this.shownTimeFields;
+    if (!time.length) return this.formatDatePartFields(wall);
+    const timeStr = time
+      .map((t, i) => (i > 0 ? this.timeSep(t.kind) : '') + valueFor[t.kind])
+      .join('');
+    return `${this.formatDatePartFields(wall)} - ${timeStr}`;
+  }
+
+  private formatDateTime(date: Date): string {
+    return this.formatWallClock(this.wallClockFromDate(date));
+  }
+
+  /** A value's digits as written: bracketed `…[GMT+05:30 Zone]` or offset-less `YYYY-MM-DDTHH:mm[:ss[.SSS]]`; anything else is null. */
+  private parseWallClock(iso: string): WallClock | null {
+    return this.parseZonedValue(iso)?.wall ?? wallClockFromOffsetLess(iso);
+  }
+
+  private parseZonedValue(raw: string): { wall: WallClock; timezone: string } | 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 wall = wallClockFromOffsetLess(m[1]);
+    if (!wall) return null;
+    const zone = m[2].trim();
+    const timezone = isValidTimezone(zone) ? zone : 'UTC';
+    return { wall, timezone };
+  }
+
+  private formatValue(detail: any): string {
+    // `detail` is an untrusted event payload: optional chaining alone would render a literal " - undefined" when `timezone` is omitted, so fall back to the component's own zone.
+    const zone = detail?.timezone ?? this.timezone;
+    const tz = this.showTimezone ? ` - ${zone}` : '';
+    if (detail?.wall) {
+      return `${this.formatWallClock(detail.wall)}${tz}`;
+    }
+    if (detail?.value instanceof Date) {
+      return `${this.formatDateTime(detail.value)}${tz}`;
+    }
+    if (typeof detail?.value === 'string' && detail.value) {
+      const wall = this.parseWallClock(detail.value);
+      if (wall) return `${this.formatWallClock(wall)}${tz}`;
+    }
+    if (detail?.startDate && detail?.endDate) {
+      // a labelled range must show its instants in the labelled zone, not the host's
+      const inZone = (d: Date) =>
+        this.showTimezone && isValidTimezone(zone)
+          ? this.formatWallClock(wallClockInZone(d.getTime(), zone))
+          : this.formatDateTime(d);
+      const start = inZone(new Date(detail.startDate));
+      const end = inZone(new Date(detail.endDate));
+      return `${start} - ${end}${tz}`;
+    }
+    return '';
+  }
+}
+
+export default NileDateTimePicker;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'nile-date-time-picker': NileDateTimePicker;
+  }
+}