stimeo-ui 0.14.0 → 0.16.0

data/dist/controllers/separator_controller.js

@@ -230,24 +230,37 @@ var SeparatorController = class extends Controller {
     value: { type: Number, default: DEFAULT_MIN }
   };
   static actions = ["onKeydown"];
-  static events = ["change"];
+  static events = ["change", "reconcile"];
   #role = new AttributeLease("role");
   #tabindex = new AttributeLease("tabindex");
   #orientation = new AttributeLease("aria-orientation");
   #minimum = new AttributeLease("aria-valuemin");
   #maximum = new AttributeLease("aria-valuemax");
   #current = new AttributeLease("aria-valuenow");
-  /** Collapses a morph that changes several render Values into one silent repaint. */
+  /** Collapses a morph that changes several render Values into one repaint. */
   #repaint = new MicrotaskCoalescer(() => this.#render());
   /** Restores authored semantics before Turbo snapshots the element. */
   #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
-  /** Hydrates legacy ARIA input once, normalizes the current Value, and renders. */
+  /**
+   * The baseline a published value is compared with: the value last published
+   * through `aria-valuenow`, or `null` while this connection has published none.
+   * It moves to each value a key the user presses or a repaint publishes. While
+   * nothing is published — the separator is decorative — it keeps the last
+   * value published, so a value that moved meanwhile is reported once when the
+   * separator publishes again; one that connected decorative keeps `null`, so
+   * its first published value is only taken as the baseline.
+   */
+  #settled = null;
+  /**
+   * Hydrates authored range ARIA into absent Values once and renders them
+   * without writing the normalized value back. What the first render publishes
+   * is the baseline, so connecting reports nothing.
+   */
   connect() {
     this.#hydrateValues();
     this.#repaint.activate();
     this.#beforeCache.activate();
-    const value = this.#currentValue();
-    if (!Object.is(this.valueValue, value)) this.valueValue = value;
+    this.#settled = null;
     this.#render();
   }
   /** Cancels repaint work and returns every semantic attribute this instance controlled. */
@@ -256,27 +269,27 @@ var SeparatorController = class extends Controller {
     this.#beforeCache.deactivate();
     this.#returnAttributes();
   }
-  /** Silently repaints an orientation changed by application code or a Turbo morph. */
+  /** Repaints an orientation changed by application code or a Turbo morph. */
   orientationValueChanged() {
     this.#repaint.schedule();
   }
-  /** Silently adds or removes the focusable range semantics at runtime. */
+  /** Adds or removes the focusable range semantics at runtime. */
   focusableValueChanged() {
     this.#repaint.schedule();
   }
-  /** Silently repaints a minimum changed by application code or a Turbo morph. */
+  /** Repaints a minimum changed by application code or a Turbo morph. */
   minValueChanged() {
     this.#repaint.schedule();
   }
-  /** Silently repaints a maximum changed by application code or a Turbo morph. */
+  /** Repaints a maximum changed by application code or a Turbo morph. */
   maxValueChanged() {
     this.#repaint.schedule();
   }
-  /** Silently repaints a step changed by application code or a Turbo morph. */
+  /** Repaints a step changed by application code or a Turbo morph. */
   stepValueChanged() {
     this.#repaint.schedule();
   }
-  /** Silently repaints a current value changed by application code or a Turbo morph. */
+  /** Repaints a current value changed by application code or a Turbo morph. */
   valueValueChanged() {
     this.#repaint.schedule();
   }
