stimeo-ui 0.2.0 → 0.2.1

package/dist/controllers/multi_select_controller.d.ts

@@ -0,0 +1,115 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible multi-select combobox with chips.
+ *
+ * Markup contract (identifier: `stimeo--multi-select`):
+ *   <div data-controller="stimeo--multi-select">
+ *     <ul data-stimeo--multi-select-target="tags" aria-label="Selected"></ul>
+ *     <input type="text" role="combobox" aria-expanded="false"
+ *            aria-autocomplete="list" aria-controls="ms-list"
+ *            data-stimeo--multi-select-target="input"
+ *            data-action="input->stimeo--multi-select#filter
+ *                         keydown->stimeo--multi-select#onKeydown
+ *                         focus->stimeo--multi-select#open" />
+ *     <ul id="ms-list" role="listbox" aria-multiselectable="true" hidden
+ *         data-stimeo--multi-select-target="list">
+ *       <li id="ms-opt-1" role="option" aria-selected="false" data-value="apple"
+ *           data-stimeo--multi-select-target="option"
+ *           data-action="click->stimeo--multi-select#toggleOption">Apple</li>
+ *     </ul>
+ *     <span role="status" aria-live="polite" class="visually-hidden"
+ *           data-stimeo--multi-select-target="status"></span>
+ *     <!-- Optional: submit the selection as name="fruits[]" hidden inputs. -->
+ *     <div data-stimeo--multi-select-target="fields"></div>
+ *     <template data-stimeo--multi-select-target="tagTemplate">…</template>
+ *   </div>
+ *
+ * Implements the WAI-ARIA APG **Combobox** pattern in its list-autocomplete,
+ * multi-select form. Focus stays on the input; the active option is tracked with
+ * `aria-activedescendant` and selection with `aria-selected`. Selected options are
+ * mirrored as removable chips. For single selection use {@link ListboxController}
+ * or Combobox; for free-text tags use {@link TagsInputController}.
+ *
+ * Behavior provided:
+ * - Typing filters options by substring and opens the list; `ArrowDown`/`ArrowUp`
+ *   (wrapping), `Home`/`End` move the active option; `Enter` toggles it (the list
+ *   stays open); `Escape`/`Tab`/outside click close.
+ * - Toggling syncs `aria-selected`, adds/removes a `Remove {label}` chip, mirrors
+ *   the live region, and dispatches `stimeo--multi-select:change` with `values`;
+ *   filtering dispatches `stimeo--multi-select:filter` for async candidates.
+ * - The chips are one roving Tab stop: `ArrowLeft`/`ArrowRight` move between them,
+ *   `Delete`/`Backspace` remove the focused chip, and `Backspace` on an empty
+ *   input removes the last; removal re-homes focus to a neighbor or the input.
+ * - `max` caps the selection (`0` = unlimited).
+ * - With a `fields` target the selected values are mirrored into named hidden
+ *   inputs (default name `options[]`), so the selection submits with a normal
+ *   form and no consumer JS — parity with {@link TagsInputController}. An optional
+ *   `form` value sets the hidden inputs' `form` attribute, associating them with a
+ *   `<form>` by id even when the picker lives outside it. Purely additive: with no
+ *   `fields` target the behavior is unchanged.
+ */
+declare class MultiSelectController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        max: {
+            type: NumberConstructor;
+            default: number;
+        };
+        name: {
+            type: StringConstructor;
+            default: string;
+        };
+        form: {
+            type: StringConstructor;
+            default: string;
+        };
+    };
+    static actions: readonly ["close", "filter", "onKeydown", "open", "toggleOption"];
+    static events: readonly ["change", "filter"];
+    readonly inputTarget: HTMLInputElement;
+    readonly listTarget: HTMLElement;
+    readonly optionTargets: HTMLElement[];
+    readonly tagsTarget: HTMLElement;
+    readonly tagTargets: HTMLElement[];
+    readonly tagTemplateTarget: HTMLTemplateElement;
+    readonly statusTarget: HTMLElement;
+    readonly fieldsTarget: HTMLElement;
+    readonly hasListTarget: boolean;
+    readonly hasInputTarget: boolean;
+    readonly hasTagsTarget: boolean;
+    readonly hasTagTemplateTarget: boolean;
+    readonly hasStatusTarget: boolean;
+    readonly hasFieldsTarget: boolean;
+    maxValue: number;
+    nameValue: string;
+    formValue: string;
+    readonly hasFormValue: boolean;
+    /** Starts closed, syncs chips for any pre-selected options, and listens out. */
+    connect(): void;
+    /** Tears down document and chip listeners on disconnect (Turbo included). */
+    disconnect(): void;
+    /** Tracks an input added initially or after connect. */
+    inputTargetConnected(input: HTMLInputElement): void;
+    /** Removes composition listeners when the active input is replaced or removed. */
+    inputTargetDisconnected(input: HTMLInputElement): void;
+    /** Filters confirmed input text, opens, and re-seeds the active option. */
+    filter(event?: InputEvent): void;
+    /** Opens the list and activates the first visible option when none is active. */
+    open(): void;
+    /** Closes the list and clears the active option. */
+    close(): void;
+    /** Routes input keyboard interaction per the multi-select combobox model. */
+    onKeydown(event: KeyboardEvent): void;
+    /**
+     * Toggles the clicked option's selection. Bound via `data-action`. Focus is
+     * re-homed to the input afterwards: options are non-focusable, so the click blurs
+     * the input to `body` — and with the list deliberately staying open, every
+     * keyboard affordance (Escape, arrows, typing) is bound to the input and would
+     * otherwise go dead until the user clicks back in ("focus stays on the input").
+     */
+    toggleOption(event: Event): void;
+}
+
+export { MultiSelectController };

