@adia-ai/web-components 0.8.40 → 0.8.41

package/components/calendar-picker/calendar-picker.class.js

@@ -12,32 +12,66 @@
  */
 
 /**
- * <calendar-picker-ui label="Date" placeholder="Select date..." format="short"></calendar-picker-ui>
+ * <calendar-picker-ui placeholder="Select date..." format="short"></calendar-picker-ui>
  *
- * Date picker with trigger button and popover calendar grid.
- * Form-associated via UIFormElement + ElementInternals.
+ * Date (and, per `[precision]`, date+time) picker with trigger button and
+ * popover panel. Form-associated via UIFormElement + ElementInternals.
+ *
+ * gh#1372 (#1363 C3c) — this class now folds `<datetime-picker-ui>`'s surface
+ * in behind a widened `precision` axis (`date` | `minute` | `second`) rather
+ * than the two primitives duplicating the same trigger/popover/anchor/focus-
+ * trap machinery. `precision="date"` (the default) is exactly the prior
+ * single-pane behavior — composes only `<calendar-grid-ui>`. `precision`
+ * `"minute"`/`"second"` additionally composes `<divider-ui>` +
+ * `<time-picker-ui>` as a second pane, `value` becomes a full ISO 8601
+ * datetime string, and `hour-cycle`/`step`/`locale` become active — the same
+ * contract `<datetime-picker-ui>` shipped, which is now a deprecated thin
+ * alias subclass (see datetime-picker.class.js) mapping onto this class with
+ * `precision="minute"` by default. Per ADR-0027, the consumer must
+ * explicitly import every composed primitive (see `composes:` in
+ * calendar-picker.yaml) — this class doesn't auto-import them.
+ *
+ * #1363 C3d sibling-contract convergence, folded into this same build:
+ *   - `readonly` (inherited from UIFormElement) now has real behavior —
+ *     blocks the popover from opening; keyboard focus/inspection still
+ *     works.
+ *   - `input` / `open` / `close` / `invalid` events now fire (previously
+ *     only `change` existed).
+ *   - `name` / `min` / `max` are declared `reflect: true` in the yaml,
+ *     matching the class's actual (already-reflecting) behavior.
+ *   - The odd first-class `label` prop is REMOVED — siblings all delegate
+ *     the label to `<field-ui label>`; this was calendar-picker's own
+ *     outlier. Breaking; migration-guide entry + consumer scan accompany
+ *     this change.
  *
  * Properties:
- *   label       — field label (rendered via CSS ::before)
- *   placeholder — trigger text when no date selected
+ *   placeholder — trigger text when no value selected
  *   format      — display format: short | long | iso
- *   min         — minimum selectable date (ISO string)
- *   max         — maximum selectable date (ISO string)
+ *   precision   — date | minute | second (mode axis — widens the surface)
+ *   min         — minimum selectable date/datetime (ISO string)
+ *   max         — maximum selectable date/datetime (ISO string)
+ *   step        — per-Arrow-keypress time increment in seconds (time modes only)
+ *   hourcycle   — '' | h12 | h23 (time modes only; attribute hour-cycle)
+ *   locale      — BCP-47 locale for hour-cycle derivation (time modes only)
  *   open        — popover visibility
+ *   readonly    — blocks edits; keyboard inspection still works
  *
- * Keyboard: Arrow keys navigate days, Enter selects, Escape closes.
+ * Keyboard: Enter/Space (closed) opens; Escape (open) closes. Arrow keys,
+ * PageUp/PageDown, Home/End, and day-selection Enter/Space are handled by
+ * the composed calendar-grid-ui once DOM focus moves into it on open (see
+ * the queueMicrotask in render()) — calendar-grid-ui binds its own keydown
+ * listener to itself, not to this host, so focus must be inside it for
+ * that handling to receive events at all. In a time-pane mode, Tab cycles
+ * from the calendar pane into the time pane's Spinbutton segments.
  */
 
 import { UIFormElement } from '../../core/form.js';
 import { anchorPopover } from '../../core/anchor.js';
 
-const DAYS = ['S', 'M', 'T', 'W', 'T', 'F', 'S'];
 const MONTHS_SHORT = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
 const MONTHS_LONG = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
 
