hibiki_rails 0.18.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 915a98a11ca62685f60697d27383e8592978e0c2173b0e984c24eca7736cef55
-  data.tar.gz: 070cd14175c3027b164ec0b52378b59178499f3f3474fe3296722f6432c580ab
+  metadata.gz: e04ed317fc77afc03ef9dcb0ec2fc1f52833e23dd0700934e3bee3551c0f1549
+  data.tar.gz: b76c0323f43becb86476653aebd6cd58e01e1ab917c18fdf5e7e843c95f01e60
 SHA512:
-  metadata.gz: 5d07fa8e0a897a21cce85e559e42a02dc78090f89986bc37c24202a36fb81322287a1ae86fb4c5166aa615a4ee8924732bb63020643a2e4db8e8ec72a5d870eb
-  data.tar.gz: 993b20b7af2d105e5c067823621eb8050ff426a57a9ac0b0aacccbd2a9fd9136a9a2a6f0f635d7932952f7c4c58bef2645492c67fe1b79acbb28d1c2e86f5a37
+  metadata.gz: c6b3b937fcaeba352b86432ceef1b4ec526e26e74509b83f39a868db656706fd4f89c64d6cd3d3805a6c5553376a1f09765dbd939ec28156bf3bb8cbcb696e45
+  data.tar.gz: 889c7cea1cfc1c772e6a18573e2717fbf8a569ff679a5a4f6208d2b961db6d80c4b7d8c00435e4be8783a7a57adfb22bb162d7d1624b566fedfd4f3ebbaeaf88

data/CHANGELOG.md

@@ -4,6 +4,118 @@ 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.20.0 — 2026-10-12
+
+### Added
+
+**Commands.** `js` builds a list of things the browser does on an event,
+with no round trip. `on` takes the list where it takes an action name.
+
+```erb
+<%= tag.button "Menu", **on(js.toggle("#menu")) %>
+<%= tag.button "Cancel", **on(js.hide("#panel").push(:cancel)) %>
+```
+
+| Command | What it does |
+|---|---|
+| `show`, `hide`, `toggle` | writes the `hidden` attribute |
+| `add_class`, `remove_class`, `toggle_class` | one or more class names |
+| `set_attribute`, `remove_attribute`, `toggle_attribute` | an attribute by name |
+| `focus`, `focus_first` | focuses the target, or the first control inside it |
+| `dispatch` | fires a `CustomEvent`, with `detail:` and `bubbles:` |
+| `push` | performs a channel action, with `with:` as its payload |
+| `show_modal`, `close_dialog` | a `<dialog>`'s own methods |
+
+- A target is a CSS selector for the whole document, `{ inner: selector }`
+  for inside the control, or `{ closest: selector }` for its nearest
+  ancestor. With no target a command acts on the control. `hide`, `show`,
+  `toggle`, `focus`, `focus_first`, `show_modal` and `close_dialog` take the
+  target as their argument; the others take it as `to:`.
+- The commands run in order and do not wait for the server.
+- `confirm:` and `debounce:` on `on` apply to the whole list. `with:` goes on
+  `push`. `fallback: true` needs a `push` in the list.
+- A list prevents the event's default.
+- A command's change lasts until the server next renders that element. Keep
+  state the server should know in a signal.
+- Commands run only on a control inside an island.
+- `set_attribute` and its siblings refuse `on*`, `style`, `srcdoc`,
+  `data-hibiki-*`, `data-controller` and `data-action`.
+
+**The `hibiki-rails/commands` module.** Commands need one import, beside
+your controllers:
+
+```js
+import "hibiki-rails/commands"
+```
+
+`hibiki:rails:install` adds it to `app/javascript/application.js`. An
+existing app adds the line by hand, or runs the generator again. Without it
+a command list does nothing, and the client says so once in the console.
+
+**Dialogs the server opens.** `modal(open:)` on a `<dialog>` makes the
+channel's state decide whether it is open. After each render the client
+calls `showModal()` or `close()` to match.
+
+```erb
+<%= tag.dialog id: "editor", **on(:cancel, event: :cancel).deep_merge(modal(open: form.editing?)) do %>
+```
+
+- Use `modal` for a dialog the server must know about, such as a form it may
+  refuse to save. Use `js.show_modal` and `js.close_dialog` for one it need
+  not. Do not put both on one dialog.
+- `on` now hears a dialog's `cancel` and `close` events. `cancel` is Escape;
+  `close` also follows `close_dialog` and a close the server asked for.
+- A morph no longer removes the `open` attribute from a dialog inside an
+  island.
+- Keep what is typed in the dialog out of the effect that renders it, or
+  each keystroke redraws it.
+
+### Changed
+
+- A `focus` site inside a closed dialog does not count as on the page. It
+  takes focus when a render of this tab opens the dialog, and focus returns
+  to the control that opened it when the dialog closes.
+
+## 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-commands.js

