stimeo-ui 0.15.0 → 0.16.0

package/dist/controllers/data_grid_controller.d.ts

@@ -6,14 +6,16 @@ import { Controller } from '@hotwired/stimulus';
  *
  * Markup contract (identifier: `stimeo--data-grid`):
  *   <table data-controller="stimeo--data-grid" role="grid" aria-label="Users"
- *          data-stimeo--data-grid-selection-value="single">
+ *          data-stimeo--data-grid-selection-value="single"
+ *          data-stimeo--data-grid-name-value="user_id">
+ *     <caption><div data-stimeo--data-grid-target="fields"></div></caption>
  *     <thead><tr role="row">
  *       <th role="columnheader" aria-sort="none" tabindex="-1"
  *           data-stimeo--data-grid-target="columnHeader"
  *           data-action="click->stimeo--data-grid#sort
  *                        keydown->stimeo--data-grid#onKeydown">Name</th>
  *     </tr></thead>
- *     <tbody><tr role="row" aria-selected="false"
+ *     <tbody><tr role="row" aria-selected="false" data-value="7"
  *                data-stimeo--data-grid-target="row">
  *       <td role="gridcell" tabindex="0" data-stimeo--data-grid-target="cell"
  *           data-action="keydown->stimeo--data-grid#onKeydown">Jane</td>
@@ -25,15 +27,38 @@ import { Controller } from '@hotwired/stimulus';
  * `-1`); arrow keys move both DOM focus and that tabbable position. Sort state is
  * exposed via `aria-sort` on headers, selection via `aria-selected` on rows.
  *
- * `selectionchange` dispatches `{ rows: HTMLElement[] }`; `sort` dispatches
+ * `selectionchange` dispatches `{ rows: HTMLElement[] }` when the user changes the
+ * selection; `sort` dispatches
  * `{ column: HTMLElement, direction: "ascending" | "descending" | "none" }`.
  *
+ * `reconcile` dispatches `{ rows: HTMLElement[] }` — the selected rows, as
+ * `selectionchange` carries them — when the page moves the selection instead: a
+ * selected row removed or dropped from the targets, a morph or a script writing
+ * a row's `aria-selected` or a selected row's `data-value`, a selected row that
+ * arrives ahead of the selection in `single` mode, or a runtime `selection` that
+ * collapses it. One batch of such changes reports once, and only when the
+ * selected rows or the values they submit differ from the selection last settled
+ * — on connect, by the user, or by the previous `reconcile` — so connecting
+ * reports nothing.
+ *
+ * With a `fields` target the selected rows are mirrored into `name`d hidden
+ * inputs so the selection can be submitted and read server-side — one per
+ * selected row that carries a `data-value`, in DOM order; a row without one
+ * submits nothing. `form` points them at a `<form>` by id when the container
+ * sits outside it. A selection the user made emits a native bubbling `change`
+ * from the container, the way a form control does, so `stimeo--auto-submit` and
+ * form-level validation hear it. The mirror is refreshed silently on connect,
+ * on a replacement container, on row churn, and whenever `selection`, `name` or
+ * `form` changes; a selection the page moved is reported by `reconcile` alone.
+ *
  * @remarks
  * Behavior only — the consumer performs the actual data sort/render in response to
- * the `sort` event and owns all styling. No timers or observers are held, so there
- * is nothing to leak across Turbo navigations; `connect()` rebuilds the single tab
- * stop idempotently from the DOM, and the target callbacks rebuild it again after
- * rows or cells are added or removed at runtime.
+ * the `sort` event and owns all styling. While connected a `MutationObserver`
+ * watches the rows' `aria-selected` and `data-value`, which a morph can rewrite
+ * without adding or removing a target; `disconnect()` releases it and drops a
+ * pending pass. `connect()` rebuilds the single tab stop idempotently from the
+ * DOM, and the target callbacks rebuild it again after rows or cells are added or
+ * removed at runtime.
  *
  * Behavior provided:
  * - `Arrow*` move between cells (clamped at edges); `Home`/`End` to the row's
