stimeo-ui 0.2.0 → 0.3.0

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;