hibiki_rails 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ab077d178d71a16ddf8d0f5706179f7fbac93c4d851aae6e3ccda4ef0e4b674
-  data.tar.gz: 409e833560a3393d2ca3c0121c2e958f3d8bb986a0b62aaaed653fe0c0f06af3
+  metadata.gz: e04ed317fc77afc03ef9dcb0ec2fc1f52833e23dd0700934e3bee3551c0f1549
+  data.tar.gz: b76c0323f43becb86476653aebd6cd58e01e1ab917c18fdf5e7e843c95f01e60
 SHA512:
-  metadata.gz: 552f5913948b16d8ed030b1eb12c35f7f28f0f109f31807dbbaf86f9b2320c3929c959c2872800785b635b9c05229df0ebe5c218e4429b490442ee2cb81ba133
-  data.tar.gz: 0ff3466d160bd5074a8d02530c87222fd8dcc5aeed43b033fb8ff3549decd55423286e1757511d352f39a5df47a4d60198dd0efb9fa254479febf43f1ea7d8c6
+  metadata.gz: c6b3b937fcaeba352b86432ceef1b4ec526e26e74509b83f39a868db656706fd4f89c64d6cd3d3805a6c5553376a1f09765dbd939ec28156bf3bb8cbcb696e45
+  data.tar.gz: 889c7cea1cfc1c772e6a18573e2717fbf8a569ff679a5a4f6208d2b961db6d80c4b7d8c00435e4be8783a7a57adfb22bb162d7d1624b566fedfd4f3ebbaeaf88

data/CHANGELOG.md

@@ -4,6 +4,78 @@ 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

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
@@ -208,6 +213,36 @@ window.addEventListener("popstate", (event) => {
   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)
@@ -911,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.
@@ -920,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)
@@ -941,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
@@ -1008,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)
@@ -1158,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))
@@ -1171,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
   }
@@ -1193,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
@@ -1206,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
@@ -1232,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()
@@ -1357,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
@@ -1366,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)) {
@@ -1411,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/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

@@ -7,6 +7,7 @@ require "securerandom"
 require_relative "dom_props"
 require_relative "keys"
 require_relative "modifiers"
+require_relative "commands"
 
 module Hibiki
   module Rails
@@ -223,13 +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(Modifiers.attributes(with:, debounce:, confirm:, reset:, fallback:)) }
+            .merge(Modifiers.attributes(with:, debounce:, confirm:, reset:, fallback:), extra) }
       end
 
       # Placeholder for a single reactive value: `<%= reactive :doubled, 0 %>`
@@ -279,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)

data/lib/hibiki/rails/modifiers.rb

@@ -19,6 +19,20 @@ module Hibiki
         }.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)

data/lib/hibiki/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Hibiki
   module Rails
-    VERSION = "0.19.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.19.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