stimeo-ui 0.8.0 → 0.9.0

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() {

data/dist/controllers/filter_controller.js

@@ -9,15 +9,46 @@ var FilterController = class extends Controller {
   #onChange = () => {
     this.apply();
   };
+  /**
+   * Gates the declaration callback to the connected window.
+   *
+   * Stimulus delivers a Value callback ahead of `connect()` and again for every
+   * runtime change; without the gate, merely connecting would emit an evaluation
+   * — and its `change` — before `connect()` runs its own.
+   */
+  #connected = false;
   connect() {
-    this.apply();
+    this.#evaluate();
     this.element.addEventListener("change", this.#onChange);
+    this.#connected = true;
   }
   disconnect() {
+    this.#connected = false;
     this.element.removeEventListener("change", this.#onChange);
   }
+  /**
+   * Re-evaluates when the match declaration changes at runtime.
+   *
+   * The declaration decides which items are shown, so an element kept across a
+   * morph — where `connect()` does not run again — still has to follow it instead
+   * of waiting for the next control interaction. The evaluation is the ordinary
+   * one, `change` included: a declaration swap is an evaluation like any other.
+   */
+  matchValueChanged() {
+    if (!this.#connected) return;
+    this.#evaluate();
+  }
   /** Re-derives every item's visibility from the active tokens and syncs groups/empty. */
   apply() {
+    this.#evaluate();
+  }
+  /**
+   * The evaluation itself: every item's visibility from the active tokens, then
+   * the groups and the empty element, then the `change` event.
+   *
+   * @stimeoRenderRoot
+   */
+  #evaluate() {
     const active = this.#activeTokens();
     let visibleCount = 0;
     for (const item of this.itemTargets) {

data/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));
   }
 };
 

data/dist/controllers/otp_controller.js

@@ -211,6 +211,9 @@ function compilePattern(source) {
 function hasModifier(event) {
   return event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
 }
+function statesDiffer(left, right) {
+  return left.value !== right.value || left.state !== right.state;
+}
 var OtpController = class extends Controller {
   static targets = ["field", "value", "error"];
   static values = {
@@ -222,8 +225,8 @@ var OtpController = class extends Controller {
   #pattern = new RegExp(`^${DEFAULT_PATTERN}$`);
   /** Source of {@link #pattern}, reported in `invalid` so consumers can word it. */
   #patternSource = DEFAULT_PATTERN;
-  /** Combined value carried by the last dispatch; keeps a no-op sync silent. */
-  #lastValue = null;
+  /** Public state carried by the last dispatch; keeps a no-op sync silent. */
+  #published = null;
   /** Field whose confirming `input` after `compositionend` is already handled. */
   #confirmedField = null;
   /** True between connect and disconnect, so pre-connect Value changes stay silent. */
@@ -259,7 +262,7 @@ var OtpController = class extends Controller {
     this.#beforeCache.activate();
     this.#reconcile.activate();
     this.#adopt();
-    this.#lastValue = this.#sync();
+    this.#sync();
   }
   disconnect() {
     this.#connected = false;
@@ -451,19 +454,23 @@ var OtpController = class extends Controller {
     this.#markFilled(field, field.value);
   }
   /**
-   * Absorbs a batch of field additions or removals as one value transition.
+   * Absorbs a batch of field additions or removals as one state transition.
    *
-   * The page, not the user, moved the value here, so it is reported as
+   * The page, not the user, moved the state here, so it is reported as
    * `reconcile`: automation listening for `change` must not read a re-render as
    * an edit, and a passcode that happens to end up full must not fire the
    * `complete` that submits it.
+   *
+   * Completeness moves on its own when the field count changes: dropping a
+   * trailing empty field completes a passcode whose combined value never moved,
+   * and adding one un-completes it. Comparing the whole derived state, not the
+   * string it contains, is what makes those transitions reportable.
    */
   #reconcileFields() {
-    const previous = this.#lastValue;
-    const combined = this.#sync();
-    if (combined === previous) return;
-    this.#lastValue = combined;
-    this.dispatch("reconcile", { detail: { value: combined } });
+    const previous = this.#published;
+    const current = this.#sync();
+    if (previous && !statesDiffer(previous, current)) return;
+    this.dispatch("reconcile", { detail: { value: current.value } });
   }
   /**
    * Validates the text an entry point received and distributes what it accepts.
@@ -558,23 +565,29 @@ var OtpController = class extends Controller {
     const fields = this.fieldTargets;
     return fields.length > 0 && fields.every((field) => field.value.length > 0);
   }
-  /** Mirrors the combined value into the form and the root's readable state. */
+  /**
+   * Mirrors the combined value into the form and the root's readable state, and
+   * records what was published so the next pass can compare against it.
+   */
   #sync() {
     const combined = this.#combinedValue();
     if (this.hasValueTarget) {
       this.valueTarget.value = combined;
     }
-    this.#state.write(this.element, this.#stateName(combined));
-    return combined;
+    const state = this.#stateName(combined);
+    this.#state.write(this.element, state);
+    const published = { value: combined, state };
+    this.#published = published;
+    return published;
   }
   #stateName(combined) {
     if (combined.length === 0) return "empty";
     return this.#isComplete() ? "complete" : "partial";
   }
   #syncAndDispatch() {
-    const combined = this.#sync();
-    if (combined === this.#lastValue) return;
-    this.#lastValue = combined;
+    const previous = this.#published;
+    const { value: combined } = this.#sync();
+    if (previous?.value === combined) return;
     this.dispatch("change", { detail: { value: combined } });
     if (this.#isComplete()) {
       this.dispatch("complete", { detail: { value: combined } });

data/dist/controllers/reset_before_cache_controller.js

@@ -1,6 +1,26 @@
 import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/reset_before_cache_controller.ts
+var STATELESS_INPUT_TYPES = /* @__PURE__ */ new Set(["hidden", "submit", "reset", "button", "image"]);
+function restoreField(element) {
+  if (element instanceof HTMLTextAreaElement) {
+    element.value = element.defaultValue;
+    return;
+  }
+  if (element instanceof HTMLSelectElement) {
+    for (const option of element.options) option.selected = option.hasAttribute("selected");
+    return;
+  }
+  if (element instanceof HTMLInputElement) {
+    if (element.type === "checkbox" || element.type === "radio") {
+      element.checked = element.defaultChecked;
+    } else if (element.type === "file") {
+      element.value = "";
+    } else if (!STATELESS_INPUT_TYPES.has(element.type)) {
+      element.value = element.defaultValue;
+    }
+  }
+}
 var ResetBeforeCacheController = class extends Controller {
   static values = {
     scope: { type: String, default: "" },
@@ -8,8 +28,32 @@ var ResetBeforeCacheController = class extends Controller {
   };
   static actions = ["reset"];
   static events = ["reset", "request"];
+  /** The `scope` declaration after validation; empty when it cannot be parsed. */
+  #scopeSelector = "";
   /** Runs the reset just before Turbo caches the snapshot. */
   #onBeforeCache = () => this.reset();
+  /**
+   * Validates the scope declaration once, keeping only a selector the engine can
+   * read.
+   *
+   * A selector reads back as an ordinary string, so a malformed one survives
+   * until it is handed to the DOM — and this part runs from a single listener
+   * whose whole job is to keep a cached page from freezing. Falling back to the
+   * default keeps that job running with a visible, findable result instead of
+   * silently taking the sweep down.
+   */
+  scopeValueChanged() {
+    const selector = this.scopeValue;
+    if (selector.length > 0) {
+      try {
+        this.element.matches(selector);
+        this.#scopeSelector = selector;
+        return;
+      } catch {
+      }
+    }
+    this.#scopeSelector = "";
+  }
   connect() {
     document.addEventListener("turbo:before-cache", this.#onBeforeCache);
   }
@@ -20,6 +64,10 @@ var ResetBeforeCacheController = class extends Controller {
    * Resets transient UI within scope to its initial state. Asks controllers to
    * close (via `request`) first, then applies the declarative `data-reset-*` cleanup,
    * and finally emits `reset`. Safe to call any number of times (idempotent).
+   *
+   * `dispatchReset` decides only whether the `request` ask goes out; the cleanup
+   * and the closing `reset` run either way. Both the listener and this action
+   * reach the same sweep, so `reset` is emitted for a manual call too.
    */
   reset() {
     const root = this.#scopeRoot();
@@ -38,9 +86,7 @@ var ResetBeforeCacheController = class extends Controller {
       if (element instanceof HTMLFormElement) element.reset();
     }
     for (const element of root.querySelectorAll("[data-reset-value]")) {
-      if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement) {
-        element.value = "";
-      }
+      restoreField(element);
     }
     for (const element of root.querySelectorAll("[data-reset-hidden]")) {
       element.hidden = true;
@@ -52,8 +98,8 @@ var ResetBeforeCacheController = class extends Controller {
   }
   /** The scan root: a `scope` descendant when set, else the controller element. */
   #scopeRoot() {
-    if (!this.scopeValue) return this.element;
-    return this.element.querySelector(this.scopeValue) ?? this.element;
+    if (!this.#scopeSelector) return this.element;
+    return this.element.querySelector(this.#scopeSelector) ?? this.element;
   }
 };