@@ -0,0 +1,105 @@
+// hibiki-rails/commands — things a control does in the browser, with no
+// round trip: show and hide, classes, attributes, focus, a DOM event, a
+// dialog, and a channel action among them.
+//
+// Opt-in: `import "hibiki-rails/commands"` once, beside the controllers.
+// The view declares a list with the `js` helper (`on(js.hide("#panel")
+// .push(:cancel))`), which the client finds on the control as
+// data-hibiki-do and hands to the interpreter below, in order. Like the
+// rest of data-hibiki-*, the list's wire form is private to the gem.
+//
+// Only the names in OPS run, and an attribute command writes nothing a
+// handler, a style or this gem's own wiring could ride in on. Ruby keeps
+// the same two lists (Commands::OPS and Commands::REFUSED) and raises at
+// render; here anything outside them is skipped. Add a command in both
+// places.
+//
+// What a command changes lasts until the server next renders that element.
+// State the server should know belongs in a signal.
+import { useCommands } from "hibiki-rails"
+
+const REFUSED = /^(on|style$|srcdoc$|data-hibiki-|data-controller$|data-action$)/i
+const ATTRIBUTE = /^[a-z_:][a-z0-9_:.-]*$/i
+const ACTION = /^[a-z][a-z0-9_.-]*$/i
+const FOCUSABLE =
+  'a[href], button:not(:disabled), input:not(:disabled):not([type="hidden"]), ' +
+  'select:not(:disabled), textarea:not(:disabled), [tabindex]:not([tabindex="-1"])'
+
+// A selector is the app's, and a bad one must not stop the rest of a list.
+const query = (root, selector, all) => {
+  try {
+    return all ? [...root.querySelectorAll(selector)] : [root.closest(selector)].filter(Boolean)
+  } catch {
+    return []
+  }
+}
+
+// Nothing is the control; a string is looked up in the document; `inner`
+// inside the control; `closest` among its ancestors.
+const targets = (control, to) => {
+  if (to === undefined) return [control]
+  if (typeof to === "string") return query(document, to, true)
+  if (typeof to?.inner === "string") return query(control, to.inner, true)
+  if (typeof to?.closest === "string") return query(control, to.closest, false)
+  return []
+}
+
+const classes = (names) =>
+  Array.isArray(names) ? names.filter((name) => typeof name === "string" && /^\S+$/.test(name)) : []
+const writable = (name) => typeof name === "string" && ATTRIBUTE.test(name) && !REFUSED.test(name)
+
+// name -> what it does to one target.
+const OPS = {
+  show: (element) => element.removeAttribute("hidden"),
+  hide: (element) => element.setAttribute("hidden", ""),
+  toggle: (element) => element.toggleAttribute("hidden"),
+  add_class: (element, { names }) => element.classList.add(...classes(names)),
+  remove_class: (element, { names }) => element.classList.remove(...classes(names)),
+  toggle_class: (element, { names }) => {
+    for (const name of classes(names)) element.classList.toggle(name)
+  },
+  set_attribute: (element, { name, value }) => {
+    if (writable(name)) element.setAttribute(name, String(value ?? ""))
+  },
+  remove_attribute: (element, { name }) => {
+    if (writable(name)) element.removeAttribute(name)
+  },
+  toggle_attribute: (element, { name, value }) => {
+    if (!writable(name)) return
+    if (element.hasAttribute(name)) element.removeAttribute(name)
+    else element.setAttribute(name, String(value ?? ""))
+  },
+  dispatch: (element, { name, detail, bubbles }) => {
+    if (typeof name !== "string") return
+    element.dispatchEvent(new CustomEvent(name, { bubbles: bubbles !== false, detail }))
+  },
+  show_modal: (element) => {
+    if (typeof element.showModal === "function" && !element.open) element.showModal()
+  },
+  close_dialog: (element) => {
+    if (element.open) element.close?.()
+  }
+}
+
+// Focus goes to one element, so these take the first target only.
+const FOCUS = {
+  focus: (element) => element,
+  focus_first: (element) => element.querySelector(FOCUSABLE)
+}
+
+useCommands((ops, control, push) => {
+  for (const op of ops) {
+    if (!Array.isArray(op)) continue
+    const [name, args = {}] = op
+    if (name === "push") {
+      if (typeof args.action === "string" && ACTION.test(args.action)) push(args.action, args.with ?? {})
+    } else if (Object.hasOwn(FOCUS, name)) {
+      const [first] = targets(control, args.to)
+      if (first) FOCUS[name](first)?.focus()
+    } else if (Object.hasOwn(OPS, name)) {
+      // With no target, close_dialog closes the dialog the control is in.
+      const to = name === "close_dialog" && args.to === undefined ? { closest: "dialog" } : args.to
+      for (const element of targets(control, to)) OPS[name](element, args)
+    }
+  }
+})

