stimeo-ui 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4f40e999f04533e49b382f7a5165c17b2338e8d520c702c34523843c12eff4c
-  data.tar.gz: 2bd4c18004fd4f92998513dd6a0d51975c7f9fcbe452fcef89477eb3f87edd7b
+  metadata.gz: dc8f7abf12a14555f6b1182d81844594d3bf86c772f115338d931e15eb35a43e
+  data.tar.gz: fee179d507f73e693b718e8563e3239d7a3fcad20d42d6db4624bdcbdf2a353c
 SHA512:
-  metadata.gz: 06ed197e53937fa086971d86c22d66efa4aed0f2accf14000046711be6aa73c3f486671c3912264a4ce5ca7c6da97a9836d7fe79c1d3ce106e1b368e5013f0d1
-  data.tar.gz: e49c3e2ccbc075def36be9d4e926d167fa4714cb66710389ad983ad7725f86e91d525fddfbb809090b4af09bc0cdaed44541466cb57391db53566119613f8863
+  metadata.gz: e68c6fd65748f2e637ddd8bd77364f74f4336549fdd2bb47803d5bd0e300c7838c0037850154d040f32aadb7ccab53879dc754acf8bbe99430ddedeb3b102b8f
+  data.tar.gz: 833febb4eb631e61d0d700e56a13cfb38fa59465757a4d0c5f9430a8f87967ef9a8cc993e3272922b4794ec88b9ab38c8244a1c7614a904cc1d539bc40cd3e81

data/CHANGELOG.md

@@ -7,6 +7,108 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 While the version is `0.x`, the public API (the `stimeo--*` data attributes) may
 change between releases.
 
