stimeo-ui 0.16.0 → 0.18.0

package/dist/controllers/command_palette_controller.d.ts

@@ -16,7 +16,7 @@ import { Controller } from '@hotwired/stimulus';
  *                           keydown->stimeo--command-palette#onKeydown" />
  *       <ul id="cmdk-list" data-stimeo--command-palette-target="list" role="listbox">
  *         <li id="cmd-new" role="option" data-stimeo--command-palette-target="option"
- *             data-action="click->stimeo--command-palette#selectByClick">New…</li>
+ *             data-action="click->stimeo--command-palette#select">New…</li>
  *         <li id="cmd-heading" role="option" data-stimeo--command-palette-target="option"
  *             data-disabled="true">Disabled command (shown but not selectable)</li>
  *       </ul>
@@ -29,18 +29,20 @@ import { Controller } from '@hotwired/stimulus';
  * within the dialog, virtual focus roves via `aria-activedescendant`, and filtering
  * is performed in memory.
  *
- * `select` dispatches `{ value: string, option: HTMLElement }`.
+ * `select` dispatches `{ value: string, option: HTMLElement, reason: StateReason }`.
  *
  * @remarks
  * Behavior only. The combobox concerns (filtering, virtual focus, selection) live
  * here; the modal lifecycle — focus trap, scroll lock, background `inert`, focus
  * restore, and teardown reversal — is delegated to the shared `FocusTrap`
- * primitive (also used by dialog / alert-dialog / drawer). `Escape` closes and
- * `Tab`/`Shift+Tab` cycle focus regardless of which element inside the dialog holds
- * focus (input, close button, …), because the trap listens at the document level.
- * IME composition is tracked from start to end: intermediate input does not filter,
- * and conversion-confirming keys never select a command. Styling, transitions, and
- * the actual command handlers remain the consumer's.
+ * primitive. `Escape` closes and `Tab`/`Shift+Tab` cycle focus regardless of which
+ * element inside the dialog holds focus (input, close button, …), because the trap
+ * listens at the document level. IME composition is tracked from start to end:
+ * intermediate input does not filter, and conversion-confirming keys never select a
+ * command. Styling, transitions, and the actual command handlers remain the
+ * consumer's. A Turbo morph that puts the server's markup back over the palette is
+ * answered by writing the palette back: an open palette stays open with its query's
+ * matches and its active option.
  */
 declare class CommandPaletteController extends Controller<HTMLElement> {
     #private;
@@ -55,13 +57,16 @@ declare class CommandPaletteController extends Controller<HTMLElement> {
             default: boolean;
         };
     };
-    static actions: readonly ["close", "closeOnBackdrop", "filter", "onKeydown", "open", "selectByClick", "toggle"];
+    static actions: readonly ["close", "closeOnBackdrop", "filter", "onKeydown", "open", "select", "toggle"];
     static events: readonly ["select"];
     readonly dialogTarget: HTMLElement;
+    readonly dialogTargets: HTMLElement[];
     readonly inputTarget: HTMLInputElement;
+    readonly inputTargets: HTMLInputElement[];
     readonly listTarget: HTMLElement;
     readonly optionTargets: HTMLElement[];
     readonly emptyTarget: HTMLElement;
+    readonly emptyTargets: HTMLElement[];
     readonly hasDialogTarget: boolean;
     readonly hasInputTarget: boolean;
     readonly hasListTarget: boolean;
@@ -71,16 +76,23 @@ declare class CommandPaletteController extends Controller<HTMLElement> {
     /**
      * Initializes the global hotkey handler and establishes the initial open state.
      *
-     * The DOM is the source of truth on reconnect (Turbo cache restore / morph): if
-     * the restored snapshot already shows the dialog open, honor that rather than
-     * re-deriving from the declarative `open` Value (which would slam a user-opened
-     * palette shut). The `open` Value only seeds the initial state of a genuinely
-     * fresh render. We normalize to a clean closed baseline first so
-     * {@link CommandPaletteController.open | open} runs its full setup — the
-     * `FocusTrap` is a fresh instance after a reconnect and must be re-activated.
+     * A dialog the server renders without `hidden` opens, and so does an `open` Value of
+     * `true`, which only seeds that first render. A reconnect of this instance (an in-page
+     * move, a permanent element carried to the next page) keeps an open palette open, its
+     * query and active option included, and takes the `FocusTrap` again. A copy of the page
+     * Turbo restores from its cache comes back closed, whatever opened the palette — the
+     * server's markup, the `open` Value or the user — and the `open` Value is written
+     * `false`: every connection leaves `data-<identifier>-lived` on the element, a copy
+     * carries it, and a new instance that finds it is on such a copy. Otherwise the baseline
+     * is normalized closed first, so {@link CommandPaletteController.open | open} runs its
+     * full setup.
      */
     connect(): void;
-    /** Tears down the global hotkey listener and reverts the modal side effects. */
+    /**
+     * Tears down the global hotkey listener and reverts the modal side effects. The open
+     * state stays on the element: an in-page move reconnects this instance onto it, and a
+     * restored copy of the page is closed by the instance that connects to it.
+     */
     disconnect(): void;
     /** Initializes semantics for an option added before or after the controller connects. */
     optionTargetConnected(option: HTMLElement): void;
@@ -88,8 +100,27 @@ declare class CommandPaletteController extends Controller<HTMLElement> {
     optionTargetDisconnected(option: HTMLElement): void;
     /** Tracks an input added initially or after connect without extra consumer actions. */
     inputTargetConnected(input: HTMLInputElement): void;
-    /** Removes controller-owned listeners when the input target is replaced or removed. */
+    /**
+     * Removes composition listeners, gives an input that no longer resolves as one back its
+     * `aria-expanded` and `aria-activedescendant` — after `disconnect()` too, since dropping
+     * the identifier leaves the element on the page — and reconciles the input that stays.
+     */
     inputTargetDisconnected(input: HTMLInputElement): void;
+    /** Applies the open state to a dialog that arrives after connect in front of the others. */
+    dialogTargetConnected(): void;
+    /**
+     * Gives a dialog that no longer resolves as the target its own `hidden` back — after
+     * `disconnect()` too, since dropping the identifier leaves the element on the page — and,
+     * while connected, applies the open state to the dialog left.
+     */
+    dialogTargetDisconnected(dialog: HTMLElement): void;
+    /** Reflects the empty state onto a region that arrives after connect. */
+    emptyTargetConnected(): void;
+    /**
+     * Gives a region that no longer resolves as the target its own `hidden` back, after
+     * `disconnect()` too, and reflects the empty state onto the region left.
+     */
+    emptyTargetDisconnected(empty: HTMLElement): void;
     /** Toggles the open state of the command palette. */
     toggle(): void;
     /** Opens the palette, traps focus, and shifts focus to the input. */
@@ -98,8 +129,8 @@ declare class CommandPaletteController extends Controller<HTMLElement> {
     close(): void;
     /** Filters option elements in-memory matching the input value. Bound to input target. */
     filter(event?: InputEvent): void;
-    /** Selects the clicked option. Bound to option targets. */
-    selectByClick(event: MouseEvent): void;
+    /** Selects an owned option or descendant; API calls preserve external focus. */
+    select(source: Event | HTMLElement): void;
     /** Closes when the backdrop (the dialog target itself) is clicked, ignoring inner clicks. */
     closeOnBackdrop(event: MouseEvent): void;
     /**