hibiki_rails 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62779990991fb78726bc665b7ad93a93dabee5b49892fa99f6486ad42dc41679
-  data.tar.gz: 9cac4fa0143ab6b5f031d9ea0d9d213a1505108e1aa06894773d59f8594b6023
+  metadata.gz: 3b21e4afc4b4e74e30f3c32286a1a75b30052e55145d25210bb3cecfbb3bc24c
+  data.tar.gz: 5c26612918d2b81c3a6a6a134710331ba656b25e9441856627ddf6b3ee093e71
 SHA512:
-  metadata.gz: bf6340bdef27fd3c320fff3a8d7fb90967d883783a965e61a90ccbae5d536b7bdcdfcba536d827089d3b389af1c07439ff7031ee11792c95a579752c8b235706
-  data.tar.gz: a9337451b21ecd955590683648f8a6d824bafa703ce096937387cff0fafaedf5ee5a959089558f7bf02037b00d39e40fd9fcab1bf3176cd976dcd1b957ab6443
+  metadata.gz: acf106a0cda97184c5bd9a988bab71efb8be65c76e1f5b08785f96795d7a9dc21f67a5511a9a10ffa7b5fee49d498891ce7516b926eec1868d76820fd7c42c48
+  data.tar.gz: 5e8d7b8aba5eaf643e5c6f82dcde5c824bd8f9eb1594163dd872bc0a304a6b37a796069385ec8fdc78e8bfe48dd7d9345d4f60a20b77fe3f72760d02e9b0157e

data/CHANGELOG.md