+## [0.3.0] - 2026-08-09
+
+Minor release focused on consistent keyboard and selection behavior, resilient
+runtime DOM changes, and substantially stronger Inspector diagnostics. No
+controller, target, value, action, event, or package export was removed. The
+Inspector manifest advances from schema v5 to v8, so tools that read the raw
+manifest must accept the new schema and fields.
+
+### Upgrade notes
+
+- Run `stimeo check` against existing views before deploying. New structural
+  checks can report errors for incomplete optional target groups, missing
+  companion controllers, undeclared role-bearing targets, and invalid
+  cardinality. New ARIA checks can also add warnings without failing the command.
+- In RTL containers, horizontal arrow keys now follow logical inline direction
+  across composite widgets. LTR behavior is unchanged.
+- Slider, range-slider, and color-picker pointer/arrow mirroring remains opt-in:
+  set their new `logicalTrack` value only when the consuming CSS mirrors the
+  track in RTL.
+- calendar's `stimeo--calendar:monthchange` no longer fires while the grid
+  settles on its initial month, so code that ran from that first event must now
+  run once at initialization. Listeners that re-apply per-date `aria-disabled`
+  marks are the common case.
+
+### Added
+
+- breadcrumb: a public `update` action for reconciling collapsible state after
+  application-driven DOM changes.
+- tree-view: a public `toggle` action for explicitly expanding or collapsing an
+  item from application markup.
+- scrollspy: a `focusSection` value for opting into focus movement when a link
+  activates a section.
+- slider, range-slider, color-picker: the `logicalTrack` value described above.
+- Inspector schema v6-v8: conditional target requirements and the new
+  `missing-companion`, `undeclared-target`, `cardinality-violation`,
+  `forbidden-aria`, and `missing-conditional-target` diagnostics. Rules can now
+  depend on controller values, element/document conditions, contained targets,
+  and ARIA requirement severity.
+
+### Changed
+
+- accordion, carousel, calendar, combobox, command-palette, context-menu,
+  data-grid, date-range-picker, listbox, menu, menubar, multi-select,
+  navigation-menu, OTP, radio-group, roving, tabs, tags-input, time-picker,
+  toggle-group, toolbar, tree-view, and related horizontal controls now resolve
+  Left/Right behavior from the effective text direction. Sortable geometry also
+  follows logical inline direction.
+- Arrow-key handlers yield modified browser shortcuts, and composite handlers
+  yield events already consumed by a nested widget. IME composition continues to
+  take precedence over component shortcuts.
+- Selection widgets normalize controller-owned `aria-selected` state, preserve a
+  single active/selected item where the pattern requires one, and reconcile that
+  state when options are inserted, removed, or replaced at runtime.
+- menu and overflow-menu delegate item interaction from their containers, so
+  dynamically added items work without per-item actions. Existing action markup
+  remains compatible.
+- `aria-disabled="true"` items remain discoverable by composite keyboard
+  navigation while activation, expansion, and consumer actions are suppressed.
+- Outside pointer listeners for dismissible composites — click and context-menu
+  alike — run in the capture phase so nested application code cannot leave an
+  open layer stuck by stopping bubbling.
+- Inspector accessible-name diagnostics now follow ARIA's Required, Recommended,
+  and conditional levels instead of treating every role alike.
+
+### Fixed
+
+- combobox, command-palette, listbox, and multi-select no longer retain stale
+  active IDs, selection, chips, or hidden fields after Turbo morphs and runtime
+  target replacement. A disconnect/reconnect in the same task can no longer let
+  an old reconciliation microtask consume the fresh generation's pass.
+- breadcrumb fails open when its optional disclosure targets are incomplete and
+  restores items that leave the collapsible set instead of leaving them hidden.
+- menu, menubar, navigation-menu, overflow-menu, pagination, and tree-view now
+  recover focus consistently across empty lists, disabled fieldsets, hidden
+  ancestors, item banking, and runtime item removal.
+- toolbar restores its single tab stop when an enclosing `<fieldset>` is
+  re-enabled, so unlocking a form brings the group back into the Tab sequence.
+- multi-select keeps chip focus when the selection was made in an order other
+  than the option order. The chips are reconciled against the selected value set
+  rather than position by position, and their labels are paired by value.
+- overflow-menu measures items adopted from server-rendered overflow in the bar
+  rather than inside the closed menu, so an already-overflowed bar no longer
+  returns every item to the bar on first paint.
+- combobox commits a clicked option after its input target is removed instead of
+  throwing, matching the tolerance the popup already had for that state.
+- color-picker falls back to the per-channel range when a slider omits
+  `aria-valuemin` / `aria-valuemax`, instead of pinning the channel at zero.
+- calendar maintains exactly one roving tab stop while selection and available
+  days change.
+- calendar reports `monthchange` from the month it paints, so a malformed
+  `month` value can no longer put a raw non-`YYYY-MM` string in `detail.month`.
+  The report is driven by the repaint rather than by the `month` value, so a
+  fallback month moved by `selected` or by selecting a neighbouring month's cell
+  is announced as it happens instead of arriving on a later repaint. Re-applying
+  the same month, as a Turbo cache restore does, stays silent.
+- scrollspy re-evaluates links and sections after every supported entry path;
+  intersection-based controllers align fallback thresholds, hidden-layout
+  handling, and reduced-motion behavior.
+- `stimeo catalog --json` and large `stimeo check --json` reports are no longer
+  truncated when stdout is piped; the CLI now lets buffered output flush before
+  exiting, and the build audit exercises the real piped catalog.
+
 ## [0.2.1] - 2026-07-26
 
 Patch release from a review of the disclosure and layout components, plus a
@@ -234,6 +336,8 @@ Initial public alpha: 101 behavior-only, accessible Stimulus controllers driven
 by `data-*` attributes, shipping no CSS. Published to npm (with provenance) and
 RubyGems.
 