-function toISO(y, m, d) {
-  return `${y}-${String(m + 1).padStart(2, '0')}-${String(d).padStart(2, '0')}`;
-}
+function pad2(n) { return String(n).padStart(2, '0'); }
 
 function parseISO(str) {
   if (!str) return null;
@@ -46,68 +80,276 @@ function parseISO(str) {
   return new Date(y, m - 1, d);
 }
 
-function sameDay(a, b) {
-  return a.getFullYear() === b.getFullYear() &&
-    a.getMonth() === b.getMonth() &&
-    a.getDate() === b.getDate();
+/** Parse "YYYY-MM-DDTHH:mm" or "YYYY-MM-DDTHH:mm:ss" → {date, time} or null. */
+function parseDatetime(str) {
+  if (!str) return null;
+  const s = String(str).trim();
+  // Tolerate space separator as a Generative-UI quality-of-life affordance;
+  // canonical wire form is always "T".
+  const m = /^(\d{4}-\d{2}-\d{2})[T ](\d{1,2}:\d{2}(?::\d{2})?)$/.exec(s);
+  if (!m) return null;
+  return { date: m[1], time: m[2] };
+}
+
+/** Compose canonical "YYYY-MM-DDTHH:mm[:ss]" from a {date, time} pair. */
+function formatDatetime(date, time, precision) {
+  if (!date || !time) return '';
+  const tm = /^(\d{1,2}):(\d{2})(?::(\d{2}))?$/.exec(time);
+  if (!tm) return '';
+  const hh = pad2(Number(tm[1]));
+  const mm = tm[2];
+  const ss = tm[3] || '00';
+  return precision === 'second' ? `${date}T${hh}:${mm}:${ss}` : `${date}T${hh}:${mm}`;
+}
+
+function formatDatePart(iso, fmt) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso || '');
+  if (!m) return '';
+  const y = +m[1];
+  const mo = +m[2] - 1;
+  const d = +m[3];
+  switch (fmt) {
+    case 'long': return `${MONTHS_LONG[mo]} ${d}, ${y}`;
+    case 'iso': return iso;
+    case 'short':
+    default: return `${MONTHS_SHORT[mo]} ${d}, ${y}`;
+  }
+}
+
+function formatTimePart(time, precision, hourcycle) {
+  const m = /^(\d{1,2}):(\d{2})(?::(\d{2}))?$/.exec(time || '');
+  if (!m) return '';
+  const h = +m[1];
+  const mm = m[2];
+  const ss = m[3];
+  let hStr;
+  let meridiem = '';
+  if (hourcycle === 'h12') {
+    const isPM = h >= 12;
+    const dispH = (h % 12) || 12;
+    hStr = pad2(dispH);
+    meridiem = isPM ? ' PM' : ' AM';
+  } else {
+    hStr = pad2(h);
+  }
+  const sec = (precision === 'second' && ss != null) ? `:${ss}` : '';
+  return `${hStr}:${mm}${sec}${meridiem}`;
 }
 
 export class UICalendarPicker extends UIFormElement {
-  static labelDeprecated = false;  // §170 (v0.5.4): label is first-class per calendar-picker.yaml
+  // §170 (v0.5.4)/gh#1372: label was first-class; removed per #1363 C3d —
+  // siblings all delegate to <field-ui label>. Base class still reads this
+  // static to decide whether to warn on an authored [label] attribute.
+  static labelDeprecated = true;
+
   // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
   // consumer markup). Aggregated by installIconLoadersForRegistered()
   // across all defined elements. Audited by check-required-icons.mjs
   // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
-  static requiredIcons = ['calendar', 'caret-left', 'caret-right'];
+  // caret-left/caret-right dropped (gh#1371) — those nav-button icons are
+  // now stamped by the composed calendar-grid-ui, which declares its own
+  // requiredIcons; this class itself only stamps `calendar` on the trigger.
+  static requiredIcons = ['calendar'];
 
   static properties = {
     ...UIFormElement.properties,
-    label:       { type: String,  default: '', reflect: true },
-    placeholder: { type: String,  default: 'Select date...', reflect: true },
-    format:      { type: String,  default: 'short', reflect: true },
-    min:         { type: String,  default: '', reflect: true },
-    max:         { type: String,  default: '', reflect: true },
-    open:        { type: Boolean, default: false, reflect: true },
+    placeholder: { type: String, default: 'Select date...', reflect: true },
+    format: { type: String, default: 'short', reflect: true },
+    min: { type: String, default: '', reflect: true },
+    max: { type: String, default: '', reflect: true },
+    open: { type: Boolean, default: false, reflect: true },
+    // gh#1372 (#1363 C3c) — the widened mode axis. 'date' is the prior
+    // single-pane behavior; 'minute'/'second' fold in what
+    // <datetime-picker-ui> used to be its own primitive for.
+    precision: { type: String, default: 'date', reflect: true },
+    // Active only when precision !== 'date' — mirrors datetime-picker's
+    // former contract exactly (folded in, not reinvented).
+    step: { type: Number, default: 60, reflect: true },
+    hourcycle: { type: String, default: '', reflect: true, attribute: 'hour-cycle' },
+    locale: { type: String, default: '', reflect: false },
     // Popover placement — yaml documented this as reflect:true since v1;
     // the JS reads it via getAttribute('placement') in the anchorPopover
     // call site. Declaring here so el.placement = 'top' also updates.
-    placement:   { type: String,  default: 'bottom', reflect: true },
+    placement: { type: String, default: 'bottom', reflect: true },
   };
 
   static template = () => null;
 
   #popover = null;
   #trigger = null;
+  #grid = null;
+  #gridBound = false;
+  #divider = null;
+  #timePane = null;
+  #timePaneBound = false;
   #anchorCleanup = null;
-  #viewYear = new Date().getFullYear();
-  #viewMonth = new Date().getMonth();
-  #focusedDay = null;
-  #popoverClickBound = false;
   #openRaf = null;
+  // Tracks whether the popover was already open as of the LAST render, so
+  // the initial-focus microtask below fires only on the closed→open
+  // transition — not on every subsequent open-state render (e.g. the one
+  // #onGridChange triggers by writing `this.value`), which would otherwise
+  // re-steal focus back to the first day on every selection (review finding,
+  // PR #1437). Reset on close (naturally, via the render() assignment below)
+  // and explicitly on disconnect so a later reconnect-while-open re-arms it.
+  #wasOpen = false;
+  // Partial {date, time} selection state — only meaningful when
+  // precision !== 'date' (two panes must both commit before `value` is
+  // written). Mirrors the former datetime-picker.class.js `#pending`.
+  #pending = null;
+  // Records why the NEXT open/close transition happened, read once by
+  // render()'s wasOpen-diff below, then cleared. Centralizing the
+  // open/close event dispatch in render() (rather than at every call site
+  // that flips `this.open`) means no call site can forget to fire it.
+  #openTrigger = 'programmatic';
+  #closeReason = 'programmatic';
+
+  get #hasTimePane() { return this.precision === 'minute' || this.precision === 'second'; }
+
+  // Substrate change → adopt the selection, mirror it back out as this
+  // primitive's own `change` (same detail shape callers already expect),
+  // and stop the inner event from also reaching listeners upstream of us
+  // (mirrors date-range-picker's #onDaySelect — one `change`, not two).
+  #onGridChange = (e) => {
+    if (this.readonly) return;
+    e.stopPropagation();
+    const iso = e.detail?.value || this.#grid?.value || '';
+    if (!iso) return;
+    if (!this.#hasTimePane) {
+      this.value = iso;
+      this.syncValue(iso);
+      this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
+      // Popover stays open until the user clicks outside — matches the prior
+      // inlined-grid behavior (no auto-close on selection).
+      return;
+    }
+    // Two-pane (datetime) mode — date half of a pending commit.
+    if (!this.#pending) this.#pending = { date: '', time: '' };
+    this.#pending.date = iso;
+    const existing = parseDatetime(this.value);
+    const timeCandidate = this.#pending.time || existing?.time || '';
+    const partial = timeCandidate ? formatDatetime(iso, timeCandidate, this.precision) : `${iso}T`;
+    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: partial } }));
+    if (timeCandidate) {
+      this.#commitFromParts({ date: iso, time: timeCandidate });
+    } else {
+      // Advance focus to the time pane's first segment — a11y model:
+      // date → time → commit.
+      queueMicrotask(() => {
+        if (!this.open) return;
+        const hourSeg = this.#timePane?.querySelector?.('[data-segment="hour"]');
+        hourSeg?.focus?.();
+      });
+    }
+  };
 
