stimeo-ui 0.1.0.pre.beta.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43ec968d086165fbfd9daeda12d003a6cf0cb9e8375a9abfb34924aab3383959
-  data.tar.gz: 8c1fde6bff018d4f47ac745df3e18b2eaaa95d3658ea1ce05fd03bda5b35dc46
+  metadata.gz: 10b597acf4a7ae2ea8c06755f65219ebcd6cf8620dada3700e196d75991c5544
+  data.tar.gz: d0cabdded21420aa90c4eb4eb439588ab7a0bfeff3d4f9fe83b179197de9acb2
 SHA512:
-  metadata.gz: 0ab3a420ebc50b56abce77cd1a4b36be4c3891d4495bd4c2ab8961a42978dc6f79443822ab389dea100b308d236064e76c2e3a0445e0daeb260e7ce4653c71d1
-  data.tar.gz: 1ffc55e37df21a692a21da69f4e98b303ca1600bc57286a132584425392be40f654ba6570227c70436934f5b0ca2bf3d0a5dee9c39c2f24f61e70632e2992751
+  metadata.gz: 66afe27aa72dcbd893b2e2f76525bfddc6bd55788b15ee531cbad6357342ec0bf4d3c2ada2e3cd3dad7dfa37ff9306356b866c1a6e7bdde2445cb103ef944119
+  data.tar.gz: 616de9b15f081a503d907cb468a3c6ad77a74a6773e9677f3e1b9fb28baad505d5bfff6d588c66b48ed965a5acd275f5d8cc1209d69bac2aa7a89153e143be54

data/CHANGELOG.md

