stimeo-ui 0.16.0 → 0.18.0

package/dist/controllers/context_menu_controller.d.ts

@@ -6,7 +6,8 @@ import { Controller } from '@hotwired/stimulus';
  * Markup contract (identifier: `stimeo--context-menu`):
  *   <div data-controller="stimeo--context-menu">
  *     <div data-stimeo--context-menu-target="region" tabindex="0"
- *          aria-haspopup="menu" aria-controls="ctx"
+ *          role="group" aria-label="Files"
+ *          aria-keyshortcuts="Shift+F10" aria-controls="ctx"
  *          data-action="contextmenu->stimeo--context-menu#open
  *                       keydown->stimeo--context-menu#onRegionKeydown">…</div>
  *     <ul id="ctx" role="menu" data-stimeo--context-menu-target="menu" hidden>
@@ -32,12 +33,25 @@ import { Controller } from '@hotwired/stimulus';
  * required). Viewport-edge flip/shift is delegated to the opt-in
  * `stimeo-ui/positioning` module, which this controller never imports.
  *
+ * The region's role and name are the author's: a `role="group"` with
+ * `aria-label`, or an element that has a role of its own (a table row, a list
+ * item, a button), chosen to match what the region holds. The controller writes
+ * no role. The author also points `aria-controls` at the menu and advertises the
+ * opening key with `aria-keyshortcuts="Shift+F10"`. The region carries no
+ * `aria-haspopup`, whatever its role. On a role that supports it, such as a
+ * button, the attribute conveys what ARIA 1.2's note says its visual
+ * counterparts, such as a downward-pointing triangle, signal: that activating
+ * the control (a click, `Enter`) displays a popup. This menu opens on a
+ * `contextmenu` event or the `Shift+F10` / `ContextMenu` key instead, so the
+ * attribute would point to the wrong gesture. On a role that does not, such as
+ * `generic`, `group`, `row` or `listitem`, it would be a global use of the
+ * attribute, which ARIA 1.2 deprecates.
+ *
  * Open state is exposed on the region as `data-state` (`open`/`closed`) — a CSS
- * hook, not an ARIA one. `aria-expanded` is deliberately *not* set on the region
- * because it is a generic container, not a role that supports that state (doing so
- * is an ARIA violation); the region's static `aria-haspopup="menu"` advertises the
- * popup, and assistive tech perceives the open state when focus moves into the
- * `role="menu"`.
+ * hook, not an ARIA one. `aria-expanded` is deliberately *not* set on the region:
+ * the role is the author's, and ARIA 1.2 lists neither `generic` nor `group`
+ * among the roles that support that state. Assistive tech perceives the open
+ * state when focus moves into the `role="menu"`.
  *
  * Behavior provided:
  * - `contextmenu` on the region suppresses the browser menu and opens this one at
@@ -45,24 +59,41 @@ import { Controller } from '@hotwired/stimulus';
  * - On open, focus moves to the first item; the region's `data-state` syncs.
  * - Roving focus inside the menu: `ArrowUp`/`ArrowDown` (wrapping), `Home`/`End`.
  * - Activating an enabled item (click / native `Enter`/`Space` on the button)
- *   closes the menu and restores focus to the region. `aria-disabled` activation
- *   is blocked before consumer click handlers run.
+ *   closes the menu and restores focus to the region. An item that is `hidden`,
+ *   natively `disabled`, or `aria-disabled="true"` itself or through an ancestor
+ *   is not activated on any path, and a click on an `aria-disabled` one is also
+ *   stopped, in a capture listener on the controller element, before the click
+ *   handlers inside that element run. Items can nest, and an event is
+ *   refused when any item holding its target refuses. A click is judged once, in
+ *   that capture pass, so a consumer handler that disables the item while the
+ *   click runs does not take back the activation. The verdict holds only for an
+ *   item that held the click's target when it was taken: an item it was not taken
+ *   for — a handler moved the target into another one — is judged when
+ *   {@link activate} runs, as is any other event.
  * - `Escape` closes and restores focus to the region. While open the menu is a
  *   layer on the shared `EscapeLayer` stack; it claims a press only while
  *   focus is inside the controller or fell to the body, so one keypress closes
  *   exactly one layer. `Tab` lets the browser move focus first, then closes on
  *   the next task. An outside click or context-menu invocation closes without
  *   stealing focus from its destination.