-  #onPopoverClick = (e) => {
-    const target = e.target instanceof Element ? e.target : null;
-    if (!target) return;
-    const prev = target.closest('[data-cal-prev]');
-    if (prev) { e.stopPropagation(); this.#navigate(-1); return; }
-    const next = target.closest('[data-cal-next]');
-    if (next) { e.stopPropagation(); this.#navigate(1); return; }
-    const day = target.closest('[data-cal-day][data-date]:not([disabled])');
-    if (day) { e.stopPropagation(); this.#selectDate(day.dataset.date); }
+  #onTimePaneChange = (e) => {
+    if (this.readonly) return;
+    e.stopPropagation();
+    const time = e.detail?.value || this.#timePane?.value || '';
+    if (!time) return;
+    if (!this.#pending) this.#pending = { date: '', time: '' };
+    this.#pending.time = time;
+    const existing = parseDatetime(this.value);
+    const dateCandidate = this.#pending.date || existing?.date || '';
+    if (dateCandidate) {
+      this.#commitFromParts({ date: dateCandidate, time });
+    } else {
+      this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: `T${time}` } }));
+    }
+  };
+
+  #onTimePaneInput = (e) => {
+    if (this.readonly) return;
+    e.stopPropagation();
+    const time = e.detail?.value || '';
+    const existing = parseDatetime(this.value);
+    const date = this.#pending?.date || existing?.date || '';
+    const partial = (date && time) ? formatDatetime(date, time, this.precision) : (time ? `T${time}` : '');
+    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: partial } }));
   };
 
