stimeo-ui 0.2.0 → 0.3.0

package/dist/controllers/sidebar_controller.js

@@ -0,0 +1,761 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/sidebar_controller.ts
+
+// src/utils/escape_layer.ts
+var EscapeLayer = class _EscapeLayer {
+  static #registries = /* @__PURE__ */ new WeakMap();
+  #ownerDocument = null;
+  /** Dismissal callback while active; `null` when inactive. */
+  #onDismiss = null;
+  /** Live predicate deciding whether the layer claims a press; `null` = always. */
+  #claims = null;
+  /**
+   * Activates this layer at the top of its document's Escape stack, installing
+   * the document's shared resolver listener if this is its first layer.
+   * Re-activating an already-active layer moves it to the top.
+   */
+  activate(ownerDocument = document, options) {
+    this.deactivate();
+    let registry = _EscapeLayer.#registries.get(ownerDocument);
+    if (!registry) {
+      registry = _EscapeLayer.#createRegistry();
+      _EscapeLayer.#registries.set(ownerDocument, registry);
+      ownerDocument.addEventListener("keydown", registry.onKeydown);
+    }
+    registry.stack.push(this);
+    this.#ownerDocument = ownerDocument;
+    this.#onDismiss = options.onDismiss;
+    this.#claims = options.claims ?? null;
+  }
+  /**
+   * Removes this layer from its document's Escape stack, uninstalling the
+   * shared listener when the stack empties. Safe to call when inactive.
+   */
+  deactivate() {
+    const ownerDocument = this.#ownerDocument;
+    if (!ownerDocument) return;
+    const registry = _EscapeLayer.#registries.get(ownerDocument);
+    if (registry) {
+      const index = registry.stack.lastIndexOf(this);
+      if (index >= 0) registry.stack.splice(index, 1);
+      if (registry.stack.length === 0) {
+        ownerDocument.removeEventListener("keydown", registry.onKeydown);
+        _EscapeLayer.#registries.delete(ownerDocument);
+      }
+    }
+    this.#ownerDocument = null;
+    this.#onDismiss = null;
+    this.#claims = null;
+  }
+  /**
+   * Whether this active layer would own a press right now: it is the topmost
+   * layer whose {@link EscapeLayerOptions.claims} passes. Exposed for tests
+   * and diagnostics — production dismissal goes through the shared listener.
+   */
+  get ownsEscape() {
+    const ownerDocument = this.#ownerDocument;
+    if (!ownerDocument) return false;
+    const registry = _EscapeLayer.#registries.get(ownerDocument);
+    if (!registry) return false;
+    return _EscapeLayer.#resolveOwner(registry.stack) === this;
+  }
+  /** Builds a document's registry with its shared resolver listener. */
+  static #createRegistry() {
+    const registry = {
+      stack: [],
+      onKeydown: (event) => {
+        if (event.key !== "Escape" || event.defaultPrevented || event.isComposing) return;
+        const owner = _EscapeLayer.#resolveOwner(registry.stack);
+        if (!owner) return;
+        event.preventDefault();
+        owner.#onDismiss?.();
+      }
+    };
+    return registry;
+  }
+  /** The topmost stack layer whose claims predicate passes, or `null`. */
+  static #resolveOwner(stack) {
+    for (let index = stack.length - 1; index >= 0; index--) {
+      const layer = stack[index];
+      if (!layer) continue;
+      if (layer.#claims && !layer.#claims()) continue;
+      return layer;
+    }
+    return null;
+  }
+};
+
+// src/utils/focus_trap.ts
+var FOCUSABLE = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+var FocusTrap = class {
+  /** The element focused before activation, restored on deactivation. */
+  #previouslyFocused = null;
+  /** The body's inline `overflow` before locking, restored on deactivation. */
+  #previousBodyOverflow = "";
+  /** Whether scroll was locked this activation (so it is only restored if applied). */
+  #scrollLocked = false;
+  /** Background siblings made `inert` while active, restored on deactivation. */
+  #inertedSiblings = [];
+  /** Whether the modal side effects are currently applied. */
+  #activeState = false;
+  /** Registers the trap on the shared Escape stack while active (see {@link EscapeLayer}). */
+  #escapeLayer = new EscapeLayer();
+  /** Returns the trapped element; called on every operation for the live target. */
+  #getContainer;
+  /** Closing/focus hooks; see {@link FocusTrapOptions}. */
+  #options;
+  /**
+   * @param getContainer - Returns the trapped element. Called on every operation
+   *   so the live target is always used.
+   * @param options - Closing/focus hooks; see {@link FocusTrapOptions}.
+   */
+  constructor(getContainer, options = {}) {
+    this.#getContainer = getContainer;
+    this.#options = options;
+  }
+  /** Whether the trap is currently active. */
+  get active() {
+    return this.#activeState;
+  }
+  /**
+   * Applies the trap: records the current focus, optionally locks background scroll
+   * and makes background siblings `inert`, listens for `Tab`/`Escape`, and (unless
+   * `autoFocus` is off) moves focus inside. No-ops if already active.
+   */
+  activate() {
+    if (this.#activeState) return;
+    this.#activeState = true;
+    const active = document.activeElement;
+    this.#previouslyFocused = active instanceof HTMLElement && active !== document.body ? active : null;
+    if (this.#flag(this.#options.lockScroll, true)) {
+      this.#previousBodyOverflow = document.body.style.overflow;
+      document.body.style.overflow = "hidden";
+      this.#scrollLocked = true;
+    }
+    if (this.#flag(this.#options.isolate, true)) this.#isolateBackground();
+    document.addEventListener("keydown", this.#onKeydown);
+    document.addEventListener("turbo:before-cache", this.#onBeforeCache);
+    const onEscape = this.#options.onEscape;
+    if (onEscape) this.#escapeLayer.activate(document, { onDismiss: () => onEscape() });
+    if (this.#flag(this.#options.autoFocus, true)) this.#focusInitial();
+  }
+  /**
+   * Reverts every side effect applied by {@link activate}. No-ops if inactive, so
+   * a controller can call it defensively from both `close()` and `disconnect()`.
+   *
+   * @param restoreFocus - Move focus back to the opener (default `true`). Pass
+   *   `false` on teardown (`disconnect`), where yanking focus is undesirable.
+   */
+  deactivate({ restoreFocus = true } = {}) {
+    if (!this.#activeState) return;
+    this.#activeState = false;
+    this.#escapeLayer.deactivate();
+    document.removeEventListener("keydown", this.#onKeydown);
+    document.removeEventListener("turbo:before-cache", this.#onBeforeCache);
+    if (this.#scrollLocked) {
+      document.body.style.overflow = this.#previousBodyOverflow;
+      this.#scrollLocked = false;
+    }
+    this.#releaseBackground();
+    if (restoreFocus) {
+      const target = this.#previouslyFocused ?? this.#options.fallbackFocus?.() ?? null;
+      target?.focus();
+    }
+  }
+  /** Resolves a boolean-or-getter option, defaulting when it was not provided. */
+  #flag(option, fallback) {
+    if (option === void 0) return fallback;
+    return typeof option === "function" ? option() : option;
+  }
+  /**
+   * Reverts the side effects just before Turbo caches the page snapshot, so an
+   * overlay left open does not bake the scroll lock into `body[style]` — a
+   * restored page would feed that locked value back into {@link activate} as the
+   * baseline, and closing would then never unlock the page. Markup state stays
+   * untouched (restore-open designs reopen against a clean baseline), and focus
+   * is left alone mid-navigation. The listener lives only while active.
+   */
+  #onBeforeCache = () => {
+    this.deactivate({ restoreFocus: false });
+  };
+  /**
+   * Handles `Tab` (focus trap) while active. `Escape` dismissal is owned by the
+   * shared {@link EscapeLayer} resolver, so Tab trapping stays independent of
+   * which layer currently owns Escape.
+   */
+  #onKeydown = (event) => {
+    if (event.key === "Tab") this.#trapTab(event);
+  };
+  /** Keeps `Tab` focus cycling within the container's focusable elements. */
+  #trapTab(event) {
+    const focusable = this.#focusableElements();
+    if (focusable.length === 0) {
+      event.preventDefault();
+      return;
+    }
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    const active = document.activeElement;
+    if (!(active instanceof Node) || !this.#getContainer().contains(active)) {
+      event.preventDefault();
+      first?.focus();
+      return;
+    }
+    if (event.shiftKey && active === first) {
+      event.preventDefault();
+      last?.focus();
+    } else if (!event.shiftKey && active === last) {
+      event.preventDefault();
+      first?.focus();
+    }
+  }
+  /**
+   * Marks every element outside the container's subtree as `inert` so background
+   * content cannot be focused or reached by assistive technology, honoring the
+   * `aria-modal="true"` contract. An element that was *already* `inert` is left
+   * untracked so `#releaseBackground` does not wrongly clear it.
+   */
+  #isolateBackground() {
+    const container = this.#getContainer();
+    this.#inertedSiblings = [];
+    for (const sibling of Array.from(document.body.children)) {
+      if (!(sibling instanceof HTMLElement)) continue;
+      if (sibling.contains(container) || sibling.inert) continue;
+      sibling.inert = true;
+      this.#inertedSiblings.push(sibling);
+    }
+  }
+  /** Reverts the `inert` flags applied by `#isolateBackground`. */
+  #releaseBackground() {
+    for (const sibling of this.#inertedSiblings) {
+      sibling.inert = false;
+    }
+    this.#inertedSiblings = [];
+  }
+  /** Moves focus to the initial target, the first focusable, or the container. */
+  #focusInitial() {
+    const preferred = this.#options.initialFocus?.();
+    if (preferred) {
+      preferred.focus();
+      return;
+    }
+    const focusable = this.#focusableElements();
+    if (focusable[0]) {
+      focusable[0].focus();
+      return;
+    }
+    const container = this.#getContainer();
+    container.tabIndex = -1;
+    container.focus();
+  }
+  /** Collects the container's currently focusable descendants in DOM order. */
+  #focusableElements() {
+    return Array.from(this.#getContainer().querySelectorAll(FOCUSABLE)).filter(
+      (el) => !el.hidden
+    );
+  }
+};
+
+// src/utils/safe_storage.ts
+function readLocalStorage(key) {
+  try {
+    return window.localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+function writeLocalStorage(key, value) {
+  try {
+    window.localStorage.setItem(key, value);
+  } catch {
+  }
+}
+
+// src/utils/safe_timeout.ts
+var TimerRegistry = class {
+  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
+  ids = /* @__PURE__ */ new Set();
+  /**
+   * Cancels a single tracked timer.
+   *
+   * No-ops if the id is unknown (already cleared, fired, or never owned by this
+   * registry), so callers can clear defensively without guarding.
+   */
+  clear(id) {
+    if (this.ids.delete(id)) {
+      this.cancel(id);
+    }
+  }
+  /**
+   * Cancels every tracked timer. Call this from a controller's `disconnect()`
+   * to guarantee no timer outlives the element.
+   */
+  clearAll() {
+    for (const id of this.ids) {
+      this.cancel(id);
+    }
+    this.ids.clear();
+  }
+  /** Number of timers currently tracked (pending). */
+  get size() {
+    return this.ids.size;
+  }
+};
+var SafeTimeout = class extends TimerRegistry {
+  /**
+   * Schedules `callback` after `delay` ms and returns the timer id.
+   *
+   * The id is removed from the registry automatically when the timeout fires,
+   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
+   */
+  set(callback, delay) {
+    const id = this.schedule(() => {
+      this.ids.delete(id);
+      callback();
+    }, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setTimeout(callback, delay);
+  }
+  cancel(id) {
+    window.clearTimeout(id);
+  }
+};
+
+// src/utils/transition_completion.ts
+function timeMs(value) {
+  const trimmed = value.trim();
+  const amount = Number.parseFloat(trimmed);
+  if (!Number.isFinite(amount)) return 0;
+  if (trimmed.endsWith("ms")) return amount;
+  if (trimmed.endsWith("s")) return amount * 1e3;
+  return 0;
+}
+function cssList(value) {
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function transitionTimings(style) {
+  const properties = cssList(style.transitionProperty);
+  const durations = cssList(style.transitionDuration).map(timeMs);
+  const delays = cssList(style.transitionDelay).map(timeMs);
+  const effectiveProperties = properties.length > 0 ? properties : Array.from({ length: Math.max(durations.length, delays.length, 1) }, () => "all");
+  const effectiveDurations = durations.length > 0 ? durations : [0];
+  const effectiveDelays = delays.length > 0 ? delays : [0];
+  return effectiveProperties.filter((property) => property !== "none").map((property, index) => ({
+    property,
+    totalMs: Math.max(
+      0,
+      (effectiveDurations[index % effectiveDurations.length] ?? 0) + (effectiveDelays[index % effectiveDelays.length] ?? 0)
+    )
+  }));
+}
+function maxTotalMs(timings) {
+  return timings.reduce((max, { totalMs }) => Math.max(max, totalMs), 0);
+}
+var TransitionCompletion = class {
+  #timers = new SafeTimeout();
+  #element = null;
+  #complete = null;
+  #pendingProperties = null;
+  #deadline = 0;
+  /**
+   * Replaces any prior wait and invokes `complete` synchronously for a 0ms
+   * transition (including when `getComputedStyle` is unavailable).
+   *
+   * With a positive `options.timeoutMs` the synchronous fast-path is skipped and
+   * the override replaces the auto-computed fallback (see {@link TransitionWaitOptions}).
+   */
+  wait(element, complete, options = {}) {
+    this.cancel();
+    const requested = options.timeoutMs ?? 0;
+    const override = Number.isFinite(requested) && requested > 0 ? requested : 0;
+    const timings = typeof window.getComputedStyle === "function" ? transitionTimings(window.getComputedStyle(element)) : [];
+    const maximum = maxTotalMs(timings);
+    if (maximum <= 0 && override <= 0) {
+      complete();
+      return;
+    }
+    this.#element = element;
+    this.#complete = complete;
+    this.#deadline = Date.now() + maximum;
+    const activeProperties = this.#activeTransitionProperties(element);
+    this.#pendingProperties = activeProperties.size > 0 ? activeProperties : this.#explicitPendingProperties(timings);
+    element.addEventListener("transitionend", this.#onTerminal);
+    element.addEventListener("transitioncancel", this.#onTerminal);
+    this.#timers.set(() => this.#finish(), override > 0 ? override : maximum + 50);
+  }
+  /** Cancels the pending wait without invoking its completion callback. */
+  cancel() {
+    this.#complete = null;
+    this.#teardown();
+  }
+  /**
+   * Handles terminal events from the observed element only.
+   *
+   * For explicit property lists, every declared positive-time property must
+   * settle. For `all`, no reliable property set exists, so an event can finish
+   * only after the computed maximum time; the safety timeout owns the usual path.
+   */
+  #onTerminal = (event) => {
+    if (event.target !== this.#element) return;
+    const transitionEvent = event;
+    if (transitionEvent.pseudoElement) return;
+    if (this.#pendingProperties) {
+      const propertyName = transitionEvent.propertyName;
+      const active = this.#activeTransitionProperties(this.#element);
+      if (active.has(propertyName)) return;
+      if (!this.#pendingProperties.delete(propertyName)) return;
+      if (this.#pendingProperties.size > 0) return;
+      if (active.size > 0) {
+        this.#pendingProperties = active;
+        return;
+      }
+      this.#finish();
+      return;
+    }
+    if (Date.now() >= this.#deadline) this.#finish();
+  };
+  /**
+   * Returns active CSS transition properties expanded to the names reported by
+   * terminal events. CSS animations and pseudo-element effects are excluded.
+   */
+  #activeTransitionProperties(element) {
+    if (!element || typeof element.getAnimations !== "function") return /* @__PURE__ */ new Set();
+    try {
+      const properties = element.getAnimations().flatMap((animation) => {
+        if (animation.playState === "idle" || animation.playState === "finished") return [];
+        const effect = animation.effect;
+        if (effect?.pseudoElement) return [];
+        const target = effect?.target;
+        if (target && target !== element) return [];
+        const property = animation.transitionProperty;
+        return typeof property === "string" && property.length > 0 ? [property] : [];
+      });
+      return new Set(properties);
+    } catch {
+      return /* @__PURE__ */ new Set();
+    }
+  }
+  /** Returns explicit positive-time properties, or `null` for the ambiguous `all`. */
+  #explicitPendingProperties(timings) {
+    if (timings.some(({ property }) => property === "all")) return null;
+    const pending = new Set(
+      timings.filter(({ totalMs }) => totalMs > 0).map(({ property }) => property)
+    );
+    return pending.size > 0 ? pending : null;
+  }
+  /** Completes exactly once, releasing listeners and the fallback before the callback. */
+  #finish() {
+    const complete = this.#complete;
+    if (!complete) return;
+    this.#complete = null;
+    this.#teardown();
+    complete();
+  }
+  /** Releases the exact element listeners and timer owned by the current wait. */
+  #teardown() {
+    this.#timers.clearAll();
+    this.#element?.removeEventListener("transitionend", this.#onTerminal);
+    this.#element?.removeEventListener("transitioncancel", this.#onTerminal);
+    this.#element = null;
+    this.#pendingProperties = null;
+    this.#deadline = 0;
+  }
+};
+
+// src/controllers/sidebar_controller.ts
+var SidebarController = class extends Controller {
+  static targets = ["trigger", "panel", "backdrop"];
+  static values = {
+    breakpoint: { type: Number, default: 768 },
+    key: { type: String, default: "" },
+    collapsed: { type: Boolean, default: false }
+  };
+  static actions = ["beforeCache", "close", "open", "toggle"];
+  /** 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(),
+    fallbackFocus: () => this.hasTriggerTarget ? this.triggerTarget : null
+  });
+  /** Current responsive mode. */
+  #mode = "inline";
+  /** Persisted inline preference: whether the rail is collapsed. */
+  #collapsed = false;
+  /** The matched media query (`min-width: breakpoint`), watched for mode changes. */
+  #mql = null;
+  /** Exact normalized query currently represented by the active media-query listener. */
+  #mqlQuery = null;
+  /** Owns the cancellable close-transition wait and its bounded fallback. */
+  #transition = new TransitionCompletion();
+  /** Distinguishes dynamic target churn from callbacks around controller teardown. */
+  #connected = false;
+  connect() {
+    this.#connected = true;
+    this.#activePanel = this.hasPanelTarget ? this.panelTarget : null;
+    this.#collapsed = this.#restoreCollapsed();
+    this.#mqlQuery = this.#breakpointQuery;
+    this.#mql = this.#matchBreakpoint(this.#mqlQuery);
+    this.#mql?.addEventListener("change", this.#onMediaChange);
+    this.#applyMode(this.#computeMode());
+  }
+  disconnect() {
+    this.#connected = false;
+    this.#mql?.removeEventListener("change", this.#onMediaChange);
+    this.#mql = null;
+    this.#mqlQuery = null;
+    this.#transition.cancel();
+    this.#trap.deactivate({ restoreFocus: false });
+    this.#activePanel = null;
+  }
+  /** Adopts a panel target added by a Turbo morph after the controller connected. */
+  panelTargetConnected(panel) {
+    if (!this.#connected || this.#activePanel?.isConnected && this.#activePanel !== panel) return;
+    this.#adoptPanel(panel);
+  }
+  /** Closes and releases overlay side effects when the actively trapped panel disappears. */
+  panelTargetDisconnected(panel) {
+    if (panel !== this.#activePanel) return;
+    this.#transition.cancel();
+    this.#activePanel = null;
+    if (!this.#connected) return;
+    panel.setAttribute("data-state", "closed");
+    panel.hidden = true;
+    this.#hideBackdrop();
+    this.#setExpandedAttr(false);
+    this.#trap.deactivate();
+    if (this.hasPanelTarget) this.#adoptPanel(this.panelTarget);
+  }
+  /**
+   * Rebinds responsive observation when `breakpoint` changes at runtime.
+   *
+   * Stimulus calls value callbacks before `connect()`, so the connected guard
+   * prevents an eager subscription. Equivalent normalized queries retain the
+   * existing listener instead of allocating duplicate `MediaQueryList` objects.
+   */
+  breakpointValueChanged() {
+    if (!this.#connected) return;
+    const query = this.#breakpointQuery;
+    if (this.#mqlQuery === query) return;
+    this.#mql?.removeEventListener("change", this.#onMediaChange);
+    this.#mqlQuery = query;
+    this.#mql = this.#matchBreakpoint(query);
+    this.#mql?.addEventListener("change", this.#onMediaChange);
+    const next = this.#computeMode();
+    if (next !== this.#mode) this.#applyMode(next);
+  }
+  /**
+   * Sanitizes overlay markup before Turbo snapshots the page.
+   *
+   * Inline state is durable and remains untouched. Overlay state is transient:
+   * pending transitions are cancelled, controller-owned open attributes are
+   * closed immediately, and modal side effects are released without moving
+   * focus during navigation.
+   */
+  beforeCache() {
+    if (!this.#connected || !this.#isOverlay) return;
+    this.#transition.cancel();
+    this.#trap.deactivate({ restoreFocus: false });
+    this.#setOverlayClosedImmediate();
+  }
+  /** Toggles the panel: inline flips collapsed/expanded, overlay flips open/closed. */
+  toggle() {
+    if (this.#isOverlay) {
+      this.#isOverlayOpen ? this.#closeOverlay() : this.#openOverlay();
+    } else {
+      this.#setCollapsed(!this.#collapsed);
+    }
+  }
+  /** Shows the panel (inline: expand; overlay: open). */
+  open() {
+    if (this.#isOverlay) this.#openOverlay();
+    else this.#setCollapsed(false);
+  }
+  /** Hides the panel (inline: collapse; overlay: close). */
+  close() {
+    if (this.#isOverlay) this.#closeOverlay();
+    else this.#setCollapsed(true);
+  }
+  // --- Mode handling ---------------------------------------------------------
+  /** Re-renders the closed/default state for `mode` and records it. */
+  #applyMode(mode) {
+    this.#mode = mode;
+    if (this.hasPanelTarget) this.panelTarget.setAttribute("data-mode", mode);
+    if (mode === "inline") {
+      this.#transition.cancel();
+      this.#trap.deactivate({ restoreFocus: false });
+      if (this.hasPanelTarget) this.panelTarget.hidden = false;
+      this.#hideBackdrop();
+      this.#applyInlineState(this.#collapsed);
+    } else {
+      this.#transition.cancel();
+      this.#trap.deactivate({ restoreFocus: false });
+      this.#setOverlayClosedImmediate();
+    }
+  }
+  /** Reconciles a replacement panel with the current responsive mode and DOM state. */
+  #adoptPanel(panel) {
+    this.#transition.cancel();
+    const trapWasActive = this.#trap.active;
+    this.#activePanel = panel;
+    panel.setAttribute("data-mode", this.#mode);
+    if (this.#mode === "inline") {
+      panel.hidden = false;
+      panel.setAttribute("data-state", this.#collapsed ? "collapsed" : "expanded");
+      this.#hideBackdrop();
+      this.#setExpandedAttr(!this.#collapsed);
+      this.#trap.deactivate({ restoreFocus: false });
+      return;
+    }
+    if (panel.getAttribute("data-state") === "open") {
+      panel.hidden = false;
+      if (this.hasBackdropTarget) {
+        this.backdropTarget.setAttribute("data-state", "open");
+        this.backdropTarget.hidden = false;
+      }
+      this.#setExpandedAttr(true);
+      if (trapWasActive) this.#trap.deactivate({ restoreFocus: false });
+      this.#trap.activate();
+      return;
+    }
+    panel.setAttribute("data-state", "closed");
+    panel.hidden = true;
+    this.#hideBackdrop();
+    this.#setExpandedAttr(false);
+    this.#trap.deactivate();
+  }
+  #onMediaChange = (event) => {
+    const next = event.matches ? "inline" : "overlay";
+    if (next !== this.#mode) this.#applyMode(next);
+  };
+  #computeMode() {
+    return this.#mql?.matches ?? true ? "inline" : "overlay";
+  }
+  #matchBreakpoint(query = this.#breakpointQuery) {
+    if (typeof window.matchMedia !== "function") return null;
+    return window.matchMedia(query);
+  }
+  // --- Inline (rail) ---------------------------------------------------------
+  /** Sets, reflects, and persists the inline collapsed preference. */
+  #setCollapsed(collapsed) {
+    if (collapsed === this.#collapsed) return;
+    this.#collapsed = collapsed;
+    this.#applyInlineState(collapsed);
+    this.#persistCollapsed(collapsed);
+  }
+  /** Reflects the inline rail state onto the panel and trigger. */
+  #applyInlineState(collapsed) {
+    if (this.hasPanelTarget) {
+      this.panelTarget.setAttribute("data-state", collapsed ? "collapsed" : "expanded");
+    }
+    this.#setExpandedAttr(!collapsed);
+  }
+  // --- Overlay (off-canvas modal) -------------------------------------------
+  /** Opens the overlay: reveal it, commit a starting frame, then trap focus. */
+  #openOverlay() {
+    if (!this.hasPanelTarget || this.#isOverlayOpen) return;
+    this.#transition.cancel();
+    this.#activePanel = this.panelTarget;
+    this.panelTarget.hidden = false;
+    if (this.hasBackdropTarget) this.backdropTarget.hidden = false;
+    void this.panelTarget.offsetWidth;
+    this.#setOverlayState("open");
+    this.#setExpandedAttr(true);
+    this.#trap.activate();
+  }
+  /** Closes the overlay: start the exit transition, defer hide + trap teardown. */
+  #closeOverlay() {
+    if (!this.hasPanelTarget || !this.#isOverlayOpen) return;
+    this.#setOverlayState("closed");
+    this.#setExpandedAttr(false);
+    this.#hideAfterTransition();
+  }
+  /** Renders the overlay closed state up front (used when entering overlay mode). */
+  #setOverlayClosedImmediate() {
+    this.#setOverlayState("closed");
+    this.#setExpandedAttr(false);
+    if (this.hasPanelTarget) this.panelTarget.hidden = true;
+    this.#hideBackdrop();
+  }
+  /** Syncs `data-state` on the panel and backdrop together (overlay). */
+  #setOverlayState(state) {
+    if (this.hasPanelTarget) this.panelTarget.setAttribute("data-state", state);
+    if (this.hasBackdropTarget) this.backdropTarget.setAttribute("data-state", state);
+  }
+  /**
+   * Applies `hidden` once the close transition ends so the exit slide can play,
+   * then reverts the modal side effects. The shared waiter completes
+   * synchronously for 0ms transitions and supplies a bounded fallback when the
+   * browser emits no terminal event.
+   */
+  #hideAfterTransition() {
+    const panel = this.panelTarget;
+    this.#activePanel = panel;
+    this.#transition.wait(panel, () => this.#applyOverlayHidden(panel));
+  }
+  /** Hides the panel/backdrop and tears down the trap after the exit transition. */
+  #applyOverlayHidden(panel) {
+    panel.hidden = true;
+    this.#hideBackdrop();
+    this.#trap.deactivate();
+  }
+  #hideBackdrop() {
+    if (!this.hasBackdropTarget) return;
+    this.backdropTarget.setAttribute("data-state", "closed");
+    this.backdropTarget.hidden = true;
+  }
+  // --- Shared helpers --------------------------------------------------------
+  #setExpandedAttr(expanded) {
+    if (this.hasTriggerTarget) {
+      this.triggerTarget.setAttribute("aria-expanded", expanded ? "true" : "false");
+    }
+  }
+  /**
+   * Resolves the inline collapsed preference, in priority order:
+   *   1. the persisted value (when a `key` is set and storage is readable),
+   *   2. the current DOM `data-state` — so a Turbo cache restore / morph that
+   *      reconnects over already-rendered markup keeps the live state (the DOM is
+   *      the source of truth) even when no `key` / localStorage is available,
+   *   3. the declared `collapsed` value.
+   */
+  #restoreCollapsed() {
+    const key = this.#storageKey;
+    if (key) {
+      const stored = readLocalStorage(key);
+      if (stored !== null) return stored === "1";
+    }
+    const domState = this.hasPanelTarget ? this.panelTarget.getAttribute("data-state") : null;
+    if (domState === "collapsed") return true;
+    if (domState === "expanded") return false;
+    return this.collapsedValue;
+  }
+  /** Persists the collapsed preference when a key is configured. */
+  #persistCollapsed(collapsed) {
+    const key = this.#storageKey;
+    if (!key) return;
+    writeLocalStorage(key, collapsed ? "1" : "0");
+  }
+  get #storageKey() {
+    return this.keyValue ? `stimeo--sidebar:${this.keyValue}` : "";
+  }
+  /** Valid breakpoint CSS query, defaulting malformed or negative values to 768px. */
+  get #breakpointQuery() {
+    const value = this.breakpointValue;
+    const breakpoint = Number.isFinite(value) && value >= 0 ? value : 768;
+    return `(min-width: ${breakpoint}px)`;
+  }
+  get #isOverlay() {
+    return this.#mode === "overlay";
+  }
+  get #isOverlayOpen() {
+    return this.#isOverlay && this.hasPanelTarget && this.panelTarget.getAttribute("data-state") === "open";
+  }
+};
+
+export { SidebarController };
+//# sourceMappingURL=sidebar_controller.js.map
+//# sourceMappingURL=sidebar_controller.js.map