@@ -62,33 +87,53 @@ declare class DataGridController extends Controller<HTMLElement> {
             type: StringConstructor;
             default: string;
         };
+        name: {
+            type: StringConstructor;
+            default: string;
+        };
+        form: {
+            type: StringConstructor;
+            default: string;
+        };
     };
     static actions: readonly ["onKeydown", "sort", "toggleSelect"];
-    static events: readonly ["selectionchange", "sort"];
+    static events: readonly ["selectionchange", "sort", "reconcile"];
     readonly columnHeaderTargets: HTMLElement[];
     readonly rowTargets: HTMLElement[];
     readonly cellTargets: HTMLElement[];
+    readonly fieldsTarget: HTMLElement;
+    readonly hasFieldsTarget: boolean;
     selectionValue: string;
+    nameValue: string;
+    formValue: string;
     /**
-     * Establishes a single tab stop across all navigable cells/headers and brings
-     * the rows to their baseline.
+     * Establishes a single tab stop across all navigable cells/headers, brings the
+     * rows to their baseline, and settles the selection without reporting it.
      *
-     * Normalizing here rather than leaving it to {@link selectionValueChanged}
-     * guarantees exactly one pass per mount: a re-attached element reuses its
-     * cached Stimulus context, whose value observer already knows the `selection`
-     * attribute, so the Value callback does not fire a second time.
+     * The whole baseline runs here rather than in the Value callbacks: Stimulus
+     * delivers those before `connect()`, where the pass is refused, and a
+     * re-attached element reuses its cached context, whose value observer does not
+     * fire again.
      */
     connect(): void;
-    /** Closes the reconcile window so a queued pass cannot run against a detached tree. */
+    /** Releases the row observer and drops a queued pass, so neither outlives the element. */
     disconnect(): void;
     /**
-     * Keeps `aria-multiselectable` in step with the `selection` Value. Fires on connect
-     * (so it self-heals after a Turbo morph) and on any runtime change, so the ARIA
-     * never drifts from the selection logic, which reads `selectionValue` live.
+     * Re-renders `aria-multiselectable`, the rows and the fields when application
+     * code (or a Turbo morph) changes `selection` at runtime; a selection the new
+     * mode collapses is reported as `reconcile`.
      */
     selectionValueChanged(): void;
+    /** Rebuilds the submitted fields when the public name changes at runtime. */
+    nameValueChanged(): void;
+    /** Repoints the submitted fields when the owning form changes at runtime. */
+    formValueChanged(): void;
+    /** Seeds a fields container inserted after connect from the current selection. */
+    fieldsTargetConnected(): void;
     /** Re-establishes the baselines for a row added after connect. */
     rowTargetConnected(): void;
+    /** Settles the selection again when a row leaves the grid or drops its target token. */
+    rowTargetDisconnected(): void;
     /** Re-establishes the tab stop when a cell joins the grid after connect. */
     cellTargetConnected(): void;
     /** Re-establishes the tab stop when a cell leaves the grid. */

package/dist/controllers/data_grid_controller.js

