stimeo-ui 0.1.0-alpha.1

package/dist/controllers/listbox_controller.js

@@ -0,0 +1,256 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/listbox_controller.ts
+
+// src/utils/safe_timeout.ts
+var TimerRegistry = class {
+  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
+  ids = /* @__PURE__ */ new Set();
+  /**
+   * Cancels a single tracked timer.
+   *
+   * No-ops if the id is unknown (already cleared, fired, or never owned by this
+   * registry), so callers can clear defensively without guarding.
+   */
+  clear(id) {
+    if (this.ids.delete(id)) {
+      this.cancel(id);
+    }
+  }
+  /**
+   * Cancels every tracked timer. Call this from a controller's `disconnect()`
+   * to guarantee no timer outlives the element.
+   */
+  clearAll() {
+    for (const id of this.ids) {
+      this.cancel(id);
+    }
+    this.ids.clear();
+  }
+  /** Number of timers currently tracked (pending). */
+  get size() {
+    return this.ids.size;
+  }
+};
+var SafeTimeout = class extends TimerRegistry {
+  /**
+   * Schedules `callback` after `delay` ms and returns the timer id.
+   *
+   * The id is removed from the registry automatically when the timeout fires,
+   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
+   */
+  set(callback, delay) {
+    const id = this.schedule(() => {
+      this.ids.delete(id);
+      callback();
+    }, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setTimeout(callback, delay);
+  }
+  cancel(id) {
+    window.clearTimeout(id);
+  }
+};
+
+// 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. */
+  connect() {
+    this.close();
+    document.addEventListener("click", this.#onOutsideClick);
+  }
+  /** Removes the document listener and clears the typeahead timer. */
+  disconnect() {
+    document.removeEventListener("click", this.#onOutsideClick);
+    this.#timers.clearAll();
+  }
+  /**
+   * Toggles the list on a real mouse click. Keyboard activation of the
+   * `<button>` also fires a click (`detail === 0`); the keydown handler already
+   * drives that, so the synthetic click is ignored to avoid double-toggling.
+   */
+  toggle(event) {
+    if (event.detail === 0) return;
+    if (this.#isClosed) {
+      this.open();
+    } else {
+      this.close();
+    }
+  }
+  /** Routes trigger keyboard interaction per the APG select-only model. */
+  onTriggerKeydown(event) {
+    const length = this.optionTargets.length;
+    if (this.#isClosed) {
+      switch (event.key) {
+        case "Enter":
+        case " ":
+        case "ArrowDown":
+        case "ArrowUp":
+          event.preventDefault();
+          this.open();
+          break;
+      }
+      return;
+    }
+    if (length === 0 && event.key !== "Escape" && event.key !== "Tab") {
+      return;
+    }
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        this.#setActive(this.#activeIndex < 0 ? 0 : (this.#activeIndex + 1) % length);
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        this.#setActive(
+          this.#activeIndex < 0 ? length - 1 : (this.#activeIndex - 1 + length) % length
+        );
+        break;
+      case "Home":
+        event.preventDefault();
+        this.#setActive(0);
+        break;
+      case "End":
+        event.preventDefault();
+        this.#setActive(length - 1);
+        break;
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        this.#commitActive();
+        break;
+      case "Escape":
+        event.preventDefault();
+        this.close();
+        this.triggerTarget.focus();
+        break;
+      case "Tab":
+        this.close();
+        break;
+      default:
+        if (this.#isPrintable(event)) {
+          event.preventDefault();
+          this.#typeaheadTo(event.key);
+        }
+        break;
+    }
+  }
+  /** Selects the clicked option and closes, returning focus to the trigger. */
+  select(event) {
+    const option = event.currentTarget.closest('[role="option"]');
+    if (!option) return;
+    this.#selectOption(option);
+    this.close();
+    this.triggerTarget.focus();
+  }
+  /** Opens the list and activates the selected option (else the first). */
+  open() {
+    if (!this.hasListTarget) return;
+    this.listTarget.hidden = false;
+    this.triggerTarget.setAttribute("aria-expanded", "true");
+    if (this.optionTargets.length === 0) {
+      this.#setActive(-1);
+      return;
+    }
+    const selected = this.optionTargets.findIndex(
+      (option) => option.getAttribute("aria-selected") === "true"
+    );
+    this.#setActive(selected === -1 ? 0 : selected);
+  }
+  /** Closes the list, clears the active option, and resets the typeahead buffer. */
+  close() {
+    if (!this.hasListTarget) return;
+    this.listTarget.hidden = true;
+    this.triggerTarget.setAttribute("aria-expanded", "false");
+    this.#setActive(-1);
+    this.#resetTypeahead();
+  }
+  /** Commits the active option (keyboard) and closes, returning focus. */
+  #commitActive() {
+    const option = this.#activeIndex < 0 ? void 0 : this.optionTargets[this.#activeIndex];
+    if (option) this.#selectOption(option);
+    this.close();
+    this.triggerTarget.focus();
+  }
+  /** Applies selection: `aria-selected`, trigger label, hidden field, `change`. */
+  #selectOption(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 } });
+  }
+  /**
+   * Marks the option at `index` active via `data-active` and the trigger's
+   * `aria-activedescendant`. Pass `-1` to clear it (the attribute is removed, not
+   * 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) {
+      if (option === active) {
+        option.setAttribute("data-active", "");
+      } else {
+        option.removeAttribute("data-active");
+      }
+    }
+    if (active?.id) {
+      this.triggerTarget.setAttribute("aria-activedescendant", active.id);
+    } else {
+      this.triggerTarget.removeAttribute("aria-activedescendant");
+    }
+  }
+  /** 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);
+  }
+  /** Clears the typeahead query and its pending reset timer. */
+  #resetTypeahead() {
+    this.#timers.clear(this.#typeaheadTimer);
+    this.#typeahead = "";
+  }
+  /** Closes the list when a click lands outside the controller element. */
+  #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;
+  }
+};
+
+export { ListboxController };
+//# sourceMappingURL=listbox_controller.js.map
+//# sourceMappingURL=listbox_controller.js.map