@@ -0,0 +1,234 @@
+# Changelog
+
+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.4.0 — 2026-08-03
+
+### Added
+
+**Loading and connection state, stamped by the client.** The first growth of the
+`data-hibiki-*` protocol since 0.3.0, and the first attributes in it that no Ruby
+helper emits — the client writes them at runtime and app CSS reads them:
+
+```
+island root      data-hibiki-busy      present while an action is in flight
+                 aria-busy="true"      the same fact, for assistive tech
+                 data-hibiki-state     connecting | ready | offline | stalled
+firing control   data-hibiki-busy      on the control that started it
+```
+
+Everything an app wants out of that is a descendant selector —
+`[data-hibiki-busy] .spinner { display: inline-block }` — so per-row and
+per-button feedback needs no server state and no `{#if loading}` branch. The
+Ruby surface is unchanged: no new option on `on`, `hibiki_island` or `reactive`.
+
+**Actions are acknowledged once their batch has run**, and the ack is what clears
+the indicator. It cannot be "clear on the next render": the core's equality gate
+(hibiki 0.2.0) lets an ordinary action produce zero bytes — paging to the page
+you are already on, a search that does not change the query, a destroy of a row
+another tab already deleted — so a render-based rule hangs forever on gestures
+users make all the time. The ack sits in an `ensure`, so a raising action stops
+the spinner too, and a subscription that has gone away acks `dropped: true` from
+the cable thread instead, which is what lets the client tell "late" from "never".
+
+A page running the 0.3.0 client sends no sequence number and gets no ack, so
+nothing about this reaches an app that has not upgraded both halves.
+
+**Actions performed before the subscription confirms are queued, not dropped.**
+ActionCable's `Subscription#perform` silently returns false on a socket that is
+not open yet, and on the Turbo-broadcast path that window is about three
+serialised round trips — a click in it used to vanish. The queue covers the first
+connect window only: after a reconnect the server rebuilds the graph with default
+state, so replaying intent formed against the old one is worse than dropping it,
+and the island reads `offline` for the whole gap instead.
+
+Three class properties on `ChannelController` are the entire tuning surface —
+`busyDelay` (150 ms before a trip is worth mentioning), `busyGrace` (60 ms for a
+broadcast still in flight after its ack), `busyCeiling` (10 s before a trip is
+declared stalled rather than cleared silently). Deliberately not Stimulus values
+and not helper options; an app that wants different numbers subclasses and
+re-registers.
+
+The scaffold generators wire five sites to all of this — the counts line, the
+pagination bar, the infinite-scroll sentinel, the destroy button and the
+inline-edit Save — through a generated `_busy.html.erb` the app owns.
+
+**`hibiki:rails:scaffold` and `hibiki:rails:scaffold_controller`** — a reactive
+CRUD resource generated the way `rails g scaffold` generates a plain one.
+
+```sh
+bin/rails g hibiki:rails:scaffold Book title:string author:references
+bin/rails g hibiki:rails:scaffold_controller Book   # an existing model
+```
+
+The generated index is live: search, filter, sort and pagination are signal
+state rather than page loads, rows edit in place, and a write from anywhere —
+another tab, another user, the plain controller, a console — repaints every open
+list. Everything is derived from the model's schema (columns, types, `belongs_to`
+reflections, validators) or from the same `NAME field:type` argument list Rails'
+own scaffold takes.
+
+Stock `rails g scaffold` is untouched; these live under their own namespace.
+
+Live per-field validation is derived only from rules the form can actually
+evaluate before a round trip: presence, length, and numericality bounds that
+carry no `allow_nil:`/`allow_blank:` exemption for the value in hand. A
+validator gated on `if:`, `unless:` or `on:` depends on the record rather than
+the field, so it contributes nothing live — it still runs at commit and still
+lands in `#errors`, which the same per-field slots mirror. The clauses are
+generated once; add validators and re-run `scaffold_controller` to pick them up.
+
+**Field order is yours, and choosing it costs nothing.** With no field list the
+columns follow the schema, which for an app built from `schema.rb` means
+alphabetical. Passing them explicitly picks the order — and against a model that
+already exists the generator still reads that model for everything else, so the
+live clauses, a number field's `min:`/`max:` and a `belongs_to`'s display label
+all survive the choice:
+
+```sh
+bin/rails g hibiki:rails:scaffold_controller Author name:string bio:text age:integer
+```
+
+A field the model has no column for is still generated, from the argument list
+alone, and named in the post-install output — it may be a column whose migration
+is still to come, and a silently missing field is the worse failure.
+
+**A unique index with no uniqueness validator is called out.** A database
+constraint is not a validator, and the generated form can only mirror what the
+model checks — so without one, a duplicate raises `ActiveRecord::RecordNotUnique`
+on the graph thread instead of showing a field error, and the round trip
+completes having saved nothing. The generator names the column and the exact
+`validates` line, for single and composite indexes alike.
+
+Options: `--css=daisyui|tailwind|none` (detected when absent),
+`--infinite-scroll`, `--skip-pagination`, `--skip-search`, `--page-size=N`,
+`--skip-routes`.
+
+Three notes on what it does to an app you already have.
+
+**The model is modified** — one `delegate` per `belongs_to`, plus the
+`after_commit` broadcast the whole thing hangs off.
+
+**So is each model a `belongs_to` points at.** It gains the `has_many` half
+Rails' own scaffold never writes (without it the generated destroy button raises
+`InvalidForeignKey`) and a ping of its own, because a row prints the parent's
+label rather than its id — rename an author and every open books index would
+otherwise keep the old name. `dependent:` follows the association: `:destroy`
+when it is required, `:nullify` when it is `optional: true`. That ping is
+collection-grained, so an open *show* page keeps the old label until reload.
+
+Both injections are idempotent and announced, and anything you already declared
+is left alone — including a `dependent:` you chose yourself.
+
+And **restart the server afterwards**: `app/forms/` is likely new, and Rails
+computes autoload paths from the `app/*` glob at boot.
+
+### Fixed
+
+**The model injection missed every namespaced model.** Thor anchors
+`inject_into_class` on the class name as the file spells it, and the generator
+passed the demodulized one — so `app/models/admin/book.rb`, which Rails writes as
+`class Admin::Book < ApplicationRecord`, never matched. Silently: Thor rewrote
+the file byte-identical and the generator reported a modification. The delegate
+never landed, so the show page raised on arrival.
+
+## 0.3.0 — 2026-07-28
+
+### Security
+
+**Channel lifecycle methods were client-invocable on Rails 7.1 and 7.2.**
+Upgrade if you run hibiki_rails on either. Rails 8.x apps were never affected.
+
+ActionCable builds a channel's client-invocable actions from the public methods
+the class adds. The gem subtracted its lifecycle hooks through ActionCable's
+`internal_methods` hook — but **that hook only exists on Rails 8.x**; on 7.1 and
+7.2 `action_methods` never consults it, so the override was silently inert and
+the hooks stayed exposed.
+
+Reachable by any client that can open a subscription, against its own
+connection's graph. There is no cross-connection or cross-user data exposure;
+the impact is resource exhaustion:
+
+- `perform("build_graph")` — exposed on **every** affected app, since
+  `#build_graph` is always public. It re-runs the graph build outside
+  `Hibiki.root`, so the effects it creates are unowned and the dispose on
+  unsubscribe never reaches them, while the previous root is still held. Each
+  call leaks; repeated calls grow memory without bound.
+- `perform("subscribed")` — exposed only where an app defined `#subscribed`
+  public, which the ActiveRecord guide's own `after_commit` example did until
+  this release. It allocates a second `GraphActor` — a new **thread** — and
+  overwrites the reference to the first, so the original is never stopped.
+  Repeated calls exhaust the process's threads.
+
+Fixed by subtracting in `action_methods` itself, which works on every supported
+version:
+
+```ruby
+HIDDEN_ACTIONS = %w[build_graph subscribed unsubscribed].freeze
+def action_methods = super - HIDDEN_ACTIONS
+```
+
+No application change is required. Writing `#subscribed` and `#unsubscribed`
+private is still the better habit, because it also protects the methods this
+list does not know about — the guides now show them that way.
+
+### Added
+
+- `on(action, event:)` takes an **event list**, so one element can answer
+  several events: `on(:load_more, event: %i[click visible])`.
+- **`input`** joins the delegated events, with a per-control **`debounce:`**.
+  `:input` carries 250 ms unless told otherwise (`debounce: 0` opts out); the
+  value is stamped into the markup rather than being an invisible client
+  default.
+- **`visible`**, a pseudo-event backed by an `IntersectionObserver`, so a
+  load-more control can double as an infinite-scroll sentinel. It fires once
+  per observation and re-attaches to the replacement element after each
+  fragment swap.
+- **`confirm:`** on `on(...)` — a `window.confirm` gate. `data-turbo-confirm`
+  does nothing on a hibiki control, since it is not a Turbo-driven form.
+- **`reset: false`** on a submit, to keep a form's inputs. The default resets
+  them synchronously, before the server has replied, which is right for an
+  "add" form and destroys an edit form's contents on a failed commit.
+- **Subscribe params**: `hibiki_island(channel, cid:, params: { record_id: })`
+  reach the channel as `params[:key]`, which is how a channel learns which
+  record its page is about. They are client-supplied and untrusted — use one
+  only to look up a record inside a scope the channel chooses, and never
+  interpolate one into a streamable name. They cannot override `channel` or
+  `cid`.
+- The client has its own test suite (`spec/js`, vitest + happy-dom) and a CI
+  job, plus a pinned Rails 8.1 matrix leg.
+
+### Changed
+
+- **A changed checkbox now sends its checked state as a boolean**, and a
+  multi-select sends an array of its selected values. Previously both sent
+  `control.value` — the value *attribute* — so checking and unchecking a
+  checkbox produced byte-identical payloads. **This is a payload shape
+  change**: an action reading a `change` payload for a checkbox now receives
+  `true`/`false` rather than `"1"`. The form-submit path is unaffected.
+- `transmit_value` is **equality-gated**: an effect re-runs whenever any signal
+  it read changed, so a bumped version token used to re-send every reactive
+  value's text even when byte-identical. The block still runs unconditionally,
+  so dependency collection is unchanged — only the transmit is skipped. If you
+  render a reactive placeholder *inside* a broadcast-replaced fragment, render
+  it with its current value: the swap resets the DOM text and the gate now
+  suppresses the re-send that used to heal it.
+- Each graph job runs inside `Rails.application.executor`, so
+  `CurrentAttributes` are reset between jobs, autoloads are safe off the main
+  thread, and each job gets its own query cache.
+- Graph-thread errors are **logged** in development and test.
+  `ActiveSupport::ErrorReporter` has no subscribers by default, so in a stock
+  app these previously vanished entirely — no line, no stack, just a fragment
+  that stopped updating. Production behaviour is unchanged.
+
+## 0.2.0 — 2026-07-21
+
+- Reactive values: `reactive` / `reactive_attrs` / `transmit_value`, matched
+  document-wide so a value can render outside the island that computes it.
+- `Components::` namespacing for the Phlex generator.
+
+## 0.1.0 — 2026-07-18
+
+Initial release.

