stimeo-ui 0.4.0 → 0.6.0

package/dist/controllers/tags_input_controller.js

@@ -2,6 +2,23 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/tags_input_controller.ts
 
+// src/utils/announce.ts
+function announce(message, options = {}) {
+  const text = message.trim();
+  if (text.length === 0) return;
+  window.dispatchEvent(
+    new CustomEvent("stimeo--announcer:announce", {
+      detail: { message: text, assertive: options.assertive === true }
+    })
+  );
+}
+function fillTemplate(template, values) {
+  return template.replace(/\{([a-zA-Z][a-zA-Z0-9]*)\}/g, (match, name) => {
+    const replacement = values[name];
+    return replacement === void 0 ? match : String(replacement);
+  });
+}
+
 // src/utils/logical_scroll.ts
 function isRtl(element) {
   return window.getComputedStyle(element).direction === "rtl";
@@ -18,6 +35,177 @@ function isReservedArrowChord(event, allow = []) {
   return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
 }
 
+// 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,
+   *   and `items` to reuse an event-scoped collection snapshot.
+   */
+  setActive(index, options = {}) {
+    const { focus = false } = options;
+    const items = options.items ?? this.#getItems();
+    items.forEach((item, i) => {
+      item.tabIndex = i === index ? 0 : -1;
+    });
+    if (focus) items[index]?.focus();
+  }
+};
+
+// src/utils/chip_row.ts
+var ChipRow = class {
+  #directionElement;
+  #getItems;
+  #getButton;
+  #onRemove;
+  #focusAfterEnd;
+  #roving = new RovingTabindex(() => this.buttons);
+  #container = null;
+  constructor(options) {
+    this.#directionElement = options.directionElement;
+    this.#getItems = options.getItems;
+    this.#getButton = options.getButton ?? ((item) => item.querySelector("button"));
+    this.#onRemove = options.onRemove;
+    this.#focusAfterEnd = options.focusAfterEnd;
+  }
+  /**
+   * Binds delegation to `container`; any row currently bound is released first.
+   * Idempotent for the same node, so target callbacks may call it freely.
+   */
+  connect(container) {
+    if (this.#container === container) return;
+    this.disconnect();
+    this.#container = container;
+    container.addEventListener("click", this.#onClick);
+    container.addEventListener("keydown", this.#onKeydown);
+  }
+  /**
+   * Releases the current row. When `container` is supplied, a stale disconnect
+   * callback cannot tear listeners off a newer replacement target.
+   */
+  disconnect(container) {
+    const current = this.#container;
+    if (!current || container !== void 0 && current !== container) return;
+    current.removeEventListener("click", this.#onClick);
+    current.removeEventListener("keydown", this.#onKeydown);
+    this.#container = null;
+  }
+  /** Current remove buttons, at most one consumer-resolved button per chip item. */
+  get buttons() {
+    return this.#entries.map(({ button }) => button);
+  }
+  /** Number of currently navigable remove buttons. */
+  get length() {
+    return this.buttons.length;
+  }
+  /** Declared-item index of the last navigable chip, or `-1` for an empty row. */
+  get lastIndex() {
+    return this.#entries.at(-1)?.itemIndex ?? -1;
+  }
+  /** Keeps exactly one button tabbable, preferring the first authored Tab stop. */
+  ensureTabStop() {
+    const buttons = this.#entries.map(({ button }) => button);
+    const active = buttons.findIndex((button) => button.tabIndex === 0);
+    const count = buttons.filter((button) => button.tabIndex === 0).length;
+    if (buttons.length > 0 && count !== 1) {
+      this.#roving.setActive(active === -1 ? 0 : active, { items: buttons });
+    }
+  }
+  /** Focuses the last chip, returning false for an empty row. */
+  focusLast() {
+    const buttons = this.#entries.map(({ button }) => button);
+    const last = buttons.length - 1;
+    if (last < 0) return false;
+    this.#roving.setActive(last, { focus: true, items: buttons });
+    return true;
+  }
+  /**
+   * Focuses the chip that followed a removed index, or the new last chip.
+   * Returns false when removal emptied the row so the consumer can rescue focus.
+   */
+  focusAfterRemoval(index) {
+    const entries = this.#entries;
+    if (entries.length === 0) return false;
+    const following = entries.findIndex((entry) => entry.itemIndex >= index);
+    this.#roving.setActive(following === -1 ? entries.length - 1 : following, {
+      focus: true,
+      items: entries.map(({ button }) => button)
+    });
+    return true;
+  }
+  /** Current remove-button entries, retaining each button's declared item index. */
+  get #entries() {
+    return this.#getItems().flatMap((item, itemIndex) => {
+      const button = this.#getButton(item);
+      return button ? [{ button, itemIndex }] : [];
+    });
+  }
+  /** Resolves a delegated event to the remove button owned by a declared chip. */
+  #entry(event) {
+    const target = event.target;
+    if (!(target instanceof Element)) return null;
+    const button = target.closest("button");
+    const entries = this.#entries;
+    const buttonIndex = entries.findIndex((entry2) => entry2.button === button);
+    if (buttonIndex === -1) return null;
+    const entry = entries[buttonIndex];
+    return { ...entry, buttonIndex, buttons: entries.map(({ button: button2 }) => button2) };
+  }
+  /** Delegates removal clicks without waiting for Stimulus to wire a new chip. */
+  #onClick = (event) => {
+    const entry = this.#entry(event);
+    if (!entry) return;
+    this.#onRemove(entry.itemIndex);
+  };
+  /** Applies the shared logical-arrow and removal policy within the chip row. */
+  #onKeydown = (event) => {
+    if (event.defaultPrevented || isReservedArrowChord(event)) return;
+    const entry = this.#entry(event);
+    if (!entry) return;
+    const buttons = entry.buttons;
+    const index = entry.buttonIndex;
+    switch (logicalArrowKey(event.key, this.#directionElement)) {
+      case "ArrowLeft":
+        if (index > 0) {
+          event.preventDefault();
+          this.#roving.setActive(index - 1, { focus: true, items: buttons });
+        }
+        break;
+      case "ArrowRight":
+        event.preventDefault();
+        if (index < buttons.length - 1) {
+          this.#roving.setActive(index + 1, { focus: true, items: buttons });
+        } else {
+          this.#focusAfterEnd();
+        }
+        break;
+      case "Delete":
+      case "Backspace":
+        event.preventDefault();
+        this.#onRemove(entry.itemIndex);
+        break;
+    }
+  };
+};
+
 // src/utils/composition_tracker.ts
 var CompositionTracker = class {
   #observedTargets = /* @__PURE__ */ new Set();
@@ -65,65 +253,82 @@ var CompositionTracker = class {
   };
 };
 