@@ -7,6 +7,111 @@ 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.2.0] - 2026-07-22
+
+First release off the beta channel: `npm install stimeo-ui` now resolves
+this version as `latest`, and the gem no longer needs a prerelease pin. The
+library is still `0.x`, so the `stimeo--*` attribute API may change before
+1.0. The changes below come from a component-by-component hardening review
+of the catalog, centered on layered Escape handling, IME-safe input, and
+focus/dismissal correctness in the overlay controllers.
+
+### Added
+
+- dropdown: the trigger is now associated with its menu — on connect the
+  controller sets `aria-controls`, minting a menu id when needed. Authored
+  markup is never overwritten.
+- toast: item interaction (dismiss click, Escape, hover/focus pause) is now
+  delegated from the list container, so dynamically appended toasts work
+  without per-item `data-action` attributes; the dismiss button is the
+  element carrying the new `data-toast-dismiss` attribute. Existing per-item
+  markup keeps working.
+- Inspector: new checks — the menu target of `stimeo--menu` must carry an
+  accessible name, and every command-palette option needs a unique `id`.
+
+### Changed
+
+- tooltip, hover-card: Escape dismissal is now owned by the shared layer
+  stack, so the redundant `onKeydown` action was removed from the
+  controllers and the documented trigger markup. Markup still binding it
+  logs a Stimulus missing-action warning; dismissal keeps working.
+- toast: the live-region role (`status`/`alert`) now applies to the body
+  slot instead of the toast item, so screen readers announce only the
+  message text.
+- menu, overflow-menu: the documented markup contract now requires an
+  accessible name on the `role="menu"` element (`aria-labelledby` or
+  `aria-label`). Existing markup keeps working; the new Inspector check
+  flags the missing name.
+- command-palette: option ARIA is now controller-managed — `data-disabled`
+  and authored `aria-disabled` stay in sync, and every option gets a
+  baseline `aria-selected="false"`.
+
+### Fixed
+
+- Escape now dismisses exactly one overlay layer per press — the most
+  recently opened one — when overlays are stacked: nested dialogs no longer
+  close together, a tooltip or hover card shown above an open menu or dialog
+  no longer closes the layer beneath it, a press already handled by a nested
+  component (an inline edit, a listbox, a toast) is never acted on twice,
+  and an Escape aimed at another layer no longer closes an overlay
+  underneath or yanks focus back to its trigger. This covers dropdown,
+  popover, menu, menubar, context-menu, navigation-menu, hover-card,
+  tooltip, and the modal overlays; a combobox with its list closed now lets
+  Escape reach the enclosing dialog.
+- Escape or Enter pressed during an IME composition now steers the
+  composition only: cancelling a Japanese/Chinese/Korean conversion no
+  longer closes overlays, dismisses a toast or dismissible, or cancels an
+  inline edit, a drag, or a pending date-range start — and a
+  conversion-confirming Enter no longer saves an edit, commits a tag, or
+  selects a command. Filtering inputs (combobox, multi-select,
+  command-palette) apply the confirmed text once on `compositionend` instead
+  of filtering intermediate text. The guards track the composition lifecycle
+  instead of the deprecated `keyCode === 229` heuristic, and otp ignores
+  events flagged `isComposing` even without a preceding `compositionstart`.
+- command-palette: the open/close hotkey no longer misfires when Shift or
+  Alt is held or when both Cmd and Ctrl are down, an unsupported hotkey
+  value now does nothing, and stale `aria-activedescendant`/active-option
+  state is cleaned up correctly.
+- menu, context-menu: `aria-disabled="true"` items are truly inert —
+  activating one runs no consumer handlers and the menu stays open — and
+  Tab now lets the browser move focus before the menu closes. context-menu
+  also closes on an outside right-click without stealing focus from the
+  new target.
+- popover, navigation-menu, dropdown: outside-interaction handling
+  corrected — an outside click closes without refocusing the trigger,
+  clicking non-focusable panel content or deactivating the browser window
+  no longer dismisses an open panel, and dropdown's outside-click listener
+  runs in the capture phase so a widget that stops click propagation can no
+  longer leave a stuck menu.
+- tooltip, hover-card: keyboard focus and pointer hover are now tracked as
+  separate reasons to stay open (per WCAG 1.4.13), and a pending show/hide
+  delay no longer leaves the element permanently stuck after a
+  disconnect/reconnect cycle (e.g. a Turbo restore). The documented
+  hover-card markup now also closes the card after keyboard focus leaves it.
+- toast: runtime `duration` changes now take effect (0 or below makes
+  toasts persistent), a toast paused after its time fully elapsed dismisses
+  immediately, and dismissal is idempotent — the dismiss event fires exactly
+  once per removal.
+- dismissible: the `closeOnEscape` value is live after connect, and focus
+  retreat now skips unfocusable candidates instead of silently dropping
+  focus to `<body>`.
+
+## [0.1.0-beta.3] - 2026-07-18
+
+Maintenance release: one bug fix in the focus-trap primitive shared by the
+modal overlay controllers.
+
+### Fixed
+
+- dialog, alert-dialog, confirm, drawer, command-palette, sidebar: navigating
+  away while the overlay is open no longer bakes the background scroll lock
+  into Turbo's page cache. A restored page previously treated the locked
+  `<body>` as its baseline, so closing the overlay could leave the page
+  unscrollable; the shared focus trap now reverts its side effects on
+  `turbo:before-cache`.
+- drawer: the usage example in the API reference now shows the backdrop
+  overlay `hidden` at rest and a neutral `<div>` as the panel element.
+
 ## [0.1.0-beta.2] - 2026-07-12
 
 The Inspector grows two new faces: an MCP server for AI coding agents and a
@@ -70,6 +175,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.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
 [0.1.0-beta.1]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.1.0-beta.1
 [0.1.0-alpha.1]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.1.0-alpha.1

data/README.md

@@ -5,9 +5,9 @@
   </picture>
 </h1>
 
-<p align="center"><a href="https://stimeo-labs.com"><strong>Live demo (beta) →</strong></a></p>
+<p align="center"><a href="https://stimeo-labs.com"><strong>Live demo →</strong></a></p>
 
