stimeo-ui 0.1.0-alpha.1

package/dist/controllers/combobox_controller.js

@@ -0,0 +1,186 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/combobox_controller.ts
+var ComboboxController = class extends Controller {
+  static targets = ["input", "list", "option"];
+  static actions = ["close", "filter", "onKeydown", "open", "selectByClick"];
+  static events = ["selected"];
+  /** Index into the *visible* options of the active option, or -1 if none. */
+  #activeIndex = -1;
+  /**
+   * Suppresses {@link open} for the duration of the programmatic re-focus in
+   * `#select`, so committing a value (which returns focus to the input)
+   * does not immediately re-open the listbox via a `focus`-bound action.
+   */
+  #suppressOpen = false;
+  /** Starts closed with no active option and registers the outside-click listener. */
+  connect() {
+    this.close();
+    document.addEventListener("click", this.#onOutsideClick);
+  }
+  /** Removes the document-level listener registered in {@link connect}. */
+  disconnect() {
+    document.removeEventListener("click", this.#onOutsideClick);
+  }
+  /** Filters options by the current input value and opens the listbox. */
+  filter() {
+    this.open();
+  }
+  /**
+   * Opens the listbox, re-filtering the options against the current input value
+   * so the visible options and empty state always match what is typed (e.g.
+   * re-opening with a stale non-matching value still surfaces the empty state).
+   */
+  open() {
+    if (!this.hasListTarget || this.#suppressOpen) return;
+    this.#applyFilter();
+    this.listTarget.hidden = false;
+    this.inputTarget.setAttribute("aria-expanded", "true");
+    this.#setActive(-1);
+    this.#reflectEmptyState();
+  }
+  /**
+   * Hides options that don't match the current input value (case-insensitive
+   * substring). An empty query shows every option. Does not change open state.
+   */
+  #applyFilter() {
+    const query = this.inputTarget.value.trim().toLowerCase();
+    for (const option of this.optionTargets) {
+      const text = (option.textContent ?? "").trim().toLowerCase();
+      option.hidden = query.length > 0 && !text.includes(query);
+    }
+  }
+  /** Closes the listbox, clears the active option, and updates ARIA state. */
+  close() {
+    if (!this.hasListTarget) return;
+    this.listTarget.hidden = true;
+    this.inputTarget.setAttribute("aria-expanded", "false");
+    this.#setActive(-1);
+    this.element.removeAttribute("data-stimeo--combobox-empty");
+  }
+  /** Routes keyboard interaction per the APG combobox model. */
+  onKeydown(event) {
+    switch (event.key) {
+      case "ArrowDown": {
+        event.preventDefault();
+        if (this.#isClosed) this.open();
+        const visible = this.#visibleOptions();
+        if (visible.length > 0) {
+          const next = this.#activeIndex === -1 ? 0 : (this.#activeIndex + 1) % visible.length;
+          this.#setActive(next);
+        }
+        break;
+      }
+      case "ArrowUp": {
+        event.preventDefault();
+        if (this.#isClosed) this.open();
+        const visible = this.#visibleOptions();
+        if (visible.length > 0) {
+          const next = this.#activeIndex === -1 ? visible.length - 1 : (this.#activeIndex - 1 + visible.length) % visible.length;
+          this.#setActive(next);
+        }
+        break;
+      }
+      case "Home":
+        if (!this.#isClosed && this.#visibleOptions().length > 0) {
+          event.preventDefault();
+          this.#setActive(0);
+        }
+        break;
+      case "End": {
+        const visible = this.#visibleOptions();
+        if (!this.#isClosed && visible.length > 0) {
+          event.preventDefault();
+          this.#setActive(visible.length - 1);
+        }
+        break;
+      }
+      case "Enter": {
+        const visible = this.#visibleOptions();
+        const active = this.#activeIndex === -1 ? void 0 : visible[this.#activeIndex];
+        if (active) {
+          event.preventDefault();
+          this.#select(active);
+        }
+        break;
+      }
+      case "Escape":
+        event.preventDefault();
+        this.close();
+        break;
+      case "Tab":
+        this.close();
+        break;
+    }
+  }
+  /**
+   * Closes the listbox when a click lands outside the combobox. Mirrors the menu
+   * button's outside-click behavior; clicks on an option are inside the element,
+   * so `#select` (not this handler) closes the popup after committing.
+   */
+  #onOutsideClick = (event) => {
+    if (!this.#isClosed && !this.element.contains(event.target)) this.close();
+  };
+  /** Selects the clicked option. Bound via `data-action` (click). */
+  selectByClick(event) {
+    const option = event.currentTarget.closest('[role="option"]');
+    if (option) this.#select(option);
+  }
+  /** Commits an option: fills the input, closes the listbox, notifies listeners. */
+  #select(option) {
+    const value = option.dataset.value ?? (option.textContent ?? "").trim();
+    const changed = this.inputTarget.value !== value;
+    this.inputTarget.value = value;
+    this.close();
+    this.#suppressOpen = true;
+    this.inputTarget.focus();
+    this.#suppressOpen = false;
+    if (changed) {
+      this.inputTarget.dispatchEvent(new Event("change", { bubbles: true }));
+    }
+    this.dispatch("selected", { detail: { value } });
+  }
+  /**
+   * Reflects whether the open listbox currently has zero matching options by
+   * toggling `data-stimeo--combobox-empty` on the root element. Behavior only:
+   * consumers decide how to present the empty state (hide the list, show a
+   * "no results" node, etc.) via CSS keyed off this attribute.
+   */
+  #reflectEmptyState() {
+    const empty = !this.#isClosed && this.#visibleOptions().length === 0;
+    if (empty) {
+      this.element.setAttribute("data-stimeo--combobox-empty", "");
+    } else {
+      this.element.removeAttribute("data-stimeo--combobox-empty");
+    }
+  }
+  /**
+   * Marks the visible option at `index` active via `aria-selected` and the
+   * input's `aria-activedescendant`. Pass `-1` to clear the active option.
+   */
+  #setActive(index) {
+    this.#activeIndex = index;
+    const visible = this.#visibleOptions();
+    const active = index === -1 ? null : visible[index];
+    for (const option of this.optionTargets) {
+      option.setAttribute("aria-selected", option === active ? "true" : "false");
+    }
+    if (active?.id) {
+      this.inputTarget.setAttribute("aria-activedescendant", active.id);
+    } else {
+      this.inputTarget.removeAttribute("aria-activedescendant");
+    }
+  }
+  /** The options currently shown (not filtered out). */
+  #visibleOptions() {
+    return this.optionTargets.filter((option) => !option.hidden);
+  }
+  /** Whether the listbox is currently hidden. */
+  get #isClosed() {
+    return !this.hasListTarget || this.listTarget.hidden !== false;
+  }
+};
+
+export { ComboboxController };
+//# sourceMappingURL=combobox_controller.js.map
+//# sourceMappingURL=combobox_controller.js.map