+ * - A region or a menu that takes over — in one task, or after an earlier one
+ *   leaves in a later task — carries the open state, and the menu that takes over
+ *   an open one is placed where it was opened; focus stays where the swap left it.
+ *   With no menu left the region reads closed and the menu leaves the Escape stack.
+ *   One that stops resolving as the target gets back the `data-state` or `hidden` it
+ *   carried before this controller wrote on it.
  * - Each move of the open state is reported: `stimeo--context-menu:open` and
  *   `stimeo--context-menu:close` dispatch `{ reason: StateReason }`, after the
  *   state attributes are written. Both are informational, so neither is
  *   cancelable. A call that leaves the state where it already was, the
- *   normalization in {@link connect}, and {@link disconnect} are all silent.
+ *   normalization in {@link connect}, a region or a menu that takes over, and
+ *   {@link disconnect} are all silent.
  *
- * Roving focus skips `hidden` and natively `disabled` items. An
- * `aria-disabled="true"` item stays reachable by arrow keys — APG marks that
- * attribute precisely for controls that must remain discoverable — while its
- * activation is suppressed, so it announces itself and does nothing.
+ * Roving focus skips `hidden` and natively `disabled` items. An item that
+ * `aria-disabled="true"` reaches, on the item or an ancestor, stays reachable by
+ * arrow keys — APG marks that attribute precisely for controls that must remain
+ * discoverable — while its activation is suppressed, so it announces itself and
+ * does nothing.
  */
 declare class ContextMenuController extends Controller<HTMLElement> {
     #private;
@@ -70,7 +101,9 @@ declare class ContextMenuController extends Controller<HTMLElement> {
     static actions: readonly ["activate", "onItemKeydown", "onRegionKeydown", "open"];
     static events: readonly ["close", "open"];
     readonly regionTarget: HTMLElement;
+    readonly regionTargets: HTMLElement[];
     readonly menuTarget: HTMLElement;
+    readonly menuTargets: HTMLElement[];
     readonly itemTargets: HTMLButtonElement[];
     readonly hasRegionTarget: boolean;
     readonly hasMenuTarget: boolean;
@@ -78,17 +111,46 @@ declare class ContextMenuController extends Controller<HTMLElement> {
     connect(): void;
     /** Releases the listeners, stack membership, and pending Tab-close task. */
     disconnect(): void;
+    /** Brings a region that arrives after connect to the open state. */
+    regionTargetConnected(): void;
+    /**
+     * Gives a region that no longer resolves as one its own `data-state` back — after
+     * `disconnect()` too, since dropping the identifier leaves the element on the page — and
+     * brings the region that stays to the open state.
+     */
+    regionTargetDisconnected(region: HTMLElement): void;
+    /** Applies the open state to a menu that arrives after connect in front of the others. */
+    menuTargetConnected(): void;
     /**
-     * Opens the menu from a `contextmenu` event: suppresses the native menu and
-     * places this one at the pointer coordinate.
+     * Applies the open state to the menu left, then gives a menu that no longer resolves as the
+     * target its own `hidden` back — after `disconnect()` too, since dropping the identifier
+     * leaves the element on the page. The open state is read off the departing menu first,
+     * while it still carries it.
      */
-    open(event: MouseEvent): void;
+    menuTargetDisconnected(menu: HTMLElement): void;
+    /**
+     * Opens at a mouse event's coordinate, an explicit element's center, or the
+     * region's center with no argument. Opening focuses the new menu in all paths.
+     * An explicit element may be an anchor outside the controller.
+     */
+    open(input?: Event | HTMLElement): void;
     /** Keyboard entry on the region: `Shift+F10` / `ContextMenu` open at center. */
     onRegionKeydown(event: KeyboardEvent): void;
     /** Roving focus and closing keys inside the menu. */
     onItemKeydown(event: KeyboardEvent): void;
-    /** Closes after an item is activated and restores focus to the region. */
-    activate(): void;
+    /**
+     * Closes after an item is activated and restores focus to the region. An event
+     * whose target lies in an item that is `hidden`, natively `disabled`, or
+     * `aria-disabled="true"` itself or through an ancestor does nothing: the menu
+     * stays open, nothing is dispatched and focus stays where it is. Every item
+     * holding the target counts, so an item nested in another one refuses for both,
+     * wherever the action is bound. A click is judged as its capture pass found the
+     * items, before the handlers inside the controller element ran, when the
+     * item this resolves was among them; an item that was not, and any other event, is
+     * judged when this runs.
+     * An event that resolves to no item, and a call with no event, always close.
+     */
+    activate(event?: Event): void;
 }
 
 export { ContextMenuController };