+  #onPaneInvalid = (e) => {
+    e.stopPropagation();
+    this.dispatchEvent(new CustomEvent('invalid', { bubbles: true, detail: { value: this.value, reason: e.detail?.reason || 'pane' } }));
+  };
+
+  /** Commit a candidate {date, time} pair once both halves are present. */
+  #commitFromParts(parts) {
+    if (!parts || !parts.date || !parts.time) return;
+    const next = formatDatetime(parts.date, parts.time, this.precision);
+    if (!next) {
+      this.dispatchEvent(new CustomEvent('invalid', { bubbles: true, detail: { value: next, reason: 'parse' } }));
+      return;
+    }
+    if (this.min && next < this.min) {
+      this.dispatchEvent(new CustomEvent('invalid', { bubbles: true, detail: { value: next, reason: 'below-min' } }));
+      return;
+    }
+    if (this.max && next > this.max) {
+      this.dispatchEvent(new CustomEvent('invalid', { bubbles: true, detail: { value: next, reason: 'above-max' } }));
+      return;
+    }
+    this.value = next;
+    this.#pending = null;
+    this.syncValue(next);
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: next } }));
+  }
+
+  /**
+   * Override `syncValue` to run date/datetime constraint checks in addition
+   * to the base UIFormElement::syncValue write.
+   */
+  syncValue(val) {
+    const baseVal = val ?? this.value ?? '';
+    this.internals.setFormValue(baseVal);
+    this.#runConstraints(baseVal);
+  }
+
+  #runConstraints(val) {
+    if (this.required && !val) {
+      this.internals.setValidity(
+        { valueMissing: true },
+        this.getAttribute('data-msg-required') || (this.#hasTimePane ? 'Please select a date and time.' : 'Please select a date.'),
+        this,
+      );
+      return false;
+    }
+    if (!val) {
+      this.internals.setValidity({});
+      return true;
+    }
+    if (this.#hasTimePane) {
+      const parsed = parseDatetime(val);
+      if (!parsed) {
+        this.internals.setValidity({ badInput: true }, 'Invalid date or time format.', this);
+        return false;
+      }
+    }
+    if (this.min && val < this.min) {
+      this.internals.setValidity(
+        { rangeUnderflow: true },
+        `Earliest selectable ${this.#hasTimePane ? 'datetime' : 'date'} is ${this.min}.`,
+        this,
+      );
+      return false;
+    }
+    if (this.max && val > this.max) {
+      this.internals.setValidity(
+        { rangeOverflow: true },
+        `Latest selectable ${this.#hasTimePane ? 'datetime' : 'date'} is ${this.max}.`,
+        this,
+      );
+      return false;
+    }
+    this.internals.setValidity({});
+    return true;
+  }
+
   connected() {
     super.connected();
     this.setAttribute('role', 'group');
     this.addEventListener('click', this.#onClick);
     this.addEventListener('keydown', this.#onKey);
-
-    // Initialize view to selected date or today
-    const sel = parseISO(this.value);
-    if (sel) {
-      this.#viewYear = sel.getFullYear();
-      this.#viewMonth = sel.getMonth();
-    }
   }
 
   render() {
@@ -125,8 +367,6 @@ export class UICalendarPicker extends UIFormElement {
       this.#popover.setAttribute('slot', 'popover');
       this.#popover.setAttribute('popover', 'manual');
       this.appendChild(this.#popover);
-      this.#popover.addEventListener('click', this.#onPopoverClick);
-      this.#popoverClickBound = true;
     } else {
       const display = this.querySelector('[slot="display"]');
       if (display) display.textContent = this.#displayText();
@@ -134,17 +374,120 @@ export class UICalendarPicker extends UIFormElement {
 
     if (!this.#popover) this.#popover = this.querySelector('[slot="popover"]');
     if (!this.#trigger) this.#trigger = this.querySelector('[slot="trigger"]');
-    if (this.#popover && !this.#popoverClickBound) {
-      this.#popover.addEventListener('click', this.#onPopoverClick);
-      this.#popoverClickBound = true;
+
+    // Ensure the substrate grid exists inside the popover — composed once,
+    // reused across opens (matches date-range-picker's calFrom/calTo parts).
+    if (this.#popover && !this.#grid) {
+      this.#grid = this.#popover.querySelector('calendar-grid-ui');
+      if (!this.#grid) {
+        this.#grid = document.createElement('calendar-grid-ui');
+        this.#popover.appendChild(this.#grid);
+      }
+    }
+    if (this.#grid && !this.#gridBound) {
+      this.#grid.addEventListener('change', this.#onGridChange);
+      this.#gridBound = true;
+    }
+
+    // gh#1372 — stamp/tear down the time pane + divider as `precision`
+    // dictates. Idempotent: a no-op once the pane already matches.
+    if (this.#popover) {
+      if (this.#hasTimePane) {
+        if (!this.#divider) {
+          this.#divider = this.#popover.querySelector('[data-pane-divider]');
+          if (!this.#divider) {
+            this.#divider = document.createElement('divider-ui');
+            this.#divider.setAttribute('data-pane-divider', '');
+            this.#divider.setAttribute('vertical', '');
+            this.#popover.appendChild(this.#divider);
+          }
+        }
+        if (!this.#timePane) {
+          this.#timePane = this.#popover.querySelector('[data-time-pane]');
+          if (!this.#timePane) {
+            this.#timePane = document.createElement('time-picker-ui');
+            this.#timePane.setAttribute('data-time-pane', '');
+            this.#popover.appendChild(this.#timePane);
+          }
+        }
+        if (!this.#timePaneBound) {
+          this.#timePane.addEventListener('change', this.#onTimePaneChange);
+          this.#timePane.addEventListener('input', this.#onTimePaneInput);
+          this.#timePane.addEventListener('invalid', this.#onPaneInvalid);
+          this.#timePaneBound = true;
+        }
+      } else if (this.#timePane || this.#divider) {
+        // precision switched back to 'date' at runtime — tear the pane down.
+        if (this.#timePaneBound) {
+          this.#timePane.removeEventListener('change', this.#onTimePaneChange);
+          this.#timePane.removeEventListener('input', this.#onTimePaneInput);
+          this.#timePane.removeEventListener('invalid', this.#onPaneInvalid);
+          this.#timePaneBound = false;
+        }
+        this.#timePane?.remove();
+        this.#divider?.remove();
+        this.#timePane = null;
+        this.#divider = null;
+        this.#pending = null;
+      }
+    }
+
+    // Cascade value/min/max/precision knobs into the substrate(s) on every
+    // render so external prop writes (not just this class's own selection
+    // flow) stay in sync.
+    if (this.#grid) {
+      const parsed = this.#hasTimePane ? parseDatetime(this.value) : null;
+      const datePart = this.#hasTimePane ? (this.#pending?.date ?? parsed?.date ?? '') : (this.value || '');
+      this.#grid.value = datePart;
+      const minDate = this.#hasTimePane ? (this.min ? this.min.slice(0, 10) : '') : this.min;
+      const maxDate = this.#hasTimePane ? (this.max ? this.max.slice(0, 10) : '') : this.max;
+      if (minDate) this.#grid.setAttribute('min', minDate); else this.#grid.removeAttribute('min');
+      if (maxDate) this.#grid.setAttribute('max', maxDate); else this.#grid.removeAttribute('max');
+      this.#grid.toggleAttribute('disabled', !!this.disabled);
+      this.#grid.toggleAttribute('readonly', !!this.readonly);
+    }
+
+    if (this.#hasTimePane && this.#timePane) {
+      const parsed = parseDatetime(this.value);
+      const timePart = this.#pending?.time ?? parsed?.time ?? '';
+      this.#timePane.setAttribute('precision', this.precision);
+      this.#timePane.setAttribute('step', String(this.step));
+      if (this.hourcycle) this.#timePane.setAttribute('hour-cycle', this.hourcycle); else this.#timePane.removeAttribute('hour-cycle');
+      if (this.locale) this.#timePane.setAttribute('locale', this.locale); else this.#timePane.removeAttribute('locale');
+      // Time-of-day portion of min/max only applies when the pending/parsed
+      // date matches the bound's own date — an advisory affordance; the
+      // host-level #commitFromParts constraint check is the real gate.
+      const datePart = this.#pending?.date ?? parsed?.date ?? '';
+      const minTime = this.min ? this.min.slice(11) : '';
+      const maxTime = this.max ? this.max.slice(11) : '';
+      if (minTime && datePart === this.min.slice(0, 10)) this.#timePane.setAttribute('min', minTime); else this.#timePane.removeAttribute('min');
+      if (maxTime && datePart === this.max.slice(0, 10)) this.#timePane.setAttribute('max', maxTime); else this.#timePane.removeAttribute('max');
+      if (this.#timePane.value !== timePart) this.#timePane.value = timePart;
+      this.#timePane.toggleAttribute('disabled', !!this.disabled);
+      this.#timePane.toggleAttribute('readonly', !!this.readonly);
+    }
+
+    // Lift a consumer-authored [slot="footer"] (Apply/Cancel explicit-commit
+    // affordance) into the popover, after the pane(s).
+    const authorFooter = this.querySelector(':scope > [slot="footer"]');
+    if (authorFooter && this.#popover && authorFooter.parentElement !== this.#popover) {
+      this.#popover.appendChild(authorFooter);
+    }
+
+    // A disabled/readonly host can't legitimately be open — belt-and-braces
+    // circuit breaker (mirrors the former datetime-picker.class.js render()).
+    if (this.open && (this.disabled || this.readonly)) {
+      this.open = false;
     }
 
     // Toggle popover
+    const justOpened = this.open && !this.#wasOpen;
+    const justClosed = !this.open && this.#wasOpen;
     if (this.open) {
-      this.#renderCalendar();
       this.#popover?.showPopover?.();
-      // ADR-0034 Rule 2: calendar panel (~330px) >> trigger button (~200px) → center.
-      // Consumer can override via placement="bottom-start|top|…" attribute.
+      // ADR-0034 Rule 2: calendar panel (~330px, or the two-pane datetime
+      // width) >> trigger button (~200px) → center. Consumer can override
+      // via placement="bottom-start|top|…" attribute.
       this.#anchorCleanup = anchorPopover(this.#trigger, this.#popover, {
         placement: this.getAttribute('placement') || 'bottom', gap: 4,
       });
@@ -153,6 +496,36 @@ export class UICalendarPicker extends UIFormElement {
         if (!this.isConnected || !this.open) return;
         document.addEventListener('pointerdown', this.#onOutside, { once: true });
       });
+      // Move DOM focus into the grid so ITS OWN keydown listener (bound to
+      // itself, not this host) receives arrow/Enter/PageUp/PageDown/Home/End
+      // — same technique date-range-picker uses for its panes (gh#1371: the
+      // old inlined grid worked because #onKey lived on this host and
+      // intercepted keys regardless of where focus was; the composed
+      // substrate requires focus to actually be inside it). Gated to the
+      // closed→open transition only (`justOpened`) — running this on EVERY
+      // open-state render would re-steal focus back to the first day after
+      // every selection, since #onGridChange's `this.value = iso` triggers
+      // another render while still open (review finding, PR #1437).
+      if (justOpened) {
+        queueMicrotask(() => {
+          if (!this.open || !this.#grid) return;
+          const selected = this.#grid.querySelector('[data-cal-day][data-selected]:not([data-outside])');
+          const target = selected || this.#grid.querySelector('[data-cal-day]:not([disabled]):not([data-outside])');
+          const day = target && Number(target.dataset.date?.split('-')[2]);
+          // Route through the grid's own focusDay() rather than a raw
+          // `target.focus()` — focusDay() sets calendar-grid-ui's internal
+          // `#focusedDay` (the roving-tabindex + Enter-to-select state)
+          // BEFORE moving DOM focus, so Enter and subsequent arrow-key nav
+          // have a correct baseline immediately. A bare `.focus()` moves
+          // DOM focus without touching that internal state, leaving Enter
+          // with no selection target and arrow nav starting from day 1
+          // (review finding, PR #1437).
+          if (day) this.#grid.focusDay(day);
+        });
+      }
+      if (justOpened) {
+        this.dispatchEvent(new CustomEvent('open', { bubbles: true, detail: { trigger: this.#openTrigger } }));
+      }
     } else {
       this.#anchorCleanup?.();
       this.#anchorCleanup = null;
@@ -162,11 +535,23 @@ export class UICalendarPicker extends UIFormElement {
       }
       this.#popover?.hidePopover?.();
       document.removeEventListener('pointerdown', this.#onOutside);
+      if (justClosed) {
+        this.dispatchEvent(new CustomEvent('close', { bubbles: true, detail: { reason: this.#closeReason } }));
+      }
     }
+    this.#wasOpen = this.open;
   }
 
   #displayText() {
     if (!this.value) return this.placeholder;
+    if (this.#hasTimePane) {
+      const parsed = parseDatetime(this.value);
+      if (!parsed) return this.value;
+      const dPart = formatDatePart(parsed.date, this.format);
+      const tPart = formatTimePart(parsed.time, this.precision, this.hourcycle);
+      if (!dPart || !tPart) return this.placeholder;
+      return `${dPart} ${tPart}`;
+    }
     const d = parseISO(this.value);
     if (!d) return this.value;
     switch (this.format) {
@@ -180,125 +565,55 @@ export class UICalendarPicker extends UIFormElement {
     }
   }
 
-  #renderCalendar() {
-    if (!this.#popover) return;
-
-    const year = this.#viewYear;
-    const month = this.#viewMonth;
-    const today = new Date();
-    const selected = parseISO(this.value);
-    const minDate = parseISO(this.min);
-    const maxDate = parseISO(this.max);
-
-    // Header
-    // <button-ui variant="ghost" icon="…"> (gh issue 276 wave 4) — no
-    // tabindex here, matching the native version: these nav buttons stay in
-    // the default tab order (unlike calendar-grid-ui's, which are pulled out
-    // via tabindex="-1" for its inline roving-tabindex day grid).
-    let h = `<div data-cal-header>
-      <button-ui variant="ghost" size="sm" icon="caret-left" data-cal-prev aria-label="Previous month"></button-ui>
-      <span data-cal-title>${MONTHS_LONG[month]} ${year}</span>
-      <button-ui variant="ghost" size="sm" icon="caret-right" data-cal-next aria-label="Next month"></button-ui>
-    </div>`;
-
-    // Day-of-week header
-    h += `<div data-cal-weekdays>${DAYS.map(d => `<span>${d}</span>`).join('')}</div>`;
-
-    // Calendar grid
-    const firstDay = new Date(year, month, 1).getDay();
-    const daysInMonth = new Date(year, month + 1, 0).getDate();
-    const daysInPrev = new Date(year, month, 0).getDate();
-
-    h += '<div data-cal-grid>';
-
-    // Previous month trailing days
-    for (let i = firstDay - 1; i >= 0; i--) {
-      const day = daysInPrev - i;
-      h += `<button-ui variant="ghost" data-cal-day data-outside disabled tabindex="-1" text="${day}"></button-ui>`;
-    }
-
-    // Current month days
-    for (let d = 1; d <= daysInMonth; d++) {
-      const date = new Date(year, month, d);
-      const iso = toISO(year, month, d);
-      const isToday = sameDay(date, today);
-      const isSelected = selected && sameDay(date, selected);
-      const isDisabled = (minDate && date < minDate) || (maxDate && date > maxDate);
-      const isFocused = this.#focusedDay === d;
-
-      const attrs = [
-        'data-cal-day',
-        `data-date="${iso}"`,
-        isToday ? 'data-today' : '',
-        isSelected ? 'data-selected' : '',
-        isDisabled ? 'disabled' : '',
-        isFocused ? 'data-focused' : '',
-        `tabindex="${isFocused ? '0' : '-1'}"`,
-      ].filter(Boolean).join(' ');
-
-      // <button-ui variant="ghost" text="…"> (gh issue 276 wave 4) — the day
-      // number moves from element text content to the `text` attribute.
-      h += `<button-ui variant="ghost" ${attrs} text="${d}"></button-ui>`;
-    }
-
-    // Next month leading days
-    const totalCells = firstDay + daysInMonth;
-    const remaining = (7 - (totalCells % 7)) % 7;
-    for (let d = 1; d <= remaining; d++) {
-      h += `<button-ui variant="ghost" data-cal-day data-outside disabled tabindex="-1" text="${d}"></button-ui>`;
-    }
-
-    h += '</div>';
-
-    this.#popover.innerHTML = h;
-    // Events are delegated on #popover (see #onPopoverClick) — no per-element wiring.
-  }
-
-  #navigate(delta) {
-    this.#viewMonth += delta;
-    if (this.#viewMonth > 11) { this.#viewMonth = 0; this.#viewYear++; }
-    if (this.#viewMonth < 0) { this.#viewMonth = 11; this.#viewYear--; }
-    this.#focusedDay = null;
-    this.#renderCalendar();
-  }
-
-  #selectDate(iso) {
-    this.value = iso;
-    this.syncValue(iso);
-    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
-    // Re-render grid to reflect new selection; keep popover open until user clicks outside.
-    if (this.open) this.#renderCalendar();
-  }
-
   #onClick = (e) => {
-    if (this.disabled) return;
-    if (this.#popover && e.composedPath().includes(this.#popover)) return;
-    this.open = !this.open;
-    if (this.open) {
-      const sel = parseISO(this.value);
-      if (sel) {
-        this.#viewYear = sel.getFullYear();
-        this.#viewMonth = sel.getMonth();
-        this.#focusedDay = sel.getDate();
-      } else {
-        const today = new Date();
-        this.#viewYear = today.getFullYear();
-        this.#viewMonth = today.getMonth();
-        this.#focusedDay = today.getDate();
+    if (this.disabled || this.readonly) return;
+    if (this.#popover && e.composedPath().includes(this.#popover)) {
+      // Footer button handling — Apply / Cancel semantics for explicit-
+      // commit flows when the consumer wires data-action attrs onto
+      // authored slot="footer" buttons.
+      const actionBtn = e.target.closest?.('[data-action]');
+      if (actionBtn && this.contains(actionBtn)) {
+        const action = actionBtn.dataset.action;
+        if (action === 'apply') {
+          this.#commitFromParts({
+            date: this.#pending?.date ?? this.#grid?.value ?? '',
+            time: this.#pending?.time ?? this.#timePane?.value ?? '',
+          });
+          this.#closeReason = 'apply';
+          this.open = false;
+        } else if (action === 'cancel') {
+          this.#pending = null;
+          this.#closeReason = 'cancel';
+          this.open = false;
+        }
       }
+      return;
+    }
+    if (this.open) {
+      this.#closeReason = 'outside';
+      this.open = false;
+    } else {
+      this.#openTrigger = 'click';
+      this.open = true;
     }
   };
 
   #onOutside = (e) => {
     if (!this.contains(e.target) && !(this.#popover && e.composedPath().includes(this.#popover))) {
+      this.#closeReason = 'outside';
       this.open = false;
     }
   };
 
+  // Only the OPEN/CLOSE affordance lives here now — day navigation and
+  // selection are the composed calendar-grid-ui's own keydown contract
+  // once focus is inside it (see the queueMicrotask in render()).
   #onKey = (e) => {
+    if (this.disabled || this.readonly) return;
     if (!this.open) {
       if (e.key === 'Enter' || e.key === ' ') {
         e.preventDefault();
+        this.#openTrigger = 'keyboard';
         this.open = true;
       }
       return;
@@ -306,44 +621,8 @@ export class UICalendarPicker extends UIFormElement {
 
     if (e.key === 'Escape') {
       e.preventDefault();
+      this.#closeReason = 'escape';
       this.open = false;
-      return;
-    }
-
-    if (e.key === 'Enter') {
-      e.preventDefault();
-      if (this.#focusedDay) {
-        const iso = toISO(this.#viewYear, this.#viewMonth, this.#focusedDay);
-        const date = new Date(this.#viewYear, this.#viewMonth, this.#focusedDay);
-        const minDate = parseISO(this.min);
-        const maxDate = parseISO(this.max);
-        if ((!minDate || date >= minDate) && (!maxDate || date <= maxDate)) {
-          this.#selectDate(iso);
-        }
-      }
-      return;
-    }
-
-    const arrows = { ArrowUp: -7, ArrowDown: 7, ArrowLeft: -1, ArrowRight: 1 };
-    if (arrows[e.key] !== undefined) {
-      e.preventDefault();
-      const daysInMonth = new Date(this.#viewYear, this.#viewMonth + 1, 0).getDate();
-      let day = (this.#focusedDay || 1) + arrows[e.key];
-
-      if (day < 1) {
-        this.#navigate(-1);
-        const prevDays = new Date(this.#viewYear, this.#viewMonth + 1, 0).getDate();
-        this.#focusedDay = prevDays + day;
-      } else if (day > daysInMonth) {
-        this.#navigate(1);
-        this.#focusedDay = day - daysInMonth;
-      } else {
-        this.#focusedDay = day;
-      }
-
-      this.#renderCalendar();
-      const focused = this.#popover?.querySelector('[data-focused]');
-      focused?.focus();
     }
   };
 
@@ -356,14 +635,28 @@ export class UICalendarPicker extends UIFormElement {
     this.removeEventListener('click', this.#onClick);
     this.removeEventListener('keydown', this.#onKey);
     document.removeEventListener('pointerdown', this.#onOutside);
-    if (this.#popover && this.#popoverClickBound) {
-      this.#popover.removeEventListener('click', this.#onPopoverClick);
+    if (this.#grid && this.#gridBound) {
+      this.#grid.removeEventListener('change', this.#onGridChange);
+    }
+    if (this.#timePane && this.#timePaneBound) {
+      this.#timePane.removeEventListener('change', this.#onTimePaneChange);
+      this.#timePane.removeEventListener('input', this.#onTimePaneInput);
+      this.#timePane.removeEventListener('invalid', this.#onPaneInvalid);
     }
-    this.#popoverClickBound = false;
+    this.#gridBound = false;
+    this.#timePaneBound = false;
     this.#anchorCleanup?.();
     this.#anchorCleanup = null;
     this.#popover?.hidePopover?.();
     this.#popover = null;
     this.#trigger = null;
+    this.#grid = null;
+    this.#divider = null;
+    this.#timePane = null;
+    this.#pending = null;
+    // Re-arm the closed→open transition gate — a reconnect while `open`
+    // was never cleared (e.g. moved in the DOM mid-open) must still be
+    // treated as a fresh open on the next render, not silently skipped.
+    this.#wasOpen = false;
   }
 }