@@ -285,20 +298,20 @@ var SeparatorController = class extends Controller {
     if (isReservedArrowChord(event) || !this.focusableValue) return;
     const horizontal = this.#effectiveOrientation === "horizontal";
     const range = this.#effectiveRange;
-    const current = snapSteppedValue(this.valueValue, range);
+    const declared = this.valueValue;
     let next = null;
     switch (event.key) {
       case "ArrowUp":
-        if (horizontal) next = stepSteppedValue(current, 1, range);
+        if (horizontal) next = stepSteppedValue(declared, 1, range);
         break;
       case "ArrowDown":
-        if (horizontal) next = stepSteppedValue(current, -1, range);
+        if (horizontal) next = stepSteppedValue(declared, -1, range);
         break;
       case "ArrowRight":
-        if (!horizontal) next = stepSteppedValue(current, 1, range);
+        if (!horizontal) next = stepSteppedValue(declared, 1, range);
         break;
       case "ArrowLeft":
-        if (!horizontal) next = stepSteppedValue(current, -1, range);
+        if (!horizontal) next = stepSteppedValue(declared, -1, range);
         break;
       case "Home":
         next = range.min;
@@ -311,36 +324,51 @@ var SeparatorController = class extends Controller {
     }
     if (next === null) return;
     event.preventDefault();
-    this.#commit(next, current);
+    this.#commit(next);
   }
-  /** Stores a normalized user value, renders immediately, and reports real changes. */
-  #commit(raw, previous) {
+  /**
+   * Stores a normalized user value, renders immediately, and reports it as
+   * `change` when it differs from the value last published. The comparison is
+   * with the value last published, not with the value the key started from, so
+   * a page write no repaint has published yet is reported once, as this change,
+   * and a key that ends where the value was last published reports nothing. The
+   * baseline moves before the render and the report, so neither the repaint the
+   * Value write schedules nor a move a subscriber makes while `change` is
+   * dispatched is measured from the value this key replaced.
+   */
+  #commit(raw) {
     const value = snapSteppedValue(raw, this.#effectiveRange);
+    const reported = this.#settled;
+    this.#settled = value;
     if (!Object.is(this.valueValue, value)) this.valueValue = value;
     this.#render();
-    if (value !== previous) this.dispatch("change", { detail: { value } });
+    if (value !== reported) this.dispatch("change", { detail: { value } });
   }
   /**
-   * Reflects live Values into the connected element without dispatching.
+   * Reflects live Values into the connected element without writing them back,
+   * then compares what it published with the baseline. A decorative separator
+   * publishes no value (`null` here): the baseline stays the last value
+   * published. A value is reported once as `reconcile` only when it moved from a
+   * published baseline, so the first value a connection publishes is only taken
+   * as the baseline.
    *
    * @stimeoRenderRoot
    */
   #render() {
     const range = this.#effectiveRange;
-    const value = snapSteppedValue(this.valueValue, range);
+    const focusable = this.focusableValue;
+    const published = focusable ? snapSteppedValue(this.valueValue, range) : null;
     this.#role.write(this.element, "separator");
     this.#orientation.write(this.element, this.#effectiveOrientation);
-    if (!this.focusableValue) {
-      this.#tabindex.write(this.element, null);
-      this.#minimum.write(this.element, null);
-      this.#maximum.write(this.element, null);
-      this.#current.write(this.element, null);
-      return;
+    this.#tabindex.write(this.element, focusable ? "0" : null);
+    this.#minimum.write(this.element, focusable ? String(range.min) : null);
+    this.#maximum.write(this.element, focusable ? String(range.max) : null);
+    this.#current.write(this.element, published === null ? null : String(published));
+    const previous = this.#settled;
+    if (published !== null) this.#settled = published;
+    if (previous !== null && published !== null && published !== previous) {
+      this.dispatch("reconcile", { detail: { value: published } });
     }
-    this.#tabindex.write(this.element, "0");
-    this.#minimum.write(this.element, String(range.min));
-    this.#maximum.write(this.element, String(range.max));
-    this.#current.write(this.element, String(value));
   }
   /** Effective orientation; unknown strings fall back to the horizontal contract. */
   get #effectiveOrientation() {
@@ -357,11 +385,12 @@ var SeparatorController = class extends Controller {
       base: min
     };
   }
-  /** Current normalized value derived from the live declarative inputs. */
-  #currentValue() {
-    return snapSteppedValue(this.valueValue, this.#effectiveRange);
-  }
-  /** Copies valid authored ARIA into Values only when no explicit Value exists. */
+  /**
+   * Copies valid authored ARIA into Values only when no explicit Value exists.
+   * This fill is the one Value write `connect()` makes: it never overwrites a
+   * declaration, and no Value callback runs it, so a declaration the page
+   * changes later is only ever read.
+   */
   #hydrateValues() {
     if (!this.#hasInput("orientation")) {
       const orientation = this.element.getAttribute("aria-orientation");

data/dist/controllers/sidebar_controller.js

@@ -382,6 +382,16 @@ function writeLocalStorage(key, value) {
   }
 }
 
+// src/utils/state_reason.ts
+var FOCUS_EVENTS = /* @__PURE__ */ new Set(["blur", "focus", "focusin", "focusout"]);
+var POINTER_EVENTS = /* @__PURE__ */ new Set(["mouseenter", "mouseleave", "pointerenter", "pointerleave"]);
+function stateReasonFor(event) {
+  if (!event) return "api";
+  if (FOCUS_EVENTS.has(event.type)) return "focus";
+  if (POINTER_EVENTS.has(event.type)) return "pointer";
+  return "user";
+}
+
 // src/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -585,11 +595,12 @@ var SidebarController = class extends Controller {
     collapsed: { type: Boolean, default: false }
   };
   static actions = ["close", "open", "toggle"];
