hibiki_rails 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b163c0d20f8fcca4839e8cfcae98316cae9b8d01bd4f81eece18e02a9ae39be
-  data.tar.gz: bf61ca3db0cd1ad769a7f5ee931a06362124841e4d62ba0bd55856d892511b85
+  metadata.gz: d7bfeee9d4e44c3404ac6582548e0bdb46ae139cfa26eec2c71b7d8b95c40c77
+  data.tar.gz: ab0505b42c8450e0a8014f94c380ed2f3e995448a9cf8cfc8ed16f4eb450d524
 SHA512:
-  metadata.gz: 317d9a267de7853075cc35f089099f5f5fc89060afa2db3afd298d8b955f5dd441fdd90d1d2780be561280c6a9e514f827901112ede534a6dd82f06cf763e9a3
-  data.tar.gz: 2623fa07782f9d5264592c4bc3e977cb229967b1810f1b05c121bd16dbbc546335c420fd855751ae0dda71e6a148b648623a010344dbec21283f764f76d9f813
+  metadata.gz: 6c032ed168913d5c4cc0a56afdf8b6a58cd89ad61581acfda17fc6e2a8030f0ebe4a81f35e0f4ec58691b79df2e6831be4bfa75f4d850db2ff334d9504a30bbb
+  data.tar.gz: 79144e77c309815099be858e605ddad09c6a655ebc2b66f3e20c68fdfe6cf0dceca295bc418304ea6fb0865dfda732a9a4704018029fd8f52a39f21148e15532

data/CHANGELOG.md

@@ -4,6 +4,108 @@ 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
+
+**Motion for generated pages, and the `hibiki-rails/motion` module.** A
+re-rendered fragment is merged into the page in place, so a removed element
+was gone before the browser could draw it leaving. The new opt-in module
+holds a render while a marked element's transitions finish: mark an element
+`data-motion` (it needs an id), give it a transition, and `import
+"hibiki-rails/motion"` once beside your controllers. The module writes
+`data-motion-leaving` on each marked element the incoming fragment lacks,
+waits for its transitions, then lets the render run; it brackets an inserted
+marked element with `data-motion-entering` so a clip can be scoped to the
+motion. `data-motion="own"` animates the leave only when the gesture that
+removed the element came from inside it, read from the island's own trip
+records. Renders queue in arrival order; a hidden tab waits for nothing;
+every wait races a one-second ceiling. Both transports hold. This is a
+client change: the four `data-motion*` attributes are public, unlike the
+private `data-hibiki-*` ones. Docs: [Motion].
+
+- The scaffold emits it by default under `--css=daisyui` and `tailwind`:
+  the inline create card and the row's edit form slide open and shut
+  (`hbk-slide` / `hbk-slide-body`), and a row you destroy slides out to the
+  left before the list closes the gap (`hbk-slide-x` / `hbk-slide-x-body`,
+  marked `own`). The row's display markup gains an id-bearing `contents`
+  wrapper, because the merge pairs an anonymous `div` with the edit wrapper
+  and rewrites it in place, and `@starting-style` fires only on a real
+  insertion; under motion the row's card and card-body are one element, so
+  the add-on generators' anchors still hold.
+- `app/assets/stylesheets/hibiki_motion.css`, once per app beside the busy
+  sheet and wired the same four ways: slide, slide-x, fade, fly, scale and
+  blur as Tailwind `@utility` rules (the utilities layer sits above daisyUI's
+  components, and a single utility on the element still wins), with duration
+  and easing tuned there. Needs Tailwind 4.1. The generator appends
+  `import "hibiki-rails/motion"` to `app/javascript/application.js` once
+  and prints a `motion` notice when it cannot.
+- `--skip-motion` on both scaffold commands leaves every trace out.
+  `--css=none` never emits it: the transitions are Tailwind utilities, and
+  its output is byte-identical to a `--skip-motion` run.
+- Packaging: the engine pins `hibiki-rails/motion`; the npm package exports
+  `./motion`. The module imports `"hibiki-rails"` by its bare name, which
+  the pin and the package self-reference both resolve.
+
+### Changed
+
+- `hibiki.js` gains three seams for the module: an exported `islandFor(element)`,
+  the island's `lastControl` (set in `trackControl`, kept past the trip's
+  settle), and a `hibiki:before-render` event dispatched from the island root
+  before a transmit swap, with `event.detail.render` replaceable the way
+  Turbo's `turbo:before-stream-render` is. `received` returns the render's
+  result: `undefined` for a synchronous swap, a promise for a held one. An ack
+  settles its trip even while a render is held.
+- `CssVariant` gains two tokens, `row_card` and `contents`.
+
+[Motion]: https://planetaska.github.io/hibiki/motion/
+
 ## 0.14.0 — 2026-09-07
 
 ### Changed

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