data/README.md

@@ -59,6 +59,40 @@ bin/rails g hibiki:rails:stimulus counter static_pages
 
 This creates a minimal working reactive component in the given view path.
 
+### Generating a whole CRUD resource
+
+For a full reactive resource — a live index with search, filtering, sorting and
+pagination, plus edit-in-place — use the scaffold generators:
+
+```sh
+# Model, migration, route and the reactive resource, like rails g scaffold
+bin/rails g hibiki:rails:scaffold Book title:string author:references
+
+# Or, for a model you already have — the schema is read for you
+bin/rails g hibiki:rails:scaffold_controller Book
+
+# Same, but you pick the field order; everything else still comes from the model
+bin/rails g hibiki:rails:scaffold_controller Book title:string author:references
+```
+
+Your plain `rails g scaffold` is untouched. The generated markup is styled to
+match your app (DaisyUI, Tailwind, or unstyled — detected automatically, or
+forced with `--css=`). Run `bin/rails g hibiki:rails:scaffold --help` for the
+rest of the options.
+
+Listing the fields yourself only chooses their order and which ones appear — the
+model still answers everything else, so the live validation, a number field's
+`min:`/`max:` and a `belongs_to`'s display label all survive the choice.
+
+Your models are edited, not just read: the one being scaffolded gains the
+`after_commit` broadcast that makes writes from anywhere reach an open list, and
+each model a `belongs_to` points at gains the `has_many` half plus a ping of its
+own, so renaming a parent repaints the lists that print its name. Both are
+idempotent, announced, and leave anything you already declared alone.
+
+Restart the server afterwards: `app/forms/` is new, and Rails works out its
+autoload paths at boot.
+
 ### Render the reactive component
 
 The generated components are just Rails partials (or Phlex components, if you used the Phlex generator), so you can render one anywhere like any other partial:
