stimeo-ui 0.7.0 → 0.9.0

package/dist/controllers/masonry_controller.js

@@ -58,16 +58,72 @@ var LayoutObserver = class {
   }
 };
 
+// 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/masonry_controller.ts
 var COLUMNS_PROPERTY = "--stimeo--masonry-columns";
+var DEFAULT_MIN_COLUMN_WIDTH = 240;
+var DEFAULT_GAP = 16;
+function usableNumber(value, fallback) {
+  return Number.isFinite(value) ? value : fallback;
+}
 var MasonryController = class extends Controller {
   static targets = ["item"];
   static values = {
-    minColumnWidth: { type: Number, default: 240 },
-    gap: { type: Number, default: 16 }
+    minColumnWidth: { type: Number, default: DEFAULT_MIN_COLUMN_WIDTH },
+    gap: { type: Number, default: DEFAULT_GAP }
   };
   static events = ["layout"];
-  #layout = new LayoutObserver(() => this.#relayout());
+  /**
+   * The declared numbers after validation, so the layout path never sees a value
+   * it cannot compute with. Both are resolved once per declaration change rather
+   * than on every pass.
+   */
+  #minColumnWidth = DEFAULT_MIN_COLUMN_WIDTH;
+  #gap = DEFAULT_GAP;
+  /**
+   * Collapses every re-layout trigger of one DOM mutation into a single pass, and
+   * refuses to run before `connect()` or after `disconnect()`.
+   *
+   * The triggers arrive in bursts — a resize stream, a morph that syncs several
+   * attributes, a batch of rows — and each pass measures every item, so folding
+   * them keeps the work proportional to the batch rather than to the events in it.
+   */
+  #reconcile = new MicrotaskCoalescer(() => this.#relayout());
+  /** Items that left the target set and still carry the column hook. */
+  #released = /* @__PURE__ */ new Set();
+  #layout = new LayoutObserver(() => this.#reconcile.schedule());
   #mutationObserver = null;
   /** Last published column count, so `layout` fires only on real changes. */
   #lastColumns = 0;
@@ -77,20 +133,49 @@ var MasonryController = class extends Controller {
    * first pass ran before they settled; `load` does not bubble, so this is bound in
    * the capture phase to catch every descendant.
    */
-  #onLoad = () => this.#relayout();
+  #onLoad = () => this.#reconcile.schedule();
+  /** Resolves the declared column width once, falling back when it is unreadable. */
+  minColumnWidthValueChanged() {
+    this.#minColumnWidth = usableNumber(this.minColumnWidthValue, DEFAULT_MIN_COLUMN_WIDTH);
+    this.#reconcile.schedule();
+  }
+  /** Resolves the declared gap once, falling back when it is unreadable. */
+  gapValueChanged() {
+    this.#gap = usableNumber(this.gapValue, DEFAULT_GAP);
+    this.#reconcile.schedule();
+  }
+  /** Packs an element that became an item without moving in the DOM. */
+  itemTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /**
+   * Queues the column hook of an element that stopped being an item for removal.
+   *
+   * The removal is queued rather than immediate because teardown reports every
+   * target as disconnected: doing it here would strip the whole grid just before
+   * a Turbo snapshot is taken. {@link MicrotaskCoalescer.cancel} drops the queue
+   * with the pass, so only a genuine target change reaches it.
+   */
+  itemTargetDisconnected(item) {
+    this.#released.add(item);
+    this.#reconcile.schedule();
+  }
   /** Observes size/content changes and performs the first layout pass. */
   connect() {
     this.#layout.observe(this.element);
     this.#layout.observeViewport();
     if (typeof MutationObserver !== "undefined") {
-      this.#mutationObserver = new MutationObserver(() => this.#relayout());
+      this.#mutationObserver = new MutationObserver(() => this.#reconcile.schedule());
       this.#mutationObserver.observe(this.element, { childList: true, subtree: true });
     }
     this.element.addEventListener("load", this.#onLoad, true);
     this.#relayout();
+    this.#reconcile.activate();
   }
   /** Releases both observers and the load listener so nothing fires after detach. */
   disconnect() {
+    this.#reconcile.cancel();
+    this.#released.clear();
     this.#layout.disconnect();
     this.#mutationObserver?.disconnect();
     this.#mutationObserver = null;
@@ -99,26 +184,53 @@ var MasonryController = class extends Controller {
   }
   /**
    * Recomputes the column count and assigns every item to the shortest column.
-   * Runs automatically on connect, on resize, on item add/remove, and when a
-   * descendant resource loads (private — there is no public action; the observers
-   * and the capture-phase `load` listener drive it). Items are walked in DOM
-   * order; each lands in the column with the least accumulated height, which
-   * keeps the packing balanced without reordering the DOM.
+   * Runs automatically on connect, on resize, on item add/remove, when a declared
+   * number changes, and when a descendant resource loads (private — there is no
+   * public action; the observers, the target callbacks and the capture-phase
+   * `load` listener drive it). Items are walked in DOM order; each lands in the
+   * column with the least accumulated height, which keeps the packing balanced
+   * without reordering the DOM.
+   *
+   * Every box is measured before anything is written. Interleaving the two would
+   * make a consumer's `data-column` rule invalidate style once per item, and the
+   * next measurement then has to settle layout again — once per item instead of
+   * once per pass. The assignment is independent of the measurement because the
+   * columns are uniform in width, so the order of the two passes does not change
+   * the result.
+   *
+   * @stimeoRenderRoot
    */
   #relayout() {
     const items = this.itemTargets;
     const columns = this.#columnCount();
+    const boxes = items.map((item) => item.getBoundingClientRect().height);
+    let changed = false;
+    if (this.#released.size > 0) {
+      const owned = new Set(items);
+      for (const released of this.#released) {
+        if (owned.has(released)) continue;
+        if (released.hasAttribute("data-column")) {
+          released.removeAttribute("data-column");
+          changed = true;
+        }
+      }
+      this.#released.clear();
+    }
     const heights = new Array(columns).fill(0);
-    for (const item of items) {
+    items.forEach((item, index) => {
       let shortest = 0;
       for (let col = 1; col < columns; col++) {
         if ((heights[col] ?? 0) < (heights[shortest] ?? 0)) shortest = col;
       }
-      item.setAttribute("data-column", String(shortest));
-      heights[shortest] = (heights[shortest] ?? 0) + item.getBoundingClientRect().height + this.gapValue;
-    }
+      const assigned = String(shortest);
+      if (item.getAttribute("data-column") !== assigned) {
+        item.setAttribute("data-column", assigned);
+        changed = true;
+      }
+      heights[shortest] = (heights[shortest] ?? 0) + (boxes[index] ?? 0) + this.#gap;
+    });
     this.element.style.setProperty(COLUMNS_PROPERTY, String(columns));
-    if (columns !== this.#lastColumns) {
+    if (columns !== this.#lastColumns || changed) {
       this.#lastColumns = columns;
       this.dispatch("layout", { detail: { columns } });
     }
@@ -131,9 +243,9 @@ var MasonryController = class extends Controller {
    */
   #columnCount() {
     const width = this.element.getBoundingClientRect().width;
-    const denominator = this.minColumnWidthValue + this.gapValue;
+    const denominator = this.#minColumnWidth + this.#gap;
     if (width <= 0 || denominator <= 0) return 1;
-    return Math.max(1, Math.floor((width + this.gapValue) / denominator));
+    return Math.max(1, Math.floor((width + this.#gap) / denominator));
   }
 };
 

package/dist/controllers/masonry_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/layout_observer.ts","../../src/controllers/masonry_controller.ts"],"names":[],"mappings":"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","file":"masonry_controller.js","sourcesContent":["/**\n * Unified element-size and viewport observation for Stimeo controllers.\n *\n * Layout-sensitive widgets (sliders, resizable panes, scroll spies, popovers)\n * need to react both to their *own* box changing — via {@link ResizeObserver} —\n * and to the *viewport* changing — via the `window` `resize` event. Wiring those\n * two sources by hand in every controller risks leaked listeners on\n * `disconnect()`. {@link LayoutObserver} owns both behind one callback and one\n * {@link LayoutObserver.disconnect | disconnect()} that releases everything.\n *\n * Behavior only: the helper reports *that* layout changed; it never reads or\n * writes styles. Consumers decide what to recompute.\n */\n\n/** Invoked whenever an observed element or the viewport changes size. */\nexport type LayoutCallback = () => void;\n\n/** Constructs a {@link ResizeObserver}; injectable so tests stay deterministic. */\nexport type ResizeObserverFactory = (callback: ResizeObserverCallback) => ResizeObserver;\n\n/** Options for {@link LayoutObserver}. */\nexport interface LayoutObserverOptions {\n  /**\n   * Factory for the {@link ResizeObserver} used by {@link LayoutObserver.observe}.\n   * Defaults to the global constructor; override it in tests, or to no-op in\n   * environments where `ResizeObserver` is unavailable.\n   */\n  resizeObserverFactory?: ResizeObserverFactory;\n}\n\n/**\n * Observes element resizes and/or viewport resizes through a single callback,\n * with guaranteed teardown.\n *\n * @example\n * ```ts\n * #layout = new LayoutObserver(() => this.#reposition());\n *\n * connect() {\n *   this.#layout.observe(this.panelTarget);\n *   this.#layout.observeViewport();\n * }\n *\n * disconnect() {\n *   this.#layout.disconnect();\n * }\n * ```\n */\nexport class LayoutObserver {\n  readonly #callback: LayoutCallback;\n  readonly #resizeObserverFactory: ResizeObserverFactory | null;\n  #resizeObserver: ResizeObserver | null = null;\n  #observingViewport = false;\n\n  /** Stable bound handler so add/removeEventListener target the same reference. */\n  readonly #handleViewportResize = (): void => {\n    this.#callback();\n  };\n\n  constructor(callback: LayoutCallback, options: LayoutObserverOptions = {}) {\n    this.#callback = callback;\n    this.#resizeObserverFactory =\n      options.resizeObserverFactory ??\n      (typeof ResizeObserver === \"undefined\" ? null : (cb) => new ResizeObserver(cb));\n  }\n\n  /**\n   * Starts observing an element's size. Repeated calls observe additional\n   * elements through the same shared observer. No-ops when no\n   * `ResizeObserver` implementation is available.\n   */\n  observe(element: Element): void {\n    if (!this.#resizeObserverFactory) return;\n    if (!this.#resizeObserver) {\n      this.#resizeObserver = this.#resizeObserverFactory(() => {\n        this.#callback();\n      });\n    }\n    this.#resizeObserver.observe(element);\n  }\n\n  /** Stops observing a single element while leaving any others in place. */\n  unobserve(element: Element): void {\n    this.#resizeObserver?.unobserve(element);\n  }\n\n  /** Starts observing viewport resizes. Idempotent: the listener is added once. */\n  observeViewport(): void {\n    if (this.#observingViewport) return;\n    this.#observingViewport = true;\n    window.addEventListener(\"resize\", this.#handleViewportResize);\n  }\n\n  /** Stops observing viewport resizes without affecting element observation. */\n  unobserveViewport(): void {\n    if (!this.#observingViewport) return;\n    this.#observingViewport = false;\n    window.removeEventListener(\"resize\", this.#handleViewportResize);\n  }\n\n  /**\n   * Releases every observation: disconnects the {@link ResizeObserver} and\n   * removes the viewport listener. Safe to call multiple times. Call this from a\n   * controller's `disconnect()`.\n   */\n  disconnect(): void {\n    this.#resizeObserver?.disconnect();\n    this.#resizeObserver = null;\n    this.unobserveViewport();\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { LayoutObserver } from \"../utils/layout_observer\";\n\n/** CSS custom property exposing the current column count to consumer CSS. */\nconst COLUMNS_PROPERTY = \"--stimeo--masonry-columns\";\n\n/**\n * Headless **Masonry** layout helper: assigns each item to the shortest column so\n * variable-height cards pack without vertical gaps. There is no APG widget — this\n * is a layout-only utility that emits state hooks, never visual structure.\n *\n * Markup contract (identifier: `stimeo--masonry`):\n *   <div data-controller=\"stimeo--masonry\"\n *        data-stimeo--masonry-min-column-width-value=\"240\"\n *        data-stimeo--masonry-gap-value=\"16\">\n *     <div data-stimeo--masonry-target=\"item\">…</div>\n *     <div data-stimeo--masonry-target=\"item\">…</div>\n *   </div>\n *\n * The column count is derived responsively from the container width and\n * `minColumnWidth`; each item is then placed into whichever column is currently\n * shortest (measured from item heights). The count is published on the controller\n * element as the `--stimeo--masonry-columns` custom property and each item gets a\n * `data-column` index, so the consumer's CSS owns the actual placement.\n *\n * `layout` dispatches `{ columns: number }`.\n *\n * @remarks\n * Behavior only. **DOM order is never changed** — reading order and focus order\n * stay the source markup order (WCAG 1.3.2). The visual packing is purely the\n * column assignment a consumer reads from `data-column`; this controller writes no\n * positioning styles. Re-layout runs on connect, on resize ({@link LayoutObserver}),\n * and on item add/remove ({@link MutationObserver}); both observers are released on\n * `disconnect()` (Turbo navigation included). Use only for independent cards whose\n * visual order carries no meaning.\n */\nexport class MasonryController extends Controller<HTMLElement> {\n  static override targets = [\"item\"];\n  static override values = {\n    minColumnWidth: { type: Number, default: 240 },\n    gap: { type: Number, default: 16 },\n  };\n  static events = [\"layout\"] as const;\n\n  declare readonly itemTargets: HTMLElement[];\n  declare minColumnWidthValue: number;\n  declare gapValue: number;\n\n  readonly #layout = new LayoutObserver(() => this.#relayout());\n  #mutationObserver: MutationObserver | null = null;\n  /** Last published column count, so `layout` fires only on real changes. */\n  #lastColumns = 0;\n\n  /**\n   * Re-pack when a descendant resource finishes loading. Images/iframes report a\n   * height of 0 until loaded, which would skew the shortest-column packing if the\n   * first pass ran before they settled; `load` does not bubble, so this is bound in\n   * the capture phase to catch every descendant.\n   */\n  readonly #onLoad = (): void => this.#relayout();\n\n  /** Observes size/content changes and performs the first layout pass. */\n  override connect(): void {\n    this.#layout.observe(this.element);\n    this.#layout.observeViewport();\n\n    if (typeof MutationObserver !== \"undefined\") {\n      this.#mutationObserver = new MutationObserver(() => this.#relayout());\n      this.#mutationObserver.observe(this.element, { childList: true, subtree: true });\n    }\n    this.element.addEventListener(\"load\", this.#onLoad, true);\n    this.#relayout();\n  }\n\n  /** Releases both observers and the load listener so nothing fires after detach. */\n  override disconnect(): void {\n    this.#layout.disconnect();\n    this.#mutationObserver?.disconnect();\n    this.#mutationObserver = null;\n    this.element.removeEventListener(\"load\", this.#onLoad, true);\n    this.#lastColumns = 0;\n  }\n\n  /**\n   * Recomputes the column count and assigns every item to the shortest column.\n   * Runs automatically on connect, on resize, on item add/remove, and when a\n   * descendant resource loads (private — there is no public action; the observers\n   * and the capture-phase `load` listener drive it). Items are walked in DOM\n   * order; each lands in the column with the least accumulated height, which\n   * keeps the packing balanced without reordering the DOM.\n   */\n  #relayout(): void {\n    const items = this.itemTargets;\n    const columns = this.#columnCount();\n\n    const heights = new Array<number>(columns).fill(0);\n    for (const item of items) {\n      let shortest = 0;\n      for (let col = 1; col < columns; col++) {\n        if ((heights[col] ?? 0) < (heights[shortest] ?? 0)) shortest = col;\n      }\n      item.setAttribute(\"data-column\", String(shortest));\n      heights[shortest] =\n        (heights[shortest] ?? 0) + item.getBoundingClientRect().height + this.gapValue;\n    }\n\n    this.element.style.setProperty(COLUMNS_PROPERTY, String(columns));\n\n    if (columns !== this.#lastColumns) {\n      this.#lastColumns = columns;\n      this.dispatch(\"layout\", { detail: { columns } });\n    }\n  }\n\n  /**\n   * Derives how many columns fit: `floor((width + gap) / (minColumnWidth + gap))`,\n   * never fewer than one. When the width is unmeasurable (detached, or a layout\n   * engine that reports `0`), it falls back to a single column so every item still\n   * gets a valid `data-column`.\n   */\n  #columnCount(): number {\n    const width = this.element.getBoundingClientRect().width;\n    const denominator = this.minColumnWidthValue + this.gapValue;\n    if (width <= 0 || denominator <= 0) return 1;\n    return Math.max(1, Math.floor((width + this.gapValue) / denominator));\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/layout_observer.ts","../../src/utils/microtask_coalescer.ts","../../src/controllers/masonry_controller.ts"],"names":[],"mappings":"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","file":"masonry_controller.js","sourcesContent":["/**\n * Unified element-size and viewport observation for Stimeo controllers.\n *\n * Layout-sensitive widgets (sliders, resizable panes, scroll spies, popovers)\n * need to react both to their *own* box changing — via {@link ResizeObserver} —\n * and to the *viewport* changing — via the `window` `resize` event. Wiring those\n * two sources by hand in every controller risks leaked listeners on\n * `disconnect()`. {@link LayoutObserver} owns both behind one callback and one\n * {@link LayoutObserver.disconnect | disconnect()} that releases everything.\n *\n * Behavior only: the helper reports *that* layout changed; it never reads or\n * writes styles. Consumers decide what to recompute.\n */\n\n/** Invoked whenever an observed element or the viewport changes size. */\nexport type LayoutCallback = () => void;\n\n/** Constructs a {@link ResizeObserver}; injectable so tests stay deterministic. */\nexport type ResizeObserverFactory = (callback: ResizeObserverCallback) => ResizeObserver;\n\n/** Options for {@link LayoutObserver}. */\nexport interface LayoutObserverOptions {\n  /**\n   * Factory for the {@link ResizeObserver} used by {@link LayoutObserver.observe}.\n   * Defaults to the global constructor; override it in tests, or to no-op in\n   * environments where `ResizeObserver` is unavailable.\n   */\n  resizeObserverFactory?: ResizeObserverFactory;\n}\n\n/**\n * Observes element resizes and/or viewport resizes through a single callback,\n * with guaranteed teardown.\n *\n * @example\n * ```ts\n * #layout = new LayoutObserver(() => this.#reposition());\n *\n * connect() {\n *   this.#layout.observe(this.panelTarget);\n *   this.#layout.observeViewport();\n * }\n *\n * disconnect() {\n *   this.#layout.disconnect();\n * }\n * ```\n */\nexport class LayoutObserver {\n  readonly #callback: LayoutCallback;\n  readonly #resizeObserverFactory: ResizeObserverFactory | null;\n  #resizeObserver: ResizeObserver | null = null;\n  #observingViewport = false;\n\n  /** Stable bound handler so add/removeEventListener target the same reference. */\n  readonly #handleViewportResize = (): void => {\n    this.#callback();\n  };\n\n  constructor(callback: LayoutCallback, options: LayoutObserverOptions = {}) {\n    this.#callback = callback;\n    this.#resizeObserverFactory =\n      options.resizeObserverFactory ??\n      (typeof ResizeObserver === \"undefined\" ? null : (cb) => new ResizeObserver(cb));\n  }\n\n  /**\n   * Starts observing an element's size. Repeated calls observe additional\n   * elements through the same shared observer. No-ops when no\n   * `ResizeObserver` implementation is available.\n   */\n  observe(element: Element): void {\n    if (!this.#resizeObserverFactory) return;\n    if (!this.#resizeObserver) {\n      this.#resizeObserver = this.#resizeObserverFactory(() => {\n        this.#callback();\n      });\n    }\n    this.#resizeObserver.observe(element);\n  }\n\n  /** Stops observing a single element while leaving any others in place. */\n  unobserve(element: Element): void {\n    this.#resizeObserver?.unobserve(element);\n  }\n\n  /** Starts observing viewport resizes. Idempotent: the listener is added once. */\n  observeViewport(): void {\n    if (this.#observingViewport) return;\n    this.#observingViewport = true;\n    window.addEventListener(\"resize\", this.#handleViewportResize);\n  }\n\n  /** Stops observing viewport resizes without affecting element observation. */\n  unobserveViewport(): void {\n    if (!this.#observingViewport) return;\n    this.#observingViewport = false;\n    window.removeEventListener(\"resize\", this.#handleViewportResize);\n  }\n\n  /**\n   * Releases every observation: disconnects the {@link ResizeObserver} and\n   * removes the viewport listener. Safe to call multiple times. Call this from a\n   * controller's `disconnect()`.\n   */\n  disconnect(): void {\n    this.#resizeObserver?.disconnect();\n    this.#resizeObserver = null;\n    this.unobserveViewport();\n  }\n}\n","/**\n * Collapses many Stimulus lifecycle callbacks from one DOM mutation into a\n * single pass.\n *\n * Stimulus fires `<name>TargetConnected` / `Disconnected` once per element and\n * `<name>ValueChanged` once per changed attribute. Replacing a list of N options\n * or morphing several render Values therefore delivers N callbacks — but the\n * useful unit of work is \"reconcile against the resulting declarative input\",\n * once, after the batch has settled. Every controller with reconcilable targets\n * or render Values needs the same shape: a `queued` flag plus `queueMicrotask`.\n *\n * **A microtask is the right horizon, and the reason is specific.** Stimulus\n * drives these callbacks from a `MutationObserver`, whose own callback already\n * runs as a microtask with the whole batch in hand; scheduling one more lands\n * after the last sibling callback of that batch and still before paint or any\n * event handler. A timer would be later than it needs to be, and reconciling\n * synchronously would run once per element against a half-applied DOM.\n *\n * **The two guards are not the same guard.** Scheduling is refused before the\n * controller connects, and running is refused after it disconnects:\n *\n * - **Before `connect()`** — Stimulus delivers initial target and Value callbacks\n *   ahead of `connect()`. Reconciling there would compute output against a\n *   controller whose own state has not been initialised, and `connect()` is\n *   about to do a full pass anyway.\n * - **After `disconnect()`** — Stimulus fires a callback for **every** target\n *   during teardown, and a microtask queued just before it would otherwise run\n *   against a detached tree. {@link MicrotaskCoalescer.cancel} exists for the\n *   teardown path to drop the pending pass outright.\n *\n * Both guards are part of one contract here rather than something each consumer\n * has to remember separately.\n *\n * Scope is the scheduling only. *What* to reconcile — keep the surviving active\n * option, fall back to the next / previous / first visible one, rebuild derived\n * chips or hidden fields — stays in the controller, because no two consumers\n * answer it the same way.\n *\n * This file's own doc block is dropped from `dist`, but every member comment is\n * inlined into each consumer entry (`tsup` builds with `splitting: false`), so\n * rationale belongs here and only the contract belongs on the members.\n *\n * @example\n * ```ts\n * readonly #reconcile = new MicrotaskCoalescer(() => this.#reconcileOptions());\n *\n * connect()    { this.#reconcile.activate(); }\n * disconnect() { this.#reconcile.cancel(); }\n *\n * optionTargetConnected()    { this.#reconcile.schedule(); }\n * optionTargetDisconnected() { this.#reconcile.schedule(); }\n * ```\n */\nexport class MicrotaskCoalescer {\n  readonly #run: () => void;\n  #queued = false;\n  #active = false;\n  #generation = 0;\n\n  /** @param run - the single reconciliation pass, invoked at most once per batch. */\n  constructor(run: () => void) {\n    this.#run = run;\n  }\n\n  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */\n  activate(): void {\n    this.#active = true;\n  }\n\n  /** Closes the window and drops any pending pass; call from `disconnect()`. */\n  cancel(): void {\n    this.#active = false;\n    this.#queued = false;\n    this.#generation += 1;\n  }\n\n  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */\n  schedule(): void {\n    if (!this.#active || this.#queued) return;\n    this.#queued = true;\n    const generation = this.#generation;\n    queueMicrotask(() => {\n      // A cancelled callback must not consume a pass queued after reconnect.\n      if (generation !== this.#generation || !this.#queued || !this.#active) return;\n      this.#queued = false;\n      this.#run();\n    });\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { LayoutObserver } from \"../utils/layout_observer\";\nimport { MicrotaskCoalescer } from \"../utils/microtask_coalescer\";\n\n/** CSS custom property exposing the current column count to consumer CSS. */\nconst COLUMNS_PROPERTY = \"--stimeo--masonry-columns\";\n\n/** Column width assumed when the declaration is absent or unreadable. */\nconst DEFAULT_MIN_COLUMN_WIDTH = 240;\n/** Item spacing assumed when the declaration is absent or unreadable. */\nconst DEFAULT_GAP = 16;\n\n/**\n * Returns `value` when it is a number the column arithmetic can use, else\n * `fallback`.\n *\n * A unit suffix is the ordinary authoring slip here (`\"240px\"`), and Stimulus'\n * Number reader answers `NaN` rather than raising — which would reach the column\n * count and make the column bookkeeping impossible to allocate, leaving the grid\n * with no hooks at all. An infinity is rejected for the same reason: it divides\n * into itself as `NaN`.\n */\nfunction usableNumber(value: number, fallback: number): number {\n  return Number.isFinite(value) ? value : fallback;\n}\n\n/**\n * Headless **Masonry** layout helper: assigns each item to the shortest column so\n * variable-height cards pack without vertical gaps. There is no APG widget — this\n * is a layout-only utility that emits state hooks, never visual structure.\n *\n * Markup contract (identifier: `stimeo--masonry`):\n *   <div data-controller=\"stimeo--masonry\"\n *        data-stimeo--masonry-min-column-width-value=\"240\"\n *        data-stimeo--masonry-gap-value=\"16\">\n *     <div data-stimeo--masonry-target=\"item\">…</div>\n *     <div data-stimeo--masonry-target=\"item\">…</div>\n *   </div>\n *\n * The column count is derived responsively from the container width and\n * `minColumnWidth`; each item is then placed into whichever column is currently\n * shortest (measured from item heights). The count is published on the controller\n * element as the `--stimeo--masonry-columns` custom property and each item gets a\n * `data-column` index, so the consumer's CSS owns the actual placement.\n *\n * `layout` dispatches `{ columns: number }` whenever the published result moves —\n * the column count changed, or some item landed in a different column. A pass that\n * reproduces the previous result stays silent.\n *\n * @remarks\n * Behavior only. **DOM order is never changed** — reading order and focus order\n * stay the source markup order (WCAG 1.3.2). The visual packing is purely the\n * column assignment a consumer reads from `data-column`; this controller writes no\n * positioning styles. Use only for independent cards whose visual order carries no\n * meaning.\n *\n * Re-layout runs on connect, on resize ({@link LayoutObserver}), on item\n * add/remove ({@link MutationObserver}), on an item joining or leaving the target\n * set, when a declared number changes, and when a descendant resource loads.\n * Everything but the first pass is folded into one microtask, so a burst of\n * triggers costs one pass. The observers, the `load` listener and any pending pass\n * are released on `disconnect()` (Turbo navigation included).\n *\n * Consumer contract:\n * - A declaration that cannot be read as a number (`\"240px\"`, an infinity) falls\n *   back to that Value's default and the grid keeps working; `0` and negatives are\n *   readable numbers and collapse to a single column instead.\n * - `data-column` belongs to this controller: it is written on every item it owns\n *   and taken back from an element that stops being one.\n */\nexport class MasonryController extends Controller<HTMLElement> {\n  static override targets = [\"item\"];\n  static override values = {\n    minColumnWidth: { type: Number, default: DEFAULT_MIN_COLUMN_WIDTH },\n    gap: { type: Number, default: DEFAULT_GAP },\n  };\n  static events = [\"layout\"] as const;\n\n  declare readonly itemTargets: HTMLElement[];\n  declare minColumnWidthValue: number;\n  declare gapValue: number;\n\n  /**\n   * The declared numbers after validation, so the layout path never sees a value\n   * it cannot compute with. Both are resolved once per declaration change rather\n   * than on every pass.\n   */\n  #minColumnWidth = DEFAULT_MIN_COLUMN_WIDTH;\n  #gap = DEFAULT_GAP;\n\n  /**\n   * Collapses every re-layout trigger of one DOM mutation into a single pass, and\n   * refuses to run before `connect()` or after `disconnect()`.\n   *\n   * The triggers arrive in bursts — a resize stream, a morph that syncs several\n   * attributes, a batch of rows — and each pass measures every item, so folding\n   * them keeps the work proportional to the batch rather than to the events in it.\n   */\n  readonly #reconcile = new MicrotaskCoalescer(() => this.#relayout());\n\n  /** Items that left the target set and still carry the column hook. */\n  readonly #released = new Set<HTMLElement>();\n\n  readonly #layout = new LayoutObserver(() => this.#reconcile.schedule());\n  #mutationObserver: MutationObserver | null = null;\n  /** Last published column count, so `layout` fires only on real changes. */\n  #lastColumns = 0;\n\n  /**\n   * Re-pack when a descendant resource finishes loading. Images/iframes report a\n   * height of 0 until loaded, which would skew the shortest-column packing if the\n   * first pass ran before they settled; `load` does not bubble, so this is bound in\n   * the capture phase to catch every descendant.\n   */\n  readonly #onLoad = (): void => this.#reconcile.schedule();\n\n  /** Resolves the declared column width once, falling back when it is unreadable. */\n  minColumnWidthValueChanged(): void {\n    this.#minColumnWidth = usableNumber(this.minColumnWidthValue, DEFAULT_MIN_COLUMN_WIDTH);\n    this.#reconcile.schedule();\n  }\n\n  /** Resolves the declared gap once, falling back when it is unreadable. */\n  gapValueChanged(): void {\n    this.#gap = usableNumber(this.gapValue, DEFAULT_GAP);\n    this.#reconcile.schedule();\n  }\n\n  /** Packs an element that became an item without moving in the DOM. */\n  itemTargetConnected(): void {\n    this.#reconcile.schedule();\n  }\n\n  /**\n   * Queues the column hook of an element that stopped being an item for removal.\n   *\n   * The removal is queued rather than immediate because teardown reports every\n   * target as disconnected: doing it here would strip the whole grid just before\n   * a Turbo snapshot is taken. {@link MicrotaskCoalescer.cancel} drops the queue\n   * with the pass, so only a genuine target change reaches it.\n   */\n  itemTargetDisconnected(item: HTMLElement): void {\n    this.#released.add(item);\n    this.#reconcile.schedule();\n  }\n\n  /** Observes size/content changes and performs the first layout pass. */\n  override connect(): void {\n    this.#layout.observe(this.element);\n    this.#layout.observeViewport();\n\n    if (typeof MutationObserver !== \"undefined\") {\n      this.#mutationObserver = new MutationObserver(() => this.#reconcile.schedule());\n      this.#mutationObserver.observe(this.element, { childList: true, subtree: true });\n    }\n    this.element.addEventListener(\"load\", this.#onLoad, true);\n    this.#relayout();\n    this.#reconcile.activate();\n  }\n\n  /** Releases both observers and the load listener so nothing fires after detach. */\n  override disconnect(): void {\n    this.#reconcile.cancel();\n    this.#released.clear();\n    this.#layout.disconnect();\n    this.#mutationObserver?.disconnect();\n    this.#mutationObserver = null;\n    this.element.removeEventListener(\"load\", this.#onLoad, true);\n    this.#lastColumns = 0;\n  }\n\n  /**\n   * Recomputes the column count and assigns every item to the shortest column.\n   * Runs automatically on connect, on resize, on item add/remove, when a declared\n   * number changes, and when a descendant resource loads (private — there is no\n   * public action; the observers, the target callbacks and the capture-phase\n   * `load` listener drive it). Items are walked in DOM order; each lands in the\n   * column with the least accumulated height, which keeps the packing balanced\n   * without reordering the DOM.\n   *\n   * Every box is measured before anything is written. Interleaving the two would\n   * make a consumer's `data-column` rule invalidate style once per item, and the\n   * next measurement then has to settle layout again — once per item instead of\n   * once per pass. The assignment is independent of the measurement because the\n   * columns are uniform in width, so the order of the two passes does not change\n   * the result.\n   *\n   * @stimeoRenderRoot\n   */\n  #relayout(): void {\n    const items = this.itemTargets;\n    const columns = this.#columnCount();\n    const boxes = items.map((item) => item.getBoundingClientRect().height);\n\n    let changed = false;\n    if (this.#released.size > 0) {\n      // An element that left and rejoined the target set within one batch is\n      // queued here while still being an item, so ownership is decided against\n      // the set this pass sees rather than against the queue alone.\n      const owned = new Set(items);\n      for (const released of this.#released) {\n        if (owned.has(released)) continue;\n        if (released.hasAttribute(\"data-column\")) {\n          released.removeAttribute(\"data-column\");\n          changed = true;\n        }\n      }\n      this.#released.clear();\n    }\n\n    const heights = new Array<number>(columns).fill(0);\n    items.forEach((item, index) => {\n      let shortest = 0;\n      for (let col = 1; col < columns; col++) {\n        if ((heights[col] ?? 0) < (heights[shortest] ?? 0)) shortest = col;\n      }\n      const assigned = String(shortest);\n      // Writing a value the item already carries would publish a change that did\n      // not happen, and the same comparison is what tells the event whether the\n      // published layout actually moved.\n      if (item.getAttribute(\"data-column\") !== assigned) {\n        item.setAttribute(\"data-column\", assigned);\n        changed = true;\n      }\n      heights[shortest] = (heights[shortest] ?? 0) + (boxes[index] ?? 0) + this.#gap;\n    });\n\n    this.element.style.setProperty(COLUMNS_PROPERTY, String(columns));\n\n    if (columns !== this.#lastColumns || changed) {\n      this.#lastColumns = columns;\n      this.dispatch(\"layout\", { detail: { columns } });\n    }\n  }\n\n  /**\n   * Derives how many columns fit: `floor((width + gap) / (minColumnWidth + gap))`,\n   * never fewer than one. When the width is unmeasurable (detached, or a layout\n   * engine that reports `0`), it falls back to a single column so every item still\n   * gets a valid `data-column`.\n   */\n  #columnCount(): number {\n    const width = this.element.getBoundingClientRect().width;\n    const denominator = this.#minColumnWidth + this.#gap;\n    if (width <= 0 || denominator <= 0) return 1;\n    return Math.max(1, Math.floor((width + this.#gap) / denominator));\n  }\n}\n"]}

package/dist/controllers/nested_form_controller.d.ts

@@ -2,10 +2,9 @@ import { Controller } from '@hotwired/stimulus';
 
 /**
  * Headless **nested / dynamic fields** for Rails `fields_for` +
- * `accepts_nested_attributes_for` (no dedicated APG pattern — form editing). The
- * Headless successor to the cocoon / nested_form gems: clone a `<template>` row,
- * renumber its index, and remove rows by flagging `_destroy` (persisted) or
- * dropping them from the DOM (unsaved).
+ * `accepts_nested_attributes_for` (no dedicated APG pattern — form editing).
+ * Clone a `<template>` row, renumber its index, and remove rows by flagging
+ * `_destroy` (persisted) or dropping them from the DOM (unsaved).
  *
  * Markup contract (identifier: `stimeo--nested-form`):
  *   <div data-controller="stimeo--nested-form" data-stimeo--nested-form-min-value="1">
@@ -22,18 +21,43 @@ import { Controller } from '@hotwired/stimulus';
  *             data-action="click->stimeo--nested-form#add">Add</button>
  *   </div>
  *
- * `add` dispatches `{ index, element }`; `remove` dispatches `{ element, persisted }`.
+ * Values: `min` / `max` bound the effective row count (`max` `0` = unlimited;
+ * both are followed at runtime), `indexPlaceholder` is the template token
+ * replaced per row (default `__INDEX__`), and `announce` + `countMessage` (a
+ * `{count}` template) opt into the announcer bridge.
+ *
+ * `add` dispatches `{ index, element }`; `remove` dispatches `{ element, persisted }`;
+ * `reconcile` dispatches `{ count, atMin, atMax }` when a change the controller did
+ * not perform itself — rows appended or removed by Turbo Streams / a morph, or a
+ * runtime `min` / `max` change — moves the published state.
  *
  * @remarks
  * Behavior only — server-side `accepts_nested_attributes_for`, per-field
  * validation, and reordering are out of scope. Row state lives **only** in the DOM
  * (inserted nodes + each `_destroy` hidden input); there is no module-scope index
- * counter, so the controller stays idempotent across Turbo swaps. Remove buttons
- * are handled by **delegation** on the container, so dynamically-added rows work
- * without per-row `data-action`. Adding a row moves focus to its first control and
- * removing returns focus to a neighbor (WCAG 2.2 2.4.3); count changes are announced
- * through the shared `stimeo--announcer` (WCAG 2.2 4.1.3) when `announce` +
- * `countMessage` are set. The delegated listener is removed on `disconnect()`.
+ * counter, so the controller stays idempotent across Turbo swaps. A row counts as
+ * destroyed when its own `_destroy` flag holds a truthy value — `hidden` is the
+ * visual half the controller writes alongside the flag, so a consumer hiding rows
+ * for other reasons does not affect the count. Remove buttons and destroy flags
+ * are resolved by **delegation scoped to their nearest nested-form root**, so
+ * dynamically-added rows work without per-row `data-action` and one instance
+ * nested inside another never acts on the inner instance's buttons or flags.
+ * External row changes are observed on the list and reconciled once per mutation
+ * batch. Adding a row moves focus to its first tab stop; removing returns focus to
+ * the nearest surviving row's first tab stop, falling back to the add button and
+ * finally to the root via a temporary `tabindex` (WCAG 2.2 2.4.3) — candidates
+ * that cannot take focus (natively `disabled`, inside `fieldset[disabled]`, or not
+ * rendered) are skipped. Count changes from the controller's own add / remove are
+ * announced through the shared `stimeo--announcer` (WCAG 2.2 4.1.3) when
+ * `announce` + `countMessage` are set; reconciliation stays silent to assistive
+ * tech. The add button's `disabled` is managed only while `max` is set, and the
+ * authored value is restored on teardown. A template must produce exactly one
+ * root element; markup lacking the required `list` / `template` targets, or a
+ * template producing anything else, is named on the console once per connection
+ * and every operation stays a safe no-op with nothing left in the list. Clicking
+ * remove on a row whose flag is already truthy only completes its hiding —
+ * nothing effective changes, so no event and no announcement. The delegated
+ * listener, the observer, and every lease are released on `disconnect()`.
  */
 declare class NestedFormController extends Controller<HTMLElement> {
     #private;
@@ -61,7 +85,7 @@ declare class NestedFormController extends Controller<HTMLElement> {
         };
     };
     static actions: readonly ["add"];
-    static events: readonly ["add", "remove"];
+    static events: readonly ["add", "remove", "reconcile"];
     readonly listTarget: HTMLElement;
     readonly templateTarget: HTMLTemplateElement;
     readonly addTarget: HTMLButtonElement;
@@ -75,10 +99,23 @@ declare class NestedFormController extends Controller<HTMLElement> {
     countMessageValue: string;
     connect(): void;
     disconnect(): void;
+    /** Follows an arriving or swapped-in list: rebind to the primary, then reconcile. */
+    listTargetConnected(): void;
+    /** Follows a departing list the same way — the primary may have changed. */
+    listTargetDisconnected(): void;
+    /** Returns the lease with a departing add button; a new one re-arms on refresh. */
+    addTargetDisconnected(target: HTMLButtonElement): void;
+    addTargetConnected(): void;
+    /** Re-clamps when application code or a Turbo morph changes `min`. */
+    minValueChanged(): void;
+    /** Re-clamps when application code or a Turbo morph changes `max`. */
+    maxValueChanged(): void;
     /**
      * Clones the template row, replaces the index placeholder with a unique value,
-     * appends it, focuses its first control, and announces the new count. No-ops at
-     * `max`.
+     * appends it, focuses its first tab stop, and announces the new count. No-ops at
+     * `max`, when the required targets are missing (named on the console once per
+     * connection), or when the template does not produce exactly one root element
+     * (also named once; the insertion is rolled back so nothing accumulates).
      */
     add(): void;
 }