hibiki_rails 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 915a98a11ca62685f60697d27383e8592978e0c2173b0e984c24eca7736cef55
-  data.tar.gz: 070cd14175c3027b164ec0b52378b59178499f3f3474fe3296722f6432c580ab
+  metadata.gz: 0ab077d178d71a16ddf8d0f5706179f7fbac93c4d851aae6e3ccda4ef0e4b674
+  data.tar.gz: 409e833560a3393d2ca3c0121c2e958f3d8bb986a0b62aaaed653fe0c0f06af3
 SHA512:
-  metadata.gz: 5d07fa8e0a897a21cce85e559e42a02dc78090f89986bc37c24202a36fb81322287a1ae86fb4c5166aa615a4ee8924732bb63020643a2e4db8e8ec72a5d870eb
-  data.tar.gz: 993b20b7af2d105e5c067823621eb8050ff426a57a9ac0b0aacccbd2a9fd9136a9a2a6f0f635d7932952f7c4c58bef2645492c67fe1b79acbb28d1c2e86f5a37
+  metadata.gz: 552f5913948b16d8ed030b1eb12c35f7f28f0f109f31807dbbaf86f9b2320c3929c959c2872800785b635b9c05229df0ebe5c218e4429b490442ee2cb81ba133
+  data.tar.gz: 0ff3466d160bd5074a8d02530c87222fd8dcc5aeed43b033fb8ff3549decd55423286e1757511d352f39a5df47a4d60198dd0efb9fa254479febf43f1ea7d8c6

data/CHANGELOG.md

@@ -4,6 +4,46 @@ The gem and the npm package are released in lockstep and share these version
 numbers — `app/assets/javascripts/hibiki.js` is a single copy served both ways,
 so importmap and bundler apps always resolve identical client code.
 
+## 0.19.0 — 2026-10-12
+
+### Added
+
+**History entries.** `transmit_url` takes `history: :push`, and each move of
+the URL becomes an entry in the browser's history. Use it for state that
+reads as a place, such as a wizard's step. The default, `history: :replace`,
+is unchanged.
+
+```ruby
+transmit_url(history: :push) { wizard_path(step: @step.value) }
+```
+
+**The `popstate` event.** `on(:visit, event: :popstate)` on the island root
+answers Back and Forward over those entries. The client performs the action
+with the query of the address the browser moved to.
+
+```erb
+<%= island WizardChannel, **on(:visit, event: :popstate) do |cid| %>
+```
+
+```ruby
+def visit(data) = turn_to(data["step"])
+```
+
+- The params come from the address bar. Check them as you would a subscribe
+  param.
+- A pushed URL becomes an entry only when it answers an action of this tab.
+  The first URL a channel sends, and one that follows another session's
+  write, replace as before.
+- If the action refuses the address, or changes nothing, the bar is put back
+  to the URL the channel last sent. No entry is added.
+- The payload is the flat query. A key ending in `[]` arrives as an array.
+- `popstate` takes no `debounce:` or `fallback:`.
+- Without a `popstate` action, Back over a pushed entry reloads the page at
+  that address. The page shows the right state if it reads the same params
+  on its first render, as a mirrored URL already requires.
+- Coming back to a pushed entry from another page also reloads it.
+- A page that has pushed an entry is left out of Turbo's snapshot cache.
+
 ## 0.18.0 — 2026-10-11
 
 ### Added

data/app/assets/javascripts/hibiki.js

@@ -93,7 +93,9 @@
 //
 // The left side of `->` is a hibiki event name: click, change, input,
 // and submit are delegated DOM listeners; `visible` is a pseudo-event
-// backed by an IntersectionObserver (the element entering the viewport).
+// backed by an IntersectionObserver (the element entering the viewport);
+// `popstate` is the window's, heard for the history entries a pushed
+// `{ url }` frame made.
 // Everything that is not "which event" is a sibling attribute, so the
 // token grammar never has to grow.
 //
@@ -185,6 +187,27 @@ let consumer
 // island pins nothing even if disconnect never ran.
 const islands = new WeakMap()
 
+// History entries a pushed `{ url }` frame made, by the key in their state,
+// and the one window listener that answers Back and Forward over them.
+//
+// Turbo hears popstate first, whatever the listener's phase: the browser
+// runs a window's listeners in the order they were added. It answers an
+// entry carrying its own state with a restore visit, and an entry without
+// it by adopting it in place. So these entries carry only the key. The
+// island that made one answers it (pop). An entry whose island has left
+// the page, or declares no `popstate`, is loaded afresh: Turbo has by then
+// filed a snapshot of the page on show under the entry's address, and a
+// new document is the one thing that leaves none of that behind.
+//
+// Always listening, not from the first push: after a reload the browser
+// still counts the entries the old document pushed as this document's, and
+// answers Back over them with a popstate no island here made.
+const pushers = new Map()
+window.addEventListener("popstate", (event) => {
+  const key = event.state?.hibiki
+  if (key && !pushers.get(key)?.pop?.(event)) window.location.reload()
+})
+
 // The generic island CONTAINING element, or undefined. The walk performOn
 // uses, exported for the motion module's `own` policy — which reads the
 // island's trip records, so a ChannelController subclass (not in the map)
