senren-ui 0.1.6 → 0.3.0

data/templates/components/separator/separator_component.rb

@@ -7,6 +7,13 @@ module Senren
 
     SIZES = { md: '' }.freeze
 
+    # BaseComponent defaults to `variant: :default`, which this component does
+    # not define, so `.new` with no variant raised instead of rendering. The
+    # default is :horizontal (a rule across the flow).
+    def initialize(variant: :horizontal, **args)
+      super
+    end
+
     def aria_orientation = variant == :vertical ? 'vertical' : 'horizontal'
   end
 end

data/templates/components/sheet/sheet_component.html.erb

@@ -1,4 +1,7 @@
-<div data-controller="senren--sheet" data-senren-component="sheet" id="<%= dom_id %>">
+<%# Root goes through root_attrs so a caller's class: and data: reach it.
+    Hand-writing these attributes dropped both -- which is why a Stimulus
+    value could not be set from the server. %>
+<%= tag.div(**wrapper_attrs(id: dom_id, data: { controller: "senren--sheet" })) do %>
   <% if trigger? %>
     <span data-action="click->senren--sheet#open" data-senren--sheet-target="trigger">
       <%= trigger %>
@@ -8,11 +11,12 @@
   <% end %>
 
   <div data-senren--sheet-target="overlay" hidden
+       data-action="click->senren--sheet#close"
        class="fixed inset-0 z-40 bg-black/50 backdrop-blur-sm"></div>
 
   <div data-senren--sheet-target="panel" hidden role="dialog" aria-modal="true"
        data-open="false"
-       class="fixed z-50 bg-[hsl(var(--senren-background))] text-[hsl(var(--senren-foreground))] shadow-lg transition-transform duration-200 <%= self.class::VARIANTS[variant] %>">
+       class="<%= panel_class("fixed z-50 bg-[hsl(var(--senren-background))] text-[hsl(var(--senren-foreground))] shadow-lg transition-transform duration-200 #{ self.class::VARIANTS[variant] }") %>">
     <div class="flex h-full flex-col p-6">
       <% if title? %>
         <h2 class="text-lg font-semibold"><%= title %></h2>
@@ -20,7 +24,12 @@
       <% if description? %>
         <p class="text-sm text-[hsl(var(--senren-muted-foreground))]"><%= description %></p>
       <% end %>
-      <div class="mt-4 flex-1 overflow-auto">
+      <%# -mx-2 px-2 gives the scroll container room for focus rings.
+          overflow-auto clips whatever draws outside a child's border box,
+          and a ring does exactly that -- a focused input sitting flush
+          against the edge had its ring shaved off on both sides. The
+          negative margin cancels the padding, so nothing moves. %>
+      <div class="-mx-2 mt-4 flex-1 overflow-auto px-2">
         <%= body || content %>
       </div>
       <% if footer? %>
@@ -34,4 +43,4 @@
       <span aria-hidden="true">×</span>
     </button>
   </div>
-</div>
+<% end %>

data/templates/components/sheet/sheet_component.rb

@@ -1,6 +1,17 @@
 # frozen_string_literal: true
 
 module Senren
+  # Two ancestor traps to know about, because neither is visible in this file
+  # and both look like a z-index bug from the outside:
+  #
+  #   * A `z-index` on any positioned ancestor creates a stacking context, and
+  #     a fixed overlay cannot escape one. The panel then competes only inside
+  #     that context, so a sticky header with a lower z-index still covers it.
+  #     `position: relative` alone is fine; it is the z-index that traps.
+  #   * `transform`, `filter`, `backdrop-filter`, `will-change` and an opacity
+  #     below 1 create a stacking context too, with the same effect.
+  #
+  # Symptom in both cases: raising the panel's z-index changes nothing.
   class SheetComponent < BaseComponent
     renders_one :trigger
     renders_one :title
@@ -19,7 +30,7 @@ module Senren
 
     def initialize(side: :right, id: nil, class_name: nil, **html)
       super(variant: side, size: :md, class_name: class_name, **html)