package/dist/controllers/listbox_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/listbox_controller.ts"],"names":[],"mappings":"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","file":"listbox_controller.js","sourcesContent":["/**\n * Self-cleaning timer registries shared by Stimeo controllers.\n *\n * Stimulus controllers frequently schedule `setTimeout` / `setInterval` work\n * (auto-dismiss, debouncing, polling). When the element leaves the DOM — a\n * Turbo Drive navigation, a Turbo Stream replacement, or any `disconnect()` —\n * orphaned timers keep firing against a detached controller, leaking memory and\n * mutating stale state. {@link SafeTimeout} and {@link SafeInterval} track every\n * timer they create so a single {@link TimerRegistry.clearAll | clearAll()} call\n * in `disconnect()` tears them all down.\n *\n * These are intentionally low-level primitives: they own *registration and\n * cleanup only*. Higher-level policy (pause/resume, remaining-time accounting)\n * stays in the individual controllers so per-widget semantics are not flattened\n * into a lowest-common-denominator helper.\n */\n\n/**\n * Shared registry bookkeeping for the timeout/interval variants.\n *\n * Subclasses provide the scheduling primitive ({@link schedule}) and its matching\n * canceller ({@link cancel}); this base owns the set of live ids plus the\n * per-id and bulk teardown shared by both.\n */\nabstract class TimerRegistry {\n  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */\n  protected readonly ids = new Set<number>();\n\n  /** Schedules the underlying platform timer and returns its id. */\n  protected abstract schedule(callback: () => void, delay: number): number;\n\n  /** Cancels the underlying platform timer for `id`. */\n  protected abstract cancel(id: number): void;\n\n  /**\n   * Cancels a single tracked timer.\n   *\n   * No-ops if the id is unknown (already cleared, fired, or never owned by this\n   * registry), so callers can clear defensively without guarding.\n   */\n  clear(id: number): void {\n    if (this.ids.delete(id)) {\n      this.cancel(id);\n    }\n  }\n\n  /**\n   * Cancels every tracked timer. Call this from a controller's `disconnect()`\n   * to guarantee no timer outlives the element.\n   */\n  clearAll(): void {\n    for (const id of this.ids) {\n      this.cancel(id);\n    }\n    this.ids.clear();\n  }\n\n  /** Number of timers currently tracked (pending). */\n  get size(): number {\n    return this.ids.size;\n  }\n}\n\n/**\n * `setTimeout` wrapper that auto-forgets each timer once it fires and supports\n * bulk teardown on disconnect.\n *\n * @example\n * ```ts\n * #timers = new SafeTimeout();\n *\n * connect() {\n *   this.#timers.set(() => this.dismiss(), 5000);\n * }\n *\n * disconnect() {\n *   this.#timers.clearAll();\n * }\n * ```\n */\nexport class SafeTimeout extends TimerRegistry {\n  /**\n   * Schedules `callback` after `delay` ms and returns the timer id.\n   *\n   * The id is removed from the registry automatically when the timeout fires,\n   * so {@link TimerRegistry.size | size} reflects only still-pending timers.\n   */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(() => {\n      this.ids.delete(id);\n      callback();\n    }, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setTimeout(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearTimeout(id);\n  }\n}\n\n/**\n * `setInterval` wrapper that tracks every interval for bulk teardown on\n * disconnect. Unlike {@link SafeTimeout}, intervals are retained until they are\n * explicitly cleared because they fire repeatedly.\n *\n * @example\n * ```ts\n * #intervals = new SafeInterval();\n *\n * connect() {\n *   this.#intervals.set(() => this.tick(), 1000);\n * }\n *\n * disconnect() {\n *   this.#intervals.clearAll();\n * }\n * ```\n */\nexport class SafeInterval extends TimerRegistry {\n  /** Schedules a repeating `callback` every `delay` ms and returns the timer id. */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(callback, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setInterval(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearInterval(id);\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { SafeTimeout } from \"../utils/safe_timeout\";\n\n/** How long (ms) typed characters accumulate into one typeahead query. */\nconst TYPEAHEAD_TIMEOUT = 500;\n\n/**\n * Headless, accessible select-only listbox behavior.\n *\n * Markup contract (identifier: `stimeo--listbox`):\n *   <div data-controller=\"stimeo--listbox\">\n *     <span id=\"lb-label\">Favorite fruit</span>\n *     <button type=\"button\" role=\"combobox\" aria-haspopup=\"listbox\"\n *             aria-expanded=\"false\" aria-controls=\"lb-list\" aria-activedescendant=\"\"\n *             aria-labelledby=\"lb-label lb-value\"\n *             data-stimeo--listbox-target=\"trigger\"\n *             data-action=\"click->stimeo--listbox#toggle\n *                          keydown->stimeo--listbox#onTriggerKeydown\">\n *       <span id=\"lb-value\" data-stimeo--listbox-target=\"value\">Choose…</span>\n *     </button>\n *     <ul id=\"lb-list\" role=\"listbox\" aria-label=\"Options\" hidden\n *         data-stimeo--listbox-target=\"list\">\n *       <li id=\"opt-1\" role=\"option\" aria-selected=\"false\" data-value=\"1\"\n *           data-stimeo--listbox-target=\"option\"\n *           data-action=\"click->stimeo--listbox#select\">Option 1</li>\n *       <!-- more options -->\n *     </ul>\n *     <input type=\"hidden\" data-stimeo--listbox-target=\"field\" />\n *   </div>\n *\n * Implements the WAI-ARIA APG **Listbox** pattern in its collapsed\n * (Select-Only Combobox) form. Focus stays on the trigger; the active option is\n * tracked with `aria-activedescendant` rather than by moving DOM focus. For a\n * text-filtered popup use {@link ComboboxController | Combobox}; for multiple\n * selection use Multi-Select.\n *\n * @remarks\n * Behavior only. Static placement is the consumer's CSS; dynamic placement is\n * delegated to the opt-in `stimeo-ui/positioning` module. The look is keyed off\n * `aria-selected` / `data-active`. Because `role=\"combobox\"` is not named by its\n * contents, give the trigger an accessible name via `aria-labelledby` (a visible\n * label plus the value span) or `aria-label`.\n *\n * Behavior provided:\n * - Open/close the list, syncing `aria-expanded` and the list's `hidden`.\n * - `ArrowDown`/`ArrowUp` (wrapping), `Home`/`End`, and printable-character\n *   typeahead move the active option; opening picks the selected option (else\n *   the first).\n * - Single selection syncs `aria-selected`, reflects the label into the trigger\n *   value and the field's value, and dispatches `stimeo--listbox:change` plus a\n *   native bubbling `change` on the field when its value actually changed.\n *   Making the field a validatable mirror (`<input type=\"text\" hidden required>`\n *   instead of `type=\"hidden\"`) lets `stimeo--form-validation` enforce native\n *   constraints on the committed value with no extra JavaScript.\n * - `Enter`/`Space` select and close; `Escape` and outside click / `Tab` close;\n *   closing via select/Escape returns focus to the trigger.\n */\nexport class ListboxController extends Controller<HTMLElement> {\n  static override targets = [\"trigger\", \"value\", \"list\", \"option\", \"field\"];\n  static actions = [\"close\", \"onTriggerKeydown\", \"open\", \"select\", \"toggle\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly triggerTarget: HTMLElement;\n  declare readonly valueTarget: HTMLElement;\n  declare readonly listTarget: HTMLElement;\n  declare readonly optionTargets: HTMLElement[];\n  declare readonly fieldTarget: HTMLInputElement;\n  declare readonly hasTriggerTarget: boolean;\n  declare readonly hasValueTarget: boolean;\n  declare readonly hasListTarget: boolean;\n  declare readonly hasFieldTarget: boolean;\n\n  /** Index of the active option, or -1 when none is active. */\n  #activeIndex = -1;\n  /** Accumulated typeahead query, reset after {@link TYPEAHEAD_TIMEOUT} ms. */\n  #typeahead = \"\";\n  #typeaheadTimer = 0;\n  readonly #timers = new SafeTimeout();\n\n  /** Starts closed and registers the outside-click listener. */\n  override connect(): void {\n    this.close();\n    document.addEventListener(\"click\", this.#onOutsideClick);\n  }\n\n  /** Removes the document listener and clears the typeahead timer. */\n  override disconnect(): void {\n    document.removeEventListener(\"click\", this.#onOutsideClick);\n    this.#timers.clearAll();\n  }\n\n  /**\n   * Toggles the list on a real mouse click. Keyboard activation of the\n   * `<button>` also fires a click (`detail === 0`); the keydown handler already\n   * drives that, so the synthetic click is ignored to avoid double-toggling.\n   */\n  toggle(event: MouseEvent): void {\n    if (event.detail === 0) return;\n    if (this.#isClosed) {\n      this.open();\n    } else {\n      this.close();\n    }\n  }\n\n  /** Routes trigger keyboard interaction per the APG select-only model. */\n  onTriggerKeydown(event: KeyboardEvent): void {\n    const length = this.optionTargets.length;\n\n    if (this.#isClosed) {\n      switch (event.key) {\n        case \"Enter\":\n        case \" \":\n        case \"ArrowDown\":\n        case \"ArrowUp\":\n          event.preventDefault();\n          this.open();\n          break;\n        default:\n          break;\n      }\n      return;\n    }\n\n    // With no options, only Escape/Tab are meaningful; ignore navigation and\n    // typeahead so the active index can never become NaN (`% 0`).\n    if (length === 0 && event.key !== \"Escape\" && event.key !== \"Tab\") {\n      return;\n    }\n\n    switch (event.key) {\n      case \"ArrowDown\":\n        event.preventDefault();\n        this.#setActive(this.#activeIndex < 0 ? 0 : (this.#activeIndex + 1) % length);\n        break;\n      case \"ArrowUp\":\n        event.preventDefault();\n        this.#setActive(\n          this.#activeIndex < 0 ? length - 1 : (this.#activeIndex - 1 + length) % length,\n        );\n        break;\n      case \"Home\":\n        event.preventDefault();\n        this.#setActive(0);\n        break;\n      case \"End\":\n        event.preventDefault();\n        this.#setActive(length - 1);\n        break;\n      case \"Enter\":\n      case \" \":\n        event.preventDefault();\n        this.#commitActive();\n        break;\n      case \"Escape\":\n        event.preventDefault();\n        this.close();\n        this.triggerTarget.focus();\n        break;\n      case \"Tab\":\n        // Let focus leave naturally; just don't keep a stale popup open.\n        this.close();\n        break;\n      default:\n        if (this.#isPrintable(event)) {\n          event.preventDefault();\n          this.#typeaheadTo(event.key);\n        }\n        break;\n    }\n  }\n\n  /** Selects the clicked option and closes, returning focus to the trigger. */\n  select(event: Event): void {\n    const option = (event.currentTarget as HTMLElement).closest<HTMLElement>('[role=\"option\"]');\n    if (!option) return;\n    this.#selectOption(option);\n    this.close();\n    this.triggerTarget.focus();\n  }\n\n  /** Opens the list and activates the selected option (else the first). */\n  open(): void {\n    if (!this.hasListTarget) return;\n    this.listTarget.hidden = false;\n    this.triggerTarget.setAttribute(\"aria-expanded\", \"true\");\n    if (this.optionTargets.length === 0) {\n      // An empty listbox has nothing to activate; leave activedescendant cleared.\n      this.#setActive(-1);\n      return;\n    }\n    const selected = this.optionTargets.findIndex(\n      (option) => option.getAttribute(\"aria-selected\") === \"true\",\n    );\n    this.#setActive(selected === -1 ? 0 : selected);\n  }\n\n  /** Closes the list, clears the active option, and resets the typeahead buffer. */\n  close(): void {\n    if (!this.hasListTarget) return;\n    this.listTarget.hidden = true;\n    this.triggerTarget.setAttribute(\"aria-expanded\", \"false\");\n    this.#setActive(-1);\n    this.#resetTypeahead();\n  }\n\n  /** Commits the active option (keyboard) and closes, returning focus. */\n  #commitActive(): void {\n    const option = this.#activeIndex < 0 ? undefined : this.optionTargets[this.#activeIndex];\n    if (option) this.#selectOption(option);\n    this.close();\n    this.triggerTarget.focus();\n  }\n\n  /** Applies selection: `aria-selected`, trigger label, hidden field, `change`. */\n  #selectOption(option: HTMLElement): void {\n    for (const candidate of this.optionTargets) {\n      candidate.setAttribute(\"aria-selected\", candidate === option ? \"true\" : \"false\");\n    }\n    const label = (option.textContent ?? \"\").trim();\n    const value = option.dataset.value ?? label;\n    if (this.hasValueTarget) this.valueTarget.textContent = label;\n    if (this.hasFieldTarget && this.fieldTarget.value !== value) {\n      this.fieldTarget.value = value;\n      // A native bubbling change (matching <select> semantics: only on an actual\n      // value change) so form-level behaviors — validation re-checks, auto-submit\n      // — hear the commit without knowing this widget.\n      this.fieldTarget.dispatchEvent(new Event(\"change\", { bubbles: true }));\n    }\n    this.dispatch(\"change\", { detail: { value, option } });\n  }\n\n  /**\n   * Marks the option at `index` active via `data-active` and the trigger's\n   * `aria-activedescendant`. Pass `-1` to clear it (the attribute is removed, not\n   * set to empty, per the APG).\n   */\n  #setActive(index: number): void {\n    this.#activeIndex = index;\n    const active = index < 0 ? null : this.optionTargets[index];\n    for (const option of this.optionTargets) {\n      if (option === active) {\n        option.setAttribute(\"data-active\", \"\");\n      } else {\n        option.removeAttribute(\"data-active\");\n      }\n    }\n    if (active?.id) {\n      this.triggerTarget.setAttribute(\"aria-activedescendant\", active.id);\n    } else {\n      this.triggerTarget.removeAttribute(\"aria-activedescendant\");\n    }\n  }\n\n  /** Appends a character to the typeahead query and activates the first match. */\n  #typeaheadTo(char: string): void {\n    this.#timers.clear(this.#typeaheadTimer);\n    this.#typeahead += char.toLowerCase();\n    this.#typeaheadTimer = this.#timers.set(() => {\n      this.#typeahead = \"\";\n    }, TYPEAHEAD_TIMEOUT);\n    const index = this.optionTargets.findIndex((option) =>\n      (option.textContent ?? \"\").trim().toLowerCase().startsWith(this.#typeahead),\n    );\n    if (index !== -1) this.#setActive(index);\n  }\n\n  /** Clears the typeahead query and its pending reset timer. */\n  #resetTypeahead(): void {\n    this.#timers.clear(this.#typeaheadTimer);\n    this.#typeahead = \"\";\n  }\n\n  /** Closes the list when a click lands outside the controller element. */\n  readonly #onOutsideClick = (event: MouseEvent): void => {\n    if (!this.#isClosed && !this.element.contains(event.target as Node)) this.close();\n  };\n\n  /** Whether `event.key` is a single printable character (no modifier chord). */\n  #isPrintable(event: KeyboardEvent): boolean {\n    return event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey;\n  }\n\n  /** Whether the list is currently hidden. */\n  get #isClosed(): boolean {\n    return !this.hasListTarget || this.listTarget.hidden !== false;\n  }\n}\n"]}

package/dist/controllers/local_time_controller.d.ts

@@ -0,0 +1,60 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless local-time behavior: renders the UTC instant in a `<time datetime>`
+ * as an absolute, viewer-localized string via `Intl.DateTimeFormat`. No
+ * dedicated APG pattern; it follows the HTML `<time>` semantics.
+ *
+ * Markup contract (identifier: `stimeo--local-time`):
+ *   <time datetime="2026-06-08T12:30:00Z"
+ *         data-controller="stimeo--local-time"
+ *         data-stimeo--local-time-date-style-value="medium"
+ *         data-stimeo--local-time-time-style-value="short">2026-06-08 12:30 UTC</time>
+ *
+ * The server emits UTC (cache-friendly — it never needs to know the viewer's
+ * timezone), and the controller reformats the visible text into the viewer's
+ * locale/zone on connect. This is the *absolute* localization axis, distinct from
+ * {@link RelativeTimeController}'s "3 minutes ago".
+ *
+ * @remarks
+ * Behavior only. The machine-readable `datetime` (UTC) is left untouched so
+ * assistive tech and crawlers keep the canonical value while only the display
+ * text — and an optional `title` — change. Formatting is a pure function of
+ * `datetime` with no module-scope state, listeners, or timers, so a Turbo Drive
+ * cache restore or morph re-runs `connect()` and stays consistent. A parse or
+ * `Intl` error leaves the authored absolute text in place rather than throwing.
+ */
+declare class LocalTimeController extends Controller<HTMLElement> {
+    #private;
+    static values: {
+        locale: {
+            type: StringConstructor;
+            default: string;
+        };
+        timeZone: {
+            type: StringConstructor;
+            default: string;
+        };
+        dateStyle: {
+            type: StringConstructor;
+            default: string;
+        };
+        timeStyle: {
+            type: StringConstructor;
+            default: string;
+        };
+        titleFormat: {
+            type: StringConstructor;
+            default: string;
+        };
+    };
+    static events: readonly ["format"];
+    localeValue: string;
+    timeZoneValue: string;
+    dateStyleValue: string;
+    timeStyleValue: string;
+    titleFormatValue: string;
+    connect(): void;
+}
+
+export { LocalTimeController };

package/dist/controllers/local_time_controller.js

@@ -0,0 +1,81 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/local_time_controller.ts
+var STYLES = /* @__PURE__ */ new Set(["full", "long", "medium", "short"]);
+function toStyle(value) {
+  return STYLES.has(value) ? value : void 0;
+}
+var LocalTimeController = class extends Controller {
+  static values = {
+    locale: { type: String, default: "" },
+    timeZone: { type: String, default: "" },
+    dateStyle: { type: String, default: "medium" },
+    timeStyle: { type: String, default: "short" },
+    titleFormat: { type: String, default: "" }
+  };
+  static events = ["format"];
+  connect() {
+    const date = this.#parse();
+    if (date === null) return;
+    const formatted = this.#applyFormat(date, this.dateStyleValue, this.timeStyleValue);
+    if (formatted === null) return;
+    this.element.textContent = formatted;
+    const title = this.#title(date);
+    if (title !== null) this.element.setAttribute("title", title);
+    this.dispatch("format", { detail: { formatted } });
+  }
+  /** Parses the UTC `datetime` attribute into a {@link Date}, or `null`. */
+  #parse() {
+    const raw = this.element.getAttribute("datetime");
+    if (!raw) return null;
+    const ms = Date.parse(this.#asUtc(raw.trim()));
+    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
+   * 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.
+   */
+  #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;
+  }
+  /**
+   * Builds the optional detailed `title`. `titleFormat` is an `Intl` style
+   * keyword applied to *both* date and time; empty (the default) adds no title.
+   */
+  #title(date) {
+    if (this.titleFormatValue.length === 0) return null;
+    return this.#applyFormat(date, this.titleFormatValue, this.titleFormatValue);
+  }
+  /**
+   * Formats `date` with `Intl.DateTimeFormat`, including each style only when it
+   * is a valid keyword (so a consumer can show date-only or time-only by clearing
+   * the other). Returns `null` when neither style is usable or `Intl` throws, so
+   * the caller can leave the authored text untouched.
+   */
+  #applyFormat(date, dateStyle, timeStyle) {
+    const options = {
+      dateStyle: toStyle(dateStyle),
+      timeStyle: toStyle(timeStyle)
+    };
+    if (options.dateStyle === void 0 && options.timeStyle === void 0) return null;
+    if (this.timeZoneValue.length > 0) options.timeZone = this.timeZoneValue;
+    try {
+      return new Intl.DateTimeFormat(this.#locale, options).format(date);
+    } catch {
+      return null;
+    }
+  }
+  /** Locale precedence: the value, then the element's `lang`, then the document's. */
+  get #locale() {
+    return this.localeValue || this.element.lang || document.documentElement.lang || void 0;
+  }
+};
+
+export { LocalTimeController };
+//# sourceMappingURL=local_time_controller.js.map
+//# sourceMappingURL=local_time_controller.js.map