data/app/assets/javascripts/hibiki.js

@@ -64,6 +64,11 @@
 //                 that have no attribute, assigned on connect and after each
 //                 render; only the names in PROPS below, an optional "key"
 //                 beside them existing to change the text
+//   command lists data-hibiki-on="click->*" with data-hibiki-do='[["hide",
+//                 {"to":"#panel"}],["push",{"action":"cancel"}]]': the browser
+//                 runs the list on the event; see `useCommands` below
+//   modal sites   data-hibiki-modal="true|false"       a <dialog> shown with
+//                 showModal() or closed, on connect and after each render
 //   focus sites   data-hibiki-focus="true|select"      takes focus, and has its
 //                 text selected, when a render this tab caused inserts it
 //   turbo streams data-hibiki-seq="3"                  the render's number, and
@@ -93,7 +98,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 +192,57 @@ 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 command module's seam. A control whose token names `*` runs a list
+// of commands (data-hibiki-do) in place of one action; what runs them is
+// the opt-in module `hibiki-rails/commands`, which hands its interpreter
+// over here on import. Without it the list does nothing, and says so once.
+let commands
+let warned = false
+export function useCommands(interpreter) {
+  commands = interpreter
+}
+
+// A <dialog> the server declares open or closed (Helpers#modal): the state
+// is a method call away from any attribute, so it is made to match here,
+// on connect and after each render.
+const applyModal = (dialog) => {
+  if (typeof dialog.showModal !== "function") return
+  const open = dialog.dataset.hibikiModal === "true"
+  if (open && !dialog.open) dialog.showModal()
+  else if (!open && dialog.open) dialog.close()
+}
+
+// The browser writes `open` on a dialog it shows, and no server HTML has
+// it, so a morph would take it off and leave the dialog shown but closed.
+// Inside an island that attribute is the browser's.
+document.addEventListener("turbo:before-morph-attribute", (event) => {
+  const { target } = event
+  if (target.localName === "dialog" && event.detail?.attributeName === "open" && islandFor(target)) {
+    event.preventDefault()
+  }
+})
+
 // 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 +368,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 +400,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 +566,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 +659,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 +672,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 +680,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 +698,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 +831,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