@@ -18,6 +18,29 @@ 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 writeFields(container, values, { name, form = "" }) {
+  const current = [...container.children];
+  const submits = current.length === values.length && current.every(
+    (child, index) => child instanceof HTMLInputElement && child.type === "hidden" && child.value === values[index] && child.name === name && (child.getAttribute("form") ?? "") === form
+  );
+  if (submits) return false;
+  container.replaceChildren(
+    ...values.map((value) => {
+      const input = document.createElement("input");
+      input.type = "hidden";
+      input.name = name;
+      input.value = value;
+      if (form !== "") input.setAttribute("form", form);
+      return input;
+    })
+  );
+  return true;
+}
+function commitField(target) {
+  target.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
 // 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) {
@@ -70,48 +93,71 @@ var MicrotaskCoalescer = class {
 
 // src/controllers/data_grid_controller.ts
 var SORT_CYCLE = ["none", "ascending", "descending"];
+var OBSERVED_ATTRIBUTES = ["aria-selected", "data-value"];
+function setAttributeIfChanged(element, name, value) {
+  if (element.getAttribute(name) !== value) element.setAttribute(name, value);
+}
+function sameSelection(a, b) {
+  if (a.size !== b.size) return false;
+  for (const [row, value] of a) {
+    if (!b.has(row) || b.get(row) !== value) return false;
+  }
+  return true;
+}
 function nextSortDirection(current) {
   const index = SORT_CYCLE.indexOf(current);
   const from = index < 0 ? 0 : index;
   return SORT_CYCLE[(from + 1) % SORT_CYCLE.length] ?? "ascending";
 }
 var DataGridController = class extends Controller {
-  static targets = ["columnHeader", "row", "cell"];
+  static targets = ["columnHeader", "row", "cell", "fields"];
   static values = {
-    selection: { type: String, default: "none" }
+    selection: { type: String, default: "none" },
+    name: { type: String, default: "rows[]" },
+    form: { type: String, default: "" }
   };
   static actions = ["onKeydown", "sort", "toggleSelect"];
-  static events = ["selectionchange", "sort"];
+  static events = ["selectionchange", "sort", "reconcile"];
   /**
-   * Collapses the per-element target callbacks of one DOM mutation into a single
-   * baseline pass, and refuses to run before `connect()` or after `disconnect()`.
+   * Collapses the target callbacks, Value changes and observed row writes of one
+   * DOM mutation into a single 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());
+  #reconcile = new MicrotaskCoalescer(() => this.#reconcileRows());
+  /** Watches the row 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 = /* @__PURE__ */ new Map();
   /**
-   * Establishes a single tab stop across all navigable cells/headers and brings
-   * the rows to their baseline.
+   * Establishes a single tab stop across all navigable cells/headers, brings the
+   * rows to their baseline, and settles the selection without reporting it.
    *
-   * Normalizing here rather than leaving it to {@link selectionValueChanged}
-   * guarantees exactly one pass per mount: a re-attached element reuses its
-   * cached Stimulus context, whose value observer already knows the `selection`
-   * attribute, so the Value callback does not fire a second time.
+   * The whole baseline runs here rather than in the Value callbacks: Stimulus
+   * delivers those before `connect()`, where the pass is refused, and a
+   * re-attached element reuses its cached context, whose value observer does not
+   * fire again.
    */
   connect() {
     this.#restoreBaseline();
+    this.#settled = this.#selection();
     this.#reconcile.activate();
+    this.#observeRows();
   }
-  /** Closes the reconcile window so a queued pass cannot run against a detached tree. */
+  /** Releases the row observer and drops a queued pass, so neither outlives the element. */
   disconnect() {
     this.#reconcile.cancel();
+    this.#observer?.disconnect();
+    this.#observer = null;
   }
   /**
-   * 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`.
+   * Rebuilds the DOM-owned baselines from the live grid: exactly one navigable
+   * cell is in the Tab sequence, `aria-multiselectable` follows `selection`, every
+   * selectable row carries an explicit `aria-selected`, and the fields mirror the
+   * selected rows.
    *
    * 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
@@ -124,21 +170,60 @@ var DataGridController = class extends Controller {
     const cells = this.#navigableCells();
     const active = cells.find((cell) => cell.tabIndex === 0) ?? cells[0];
     if (active) this.#setActiveCell(active, { focus: false }, cells);
+    this.#syncSelectable();
+    const pageWrote = this.#takePageRecords();
     this.#normalizeSelection();
+    this.#dropOwnRecords(pageWrote);
+    this.#mirrorFields(false);
+  }
+  /**
+   * The pass the page's changes run: the baselines are rebuilt, then a selection
+   * that moved is reported. The report comes last, so rows a subscriber rewrites
+   * are the next pass's to settle.
+   */
+  #reconcileRows() {
+    this.#restoreBaseline();
+    this.#reportMove();
+  }
+  /**
+   * Reports the selection as `reconcile` when it differs from the one 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 (sameSelection(selection, this.#settled)) return;
+    this.#settled = selection;
+    this.dispatch("reconcile", { detail: { rows: [...selection.keys()] } });
   }
   /**
-   * Keeps `aria-multiselectable` in step with the `selection` Value. Fires on connect
-   * (so it self-heals after a Turbo morph) and on any runtime change, so the ARIA
-   * never drifts from the selection logic, which reads `selectionValue` live.
+   * Re-renders `aria-multiselectable`, the rows and the fields when application
+   * code (or a Turbo morph) changes `selection` at runtime; a selection the new
+   * mode collapses is reported as `reconcile`.
    */
   selectionValueChanged() {
-    this.#syncSelectable();
-    this.#normalizeSelection();
+    this.#reconcile.schedule();
+  }
+  /** Rebuilds the submitted fields when the public name changes at runtime. */
+  nameValueChanged() {
+    this.#reconcile.schedule();
+  }
+  /** Repoints the submitted fields when the owning form changes at runtime. */
+  formValueChanged() {
+    this.#reconcile.schedule();
+  }
+  /** Seeds a fields container inserted after connect from the current selection. */
+  fieldsTargetConnected() {
+    this.#reconcile.schedule();
   }
   /** Re-establishes the baselines for a row added after connect. */
   rowTargetConnected() {
     this.#reconcile.schedule();
   }
+  /** Settles the selection again when a row leaves the grid or drops its target token. */
+  rowTargetDisconnected() {
+    this.#reconcile.schedule();
+  }
   /** Re-establishes the tab stop when a cell joins the grid after connect. */
   cellTargetConnected() {
     this.#reconcile.schedule();
@@ -165,6 +250,8 @@ var DataGridController = class extends Controller {
    * A grid that declares `selection="none"` has no selectable rows, so the
    * attribute is removed rather than written: in ARIA its absence is what "not
    * selectable" looks like.
+   *
+   * @stimeoRenderRoot
    */
   #normalizeSelection() {
     const rows = this.rowTargets;
@@ -176,9 +263,9 @@ var DataGridController = class extends Controller {
     const first = rows.find((row) => row.getAttribute("aria-selected") === "true");
     for (const row of rows) {
       if (single) {
-        row.setAttribute("aria-selected", row === first ? "true" : "false");
+        setAttributeIfChanged(row, "aria-selected", row === first ? "true" : "false");
       } else if (row.getAttribute("aria-selected") !== "true") {
-        row.setAttribute("aria-selected", "false");
+        setAttributeIfChanged(row, "aria-selected", "false");
       }
     }
   }
@@ -186,10 +273,12 @@ var DataGridController = class extends Controller {
    * Mirrors `selection="multiple"` onto `aria-multiselectable` (APG Grid) so SRs
    * announce that more than one row can be selected; cleared for single/none so a
    * grid never carries a misleading attribute.
+   *
+   * @stimeoRenderRoot
    */
   #syncSelectable() {
     if (this.selectionValue === "multiple") {
-      this.element.setAttribute("aria-multiselectable", "true");
+      setAttributeIfChanged(this.element, "aria-multiselectable", "true");
     } else {
       this.element.removeAttribute("aria-multiselectable");
     }
@@ -288,7 +377,12 @@ var DataGridController = class extends Controller {
     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. */
+  /**
+   * Performs a header's sort or a cell row's selection toggle on activation.
+   *
+   * @stimeoRuntimeOnly `selection` decides whether this one activation toggles the row; the sort it
+   *   cycles does not depend on it.
+   */
   #activate(cell) {
     if (this.columnHeaderTargets.includes(cell)) {
       this.#cycleSort(cell);
@@ -306,17 +400,89 @@ var DataGridController = class extends Controller {
     }
     this.dispatch("sort", { detail: { column: header, direction } });
   }
-  /** Toggles a row's `aria-selected`, honoring single vs. multiple selection. */
+  /**
+   * Toggles a row's `aria-selected`, honoring single vs. multiple selection.
+   *
+   * @stimeoRuntimeOnly `selection` decides how this one toggle treats the other rows.
+   */
   #toggleRow(row) {
     const selected = row.getAttribute("aria-selected") === "true";
+    const pageWrote = this.#takePageRecords();
     if (this.selectionValue === "single") {
       for (const other of this.rowTargets) {
-        if (other !== row) other.setAttribute("aria-selected", "false");
+        if (other !== row) setAttributeIfChanged(other, "aria-selected", "false");
       }
     }
     row.setAttribute("aria-selected", selected ? "false" : "true");
-    const rows = this.rowTargets.filter((r) => r.getAttribute("aria-selected") === "true");
-    this.dispatch("selectionchange", { detail: { rows } });
+    this.#dropOwnRecords(pageWrote);
+    this.#settled = this.#selection();
+    this.#mirrorFields(true);
+    this.dispatch("selectionchange", { detail: { rows: [...this.#settled.keys()] } });
+  }
+  /** The selected rows in DOM order, each with the `data-value` it submits, if any. */
+  #selection() {
+    return new Map(
+      this.rowTargets.filter((row) => row.getAttribute("aria-selected") === "true").map((row) => [row, row.dataset.value])
+    );
+  }
+  /**
+   * Watches the rows' `aria-selected` and `data-value`. Every write the grid makes
+   * to them sits between a take and a drop of the observer's queue, so each record
+   * the callback receives is the page's, and only a record on one of the grid's own
+   * rows schedules a pass.
+   */
+  #observeRows() {
+    const observer = new MutationObserver((records) => {
+      if (this.#concernsRows(records)) this.#reconcile.schedule();
+    });
+    observer.observe(this.element, {
+      subtree: true,
+      attributes: true,
+      attributeFilter: OBSERVED_ATTRIBUTES
+    });
+    this.#observer = observer;
+  }
+  /**
+   * Empties the observer's queue before the grid writes to the rows, and says
+   * whether the page had queued anything about them. Those records still owe a
+   * pass: a toggle in `multiple` mode rewrites only its own row, so it does not fold
+   * in what the page wrote to the others.
+   */
+  #takePageRecords() {
+    const records = this.#observer?.takeRecords() ?? [];
+    return records.length > 0 && this.#concernsRows(records);
+  }
+  /**
+   * Whether any record is about one of this grid's own rows. A widget nested in a
+   * cell writes the same attributes on its own elements, and those are no reason
+   * to reconcile the grid.
+   */
+  #concernsRows(records) {
+    const rows = new Set(this.rowTargets);
+    return records.some((record) => rows.has(record.target));
+  }
+  /**
+   * Drops the records the grid's own writes just queued, so the observer never
+   * takes them for the page's, then schedules the pass the page's records owe.
+   */
+  #dropOwnRecords(pageWrote) {
+    this.#observer?.takeRecords();
+    if (pageWrote) this.#reconcile.schedule();
+  }
+  /**
+   * Mirrors the selected rows' `data-value` into the optional fields container.
+   * A selected row without one submits nothing, so a grid whose rows carry no
+   * value submits an empty set rather than a row of blanks.
+   *
+   * @stimeoRenderRoot
+   */
+  #mirrorFields(notify) {
+    if (!this.hasFieldsTarget) return;
+    const values = this.rowTargets.filter((row) => row.getAttribute("aria-selected") === "true").map((row) => row.dataset.value).filter((value) => value !== void 0);
+    const options = { name: this.nameValue, form: this.formValue };
+    if (writeFields(this.fieldsTarget, values, options) && notify) {
+      commitField(this.fieldsTarget);
+    }
   }
   /**
    * Makes `cell` the single tabbable cell (roving) and optionally focuses it.