hibiki_rails 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce497d3d19ee46dede8bb9973f3a408e8b724f588ee2ebce3a4c0a0e5aa998f1
-  data.tar.gz: 1eea58578f6a73f3617a8f717cc1407023d741c1bbd1fb68f534b1fe135a4caa
+  metadata.gz: d7bfeee9d4e44c3404ac6582548e0bdb46ae139cfa26eec2c71b7d8b95c40c77
+  data.tar.gz: ab0505b42c8450e0a8014f94c380ed2f3e995448a9cf8cfc8ed16f4eb450d524
 SHA512:
-  metadata.gz: fd67705cbe7db3a1eb1ddcd5dd914e7f8377f01070d564f3dca40a96f205833ef0a442f3a74bc68a8928d6577461a8bc83427c0e0117c711d3fd5733fa478b9e
-  data.tar.gz: eefeee042142381f1e2f1f2dba0d49d2884db32409a029d08215a9479aefce564bc7e03333c23b525ade2dc37fc3111a89ebbabd52fed6adf450bfe19c9f63bf
+  metadata.gz: 6c032ed168913d5c4cc0a56afdf8b6a58cd89ad61581acfda17fc6e2a8030f0ebe4a81f35e0f4ec58691b79df2e6831be4bfa75f4d850db2ff334d9504a30bbb
+  data.tar.gz: 79144e77c309815099be858e605ddad09c6a655ebc2b66f3e20c68fdfe6cf0dceca295bc418304ea6fb0865dfda732a9a4704018029fd8f52a39f21148e15532

data/CHANGELOG.md

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

@@ -57,6 +57,10 @@
 //                 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
 //
 // The client writes the protocol's other half at runtime — read-only to
 // app code, addressed to app CSS:
@@ -142,7 +146,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)
@@ -401,7 +407,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
@@ -578,6 +586,40 @@ 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()
+
+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 +649,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.
@@ -639,7 +687,7 @@ 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) => {
@@ -652,14 +700,19 @@ 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()
       }
     }
     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.
+    this.pageRender = () => this.scan()
+    document.addEventListener("turbo:render", this.pageRender)
 
     await this.openSubscription()
     if (this.aborted) return
-    this.scanSentinels()
+    this.scan()
   }
 
   disconnect() {
@@ -668,6 +721,7 @@ export default class HibikiController extends ChannelController {
       this.element.removeEventListener(type, handler)
     }
     document.removeEventListener("turbo:before-stream-render", this.streamRender)
+    document.removeEventListener("turbo:render", this.pageRender)
     for (const id of this.pending) clearTimeout(id)
     this.pending.clear()
     this.observer.disconnect()
@@ -679,17 +733,28 @@ export default class HibikiController extends ChannelController {
   received(data) {
     const swapped = super.received(data)
     if (!data.html) return
-    if (swapped?.then) swapped.then(() => this.scanSentinels())
-    else this.scanSentinels()
-  }
-
-  // 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)
+    if (swapped?.then) swapped.then(() => this.scan())
+    else this.scan()
+  }
+
+  // What a render leaves for the client to finish, in one walk of the
+  // island: assign every prop site's properties, and 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. Props need no ownership
+  // check: assigning one twice, from a nested island and its parent, lands
+  // the same value.
+  scan() {
+    const found = this.element.querySelectorAll(
+      '[data-hibiki-on*="visible->"], [data-hibiki-props]'
+    )
+    for (const element of found) {
+      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)
       }
     }
   }

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,8 @@ require "cgi/escape"
 require "json"
 require "securerandom"
 
+require_relative "dom_props"
+
 module Hibiki
   module Rails
     # Opt-in helpers that stamp the packaged client's attribute protocol
@@ -230,6 +232,34 @@ 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
+
       private
 
       # #island's preconditions: a block, an ActionView receiver, a channel

data/lib/hibiki/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Hibiki
   module Rails
-    VERSION = "0.15.0"
+    VERSION = "0.16.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.16.0
 platform: ruby
 authors:
 - planetaska
@@ -183,6 +183,7 @@ 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