+  static events = ["close", "open", "reconcile"];
   /** Exact panel currently owned by the modal lifecycle (survives target churn safely). */
   #activePanel = null;
   /** Owns the overlay modal side effects; Escape closes, focus falls to trigger. */
   #trap = new FocusTrap(() => this.#activePanel ?? this.panelTarget, {
-    onEscape: () => this.close(),
+    onEscape: () => this.#closeOverlay("escape"),
     fallbackFocus: () => this.hasTriggerTarget ? this.triggerTarget : null
   });
   /** Current responsive mode. */
@@ -604,6 +615,8 @@ var SidebarController = class extends Controller {
   #transition = new TransitionCompletion();
   /** Distinguishes dynamic target churn from callbacks around controller teardown. */
   #connected = false;
+  /** Whether state moves are reported: set once `connect()` settled the baseline. */
+  #reporting = false;
   connect() {
     this.#connected = true;
     this.#beforeCache.activate();
@@ -612,10 +625,12 @@ var SidebarController = class extends Controller {
     this.#mqlQuery = this.#breakpointQuery;
     this.#mql = this.#matchBreakpoint(this.#mqlQuery);
     this.#mql?.addEventListener("change", this.#onMediaChange);
-    this.#applyMode(this.#computeMode());
+    this.#applyMode(this.#computeMode(), false);
+    this.#reporting = true;
   }
   disconnect() {
     this.#connected = false;
+    this.#reporting = false;
     this.#beforeCache.deactivate();
     this.#mql?.removeEventListener("change", this.#onMediaChange);
     this.#mql = null;
@@ -658,7 +673,7 @@ var SidebarController = class extends Controller {
     this.#mql = this.#matchBreakpoint(query);
     this.#mql?.addEventListener("change", this.#onMediaChange);
     const next = this.#computeMode();
-    if (next !== this.#mode) this.#applyMode(next);
+    if (next !== this.#mode) this.#applyMode(next, true);
   }
   /**
    * Sanitizes overlay markup before Turbo snapshots the page.
@@ -675,26 +690,44 @@ var SidebarController = class extends Controller {
     this.#setOverlayClosedImmediate();
   });
   /** Toggles the panel: inline flips collapsed/expanded, overlay flips open/closed. */
-  toggle() {
+  toggle(event) {
+    const reason = stateReasonFor(event);
     if (this.#isOverlay) {
-      this.#isOverlayOpen ? this.#closeOverlay() : this.#openOverlay();
+      this.#isOverlayOpen ? this.#closeOverlay(reason) : this.#openOverlay(reason);
     } else {
-      this.#setCollapsed(!this.#collapsed);
+      this.#setCollapsed(!this.#collapsed, reason);
     }
   }
   /** Shows the panel (inline: expand; overlay: open). */
-  open() {
-    if (this.#isOverlay) this.#openOverlay();
-    else this.#setCollapsed(false);
+  open(event) {
+    const reason = stateReasonFor(event);
+    if (this.#isOverlay) this.#openOverlay(reason);
+    else this.#setCollapsed(false, reason);
   }
   /** Hides the panel (inline: collapse; overlay: close). */
-  close() {
-    if (this.#isOverlay) this.#closeOverlay();
-    else this.#setCollapsed(true);
+  close(event) {
+    const reason = this.#closeReason(event);
+    if (this.#isOverlay) this.#closeOverlay(reason);
+    else this.#setCollapsed(true, reason);
+  }
+  /**
+   * Reads why a close happened. The backdrop has no action of its own — the
+   * consumer wires this one onto it — so the shared `"outside"` vocabulary is
+   * only reachable by recognising that target here.
+   */
+  #closeReason(event) {
+    if (this.hasBackdropTarget && event?.currentTarget === this.backdropTarget) return "outside";
+    return stateReasonFor(event);
   }
   // --- Mode handling ---------------------------------------------------------
-  /** Re-renders the closed/default state for `mode` and records it. */
-  #applyMode(mode) {
+  /**
+   * Re-renders the closed/default state for `mode` and records it.
+   *
+   * @param report - Whether the mode change is one the consumer can observe: a
+   *   viewport change re-derives the state under them, the connect-time baseline
+   *   does not.
+   */
+  #applyMode(mode, report) {
     this.#mode = mode;
     if (this.hasPanelTarget) this.panelTarget.setAttribute("data-mode", mode);
     if (mode === "inline") {
@@ -708,6 +741,12 @@ var SidebarController = class extends Controller {
       this.#trap.deactivate({ restoreFocus: false });
       this.#setOverlayClosedImmediate();
     }
+    if (report && this.#reporting) {
+      this.dispatch("reconcile", {
+        detail: { mode, open: this.#isExpanded },
+        cancelable: false
+      });
+    }
   }
   /** Reconciles a replacement panel with the current responsive mode and DOM state. */
   #adoptPanel(panel) {
@@ -742,7 +781,7 @@ var SidebarController = class extends Controller {
   }
   #onMediaChange = (event) => {
     const next = event.matches ? "inline" : "overlay";
-    if (next !== this.#mode) this.#applyMode(next);
+    if (next !== this.#mode) this.#applyMode(next, true);
   };
   #computeMode() {
     return this.#mql?.matches ?? true ? "inline" : "overlay";
@@ -753,10 +792,11 @@ var SidebarController = class extends Controller {
   }
   // --- Inline (rail) ---------------------------------------------------------
   /** Sets, reflects, and persists the inline collapsed preference. */
-  #setCollapsed(collapsed) {
+  #setCollapsed(collapsed, reason) {
     if (collapsed === this.#collapsed) return;
     this.#collapsed = collapsed;
     this.#applyInlineState(collapsed);
+    this.#report(!collapsed, reason);
     this.#persistCollapsed(collapsed);
   }
   /** Reflects the inline rail state onto the panel and trigger. */
@@ -768,7 +808,7 @@ var SidebarController = class extends Controller {
   }
   // --- Overlay (off-canvas modal) -------------------------------------------
   /** Opens the overlay: reveal it, commit a starting frame, then trap focus. */
-  #openOverlay() {
+  #openOverlay(reason) {
     if (!this.hasPanelTarget || this.#isOverlayOpen) return;
     this.#transition.cancel();
     this.#activePanel = this.panelTarget;
@@ -777,13 +817,17 @@ var SidebarController = class extends Controller {
     void this.panelTarget.offsetWidth;
     this.#setOverlayState("open");
     this.#setExpandedAttr(true);
+    this.#report(true, reason);
+    if (!this.#isOverlayOpen) return;
     this.#trap.activate();
   }
   /** Closes the overlay: start the exit transition, defer hide + trap teardown. */
-  #closeOverlay() {
+  #closeOverlay(reason) {
     if (!this.hasPanelTarget || !this.#isOverlayOpen) return;
     this.#setOverlayState("closed");
     this.#setExpandedAttr(false);
+    this.#report(false, reason);
+    if (this.#isOverlayOpen) return;
     this.#hideAfterTransition();
   }
   /** Renders the overlay closed state up front (used when entering overlay mode). */
@@ -826,6 +870,17 @@ var SidebarController = class extends Controller {
       this.triggerTarget.setAttribute("aria-expanded", expanded ? "true" : "false");
     }
   }
+  /** Reports a move of the expanded state, naming the mode it happened in. */
+  #report(open, reason) {
+    if (!this.#reporting) return;
+    const detail = { reason, mode: this.#mode };
+    if (open) this.dispatch("open", { detail, cancelable: false });
+    else this.dispatch("close", { detail, cancelable: false });
+  }
+  /** Whether the panel currently counts as expanded in the mode it is in. */
+  get #isExpanded() {
+    return this.#isOverlay ? this.#isOverlayOpen : !this.#collapsed;
+  }
   /**
    * Resolves the inline collapsed preference, in priority order:
    *   1. the persisted value (when a `key` is set and storage is readable),
@@ -851,6 +906,10 @@ var SidebarController = class extends Controller {
     if (!key) return;
     writeLocalStorage(key, collapsed ? "1" : "0");
   }
+  /**
+   * @stimeoRuntimeOnly `key` names the storage slot the collapsed state is saved under; the state
+   *   itself comes from the user.
+   */
   get #storageKey() {
     return this.keyValue ? `stimeo--sidebar:${this.keyValue}` : "";
   }

data/dist/controllers/skeleton_controller.js

@@ -215,7 +215,12 @@ var SkeletonController = class extends Controller {
     this.element.setAttribute("aria-busy", "true");
     this.element.setAttribute("data-state", "loading");
   }
-  /** Hides the placeholder, shows content, and clears the busy state. */
+  /**
+   * Hides the placeholder, shows content, and clears the busy state.
+   *
+   * @stimeoRuntimeOnly `announceReadyText` is the wording of the one announcement this reveal
+   *   makes.
+   */
   #reveal() {
     if (this.hasPlaceholderTarget) this.placeholderTarget.hidden = true;
     if (this.hasContentTarget) this.contentTarget.hidden = false;