package/dist/controllers/local_time_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/local_time_controller.ts"],"names":[],"mappings":"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","file":"local_time_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/** A date/time style keyword accepted by `Intl` `dateStyle` / `timeStyle`. */\ntype DateTimeStyle = \"full\" | \"long\" | \"medium\" | \"short\";\n\n/** The valid `Intl` style keywords, used to validate the string-typed values. */\nconst STYLES = new Set<DateTimeStyle>([\"full\", \"long\", \"medium\", \"short\"]);\n\n/** Narrows an arbitrary string to a valid {@link DateTimeStyle}, or `undefined`. */\nfunction toStyle(value: string): DateTimeStyle | undefined {\n  return (STYLES as Set<string>).has(value) ? (value as DateTimeStyle) : undefined;\n}\n\n/**\n * Headless local-time behavior: renders the UTC instant in a `<time datetime>`\n * as an absolute, viewer-localized string via `Intl.DateTimeFormat`. No\n * dedicated APG pattern; it follows the HTML `<time>` semantics.\n *\n * Markup contract (identifier: `stimeo--local-time`):\n *   <time datetime=\"2026-06-08T12:30:00Z\"\n *         data-controller=\"stimeo--local-time\"\n *         data-stimeo--local-time-date-style-value=\"medium\"\n *         data-stimeo--local-time-time-style-value=\"short\">2026-06-08 12:30 UTC</time>\n *\n * The server emits UTC (cache-friendly — it never needs to know the viewer's\n * timezone), and the controller reformats the visible text into the viewer's\n * locale/zone on connect. This is the *absolute* localization axis, distinct from\n * {@link RelativeTimeController}'s \"3 minutes ago\".\n *\n * @remarks\n * Behavior only. The machine-readable `datetime` (UTC) is left untouched so\n * assistive tech and crawlers keep the canonical value while only the display\n * text — and an optional `title` — change. Formatting is a pure function of\n * `datetime` with no module-scope state, listeners, or timers, so a Turbo Drive\n * cache restore or morph re-runs `connect()` and stays consistent. A parse or\n * `Intl` error leaves the authored absolute text in place rather than throwing.\n */\nexport class LocalTimeController extends Controller<HTMLElement> {\n  static override values = {\n    locale: { type: String, default: \"\" },\n    timeZone: { type: String, default: \"\" },\n    dateStyle: { type: String, default: \"medium\" },\n    timeStyle: { type: String, default: \"short\" },\n    titleFormat: { type: String, default: \"\" },\n  };\n  static events = [\"format\"] as const;\n\n  declare localeValue: string;\n  declare timeZoneValue: string;\n  declare dateStyleValue: string;\n  declare timeStyleValue: string;\n  declare titleFormatValue: string;\n\n  override connect(): void {\n    const date = this.#parse();\n    if (date === null) return;\n\n    const formatted = this.#applyFormat(date, this.dateStyleValue, this.timeStyleValue);\n    if (formatted === null) return;\n\n    // Only the visible text (and optional title) change; `datetime` is the\n    // immutable machine-readable source and is never rewritten.\n    this.element.textContent = formatted;\n\n    const title = this.#title(date);\n    if (title !== null) this.element.setAttribute(\"title\", title);\n\n    this.dispatch(\"format\", { detail: { formatted } });\n  }\n\n  /** Parses the UTC `datetime` attribute into a {@link Date}, or `null`. */\n  #parse(): Date | null {\n    const raw = this.element.getAttribute(\"datetime\");\n    if (!raw) return null;\n    const ms = Date.parse(this.#asUtc(raw.trim()));\n    return Number.isNaN(ms) ? null : new Date(ms);\n  }\n\n  /**\n   * Reads a timezone-less date-time as UTC — the documented input contract —\n   * since `Date.parse` would otherwise interpret e.g. `\"2026-06-08T12:30:00\"` in\n   * the *runtime's* local zone, contradicting \"the server emits UTC\". Values that\n   * already carry `Z` or a `±hh:mm` offset (and bare `YYYY-MM-DD` dates, already\n   * parsed as UTC) are returned unchanged.\n   */\n  #asUtc(value: string): string {\n    const hasTime = /T\\d{2}:\\d{2}/.test(value);\n    const hasZone = /(Z|[+-]\\d{2}:?\\d{2})$/.test(value);\n    return hasTime && !hasZone ? `${value}Z` : value;\n  }\n\n  /**\n   * Builds the optional detailed `title`. `titleFormat` is an `Intl` style\n   * keyword applied to *both* date and time; empty (the default) adds no title.\n   */\n  #title(date: Date): string | null {\n    if (this.titleFormatValue.length === 0) return null;\n    return this.#applyFormat(date, this.titleFormatValue, this.titleFormatValue);\n  }\n\n  /**\n   * Formats `date` with `Intl.DateTimeFormat`, including each style only when it\n   * is a valid keyword (so a consumer can show date-only or time-only by clearing\n   * the other). Returns `null` when neither style is usable or `Intl` throws, so\n   * the caller can leave the authored text untouched.\n   */\n  #applyFormat(date: Date, dateStyle: string, timeStyle: string): string | null {\n    // `toStyle` yields `undefined` for an empty/invalid keyword; assigning it is\n    // equivalent to omitting the option, so a consumer can show date- or time-only.\n    const options: Intl.DateTimeFormatOptions = {\n      dateStyle: toStyle(dateStyle),\n      timeStyle: toStyle(timeStyle),\n    };\n    if (options.dateStyle === undefined && options.timeStyle === undefined) return null;\n    if (this.timeZoneValue.length > 0) options.timeZone = this.timeZoneValue;\n\n    try {\n      return new Intl.DateTimeFormat(this.#locale, options).format(date);\n    } catch {\n      // An invalid locale / timeZone (or unsupported style) must not break the\n      // page; the authored absolute text remains as the graceful fallback.\n      return null;\n    }\n  }\n\n  /** Locale precedence: the value, then the element's `lang`, then the document's. */\n  get #locale(): string | undefined {\n    return this.localeValue || this.element.lang || document.documentElement.lang || undefined;\n  }\n}\n"]}