package/dist/controllers/combobox_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/combobox_controller.ts"],"names":[],"mappings":"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","file":"combobox_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless, accessible combobox behavior (list autocomplete).\n *\n * Markup contract (identifier: `stimeo--combobox`):\n *   <div data-controller=\"stimeo--combobox\">\n *     <input type=\"text\" role=\"combobox\" aria-expanded=\"false\"\n *            aria-autocomplete=\"list\" aria-controls=\"listbox\"\n *            data-stimeo--combobox-target=\"input\"\n *            data-action=\"input->stimeo--combobox#filter\n *                         keydown->stimeo--combobox#onKeydown\n *                         focus->stimeo--combobox#open\n *                         click->stimeo--combobox#open\" />\n *     <ul id=\"listbox\" role=\"listbox\" data-stimeo--combobox-target=\"list\" hidden>\n *       <li role=\"option\" id=\"opt-apple\" data-value=\"apple\"\n *           data-stimeo--combobox-target=\"option\"\n *           data-action=\"click->stimeo--combobox#selectByClick\">Apple</li>\n *       <!-- more options -->\n *     </ul>\n *   </div>\n *\n * Implements the WAI-ARIA APG **Combobox** pattern with a listbox popup and\n * list-autocomplete. Focus stays in the input; the active option is tracked with\n * `aria-activedescendant` rather than by moving DOM focus.\n *\n * @remarks\n * Behavior only. Options are authored in the DOM; the controller filters them by\n * toggling each option's `hidden` attribute (case-insensitive substring match on\n * its text). The consumer owns styling, typically keyed off `[aria-selected]`.\n * When an open listbox has no matching options, the root element gets\n * `data-stimeo--combobox-empty` so the consumer can style the empty state (hide\n * the list, show a \"no results\" node, …) — the library imposes no visuals.\n *\n * Behavior provided:\n * - Typing filters the options and opens the listbox.\n * - Focusing or clicking the input opens the listbox, re-filtered against the\n *   current value (so re-opening with a non-matching value keeps the empty state).\n * - `ArrowDown`/`ArrowUp` move the active option (wrapping); `Enter` selects it;\n *   `Escape` closes the listbox; `Home`/`End` jump to the first/last visible\n *   option.\n * - Selecting an option fills the input (with the option's `data-value` if set,\n *   otherwise its text) and closes the listbox.\n * - A click outside the combobox closes the listbox.\n */\nexport class ComboboxController extends Controller<HTMLElement> {\n  static override targets = [\"input\", \"list\", \"option\"];\n  static actions = [\"close\", \"filter\", \"onKeydown\", \"open\", \"selectByClick\"] as const;\n  static events = [\"selected\"] as const;\n\n  declare readonly inputTarget: HTMLInputElement;\n  declare readonly listTarget: HTMLElement;\n  declare readonly optionTargets: HTMLElement[];\n  declare readonly hasInputTarget: boolean;\n  declare readonly hasListTarget: boolean;\n\n  /** Index into the *visible* options of the active option, or -1 if none. */\n  #activeIndex = -1;\n  /**\n   * Suppresses {@link open} for the duration of the programmatic re-focus in\n   * `#select`, so committing a value (which returns focus to the input)\n   * does not immediately re-open the listbox via a `focus`-bound action.\n   */\n  #suppressOpen = false;\n\n  /** Starts closed with no active option 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-level listener registered in {@link connect}. */\n  override disconnect(): void {\n    document.removeEventListener(\"click\", this.#onOutsideClick);\n  }\n\n  /** Filters options by the current input value and opens the listbox. */\n  filter(): void {\n    this.open();\n  }\n\n  /**\n   * Opens the listbox, re-filtering the options against the current input value\n   * so the visible options and empty state always match what is typed (e.g.\n   * re-opening with a stale non-matching value still surfaces the empty state).\n   */\n  open(): void {\n    if (!this.hasListTarget || this.#suppressOpen) return;\n    this.#applyFilter();\n    this.listTarget.hidden = false;\n    this.inputTarget.setAttribute(\"aria-expanded\", \"true\");\n    this.#setActive(-1);\n    this.#reflectEmptyState();\n  }\n\n  /**\n   * Hides options that don't match the current input value (case-insensitive\n   * substring). An empty query shows every option. Does not change open state.\n   */\n  #applyFilter(): void {\n    const query = this.inputTarget.value.trim().toLowerCase();\n    for (const option of this.optionTargets) {\n      const text = (option.textContent ?? \"\").trim().toLowerCase();\n      option.hidden = query.length > 0 && !text.includes(query);\n    }\n  }\n\n  /** Closes the listbox, clears the active option, and updates ARIA state. */\n  close(): void {\n    if (!this.hasListTarget) return;\n    this.listTarget.hidden = true;\n    this.inputTarget.setAttribute(\"aria-expanded\", \"false\");\n    this.#setActive(-1);\n    this.element.removeAttribute(\"data-stimeo--combobox-empty\");\n  }\n\n  /** Routes keyboard interaction per the APG combobox model. */\n  onKeydown(event: KeyboardEvent): void {\n    switch (event.key) {\n      case \"ArrowDown\": {\n        event.preventDefault();\n        // open() re-filters, so read the visible set afterwards.\n        if (this.#isClosed) this.open();\n        const visible = this.#visibleOptions();\n        if (visible.length > 0) {\n          const next = this.#activeIndex === -1 ? 0 : (this.#activeIndex + 1) % visible.length;\n          this.#setActive(next);\n        }\n        break;\n      }\n      case \"ArrowUp\": {\n        event.preventDefault();\n        if (this.#isClosed) this.open();\n        const visible = this.#visibleOptions();\n        if (visible.length > 0) {\n          // From the input (no active option) ArrowUp jumps to the last option,\n          // per the APG; otherwise it wraps backwards.\n          const next =\n            this.#activeIndex === -1\n              ? visible.length - 1\n              : (this.#activeIndex - 1 + visible.length) % visible.length;\n          this.#setActive(next);\n        }\n        break;\n      }\n      case \"Home\":\n        if (!this.#isClosed && this.#visibleOptions().length > 0) {\n          event.preventDefault();\n          this.#setActive(0);\n        }\n        break;\n      case \"End\": {\n        const visible = this.#visibleOptions();\n        if (!this.#isClosed && visible.length > 0) {\n          event.preventDefault();\n          this.#setActive(visible.length - 1);\n        }\n        break;\n      }\n      case \"Enter\": {\n        const visible = this.#visibleOptions();\n        const active = this.#activeIndex === -1 ? undefined : visible[this.#activeIndex];\n        if (active) {\n          event.preventDefault();\n          this.#select(active);\n        }\n        break;\n      }\n      case \"Escape\":\n        event.preventDefault();\n        this.close();\n        break;\n      case \"Tab\":\n        // Let focus leave naturally, but don't keep a stale popup open.\n        this.close();\n        break;\n      default:\n        break;\n    }\n  }\n\n  /**\n   * Closes the listbox when a click lands outside the combobox. Mirrors the menu\n   * button's outside-click behavior; clicks on an option are inside the element,\n   * so `#select` (not this handler) closes the popup after committing.\n   */\n  readonly #onOutsideClick = (event: MouseEvent): void => {\n    if (!this.#isClosed && !this.element.contains(event.target as Node)) this.close();\n  };\n\n  /** Selects the clicked option. Bound via `data-action` (click). */\n  selectByClick(event: Event): void {\n    const option = (event.currentTarget as HTMLElement).closest<HTMLElement>('[role=\"option\"]');\n    if (option) this.#select(option);\n  }\n\n  /** Commits an option: fills the input, closes the listbox, notifies listeners. */\n  #select(option: HTMLElement): void {\n    const value = option.dataset.value ?? (option.textContent ?? \"\").trim();\n    const changed = this.inputTarget.value !== value;\n    this.inputTarget.value = value;\n    this.close();\n    // Returning focus to the input would re-trigger a `focus`-bound open(); guard\n    // it so the listbox stays closed after a selection.\n    this.#suppressOpen = true;\n    this.inputTarget.focus();\n    this.#suppressOpen = false;\n    if (changed) {\n      // A native bubbling `change` (matching <select>/listbox semantics: only on\n      // an actual value change) so form-level behaviors — validation re-checks,\n      // auto-submit — hear the commit without knowing this widget. Deliberately\n      // NOT `input`: that is this combobox's own filter trigger and would reopen\n      // the popup on every selection.\n      this.inputTarget.dispatchEvent(new Event(\"change\", { bubbles: true }));\n    }\n    this.dispatch(\"selected\", { detail: { value } });\n  }\n\n  /**\n   * Reflects whether the open listbox currently has zero matching options by\n   * toggling `data-stimeo--combobox-empty` on the root element. Behavior only:\n   * consumers decide how to present the empty state (hide the list, show a\n   * \"no results\" node, etc.) via CSS keyed off this attribute.\n   */\n  #reflectEmptyState(): void {\n    const empty = !this.#isClosed && this.#visibleOptions().length === 0;\n    if (empty) {\n      this.element.setAttribute(\"data-stimeo--combobox-empty\", \"\");\n    } else {\n      this.element.removeAttribute(\"data-stimeo--combobox-empty\");\n    }\n  }\n\n  /**\n   * Marks the visible option at `index` active via `aria-selected` and the\n   * input's `aria-activedescendant`. Pass `-1` to clear the active option.\n   */\n  #setActive(index: number): void {\n    this.#activeIndex = index;\n    const visible = this.#visibleOptions();\n    const active = index === -1 ? null : visible[index];\n    // Clear aria-selected on every option (not just the visible ones) so a\n    // previously-active option that became hidden by filtering doesn't keep a\n    // stale selected state.\n    for (const option of this.optionTargets) {\n      option.setAttribute(\"aria-selected\", option === active ? \"true\" : \"false\");\n    }\n    if (active?.id) {\n      this.inputTarget.setAttribute(\"aria-activedescendant\", active.id);\n    } else {\n      this.inputTarget.removeAttribute(\"aria-activedescendant\");\n    }\n  }\n\n  /** The options currently shown (not filtered out). */\n  #visibleOptions(): HTMLElement[] {\n    return this.optionTargets.filter((option) => !option.hidden);\n  }\n\n  /** Whether the listbox is currently hidden. */\n  get #isClosed(): boolean {\n    return !this.hasListTarget || this.listTarget.hidden !== false;\n  }\n}\n"]}