@@ -310,6 +333,9 @@ export class ChannelController extends Controller {
     this.settledAt = -Infinity
     this.lastControl = null
     this.queued = []
+    // Marks the history entries this island made; see replaceUrl().
+    this.historyKey = `${Date.now()}-${Math.random()}`
+    this.popping = undefined
     this.setState("connecting")
   }
 
@@ -339,6 +365,8 @@ export class ChannelController extends Controller {
 
   disconnect() {
     this.aborted = true
+    pushers.delete(this.historyKey)
+    this.popping = undefined // the bar is the next page's now
     this.settleAll()
     this.subscription?.unsubscribe()
     this.subscription = undefined
@@ -503,6 +531,7 @@ export class ChannelController extends Controller {
   }
 
   settle(seq) {
+    if (this.popping === seq) this.popped()
     const record = this.busy.get(seq)
     if (!record) return
     clearTimeout(record.ceiling)
@@ -595,7 +624,8 @@ export class ChannelController extends Controller {
   // textContent assignment keeps values text-only and preserves each
   // site's own tag/classes, so per-placeholder styling survives updates.
   //
-  // { url } — mirror graph state into the address bar (transmit_url).
+  // { url } — mirror graph state into the address bar (transmit_url);
+  // with `push`, as a history entry.
   //
   // { html } — a fragment: swap it in by its root id. The swap is holdable
   // the way Turbo's is: `hibiki:before-render` bubbles from the island
@@ -607,7 +637,7 @@ export class ChannelController extends Controller {
   //
   // Anything else is not ours to interpret. Subclasses may override, but
   // should call super (or handle `value`) to keep reactive values live.
-  received({ html, value, url }) {
+  received({ html, value, url, push }) {
     if (value) {
       const selector = `[data-hibiki-value="${CSS.escape(value.name)}"]`
       for (const site of document.querySelectorAll(selector)) {
@@ -615,7 +645,7 @@ export class ChannelController extends Controller {
       }
       return
     }
-    if (url !== undefined) return this.replaceUrl(url)
+    if (url !== undefined) return this.replaceUrl(url, push)
     if (!html) return
     const template = document.createElement("template")
     template.innerHTML = html
@@ -633,15 +663,48 @@ export class ChannelController extends Controller {
     return event.detail.render()
   }
 
-  // replaceState, never pushState: the URL is a mirror of graph state, not
-  // a history entry — Back needs no popstate handling and leaves the page
-  // normally. Same-origin only, so a channel can move the bar solely
-  // within its own app (replaceState would throw on a cross-origin URL;
-  // refusing keeps it silent and intentional).
-  replaceUrl(url) {
+  // replaceState unless the channel asked for entries: the URL is a mirror
+  // of graph state, and Back leaves the page normally. Same-origin only, so
+  // a channel can move the bar solely within its own app (replaceState
+  // would throw on a cross-origin URL; refusing keeps it silent and
+  // intentional).
+  //
+  // A pushed URL becomes an entry only when it answers this tab's own
+  // action, so neither the first frame nor another session's write adds
+  // one, and never while a Back is being answered: an action that refuses
+  // the popped URL corrects the bar in place. The entry it leaves and the
+  // one it makes carry this island's key in place of Turbo's state; see
+  // `pushers`. The page is also kept out of Turbo's snapshot cache from
+  // then on, since Turbo no longer knows which address a snapshot is of.
+  replaceUrl(url, push = false) {
     const resolved = new URL(url, window.location.href)
     if (resolved.origin !== window.location.origin) return
-    history.replaceState(history.state, "", resolved)
+    this.url = resolved.href
+    if (!push || this.popping !== undefined || !this.own()) {
+      return history.replaceState(history.state, "", resolved)
+    }
+    if (resolved.href === window.location.href) return
+    pushers.set(this.historyKey, this)
+    window.Turbo?.cache?.exemptPageFromCache?.()
+    history.replaceState(this.entry(), "")
+    history.pushState(this.entry(), "", resolved)
+  }
+
+  // The state of an entry this island answers for: what is there now,
+  // less Turbo's part.
+  entry() {
+    const { turbo, ...rest } = history.state ?? {}
+    return { ...rest, hibiki: this.historyKey }
+  }
+
+  // The Back being answered is over. An action that changed nothing sent no
+  // URL, so the bar still shows the popped one: put back the last the
+  // channel gave, which is the state the page is in.
+  popped() {
+    this.popping = undefined
+    if (this.url && this.url !== window.location.href) {
+      history.replaceState(history.state, "", this.url)
+    }
   }
 
   // `static channel = "..."` wins; otherwise infer Rails-style from the
@@ -733,6 +796,7 @@ const KEYS = {
 }
 const KEYED = '[data-hibiki-on*="keydown."]'
 const HOTKEYED = '[data-hibiki-on*="@window"]'
+const POPPED = '[data-hibiki-on*="popstate->"]'
 const ISLAND = '[data-controller~="hibiki"]'
 
 // A key press that is a gesture: not part of an IME composition (Safari
@@ -1218,6 +1282,31 @@ export default class HibikiController extends ChannelController {
     }
   }
 
+  // Back or Forward landed on an entry this island made, or the one it
+  // first pushed from: the control declaring `popstate`, the root as a
+  // rule, performs its action with the entry's query. Turbo has adopted the
+  // entry by now and written its own state there, which would make the
+  // next visit to it a restore; the entry's own state goes back. False
+  // when nothing here answers, and the page is loaded afresh instead.
+  pop(event) {
+    const control = [this.element, ...this.element.querySelectorAll(POPPED)].find(
+      (element) => element.closest(ISLAND) === this.element && element.matches(POPPED)
+    )
+    const token = control?.dataset.hibikiOn.split(/\s+/).find((t) => t.startsWith("popstate->"))
+    if (!token) return false
+    history.replaceState(event.state, "")
+    const payload = control.dataset.hibikiWith ? JSON.parse(control.dataset.hibikiWith) : {}
+    const query = new URLSearchParams(window.location.search)
+    for (const key of new Set(query.keys())) {
+      const all = query.getAll(key)
+      payload[payloadKey(key)] = key.endsWith("[]") ? all : all.at(-1)
+    }
+    this.flush()
+    this.popping = this.perform(token.slice(10), payload)
+    if (this.popping === undefined) this.popped() // offline: nothing will answer
+    return true
+  }
+
   // A matched key is the control's gesture, so its default goes. A fallback
   // control on an island that is not ready stands aside: a key has no
   // native destination, but its default may be the form's own submit.

data/lib/hibiki/rails/channel.rb

@@ -30,11 +30,23 @@ module Hibiki
     # other public method would be picked up by Channel#action_methods and
     # become client-invocable.
     module Channel
+      # #transmit_url's history option, allowlisted so a typo names itself.
+      HISTORIES = %i[replace push].freeze
+      private_constant :HISTORIES
+
       def self.included(base)
         base.extend(ClassMethods)
         base.include(Broadcasts)
       end
 
+      # What a history mode adds to the `{ url: }` frame.
+      def self.url_frame(history)
+        return history == :push ? { push: true } : {} if HISTORIES.include?(history)
+
+        raise ArgumentError,
+              "transmit_url history #{history.inspect} must be one of #{HISTORIES.map(&:inspect).join(', ')}"
+      end
+
       module ClassMethods
         # Lifecycle hooks, never client-invocable actions. Performing
         # "build_graph" would rebuild the graph and leak the old root;
@@ -177,24 +189,30 @@ module Hibiki
       end
 
       # Mirror graph state into the page's address bar: wraps the block in
-      # an effect that transmits `{ url: }`; the packaged client
-      # history.replaceState's the bar to it. replaceState, never pushState —
-      # the URL is a MIRROR of state, not a history entry, so Back needs no
-      # popstate choreography and leaves the page normally. Compute a
-      # same-origin path ("/songs?page=2" — the client refuses anything
-      # else), and omit params that hold their defaults, or the bar grows
-      # noise on the first transmit. Pair it with first-paint code that READS
-      # those params (controller + subscribe-params seeding), so the mirrored
-      # URL reloads to the state it names. Equality-gated like
-      # #transmit_value: re-runs track every signal read, re-sends only when
-      # the URL actually moved.
-      def transmit_url(&compute)
+      # an effect that transmits `{ url: }`, and the packaged client moves
+      # the bar to it. Compute a same-origin path ("/songs?page=2" — the
+      # client refuses anything else), and omit params that hold their
+      # defaults, or the bar grows noise on the first transmit. Pair it with
+      # first-paint code that READS those params (controller +
+      # subscribe-params seeding), so the mirrored URL reloads to the state
+      # it names. Equality-gated like #transmit_value: re-runs track every
+      # signal read, re-sends only when the URL actually moved.
+      #
+      # history: :replace (the default) is replaceState: the URL is a MIRROR
+      # of state, not a history entry, so Back leaves the page normally.
+      # history: :push makes each move an entry, for state that reads as a
+      # place (a wizard's step). Back then needs an answer: put
+      # `on(:visit, event: :popstate)` on the island root, and the client
+      # performs that action with the popped URL's query params. They come
+      # from the address bar, so treat them like a subscribe param.
+      def transmit_url(history: :replace, &compute)
+        frame = Channel.url_frame(history)
         last = Object.new
         Hibiki::Effect.new do
           url = compute.call.to_s
           unless url == last
             last = url
-            transmit({ url: })
+            transmit({ url: }.merge(frame))
           end
         end
       end

data/lib/hibiki/rails/helpers.rb

@@ -6,6 +6,7 @@ require "securerandom"
 
 require_relative "dom_props"
 require_relative "keys"
+require_relative "modifiers"
 
 module Hibiki
   module Rails
@@ -187,6 +188,10 @@ module Hibiki
       # `{ name => value }` — a checkbox its checked state, a multi-select
       # its selected values — and a submitted form contributes its FormData.
       #
+      # `event: :popstate` goes on the island root and answers Back and
+      # Forward over the entries `transmit_url(history: :push)` made; the
+      # payload is the popped URL's query.
+      #
       # Everything else is a per-control modifier, kept out of the token
       # grammar so the `->` left side stays purely "which event":
       #
@@ -221,9 +226,10 @@ module Hibiki
         action = Helpers.event_name(action)
         events = Array(event).map { Helpers.event(it) }
         debounce = DEFAULT_INPUT_DEBOUNCE if debounce.nil? && events.include?("input")
+        Modifiers.popstate!(debounce:, fallback:) if events.include?("popstate")
         tokens = events.map { "#{it}->#{action}" }.join(" ")
         { data: { hibiki_on: tokens }
-            .merge(on_modifiers(with:, debounce:, confirm:, reset:, fallback:)) }
+            .merge(Modifiers.attributes(with:, debounce:, confirm:, reset:, fallback:)) }
       end
 
       # Placeholder for a single reactive value: `<%= reactive :doubled, 0 %>`
@@ -305,20 +311,6 @@ module Hibiki
       def island_stream(channel, cid, content)
         safe_join([turbo_stream_from(channel.channel_name, cid), content])
       end
-
-      # #on's per-control modifiers, kept out of the token grammar. Each is
-      # omitted when it matches the client's own default, so the common call
-      # still stamps exactly one attribute.
-      def on_modifiers(with:, debounce:, confirm:, reset:, fallback:)
-        {
-          hibiki_with: (JSON.generate(with) unless with.nil?),
-          # nonzero? returns the integer itself, so 0 compacts away.
-          hibiki_debounce: (Integer(debounce).nonzero? if debounce),
-          hibiki_confirm: confirm&.to_s,
-          hibiki_reset: ("false" if reset == false),
-          hibiki_fallback: ("true" if fallback)
-        }.compact
-      end
     end
   end
 end

data/lib/hibiki/rails/modifiers.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hibiki
+  module Rails
+    # Helpers#on's per-control modifiers, kept out of the token grammar.
+    module Modifiers
+      # The attributes beside hibiki_on. Each is omitted when it matches the
+      # client's own default, so the common call still stamps exactly one.
+      def self.attributes(with:, debounce:, confirm:, reset:, fallback:)
+        {
+          hibiki_with: (JSON.generate(with) unless with.nil?),
+          # nonzero? returns the integer itself, so 0 compacts away.
+          hibiki_debounce: (Integer(debounce).nonzero? if debounce),
+          hibiki_confirm: confirm&.to_s,
+          hibiki_reset: ("false" if reset == false),
+          hibiki_fallback: ("true" if fallback)
+        }.compact
+      end
+
+      # Back is not a gesture on a control: it has nothing to wait for and
+      # no native destination to fall back to.
+      def self.popstate!(**modifiers)
+        given = modifiers.compact.keys
+        raise ArgumentError, "a popstate event takes no #{given.join(' or ')}" if given.any?
+      end
+    end
+  end
+end

data/lib/hibiki/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Hibiki
   module Rails
-    VERSION = "0.18.0"
+    VERSION = "0.19.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hibiki_rails
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - planetaska
@@ -189,6 +189,7 @@ files:
 - lib/hibiki/rails/helpers.rb
 - lib/hibiki/rails/instrumentation.rb
 - lib/hibiki/rails/keys.rb
+- lib/hibiki/rails/modifiers.rb
 - lib/hibiki/rails/nested_actions.rb
 - lib/hibiki/rails/reactive_form.rb
 - lib/hibiki/rails/registry.rb