stimeo-ui 0.15.0 → 0.16.0

data/dist/controllers/stick_to_bottom_controller.js

@@ -89,6 +89,47 @@ function prefersReducedMotion() {
   return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 }
 
+// src/utils/state_regions.ts
+var StateRegions = class {
+  #whenTrue;
+  #whenFalse;
+  #taken = /* @__PURE__ */ new WeakSet();
+  constructor(options) {
+    this.#whenTrue = options.whenTrue;
+    this.#whenFalse = options.whenFalse ?? null;
+  }
+  /** Shows the regions inside `host` that belong to `isTrue` and hides the others. */
+  reflect(host, isTrue) {
+    const shown = this.#inside(host, this.#whenTrue());
+    if (!this.#whenFalse) {
+      for (const region of shown) this.#write(region, !isTrue);
+      return;
+    }
+    const hiddenSide = this.#inside(host, this.#whenFalse());
+    if (shown.length === 0 || hiddenSide.length === 0) {
+      for (const region of shown) this.#give(region);
+      for (const region of hiddenSide) this.#give(region);
+      return;
+    }
+    for (const region of shown) this.#write(region, !isTrue);
+    for (const region of hiddenSide) this.#write(region, isTrue);
+  }
+  /** Writes `hidden` where it moves, noting which regions it takes out of view. */
+  #write(region, hidden) {
+    if (hidden) this.#taken.add(region);
+    else this.#taken.delete(region);
+    if (region.hidden !== hidden) region.hidden = hidden;
+  }
+  /** Returns a region this instance hid; one it never hid keeps what it carries. */
+  #give(region) {
+    if (this.#taken.delete(region)) region.hidden = false;
+  }
+  /** The declared regions that sit within `host`, which may be the host itself. */
+  #inside(host, regions) {
+    return regions.filter((region) => host.contains(region));
+  }
+};
+
 // src/controllers/stick_to_bottom_controller.ts
 var DEFAULT_THRESHOLD = 80;
 var countElements = (nodes) => {
@@ -97,7 +138,7 @@ var countElements = (nodes) => {
   return n;
 };
 var StickToBottomController = class extends Controller {
-  static targets = ["content"];
+  static targets = ["content", "hasNew"];
   static values = {
     threshold: { type: Number, default: DEFAULT_THRESHOLD },
     behavior: { type: String, default: "auto" },
@@ -113,11 +154,14 @@ var StickToBottomController = class extends Controller {
   #awaitingLayout = false;
   #connected = false;
   #pinned = false;
+  #hasNew = false;
+  /** Owns `hidden` on the regions declared for the has-new state. */
+  #hasNewRegion = new StateRegions({ whenTrue: () => this.hasNewTargets });
   #onScroll = () => this.#updatePinned();
   connect() {
     this.#connected = true;
     if (this.pinOnConnectValue && this.#measurable()) this.#scrollToBottom("instant");
-    this.element.removeAttribute("data-has-new");
+    this.#setHasNew(false);
     this.#pinned = this.#isPinned();
     this.#reflectPinned();
     this.element.addEventListener("scroll", this.#onScroll, { passive: true });
@@ -138,6 +182,19 @@ var StickToBottomController = class extends Controller {
   contentTargetDisconnected() {
     this.#syncWatched();
   }
+  /**
+   * Settles a has-new region that arrived at runtime on the side the flag is currently
+   * on, the way a region present at connect is settled by the connect-time normalization.
+   *
+   * Stimulus attaches targets before `connect()`, and a container that leaves the document
+   * and comes back keeps its controller, so in that window the flag still reads the
+   * arrival of the connection that ended. A region attached there is left to the
+   * connect-time normalization, which drops the flag and settles the region in one write.
+   */
+  hasNewTargetConnected() {
+    if (!this.#connected) return;
+    this.#hasNewRegion.reflect(this.element, this.#hasNew);
+  }
   /**
    * Re-derives pinned when the distance that counts as the bottom is changed at runtime
    * (a morph that swaps the attribute on a retained element).
@@ -159,7 +216,7 @@ var StickToBottomController = class extends Controller {
    */
   scrollToBottom() {
     this.#scrollToBottom();
-    this.element.removeAttribute("data-has-new");
+    this.#setHasNew(false);
     this.#updatePinned();
   }
   /** Follows appended children while pinned; otherwise flags new content. */
@@ -170,7 +227,7 @@ var StickToBottomController = class extends Controller {
     if (this.#pinned) {
       this.#scrollToBottom();
     } else {
-      this.element.setAttribute("data-has-new", "true");
+      this.#setHasNew(true);
       this.dispatch("new", { detail: { count: added } });
     }
   }
@@ -190,11 +247,24 @@ var StickToBottomController = class extends Controller {
   #reflectPinned() {
     if (this.#pinned) {
       this.element.setAttribute("data-pinned", "true");
-      this.element.removeAttribute("data-has-new");
+      this.#setHasNew(false);
     } else {
       this.element.removeAttribute("data-pinned");
     }
   }
+  /**
+   * Mirrors whether content has arrived that the container did not follow onto the state
+   * hook and onto the regions declared for that state.
+   */
+  #setHasNew(hasNew) {
+    this.#hasNew = hasNew;
+    if (hasNew) {
+      this.element.setAttribute("data-has-new", "true");
+    } else {
+      this.element.removeAttribute("data-has-new");
+    }
+    this.#hasNewRegion.reflect(this.element, hasNew);
+  }
   /** Whether the container currently sits within `threshold` of its bottom. */
   #isPinned() {
     if (!this.#measurable()) return false;

data/dist/controllers/submit_once_controller.js

@@ -331,7 +331,12 @@ var SubmitOnceController = class extends Controller {
     if (!session || !this.#isNativeSubmitControl(target)) return;
     this.#enterControl(session, target);
   }
-  /** Ends one session, restores owned state, and reports the observable completion. */
+  /**
+   * Ends one session, restores owned state, and reports the observable completion.
+   *
+   * @stimeoRuntimeOnly `announceReadyText` words the one announcement of this finished submission
+   *   and `restoreFocus` decides where its focus returns.
+   */
   #complete(form, reason, success) {
     const session = this.#sessionFor(form);
     if (!session) return;
@@ -353,7 +358,12 @@ var SubmitOnceController = class extends Controller {
     this.#disabled.write(control, "");
     this.#controlBusy.write(control, "true");
   }
-  /** Swaps only the triggering control's safe label channel. */
+  /**
+   * Swaps only the triggering control's safe label channel.
+   *
+   * @stimeoRuntimeOnly `busyLabel` is the label this one submission shows until it ends; the idle
+   *   label comes back with the state it returns.
+   */
   #enterLabel(session) {
     const control = session.submitter;
     if (!control) return;
@@ -440,7 +450,10 @@ var SubmitOnceController = class extends Controller {
     }
     this.#sessions.clear();
   }
-  /** Keeps Turbo's cached snapshot idle, without events, announcements, or focus moves. */
+  /**
+   * Keeps Turbo's cached snapshot idle without `end`, announcements, or focus
+   * moves; the abandoned forms are reported once as `reconcile`.
+   */
   #rewindForCache() {
     const forms = [...this.#sessions.keys()];
     this.#abandonSessions();

data/dist/controllers/switch_controller.js

@@ -9,6 +9,16 @@ function setDefaultAttribute(element, name, value) {
   return true;
 }
 
+// src/utils/field_mirror.ts
+function writeField(field, value) {
+  if (field.value === value) return false;
+  field.value = value;
+  return true;
+}
+function commitField(target) {
+  target.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
 // src/utils/focus_candidate.ts
 function inheritsFieldsetDisabled(control) {
   let fieldset = control.closest("fieldset[disabled]");
@@ -37,6 +47,39 @@ function isInteractiveHost(element) {
   return false;
 }
 
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
 // src/controllers/switch_controller.ts
 var OBSERVED_ATTRIBUTES = [
   "role",
@@ -49,17 +92,20 @@ var OBSERVED_ATTRIBUTES = [
 ];
 var OBSERVED_ANCESTOR_ATTRIBUTES = ["contenteditable"];
 var SwitchController = class extends Controller {
+  static targets = ["field"];
   static actions = ["onKeydown", "toggle"];
-  static events = ["changed"];
+  static events = ["change", "reconcile"];
   /** Defaults this instance introduced and may therefore remove safely. */
   #ownedDefaults = /* @__PURE__ */ new Set();
   /** Controller writes that must not be mistaken for authored morph changes. */
   #internalAttributeValues = /* @__PURE__ */ new Map();
+  /** One pass per batch of retained-element changes and field arrivals. */
+  #pass = new MicrotaskCoalescer(() => this.#reconcile());
+  /** The checked state last published: read on connect, then committed or reported. */
+  #committedChecked = false;
   #attributeObserver = new MutationObserver((records) => {
     this.#releaseAuthoredDefaults(records);
-    this.#attributeObserver.disconnect();
-    this.#reconcileDefaults();
-    this.#observeAttributes();
+    this.#pass.schedule();
   });
   /** Blocks disabled pointer/native-key activation before consumer click handlers. */
   #onClickCapture = (event) => {
@@ -67,14 +113,25 @@ var SwitchController = class extends Controller {
     event.preventDefault();
     event.stopImmediatePropagation();
   };
-  /** Ensures the switch exposes a role and is keyboard-reachable. */
+  /**
+   * Ensures the switch exposes a role and is keyboard-reachable, and takes the
+   * state it finds as the one a later move is measured from, reporting nothing.
+   */
   connect() {
     this.#reconcileDefaults();
+    this.#mirrorField(false);
+    this.#committedChecked = this.#checked;
     this.element.addEventListener("click", this.#onClickCapture, true);
+    this.#pass.activate();
     this.#observeAttributes();
   }
-  /** Releases the explicit click guard and retained-element attribute observer. */
+  /** Fills a form field inserted or replaced at runtime with the current state. */
+  fieldTargetConnected() {
+    this.#pass.schedule();
+  }
+  /** Releases the click guard, the attribute observer, and a pass still queued. */
   disconnect() {
+    this.#pass.cancel();
     this.element.removeEventListener("click", this.#onClickCapture, true);
     this.#attributeObserver.disconnect();
     this.#internalAttributeValues.clear();
@@ -82,7 +139,7 @@ var SwitchController = class extends Controller {
   /** Toggles the checked state. Bound via `data-action` (click). */
   toggle() {
     if (!this.#isSupportedHost || this.#isActivationDisabled) return;
-    this.#checked = !this.#checked;
+    this.#commit(!this.#checked);
   }
   /**
    * Activates the switch on Space/Enter for non-native hosts and suppresses key
@@ -107,6 +164,28 @@ var SwitchController = class extends Controller {
     if (event.repeat) return;
     this.toggle();
   }
+  /**
+   * Re-derives the defaults and the field after the page changed the host, then
+   * reports a checked state that moved. Records still queued are read first, so
+   * an author's write is not lost when observation is suspended for this pass's
+   * own writes; observation resumes before the report, so an edit a listener
+   * makes is seen by the next pass.
+   */
+  #reconcile() {
+    this.#releaseAuthoredDefaults(this.#attributeObserver.takeRecords());
+    this.#attributeObserver.disconnect();
+    this.#reconcileDefaults();
+    this.#mirrorField(false);
+    this.#observeAttributes();
+    this.#reportMove();
+  }
+  /** Reports a checked state that moved since the one this switch last published. */
+  #reportMove() {
+    const checked = this.#checked;
+    if (checked === this.#committedChecked) return;
+    this.#committedChecked = checked;
+    this.dispatch("reconcile", { detail: { checked } });
+  }
   /** Re-adds only missing defaults, preserving every authored attribute value. */
   #reconcileDefaults() {
     if (!this.#isSupportedHost) {
@@ -119,6 +198,12 @@ var SwitchController = class extends Controller {
       this.#setOwnedDefault("tabindex", "0");
     }
   }
+  /** Mirrors the checked state into the optional form field. */
+  #mirrorField(notify) {
+    if (!this.hasFieldTarget) return;
+    const moved = writeField(this.fieldTarget, this.#checked ? "true" : "false");
+    if (moved && notify) commitField(this.fieldTarget);
+  }
   /** Records a newly introduced default without claiming authored markup. */
   #setOwnedDefault(name, value) {
     if (setDefaultAttribute(this.element, name, value)) this.#ownedDefaults.add(name);
@@ -181,12 +266,18 @@ var SwitchController = class extends Controller {
   get #checked() {
     return this.element.getAttribute("aria-checked") === "true";
   }
-  /** Reflects the new state on `aria-checked` and notifies listeners. */
-  set #checked(value) {
+  /**
+   * Applies one toggle the user made. The state is taken as published before
+   * either report goes out, so a listener that toggles again or writes the
+   * attribute is measured from it.
+   */
+  #commit(value) {
     const reflected = value ? "true" : "false";
     this.#internalAttributeValues.set("aria-checked", reflected);
     this.element.setAttribute("aria-checked", reflected);
-    this.dispatch("changed", { detail: { checked: value } });
+    this.#committedChecked = value;
+    this.#mirrorField(true);
+    this.dispatch("change", { detail: { checked: value } });
   }
 };
 

data/dist/controllers/tabs_controller.js

@@ -17,6 +17,9 @@ function isReservedArrowChord(event, allow = []) {
 var TabsController = class extends Controller {
   static targets = ["tab", "panel", "list"];
   static actions = ["onKeydown", "select"];
+  static events = ["change"];
+  /** Whether selection moves are reported: set once `connect()` settled the baseline. */
+  #reporting = false;
   /**
    * Selects the initially active tab: the pre-selected one, else the first.
    *
@@ -30,6 +33,14 @@ var TabsController = class extends Controller {
       (tab) => tab.getAttribute("aria-selected") === "true"
     );
     this.#selectIndex(preselected === -1 ? 0 : preselected, { focus: false });
+    this.#reporting = true;
+  }
+  /**
+   * Stops reporting until the next `connect()` has settled its baseline, so that
+   * normalization stays silent.
+   */
+  disconnect() {
+    this.#reporting = false;
   }
   /** Selects the clicked tab. Bound via `data-action` (click). */
   select(event) {
@@ -69,7 +80,9 @@ var TabsController = class extends Controller {
    * `tabindex`, and panel visibility. Optionally moves focus to the new tab.
    */
   #selectIndex(index, { focus }) {
-    this.tabTargets.forEach((tab, i) => {
+    const tabs = this.tabTargets;
+    const previous = tabs.findIndex((tab) => tab.getAttribute("aria-selected") === "true");
+    tabs.forEach((tab, i) => {
       const selected = i === index;
       tab.setAttribute("aria-selected", selected ? "true" : "false");
       tab.tabIndex = selected ? 0 : -1;
@@ -77,7 +90,13 @@ var TabsController = class extends Controller {
     this.panelTargets.forEach((panel, i) => {
       panel.hidden = i !== index;
     });
-    if (focus) this.tabTargets[index]?.focus();
+    if (previous !== index && this.#reporting) {
+      this.dispatch("change", {
+        detail: { index, total: tabs.length, previous },
+        cancelable: false
+      });
+    }
+    if (focus && tabs[index]?.getAttribute("aria-selected") === "true") tabs[index]?.focus();
   }
 };