-// 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;
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
   }
-  /** Index of the currently tabbable item (`tabindex="0"`), or `-1` if none. */
-  get activeIndex() {
-    return this.#getItems().findIndex((item) => item.tabIndex === 0);
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
   }
-  /**
-   * 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;
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
     });
-    if (focus) items[index]?.focus();
   }
 };
 
 // src/controllers/tags_input_controller.ts
 var TagsInputController = class extends Controller {
-  static targets = ["input", "tags", "tag", "tagTemplate", "status", "fields"];
+  static targets = ["input", "tags", "tag", "tagTemplate", "label", "remove", "fields"];
   static values = {
     delimiter: { type: String, default: "," },
     max: { type: Number, default: 0 },
     allowDuplicates: { type: Boolean, default: false },
-    name: { type: String, default: "tags[]" }
+    name: { type: String, default: "tags[]" },
+    announceText: { type: String, default: "" },
+    announceRemovedText: { type: String, default: "" }
   };
   static actions = ["onKeydown"];
-  static events = ["change", "reject"];
-  #roving = new RovingTabindex(() => this.#removeButtons);
+  static events = ["change", "reconcile", "reject"];
+  /** Last reconciled tag order, separating user edits from DOM/Turbo repair. */
+  #tagValues = [];
+  /** Whether this connection already reported its unusable chip template. */
+  #warnedTemplate = false;
+  /** Collapses one target/Value mutation batch into one final-DOM repair pass. */
+  #reconcile = new MicrotaskCoalescer(() => this.#reconcileTags());
+  #chipRow = new ChipRow({
+    directionElement: this.element,
+    getItems: () => this.tagTargets,
+    getButton: (tag) => tag.querySelector('button[data-stimeo--tags-input-target~="remove"]'),
+    onRemove: (index) => this.#removeAt(index),
+    focusAfterEnd: () => this.#focusInput()
+  });
   /** Owns IME lifecycle state for commit-key guarding. */
   #composition = new CompositionTracker();
   /** Wires tag-list keyboard navigation and removal, and seeds the single Tab stop. */
   connect() {
+    this.#warnedTemplate = false;
     if (this.hasInputTarget) this.#composition.observe(this.inputTarget);
-    this.tagsTarget.addEventListener("keydown", this.#onTagKeydown);
-    this.tagsTarget.addEventListener("click", this.#onTagClick);
-    this.#syncState();
+    if (this.hasTagsTarget) this.#chipRow.connect(this.tagsTarget);
+    const tags = this.#values;
+    this.#syncState(tags);
+    this.#tagValues = tags;
+    this.#reconcile.activate();
   }
   /** Releases the delegated listeners so no handler outlives the element. */
   disconnect() {
+    this.#reconcile.cancel();
     this.#composition.disconnect();
-    this.tagsTarget.removeEventListener("keydown", this.#onTagKeydown);
-    this.tagsTarget.removeEventListener("click", this.#onTagClick);
+    this.#chipRow.disconnect();
   }
   /** Tracks an input added initially or after connect. */
   inputTargetConnected(input) {
@@ -133,10 +338,40 @@ var TagsInputController = class extends Controller {
   inputTargetDisconnected(input) {
     this.#composition.unobserve(input);
   }
+  /** Rebinds delegation and derived state when the tags container is replaced. */
+  tagsTargetConnected(_tags) {
+    this.#reconcile.schedule();
+  }
+  /** Releases only the row that disconnected, leaving a newer target intact. */
+  tagsTargetDisconnected(tags) {
+    this.#chipRow.disconnect(tags);
+    this.#reconcile.schedule();
+  }
+  /** Reconciles a tag inserted by Turbo, a server render, or another controller. */
+  tagTargetConnected(_tag) {
+    this.#reconcile.schedule();
+  }
+  /** Reconciles a tag removed by Turbo, a server render, or another controller. */
+  tagTargetDisconnected(_tag) {
+    this.#reconcile.schedule();
+  }
+  /** Seeds a fields target inserted after connect. */
+  fieldsTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Rebuilds submitted fields when the public name changes at runtime. */
+  nameValueChanged() {
+    this.#reconcile.schedule();
+  }
+  /** Recomputes the full hook when the cap changes at runtime. */
+  maxValueChanged() {
+    this.#reconcile.schedule();
+  }
   /** Commits on `Enter`/delimiter and deletes the last tag on empty `Backspace`. */
   onKeydown(event) {
     if (event.defaultPrevented) return;
     if (isReservedArrowChord(event)) return;
+    if (!this.hasInputTarget) return;
     if (this.#composition.isComposing(event)) return;
     if (event.key === "Enter" || event.key === this.delimiterValue) {
       event.preventDefault();
@@ -144,33 +379,20 @@ var TagsInputController = class extends Controller {
       return;
     }
     if (event.key === "Backspace" && this.inputTarget.value === "") {
-      const buttons = this.#removeButtons;
-      if (buttons.length > 0) {
+      const last = this.#chipRow.lastIndex;
+      if (last >= 0) {
         event.preventDefault();
-        this.#removeAt(buttons.length - 1);
+        this.#removeAt(last, "input");
       }
       return;
     }
     if (logicalArrowKey(event.key, this.element) === "ArrowLeft" && this.inputTarget.value === "") {
-      const buttons = this.#removeButtons;
-      if (buttons.length > 0) {
+      if (this.#chipRow.length > 0) {
         event.preventDefault();
-        this.#roving.setActive(buttons.length - 1, { focus: true });
+        this.#chipRow.focusLast();
       }
     }
   }
-  /**
-   * Deletes the tag whose remove button was clicked. 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.#removeAt(index);
-  };
   /** Validates and adds the current input value as a tag, then clears the input. */
   #commitInput() {
     const value = this.inputTarget.value.trim();
@@ -186,78 +408,83 @@ var TagsInputController = class extends Controller {
       this.#reject(value, "duplicate");
       return;
     }
-    this.#appendTag(value);
+    if (!this.#appendTag(value)) return;
     this.inputTarget.value = "";
-    this.#announce(value);
-    this.#syncState();
-    this.dispatch("change", { detail: { tags: this.#values } });
+    const tags = this.#values;
+    this.#syncState(tags);
+    this.#tagValues = tags;
+    this.#announceTransition(true, value, tags.length);
+    this.dispatch("change", { detail: { tags } });
   }
   /** Builds one chip from the template and appends it to the tag list. */
   #appendTag(value) {
-    if (!this.hasTagTemplateTarget) return;
+    if (!this.hasTagsTarget) return false;
+    if (!this.hasTagTemplateTarget) return this.#warnTemplate('a "tagTemplate" target');
     const fragment = this.tagTemplateTarget.content.cloneNode(true);
-    const tag = fragment.querySelector('[data-stimeo--tags-input-target="tag"]');
-    const label = fragment.querySelector('[data-tags-input-slot="label"]');
-    const button = fragment.querySelector("button");
-    if (!tag || !button) return;
+    const tag = fragment.querySelector('[data-stimeo--tags-input-target~="tag"]');
+    const label = fragment.querySelector('[data-stimeo--tags-input-target~="label"]');
+    const button = fragment.querySelector(
+      'button[data-stimeo--tags-input-target~="remove"]'
+    );
+    const removeName = button?.getAttribute("aria-label")?.trim() ?? "";
+    if (!tag) return this.#warnTemplate('a "tag" target');
+    if (!label) return this.#warnTemplate('a "label" target');
+    if (!button) return this.#warnTemplate('a "remove" target <button>');
+    if (removeName === "") {
+      return this.#warnTemplate('a non-empty aria-label on its "remove" target');
+    }
     tag.dataset.value = value;
-    if (label) label.textContent = value;
-    button.setAttribute("aria-label", `Remove ${value}`);
+    label.textContent = value;
+    button.setAttribute("aria-label", fillTemplate(removeName, { label: value, value }));
     button.tabIndex = -1;
     this.tagsTarget.appendChild(fragment);
+    return true;
+  }
+  /**
+   * Reports an unusable chip template to the author, once per connection.
+   *
+   * The commit itself stays a no-op — nothing about the input, the tag set, the
+   * hidden fields, the announcement, or the events changes. Without this line
+   * the only symptom is a field that accepts no tags at all, and the two causes
+   * the Inspector cannot see statically (a name that renders empty from a
+   * missing translation, a server-rendered template) would have no diagnostic
+   * anywhere.
+   */
+  #warnTemplate(missing) {
+    if (!this.#warnedTemplate) {
+      this.#warnedTemplate = true;
+      console.warn(
+        `Stimeo UI: "${this.identifier}" added no tag because its chip template lacks ${missing}.`
+      );
+    }
+    return false;
   }
-  /** Removes the tag at `index`, then moves focus to a neighbor or the input. */
-  #removeAt(index) {
+  /** Removes the tag at `index`, then applies the interaction-origin focus policy. */
+  #removeAt(index, focus = "neighbor") {
     const tag = this.tagTargets[index];
     if (!tag) return;
     const value = tag.dataset.value ?? "";
     tag.remove();
-    this.#announce(value);
-    this.#syncState();
-    this.dispatch("change", { detail: { tags: 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 });
+    const tags = this.#values;
+    this.#syncState(tags);
+    this.#tagValues = tags;
+    this.#announceTransition(false, value, tags.length);
+    this.dispatch("change", { detail: { tags } });
+    if (focus === "input") {
+      this.#focusInput();
+      return;
     }
+    if (!this.#chipRow.focusAfterRemoval(index)) this.#focusInput();
+  }
+  /** Moves focus to the current input when one exists. */
+  #focusInput() {
+    if (this.hasInputTarget) this.inputTarget.focus();
   }
-  /** Handles arrow navigation and deletion within the chip list (delegated). */
-  #onTagKeydown = (event) => {
-    if (event.defaultPrevented) return;
-    if (isReservedArrowChord(event)) return;
-    const button = event.target.closest("button");
-    if (!button) return;
-    const buttons = this.#removeButtons;
-    const index = buttons.indexOf(button);
-    if (index === -1) return;
-    switch (logicalArrowKey(event.key, this.element)) {
-      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.#removeAt(index);
-        break;
-    }
-  };
   /** Rebuilds the hidden form fields, the `full` flag, and the roving Tab stop. */
-  #syncState() {
+  #syncState(values) {
     if (this.hasFieldsTarget) {
       this.fieldsTarget.replaceChildren(
-        ...this.#values.map((value) => {
+        ...values.map((value) => {
           const input = document.createElement("input");
           input.type = "hidden";
           input.name = this.nameValue;
@@ -266,28 +493,37 @@ var TagsInputController = class extends Controller {
         })
       );
     }
-    const full = this.maxValue > 0 && this.tagTargets.length >= this.maxValue;
+    const full = this.maxValue > 0 && values.length >= this.maxValue;
     this.element.toggleAttribute("data-stimeo--tags-input-full", full);
-    if (this.#removeButtons.length > 0 && this.#roving.activeIndex === -1) {
-      this.#roving.setActive(0);
-    }
+    this.#chipRow.ensureTabStop();
+  }
+  /** Repairs derived state after DOM/Turbo changes and reports a changed tag order. */
+  #reconcileTags() {
+    if (this.hasTagsTarget) this.#chipRow.connect(this.tagsTarget);
+    else this.#chipRow.disconnect();
+    const tags = this.#values;
+    this.#syncState(tags);
+    const changed = !this.#sameTags(this.#tagValues, tags);
+    this.#tagValues = tags;
+    if (changed) this.dispatch("reconcile", { detail: { tags } });
   }
-  /** Mirrors the changed tag into the live region for assistive tech. */
-  #announce(value) {
-    if (this.hasStatusTarget) this.statusTarget.textContent = value;
+  /** Sends one localized tag transition through the page's shared announcer. */
+  #announceTransition(added, value, count) {
+    const template = added ? this.announceTextValue : this.announceRemovedTextValue;
+    announce(fillTemplate(template, { label: value, value, count }));
   }
-  /** Reports a rejected addition via `stimeo--tags-input:reject`. */
+  /** Reports rejection with `{ value, reason: "duplicate" | "empty" | "max" }`. */
   #reject(value, reason) {
     this.dispatch("reject", { detail: { value, reason } });
   }
-  /** The remove buttons in document order (the roving navigation set). */
-  get #removeButtons() {
-    return Array.from(this.tagsTarget.querySelectorAll("button"));
-  }
   /** Current tag values in order. */
   get #values() {
     return this.tagTargets.map((tag) => tag.dataset.value ?? "");
   }
+  /** Whether two arrays carry the same values in the same submitted order. */
+  #sameTags(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+  }
 };
 
 export { TagsInputController };