hibiki_rails 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce497d3d19ee46dede8bb9973f3a408e8b724f588ee2ebce3a4c0a0e5aa998f1
-  data.tar.gz: 1eea58578f6a73f3617a8f717cc1407023d741c1bbd1fb68f534b1fe135a4caa
+  metadata.gz: fbcb87c658d3e83cc6c10f216a69e78266878aa8396ed9662e3f06d8c6213027
+  data.tar.gz: d6a66d149293d26e43edf4cd31ec20eb5886cc0d3db2b935b5b0c3c333965292
 SHA512:
-  metadata.gz: fd67705cbe7db3a1eb1ddcd5dd914e7f8377f01070d564f3dca40a96f205833ef0a442f3a74bc68a8928d6577461a8bc83427c0e0117c711d3fd5733fa478b9e
-  data.tar.gz: eefeee042142381f1e2f1f2dba0d49d2884db32409a029d08215a9479aefce564bc7e03333c23b525ade2dc37fc3111a89ebbabd52fed6adf450bfe19c9f63bf
+  metadata.gz: 0e027bd60c62abdf4d269b94cd38f0e008889b42d205b9f2d98d737f1455acd60f467cf9951a5a35f77bbc3ee02120b8e5f6397fc43dc9b7dc7842d91c73372e
+  data.tar.gz: 28a6058a2a235ef23e02d52b5dbdf7177f97b6ba96971d9c72ea0d0302d6eaf380854b2e283069177b2038a06a2d45af540bf3b929a62f53baa7144589c33bc3

data/CHANGELOG.md

