stimeo-ui 0.14.0 → 0.16.0

package/dist/controllers/tree_view_controller.js

@@ -13,6 +13,16 @@ 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/field_mirror.ts
+function writeField(field, value) {
+  if (field.value === value) return false;
+  field.value = value;
+  return true;
+}
+function commitField(target) {
+  target.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
 // src/utils/focus_candidate.ts
 function inheritsFieldsetDisabled(control) {
   let fieldset = control.closest("fieldset[disabled]");
@@ -48,6 +58,39 @@ function isInteractiveHost(element) {
   return false;
 }
 
+// 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;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** 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();
+    });
+  }
+};
+
 // src/utils/roving_tabindex.ts
 var RovingTabindex = class {
   /** Returns the current ordered item elements; called on every operation. */
@@ -195,14 +238,28 @@ function findTypeaheadMatch(items, from, query, label = (item) => typeaheadLabel
 }
 
 // src/controllers/tree_view_controller.ts
+var OBSERVED_ATTRIBUTES = ["aria-selected", "data-value"];
+function setAttributeIfChanged(element, name, value) {
+  if (element.getAttribute(name) !== value) element.setAttribute(name, value);
+}
 var NESTED_INTERACTIVE = INTERACTIVE_HOST_SELECTOR;
 var TreeViewController = class extends Controller {
-  static targets = ["item", "group"];
+  static targets = ["item", "group", "field"];
   static actions = ["onClick", "onKeydown", "toggle"];
-  static events = ["select", "toggle"];
+  static events = ["select", "toggle", "reconcile"];
   #roving = new RovingTabindex(() => this.itemTargets);
   #typeahead = new Typeahead();
   #timers = new SafeTimeout();
+  /**
+   * Collapses the item and field callbacks and observed item writes of one DOM
+   * mutation into a single selection pass; refused before `connect()` and after
+   * `disconnect()`.
+   */
+  #reconcile = new MicrotaskCoalescer(() => this.#reconcileSelection());
+  /** Watches the item attributes a page can rewrite in place; set while connected. */
+  #observer = null;
+  /** The selection last settled: on connect, by the user, or by a reported pass. */
+  #settled = { item: null, value: "" };
   #connected = false;
   /**
    * Item targets in DOM order as of the last connect / target change. A removed
@@ -247,9 +304,10 @@ var TreeViewController = class extends Controller {
     });
   };
   /**
-   * Reconciles authored expansion state and establishes the single tab stop.
-   * Idempotent, so a Turbo cache restore / morph re-runs it safely (re-adding
-   * the same listener reference is a no-op per the DOM spec).
+   * Reconciles authored expansion state, establishes the single tab stop, and
+   * settles the selection without reporting it. Idempotent, so a Turbo cache
+   * restore / morph re-runs it safely (re-adding the same listener reference is a
+   * no-op per the DOM spec).
    */
   connect() {
     this.element.addEventListener("focusin", this.#onFocusIn);
@@ -258,14 +316,28 @@ var TreeViewController = class extends Controller {
     this.#reconcileExpansion();
     this.#normalizeSelection();
     this.#normalizeTabStop();
+    this.#mirrorField(false);
     this.#order = [...this.itemTargets];
+    this.#settled = this.#selection();
     this.#connected = true;
+    this.#reconcile.activate();
+    this.#observeItems();
+  }
+  /** Fills a form field inserted or replaced at runtime with the current selection. */
+  fieldTargetConnected() {
+    this.#reconcile.schedule();
   }
-  /** Detaches the focus trackers, drops the typeahead buffer and its timer. */
+  /**
+   * Detaches the focus trackers and the item observer, drops a queued selection
+   * pass, the typeahead buffer and its timer.
+   */
   disconnect() {
     this.element.removeEventListener("focusin", this.#onFocusIn);
     this.element.removeEventListener("focusout", this.#onFocusOut);
     this.#connected = false;
+    this.#reconcile.cancel();
+    this.#observer?.disconnect();
+    this.#observer = null;
     this.#typeahead.reset();
     this.#timers.clearAll();
     this.#order = [];
@@ -284,14 +356,15 @@ var TreeViewController = class extends Controller {
   /**
    * Re-normalizes the tab stop when a `treeitem` is added at runtime, so an
    * appended item carrying `tabindex="0"` cannot turn the tree into two Tab
-   * stops. Skipped before `connect()`: Stimulus registers the initial targets
-   * first, and `connect()` owns the initial tab-stop policy.
+   * stops, and settles the selection once the batch is in. Skipped before
+   * `connect()`: Stimulus registers the initial targets first, and `connect()`
+   * owns the initial tab-stop policy.
    */
   itemTargetConnected() {
     if (!this.#connected) return;
-    this.#normalizeSelection();
     this.#normalizeTabStop();
     this.#trackOrder();
+    this.#reconcile.schedule();
   }
   /**
    * Brings authored `aria-selected` to the shape the APG requires, without
@@ -299,18 +372,91 @@ var TreeViewController = class extends Controller {
    *
    * Every item gets an explicit value — an absent `aria-selected` means "not
    * selectable" in ARIA, so a forgotten attribute hides a selectable row — and a
-   * single-select tree keeps at most one `true`, first in DOM order. `connect()`
-   * reconciles authored expansion the same way. The scan is the `item` target
-   * set: a `role="treeitem"` without the target is outside the contract and is
-   * neither counted nor written.
+   * single-select tree keeps at most one `true`, first in DOM order: an item the
+   * page inserts ahead of the selection, already selected, takes it over.
+   * `connect()` reconciles authored expansion the same way. The scan is the
+   * `item` target set: a `role="treeitem"` without the target is outside the
+   * contract and is neither counted nor written.
    */
   #normalizeSelection() {
     const items = this.itemTargets;
     const selected = items.find((item) => item.getAttribute("aria-selected") === "true");
     for (const item of items) {
-      item.setAttribute("aria-selected", item === selected ? "true" : "false");
+      setAttributeIfChanged(item, "aria-selected", item === selected ? "true" : "false");
     }
   }
+  /**
+   * Mirrors the selected item's `data-value` into the optional form field.
+   * Nothing selected, and an item that carries no value, both submit `""`.
+   */
+  #mirrorField(notify) {
+    if (!this.hasFieldTarget) return;
+    const moved = writeField(this.fieldTarget, this.#selection().value);
+    if (moved && notify) commitField(this.fieldTarget);
+  }
+  /** The selected item target, if any, and the value its field submits. */
+  #selection() {
+    const item = this.itemTargets.find((candidate) => candidate.getAttribute("aria-selected") === "true") ?? null;
+    return { item, value: item?.dataset.value ?? "" };
+  }
+  /**
+   * The pass the page's changes run: the selection is normalized and mirrored,
+   * then reported if it moved. The report comes last, so items a subscriber
+   * rewrites are the next pass's to settle.
+   */
+  #reconcileSelection() {
+    this.#normalizeSelection();
+    this.#dropOwnRecords();
+    this.#mirrorField(false);
+    this.#reportMove();
+  }
+  /**
+   * Reports the selection as `reconcile` when its item or value differs from the
+   * selection last settled. The settled selection is replaced before dispatching,
+   * so a move a subscriber makes is measured against what it was told.
+   */
+  #reportMove() {
+    const selection = this.#selection();
+    if (selection.item === this.#settled.item && selection.value === this.#settled.value) return;
+    this.#settled = selection;
+    this.dispatch("reconcile", { detail: { item: selection.item } });
+  }
+  /**
+   * Watches the items' `aria-selected` and `data-value`. The tree's own writes to
+   * them are dropped from the queue as they happen, so each record the callback
+   * receives is the page's, and only a record on one of the tree's own items
+   * schedules a pass.
+   */
+  #observeItems() {
+    const observer = new MutationObserver((records) => {
+      if (this.#concernsItems(records)) this.#reconcile.schedule();
+    });
+    observer.observe(this.element, {
+      subtree: true,
+      attributes: true,
+      attributeFilter: OBSERVED_ATTRIBUTES
+    });
+    this.#observer = observer;
+  }
+  /**
+   * Whether any record is about one of this tree's own items. A widget nested in a
+   * row writes the same attributes on its own elements, and those are no reason to
+   * reconcile the tree.
+   */
+  #concernsItems(records) {
+    const items = new Set(this.itemTargets);
+    return records.some((record) => items.has(record.target));
+  }
+  /**
+   * Drops the records the tree's own writes just queued, so the observer never
+   * takes them for the page's. A page write queued just before goes with them and
+   * owes nothing: every such write leaves every item's `aria-selected` at the value
+   * the selection gives it, and the selection is then read back from the DOM, so it
+   * already holds what the page wrote.
+   */
+  #dropOwnRecords() {
+    this.#observer?.takeRecords();
+  }
   /**
    * Restores the roving invariants when a `treeitem` leaves at runtime — a Turbo
    * Stream `remove`, a morph, or plain DOM surgery. The mirror of
@@ -326,7 +472,10 @@ var TreeViewController = class extends Controller {
    * state.
    *
    * Focus is only *restored*, never *stolen*: DOM focus moves solely when it was
-   * inside the removed subtree and the document has nowhere left to put it.
+   * inside the removed subtree and the document has nowhere left to put it. The
+   * roving recovery runs here, while the pre-removal order is still on record;
+   * the selection is settled once the batch is in, and a selected item that left
+   * is reported as `reconcile` with no item.
    */
   itemTargetDisconnected(item) {
     if (!this.#connected || !this.element.isConnected) return;
@@ -336,6 +485,7 @@ var TreeViewController = class extends Controller {
       const next = this.#neighborOf(item);
       if (next) this.#roving.setActive(this.itemTargets.indexOf(next), { focus: stranded });
     }
+    this.#reconcile.schedule();
     this.#order = this.#order.filter((tracked) => tracked !== item);
   }
   /**
@@ -565,8 +715,11 @@ var TreeViewController = class extends Controller {
   #select(item) {
     if (this.#isDisabled(item)) return;
     for (const candidate of this.itemTargets) {
-      candidate.setAttribute("aria-selected", candidate === item ? "true" : "false");
+      setAttributeIfChanged(candidate, "aria-selected", candidate === item ? "true" : "false");
     }
+    this.#dropOwnRecords();
+    this.#settled = this.#selection();
+    this.#mirrorField(true);
     this.dispatch("select", { detail: { item } });
   }
   /** Updates expansion, reconciles a collapsed subtree, then synchronously dispatches `toggle`. */