stimeo-ui 0.7.0 → 0.9.0

data/dist/controllers/data_grid_controller.js

@@ -18,6 +18,56 @@ 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/interactive_host.ts
+var INTERACTIVE_HOST_SELECTOR = "button, input, select, textarea, label, a[href], area[href], summary, details, audio[controls], video[controls], iframe, object, embed";
+function isInteractiveHost(element) {
+  if (element.matches(INTERACTIVE_HOST_SELECTOR)) return true;
+  let current = element;
+  while (current) {
+    const raw = current.getAttribute("contenteditable");
+    if (raw !== null) {
+      const value = raw.trim().toLowerCase();
+      if (value === "false") return false;
+      if (value === "" || value === "true" || value === "plaintext-only") return true;
+    }
+    current = current.parentElement;
+  }
+  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/controllers/data_grid_controller.ts
 var SORT_CYCLE = ["none", "ascending", "descending"];
 function nextSortDirection(current) {
@@ -32,8 +82,15 @@ var DataGridController = class extends Controller {
   };
   static actions = ["onKeydown", "sort", "toggleSelect"];
   static events = ["selectionchange", "sort"];
-  /** Gates the row callback so it does not re-walk every row once per authored row on mount. */
-  #connected = false;
+  /**
+   * Collapses the per-element target callbacks of one DOM mutation into a single
+   * baseline pass, and refuses to run before `connect()` or after `disconnect()`.
+   *
+   * Stimulus reports every target one at a time, so an ungated pass would re-walk
+   * the whole grid once per authored cell on mount and once per streamed cell
+   * afterwards — quadratic in the cell count both times.
+   */
+  #reconcile = new MicrotaskCoalescer(() => this.#restoreBaseline());
   /**
    * Establishes a single tab stop across all navigable cells/headers and brings
    * the rows to their baseline.
@@ -44,15 +101,30 @@ var DataGridController = class extends Controller {
    * attribute, so the Value callback does not fire a second time.
    */
   connect() {
+    this.#restoreBaseline();
+    this.#reconcile.activate();
+  }
+  /** Closes the reconcile window so a queued pass cannot run against a detached tree. */
+  disconnect() {
+    this.#reconcile.cancel();
+  }
+  /**
+   * Rebuilds both DOM-owned baselines from the live grid: exactly one navigable
+   * cell is in the Tab sequence, and every selectable row carries an explicit
+   * `aria-selected`.
+   *
+   * The tab stop keeps whichever cell already holds it, so a rebuild triggered by
+   * an unrelated row arriving does not throw the user's position away; only when
+   * no cell holds it — the grid is fresh, or the holder was removed — does the
+   * first navigable cell take over. Without that fallback a grid whose active row
+   * is removed keeps every cell at `-1` and drops out of the Tab sequence
+   * entirely.
+   */
+  #restoreBaseline() {
     const cells = this.#navigableCells();
     const active = cells.find((cell) => cell.tabIndex === 0) ?? cells[0];
-    this.#setActiveCell(active, { focus: false });
+    if (active) this.#setActiveCell(active, { focus: false }, cells);
     this.#normalizeSelection();
-    this.#connected = true;
-  }
-  /** Reopens the row callback for the next mount. */
-  disconnect() {
-    this.#connected = false;
   }
   /**
    * Keeps `aria-multiselectable` in step with the `selection` Value. Fires on connect
@@ -63,16 +135,25 @@ var DataGridController = class extends Controller {
     this.#syncSelectable();
     this.#normalizeSelection();
   }
-  /**
-   * Re-establishes the row baseline for a row added after connect.
-   *
-   * Each pass walks every row, and Stimulus reports the authored rows one by one
-   * before `connect()`, so the mount is gated to keep it linear in the row count
-   * rather than quadratic; `connect()` runs the single baseline pass instead.
-   */
+  /** Re-establishes the baselines for a row added after connect. */
   rowTargetConnected() {
-    if (!this.#connected) return;
-    this.#normalizeSelection();
+    this.#reconcile.schedule();
+  }
+  /** Re-establishes the tab stop when a cell joins the grid after connect. */
+  cellTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Re-establishes the tab stop when a cell leaves the grid. */
+  cellTargetDisconnected() {
+    this.#reconcile.schedule();
+  }
+  /** Re-establishes the tab stop when a header joins the grid after connect. */
+  columnHeaderTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Re-establishes the tab stop when a header leaves the grid. */
+  columnHeaderTargetDisconnected() {
+    this.#reconcile.schedule();
   }
   /**
    * Brings the authored rows to the shape the APG requires, without changing
@@ -117,6 +198,9 @@ var DataGridController = class extends Controller {
   sort(event) {
     const header = event.currentTarget;
     if (!this.columnHeaderTargets.includes(header)) return;
+    if (event.defaultPrevented) return;
+    const control = this.#claimingControl(event, header);
+    if (control && !(control instanceof HTMLButtonElement)) return;
     const direction = nextSortDirection(header.getAttribute("aria-sort") ?? "none");
     for (const other of this.columnHeaderTargets) {
       other.setAttribute("aria-sort", other === header ? direction : "none");
@@ -127,14 +211,19 @@ var DataGridController = class extends Controller {
   /** Toggles selection of the row owning the event target. Bound optionally. */
   toggleSelect(event) {
     if (this.selectionValue === "none") return;
-    const row = event.currentTarget.closest("[role='row']");
+    if (event.defaultPrevented) return;
+    const host = event.currentTarget;
+    if (this.#claimedByDescendant(event, host)) return;
+    const row = host.closest("[role='row']");
     if (row && this.rowTargets.includes(row)) this.#toggleRow(row);
   }
   /** Grid navigation + sort/select activation. Bound to cells and headers. */
   onKeydown(event) {
     if (event.defaultPrevented) return;
     if (isReservedArrowChord(event)) return;
+    if (event.isComposing) return;
     const cell = event.currentTarget;
+    if (this.#claimedByDescendant(event, cell)) return;
     const matrix = this.#matrix();
     const position = this.#locate(matrix, cell);
     if (!position) return;
@@ -170,9 +259,35 @@ var DataGridController = class extends Controller {
     }
     if (target) {
       event.preventDefault();
-      this.#setActiveCell(target, { focus: true });
+      this.#setActiveCell(target, { focus: true }, matrix.flat());
     }
   }
+  /**
+   * Whether the event was addressed to a control inside `host` rather than to the
+   * grid.
+   *
+   * Cells and headers hold consumer markup, and APG's grid pattern expects that
+   * markup to include working controls — a row action button, an inline editor.
+   * Those own their own keystrokes and clicks, so the grid stands down entirely
+   * rather than acting in parallel. An editable host (its `contenteditable` state
+   * is inherited, so the walk is explicit) counts the same way.
+   */
+  #claimedByDescendant(event, host) {
+    return this.#claimingControl(event, host) !== null;
+  }
+  /**
+   * The nested control this event belongs to, or `null` when the host owns it.
+   *
+   * Naming the control, rather than answering yes or no, is what lets the click
+   * path treat a sortable header's `<button>` as the activation it is while every
+   * other control still takes the event away.
+   */
+  #claimingControl(event, host) {
+    const source = event.target;
+    const control = source.closest(INTERACTIVE_HOST_SELECTOR);
+    if (control && host.contains(control)) return control;
+    return isInteractiveHost(source) ? source : null;
+  }
   /** Performs a header's sort or a cell row's selection toggle on activation. */
   #activate(cell) {
     if (this.columnHeaderTargets.includes(cell)) {
@@ -203,11 +318,22 @@ var DataGridController = class extends Controller {
     const rows = this.rowTargets.filter((r) => r.getAttribute("aria-selected") === "true");
     this.dispatch("selectionchange", { detail: { rows } });
   }
-  /** Makes `cell` the single tabbable cell (roving) and optionally focuses it. */
-  #setActiveCell(cell, { focus }) {
-    if (!cell) return;
-    for (const candidate of this.#navigableCells()) {
-      candidate.tabIndex = candidate === cell ? 0 : -1;
+  /**
+   * Makes `cell` the single tabbable cell (roving) and optionally focuses it.
+   *
+   * `cells` lets a caller that already walked the grid hand its collection over,
+   * so one keystroke rebuilds the matrix once instead of twice. The write is
+   * skipped where the attribute already holds the wanted value — comparing the
+   * attribute rather than the IDL property, because a cell with no `tabindex` at
+   * all reports `-1` and would then never receive the attribute it needs to be
+   * focusable.
+   */
+  #setActiveCell(cell, { focus }, cells) {
+    for (const candidate of cells ?? this.#navigableCells()) {
+      const wanted = candidate === cell ? "0" : "-1";
+      if (candidate.getAttribute("tabindex") !== wanted) {
+        candidate.setAttribute("tabindex", wanted);
+      }
     }
     if (focus) cell.focus();
   }

data/dist/controllers/direct_upload_controller.js

@@ -111,10 +111,10 @@ var DirectUploadController = class extends Controller {
     announceErrorText: { type: String, default: "" },
     scope: { type: String, default: "" }
   };
-  static events = ["progress", "done", "error"];
+  static events = ["progress", "done", "error", "reconcile"];
   #timeouts = new SafeTimeout();
   #rows = /* @__PURE__ */ new Map();
-  #beforeCache = new BeforeCacheReset(() => this.#reset());
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
   /** The validated `scope` selector; a broken declaration falls back to `""`. */
   #scopeSelector = "";
   #onInitialize = (event) => {
@@ -314,6 +314,16 @@ var DirectUploadController = class extends Controller {
    * Returns the widget to its pre-upload state just before Turbo caches the
    * page, so the snapshot never replays rows for uploads that cannot resume.
    */
+  /**
+   * Rewinds for the snapshot and reports what that discarded. An upload in flight
+   * cannot survive the navigation, so a consumer mirroring the rows would keep a
+   * progress bar that never resolves.
+   */
+  #rewindForCache() {
+    const ids = [...this.#rows.keys()];
+    this.#reset();
+    if (ids.length > 0) this.dispatch("reconcile", { detail: { ids } });
+  }
   #reset() {
     for (const row of this.#rows.values()) row.remove();
     this.#rows.clear();

data/dist/controllers/editable_controller.js

@@ -55,33 +55,64 @@ var EditableController = class extends Controller {
   static values = {
     submitOnBlur: { type: Boolean, default: true }
   };
-  static actions = ["edit", "onBlur", "onDisplayKeydown", "onKeydown"];
+  static actions = ["cancel", "edit", "onDisplayKeydown", "onKeydown", "revert", "save"];
   static events = ["cancel", "change"];
   /** The value captured when edit mode began, used to detect real changes. */
   #previousValue = "";
+  /**
+   * The value the last save replaced, or `null` when there is nothing to undo.
+   * Cleared on connect: a value from before a page restore is unrecoverable, so
+   * `revert()` must not resurrect one.
+   */
+  #revertValue = null;
   /**
    * Owns IME lifecycle state for the edit surface, so a keydown that belongs to
    * a composition (cancel or confirm) is never treated as an edit command.
    */
   #composition = new CompositionTracker();
+  /**
+   * Watches focus leaving the editor from wherever it currently sits.
+   *
+   * `focusout` bubbles where `blur` does not, so one listener on the root sees
+   * every departure — including one from a Save or Cancel button the consumer
+   * placed beside the input. Binding the input alone would make the promise
+   * "saves wherever focus moved" true only for focus that leaves the input
+   * itself, and tabbing straight past an inner button would strand the editor
+   * open.
+   */
+  #onFocusOut = (event) => {
+    const from = event.target;
+    if (this.hasDisplayTarget && from instanceof Node && this.displayTarget.contains(from)) return;
+    const next = event.relatedTarget;
+    if (next instanceof Node && this.element.contains(next)) return;
+    if (this.submitOnBlurValue) this.#commit(false);
+  };
   /** Establishes the initial display mode (display shown, input hidden). */
   connect() {
     if (this.hasInputTarget) this.#composition.observe(this.inputTarget);
+    this.element.addEventListener("focusout", this.#onFocusOut);
+    this.#revertValue = null;
     this.#setMode("display");
   }
-  /** Releases the composition listeners so nothing outlives the element. */
+  /** Releases the composition and focus listeners so nothing outlives the element. */
   disconnect() {
     this.#composition.disconnect();
+    this.element.removeEventListener("focusout", this.#onFocusOut);
   }
   /** Tracks an input added initially or after connect (e.g. a Turbo swap). */
   inputTargetConnected(input) {
     this.#composition.observe(input);
+    this.#applyMode();
   }
   /** Removes composition listeners when the active input is replaced or removed. */
   inputTargetDisconnected(input) {
     this.#composition.unobserve(input);
   }
-  /** Enters edit mode: seeds the input from the display text, focuses, selects. */
+  /** Re-hides or re-shows a display element that arrived after the mode was set. */
+  displayTargetConnected() {
+    this.#applyMode();
+  }
+  /** Enters edit mode: seeds the input from the declared value, focuses, selects. */
   edit() {
     if (this.#isEditing || !this.hasInputTarget || !this.hasDisplayTarget) return;
     this.#previousValue = this.#currentValue;
@@ -90,6 +121,27 @@ var EditableController = class extends Controller {
     this.inputTarget.focus();
     this.inputTarget.select();
   }
+  /** Commits the edit and returns focus to the display element. */
+  save() {
+    this.#commit(true);
+  }
+  /** Discards edits, returns to display mode, and dispatches `cancel`. */
+  cancel() {
+    if (!this.#isEditing) return;
+    this.#setMode("display");
+    if (this.hasDisplayTarget) this.displayTarget.focus();
+    this.dispatch("cancel", { detail: {} });
+  }
+  /**
+   * Puts back the value the last save replaced — for a consumer whose server
+   * rejected it. Silent by design: a `change` here would re-enter the same
+   * handler that asked for the undo. One save, one undo.
+   */
+  revert() {
+    if (this.#revertValue === null || this.#isEditing) return;
+    this.#writeValue(this.#revertValue);
+    this.#revertValue = null;
+  }
   /** Adds `F2` as an editing entry point alongside the button's native activation. */
   onDisplayKeydown(event) {
     if (event.key === "F2") {
@@ -103,56 +155,57 @@ var EditableController = class extends Controller {
     if (event.key === "Escape") {
       if (event.defaultPrevented) return;
       event.preventDefault();
-      this.#cancel();
+      this.cancel();
       return;
     }
     if (event.key === "Enter") {
       if (event.defaultPrevented) return;
       if (this.#isMultiline && !(event.ctrlKey || event.metaKey)) return;
       event.preventDefault();
-      this.#save(true);
+      this.#commit(true);
     }
   }
-  /** Saves on blur when `submitOnBlur` is set; otherwise keeps editing. */
-  onBlur() {
-    if (!this.#isEditing) return;
-    if (this.submitOnBlurValue) this.#save(false);
-  }
   /**
-   * Returns to display mode, reflecting the input into the display text and
-   * dispatching `change` when the value differs from where editing began.
+   * Returns to display mode, storing the input's value and dispatching `change`
+   * when it differs from where editing began.
    *
    * @param restoreFocus - Move focus back to the display element (explicit
-   *   keyboard commit) rather than honoring the user's new focus target (blur).
+   *   commit) rather than honoring the user's new focus target (blur).
    */
-  #save(restoreFocus) {
-    if (!this.#isEditing) return;
-    const value = this.inputTarget.value;
+  #commit(restoreFocus) {
+    if (!this.#isEditing || !this.hasInputTarget) return;
+    const value = this.inputTarget.value.trim();
     const previous = this.#previousValue;
-    this.displayTarget.textContent = value;
+    this.#writeValue(value);
     this.#setMode("display");
-    if (restoreFocus) this.displayTarget.focus();
+    if (restoreFocus && this.hasDisplayTarget) this.displayTarget.focus();
     if (value !== previous) {
+      this.#revertValue = previous;
       this.dispatch("change", { detail: { value, previous } });
     }
   }
-  /** Discards edits, returns to display mode, and dispatches `cancel`. */
-  #cancel() {
-    if (!this.#isEditing) return;
-    this.#setMode("display");
-    this.displayTarget.focus();
-    this.dispatch("cancel", { detail: {} });
+  /** Stores `value` wherever the display element declares it. */
+  #writeValue(value) {
+    if (!this.hasDisplayTarget) return;
+    const display = this.displayTarget;
+    if (display.hasAttribute("data-value")) display.dataset.value = value;
+    else display.textContent = value;
   }
-  /** Toggles the `data-mode` flag and the `hidden` state of both elements. */
-  #setMode(mode) {
-    this.element.dataset.mode = mode;
-    const editing = mode === "editing";
+  /** Derives both elements' visibility from the mode currently in the DOM. */
+  #applyMode() {
+    const editing = this.#isEditing;
     if (this.hasDisplayTarget) this.displayTarget.hidden = editing;
     if (this.hasInputTarget) this.inputTarget.hidden = !editing;
   }
-  /** Current display text, trimmed — the value shown when not editing. */
+  /** Records the mode, then brings both elements in line with it. */
+  #setMode(mode) {
+    this.element.dataset.mode = mode;
+    this.#applyMode();
+  }
+  /** The value the display element declares, trimmed. */
   get #currentValue() {
-    return (this.displayTarget.textContent ?? "").trim();
+    const display = this.displayTarget;
+    return (display.dataset.value ?? display.textContent ?? "").trim();
   }
   /** Whether the editing control is a multi-line `<textarea>`. */
   get #isMultiline() {