package/dist/controllers/menu_controller.d.ts

@@ -0,0 +1,81 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible menu button behavior.
+ *
+ * Markup contract (identifier: `stimeo--menu`):
+ *   <div data-controller="stimeo--menu">
+ *     <button data-stimeo--menu-target="trigger"
+ *             data-action="click->stimeo--menu#toggle
+ *                          keydown->stimeo--menu#onTriggerKeydown"
+ *             aria-haspopup="menu" aria-expanded="false" aria-controls="menu">
+ *       Actions
+ *     </button>
+ *     <ul id="menu" role="menu" data-stimeo--menu-target="menu" hidden>
+ *       <li role="none">
+ *         <button role="menuitem" tabindex="-1"
+ *                 data-stimeo--menu-target="item"
+ *                 data-action="click->stimeo--menu#activate
+ *                              keydown->stimeo--menu#onItemKeydown">…</button>
+ *       </li>
+ *     </ul>
+ *   </div>
+ *
+ * Implements the WAI-ARIA APG **Menu Button** pattern (a button that opens a menu
+ * of commands). Unlike `stimeo--dropdown` (a disclosure for arbitrary content),
+ * this is a true `role="menu"` widget with roving focus across `role="menuitem"`
+ * children.
+ *
+ * @remarks
+ * Behavior only — static placement is the consumer's responsibility (CSS), and
+ * viewport-edge collision handling is intentionally out of scope (a future shared
+ * positioning module will own it). State is exposed via `aria-expanded` and the
+ * menu's `hidden` attribute.
+ *
+ * Behavior provided:
+ * - Click the trigger to toggle; `ArrowDown`/`ArrowUp` open and focus the
+ *   first/last item.
+ * - Within the menu, `ArrowDown`/`ArrowUp` move focus (wrapping), `Home`/`End`
+ *   jump to the first/last item, `Escape`/`Tab` close and return focus to the
+ *   trigger, and activating an item closes the menu.
+ * - A click outside the controller closes the menu.
+ *
+ * Roving focus skips items that are not navigable — `hidden`, natively
+ * `disabled`, or `aria-disabled="true"` — so the keyboard never lands focus on an
+ * inert command (matching `stimeo--command-palette` / `stimeo--toolbar`).
+ */
+declare class MenuController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static actions: readonly ["activate", "close", "onItemKeydown", "onTriggerKeydown", "open", "toggle"];
+    readonly triggerTarget: HTMLButtonElement;
+    readonly menuTarget: HTMLElement;
+    readonly itemTargets: HTMLButtonElement[];
+    readonly hasTriggerTarget: boolean;
+    readonly hasMenuTarget: boolean;
+    /** Starts closed and registers the outside-click listener. */
+    connect(): void;
+    /** Removes the document-level listener registered in {@link connect}. */
+    disconnect(): void;
+    /** Toggles the menu open/closed. Bound via `data-action` (click). */
+    toggle(): void;
+    /** Opens the menu and reflects the expanded state on the trigger. */
+    open(): void;
+    /** Closes the menu and reflects the collapsed state on the trigger. */
+    close(): void;
+    /**
+     * Opens the menu with the keyboard per the APG (Down → first, Up → last).
+     *
+     * Enter/Space are intentionally not handled here: on a native `<button>`
+     * trigger the browser turns them into a click, which already runs
+     * {@link toggle} (open + focus first item). Handling them again here would
+     * open and then immediately re-toggle the menu.
+     */
+    onTriggerKeydown(event: KeyboardEvent): void;
+    /** Implements roving focus and closing keys inside the menu. */
+    onItemKeydown(event: KeyboardEvent): void;
+    /** Closes the menu after an item is activated. Bound via `data-action`. */
+    activate(): void;
+}
+
+export { MenuController };