@@ -847,6 +946,9 @@ export default class HibikiController extends ChannelController {
     for (const site of this.element.querySelectorAll("[data-hibiki-props]")) {
       applyProps(site)
     }
+    for (const dialog of this.element.querySelectorAll("[data-hibiki-modal]")) {
+      applyModal(dialog)
+    }
 
     // Root-scoped delegation (bound to the island, not document): controls
     // inside server-replaced fragments keep working with no rebinding.
@@ -856,6 +958,13 @@ export default class HibikiController extends ChannelController {
       this.element.addEventListener(type, handler)
       return [type, handler]
     })
+    // A dialog's `cancel` (Escape, before it closes) and `close` do not
+    // bubble, so they are heard on the way down.
+    for (const type of ["cancel", "close"]) {
+      const handler = (event) => this.forward(event)
+      this.element.addEventListener(type, handler, true)
+      this.listeners.push([type, handler, true])
+    }
     // Keys take their own path: a key names its control by a token, not by
     // being the nearest one.
     const keydown = (event) => this.key(event)
@@ -877,7 +986,7 @@ export default class HibikiController extends ChannelController {
     // page's own marks already seen.
     this.marks = new Map()
     for (const site of this.element.querySelectorAll("[data-hibiki-focus]")) {
-      if (site.closest(ISLAND) === this.element) this.marks.set(site, undefined)
+      if (this.marked(site)) this.marks.set(site, undefined)
     }
 
     // `visible` is not a DOM event, so it needs its own observer beside the
@@ -944,8 +1053,8 @@ export default class HibikiController extends ChannelController {
 
   disconnect() {
     islands.delete(this.element)
-    for (const [type, handler] of this.listeners) {
-      this.element.removeEventListener(type, handler)
+    for (const [type, handler, capture] of this.listeners) {
+      this.element.removeEventListener(type, handler, capture)
     }
     document.removeEventListener("turbo:before-stream-render", this.streamRender)
     document.removeEventListener("turbo:before-render", this.pageBefore)
@@ -1094,8 +1203,11 @@ export default class HibikiController extends ChannelController {
     if (self && index === 0) {
       const twin = found(ids[0])
       twin.focus()
-      if (start != null && document.activeElement === twin) twin.setSelectionRange?.(start, end)
-      return
+      // It may not have taken it: a field of a dialog now closed.
+      if (document.activeElement === twin) {
+        if (start != null) twin.setSelectionRange?.(start, end)
+        return
+      }
     }
     const candidates = [opener && this.twin(opener)]
     if (index === (self ? 1 : 0)) candidates.push(...found(ids[index]).querySelectorAll(FOCUSABLE))
@@ -1107,12 +1219,13 @@ export default class HibikiController extends ChannelController {
 
   // The control a gesture came from, or the one a render has put in its
   // place: the same id, else the same action and payload.
-  twin({ element, id, on, payload }) {
+  twin({ element, id, on, payload, ops }) {
     if (element.isConnected) return element
     const twin = id
       ? document.getElementById(id)
       : [...this.element.querySelectorAll("[data-hibiki-on]")].find(
-          (control) => control.dataset.hibikiOn === on && control.dataset.hibikiWith === payload
+          ({ dataset }) =>
+            dataset.hibikiOn === on && dataset.hibikiWith === payload && dataset.hibikiDo === ops
         )
     return twin?.closest(ISLAND) === this.element ? twin : null
   }
@@ -1129,9 +1242,17 @@ export default class HibikiController extends ChannelController {
   // a listener twice is a no-op too. Props need no ownership check: assigning one twice,
   // from a nested island and its parent, lands the same value. Nor does
   // the window listener, which finds nothing of its own to fire.
+  // A focus site this island counts as on the page: its own, and not
+  // inside a closed dialog. So a dialog's field is new on the render that
+  // opens the dialog, though its markup was there all along, and gone on
+  // the one that closes it, which is when focus goes back to the opener.
+  marked(site) {
+    return site.closest(ISLAND) === this.element && !site.closest("dialog:not([open])")
+  }
+
   scan({ own = false, control, trail } = {}) {
     const found = this.element.querySelectorAll(
-      `[data-hibiki-on*="visible->"], [data-hibiki-props], [data-hibiki-focus], ${HOTKEYED}`
+      `[data-hibiki-on*="visible->"], [data-hibiki-props], [data-hibiki-focus], [data-hibiki-modal], ${HOTKEYED}`
     )
     let hotkeys = this.element.matches(HOTKEYED)
     // A site is the one seen before when it is that element or, after a
@@ -1142,7 +1263,9 @@ export default class HibikiController extends ChannelController {
     const ids = new Set()
     let site
     for (const element of found) {
-      if (element.hasAttribute("data-hibiki-focus") && element.closest(ISLAND) === this.element) {
+      // First: a focus site inside the dialog is on the page once it opens.
+      if (element.hasAttribute("data-hibiki-modal")) applyModal(element)
+      if (element.hasAttribute("data-hibiki-focus") && this.marked(element)) {
         marks.set(element, this.marks.get(element) ?? seen.get(element.id))
         if (element.id) ids.add(element.id)
         if (!this.marks.has(element) && !seen.has(element.id)) site ??= element
@@ -1168,7 +1291,13 @@ export default class HibikiController extends ChannelController {
     if (own && site && !this.unsent.has(trail?.element)) {
       if (control) {
         const { id, dataset } = control
-        marks.set(site, { element: control, id, on: dataset.hibikiOn, payload: dataset.hibikiWith })
+        marks.set(site, {
+          element: control,
+          id,
+          on: dataset.hibikiOn,
+          payload: dataset.hibikiWith,
+          ops: dataset.hibikiDo
+        })
       }
       const take = () => {
         site.focus()
@@ -1218,6 +1347,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.
@@ -1268,7 +1422,9 @@ export default class HibikiController extends ChannelController {
     // Before the confirm, not after: declining must not let the form (or
     // a fallback control's navigation) proceed. Optional call because the
     // `visible` pseudo-event arrives as a plain object.
-    if (event.type === "submit" || fallback) event.preventDefault?.()
+    // A command list is the control's whole behaviour, so its default goes.
+    const listed = action === "*"
+    if (event.type === "submit" || fallback || listed) event.preventDefault?.()
 
     const message = control.dataset.hibikiConfirm
     if (message && !window.confirm(message)) return
@@ -1277,7 +1433,7 @@ export default class HibikiController extends ChannelController {
     // input sends what the user finished typing rather than the first
     // keystroke that started the timer.
     const wait = Number(control.dataset.hibikiDebounce)
-    const fire = () => this.send(control, event, action)
+    const fire = () => (listed ? this.command(control, event) : this.send(control, event, action))
     if (wait > 0) {
       const field = event.target
       if (event.type !== "keydown" && typed(field)) {
@@ -1322,10 +1478,32 @@ export default class HibikiController extends ChannelController {
     }
   }
 
-  send(control, event, action) {
-    const payload = control.dataset.hibikiWith
-      ? JSON.parse(control.dataset.hibikiWith)
-      : {}
+  // The control's command list, handed to the command module with the one
+  // thing only this file can do: send an action as the control's own.
+  command(control, event) {
+    if (!commands) {
+      if (!warned) console.warn('hibiki: a control has commands, but "hibiki-rails/commands" is not imported')
+      warned = true
+      return
+    }
+    let ops
+    try {
+      ops = JSON.parse(control.dataset.hibikiDo)
+    } catch {
+      return
+    }
+    if (!Array.isArray(ops)) return
+    commands(ops, control, (action, payload) => this.send(control, event, action, payload))
+  }
+
+  // `given` is a pushed command's payload, where a plain action reads the
+  // control's own.
+  send(control, event, action, given) {
+    const payload = given
+      ? { ...given }
+      : control.dataset.hibikiWith
+        ? JSON.parse(control.dataset.hibikiWith)
+        : {}
     if (event.type === "submit") {
       Object.assign(payload, formPayload(control))
     } else if (control.name && (event.type === "change" || event.type === "input")) {

data/config/importmap.rb

@@ -8,3 +8,6 @@
 pin "hibiki-rails", to: "hibiki.js"
 # The opt-in motion module; it imports "hibiki-rails" by the pin above.
 pin "hibiki-rails/motion", to: "hibiki-motion.js"
+# The opt-in commands module (`on(js.hide(...))`); the install generator
+# imports it.
+pin "hibiki-rails/commands", to: "hibiki-commands.js"

data/lib/generators/hibiki/rails/install/install_generator.rb

@@ -18,7 +18,7 @@ module Hibiki
 
         desc "Wires the packaged hibiki client: registers the \"hibiki\" Stimulus " \
              "controller, includes Hibiki::Rails::Helpers in ApplicationHelper, " \
-             "and creates the ApplicationCable boilerplate."
+             "imports the commands module, and creates the ApplicationCable boilerplate."
 
         # Exactly the lines `stimulus:manifest:update` emits for the shim,
         # so a later manifest run converges instead of duplicating.
@@ -30,6 +30,12 @@ module Hibiki
 
         INCLUDE_LINE = "  include Hibiki::Rails::Helpers\n"
 
+        # The opt-in module that runs `on(js....)` command lists. One line in
+        # the file both worlds have: the engine's pin answers it in importmap
+        # apps, the npm package under a bundler.
+        APPLICATION_JS = "app/javascript/application.js"
+        COMMANDS_IMPORT = %(import "hibiki-rails/commands"\n)
+
         # Stock Rails apps don't have these until the first `rails g
         # channel` — the hibiki:rails:* generators write their channels
         # directly, so install supplies the boilerplate they inherit.
@@ -63,6 +69,13 @@ module Hibiki
                            after: /module ApplicationHelper\s*\n/
         end
 
+        def import_commands
+          return say_status :identical, APPLICATION_JS, :blue if wired?(APPLICATION_JS, COMMANDS_IMPORT.strip)
+          return manual_wiring(APPLICATION_JS, COMMANDS_IMPORT) unless exists?(APPLICATION_JS)
+
+          append_to_file APPLICATION_JS, COMMANDS_IMPORT
+        end
+
         # Presence is enough — an app's own ApplicationCable (customized
         # or not) is never touched.
         def create_application_cable

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/commands.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hibiki
+  module Rails
+    # What Helpers#js builds: a list of things the browser does on an event
+    # with no round trip, in order. Each method returns a new list, so one
+    # can be kept and extended:
+    #
+    #   js.toggle("#menu")
+    #   js.hide("#panel").push(:cancel)
+    #   js.add_class("open", to: { closest: "li" })
+    #
+    # A target is a CSS selector looked up in the whole document,
+    # `{ inner: selector }` (inside the control), `{ closest: selector }`
+    # (the control's nearest ancestor), or nothing, which is the control
+    # itself. The client runs only the names in OPS and keeps the same list
+    # (OPS in hibiki-commands.js). Add a command in both places.
+    class Commands
+      OPS = %w[
+        show hide toggle add_class remove_class toggle_class set_attribute remove_attribute
+        toggle_attribute focus focus_first dispatch push show_modal close_dialog
+      ].freeze
+
+      # An attribute a command may not write: a handler, a style, markup, or
+      # the wiring of this gem and Stimulus.
+      REFUSED = /\A(on|style\z|srcdoc\z|data-hibiki-|data-controller\z|data-action\z)/i
+      ATTRIBUTE = /\A[a-z_:][a-z0-9_:.-]*\z/i
+      SCOPES = %i[inner closest].freeze
+      # A dispatched event's name; app events are often namespaced by a colon.
+      EVENT = /\A[a-z][a-z0-9_.:-]*\z/i
+
+      attr_reader :ops
+
+      def initialize(ops = [])
+        @ops = ops.freeze
+        freeze
+      end
+
+      # Show, hide or flip an element by its `hidden` attribute, which is
+      # also what the server renders it with.
+      def show(to = nil) = add("show", to:)
+      def hide(to = nil) = add("hide", to:)
+      def toggle(to = nil) = add("toggle", to:)
+
+      def add_class(names, to: nil) = add("add_class", to:, names: Commands.names(names))
+      def remove_class(names, to: nil) = add("remove_class", to:, names: Commands.names(names))
+      def toggle_class(names, to: nil) = add("toggle_class", to:, names: Commands.names(names))
+
+      def set_attribute(name, value, to: nil)
+        add("set_attribute", to:, name: Commands.attribute(name), value: value.to_s)
+      end
+
+      def remove_attribute(name, to: nil) = add("remove_attribute", to:, name: Commands.attribute(name))
+
+      # Present with `value`, or absent.
+      def toggle_attribute(name, value = "", to: nil)
+        add("toggle_attribute", to:, name: Commands.attribute(name), value: value.to_s)
+      end
+
+      def focus(to = nil) = add("focus", to:)
+
+      # The first control inside the target that can take focus.
+      def focus_first(to = nil) = add("focus_first", to:)
+
+      # A CustomEvent on the target, for the page's own JavaScript.
+      def dispatch(name, to: nil, detail: nil, bubbles: true)
+        add("dispatch", to:, name: Commands.event(name), detail:, bubbles: (false unless bubbles))
+      end
+
+      # A channel action, as `on(:action, with:)` sends it.
+      def push(action, with: nil) = add("push", action: Helpers.event_name(action), with:)
+
+      # A <dialog>, by its own methods: the browser keeps focus inside it,
+      # closes it on Escape and gives focus back. With no target,
+      # close_dialog closes the one the control is in.
+      def show_modal(to) = add("show_modal", to: to || raise(ArgumentError, "show_modal needs a target"))
+      def close_dialog(to = nil) = add("close_dialog", to:)
+
+      def push? = ops.any? { it.first == "push" }
+      def empty? = ops.empty?
+      def to_json(*) = JSON.generate(ops)
+
+      def self.names(names)
+        list = Array(names).flat_map { it.to_s.split }
+        raise ArgumentError, "a class command needs at least one class name" if list.empty?
+
+        list
+      end
+
+      def self.event(name)
+        name = name.to_s
+        return name if EVENT.match?(name)
+
+        raise ArgumentError, "dispatched event #{name.inspect} must match #{EVENT.inspect}"
+      end
+
+      def self.attribute(name)
+        name = name.to_s
+        return name if ATTRIBUTE.match?(name) && !REFUSED.match?(name)
+
+        raise ArgumentError, "attribute #{name.inspect} is not one a command may write"
+      end
+
+      def self.target(to)
+        return selector(to) if to.is_a?(String)
+        return { to.keys.first.to_s => selector(to.values.first) } if scoped?(to)
+
+        raise ArgumentError,
+              "command target #{to.inspect} must be a selector, { inner: selector } or { closest: selector }"
+      end
+
+      def self.scoped?(to) = to.is_a?(Hash) && to.size == 1 && SCOPES.include?(to.keys.first)
+
+      def self.selector(value)
+        return value if value.is_a?(String) && !value.strip.empty?
+
+        raise ArgumentError, "command selector #{value.inspect} must be a non-empty string"
+      end
+
+      private
+
+      def add(name, to: nil, **args)
+        args[:to] = Commands.target(to) unless to.nil?
+        self.class.new([*ops, [name, args.compact.transform_keys(&:to_s)]])
+      end
+    end
+  end
+end

data/lib/hibiki/rails/helpers.rb

@@ -6,6 +6,8 @@ require "securerandom"
 
 require_relative "dom_props"
 require_relative "keys"
+require_relative "modifiers"
+require_relative "commands"
 
 module Hibiki
   module Rails
@@ -187,6 +189,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":
       #
@@ -218,12 +224,14 @@ module Hibiki
       #                 works in both worlds).
       def on(action, event: :click, with: nil, debounce: nil, confirm: nil, reset: nil,
              fallback: nil)
-        action = Helpers.event_name(action)
+        extra = Modifiers.chain(action, with:, fallback:)
+        action = extra.empty? ? Helpers.event_name(action) : Modifiers::CHAIN
         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:), extra) }
       end
 
       # Placeholder for a single reactive value: `<%= reactive :doubled, 0 %>`
@@ -273,6 +281,30 @@ module Hibiki
         { data: { hibiki_props: JSON.generate(wanted) } }
       end
 
+      # Commands the browser runs on the event itself, with no round trip:
+      #
+      #   tag.button "Menu", **on(js.toggle("#menu"))
+      #   tag.button "Cancel", **on(js.hide("#panel").push(:cancel))
+      #
+      # Commands lists them. `on` takes the list where it takes an action
+      # name; `confirm:` and `debounce:` then apply to the whole list, and
+      # the event's default is prevented. The page must import
+      # "hibiki-rails/commands". What a command changes lasts until the
+      # server next renders that element, so state the server should know
+      # belongs in a signal.
+      def js = Commands.new
+
+      # Open or close a <dialog> as the server's state says:
+      #
+      #   tag.dialog id: "editor", **modal(open: form.editing?)
+      #
+      # After each render the client calls showModal() or close() to match.
+      # Render it by morph where you can: a replaced dialog is a new element
+      # and opens again. For a dialog the server need not know about, use
+      # `js.show_modal` and `js.close_dialog` instead, not both on one.
+      # `on(:cancel, event: :cancel)` on the dialog hears Escape.
+      def modal(open:) = { data: { hibiki_modal: open ? "true" : "false" } }
+
       # Put the cursor in this element when a render opens it:
       #
       #   tag.input name: "title", value: form.title, **focus(select: true)
@@ -305,20 +337,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,44 @@
+# 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
+
+      # What stands in for the action name in a token whose control runs a
+      # command list. No action can be named this.
+      CHAIN = "*"
+
+      # The attribute a command list adds, or nothing for an action name.
+      def self.chain(action, with:, fallback:)
+        return {} unless action.is_a?(Commands)
+        raise ArgumentError, "on(js) needs at least one command" if action.empty?
+        raise ArgumentError, "with: belongs on the command: js.push(:action, with: ...)" unless with.nil?
+        raise ArgumentError, "fallback: needs a push in the commands" if fallback && !action.push?
+
+        { hibiki_do: action.to_json }
+      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.20.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.20.0
 platform: ruby
 authors:
 - planetaska
@@ -76,6 +76,7 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - README.md
+- app/assets/javascripts/hibiki-commands.js
 - app/assets/javascripts/hibiki-motion.js
 - app/assets/javascripts/hibiki.js
 - config/importmap.rb
@@ -182,6 +183,7 @@ files:
 - lib/hibiki/rails.rb
 - lib/hibiki/rails/broadcasts.rb
 - lib/hibiki/rails/channel.rb
+- lib/hibiki/rails/commands.rb
 - lib/hibiki/rails/debounce.rb
 - lib/hibiki/rails/dom_props.rb
 - lib/hibiki/rails/engine.rb
@@ -189,6 +191,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