package/dist/controllers/command_palette_controller.d.ts

@@ -0,0 +1,103 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, highly accessible Command Palette behavior.
+ *
+ * Markup contract (identifier: `stimeo--command-palette`):
+ *   <div data-controller="stimeo--command-palette"
+ *        data-stimeo--command-palette-hotkey-value="mod+k">
+ *     <div data-stimeo--command-palette-target="dialog" role="dialog"
+ *          aria-modal="true" aria-label="Command palette"
+ *          data-action="click->stimeo--command-palette#closeOnBackdrop" hidden>
+ *       <input data-stimeo--command-palette-target="input" role="combobox"
+ *              aria-expanded="false" aria-controls="cmdk-list"
+ *              aria-autocomplete="list" aria-label="Search commands"
+ *              data-action="input->stimeo--command-palette#filter
+ *                           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>
+ *         <li role="option" data-stimeo--command-palette-target="option"
+ *             data-disabled="true">Section heading (shown but not selectable)</li>
+ *       </ul>
+ *       <p data-stimeo--command-palette-target="empty" hidden>No commands</p>
+ *     </div>
+ *   </div>
+ *
+ * Implements a composite **Dialog (Modal)** + **Combobox** (Listbox options) pattern.
+ * A customizable global hotkey (Command/Ctrl + K) toggles it, focus is trapped
+ * within the dialog, virtual focus roves via `aria-activedescendant`, and filtering
+ * is performed in memory.
+ *
+ * @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 {@link 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.
+ * Styling, transitions, and the actual command handlers remain the consumer's.
+ */
+declare class CommandPaletteController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        hotkey: {
+            type: StringConstructor;
+            default: string;
+        };
+        open: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static actions: readonly ["close", "closeOnBackdrop", "filter", "onKeydown", "open", "selectByClick", "toggle"];
+    static events: readonly ["select"];
+    readonly dialogTarget: HTMLElement;
+    readonly inputTarget: HTMLInputElement;
+    readonly listTarget: HTMLElement;
+    readonly optionTargets: HTMLElement[];
+    readonly emptyTarget: HTMLElement;
+    readonly hasDialogTarget: boolean;
+    readonly hasInputTarget: boolean;
+    readonly hasListTarget: boolean;
+    readonly hasEmptyTarget: boolean;
+    hotkeyValue: string;
+    openValue: boolean;
+    /**
+     * 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 open}
+     * runs its full setup — the {@link FocusTrap} is a fresh instance after a
+     * reconnect and must be re-activated.
+     */
+    connect(): void;
+    /** Tears down the global hotkey listener and reverts the modal side effects. */
+    disconnect(): void;
+    /** Toggles the open state of the command palette. */
+    toggle(): void;
+    /** Opens the palette, traps focus, and shifts focus to the input. */
+    open(): void;
+    /** Closes the palette and restores focus back to the opener. */
+    close(): void;
+    /** Filters option elements in-memory matching the input value. Bound to input target. */
+    filter(): void;
+    /** Selects the clicked option. Bound to option targets. */
+    selectByClick(event: MouseEvent): void;
+    /** Closes when the backdrop (the dialog target itself) is clicked, ignoring inner clicks. */
+    closeOnBackdrop(event: MouseEvent): void;
+    /**
+     * Combobox navigation keys (arrows / Home / End / Enter), bound to the input.
+     * `Tab` (focus trap) and `Escape` (close) are owned by the {@link FocusTrap} at
+     * the document level, so they work no matter which element inside the dialog has
+     * focus — not only the input.
+     */
+    onKeydown(event: KeyboardEvent): void;
+}
+
+export { CommandPaletteController };