+[0.3.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.3.0
+[0.2.1]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.2.1
 [0.2.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.2.0
 [0.1.0-beta.3]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.1.0-beta.3
 [0.1.0-beta.2]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.1.0-beta.2

data/dist/controllers/accordion_controller.js

@@ -1,5 +1,13 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/accordion_controller.ts
+
+// src/utils/arrow_step.ts
+function isReservedArrowChord(event, allow = []) {
+  if (!event.key.startsWith("Arrow")) return false;
+  return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
+}
+
 // src/controllers/accordion_controller.ts
 var AccordionController = class extends Controller {
   static targets = ["trigger", "panel"];
@@ -39,6 +47,8 @@ var AccordionController = class extends Controller {
    * `.focus()` lands on nothing and navigation appears to stall.
    */
   onKeydown(event) {
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
     const current = event.currentTarget;
     if (this.triggerTargets.indexOf(current) === -1) return;
     const navigable = this.triggerTargets.filter((trigger) => trigger.closest("[hidden]") === null);

data/dist/controllers/breadcrumb_controller.js

@@ -2,6 +2,61 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/breadcrumb_controller.ts
 
+// src/utils/blur_deferral.ts
+var BlurDeferral = class {
+  /** Elements currently holding an update back, mapped to their `blur` listener. */
+  #pending = /* @__PURE__ */ new Map();
+  /** Called after a pending element blurs and has been detached. */
+  #onRelease;
+  /** @param onRelease - Invoked once `element` actually blurs; never on `release`. */
+  constructor(onRelease) {
+    this.#onRelease = onRelease;
+  }
+  /** Number of elements currently holding an update back. */
+  get size() {
+    return this.#pending.size;
+  }
+  /** Snapshot of the pending elements, safe to iterate while releasing them. */
+  get elements() {
+    return [...this.#pending.keys()];
+  }
+  /** Whether `element` is currently holding an update back. */
+  has(element) {
+    return this.#pending.has(element);
+  }
+  /** Holds an update back until `element` blurs. Idempotent (no stacked listeners). */
+  defer(element) {
+    if (this.#pending.has(element)) return;
+    const onBlur = () => {
+      this.#detach(element);
+      this.#onRelease(element);
+    };
+    this.#pending.set(element, onBlur);
+    element.addEventListener("blur", onBlur);
+  }
+  /** Defers `element` as the only pending entry, cancelling any others. */
+  deferOnly(element) {
+    for (const pending of this.elements) {
+      if (pending !== element) this.#detach(pending);
+    }
+    this.defer(element);
+  }
+  /** Cancels `element`'s deferral without completing it; no-ops when not pending. */
+  release(element) {
+    this.#detach(element);
+  }
+  /** Cancels every deferral without completing any of them. */
+  releaseAll() {
+    for (const element of this.elements) this.#detach(element);
+  }
+  /** Removes the `blur` listener for `element` and forgets it. */
+  #detach(element) {
+    const onBlur = this.#pending.get(element);
+    if (onBlur) element.removeEventListener("blur", onBlur);
+    this.#pending.delete(element);
+  }
+};
+
 // src/utils/layout_observer.ts
 var LayoutObserver = class {
   #callback;
@@ -59,37 +114,152 @@ var LayoutObserver = class {
 };
 
 // src/controllers/breadcrumb_controller.ts
+var OVERFLOW_EPSILON = 1;
 var BreadcrumbController = class extends Controller {
   static targets = ["list", "collapsible", "ellipsis", "trigger"];
-  static actions = ["toggle"];
+  static actions = ["toggle", "update"];
   static events = ["toggle"];
+  /** Guards target callbacks that can fire outside the connected window. */
+  #connected = false;
   /** Whether the trail currently overflows its container. */
   #overflowing = false;
   /** Whether the user has expanded the collapsed items via the disclosure. */
   #expanded = false;
-  #layout = new LayoutObserver(() => this.#update());
+  /** The list element currently observed (resize + mutations), if any. */
+  #observedList = null;
+  #listMutations = null;
+  #layout = new LayoutObserver(() => this.update());
+  #onListMutation = () => {
+    this.update();
+  };
+  /** Holds the ellipsis hide back while it contains focus; re-renders on blur. */
+  #deferredHide = new BlurDeferral(() => {
+    this.#render();
+  });
   /** Starts observing for overflow and renders the initial state. */
   connect() {
-    if (this.hasListTarget) this.#layout.observe(this.listTarget);
+    this.#connected = true;
+    this.#expanded = this.#initialExpanded();
     this.#layout.observeViewport();
-    this.#update();
+    this.#syncListObservation();
+    this.update();
   }
-  /** Releases the resize observation (Turbo navigation included). */
+  /** Releases the resize/mutation observation (Turbo navigation included). */
   disconnect() {
+    this.#connected = false;
+    this.#deferredHide.releaseAll();
+    this.#stopObservingList();
     this.#layout.disconnect();
   }
-  /** Expands or re-collapses the trail and dispatches `toggle`. */
+  listTargetConnected() {
+    this.#resync();
+  }
+  listTargetDisconnected() {
+    this.#resync();
+  }
+  collapsibleTargetConnected() {
+    this.#resync();
+  }
+  /**
+   * Re-measures when the disclosure set gains or loses a member. The set is a
+   * precondition for collapsing at all, so it needs the same watching the list
+   * and items get: without these callbacks a swap that breaks or completes the
+   * set would only take effect at the next resize or list mutation, which may
+   * never come.
+   */
+  ellipsisTargetConnected() {
+    this.#resync();
+  }
+  ellipsisTargetDisconnected() {
+    this.#resync();
+  }
+  triggerTargetConnected() {
+    this.#resync();
+  }
+  triggerTargetDisconnected() {
+    this.#resync();
+  }
+  /**
+   * Hands `hidden` back when an element stops being a `collapsible` target.
+   *
+   * The marker is the source of truth for what may be collapsed, so an element
+   * that loses it while the controller is live is an always-visible item again —
+   * and `#render` only walks the *current* targets, so nothing else would ever
+   * clear the `hidden` this controller put there.
+   *
+   * The `#connected` guard is load-bearing, not defensive. Stimulus fires this
+   * callback for **every** target during teardown as well (`Context.disconnect()`
+   * stops the target observer after `disconnect()` has run), and there the
+   * collapsed DOM must survive untouched so Turbo's cache restores the trail in
+   * the state the user left it (see the ownership note in {@link BreadcrumbController}).
+   *
+   * @param element - the element that just left the `collapsible` target set
+   */
+  collapsibleTargetDisconnected(element) {
+    if (this.#connected) element.hidden = false;
+    this.#resync();
+  }
+  /**
+   * Expands or re-collapses the trail and dispatches `toggle`.
+   *
+   * No-op while the trail fits: there is nothing collapsed to reveal, and the
+   * (hidden) trigger would otherwise keep a stale `aria-expanded="true"` that
+   * surfaces pre-expanded the next time the trail overflows. No event is
+   * dispatched in that case.
+   */
   toggle() {
+    if (!this.#connected || !this.#overflowing) return;
     this.#expanded = !this.#expanded;
     this.#render();
     this.dispatch("toggle", { detail: { expanded: this.#expanded } });
   }
-  /** Re-measures overflow and re-renders (e.g. on resize). */
-  #update() {
+  /**
+   * Re-measures overflow and re-renders. Wired to resizes and list mutations;
+   * exposed as an action so consumers can re-measure after a change the
+   * observers cannot see (e.g. a web font swap that only alters text width).
+   */
+  update() {
+    if (!this.#connected) return;
     this.#overflowing = this.#measureOverflow();
     if (!this.#overflowing) this.#expanded = false;
     this.#render();
   }
+  /** Re-attaches the list observation (targets may have been swapped) and re-measures. */
+  #resync() {
+    if (!this.#connected) return;
+    this.#syncListObservation();
+    this.update();
+  }
+  /** Reads the expanded state back from its DOM home (the trigger's `aria-expanded`). */
+  #initialExpanded() {
+    return this.hasTriggerTarget && this.triggerTarget.getAttribute("aria-expanded") === "true";
+  }
+  /**
+   * Points the resize + mutation observation at the current `list` target.
+   *
+   * The list is re-resolved rather than captured at connect so a target swapped
+   * at runtime (Turbo Stream replacement of the `<ol>`) is observed too. Only
+   * `childList` / `subtree` / `characterData` are watched — deliberately **not**
+   * `attributes`, which the controller's own `hidden` writes would re-trigger.
+   */
+  #syncListObservation() {
+    const next = this.hasListTarget ? this.listTarget : null;
+    if (next === this.#observedList) return;
+    this.#stopObservingList();
+    if (!next) return;
+    this.#observedList = next;
+    this.#layout.observe(next);
+    if (typeof MutationObserver !== "undefined") {
+      this.#listMutations = new MutationObserver(this.#onListMutation);
+      this.#listMutations.observe(next, { childList: true, subtree: true, characterData: true });
+    }
+  }
+  #stopObservingList() {
+    if (this.#observedList) this.#layout.unobserve(this.#observedList);
+    this.#observedList = null;
+    this.#listMutations?.disconnect();
+    this.#listMutations = null;
+  }
   /**
    * Measures overflow against the **fully expanded** layout so hiding items does
    * not make the condition oscillate. Reveals every item, then compares the list's
@@ -100,21 +270,63 @@ var BreadcrumbController = class extends Controller {
    * check is independent of any padding/border on the host — comparing against the
    * host's `clientWidth` would over-report the available space by its padding and
    * miss real overflow in a padded container.
+   *
+   * With no `collapsible` items there is nothing to collapse, so the trail is
+   * never reported as overflowing (which also keeps the disclosure out of the
+   * tab order — a button controlling nothing).
+   *
+   * The full disclosure set is a precondition: collapsing without an `ellipsis`
+   * *and* a `trigger` would hide items behind a control that does not exist, so
+   * an incomplete set reports "not overflowing" and `#render` degrades the trail
+   * to a plain breadcrumb. Losing layout is recoverable; losing the path is not.
    */
   #measureOverflow() {
-    if (!this.hasListTarget) return false;
+    if (!this.hasListTarget || this.collapsibleTargets.length === 0) return false;
+    if (!this.hasEllipsisTarget || !this.hasTriggerTarget) return false;
     for (const item of this.collapsibleTargets) item.hidden = false;
-    if (this.hasEllipsisTarget) this.ellipsisTarget.hidden = true;
-    return this.listTarget.scrollWidth > this.listTarget.clientWidth;
+    this.ellipsisTarget.hidden = true;
+    return this.listTarget.scrollWidth > this.listTarget.clientWidth + OVERFLOW_EPSILON;
   }
   /** Applies the collapsed/expanded state to the items, ellipsis, and trigger. */
   #render() {
     const collapsed = this.#overflowing && !this.#expanded;
+    const showEllipsis = this.#overflowing && this.collapsibleTargets.length > 0;
+    const rescueFocus = collapsed && this.hasTriggerTarget && this.collapsibleTargets.some((i) => this.#holdsFocus(i));
     for (const item of this.collapsibleTargets) item.hidden = collapsed;
-    if (this.hasEllipsisTarget) this.ellipsisTarget.hidden = !this.#overflowing;
+    if (this.hasEllipsisTarget) this.#applyEllipsisVisibility(showEllipsis);
     if (this.hasTriggerTarget) {
-      this.triggerTarget.setAttribute("aria-expanded", this.#expanded ? "true" : "false");
+      const expanded = this.#overflowing && this.#expanded;
+      this.triggerTarget.setAttribute("aria-expanded", expanded ? "true" : "false");
+    }
+    if (rescueFocus) this.triggerTarget.focus();
+  }
+  /**
+   * Shows or hides the ellipsis item, deferring a hide that would blur the user.
+   *
+   * Hiding the element that currently holds focus drops focus to `<body>`, so the
+   * hide waits for that element's `blur` and is re-applied then (the shared
+   * `BlurDeferral` registry).
+   */
+  #applyEllipsisVisibility(show) {
+    const ellipsis = this.ellipsisTarget;
+    if (show) {
+      this.#deferredHide.releaseAll();
+      ellipsis.hidden = false;
+      return;
+    }
+    const active = document.activeElement;
+    if (active instanceof HTMLElement && ellipsis.contains(active)) {
+      ellipsis.hidden = false;
+      this.#deferredHide.deferOnly(active);
+      return;
     }
+    this.#deferredHide.releaseAll();
+    ellipsis.hidden = true;
+  }
+  /** Whether `element` contains (or is) the currently focused element. */
+  #holdsFocus(element) {
+    const active = document.activeElement;
+    return active instanceof HTMLElement && element.contains(active);
   }
 };
 

data/dist/controllers/calendar_controller.js

@@ -2,6 +2,22 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/calendar_controller.ts
 
+// src/utils/logical_scroll.ts
+function isRtl(element) {
+  return window.getComputedStyle(element).direction === "rtl";
+}
+
+// src/utils/arrow_step.ts
+function logicalArrowKey(key, element) {
+  if (key !== "ArrowRight" && key !== "ArrowLeft") return key;
+  if (!isRtl(element)) return key;
+  return key === "ArrowRight" ? "ArrowLeft" : "ArrowRight";
+}
+function isReservedArrowChord(event, allow = []) {
+  if (!event.key.startsWith("Arrow")) return false;
+  return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
+}
+
 // src/utils/dates.ts
 function toISODateString(date) {
   const year = date.getFullYear();
@@ -32,6 +48,9 @@ function parseISOMonthString(monthStr) {
   if (month < 1 || month > 12) return null;
   return { year: Number(y), month };
 }
+function toISOMonthString(date) {
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}`;
+}
 
 // src/utils/safe_timeout.ts
 var TimerRegistry = class {
@@ -87,6 +106,7 @@ var SafeTimeout = class extends TimerRegistry {
 };
 
 // src/controllers/calendar_controller.ts
+var OWNED_DISABLED = "data-stimeo--calendar-owns-disabled";
 var CalendarController = class extends Controller {
   static targets = ["label", "grid", "day"];
   static values = {
@@ -107,6 +127,13 @@ var CalendarController = class extends Controller {
    * controller never steals focus after the element leaves the DOM (Turbo).
    */
   #focusTimer = new SafeTimeout();
+  /**
+   * The painted month the last `monthchange` reported, or `null` before the first
+   * paint. Settling on the initial month — whether it comes from the attribute or
+   * is derived here — is the grid describing itself, not a navigation, so it must
+   * not reach a listener that refetches inventory or pushes history.
+   */
+  #announcedMonth = null;
   connect() {
     if (!this.monthValue) {
       const today = /* @__PURE__ */ new Date();
@@ -129,7 +156,6 @@ var CalendarController = class extends Controller {
     if (!this.monthValue) return;
     this.#syncFocusedDateWithMonth();
     this.render();
-    this.dispatch("monthchange", { detail: { month: this.monthValue } });
   }
   /**
    * Stimulus lifecycle callback triggered automatically when the selectedValue changes.
@@ -156,25 +182,25 @@ var CalendarController = class extends Controller {
   }
   /** Handles day selection when a gridcell is clicked. */
   selectByClick(event) {
-    const target = event.target;
-    if (!target) return;
-    const dayElement = target.closest("[data-stimeo--calendar-target='day']");
+    const dayElement = event.target?.closest(
+      "[data-stimeo--calendar-target='day']"
+    );
     if (!dayElement) return;
     this.selectDayElement(dayElement);
   }
   /** Handles grid cell keyboard navigation and triggers selection. */
   onKeydown(event) {
-    const target = event.target;
-    if (!target) return;
-    const dayElement = target.closest("[data-stimeo--calendar-target='day']");
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
+    const dayElement = event.target?.closest(
+      "[data-stimeo--calendar-target='day']"
+    );
     if (!dayElement) return;
-    const dateStr = dayElement.getAttribute("data-date");
-    if (!dateStr) return;
-    const date = parseISODateString(dateStr);
+    const date = parseISODateString(dayElement.getAttribute("data-date") ?? "");
     if (!date) return;
     let handled = true;
     let nextDate = new Date(date);
-    switch (event.key) {
+    switch (logicalArrowKey(event.key, this.element)) {
       case "ArrowLeft":
         nextDate.setDate(nextDate.getDate() - 1);
         break;
@@ -209,6 +235,10 @@ var CalendarController = class extends Controller {
         break;
       case "t":
       case "T": {
+        if (event.ctrlKey || event.metaKey || event.altKey) {
+          handled = false;
+          break;
+        }
         const now = /* @__PURE__ */ new Date();
         nextDate = new Date(now.getFullYear(), now.getMonth(), now.getDate());
         break;
@@ -227,25 +257,50 @@ var CalendarController = class extends Controller {
       this.#focusAndNavigateToDate(nextDate);
     }
   }
-  /** Renders the grid days and updates the month/year label. */
-  render() {
+  /**
+   * First day of the month the grid paints: the `month` Value when it parses,
+   * otherwise the focused date's month.
+   *
+   * A malformed `month` falls back instead of stopping the paint: every cell
+   * keeps its `aria-selected` and the grid keeps its tab stop, so a Value typo
+   * still leaves the grid reachable by Tab and the author can see what they
+   * typed. Every consumer of "which month is on screen" reads it from here, so
+   * the paint and the `monthchange` report cannot name different months.
+   */
+  #paintedMonthStart() {
     const monthInfo = parseISOMonthString(this.monthValue);
-    if (!monthInfo) return;
-    const { year, month } = monthInfo;
+    return monthInfo ? new Date(monthInfo.year, monthInfo.month - 1, 1) : new Date(this.focusedDate.getFullYear(), this.focusedDate.getMonth(), 1);
+  }
+  /**
+   * Renders the grid days and updates the month/year label, then reports the
+   * painted month once it differs from the one already announced.
+   *
+   * The report belongs to the paint, not to the `month` Value: the Value is only
+   * one of the things that decide the month on screen. While a malformed `month`
+   * falls back, changing `selected` and selecting a neighbouring month's cell
+   * move the painted month too, and both repaint from here. Reading the report
+   * off the paint keeps the event naming the month the grid shows, in the
+   * `YYYY-MM` the detail contract promises, whichever route repainted.
+   */
+  render() {
+    const monthStart = this.#paintedMonthStart();
+    const year = monthStart.getFullYear();
+    const month = monthStart.getMonth() + 1;
     if (this.hasLabelTarget) {
       const lang = document.documentElement.lang || "en";
-      const labelDate = new Date(year, month - 1, 1);
       const formatter = new Intl.DateTimeFormat(lang, { month: "long", year: "numeric" });
-      this.labelTarget.textContent = formatter.format(labelDate);
+      this.labelTarget.textContent = formatter.format(monthStart);
     }
     const days = this.#calculateGridDays(year, month);
     const dayElements = this.dayTargets;
-    for (let i = 0; i < 42; i++) {
-      const el = dayElements[i];
+    for (const [index, date] of days.entries()) {
+      const el = dayElements[index];
       if (!el) continue;
-      const date = days[i];
-      if (!date) continue;
       const dateStr = toISODateString(date);
+      if (el.getAttribute("data-date") !== dateStr) {
+        el.removeAttribute("aria-disabled");
+        el.removeAttribute(OWNED_DISABLED);
+      }
       el.setAttribute("data-date", dateStr);
       el.textContent = String(date.getDate());
       const isOutside = date.getFullYear() !== year || date.getMonth() !== month - 1;
@@ -258,11 +313,23 @@ var CalendarController = class extends Controller {
       el.setAttribute("tabindex", isFocused ? "0" : "-1");
       const isDisabled = this.#isDateOutOfBounds(dateStr);
       if (isDisabled) {
+        if (!el.hasAttribute("aria-disabled")) el.setAttribute(OWNED_DISABLED, "");
         el.setAttribute("aria-disabled", "true");
-      } else {
+      } else if (el.hasAttribute(OWNED_DISABLED)) {
         el.removeAttribute("aria-disabled");
+        el.removeAttribute(OWNED_DISABLED);
       }
     }
+    if (!dayElements.some((el) => el.getAttribute("tabindex") === "0")) {
+      const fallback = dayElements.find((el) => el.getAttribute("data-outside") === "false") ?? dayElements[0];
+      fallback?.setAttribute("tabindex", "0");
+    }
+    const painted = toISOMonthString(monthStart);
+    const previous = this.#announcedMonth;
+    this.#announcedMonth = painted;
+    if (previous !== null && previous !== painted) {
+      this.dispatch("monthchange", { detail: { month: painted } });
+    }
   }
   selectDayElement(dayElement) {
     if (dayElement.getAttribute("aria-disabled") === "true") return;