-[![CI](https://github.com/taiyaky/stimeo-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/taiyaky/stimeo-ui/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/stimeo-ui/beta)](https://www.npmjs.com/package/stimeo-ui) [![gem](https://img.shields.io/gem/v/stimeo-ui)](https://rubygems.org/gems/stimeo-ui) [![License: MIT](https://img.shields.io/github/license/taiyaky/stimeo-ui)](LICENSE)
+[![CI](https://github.com/taiyaky/stimeo-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/taiyaky/stimeo-ui/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/stimeo-ui)](https://www.npmjs.com/package/stimeo-ui) [![gem](https://img.shields.io/gem/v/stimeo-ui)](https://rubygems.org/gems/stimeo-ui) [![License: MIT](https://img.shields.io/github/license/taiyaky/stimeo-ui)](LICENSE)
 
 **Headless Stimulus UI framework for Ruby on Rails.** Stimeo UI ships *behavior*
 — ARIA state, keyboard interaction, focus management, Turbo resilience — as
@@ -23,15 +23,15 @@ owns the look entirely.
 - Public controller identifiers use the `stimeo--` namespace (e.g.
   `stimeo--dropdown`).
 
-> Status: **beta** (`0.x`). The `stimeo--*` attribute API may still change before
-> 1.0 — pin your version.
+> Status: **pre-release** (`0.x`). The `stimeo--*` attribute API may still
+> change before 1.0 — pin your version.
 
 ## Install
 
 ### Rails with importmap (recommended)
 
 ```bash
-bundle add stimeo-ui --version "0.1.0.pre.beta.2"
+bundle add stimeo-ui
 bin/rails generate stimeo:install
 ```
 
@@ -50,7 +50,7 @@ Stimulus application. Then drive components from HTML alone:
 ### npm (jsbundling or any bundler)
 
 ```bash
-npm install stimeo-ui@beta @hotwired/stimulus
+npm install stimeo-ui @hotwired/stimulus
 ```
 
 ```js

data/dist/controllers/auto_submit_controller.js

@@ -2,6 +2,53 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/auto_submit_controller.ts
 
+// src/utils/composition_tracker.ts
+var CompositionTracker = class {
+  #observedTargets = /* @__PURE__ */ new Set();
+  #activeTargets = /* @__PURE__ */ new Set();
+  #onStart;
+  #onEnd;
+  constructor(options = {}) {
+    this.#onStart = options.onStart;
+    this.#onEnd = options.onEnd;
+  }
+  /** Starts lifecycle tracking for `target`; repeated calls are idempotent. */
+  observe(target) {
+    if (this.#observedTargets.has(target)) return;
+    target.addEventListener("compositionstart", this.#handleStart);
+    target.addEventListener("compositionend", this.#handleEnd);
+    this.#observedTargets.add(target);
+  }
+  /** Stops tracking one target and clears any active composition it owned. */
+  unobserve(target) {
+    if (!this.#observedTargets.delete(target)) return;
+    target.removeEventListener("compositionstart", this.#handleStart);
+    target.removeEventListener("compositionend", this.#handleEnd);
+    this.#activeTargets.delete(target);
+  }
+  /** Releases every listener and clears state so reconnect starts cleanly. */
+  disconnect() {
+    for (const target of this.#observedTargets) {
+      target.removeEventListener("compositionstart", this.#handleStart);
+      target.removeEventListener("compositionend", this.#handleEnd);
+    }
+    this.#observedTargets.clear();
+    this.#activeTargets.clear();
+  }
+  /** True when lifecycle tracking or the current event reports composition. */
+  isComposing(event) {
+    return this.#activeTargets.size > 0 || event?.isComposing === true;
+  }
+  #handleStart = (event) => {
+    if (event.currentTarget) this.#activeTargets.add(event.currentTarget);
+    this.#onStart?.(event);
+  };
+  #handleEnd = (event) => {
+    if (event.currentTarget) this.#activeTargets.delete(event.currentTarget);
+    this.#onEnd?.(event);
+  };
+};
+
 // src/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -79,34 +126,22 @@ var AutoSubmitController = class extends Controller {
       window.dispatchEvent(new CustomEvent("stimeo--announcer:announce", { detail: { message } }));
     }
   };
-  /** True while an IME composition is in progress on one of the form's fields. */
-  #composing = false;
-  /** Marks composition active so `input` events mid-conversion don't submit. */
-  #onCompositionStart = () => {
-    this.#composing = true;
-  };
-  /**
-   * Composition finished (the IME conversion is confirmed): clear the flag and
-   * schedule a submit as if `input` fired, so the settled text triggers a submit
-   * even on browsers whose post-composition `input` still reads `isComposing`.
-   */
-  #onCompositionEnd = (event) => {
-    this.#composing = false;
-    if (this.#triggers("input")) this.#schedule(event.target ?? null);
-  };
+  /** Owns delegated IME lifecycle state and submits confirmed input text. */
+  #composition = new CompositionTracker({
+    onEnd: (event) => {
+      if (this.#triggers("input")) this.#schedule(event.target ?? null);
+    }
+  });
   connect() {
     this.#form.addEventListener("turbo:submit-end", this.#onSubmitEnd);
-    this.#form.addEventListener("compositionstart", this.#onCompositionStart);
-    this.#form.addEventListener("compositionend", this.#onCompositionEnd);
+    this.#composition.observe(this.#form);
   }
   disconnect() {
     this.#timers.clearAll();
     this.#pendingId = 0;
-    this.#composing = false;
+    this.#composition.disconnect();
     this.#form.removeAttribute("data-auto-submit-pending");
     this.#form.removeEventListener("turbo:submit-end", this.#onSubmitEnd);
-    this.#form.removeEventListener("compositionstart", this.#onCompositionStart);
-    this.#form.removeEventListener("compositionend", this.#onCompositionEnd);
   }
   /**
    * Schedules a debounced submit. Wired to `input`/`change`; the `on` value is an
@@ -115,7 +150,7 @@ var AutoSubmitController = class extends Controller {
    */
   submit(event) {
     if (!this.#triggers(event.type)) return;
-    if (event.type === "input" && (this.#composing || event.isComposing)) return;
+    if (event.type === "input" && this.#composition.isComposing(event)) return;
     this.#schedule(event.target ?? null);
   }
   /** Schedules (and coalesces) the debounced submit for the given trigger. */

data/dist/controllers/character_counter_controller.js

@@ -2,6 +2,53 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/character_counter_controller.ts
 
+// src/utils/composition_tracker.ts
+var CompositionTracker = class {
+  #observedTargets = /* @__PURE__ */ new Set();
+  #activeTargets = /* @__PURE__ */ new Set();
+  #onStart;
+  #onEnd;
+  constructor(options = {}) {
+    this.#onStart = options.onStart;
+    this.#onEnd = options.onEnd;
+  }
+  /** Starts lifecycle tracking for `target`; repeated calls are idempotent. */
+  observe(target) {
+    if (this.#observedTargets.has(target)) return;
+    target.addEventListener("compositionstart", this.#handleStart);
+    target.addEventListener("compositionend", this.#handleEnd);
+    this.#observedTargets.add(target);
+  }
+  /** Stops tracking one target and clears any active composition it owned. */
+  unobserve(target) {
+    if (!this.#observedTargets.delete(target)) return;
+    target.removeEventListener("compositionstart", this.#handleStart);
+    target.removeEventListener("compositionend", this.#handleEnd);
+    this.#activeTargets.delete(target);
+  }
+  /** Releases every listener and clears state so reconnect starts cleanly. */
+  disconnect() {
+    for (const target of this.#observedTargets) {
+      target.removeEventListener("compositionstart", this.#handleStart);
+      target.removeEventListener("compositionend", this.#handleEnd);
+    }
+    this.#observedTargets.clear();
+    this.#activeTargets.clear();
+  }
+  /** True when lifecycle tracking or the current event reports composition. */
+  isComposing(event) {
+    return this.#activeTargets.size > 0 || event?.isComposing === true;
+  }
+  #handleStart = (event) => {
+    if (event.currentTarget) this.#activeTargets.add(event.currentTarget);
+    this.#onStart?.(event);
+  };
+  #handleEnd = (event) => {
+    if (event.currentTarget) this.#activeTargets.delete(event.currentTarget);
+    this.#onEnd?.(event);
+  };
+};
+
 // src/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -69,35 +116,25 @@ var CharacterCounterController = class _CharacterCounterController extends Contr
   static #announceDelay = 200;
   #timeouts = new SafeTimeout();
   #announceId = null;
-  /** True while an IME composition is active; intermediate input is skipped. */
-  #composing = false;
+  /** Owns IME lifecycle state and applies the confirmed count once. */
+  #composition = new CompositionTracker({ onEnd: () => this.#update() });
   #onInput = (event) => {
-    if (this.#composing || event.isComposing) return;
-    this.#update();
-  };
-  #onCompositionStart = () => {
-    this.#composing = true;
-  };
-  #onCompositionEnd = () => {
-    this.#composing = false;
+    if (this.#composition.isComposing(event)) return;
     this.#update();
   };
   connect() {
     const field = this.#field;
     if (!field) return;
     field.addEventListener("input", this.#onInput);
-    field.addEventListener("compositionstart", this.#onCompositionStart);
-    field.addEventListener("compositionend", this.#onCompositionEnd);
+    this.#composition.observe(field);
     this.#update({ announce: false });
   }
   disconnect() {
     const field = this.#field;
     field?.removeEventListener("input", this.#onInput);
-    field?.removeEventListener("compositionstart", this.#onCompositionStart);
-    field?.removeEventListener("compositionend", this.#onCompositionEnd);
+    this.#composition.disconnect();
     this.#timeouts.clearAll();
     this.#announceId = null;
-    this.#composing = false;
   }
   /**
    * Recomputes length-derived state. Non-text state (data hooks, `aria-invalid`)

data/dist/controllers/combobox_controller.js

@@ -2,6 +2,53 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/combobox_controller.ts
 
+// src/utils/composition_tracker.ts
+var CompositionTracker = class {
+  #observedTargets = /* @__PURE__ */ new Set();
+  #activeTargets = /* @__PURE__ */ new Set();
+  #onStart;
+  #onEnd;
+  constructor(options = {}) {
+    this.#onStart = options.onStart;
+    this.#onEnd = options.onEnd;
+  }
+  /** Starts lifecycle tracking for `target`; repeated calls are idempotent. */
+  observe(target) {
+    if (this.#observedTargets.has(target)) return;
+    target.addEventListener("compositionstart", this.#handleStart);
+    target.addEventListener("compositionend", this.#handleEnd);
+    this.#observedTargets.add(target);
+  }
+  /** Stops tracking one target and clears any active composition it owned. */
+  unobserve(target) {
+    if (!this.#observedTargets.delete(target)) return;
+    target.removeEventListener("compositionstart", this.#handleStart);
+    target.removeEventListener("compositionend", this.#handleEnd);
+    this.#activeTargets.delete(target);
+  }
+  /** Releases every listener and clears state so reconnect starts cleanly. */
+  disconnect() {
+    for (const target of this.#observedTargets) {
+      target.removeEventListener("compositionstart", this.#handleStart);
+      target.removeEventListener("compositionend", this.#handleEnd);
+    }
+    this.#observedTargets.clear();
+    this.#activeTargets.clear();
+  }
+  /** True when lifecycle tracking or the current event reports composition. */
+  isComposing(event) {
+    return this.#activeTargets.size > 0 || event?.isComposing === true;
+  }
+  #handleStart = (event) => {
+    if (event.currentTarget) this.#activeTargets.add(event.currentTarget);
+    this.#onStart?.(event);
+  };
+  #handleEnd = (event) => {
+    if (event.currentTarget) this.#activeTargets.delete(event.currentTarget);
+    this.#onEnd?.(event);
+  };
+};
+
 // src/utils/option_scroll.ts
 function scrollOptionIntoView(list, option) {
   if (list.scrollHeight <= list.clientHeight) return;
@@ -27,17 +74,30 @@ var ComboboxController = class extends Controller {
    * does not immediately re-open the listbox via a `focus`-bound action.
    */
   #suppressOpen = false;
+  /** Owns IME lifecycle state; confirmed text re-filters the list once. */
+  #composition = new CompositionTracker({ onEnd: () => this.filter() });
   /** Starts closed with no active option and registers the outside-click listener. */
   connect() {
+    if (this.hasInputTarget) this.#composition.observe(this.inputTarget);
     this.close();
     document.addEventListener("click", this.#onOutsideClick);
   }
   /** Removes the document-level listener registered in {@link connect}. */
   disconnect() {
+    this.#composition.disconnect();
     document.removeEventListener("click", this.#onOutsideClick);
   }
-  /** Filters options by the current input value and opens the listbox. */
-  filter() {
+  /** Tracks an input added initially or after connect. */
+  inputTargetConnected(input) {
+    this.#composition.observe(input);
+  }
+  /** Removes composition listeners when the active input is replaced or removed. */
+  inputTargetDisconnected(input) {
+    this.#composition.unobserve(input);
+  }
+  /** Filters confirmed input text and opens the listbox. */
+  filter(event) {
+    if (this.#composition.isComposing(event)) return;
     this.open();
   }
   /**
@@ -74,7 +134,7 @@ var ComboboxController = class extends Controller {
   }
   /** Routes keyboard interaction per the APG combobox model. */
   onKeydown(event) {
-    if (event.isComposing || event.keyCode === 229) return;
+    if (this.#composition.isComposing(event)) return;
     switch (event.key) {
       case "ArrowDown": {
         event.preventDefault();
@@ -120,6 +180,7 @@ var ComboboxController = class extends Controller {
         break;
       }
       case "Escape":
+        if (event.defaultPrevented || this.#isClosed) break;
         event.preventDefault();
         this.close();
         break;