stimeo-ui 0.2.1 → 0.4.0

data/dist/controllers/listbox_controller.js

@@ -2,6 +2,45 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/listbox_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/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
 // src/utils/option_scroll.ts
 function scrollOptionIntoView(list, option) {
   if (list.scrollHeight <= list.clientHeight) return;
@@ -67,27 +106,135 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/typeahead.ts
+var TYPEAHEAD_RESET_MS = 500;
+var Typeahead = class {
+  /** Timer registry for the pending idle reset; private so `reset()` is the only exit. */
+  #timers = new SafeTimeout();
+  /** Idle window before the query resets, in milliseconds. */
+  #resetMs;
+  /** The accumulated lowercase query, empty when idle. */
+  #query = "";
+  /** Id of the pending reset timer, `0` when none is scheduled. */
+  #timerId = 0;
+  /** @param options - Overrides for the idle window. */
+  constructor({ resetMs = TYPEAHEAD_RESET_MS } = {}) {
+    this.#resetMs = resetMs;
+  }
+  /** The query a search would currently run with; empty while idle. */
+  get query() {
+    return this.#query;
+  }
+  /**
+   * Folds `key` into the query, restarts the idle window, and returns the query to
+   * search with. A repeated character collapses the query to that one character.
+   */
+  push(key) {
+    const char = key.toLowerCase();
+    const repeated = this.#query.length > 0 && [...this.#query].every((c) => c === char);
+    this.#query = repeated ? char : this.#query + char;
+    this.#timers.clear(this.#timerId);
+    this.#timerId = this.#timers.set(() => this.reset(), this.#resetMs);
+    return this.#query;
+  }
+  /** Clears the query and cancels the pending idle reset. */
+  reset() {
+    this.#query = "";
+    this.#timers.clear(this.#timerId);
+    this.#timerId = 0;
+  }
+};
+function isTypeaheadKey(event) {
+  return event.key.length === 1 && event.key !== " " && !event.ctrlKey && !event.metaKey && !event.altKey && !event.isComposing;
+}
+function typeaheadLabel(element, fallbackText) {
+  const label = element.getAttribute("aria-label")?.trim();
+  if (label) return label.toLowerCase();
+  const text = element.textContent ?? "";
+  return text.trim().toLowerCase();
+}
+function findTypeaheadMatch(items, from, query, label = (item) => typeaheadLabel(item)) {
+  if (query === "") return -1;
+  const count = items.length;
+  for (let step = 1; step <= count; step += 1) {
+    const index = ((from + step) % count + count) % count;
+    const candidate = items[index];
+    if (candidate && label(candidate).startsWith(query)) return index;
+  }
+  return -1;
+}
+
 // src/controllers/listbox_controller.ts
-var TYPEAHEAD_TIMEOUT = 500;
 var ListboxController = class extends Controller {
   static targets = ["trigger", "value", "list", "option", "field"];
   static actions = ["close", "onTriggerKeydown", "open", "select", "toggle"];
   static events = ["change"];
-  /** Index of the active option, or -1 when none is active. */
-  #activeIndex = -1;
-  /** Accumulated typeahead query, reset after {@link TYPEAHEAD_TIMEOUT} ms. */
-  #typeahead = "";
-  #typeaheadTimer = 0;
-  #timers = new SafeTimeout();
-  /** Starts closed and registers the outside-click listener. */
+  /** Stable ID of the active option; DOM targets are resolved afresh before use. */
+  #activeId = null;
+  /** Target ID order captured while an option is active, used only for removal fallback. */
+  #activeOrder = [];
+  #connected = false;
+  /** Collapses one mutation batch of target callbacks into a single pass. */
+  #reconcile = new MicrotaskCoalescer(() => this.#reconcileActive());
+  /** Accumulated typeahead query and its idle-reset timer. */
+  #typeahead = new Typeahead();
+  /** Establishes the ARIA baseline, starts closed, and listens for outside clicks. */
   connect() {
+    this.#normalizeSelection();
     this.close();
-    document.addEventListener("click", this.#onOutsideClick);
+    document.addEventListener("click", this.#onOutsideClick, true);
+    this.#connected = true;
+    this.#reconcile.activate();
+  }
+  /**
+   * Establishes an inactive baseline for a late option, re-resolves active
+   * identity, and re-applies the selection baseline.
+   */
+  optionTargetConnected(option) {
+    option.removeAttribute("data-active");
+    if (!this.#connected) return;
+    this.#normalizeSelection();
+    this.#queueOptionReconciliation();
+  }
+  /** Removes controller-owned active state and reconciles the surviving targets. */
+  optionTargetDisconnected(option) {
+    option.removeAttribute("data-active");
+    if (this.#connected) this.#queueOptionReconciliation();
+  }
+  /**
+   * Brings the authored DOM to the shape the APG requires, and derives the state
+   * that follows from the initial selection.
+   *
+   * Three things happen, and only these three — which option is chosen is the
+   * author's, and is never changed:
+   *
+   * 1. Every option gets an explicit value. An absent `aria-selected` means "not
+   *    selectable" in ARIA, so a forgotten attribute hides a selectable option
+   *    from assistive technology.
+   * 2. At most one stays `true`. The first in DOM order wins, since that is the
+   *    only deterministic reading of "which one did the author mean".
+   * 3. The trigger label and the hidden field are derived from that selection.
+   *    Without this the widget announces a choice it does not submit: the popup
+   *    says "Banana", the trigger still says "Choose…", and the form posts "".
+   *
+   * No `change` fires — nothing changed, this is the initial state being told
+   * properly. The scan is the `option` target set: a `role="option"` without the
+   * target is outside the contract and is neither counted nor written.
+   */
+  #normalizeSelection() {
+    const options = this.optionTargets;
+    const selected = options.find((option) => option.getAttribute("aria-selected") === "true");
+    for (const option of options) {
+      option.setAttribute("aria-selected", option === selected ? "true" : "false");
+    }
+    if (selected) this.#applySelection(selected);
   }
   /** Removes the document listener and clears the typeahead timer. */
   disconnect() {
-    document.removeEventListener("click", this.#onOutsideClick);
-    this.#timers.clearAll();
+    this.#connected = false;
+    this.#reconcile.cancel();
+    document.removeEventListener("click", this.#onOutsideClick, true);
+    this.#typeahead.reset();
   }
   /**
    * Toggles the list on a real mouse click. Keyboard activation of the
@@ -102,9 +249,14 @@ var ListboxController = class extends Controller {
       this.close();
     }
   }
-  /** Routes trigger keyboard interaction per the APG select-only model. */
+  /** Yields claimed keys; otherwise routes the APG select-only keyboard model. */
   onTriggerKeydown(event) {
-    const length = this.optionTargets.length;
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
+    if (!this.#isClosed) this.#reconcileActive();
+    const options = this.optionTargets;
+    const length = options.length;
+    const activeIndex = this.#findActiveIndex(options);
     if (this.#isClosed) {
       switch (event.key) {
         case "Enter":
@@ -123,13 +275,11 @@ var ListboxController = class extends Controller {
     switch (event.key) {
       case "ArrowDown":
         event.preventDefault();
-        this.#setActive(this.#activeIndex < 0 ? 0 : (this.#activeIndex + 1) % length);
+        this.#setActive(activeIndex < 0 ? 0 : (activeIndex + 1) % length);
         break;
       case "ArrowUp":
         event.preventDefault();
-        this.#setActive(
-          this.#activeIndex < 0 ? length - 1 : (this.#activeIndex - 1 + length) % length
-        );
+        this.#setActive(activeIndex < 0 ? length - 1 : (activeIndex - 1 + length) % length);
         break;
       case "Home":
         event.preventDefault();
@@ -145,7 +295,7 @@ var ListboxController = class extends Controller {
         this.#commitActive();
         break;
       case "Escape":
-        if (event.defaultPrevented || event.isComposing) break;
+        if (event.isComposing) break;
         event.preventDefault();
         this.close();
         this.triggerTarget.focus();
@@ -154,9 +304,9 @@ var ListboxController = class extends Controller {
         this.close();
         break;
       default:
-        if (this.#isPrintable(event)) {
+        if (isTypeaheadKey(event)) {
           event.preventDefault();
-          this.#typeaheadTo(event.key);
+          this.#typeaheadTo(options, activeIndex, event.key);
         }
         break;
     }
@@ -164,7 +314,7 @@ var ListboxController = class extends Controller {
   /** Selects the clicked option and closes, returning focus to the trigger. */
   select(event) {
     const option = event.currentTarget.closest('[role="option"]');
-    if (!option) return;
+    if (!option || !this.optionTargets.includes(option)) return;
     this.#selectOption(option);
     this.close();
     this.triggerTarget.focus();
@@ -189,28 +339,41 @@ var ListboxController = class extends Controller {
     this.listTarget.hidden = true;
     this.triggerTarget.setAttribute("aria-expanded", "false");
     this.#setActive(-1);
-    this.#resetTypeahead();
+    this.#typeahead.reset();
   }
   /** Commits the active option (keyboard) and closes, returning focus. */
   #commitActive() {
-    const option = this.#activeIndex < 0 ? void 0 : this.optionTargets[this.#activeIndex];
+    this.#reconcileActive();
+    const options = this.optionTargets;
+    const activeIndex = this.#findActiveIndex(options);
+    const option = activeIndex < 0 ? void 0 : options[activeIndex];
     if (option) this.#selectOption(option);
     this.close();
     this.triggerTarget.focus();
   }
   /** Applies selection: `aria-selected`, trigger label, hidden field, `change`. */
   #selectOption(option) {
+    const { value, fieldChanged } = this.#applySelection(option);
+    if (fieldChanged) {
+      this.fieldTarget.dispatchEvent(new Event("change", { bubbles: true }));
+    }
+    this.dispatch("change", { detail: { value, option } });
+  }
+  /**
+   * Writes `option` into `aria-selected`, the trigger label and the hidden field.
+   * Emits nothing — {@link #normalizeSelection} reuses this at connect, where the
+   * state is being described rather than changed.
+   */
+  #applySelection(option) {
     for (const candidate of this.optionTargets) {
       candidate.setAttribute("aria-selected", candidate === option ? "true" : "false");
     }
     const label = (option.textContent ?? "").trim();
     const value = option.dataset.value ?? label;
     if (this.hasValueTarget) this.valueTarget.textContent = label;
-    if (this.hasFieldTarget && this.fieldTarget.value !== value) {
-      this.fieldTarget.value = value;
-      this.fieldTarget.dispatchEvent(new Event("change", { bubbles: true }));
-    }
-    this.dispatch("change", { detail: { value, option } });
+    const fieldChanged = this.hasFieldTarget && this.fieldTarget.value !== value;
+    if (fieldChanged) this.fieldTarget.value = value;
+    return { value, fieldChanged };
   }
   /**
    * Marks the option at `index` active via `data-active` and the trigger's
@@ -218,47 +381,88 @@ var ListboxController = class extends Controller {
    * set to empty, per the APG).
    */
   #setActive(index) {
-    this.#activeIndex = index;
-    const active = index < 0 ? null : this.optionTargets[index];
-    for (const option of this.optionTargets) {
+    const options = this.optionTargets;
+    const active = index < 0 ? null : options[index] ?? null;
+    for (const option of options) {
+      const marked = option.hasAttribute("data-active");
       if (option === active) {
-        option.setAttribute("data-active", "");
-      } else {
+        if (!marked) option.setAttribute("data-active", "");
+      } else if (marked) {
         option.removeAttribute("data-active");
       }
     }
     if (active?.id) {
+      this.#activeId = active.id;
       this.triggerTarget.setAttribute("aria-activedescendant", active.id);
     } else {
+      this.#activeId = null;
       this.triggerTarget.removeAttribute("aria-activedescendant");
     }
+    this.#activeOrder = active ? options.map((option) => option.id).filter(Boolean) : [];
     if (active && this.hasListTarget) scrollOptionIntoView(this.listTarget, active);
   }
-  /** Appends a character to the typeahead query and activates the first match. */
-  #typeaheadTo(char) {
-    this.#timers.clear(this.#typeaheadTimer);
-    this.#typeahead += char.toLowerCase();
-    this.#typeaheadTimer = this.#timers.set(() => {
-      this.#typeahead = "";
-    }, TYPEAHEAD_TIMEOUT);
-    const index = this.optionTargets.findIndex(
-      (option) => (option.textContent ?? "").trim().toLowerCase().startsWith(this.#typeahead)
-    );
-    if (index !== -1) this.#setActive(index);
+  /** Resolves active state against the current target collection. */
+  #reconcileActive() {
+    if (!this.hasTriggerTarget || this.#isClosed) {
+      if (this.hasTriggerTarget) this.#setActive(-1);
+      return;
+    }
+    const options = this.optionTargets;
+    const currentIndex = this.#findActiveIndex(options);
+    if (currentIndex >= 0) {
+      const active = options[currentIndex] ?? null;
+      const marked = options.filter((option) => option.hasAttribute("data-active"));
+      const stateMatches = this.#activeId === (active?.id || null) && marked.length === 1 && marked[0] === active && this.triggerTarget.getAttribute("aria-activedescendant") === (active?.id || null);
+      if (stateMatches) {
+        this.#activeOrder = options.map((option) => option.id).filter(Boolean);
+      } else {
+        this.#setActive(currentIndex);
+      }
+      return;
+    }
+    const activeId = this.triggerTarget.getAttribute("aria-activedescendant") ?? this.#activeId;
+    this.#setActive(activeId ? this.#findFallbackIndex(options, activeId) : -1);
+  }
+  /** Finds the live target carrying the stable ID, or the active marker for an ID-less option. */
+  #findActiveIndex(options) {
+    const activeId = (this.hasTriggerTarget ? this.triggerTarget.getAttribute("aria-activedescendant") : null) ?? this.#activeId;
+    if (activeId) return options.findIndex((option) => option.id === activeId);
+    return options.findIndex((option) => option.hasAttribute("data-active"));
   }
-  /** Clears the typeahead query and its pending reset timer. */
-  #resetTypeahead() {
-    this.#timers.clear(this.#typeaheadTimer);
-    this.#typeahead = "";
+  /** Chooses a surviving former successor, then a former predecessor. */
+  #findFallbackIndex(options, activeId) {
+    const oldIndex = this.#activeOrder.indexOf(activeId);
+    if (oldIndex < 0) return -1;
+    const indexesById = new Map(options.map((option, index) => [option.id, index]));
+    for (let index = oldIndex + 1; index < this.#activeOrder.length; index += 1) {
+      const fallback = indexesById.get(this.#activeOrder[index] ?? "");
+      if (fallback !== void 0) return fallback;
+    }
+    for (let index = oldIndex - 1; index >= 0; index -= 1) {
+      const fallback = indexesById.get(this.#activeOrder[index] ?? "");
+      if (fallback !== void 0) return fallback;
+    }
+    return -1;
   }
-  /** Closes the list when a click lands outside the controller element. */
+  /** Coalesces all target callbacks from one MutationObserver batch. */
+  #queueOptionReconciliation() {
+    this.#reconcile.schedule();
+  }
+  /**
+   * Advances the typeahead query and activates the next matching option.
+   *
+   * The search resumes just after the active option so repeating a character
+   * cycles through the options starting with it, rather than re-activating the
+   * same first match on every press.
+   */
+  #typeaheadTo(options, activeIndex, char) {
+    const index = findTypeaheadMatch(options, activeIndex, this.#typeahead.push(char));
+    if (index !== -1) this.#setActive(index);
+  }
+  /** Closes on an outside click before an inside handler can detach its target. */
   #onOutsideClick = (event) => {
     if (!this.#isClosed && !this.element.contains(event.target)) this.close();
   };
-  /** Whether `event.key` is a single printable character (no modifier chord). */
-  #isPrintable(event) {
-    return event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey;
-  }
   /** Whether the list is currently hidden. */
   get #isClosed() {
     return !this.hasListTarget || this.listTarget.hidden !== false;

data/dist/controllers/local_time_controller.js

@@ -1,5 +1,40 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/local_time_controller.ts
+
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
 // src/controllers/local_time_controller.ts
 var STYLES = /* @__PURE__ */ new Set(["full", "long", "medium", "short"]);
 function toStyle(value) {
@@ -14,7 +49,53 @@ var LocalTimeController = class extends Controller {
     titleFormat: { type: String, default: "" }
   };
   static events = ["format"];
+  /** Collapses a morph that swaps several render inputs at once into one repaint. */
+  #resync = new MicrotaskCoalescer(() => this.#render());
+  /**
+   * Watches the one render input that is not a Value. Only `datetime` is filtered
+   * in, so the text and `title` this controller writes cannot re-enter the pass.
+   */
+  #datetimeWatch = new MutationObserver(() => {
+    this.#resync.schedule();
+  });
   connect() {
+    this.#resync.activate();
+    this.#datetimeWatch.observe(this.element, { attributeFilter: ["datetime"] });
+    this.#render();
+  }
+  disconnect() {
+    this.#resync.cancel();
+    this.#datetimeWatch.disconnect();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `locale` at runtime. */
+  localeValueChanged() {
+    this.#resync.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `timeZone` at runtime. */
+  timeZoneValueChanged() {
+    this.#resync.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `dateStyle` at runtime. */
+  dateStyleValueChanged() {
+    this.#resync.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `timeStyle` at runtime. */
+  timeStyleValueChanged() {
+    this.#resync.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `titleFormat` at runtime. */
+  titleFormatValueChanged() {
+    this.#resync.schedule();
+  }
+  /**
+   * Formats the instant in `datetime` against the current Values and writes it out.
+   *
+   * The `format` event rides with every pass, including a repaint a morph triggers:
+   * its condition is that formatting was applied, and a repaint applies it with a
+   * new result. A pass that cannot format writes nothing and emits nothing, so the
+   * authored absolute text stays as the fallback.
+   */
+  #render() {
     const date = this.#parse();
     if (date === null) return;
     const formatted = this.#applyFormat(date, this.dateStyleValue, this.timeStyleValue);
@@ -24,7 +105,10 @@ var LocalTimeController = class extends Controller {
     if (title !== null) this.element.setAttribute("title", title);
     this.dispatch("format", { detail: { formatted } });
   }
-  /** Parses the UTC `datetime` attribute into a {@link Date}, or `null`. */
+  /**
+   * Parses the UTC `datetime` attribute into a {@link Date}, or `null`. Whitespace
+   * around the attribute value is tolerated.
+   */
   #parse() {
     const raw = this.element.getAttribute("datetime");
     if (!raw) return null;
@@ -32,16 +116,26 @@ var LocalTimeController = class extends Controller {
     return Number.isNaN(ms) ? null : new Date(ms);
   }
   /**
-   * Reads a timezone-less date-time as UTC — the documented input contract —
-   * since `Date.parse` would otherwise interpret e.g. `"2026-06-08T12:30:00"` in
+   * Reads a timezone-less date-time as UTC — the input contract of this
+   * controller — since `Date.parse` would otherwise read `"2026-06-08T12:30:00"` in
    * the *runtime's* local zone, contradicting "the server emits UTC". Values that
    * already carry `Z` or a `±hh:mm` offset (and bare `YYYY-MM-DD` dates, already
    * parsed as UTC) are returned unchanged.
+   *
+   * HTML accepts a space where ISO 8601 wants `T`, and `Date.parse` of that form is
+   * left to each engine, so a whole value shaped that way is normalized to the `T`
+   * separator first. The pattern is anchored: a value trailing anything else — a
+   * zone word such as `"2026-06-08 12:30:00 UTC"` — is handed to `Date.parse` as
+   * authored instead of being turned into a string nothing can parse.
    */
   #asUtc(value) {
-    const hasTime = /T\d{2}:\d{2}/.test(value);
-    const hasZone = /(Z|[+-]\d{2}:?\d{2})$/.test(value);
-    return hasTime && !hasZone ? `${value}Z` : value;
+    const isoLike = value.replace(
+      /^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)$/,
+      "$1T$2"
+    );
+    const hasTime = /T\d{2}:\d{2}/.test(isoLike);
+    const hasZone = /(Z|[+-]\d{2}:?\d{2})$/.test(isoLike);
+    return hasTime && !hasZone ? `${isoLike}Z` : isoLike;
   }
   /**
    * Builds the optional detailed `title`. `titleFormat` is an `Intl` style
@@ -70,9 +164,9 @@ var LocalTimeController = class extends Controller {
       return null;
     }
   }
-  /** Locale precedence: the value, then the element's `lang`, then the document's. */
+  /** Locale precedence: the value, then the nearest `lang` up the ancestor chain. */
   get #locale() {
-    return this.localeValue || this.element.lang || document.documentElement.lang || void 0;
+    return this.localeValue || this.element.closest("[lang]")?.getAttribute("lang") || void 0;
   }
 };