-      @dom_id = id || "senren-sheet-#{SecureRandom.hex(3)}"
+      @dom_id = id || senren_dom_id(side)
     end
 
     attr_reader :dom_id

data/templates/components/shortcut_key/shortcut_key_component.html.erb

@@ -1,6 +1,6 @@
-<span <%= tag.attributes(**root_attrs("inline-flex items-center gap-1 text-xs text-[hsl(var(--senren-muted-foreground))]")) %>>
+<%= tag.span(**root_attrs("inline-flex items-center gap-1 text-xs text-[hsl(var(--senren-muted-foreground))]")) do %>
   <% (keys.presence || [content]).compact.each_with_index do |key, index| %>
     <% if index.positive? %><span aria-hidden="true">+</span><% end %>
     <kbd class="rounded border border-[hsl(var(--senren-border))] bg-[hsl(var(--senren-muted))] px-1.5 py-0.5 font-mono text-[11px] text-[hsl(var(--senren-foreground))] shadow-sm"><%= key %></kbd>
   <% end %>
-</span>
+<% end %>

data/templates/components/sidebar/sidebar_component.html.erb

@@ -1,4 +1,4 @@
-<aside <%= tag.attributes(**root_attrs("flex min-h-80 flex-col overflow-hidden rounded-(--senren-radius) border border-[hsl(var(--senren-border))] bg-[hsl(var(--senren-card))] p-3 text-[hsl(var(--senren-card-foreground))] transition-[width] duration-300 ease-in-out", data: { controller: "senren--sidebar" })) %>>
+<%= tag.aside(**root_attrs("flex min-h-80 flex-col overflow-hidden rounded-(--senren-radius) border border-[hsl(var(--senren-border))] bg-[hsl(var(--senren-card))] p-3 text-[hsl(var(--senren-card-foreground))] transition-[width] duration-300 ease-in-out", data: { controller: "senren--sidebar" })) do %>
   <div class="mb-4 flex items-center justify-between gap-2 px-2">
     <div data-senren--sidebar-target="brand" class="truncate font-display text-sm font-semibold tracking-tight"><%= brand %></div>
     <button type="button" data-senren--sidebar-target="toggleButton" class="inline-flex h-8 w-8 cursor-pointer items-center justify-center rounded-md text-[hsl(var(--senren-muted-foreground))] transition-colors hover:bg-[hsl(var(--senren-accent))] hover:text-[hsl(var(--senren-accent-foreground))]" data-action="click->senren--sidebar#toggle" aria-label="Toggle sidebar" aria-expanded="<%= variant != :compact %>">
@@ -21,4 +21,4 @@
   <% if content? %>
     <div data-senren--sidebar-target="footer" class="mt-auto pt-4 text-xs text-[hsl(var(--senren-muted-foreground))]"><%= content %></div>
   <% end %>
-</aside>
+<% end %>

data/templates/components/switch/switch_component.html.erb

@@ -1,6 +1,6 @@
 <%= tag.label(**root_attrs("inline-flex items-center gap-3 cursor-pointer")) do %>
   <span class="relative inline-flex h-6 w-11 items-center rounded-full bg-[hsl(var(--senren-muted))] has-[:checked]:bg-[hsl(var(--senren-primary))] transition-colors">
-    <input type="checkbox" role="switch" id="<%= id %>" name="<%= name %>" value="<%= value %>" <%= "checked" if checked %> class="peer sr-only">
+    <input type="checkbox" role="switch" id="<%= id %>" name="<%= name %>" value="<%= value %>" <% if checked %>checked<% end %> class="peer sr-only">
     <span aria-hidden="true" class="absolute left-0.5 top-0.5 inline-block h-5 w-5 transform rounded-full bg-[hsl(var(--senren-background))] transition-transform peer-checked:translate-x-5"></span>
   </span>
   <% if label %>

data/templates/components/table/table_component.html.erb

@@ -1,4 +1,4 @@
-<div <%= tag.attributes(**root_attrs("w-full overflow-hidden rounded-(--senren-radius) border border-[hsl(var(--senren-border))]")) %>>
+<%= tag.div(**root_attrs("w-full overflow-hidden rounded-(--senren-radius) border border-[hsl(var(--senren-border))]")) do %>
   <table class="w-full border-collapse text-left text-sm <%= self.class::VARIANTS[variant] %>">
     <% if caption.present? %>
       <caption class="sr-only"><%= caption %></caption>