@@ -0,0 +1,164 @@
+// hibiki-rails/motion — enter/leave motion for server-rendered swaps.
+//
+// Opt-in: `import "hibiki-rails/motion"` once, beside the controllers. This
+// is the PUBLIC motion contract (unlike the client's private data-hibiki-*):
+//
+//   app-written    data-motion          the element animates its leave
+//                  data-motion="own"    …only when the gesture that removed
+//                                       it came from inside it — a destroyed
+//                                       row, not one that paged or filtered
+//                                       away. Marked elements need an id: both
+//                                       sets below are keyed by id, as the
+//                                       transports' swaps are.
+//   written here   data-motion-leaving  on a marked element the incoming
+//                                       render lacks, until its transitions end
+//                  data-motion-entering on a marked element the render inserted,
+//                                       until its first transitions end
+//
+// Addressed to app CSS — Tailwind's `starting:` / `data-motion-leaving:` /
+// `in-data-motion-leaving:` variants, or plain attribute selectors. The
+// enter needs no help: @starting-style is the from-state on a real
+// insertion. The exit does, because a morph drops the node before any CSS
+// could run — so a render that would remove a marked element is HELD until
+// the element's transitions finish. Renders queue in arrival order, one
+// chain per document, so a hold never lets a later render overtake it. Only
+// the outermost marked element of a subtree moves, in either phase.
+//
+// One requestAnimationFrame per wait, because transitions exist only after
+// the next style pass. A hidden document waits for nothing (its frames never
+// come), and every wait races a one-second ceiling, so a tab hidden mid-hold
+// cannot wedge the queue. Nothing here reads layout: a forced style read
+// between a morph's insert and its class sync defeats @starting-style.
+import { islandFor } from "hibiki-rails"
+
+const CEILING = 1000
+
+// Turbo stream actions that remove content. morph rides replace/update;
+// append/prepend/before/after/refresh remove nothing.
+const REMOVING = new Set(["replace", "update", "remove"])
+
+const marked = (root) => [...root.querySelectorAll("[data-motion]")]
+const hasMarks = (root) => root.querySelector("[data-motion]") !== null
+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()) {
+    if (record.control && element.contains(record.control)) return true
+  }
+  return Boolean(island.lastControl) && element.contains(island.lastControl)
+}
+
+const animates = (element, island) =>
+  element.getAttribute("data-motion") !== "own" || ownsGesture(island, element)
+
+// Marked elements under `target` (and `target` itself when the action
+// replaces it) whose id the incoming content lacks.
+const leavingFrom = (target, includeSelf, incoming, island) => {
+  const candidates =
+    includeSelf && target.hasAttribute("data-motion") ? [target, ...marked(target)] : marked(target)
+  return candidates.filter(
+    (element) => element.id && !incoming.has(element.id) && animates(element, island)
+  )
+}
+
+const outermost = (elements) =>
+  elements.filter((element) => !elements.some((other) => other !== element && other.contains(element)))
+
+// Resolves once the element's own transitions have run. Element-only, not
+// {subtree: true}: a spinner inside a leaving row is an infinite animation.
+const settled = async (element) => {
+  if (document.visibilityState === "hidden") return
+  await new Promise(requestAnimationFrame)
+  await Promise.allSettled((element.getAnimations?.() ?? []).map((animation) => animation.finished))
+}
+
+const finished = (elements) => {
+  let timer
+  const ceiling = new Promise((resolve) => {
+    timer = setTimeout(resolve, CEILING)
+  })
+  return Promise.race([Promise.all(elements.map(settled)), ceiling]).finally(() => clearTimeout(timer))
+}
+
+// One chain per document. A failed render must not close it.
+let queue = Promise.resolve()
+const enqueue = (job) => (queue = queue.catch(() => {}).then(job))
+
+// The hold. `plan` runs when the render's turn comes (earlier renders may
+// have changed the DOM) and returns { leaving, islands }; `render` is what
+// the transport would have run at once.
+const held = (plan, render) =>
+  enqueue(async () => {
+    const { leaving: candidates, islands } = plan()
+    const leaving = outermost(candidates)
+    const before = idsOf(document)
+    for (const element of leaving) element.setAttribute("data-motion-leaving", "")
+    if (leaving.length) await finished(leaving)
+    try {
+      await render()
+    } finally {
+      // A render that kept the element after all, and the gesture consumed.
+      for (const element of leaving) {
+        if (element.isConnected) element.removeAttribute("data-motion-leaving")
+      }
+      for (const island of islands) island.lastControl = null
+    }
+    const entering = outermost(marked(document).filter((element) => element.id && !before.has(element.id)))
+    for (const element of entering) {
+      element.setAttribute("data-motion-entering", "")
+      finished([element]).then(() => element.removeAttribute("data-motion-entering"))
+    }
+  })
+
+// Turbo streams. Registered at import, so this wrapper sits INSIDE the
+// islands' own render wrappers (theirs count the paint) and the hold ends
+// before they count it. The gate keeps unmarked pages at two querySelectors;
+// a hold is pending only while a marked element is still in the document,
+// so any render arriving during one sees marks and queues behind it.
+document.addEventListener("turbo:before-stream-render", (event) => {
+  const stream = event.detail.newStream
+  if (!stream?.templateElement) return
+  const content = stream.templateElement.content
+  if (!hasMarks(document) && !hasMarks(content)) return
+
+  const render = event.detail.render
+  event.detail.render = (streamElement) =>
+    held(() => {
+      const plan = { leaving: [], islands: new Set() }
+      // A refresh stream has no target: targetElements throws.
+      if (stream.action === "refresh") return plan
+      const incoming = idsOf(content)
+      for (const target of stream.targetElements) {
+        const island = islandFor(target)
+        if (island) plan.islands.add(island)
+        if (REMOVING.has(stream.action)) {
+          plan.leaving.push(...leavingFrom(target, stream.action !== "update", incoming, island))
+        }
+      }
+      return plan
+    }, () => render(streamElement))
+})
+
+// The transmit transport: the client's own swap, by root id. A root id
+// always survives a by-id swap, so only descendants can leave.
+document.addEventListener("hibiki:before-render", (event) => {
+  const { island, content, render } = event.detail
+  if (!hasMarks(document) && !hasMarks(content)) return
+
+  event.detail.render = () =>
+    held(() => ({
+      islands: new Set([island]),
+      leaving: [...content.children].flatMap((fragment) => {
+        const target = document.getElementById(fragment.id)
+        return target ? leavingFrom(target, false, idsOf(fragment), island) : []
+      })
+    }), render)
+})

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:
@@ -71,6 +75,14 @@
 // and per-button feedback needs no server state. Content is stale during
 // a round trip, never absent.
 //