@@ -73,11 +107,42 @@ Congratulations! Now you have your first reactive component!
 
 Documentation site: <https://planetaska.github.io/hibiki/rails-introduction/>
 
+Release notes and upgrade advice: [CHANGELOG.md](CHANGELOG.md). **If you run Rails 7.1 or 7.2, read the 0.3.0 entry** — it fixes channel lifecycle methods that were client-invocable on those versions.
+
 ## Development
 
 ```
-bundle exec rake   # specs + rubocop (same as CI)
+bundle exec rake   # Ruby specs + rubocop
+bun install && bun run test   # the client's own specs
 ```
 
-The spec suite boots a minimal inline Rails app (`spec/support/dummy_app.rb`).
+Both are what CI runs. The Ruby suite boots a minimal inline Rails app (`spec/support/dummy_app.rb`); the JS suite (`spec/js/`) drives the real Stimulus controller in happy-dom against a stubbed Action Cable consumer.
+
+The gem and the npm package are **released in lockstep**: `app/assets/javascripts/hibiki.js` is the single copy — the engine puts it on the asset path and `package.json` points `main`/`module`/`exports` at it — so importmap and bundler apps must never be able to resolve different client code. Bump `lib/hibiki/rails/version.rb` and `package.json` in the same commit, and publish both. The version table lives in [the JS client docs](https://planetaska.github.io/hibiki/the-js-client/).
+
+## Contributing
+
+Bug reports and pull requests are welcome at <https://github.com/planetaska/hibiki-rails>.
+
+A few things that make a change easier to accept:
+
+- **`bundle exec rake` and `bun run test` both green.** They are what CI runs, and the client half is easy to forget — most changes here touch one side, but the wire protocol is shared by both.
+- **A regression spec first** for anything that was a bug. `spec/js/` covers the client, `spec/generators/` the generated output.
+- **Generated code follows `rubocop-rails-omakase`**, which is what a stock Rails app lints with — not this gem's own style. The templates are written to satisfy the app's linter, not ours.
+- **The `data-hibiki-*` attributes are a private contract** between the Ruby helpers and the vendored JS, and the two halves ship in one version — so a change to either side belongs in one commit with the other. Two of them, `data-hibiki-busy` and `data-hibiki-state`, are written by the client rather than by a helper, and apps select on them from CSS; those need a CHANGELOG entry even when no Ruby changes.
+
+### Running against a checkout
+
+The gem side needs nothing special: point an app's Gemfile at your clone with `gem "hibiki_rails", path: "../hibiki-rails"`.
+
+The npm side has one trap. `bun link` from an app resolves the linked package's own imports from the **symlink's realpath**, not from the app — so `hibiki.js` looks for `@rails/actioncable` inside your checkout rather than inside the app that linked it, and if the checkout has no `node_modules` the import fails at build time with nothing pointing at the cause.
+
+```sh
+cd hibiki-rails && bun install   # before linking, not after
+```
+
+This affects only development against a clone. Anyone installing the published package resolves normally and never sees it.
+
+## License
 
+[MIT](LICENSE.txt)