@@ -23,4 +23,4 @@
       <% end %>
     </tbody>
   </table>
-</div>
+<% end %>

data/templates/components/tabs/tabs_component.html.erb

@@ -1,4 +1,4 @@
-<div <%= tag.attributes(**root_attrs("w-full", data: { controller: "senren--tabs" })) %>>
+<%= tag.div(**root_attrs("w-full", data: { controller: "senren--tabs" })) do %>
   <div role="tablist" aria-label="<%= label %>" class="<%= self.class::VARIANTS[variant] %> flex flex-wrap items-center gap-1">
     <% items.each do |item| %>
       <% selected = active_item?(item) %>
@@ -10,9 +10,9 @@
   <div class="mt-4">
     <% items.each do |item| %>
       <% selected = active_item?(item) %>
-      <section id="<%= item[:id] %>-panel" role="tabpanel" aria-labelledby="<%= item[:id] %>-tab" data-senren--tabs-target="panel" data-panel-id="<%= item[:id] %>" data-state="<%= selected ? "active" : "inactive" %>" <%= "hidden" unless selected %> class="rounded-(--senren-radius) border border-[hsl(var(--senren-border))] bg-[hsl(var(--senren-card))] p-4 text-sm text-[hsl(var(--senren-card-foreground))]">
+      <section id="<%= item[:id] %>-panel" role="tabpanel" aria-labelledby="<%= item[:id] %>-tab" data-senren--tabs-target="panel" data-panel-id="<%= item[:id] %>" data-state="<%= selected ? "active" : "inactive" %>" <% unless selected %>hidden<% end %> class="rounded-(--senren-radius) border border-[hsl(var(--senren-border))] bg-[hsl(var(--senren-card))] p-4 text-sm text-[hsl(var(--senren-card-foreground))]">
         <%= item[:content].presence || content %>
       </section>
     <% end %>
   </div>
-</div>
+<% end %>

data/templates/components/tooltip/tooltip_component.html.erb

@@ -1,9 +1,11 @@
-<span data-controller="senren--tooltip" class="relative inline-block" data-senren-component="tooltip">
+<%# Root goes through root_attrs so a caller's class: and data: reach it.
+    Hand-writing these attributes dropped both. %>
+<%= tag.span(**wrapper_attrs("relative inline-block", data: { controller: "senren--tooltip" })) do %>
   <span tabindex="0"
         aria-describedby="<%= id %>"
         data-action="mouseenter->senren--tooltip#show mouseleave->senren--tooltip#hide focus->senren--tooltip#show blur->senren--tooltip#hide">
     <%= content %>
   </span>
   <span id="<%= id %>" role="tooltip" hidden data-senren--tooltip-target="bubble"
-        class="absolute z-50 mt-1 whitespace-nowrap rounded-md bg-[hsl(var(--senren-foreground))] text-[hsl(var(--senren-background))] px-2 py-1 text-xs shadow"><%= text %></span>
-</span>
+        class="<%= panel_class("absolute z-50 mt-1 whitespace-nowrap rounded-md bg-[hsl(var(--senren-foreground))] text-[hsl(var(--senren-background))] px-2 py-1 text-xs shadow") %>"><%= text %></span>
+<% end %>

data/templates/components/tooltip/tooltip_component.rb

@@ -5,10 +5,10 @@ module Senren
     VARIANTS = { default: '' }.freeze
     SIZES    = { md: '' }.freeze
 
-    def initialize(text:, class_name: nil, **html)
+    def initialize(text:, id: nil, class_name: nil, **html)
       super(variant: :default, size: :md, class_name: class_name, **html)
       @text = text
-      @id = "senren-tooltip-#{SecureRandom.hex(3)}"
+      @id = id || senren_dom_id(text)
     end
 
     attr_reader :text, :id

data/templates/components/top_nav/top_nav_component.html.erb