package/dist/controllers/multi_select_controller.js

@@ -0,0 +1,472 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/multi_select_controller.ts
+
+// src/utils/aria_ids.ts
+var counter = 0;
+function uniqueId(prefix = "stimeo") {
+  let candidate;
+  do {
+    counter += 1;
+    candidate = `${prefix}-${counter}`;
+  } while (typeof document !== "undefined" && document.getElementById(candidate) !== null);
+  return candidate;
+}
+function ensureId(element, prefix = "stimeo") {
+  if (element.id) return element.id;
+  const id = uniqueId(prefix);
+  element.id = id;
+  return id;
+}
+
+// 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;
+  const listRect = list.getBoundingClientRect();
+  const optionRect = option.getBoundingClientRect();
+  if (optionRect.top < listRect.top) {
+    list.scrollTop -= listRect.top - optionRect.top;
+  } else if (optionRect.bottom > listRect.bottom) {
+    list.scrollTop += optionRect.bottom - listRect.bottom;
+  }
+}
+
+// src/utils/roving_tabindex.ts
+var RovingTabindex = class {
+  /** Returns the current ordered item elements; called on every operation. */
+  #getItems;
+  /**
+   * @param getItems - Returns the current ordered item elements. Called on every
+   *   operation so the live target list is always used.
+   */
+  constructor(getItems) {
+    this.#getItems = getItems;
+  }
+  /** Index of the currently tabbable item (`tabindex="0"`), or `-1` if none. */
+  get activeIndex() {
+    return this.#getItems().findIndex((item) => item.tabIndex === 0);
+  }
+  /**
+   * Makes exactly the item at `index` tabbable (`tabindex="0"`) and removes every
+   * other item from the Tab sequence (`tabindex="-1"`). An out-of-range `index`
+   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express
+   * "nothing is currently tabbable".
+   *
+   * @param index - Position of the item to make tabbable.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.
+   */
+  setActive(index, { focus = false } = {}) {
+    const items = this.#getItems();
+    items.forEach((item, i) => {
+      item.tabIndex = i === index ? 0 : -1;
+    });
+    if (focus) items[index]?.focus();
+  }
+};
+
+// src/controllers/multi_select_controller.ts
+var MultiSelectController = class extends Controller {
+  static targets = [
+    "input",
+    "list",
+    "option",
+    "tags",
+    "tag",
+    "tagTemplate",
+    "status",
+    "fields"
+  ];
+  static values = {
+    max: { type: Number, default: 0 },
+    name: { type: String, default: "options[]" },
+    form: { type: String, default: "" }
+  };
+  static actions = ["close", "filter", "onKeydown", "open", "toggleOption"];
+  static events = ["change", "filter"];
+  /** The active option (tracked via `aria-activedescendant`), or null. */
+  #activeOption = null;
+  /** Absorbs the browser's redundant final input after compositionend. */
+  #ignorePostCompositionInput = false;
+  /** Owns IME lifecycle state; confirmed text emits one filter result. */
+  #composition = new CompositionTracker({
+    onStart: () => {
+      this.#ignorePostCompositionInput = false;
+    },
+    onEnd: () => {
+      this.#ignorePostCompositionInput = true;
+      queueMicrotask(() => {
+        this.#ignorePostCompositionInput = false;
+      });
+      this.filter();
+    }
+  });
+  #roving = new RovingTabindex(() => this.#removeButtons);
+  /** Starts closed, syncs chips for any pre-selected options, and listens out. */
+  connect() {
+    if (this.hasInputTarget) this.#composition.observe(this.inputTarget);
+    this.close();
+    if (this.hasTagsTarget) {
+      this.tagsTarget.addEventListener("keydown", this.#onTagKeydown);
+      this.tagsTarget.addEventListener("click", this.#onTagClick);
+      for (const tag of this.tagTargets) tag.remove();
+      for (const option of this.#selectedOptions) this.#appendTag(option);
+      if (this.#removeButtons.length > 0) this.#roving.setActive(0);
+    }
+    this.#syncFields();
+    document.addEventListener("click", this.#onOutsideClick);
+  }
+  /** Tears down document and chip listeners on disconnect (Turbo included). */
+  disconnect() {
+    this.#composition.disconnect();
+    this.#ignorePostCompositionInput = false;
+    if (this.hasTagsTarget) {
+      this.tagsTarget.removeEventListener("keydown", this.#onTagKeydown);
+      this.tagsTarget.removeEventListener("click", this.#onTagClick);
+    }
+    document.removeEventListener("click", this.#onOutsideClick);
+  }
+  /** 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);
+    this.#ignorePostCompositionInput = false;
+  }
+  /** Filters confirmed input text, opens, and re-seeds the active option. */
+  filter(event) {
+    if (event && this.#ignorePostCompositionInput) {
+      this.#ignorePostCompositionInput = false;
+      return;
+    }
+    if (this.#composition.isComposing(event)) return;
+    const query = this.inputTarget.value.trim().toLowerCase();
+    for (const option of this.optionTargets) {
+      const label = (option.textContent ?? "").trim().toLowerCase();
+      option.hidden = query !== "" && !label.includes(query);
+    }
+    this.open();
+    const visible = this.#visibleOptions;
+    this.element.toggleAttribute("data-stimeo--multi-select-empty", visible.length === 0);
+    this.#setActive(visible[0] ?? null);
+    this.dispatch("filter", { detail: { query } });
+  }
+  /** Opens the list and activates the first visible option when none is active. */
+  open() {
+    if (!this.hasListTarget) return;
+    this.listTarget.hidden = false;
+    this.inputTarget.setAttribute("aria-expanded", "true");
+    if (!this.#activeOption) this.#setActive(this.#visibleOptions[0] ?? null);
+  }
+  /** Closes the list and clears the active option. */
+  close() {
+    if (!this.hasListTarget) return;
+    this.listTarget.hidden = true;
+    this.inputTarget.setAttribute("aria-expanded", "false");
+    this.#setActive(null);
+  }
+  /** Routes input keyboard interaction per the multi-select combobox model. */
+  onKeydown(event) {
+    if (this.#composition.isComposing(event)) return;
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        if (this.#isClosed) this.open();
+        else this.#moveActive(1);
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        if (this.#isClosed) this.open();
+        else this.#moveActive(-1);
+        break;
+      case "Home":
+        if (!this.#isClosed) {
+          event.preventDefault();
+          this.#setActive(this.#visibleOptions[0] ?? null);
+        }
+        break;
+      case "End": {
+        if (!this.#isClosed) {
+          event.preventDefault();
+          const visible = this.#visibleOptions;
+          this.#setActive(visible[visible.length - 1] ?? null);
+        }
+        break;
+      }
+      case "Enter":
+        if (!this.#isClosed && this.#activeOption) {
+          event.preventDefault();
+          this.#toggleSelection(this.#activeOption);
+        }
+        break;
+      case "Escape":
+        if (event.defaultPrevented || this.#isClosed) break;
+        event.preventDefault();
+        this.close();
+        break;
+      case "Backspace":
+        if (this.inputTarget.value === "") {
+          const buttons = this.#removeButtons;
+          if (buttons.length > 0) {
+            event.preventDefault();
+            this.#removeTagAt(buttons.length - 1);
+          }
+        }
+        break;
+      case "ArrowLeft":
+        if (this.inputTarget.value === "" && this.#removeButtons.length > 0) {
+          event.preventDefault();
+          this.#roving.setActive(this.#removeButtons.length - 1, { focus: true });
+        }
+        break;
+      case "Tab":
+        this.close();
+        break;
+    }
+  }
+  /**
+   * Toggles the clicked option's selection. Bound via `data-action`. Focus is
+   * re-homed to the input afterwards: options are non-focusable, so the click blurs
+   * the input to `body` — and with the list deliberately staying open, every
+   * keyboard affordance (Escape, arrows, typing) is bound to the input and would
+   * otherwise go dead until the user clicks back in ("focus stays on the input").
+   */
+  toggleOption(event) {
+    const option = event.currentTarget.closest('[role="option"]');
+    if (!option) return;
+    this.#toggleSelection(option);
+    this.inputTarget.focus();
+  }
+  /**
+   * Removes the chip whose remove button was clicked, deselecting its option.
+   * Delegated on the tags container (like `#onTagKeydown`) rather than bound
+   * per chip via `data-action`, so it works the instant a chip is appended without
+   * waiting on Stimulus to wire a freshly created element.
+   */
+  #onTagClick = (event) => {
+    const button = event.target.closest("button");
+    if (!button || !this.tagsTarget.contains(button)) return;
+    const index = this.#removeButtons.indexOf(button);
+    if (index !== -1) this.#removeTagAt(index);
+  };
+  /** Moves the active option by `delta` among visible options, wrapping. */
+  #moveActive(delta) {
+    const visible = this.#visibleOptions;
+    if (visible.length === 0) return;
+    const current = this.#activeOption ? visible.indexOf(this.#activeOption) : -1;
+    const next = (current + delta + visible.length) % visible.length;
+    this.#setActive(visible[next] ?? null);
+  }
+  /** Selects/deselects `option`, honoring `max`, and syncs chip + live region. */
+  #toggleSelection(option) {
+    const selected = option.getAttribute("aria-selected") === "true";
+    if (!selected && this.maxValue > 0 && this.#selectedOptions.length >= this.maxValue) {
+      return;
+    }
+    option.setAttribute("aria-selected", String(!selected));
+    if (selected) {
+      this.#removeTagFor(option);
+    } else {
+      this.#appendTag(option);
+    }
+    this.#announce(this.#optionLabel(option));
+    this.#refreshRoving();
+    this.#syncFields();
+    this.dispatch("change", { detail: { values: this.#values } });
+  }
+  /** Builds one chip from the template for `option`. */
+  #appendTag(option) {
+    if (!this.hasTagTemplateTarget || !this.hasTagsTarget) return;
+    const fragment = this.tagTemplateTarget.content.cloneNode(true);
+    const tag = fragment.querySelector('[data-stimeo--multi-select-target="tag"]');
+    const label = fragment.querySelector('[data-multi-select-slot="label"]');
+    const button = fragment.querySelector("button");
+    if (!tag || !button) return;
+    const text = this.#optionLabel(option);
+    tag.dataset.value = this.#optionValue(option);
+    if (label) label.textContent = text;
+    button.setAttribute("aria-label", `Remove ${text}`);
+    button.tabIndex = -1;
+    this.tagsTarget.appendChild(fragment);
+  }
+  /** Removes the chip mirroring `option`, if present. */
+  #removeTagFor(option) {
+    const value = this.#optionValue(option);
+    const tag = this.tagTargets.find((candidate) => candidate.dataset.value === value);
+    tag?.remove();
+  }
+  /** Removes chip `index` and deselects its option, re-homing focus. */
+  #removeTagAt(index) {
+    const tag = this.tagTargets[index];
+    if (!tag) return;
+    const value = tag.dataset.value ?? "";
+    const option = this.optionTargets.find((candidate) => this.#optionValue(candidate) === value);
+    if (option) option.setAttribute("aria-selected", "false");
+    tag.remove();
+    this.#announce(option ? this.#optionLabel(option) : value);
+    this.#refreshRoving();
+    this.#syncFields();
+    this.dispatch("change", { detail: { values: this.#values } });
+    const remaining = this.#removeButtons;
+    if (remaining.length === 0) {
+      this.inputTarget.focus();
+    } else {
+      this.#roving.setActive(Math.min(index, remaining.length - 1), { focus: true });
+    }
+  }
+  /** Arrow navigation and deletion within the chip list (delegated). */
+  #onTagKeydown = (event) => {
+    const button = event.target.closest("button");
+    if (!button) return;
+    const buttons = this.#removeButtons;
+    const index = buttons.indexOf(button);
+    if (index === -1) return;
+    switch (event.key) {
+      case "ArrowLeft":
+        if (index > 0) {
+          event.preventDefault();
+          this.#roving.setActive(index - 1, { focus: true });
+        }
+        break;
+      case "ArrowRight":
+        event.preventDefault();
+        if (index < buttons.length - 1) this.#roving.setActive(index + 1, { focus: true });
+        else this.inputTarget.focus();
+        break;
+      case "Delete":
+      case "Backspace":
+        event.preventDefault();
+        this.#removeTagAt(index);
+        break;
+    }
+  };
+  /**
+   * Marks `option` active via `data-active` and the input's
+   * `aria-activedescendant` (the attribute is removed, not emptied, when null).
+   */
+  #setActive(option) {
+    this.#activeOption = option;
+    for (const candidate of this.optionTargets) {
+      candidate.toggleAttribute("data-active", candidate === option);
+    }
+    if (option) {
+      this.inputTarget.setAttribute("aria-activedescendant", ensureId(option, "stimeo-ms-opt"));
+      if (this.hasListTarget) scrollOptionIntoView(this.listTarget, option);
+    } else {
+      this.inputTarget.removeAttribute("aria-activedescendant");
+    }
+  }
+  /**
+   * Mirrors the selected values into named hidden inputs under the `fields`
+   * target so the selection submits with a normal form (parity with tags-input).
+   * No-ops without a `fields` target, keeping the control back-compat. When the
+   * `form` value is set, each input gets a matching `form` attribute so the picker
+   * can submit with a `<form>` it lives outside of.
+   */
+  #syncFields() {
+    if (!this.hasFieldsTarget) return;
+    this.fieldsTarget.replaceChildren(
+      ...this.#values.map((value) => {
+        const input = document.createElement("input");
+        input.type = "hidden";
+        input.name = this.nameValue;
+        input.value = value;
+        if (this.hasFormValue && this.formValue !== "") input.setAttribute("form", this.formValue);
+        return input;
+      })
+    );
+  }
+  /** Keeps exactly one chip remove button tabbable after the set changes. */
+  #refreshRoving() {
+    if (this.#removeButtons.length > 0 && this.#roving.activeIndex === -1)
+      this.#roving.setActive(0);
+  }
+  /** Mirrors the changed option label into the live region. */
+  #announce(text) {
+    if (this.hasStatusTarget) this.statusTarget.textContent = text;
+  }
+  /** Closes the list on a click outside the controller element. */
+  #onOutsideClick = (event) => {
+    if (!this.#isClosed && !this.element.contains(event.target)) this.close();
+  };
+  /** Trimmed visible label of an option. */
+  #optionLabel(option) {
+    return (option.textContent ?? "").trim();
+  }
+  /** An option's stable value: its `data-value`, else its display label. */
+  #optionValue(option) {
+    return option.dataset.value ?? this.#optionLabel(option);
+  }
+  /** Options not hidden by the current filter. */
+  get #visibleOptions() {
+    return this.optionTargets.filter((option) => !option.hidden);
+  }
+  /** Options currently selected. */
+  get #selectedOptions() {
+    return this.optionTargets.filter((option) => option.getAttribute("aria-selected") === "true");
+  }
+  /** Selected values in option order. */
+  get #values() {
+    return this.#selectedOptions.map((option) => this.#optionValue(option));
+  }
+  /** The chip remove buttons in order (the roving navigation set). */
+  get #removeButtons() {
+    return this.hasTagsTarget ? Array.from(this.tagsTarget.querySelectorAll("button")) : [];
+  }
+  /** Whether the list is currently hidden. */
+  get #isClosed() {
+    return !this.hasListTarget || this.listTarget.hidden !== false;
+  }
+};
+
+export { MultiSelectController };
+//# sourceMappingURL=multi_select_controller.js.map
+//# sourceMappingURL=multi_select_controller.js.map