@@ -4,6 +4,132 @@ 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.17.0 — 2026-10-08
+
+### Added
+
+**Keys in `on`.** `event:` takes `keydown.<key>`, so a form's Escape or a
+list's arrow keys reach the channel with no JavaScript in the app.
+
+```erb
+<%= tag.div(**on(:cancel, event: "keydown.esc")) do %> ... <% end %>
+<%= link_to "New", new_song_path,
+      **on(:new_form, event: ["click", "keydown.n@window"]) %>
+```
+
+- A key is heard while focus is inside its element. With `@window` it is
+  heard anywhere on the page, for as long as the element is rendered.
+- Keys: `enter`, `tab`, `esc`, `space`, `up`, `down`, `left`, `right`,
+  `home`, `end`, `page_up`, `page_down`, a letter, or a digit. Modifiers go
+  in front: `keydown.ctrl+s`, `keydown.meta+shift+k`. They are `ctrl`, `meta`
+  and `shift`, and they match exactly.
+- A matched key's default is prevented. Keys pressed during IME composition
+  and a held key's repeats are ignored.
+- A window key with neither `ctrl` nor `meta` is ignored while the visitor is
+  typing in a field, except `esc`.
+- A bare `keydown` raises; `input` is the event for typed text.
+
+**`focus`: the cursor in a field a render opens.** A row that turns into a
+form used to leave focus on the page, so the visitor had to click into the
+field before typing or pressing Escape.
+
+```erb
+<%= text_field_tag "title", form.title, **focus(select: true) %>
+```
+
+- The client focuses the marked element once, on the render that brings it.
+  `select: true` also selects its text.
+- Only a render this tab's own action caused counts. Another visitor's save
+  never moves the cursor, and neither does a page refresh.
+- A marked element in the page's first HTML is not focused; use `autofocus`
+  there.
+- Focus is not taken from a field whose typed text has yet to be sent.
+- `focus` returns a `{ data: }` hash like `on` and `props`:
+  `**on(:set_field, event: :input).deep_merge(focus)`.
+
+**Focus comes back when a render removes the focused element.** After Save,
+Cancel or Escape the form is gone, and focus used to fall to `<body>`: a
+keyboard user lost their place, and the island stopped hearing keys. The
+client now gives focus back to a control. Nothing more to write in the view.
+
+- A form opened with `focus` returns to the control that opened it: the
+  row's Edit link, the New button. The client remembers which control's
+  action brought the marked field, and finds it again after a re-render by
+  its id, or by its action and `with:` payload.
+- A replaced element with the same id takes the focus, and the caret, its
+  predecessor had.
+- Failing both, focus goes to the first control inside the nearest ancestor
+  that has an id.
+- Only a control ever takes focus. When none of these is found, as after a
+  row is destroyed, focus is left where the browser put it.
+- It applies to any render, on both transports and after a page refresh, and
+  never moves focus the visitor has since put somewhere else.
+
+### Fixed
+
+**Typed text is no longer lost to a render that lands inside the input
+debounce.** A debounced field holds text the server has not heard for a
+quarter second. Any render reaching the field in that wait was drawn without
+it, and the morph wrote the older value over what the visitor had typed. The
+render need not be theirs: another visitor's save of any row was enough.
+
+- A field with unsent input now wins over a render. The client records the
+  text and the caret as it is typed and puts them back after the render,
+  until the debounced send has fired. After that the server's value wins
+  again, so Reset and a failed save still overwrite the field.
+- Any action that is not debounced first sends the island's pending
+  debounced input, so gestures reach the server in the order they were made:
+  typing into a field and pressing Enter inside the wait no longer saves the
+  form without the last characters.
+- This covers fields wired with a debounce (`event: :input`). Checkboxes,
+  radios, file inputs and multi-selects are not recorded.
+
+## 0.16.0 — 2026-10-07
+
+### Added
+
+**`props`: DOM properties from the view.** Some state of a control has no
+HTML attribute, so no re-rendered fragment could carry it: a checkbox's
+`indeterminate`, a container's scroll position. A page that needed one
+brought JavaScript of its own. The new helper writes the wanted properties
+beside the element's other attributes, and the client assigns them when the
+island connects and after every render, on both transports.
+
+```erb
+<%= check_box_tag "all", "1", all_selected,
+      **on(:select_all, event: :change)
+          .deep_merge(props(indeterminate: some_selected)) %>
+<%= tag.div class: "list", **props(scroll_top: 0, key: page) do %>
+```
+
+- `indeterminate:` is assigned after every render, so the server's value wins
+  over a click (the browser clears the property when the box is clicked).
+- `scroll_top:` and `scroll_left:` are assigned to a new element, and again
+  only when the helper's output changes, so the visitor's own scrolling
+  survives unrelated renders. `key:` takes any JSON value and exists to change
+  the output: `scroll_top: 0, key: page` scrolls back to the top on each page
+  change, though the `0` never changes.
+- The list is an allowlist kept on both sides: an unknown name raises in Ruby
+  and is ignored by the client, so a fragment cannot reach `innerHTML` or an
+  event handler.
+- `props` returns a `{ data: }` hash like `on`. Two splats of the same key do
+  not merge, so combine them with `deep_merge` (or Phlex's `mix`).
+- The element must be inside an island. This is a client change: the scan that
+  re-observes `visible` sentinels after a render now assigns properties in the
+  same walk.
+
+Not covered, by design: properties that already have an attribute (`value`,
+`checked`, `disabled`, `open` on `<details>`) ride the fragment as before.
+Modal dialogs, focus and media playback are method calls, not properties, and
+are left for a later release.
+
+### Fixed
+
+- A `visible` sentinel inside a page that a refresh stream
+  (`broadcast_refresh_effect`) morphed was not re-observed: the page morph
+  runs after the stream's own render returns. The island now also rescans on
+  `turbo:render`.
+
 ## 0.15.0 — 2026-09-09
 
 ### Added

data/app/assets/javascripts/hibiki-motion.js

@@ -44,6 +44,10 @@ const idsOf = (root) => new Set(marked(root).map((element) => element.id))
 // `own`: the island's trip records are the honest gesture signal — the
 // control of an in-flight trip, or the last control the island tracked
 // (kept past its trip's settle; a render can land after the ack's grace).
+// No island is no evidence, not a plain mark: an `own` element outside any
+// generic island (a ChannelController subclass over Turbo streams) never
+// animates its leave, since the policy exists to keep rows that paged or
+// filtered away from sliding. A plain mark is the way to always animate.
 const ownsGesture = (island, element) => {
   if (!island) return false
   for (const record of island.busy.values()) {

data/app/assets/javascripts/hibiki.js

@@ -45,7 +45,10 @@
 //                 data-hibiki-params-value='{"record_id":7}'  extra subscribe
 //                 params, merged UNDER channel/cid so they can't override them
 //   controls      data-hibiki-on="<event>-><action> ..."  whitespace-separated;
-//                 e.g. "click->load_more visible->load_more"
+//                 e.g. "click->load_more visible->load_more". A key is
+//                 "keydown.<key>" (heard inside the control) or
+//                 "keydown.<key>@window" (heard anywhere), with ctrl+ meta+
+//                 shift+ in front in that order; only the names in KEYS below
 //                 data-hibiki-with='{"index":3}'       optional JSON payload
 //                 data-hibiki-debounce="250"           ms to let the gesture settle
 //                 data-hibiki-confirm="Are you sure?"  window.confirm gate
@@ -57,6 +60,12 @@
 //                 browser does what the markup says
 //   value sites   data-hibiki-value="<name>"           reactive-value placeholder;
 //                 the server's transmit_value message updates every match
+//   prop sites    data-hibiki-props='{"indeterminate":true}'  DOM properties
+//                 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
+//   focus sites   data-hibiki-focus="true|select"      takes focus, and has its
+//                 text selected, when a render this tab caused inserts it
 //
 // The client writes the protocol's other half at runtime — read-only to
 // app code, addressed to app CSS:
@@ -85,6 +94,30 @@
 // Everything that is not "which event" is a sibling attribute, so the
 // token grammar never has to grow.
 //
+// A debounced field holds text the server has not heard, and two rules keep
+// it. A render landing inside the wait is drawn without the text, so the
+// client records it at input time and puts it back after the render: a
+// field with unsent input wins, until its send fires. And any undebounced
+// action first flushes the island's pending debounces, so gestures reach
+// the server in the order they were made.
+//
+// A focus site takes focus once, on the render that brings it: marked now
+// and not at the scan before, by element or by id. Only a render this tab
+// caused counts, one that arrived while an action was in flight or just
+// after its ack, so a render nobody here asked for never moves the cursor.
+// A mark in the page's first HTML is `autofocus`'s business, and a refresh
+// morph focuses nothing.
+//
+// Focus is also given back. When a render removes the element that had
+// focus, it would fall to <body>: a keyboard user loses their place, and
+// the island stops hearing keys. So the client looks, in order, for the
+// element now carrying the same id (a replaced field); for the control
+// whose gesture opened the focus site that render closed (the Edit button
+// of a form now gone), known again after a re-render by its id or by its
+// action and payload; and for the first control of the focused element's
+// nearest id-bearing ancestor. Only controls: when none of these is there,
+// focus is left where the browser put it. Any render, whoever caused it.
+//
 // App JS reaching the graph — the ONE public seam. A gesture that needs
 // script (drag-and-drop, a third-party widget) fires its action through
 // the island's OWN subscription: `perform(action, payload)` on the island
@@ -142,7 +175,9 @@ const islands = new WeakMap()
 // 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)
-// gets plain marks only.
+// yields no records: its `own` marks never animate a leave a Turbo stream
+// removes. (The transmit swap's event carries the subclass itself, so
+// `own` works there once the subclass tracks its controls.)
 export function islandFor(element) {
   for (let node = element; node; node = node.parentElement) {
     const island = islands.get(node)
@@ -226,9 +261,15 @@ export class ChannelController extends Controller {
   // busyCeiling ms before a trip is declared stalled rather than silently
   //             cleared. On a bad link "we lost it" beats "nothing
   //             happened".
+  // focusGrace  ms after a trip settles in which a render still counts as
+  //             its answer (see own()). One action can broadcast twice: the
+  //             first render settles the trip with the ack and the second
+  //             trails both. Longer than busyGrace because a missed focus
+  //             costs more than a spinner's flicker.
   static busyDelay = 150
   static busyGrace = 60
   static busyCeiling = 10000
+  static focusGrace = 500
 
   async connect() {
     this.prepareTransport()
@@ -248,6 +289,7 @@ export class ChannelController extends Controller {
     this.seq = 0
     this.renders = 0
     this.busy = new Map()
+    this.settledAt = -Infinity
     this.lastControl = null
     this.queued = []
     this.setState("connecting")
@@ -401,7 +443,9 @@ export class ChannelController extends Controller {
     // The most recent gesture, kept past its trip's settle for the motion
     // module's `own` policy (a render can land after the ack's grace). Set
     // before the record check: a send that died on the socket was still a
-    // gesture. A ChannelController subclass wanting `own` calls this itself.
+    // gesture. A ChannelController subclass wanting `own` calls this itself —
+    // which serves the transmit swap only: a Turbo stream reaches the
+    // records through islandFor, and that walk lists generic islands alone.
     this.lastControl = control
     const record = this.busy.get(seq)
     if (!record) return
@@ -439,6 +483,7 @@ export class ChannelController extends Controller {
     clearTimeout(record.ceiling)
     clearTimeout(record.grace)
     this.busy.delete(seq)
+    this.settledAt = performance.now()
     record.control?.removeAttribute("data-hibiki-busy")
     if (this.busy.size === 0) this.hideBusy()
   }
@@ -456,6 +501,13 @@ export class ChannelController extends Controller {
     this.element.removeAttribute("aria-busy")
   }
 
+  // Whether a render arriving now answers this tab's own action: one is in
+  // flight, or settled within the grace. Asked when the render arrives, not
+  // when it is applied, since the motion module may hold it for a second.
+  own() {
+    return this.busy.size > 0 || performance.now() - this.settledAt <= this.constructor.focusGrace
+  }
+
   // Say so rather than clearing silently: on a bad link the honest report
   // is "we lost it", and a cleared indicator claims the opposite.
   stall(seq) {
@@ -578,6 +630,122 @@ export class ChannelController extends Controller {
   }
 }
 
+// The DOM properties a fragment may set (Helpers#props), and when. A
+// property has no attribute, so no swap or morph carries it: the client
+// assigns it after the fact. The table is the allowlist — a fragment must
+// never reach innerHTML or onclick — and a value of the wrong type is
+// skipped. `always` is re-assigned after every render (the browser clears
+// indeterminate on click; the server's value comes back). `changed` is
+// assigned only to a new element or when the attribute's text differs from
+// the text last applied, so the visitor's own scrolling survives unrelated
+// renders; the view's `key:` is how it says "again".
+const PROPS = {
+  indeterminate: ["boolean", "always"],
+  scrollTop: ["number", "changed"],
+  scrollLeft: ["number", "changed"]
+}
+const appliedProps = new WeakMap()
+
+// Fields whose state is not their `value`, so there is no typed text to keep.
+const typed = (field) =>
+  typeof field.value === "string" &&
+  !field.multiple &&
+  !["checkbox", "radio", "file"].includes(field.type)
+
+// The keys a `keydown.<key>` token may name, by the `event.key` each
+// reports; a single letter or digit names itself. The server keeps the same
+// list (Keys in the gem) and emits nothing outside it.
+const KEYS = {
+  enter: "Enter",
+  tab: "Tab",
+  esc: "Escape",
+  space: " ",
+  up: "ArrowUp",
+  down: "ArrowDown",
+  left: "ArrowLeft",
+  right: "ArrowRight",
+  home: "Home",
+  end: "End",
+  page_up: "PageUp",
+  page_down: "PageDown"
+}
+const KEYED = '[data-hibiki-on*="keydown."]'
+const HOTKEYED = '[data-hibiki-on*="@window"]'
+const ISLAND = '[data-controller~="hibiki"]'
+
+// A key press that is a gesture: not part of an IME composition (Safari
+// reports the Enter that ends one only as keyCode 229), not a held key's
+// repeat, and not Chrome's keyless autofill event.
+const heard = (event) =>
+  typeof event.key === "string" &&
+  !event.isComposing &&
+  event.keyCode !== 229 &&
+  !event.repeat
+
+// Where a plain key is text, or moves within it.
+const NOT_TEXT = new Set([
+  "checkbox", "radio", "file", "button", "submit", "reset", "image", "range", "color"
+])
+const entering = (target) =>
+  !!target.closest?.('textarea, select, [contenteditable]:not([contenteditable="false"])') ||
+  (target.localName === "input" && !NOT_TEXT.has(target.type))
+
+// The action of the control's first key token of this scope ("" or
+// "window") that the event matches. Modifiers match exactly, and Alt
+// matches nothing: on macOS it changes the character the key reports.
+// `typing` is a window key pressed in a text field, where only Escape and
+// ctrl or meta combinations are not the field's own.
+function keyAction(control, event, scope, typing = false) {
+  const pressed = event.key.length === 1 ? event.key.toLowerCase() : event.key
+  for (const token of (control.dataset.hibikiOn ?? "").split(/\s+/)) {
+    if (!token.startsWith("keydown.")) continue
+    const [bound, action] = token.slice(8).split("->")
+    const [combo, at = ""] = bound.split("@")
+    if (at !== scope) continue
+    const modifiers = combo.split("+")
+    const name = modifiers.pop()
+    if ((KEYS[name] ?? (name.length === 1 ? name : null)) !== pressed) continue
+    const ctrl = modifiers.includes("ctrl")
+    const meta = modifiers.includes("meta")
+    if (typing && !ctrl && !meta && name !== "esc") continue
+    if (
+      event.ctrlKey === ctrl &&
+      event.metaKey === meta &&
+      event.shiftKey === modifiers.includes("shift") &&
+      !event.altKey
+    ) {
+      return action
+    }
+  }
+}
+
+// What focus return may land on inside a surviving ancestor.
+const FOCUSABLE =
+  'a[href], button:not(:disabled), input:not(:disabled):not([type="hidden"]), ' +
+  'select:not(:disabled), textarea:not(:disabled), [tabindex]:not([tabindex="-1"])'
+
+// Key events a window binding answered, so a second island declaring the
+// same key still fires where a key taken by anything else is left alone.
+const hotkeyed = new WeakSet()
+
+function applyProps(element) {
+  const text = element.getAttribute("data-hibiki-props")
+  let wanted
+  try {
+    wanted = JSON.parse(text)
+  } catch {
+    return
+  }
+  if (!wanted || typeof wanted !== "object") return
+  const fresh = appliedProps.get(element) !== text
+  for (const [name, [type, policy]] of Object.entries(PROPS)) {
+    const value = wanted[name]
+    if (typeof value !== type || (type === "number" && !Number.isFinite(value))) continue
+    if (policy === "always" || fresh) element[name] = value
+  }
+  appliedProps.set(element, text)
+}
+
 // The generic controller: adds the data-hibiki-* wire protocol on top of
 // the base's plumbing.
 export default class HibikiController extends ChannelController {
@@ -607,6 +775,12 @@ export default class HibikiController extends ChannelController {
     // rather than from the middle of it.
     this.prepareTransport()
 
+    // First paint, so before the subscription: a property is right while
+    // the island is still connecting, and stays right if it never does.
+    for (const site of this.element.querySelectorAll("[data-hibiki-props]")) {
+      applyProps(site)
+    }
+
     // Root-scoped delegation (bound to the island, not document): controls
     // inside server-replaced fragments keep working with no rebinding.
     // Set up synchronously so disconnect can always tear them down.
@@ -615,12 +789,29 @@ export default class HibikiController extends ChannelController {
       this.element.addEventListener(type, handler)
       return [type, handler]
     })
+    // 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)
+    this.element.addEventListener("keydown", keydown)
+    this.listeners.push(["keydown", keydown])
+    // On the window only while the island has a window key; see scan().
+    this.hotkeys = (event) => this.hotkey(event)
 
     // Debounce bookkeeping: a WeakMap keyed by control (so detached
-    // elements don't pin memory) plus a flat set of live timeouts, which is
-    // what disconnect can actually iterate.
+    // elements don't pin memory) plus the live timeouts with what each
+    // will run, which is what disconnect and flush can actually iterate.
+    // `unsent` is the text those timeouts have yet to send, by field.
     this.timers = new WeakMap()
-    this.pending = new Set()
+    this.pending = new Map()
+    this.unsent = new Map()
+    // The focus sites seen at the last scan, each with the control whose
+    // gesture opened it, when one did; a site not among them is new.
+    // Seeded now, so a render landing in the connect window finds the
+    // 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)
+    }
 
     // `visible` is not a DOM event, so it needs its own observer beside the
     // delegated listeners. Always on, never a pluggable module: an
@@ -639,11 +830,12 @@ export default class HibikiController extends ChannelController {
       }
     })
 
-    // Re-scan at the two points a fragment can be swapped under us, rather
+    // Re-scan at the points a fragment can be swapped under us, rather
     // than blanket-observing the document: a MutationObserver over the page
     // is a real per-mutation cost paid by every app on it.
     this.streamRender = (event) => {
       const render = event.detail.render
+      const arrival = this.arrival()
       event.detail.render = async (streamElement) => {
         await render(streamElement)
         // The Turbo transport's paint. Counting it here is what lets an ack
@@ -652,14 +844,28 @@ export default class HibikiController extends ChannelController {
         // — which at worst settles an already-acked trip a few ms early,
         // never one that has not been acked at all.
         this.renders++
-        this.scanSentinels()
+        this.scan(arrival)
       }
     }
     document.addEventListener("turbo:before-stream-render", this.streamRender)
+    // A refresh stream morphs the page after its own render has returned,
+    // so the wrapper above scans too early for it; turbo:render follows
+    // the morph.
+    // It is nobody's own render, so it brings no focus, but it can
+    // take the focused element away like any other.
+    this.pageBefore = () => {
+      this.paging = { trail: this.trail() }
+    }
+    this.pageRender = () => {
+      this.scan(this.paging)
+      this.paging = undefined
+    }
+    document.addEventListener("turbo:before-render", this.pageBefore)
+    document.addEventListener("turbo:render", this.pageRender)
 
     await this.openSubscription()
     if (this.aborted) return
-    this.scanSentinels()
+    this.scan()
   }
 
   disconnect() {
@@ -668,8 +874,13 @@ export default class HibikiController extends ChannelController {
       this.element.removeEventListener(type, handler)
     }
     document.removeEventListener("turbo:before-stream-render", this.streamRender)
-    for (const id of this.pending) clearTimeout(id)
+    document.removeEventListener("turbo:before-render", this.pageBefore)
+    document.removeEventListener("turbo:render", this.pageRender)
+    window.removeEventListener("keydown", this.hotkeys)
+    for (const id of this.pending.keys()) clearTimeout(id)
     this.pending.clear()
+    this.unsent.clear()
+    this.marks.clear()
     this.observer.disconnect()
     super.disconnect()
   }
@@ -677,21 +888,179 @@ export default class HibikiController extends ChannelController {
   // The other swap point: hibiki's own transmit transport. A held swap
   // hands back a promise; the replacement sentinel exists only after it.
   received(data) {
+    const arrival = this.arrival()
     const swapped = super.received(data)
     if (!data.html) return
-    if (swapped?.then) swapped.then(() => this.scanSentinels())
-    else this.scanSentinels()
+    if (swapped?.then) swapped.then(() => this.scan(arrival))
+    else this.scan(arrival)
+  }
+
+  // What is only knowable as a render arrives: whether it answers this
+  // tab's action, the control that action came from (the motion module
+  // forgets it once a held render lands), and where focus was.
+  arrival() {
+    return { own: this.own(), control: this.lastControl, trail: this.trail() }
+  }
+
+  // The focused element, when it is this island's, with the ids from it
+  // upward, nearest first, and its caret.
+  trail() {
+    const element = document.activeElement
+    if (!element || element === this.element || element.closest?.(ISLAND) !== this.element) return
+    const ids = []
+    for (let node = element; node !== this.element; node = node.parentElement) {
+      if (node.id) ids.push(node.id)
+    }
+    if (this.element.id) ids.push(this.element.id)
+    return { element, ids, self: Boolean(element.id), start: element.selectionStart, end: element.selectionEnd }
   }
 
-  // Observe every `visible->` sentinel this island owns. observe() is a
-  // no-op for an element already being observed, so re-scanning is cheap
-  // and cannot double-fire a sentinel that merely stayed put.
-  scanSentinels() {
-    for (const control of this.element.querySelectorAll('[data-hibiki-on*="visible->"]')) {
-      if (control.closest('[data-controller~="hibiki"]') === this.element) {
-        this.observer.observe(control)
+  // Give focus back after a render removed the element that had it; the
+  // header has the rule. `opener` is the control behind a focus site the
+  // same render closed. Left alone when focus has gone somewhere since.
+  refocus({ element, ids, self, start, end }, opener) {
+    if (element.isConnected) return
+    const active = document.activeElement
+    if ((active && active !== document.body && active.isConnected) || !this.element.isConnected) return
+    const found = (id) => {
+      const survivor = document.getElementById(id)
+      return survivor && this.element.contains(survivor) ? survivor : null
+    }
+    const index = ids.findIndex(found)
+    if (self && index === 0) {
+      const twin = found(ids[0])
+      twin.focus()
+      if (start != null && document.activeElement === twin) twin.setSelectionRange?.(start, end)
+      return
+    }
+    const candidates = [opener && this.twin(opener)]
+    if (index === (self ? 1 : 0)) candidates.push(...found(ids[index]).querySelectorAll(FOCUSABLE))
+    for (const control of candidates) {
+      control?.focus()
+      if (control && document.activeElement === control) return
+    }
+  }
+
+  // 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 }) {
+    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
+        )
+    return twin?.closest(ISLAND) === this.element ? twin : null
+  }
+
+  // What a render leaves for the client to finish: put back unsent text,
+  // then in one walk of the island assign every prop site's properties,
+  // observe every `visible->` sentinel this island owns, listen on the
+  // window while a window key is declared, and settle focus: on the first
+  // focus site the render brought when it was this tab's `own`, else back
+  // to a control when the render removed the focused element. Focus before
+  // the unsent text, whose caret goes only to the focused field. observe()
+  // is a no-op for an element already being observed, so re-scanning is
+  // cheap and cannot double-fire a sentinel that merely stayed put; adding
+  // 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.
+  scan({ own = false, control, trail } = {}) {
+    const found = this.element.querySelectorAll(
+      `[data-hibiki-on*="visible->"], [data-hibiki-props], [data-hibiki-focus], ${HOTKEYED}`
+    )
+    let hotkeys = this.element.matches(HOTKEYED)
+    // A site is the one seen before when it is that element or, after a
+    // replace, carries its id; it keeps the opener either way.
+    const seen = new Map()
+    for (const [was, opener] of this.marks) if (was.id) seen.set(was.id, opener)
+    const marks = new Map()
+    const ids = new Set()
+    let site
+    for (const element of found) {
+      if (element.hasAttribute("data-hibiki-focus") && element.closest(ISLAND) === this.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
       }
+      hotkeys ||= element.dataset.hibikiOn?.includes("@window")
+      if (element.hasAttribute("data-hibiki-props")) applyProps(element)
+      if (
+        element.dataset.hibikiOn?.includes("visible->") &&
+        element.closest('[data-controller~="hibiki"]') === this.element
+      ) {
+        this.observer.observe(element)
+      }
+    }
+    if (hotkeys) window.addEventListener("keydown", this.hotkeys)
+    else window.removeEventListener("keydown", this.hotkeys)
+    // The opener of a site this render closed, for the focus it leaves.
+    let opener
+    for (const [was, its] of this.marks) {
+      if (its && !marks.has(was) && !ids.has(was.id)) opener = its
     }
+    this.marks = marks
+    // Not from a field with unsent input: the visitor is typing there.
+    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 })
+      }
+      const take = () => {
+        site.focus()
+        if (site.dataset.hibikiFocus === "select") site.select?.()
+      }
+      take()
+      // Turbo hands focus back to the id that had it before a stream, one
+      // frame after appending it, which is just after this. Take it again.
+      const id = trail?.element.id
+      if (id) {
+        setTimeout(() => {
+          if (site.isConnected && document.activeElement?.id === id) take()
+        }, 0)
+      }
+    } else if (trail) {
+      this.refocus(trail, opener)
+    }
+    if (this.unsent.size) this.restoreUnsent()
+  }
+
+  // A key pressed inside the island: the nearest control up from the
+  // target whose key token matches. Not forward()'s nearest control, since
+  // a field wired for `input` sits inside the form that takes Escape. A
+  // key something else took (a nested island, the page's script) is left.
+  key(event) {
+    if (event.defaultPrevented || !heard(event)) return
+    let control = event.target.closest?.(KEYED)
+    while (control && this.element.contains(control)) {
+      const action = control.closest(ISLAND) === this.element && keyAction(control, event, "")
+      if (action) return this.press(control, event, action)
+      control = control.parentElement?.closest(KEYED)
+    }
+  }
+
+  // A key pressed anywhere: the island's first enabled control declaring
+  // it `@window`, the root included. One an inside control answered has
+  // its default prevented, and so is not heard here.
+  hotkey(event) {
+    if ((event.defaultPrevented && !hotkeyed.has(event)) || !heard(event)) return
+    const typing = entering(event.target)
+    for (const control of [this.element, ...this.element.querySelectorAll(HOTKEYED)]) {
+      if (control.closest(ISLAND) !== this.element || control.matches(":disabled")) continue
+      const action = keyAction(control, event, "window", typing)
+      if (!action) continue
+      hotkeyed.add(event)
+      return this.press(control, event, action)
+    }
+  }
+
+  // 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.
+  press(control, event, action) {
+    if ("hibikiFallback" in control.dataset && this.state !== "ready") return
+    event.preventDefault()
+    this.run(control, event, action)
   }
 
   // DOM → server: forward a control's event as a channel action.
@@ -711,8 +1080,11 @@ export default class HibikiController extends ChannelController {
       .split(/\s+/)
       .find((t) => t.startsWith(`${event.type}->`))
     if (!token) return
-    const action = token.slice(event.type.length + 2)
+    this.run(control, event, token.slice(event.type.length + 2))
+  }
 
+  // From a control's matched token to the wire.
+  run(control, event, action) {
     // A fallback control's native behavior IS the degraded path: unless
     // the island is `ready`, stand aside — no perform, no queueing — and
     // the browser follows the href or submits the form to its own
@@ -742,8 +1114,48 @@ export default class HibikiController extends ChannelController {
     // keystroke that started the timer.
     const wait = Number(control.dataset.hibikiDebounce)
     const fire = () => this.send(control, event, action)
-    if (wait > 0) this.debounce(control, action, wait, fire)
-    else fire()
+    if (wait > 0) {
+      const field = event.target
+      if (event.type !== "keydown" && typed(field)) {
+        this.unsent.set(field, {
+          value: field.value,
+          start: field.selectionStart,
+          end: field.selectionEnd
+        })
+      }
+      this.debounce(control, action, wait, () => {
+        fire()
+        // Sent: from here the server's value for the field wins again.
+        if (!this.timers.get(control)?.size) this.unsent.delete(field)
+      })
+    } else {
+      this.flush()
+      fire()
+    }
+  }
+
+  // A render drew these fields without the text typed since their last
+  // send. A morph kept the element; a replace swapped in another with the
+  // same id (the pending send still reads the detached one, whose value is
+  // intact). The selection is the one the last keystroke left, restored
+  // because assigning a value moves the caret to the end.
+  restoreUnsent() {
+    for (const [field, { value, start, end }] of this.unsent) {
+      const live = field.isConnected ? field : field.id && document.getElementById(field.id)
+      if (!live || !typed(live) || live.value === value) continue
+      live.value = value
+      if (start != null && live === document.activeElement) live.setSelectionRange(start, end)
+    }
+  }
+
+  // Run every pending debounce now, oldest first.
+  flush() {
+    const runs = [...this.pending]
+    this.pending.clear()
+    for (const [id, run] of runs) {
+      clearTimeout(id)
+      run()
+    }
   }
 
   send(control, event, action) {
@@ -800,13 +1212,14 @@ export default class HibikiController extends ChannelController {
       clearTimeout(previous)
       this.pending.delete(previous)
     }
-    const id = setTimeout(() => {
+    const run = () => {
       byAction.delete(action)
       this.pending.delete(id)
       fire()
-    }, wait)
+    }
+    const id = setTimeout(run, wait)
     byAction.set(action, id)
-    this.pending.add(id)
+    this.pending.set(id, run)
   }
 }
 

data/lib/hibiki/rails/dom_props.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Hibiki
+  module Rails
+    # The DOM properties Helpers#props may set, and their wire form. The
+    # client keeps the same list (PROPS in hibiki.js) and ignores anything
+    # outside it, so a fragment can never reach innerHTML or an event
+    # handler. Add a property in both places.
+    module DomProps
+      # Ruby key => [wire name, type].
+      ALLOWED = {
+        indeterminate: ["indeterminate", :boolean],
+        scroll_top: ["scrollTop", :number],
+        scroll_left: ["scrollLeft", :number]
+      }.freeze
+
+      # One name/value as its wire pair, or nil when there is nothing to
+      # send. A boolean is always sent, false included: a morph keeps the
+      # element, so an omitted false would leave the property set.
+      def self.pair(name, value)
+        wire, type = ALLOWED.fetch(name.to_sym) do
+          raise ArgumentError,
+                "DOM property #{name.inspect} must be one of #{ALLOWED.keys.join(', ')}"
+        end
+        return [wire, value ? true : false] if type == :boolean
+        return if value.nil?
+        return [wire, value] if value.is_a?(Numeric) && value.to_f.finite?
+
+        raise ArgumentError, "DOM property #{name} must be a finite number, got #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/hibiki/rails/helpers.rb

@@ -4,6 +4,9 @@ require "cgi/escape"
 require "json"
 require "securerandom"
 
+require_relative "dom_props"
+require_relative "keys"
+
 module Hibiki
   module Rails
     # Opt-in helpers that stamp the packaged client's attribute protocol
@@ -44,9 +47,8 @@ module Hibiki
 
       # Event and action names share the hibiki_on attribute, which is a
       # whitespace-separated token list — a name carrying a space or an
-      # arrow would silently change what the client dispatches. The dot is
-      # allowed so a future event qualifier (keydown.enter) needs no second
-      # grammar change.
+      # arrow would silently change what the client dispatches. Key events
+      # (keydown.enter) have their own grammar; see Keys.
       EVENT_NAME = /\A[a-z][a-z0-9_.-]*\z/i
 
       # Per-keystroke round trips are the failure mode #on exists to avoid,
@@ -101,6 +103,13 @@ module Hibiki
         name
       end
 
+      # The left side of a token. Keys validates a key event, and anything
+      # else that asks for a scope.
+      def self.event(name)
+        name = name.to_s
+        name.match?(Keys::EVENT) || name.include?("@") ? Keys.token(name) : event_name(name)
+      end
+
       # The island root: one channel subscription per island, identified by
       # a per-page-load cid (each tab is its own graph). `channel` is the
       # channel class or its name as a string.
@@ -123,8 +132,7 @@ module Hibiki
       # override `channel` or `cid` through this hash.
       def hibiki_island(channel, cid:, params: nil)
         channel_name = channel.is_a?(Class) ? channel.name : channel.to_s
-        data = { controller: "hibiki", hibiki_channel_value: channel_name,
-                 hibiki_cid_value: cid }
+        data = { controller: "hibiki", hibiki_channel_value: channel_name, hibiki_cid_value: cid }
         data[:hibiki_params_value] = JSON.generate(params) unless params.nil?
         { data: }
       end
@@ -167,6 +175,13 @@ module Hibiki
       #
       #   on(:load_more, event: %i[click visible], with: { shown: rows.size })
       #
+      # A key is `keydown.<key>`, heard while focus is inside the element,
+      # or `keydown.<key>@window`, heard anywhere on the page while the
+      # element is rendered. Modifiers go in front; Keys lists both:
+      #
+      #   on(:cancel, event: "keydown.esc")
+      #   on(:new_row, event: ["click", "keydown.ctrl+n@window"])
+      #
       # `with:` is a hash sent as the action's payload. The client adds
       # event-derived data on top: a changed control contributes
       # `{ name => value }` — a checkbox its checked state, a multi-select
@@ -204,7 +219,7 @@ module Hibiki
       def on(action, event: :click, with: nil, debounce: nil, confirm: nil, reset: nil,
              fallback: nil)
         action = Helpers.event_name(action)
-        events = Array(event).map { Helpers.event_name(it) }
+        events = Array(event).map { Helpers.event(it) }
         debounce = DEFAULT_INPUT_DEBOUNCE if debounce.nil? && events.include?("input")
         tokens = events.map { "#{it}->#{action}" }.join(" ")
         { data: { hibiki_on: tokens }
@@ -230,6 +245,46 @@ module Hibiki
       # Phlex form of #reactive: `span(**reactive_attrs(:doubled)) { "0" }`.
       def reactive_attrs(name) = { data: { hibiki_value: Helpers.value_name(name) } }
 
+      # DOM properties for this element — state that has no HTML attribute,
+      # so no fragment can carry it. The client assigns them when the island
+      # connects and after every render.
+      #
+      #   tag.input type: "checkbox", **props(indeterminate: some_selected)
+      #   tag.div class: "list", **props(scroll_top: 0, key: query)
+      #
+      #   indeterminate:  true/false. Assigned after every render, so the
+      #                   server's value wins over a click.
+      #   scroll_top:, scroll_left:  pixels, nil to leave alone. Assigned to
+      #                   a new element, and again only when this helper's
+      #                   output changes — the visitor's own scrolling is
+      #                   kept across unrelated renders.
+      #   key:            any JSON value, sent only to change the output:
+      #                   `scroll_top: 0, key: query` scrolls back to the top
+      #                   each time the query changes.
+      #
+      # The element must be inside an island. Returns a `{ data: }` hash
+      # like #on; two splats of one key do not merge, so on an element that
+      # has both: `**on(:select_all, event: :change).deep_merge(props(...))`.
+      def props(key: nil, **properties)
+        wanted = properties.filter_map { |name, value| DomProps.pair(name, value) }.to_h
+        return { data: {} } if wanted.empty?
+
+        wanted["key"] = key unless key.nil?
+        { data: { hibiki_props: JSON.generate(wanted) } }
+      end
+
+      # Put the cursor in this element when a render opens it:
+      #
+      #   tag.input name: "title", value: form.title, **focus(select: true)
+      #
+      # The client focuses it once, on the render that brings it, and only
+      # when that render answers this tab's own action; another visitor's
+      # save never moves the cursor. `select: true` also selects its text.
+      # An element in the page's first HTML is not focused: that is the
+      # `autofocus` attribute's job. Returns a `{ data: }` hash, merged like
+      # #props: `**on(:set_field, event: :input).deep_merge(focus)`.
+      def focus(select: false) = { data: { hibiki_focus: select ? "select" : "true" } }
+
       private
 
       # #island's preconditions: a block, an ActionView receiver, a channel

data/lib/hibiki/rails/keys.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Hibiki
+  module Rails
+    # The key events Helpers#on may name, and their wire form:
+    # `keydown.[<modifier>+]*<key>[@window]`. The client keeps the same key
+    # list (KEYS in hibiki.js) and matches nothing outside it. Add a key in
+    # both places.
+    module Keys
+      # Named keys, Stimulus's spellings. Single letters and digits are
+      # keys too.
+      NAMES = %w[enter tab esc space up down left right home end page_up page_down].freeze
+      CHARACTER = /\A[a-z0-9]\z/
+
+      # In wire order. No alt: on macOS Option changes the character the
+      # key reports, so `alt+s` would never match there.
+      MODIFIERS = %w[ctrl meta shift].freeze
+
+      SCOPES = %w[window].freeze
+
+      # What Helpers#on hands over: `keydown` alone or followed by a
+      # qualifier, not a longer name that starts with it.
+      EVENT = /\Akeydown(?![a-z0-9_-])/i
+
+      # One `keydown...` event as its canonical token: lowercase, modifiers
+      # in MODIFIERS order.
+      def self.token(event)
+        event = event.to_s.downcase
+        unless EVENT.match?(event)
+          raise ArgumentError, "event #{event.inspect}: only a keydown.<key> event takes a scope"
+        end
+
+        combo, scope = event.split("@", 2)
+        *modifiers, key = combo.delete_prefix("keydown").delete_prefix(".").split("+")
+        key!(event, key)
+        modifiers!(event, key, modifiers)
+        scope!(event, scope)
+        ["keydown.#{[*(MODIFIERS & modifiers), key].join('+')}", scope].compact.join("@")
+      end
+
+      def self.key!(event, key)
+        if key.nil?
+          raise ArgumentError,
+                "#{event.inspect} names no key; write keydown.<key>, or use :input for typed text"
+        end
+        return if NAMES.include?(key) || CHARACTER.match?(key)
+
+        raise ArgumentError,
+              "key #{key.inspect} in #{event.inspect} must be a letter, a digit, or one of #{NAMES.join(', ')}"
+      end
+
+      def self.modifiers!(event, key, modifiers)
+        unknown = modifiers - MODIFIERS
+        unless unknown.empty?
+          raise ArgumentError,
+                "modifier #{unknown.first.inspect} in #{event.inspect} must be one of #{MODIFIERS.join(', ')}"
+        end
+        return unless modifiers.include?("shift") && key.match?(/\A\d\z/)
+
+        # Shift turns a digit into punctuation, so the key would never match.
+        raise ArgumentError, "#{event.inspect}: shift cannot be combined with a digit"
+      end
+
+      def self.scope!(event, scope)
+        return if scope.nil? || SCOPES.include?(scope)
+
+        raise ArgumentError, "scope #{scope.inspect} in #{event.inspect} must be #{SCOPES.join(', ')}"
+      end
+
+      private_class_method :key!, :modifiers!, :scope!
+    end
+  end
+end

data/lib/hibiki/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Hibiki
   module Rails
-    VERSION = "0.15.0"
+    VERSION = "0.17.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hibiki_rails
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - planetaska
@@ -183,9 +183,11 @@ files:
 - lib/hibiki/rails/broadcasts.rb
 - lib/hibiki/rails/channel.rb
 - lib/hibiki/rails/debounce.rb
+- lib/hibiki/rails/dom_props.rb
 - lib/hibiki/rails/engine.rb
 - lib/hibiki/rails/graph_actor.rb
 - lib/hibiki/rails/helpers.rb
+- lib/hibiki/rails/keys.rb
 - lib/hibiki/rails/nested_actions.rb
 - lib/hibiki/rails/reactive_form.rb
 - lib/hibiki/rails/registry.rb