+// Motion is the one PUBLIC data-* contract, and it lives in the opt-in
+// module `hibiki-rails/motion`: an app marks an element `data-motion` (or
+// `data-motion="own"`), the module stamps `data-motion-leaving` /
+// `data-motion-entering` around a swap and holds the render while a
+// leaving element's transitions run. Its header carries the rules; this
+// file only gives it two seams — `islandFor` and the `hibiki:before-render`
+// event the transmit swap dispatches (the same shape Turbo gives streams).
+//
 // The left side of `->` is a hibiki event name: click, change, input,
 // and submit are delegated DOM listeners; `visible` is a pseudo-event
 // backed by an IntersectionObserver (the element entering the viewport).
@@ -131,6 +143,20 @@ let consumer
 // island pins nothing even if disconnect never ran.
 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)
+// 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)
+    if (island) return island
+  }
+  return undefined
+}
+
 // camelCase Stimulus method name → snake_case Ruby channel action.
 const underscore = (name) => name.replace(/([A-Z])/g, "_$1").toLowerCase()
 
@@ -228,6 +254,7 @@ export class ChannelController extends Controller {
     this.seq = 0
     this.renders = 0
     this.busy = new Map()
+    this.lastControl = null
     this.queued = []
     this.setState("connecting")
   }
@@ -348,7 +375,11 @@ export class ChannelController extends Controller {
   // A depth counter, not a boolean: typing while a page loads is one island
   // with two actions outstanding. No requestAnimationFrame anywhere — it
   // never fires in a background tab, which is exactly when a stuck
-  // indicator goes unnoticed.
+  // indicator goes unnoticed. (The motion module is the one place a frame
+  // is waited for, and it waits for nothing in a hidden document.) An ack
+  // settles a trip even while that module is holding the render: the flag
+  // means the server has not answered, and a hold is motion after the
+  // answer.
 
   beginBusy(seq) {
     const record = {
@@ -373,6 +404,13 @@ export class ChannelController extends Controller {
   // has none); controls outside it — the search field — need the removal
   // in settle().
   trackControl(seq, control) {
+    // 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 —
+    // 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
     record.control = control
@@ -453,7 +491,13 @@ export class ChannelController extends Controller {
   //
   // { url } — mirror graph state into the address bar (transmit_url).
   //
-  // { html } — a fragment: swap it in by its root id.
+  // { html } — a fragment: swap it in by its root id. The swap is holdable
+  // the way Turbo's is: `hibiki:before-render` bubbles from the island
+  // first (detail { island, content, render }), and a listener may replace
+  // detail.render with one that waits — the motion module does, to let a
+  // leaving element's transition finish. Returns whatever that render
+  // returns: undefined when the swap ran synchronously, a promise when it
+  // was held, which is what a subclass reading the DOM afterwards awaits.
   //
   // Anything else is not ours to interpret. Subclasses may override, but
   // should call super (or handle `value`) to keep reactive values live.
@@ -469,9 +513,18 @@ export class ChannelController extends Controller {
     if (!html) return
     const template = document.createElement("template")
     template.innerHTML = html
-    for (const fragment of [...template.content.children]) {
-      document.getElementById(fragment.id)?.replaceWith(fragment)
+    const fragments = [...template.content.children]
+    const render = () => {
+      for (const fragment of fragments) {
+        document.getElementById(fragment.id)?.replaceWith(fragment)
+      }
     }
+    const event = new CustomEvent("hibiki:before-render", {
+      bubbles: true,
+      detail: { island: this, content: template.content, render }
+    })
+    this.element.dispatchEvent(event)
+    return event.detail.render()
   }
 
   // replaceState, never pushState: the URL is a mirror of graph state, not
@@ -533,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 {
@@ -562,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.
@@ -594,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) => {
@@ -607,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() {
@@ -623,25 +721,40 @@ 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()
     super.disconnect()
   }
 
-  // The other swap point: hibiki's own transmit transport.
+  // 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) {
-    super.received(data)
-    if (data.html) 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)
+    const swapped = super.received(data)
+    if (!data.html) return
+    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)
       }
     }
   }
@@ -771,10 +884,8 @@ export { HibikiController }
 // element (a structural mistake, hence the warn; the offline case stays
 // quiet because it is expected weather).
 export function performOn(element, action, payload = {}) {
-  for (let node = element; node; node = node.parentElement) {
-    const island = islands.get(node)
-    if (island) return island.perform(action, payload)
-  }
+  const island = islandFor(element)
+  if (island) return island.perform(action, payload)
   console.warn("hibiki: performOn found no island containing", element)
   return undefined
 }

data/config/importmap.rb

@@ -6,3 +6,5 @@
 # — both are part of the Rails 8 default stack. The client takes Action
 # Cable from turbo-rails' consumer, so no "@rails/actioncable" pin is needed.
 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"

data/lib/generators/hibiki/rails/css_variant.rb

@@ -57,6 +57,11 @@ module Hibiki
           card: "card bg-base-100 shadow-sm",
           card_body: "card-body",
           card_actions: "card-actions justify-end",
+          # The row under motion: card and body as ONE element, so the sliding
+          # wrapper above it adds no depth to the row's content. And the
+          # display wrapper, a swap unit with no box of its own.
+          row_card: "card bg-base-100 shadow-sm card-body",
+          contents: "contents",
           toggle: "toggle",
           toggle_sm: "toggle toggle-sm",
           btn: "btn",
@@ -149,6 +154,7 @@ module Hibiki
           card: "rounded-lg border border-gray-200 bg-white shadow-sm",
           card_body: "p-6 space-y-2",
           card_actions: "flex flex-wrap justify-end gap-2 pt-4",
+          row_card: "rounded-lg border border-gray-200 bg-white shadow-sm p-6 space-y-2",
           toggle: CHECKBOX,
           toggle_sm: CHECKBOX,
           btn: SECONDARY_BUTTON,

data/lib/generators/hibiki/rails/scaffold/USAGE

@@ -25,8 +25,11 @@ Example:
         app/controllers/books_controller.rb
         app/views/books/*
         app/assets/stylesheets/hibiki_busy.css
+        app/assets/stylesheets/hibiki_motion.css
     And add to config/routes.rb:
         resources :books
+    And to app/javascript/application.js:
+        import "hibiki-rails/motion"
 
     Restart the server afterwards if it is running — app/forms and
     app/queries are new.
@@ -34,3 +37,7 @@ Example:
     Pass --phlex to emit Phlex components under app/views/books/*.rb instead of
     ERB templates. The view layer is the only thing it changes; it needs the
     phlex-rails gem and `bin/rails g phlex:install`.
+
+    Rows and inline forms slide open and shut. Pass --skip-motion to leave
+    that out: no motion stylesheet, no import, no marks in the views.
+    --css=none never emits it either.

data/lib/generators/hibiki/rails/scaffold/scaffold_generator.rb

@@ -46,6 +46,8 @@ module Hibiki
                                    desc: "Omit the search box and the LIKE terms behind it"
         class_option :skip_create, type: :boolean, default: false,
                                    desc: "Omit the inline create form — New always navigates"
+        class_option :skip_motion, type: :boolean, default: false,
+                                   desc: "Omit the enter/leave motion — no hibiki_motion.css, no marks"
         class_option :page_size, type: :numeric, default: 20, desc: "Rows per page"
         class_option :phlex, type: :boolean, default: false,
                              desc: "Emit Phlex components under app/views instead of ERB templates"

data/lib/generators/hibiki/rails/scaffold_controller/USAGE

@@ -24,11 +24,17 @@ Example:
         app/controllers/books_controller.rb
         app/views/books/*
         app/assets/stylesheets/hibiki_busy.css
+        app/assets/stylesheets/hibiki_motion.css
     And modify:
         app/models/book.rb
         app/models/author.rb   # each model a belongs_to points at
+        app/javascript/application.js   # imports hibiki-rails/motion
         config/routes.rb
 
     Pass --phlex to emit Phlex components under app/views/books/*.rb instead of
     ERB templates. The view layer is the only thing it changes; it needs the
     phlex-rails gem and `bin/rails g phlex:install`.
+
+    Rows and inline forms slide open and shut. Pass --skip-motion to leave
+    that out: no motion stylesheet, no import, no marks in the views.
+    --css=none never emits it either.