@@ -1,4 +1,4 @@
-<header <%= tag.attributes(**root_attrs("sticky top-0 z-30 border-b border-[hsl(var(--senren-border))] backdrop-blur-md")) %>>
+<%= tag.header(**root_attrs("sticky top-0 z-30 border-b border-[hsl(var(--senren-border))] backdrop-blur-md")) do %>
   <div class="mx-auto flex h-14 w-full max-w-[1400px] items-center gap-6 px-4 lg:px-8">
     <div class="min-w-0 flex-none font-display text-sm font-semibold text-[hsl(var(--senren-foreground))]">
       <% if brand? %><%= brand %><% else %>Senren<% end %>
@@ -18,4 +18,4 @@
       <div class="ml-auto flex items-center gap-2"><%= actions %></div>
     <% end %>
   </div>
-</header>
+<% end %>

data/templates/components/typography/typography_component.rb

@@ -14,6 +14,13 @@ module Senren
 
     SIZES = { md: '' }.freeze
 
+    # BaseComponent defaults to `variant: :default`, which this component does
+    # not define, so `.new` with no variant raised instead of rendering. The
+    # default is :p (body text).
+    def initialize(variant: :p, **args)
+      super
+    end
+
     TAG_FOR = {
       h1: :h1, h2: :h2, h3: :h3, h4: :h4,
       p: :p, lead: :p, large: :p, small: :small, muted: :p

data/templates/controllers/accordion_controller.js

@@ -17,7 +17,7 @@ export default class extends Controller {
   }
 
   _closeAll() {
-    this.triggerTargets.forEach((trigger) => trigger.setAttribute("aria-expanded", "false"))
+    this.triggerTargets.forEach((trigger) => { trigger.setAttribute("aria-expanded", "false") })
     this.panelTargets.forEach((panel) => { panel.hidden = true })
   }
 

data/templates/controllers/alert_dialog_controller.js

@@ -3,36 +3,60 @@ import { Controller } from "@hotwired/stimulus"
 // senren--alert-dialog
 // Same shape as dialog, but role=alertdialog. Triggered by external buttons that include
 // data-action="click->senren--alert-dialog#open" pointing at the controller scope.
+//
+// State lives in `openValue`. Actions assign it; openValueChanged performs every
+// DOM change, so the dialog can be opened from the server and survives a morph.
 export default class extends Controller {
   static targets = ["overlay", "panel", "trigger"]
+  static values = { open: Boolean }
 
   connect() {
     this._onKey = this._onKey.bind(this)
+    this._onBeforeCache = this._onBeforeCache.bind(this)
+    document.addEventListener("turbo:before-cache", this._onBeforeCache)
   }
 
   disconnect() {
     document.removeEventListener("keydown", this._onKey)
+    document.removeEventListener("turbo:before-cache", this._onBeforeCache)
     document.body.style.overflow = ""
   }
 
   open(event) {
     event?.preventDefault()
-    this.overlayTarget.hidden = false
-    this.panelTarget.hidden = false
-    document.addEventListener("keydown", this._onKey)
-    document.body.style.overflow = "hidden"
-    queueMicrotask(() => this.panelTarget?.focus())
+    this.openValue = true
   }
 
   close(event) {
     event?.preventDefault()
-    this.overlayTarget.hidden = true
-    this.panelTarget.hidden = true
+    this.openValue = false
+  }
+
+  openValueChanged(isOpen, wasOpen) {
+    if (this.hasOverlayTarget) this.overlayTarget.hidden = !isOpen
+    if (this.hasPanelTarget) this.panelTarget.hidden = !isOpen
+
+    if (isOpen) {
+      document.addEventListener("keydown", this._onKey)
+      document.body.style.overflow = "hidden"
+      queueMicrotask(() => this.panelTarget?.focus())
+      this.dispatch("opened")
+      return
+    }
+
     document.removeEventListener("keydown", this._onKey)
     document.body.style.overflow = ""
+    if (wasOpen !== undefined) this.dispatch("closed")
   }
 
   _onKey(event) {
     if (event.key === "Escape") this.close()
   }
+
+  // Turbo snapshots the page before navigating away; without this the scroll
+  // lock is captured while applied and a back navigation restores a page that
+  // cannot be scrolled.
+  _onBeforeCache() {
+    this.openValue = false
+  }
 }

data/templates/controllers/cart_controller.js

@@ -0,0 +1,85 @@
+import { Controller } from "@hotwired/stimulus"
+
+// senren--cart
+// Local UI only: quantity steppers and the displayed subtotal. The server owns
+// the cart, so nothing here talks to it — a host app persists changes by
+// listening for senren--cart:changed, or by submitting the surrounding form.
+//
+// State lives in `subtotalCentsValue`, following the pattern in
+// .senren/conventions.md: actions assign values, and subtotalCentsValueChanged
+// performs the DOM work. A server-rendered subtotal therefore paints the first
+// frame, survives a Turbo morph, and can be corrected by a Turbo Stream that
+// changes one attribute.
+export default class extends Controller {
+  static targets = ["line", "quantity", "lineTotal", "subtotal", "count"]
+  static values = { currency: String, subtotalCents: Number }
+
+  increment(event) {
+    this._step(event, +1)
+  }
+
+  decrement(event) {
+    this._step(event, -1)
+  }
+
+  remove(event) {
+    const line = event.currentTarget.closest("[data-senren--cart-target~='line']")
+    if (!line) return
+
+    const id = line.dataset.lineId
+    // Read before the node goes away.
+    const removeUrl = line.dataset.removeUrl || null
+    line.remove()
+    this._recalculate()
+    this.dispatch("removed", { detail: { id, removeUrl, subtotalCents: this.subtotalCentsValue } })
+  }
+
+  // The value is the state; this renders it. Called on initialization too, so
+  // whatever the server rendered is what shows.
+  subtotalCentsValueChanged(cents) {
+    if (this.hasSubtotalTarget) this.subtotalTarget.textContent = this.format(cents)
+  }
+
+  format(cents) {
+    return `${this.currencyValue || "$"}${(Number(cents) / 100).toFixed(2)}`
+  }
+
+  _step(event, delta) {
+    const line = event.currentTarget.closest("[data-senren--cart-target~='line']")
+    if (!line) return
+
+    const output = line.querySelector("[data-senren--cart-target~='quantity']")
+    if (!output) return
+
+    // Never below one: removing is a separate, explicit action, so a stepper
+    // that reaches zero would leave a line the user cannot see the price of.
+    const next = Math.max(1, Number(output.textContent.trim() || 1) + delta)
+    output.textContent = String(next)
+
+    this._recalculate()
+    this.dispatch("changed", {
+      detail: { id: line.dataset.lineId, quantity: next, subtotalCents: this.subtotalCentsValue }
+    })
+  }
+
+  _recalculate() {
+    let cents = 0
+    let count = 0
+
+    this.lineTargets.forEach((line) => {
+      const price = Number(line.dataset.priceCents || 0)
+      const output = line.querySelector("[data-senren--cart-target~='quantity']")
+      const quantity = Number(output?.textContent.trim() || 0)
+      const total = price * quantity
+
+      cents += total
+      count += quantity
+
+      const lineTotal = line.querySelector("[data-senren--cart-target~='lineTotal']")
+      if (lineTotal) lineTotal.textContent = this.format(total)
+    })
+
+    if (this.hasCountTarget) this.countTarget.textContent = String(count)
+    this.subtotalCentsValue = cents
+  }
+}

data/templates/controllers/clipboard_controller.js

@@ -9,9 +9,20 @@ export default class extends Controller {
   async copy() {
     const value = this.sourceTarget.value || this.sourceTarget.textContent
     await navigator.clipboard.writeText(value)
+    // The await is a suspension point: the element may be gone by now.
+    if (!this.hasButtonTarget) return
+
     const original = this.buttonTarget.textContent
     this.buttonTarget.textContent = this.copiedLabelValue || "Copied"
     if (this.hasStatusTarget) this.statusTarget.textContent = "Copied to clipboard"
-    window.setTimeout(() => { this.buttonTarget.textContent = original }, 1200)
+
+    clearTimeout(this._resetTimer)
+    this._resetTimer = setTimeout(() => {
+      if (this.hasButtonTarget) this.buttonTarget.textContent = original
+    }, 1200)
+  }
+
+  disconnect() {
+    clearTimeout(this._resetTimer)
   }
 }

data/templates/controllers/command_controller.js

@@ -43,10 +43,9 @@ export default class extends Controller {
   }
 
   choose(event) {
-    this.element.dispatchEvent(new CustomEvent("senren:command-select", {
-      bubbles: true,
+    this.dispatch("select", {
       detail: { label: event.currentTarget.textContent.trim(), href: event.currentTarget.getAttribute("href") }
-    }))
+    })
   }
 
   move(delta) {
@@ -59,7 +58,7 @@ export default class extends Controller {
   updateActive() {
     const options = this.visibleOptions
     this.emptyTarget.hidden = options.length > 0
-    this.optionTargets.forEach((option) => option.setAttribute("aria-selected", "false"))
+    this.optionTargets.forEach((option) => { option.setAttribute("aria-selected", "false") })
     const active = options[this.activeIndex]
     if (!active) {
       this.inputTarget.removeAttribute("aria-activedescendant")

data/templates/controllers/context_menu_controller.js

@@ -2,8 +2,13 @@ import { Controller } from "@hotwired/stimulus"
 
 // senren--context-menu
 // Opens on right-click within the trigger; closes on outside click or Escape.
+//
+// State lives in `openValue`. The pointer position is transient and belongs to
+// the opening event, so it is applied in the action; everything else — the
+// visibility and the document listeners — is driven by the value.
 export default class extends Controller {
   static targets = ["trigger", "menu"]
+  static values = { open: Boolean }
 
   connect() {
     this._onDocClick = this._onDocClick.bind(this)
@@ -11,26 +16,48 @@ export default class extends Controller {
   }
 
   disconnect() {
-    document.removeEventListener("click", this._onDocClick)
-    document.removeEventListener("keydown", this._onKey)
+    this._stopListening()
   }
 
   open(event) {
     event.preventDefault()
-    const rect = this.element.getBoundingClientRect()
-    this.menuTarget.style.top = (event.clientY - rect.top) + "px"
-    this.menuTarget.style.left = (event.clientX - rect.left) + "px"
-    this.menuTarget.hidden = false
-    document.addEventListener("click", this._onDocClick)
-    document.addEventListener("keydown", this._onKey)
+
+    if (this.hasMenuTarget) {
+      const rect = this.element.getBoundingClientRect()
+      this.menuTarget.style.top = `${event.clientY - rect.top}px`
+      this.menuTarget.style.left = `${event.clientX - rect.left}px`
+    }
+
+    this.openValue = true
   }
 
   close() {
-    this.menuTarget.hidden = true
+    this.openValue = false
+  }
+
+  openValueChanged(isOpen) {
+    if (this.hasMenuTarget) this.menuTarget.hidden = !isOpen
+
+    if (isOpen) {
+      document.addEventListener("click", this._onDocClick)
+      document.addEventListener("keydown", this._onKey)
+      this.dispatch("opened")
+      return
+    }
+
+    this._stopListening()
+  }
+
+  _stopListening() {
     document.removeEventListener("click", this._onDocClick)
     document.removeEventListener("keydown", this._onKey)
   }
 
-  _onDocClick(event) { if (!this.menuTarget.contains(event.target)) this.close() }
-  _onKey(event)      { if (event.key === "Escape") this.close() }
+  _onDocClick(event) {
+    if (!this.menuTarget.contains(event.target)) this.close()
+  }
+
+  _onKey(event) {
+    if (event.key === "Escape") this.close()
+  }
 }

data/templates/controllers/data_table_controller.js

@@ -15,9 +15,14 @@ export default class extends Controller {
     const direction = this.directions[key] === "asc" ? "desc" : "asc"
     this.directions[key] = direction
 
-    const rows = [...this.rowTargets]
-    rows.sort((a, b) => this.compare(this.valueFor(a, key), this.valueFor(b, key), direction))
-    rows.forEach((row) => this.bodyTarget.appendChild(row))
+    // Read each cell once (O(n)) rather than once per comparison (O(n log n)),
+    // then move the rows in a single batched write.
+    const decorated = this.rowTargets.map((row) => ({ row, value: this.valueFor(row, key) }))
+    decorated.sort((a, b) => this.compare(a.value, b.value, direction))
+
+    const fragment = document.createDocumentFragment()
+    decorated.forEach((entry) => { fragment.appendChild(entry.row) })
+    this.bodyTarget.appendChild(fragment)
   }
 
   valueFor(row, key) {

data/templates/controllers/dialog_controller.js

@@ -1,50 +1,76 @@
 import { Controller } from "@hotwired/stimulus"
 
 // senren--dialog
-// Local UI: open/close, focus trap, Escape to close, body scroll lock.
+// Local UI: open/close, Escape to close, body scroll lock.
+//
+// State lives in `openValue`, not in the DOM nodes this controller touches.
+// Actions only assign the value; every DOM change happens in openValueChanged.
+//
+// That inversion is what makes the state server-renderable (render
+// open-value="true" and the dialog is open with no JavaScript), survivable
+// across a Turbo morph, and reachable from a Turbo Stream that changes a single
+// attribute. It is the pattern every stateful Senren controller follows.
 export default class extends Controller {
   static targets = ["overlay", "panel", "trigger"]
-  static values  = { open: Boolean }
+  static values = { open: Boolean }
 
   connect() {
     this._onKey = this._onKey.bind(this)
-    if (this.openValue) this._show()
+    this._onBeforeCache = this._onBeforeCache.bind(this)
+    document.addEventListener("turbo:before-cache", this._onBeforeCache)
   }
 
   disconnect() {
     document.removeEventListener("keydown", this._onKey)
-    document.body.style.overflow = ""
+    document.removeEventListener("turbo:before-cache", this._onBeforeCache)
+    this._releaseScroll()
   }
 
   open(event) {
     event?.preventDefault()
-    this._show()
+    this.openValue = true
   }
 
   close(event) {
     event?.preventDefault()
-    this._hide()
+    this.openValue = false
   }
 
-  _show() {
-    this.openValue = true
-    if (this.hasOverlayTarget) this.overlayTarget.hidden = false
-    if (this.hasPanelTarget)   this.panelTarget.hidden   = false
-    document.addEventListener("keydown", this._onKey)
-    document.body.style.overflow = "hidden"
-    queueMicrotask(() => this.panelTarget?.focus())
-  }
+  // Stimulus calls this during initialization too, so the server-rendered value
+  // paints the first frame.
+  openValueChanged(isOpen, wasOpen) {
+    if (this.hasOverlayTarget) this.overlayTarget.hidden = !isOpen
+    if (this.hasPanelTarget) this.panelTarget.hidden = !isOpen
+
+    if (isOpen) {
+      document.addEventListener("keydown", this._onKey)
+      document.body.style.overflow = "hidden"
+      queueMicrotask(() => this.panelTarget?.focus())
+      this.dispatch("opened")
+      return
+    }
 
-  _hide() {
-    this.openValue = false
-    if (this.hasOverlayTarget) this.overlayTarget.hidden = true
-    if (this.hasPanelTarget)   this.panelTarget.hidden   = true
     document.removeEventListener("keydown", this._onKey)
-    document.body.style.overflow = ""
-    this.triggerTarget?.focus?.()
+    this._releaseScroll()
+    // Only return focus on a real close, not on the initial render.
+    if (wasOpen !== undefined) {
+      this.triggerTarget?.focus?.()
+      this.dispatch("closed")
+    }
   }
 
   _onKey(event) {
-    if (event.key === "Escape") this._hide()
+    if (event.key === "Escape") this.close()
+  }
+
+  // Turbo snapshots the page before navigating away. Without this the scroll
+  // lock is captured while still applied, and a back navigation restores a page
+  // that cannot be scrolled.
+  _onBeforeCache() {
+    this.openValue = false
+  }
+
+  _releaseScroll() {
+    document.body.style.overflow = ""
   }
 }