hibiki_rails 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73beec766683bf4a92c8bebcb19b62e58686f50f68e3b16f0a958c2d0d155de1
-  data.tar.gz: 8ce7469020b298e4e94b7fa7daef8bafb5443a891fc90163339750f400aa9228
+  metadata.gz: 62779990991fb78726bc665b7ad93a93dabee5b49892fa99f6486ad42dc41679
+  data.tar.gz: 9cac4fa0143ab6b5f031d9ea0d9d213a1505108e1aa06894773d59f8594b6023
 SHA512:
-  metadata.gz: 3f5fc7f1fe7a4f72047d86e054612e9144e5815cc1a96d2fa87737573f9701ce2b2c6d713992822ee6cd90cae7b6cae5b4647bb6001b3f863dee2f38354ec131
-  data.tar.gz: 67f0275c2e22bd291fc8940f84a99775c9e1acac5e3542ffc68edd9c896e26f9e786270904bfa75029e78c872984560fdeca6499532f4128c4f65a1c420ab7b2
+  metadata.gz: bf6340bdef27fd3c320fff3a8d7fb90967d883783a965e61a90ccbae5d536b7bdcdfcba536d827089d3b389af1c07439ff7031ee11792c95a579752c8b235706
+  data.tar.gz: a9337451b21ecd955590683648f8a6d824bafa703ce096937387cff0fafaedf5ee5a959089558f7bf02037b00d39e40fd9fcab1bf3176cd976dcd1b957ab6443

data/README.md

@@ -1,246 +1,77 @@
 # hibiki_rails
 
 Rails glue for [hibiki](https://github.com/planetaska/hibiki):
-connection-scoped signal graphs over ActionCable, pushing re-rendered HTML
-to the page — either through Turbo Streams, or over the channel's own
-subscription to the gem's packaged client (see "The packaged client").
+connection-scoped signal graphs over ActionCable, pushing re-rendered HTML to the page — either through Turbo Streams, or over the channel's own subscription to the gem's packaged client (see [The JS client](https://planetaska.github.io/hibiki/the-js-client/)).
 
 ```
 cable action arrives → mutate signals → effects render partials →
 Turbo Streams broadcast → Turbo morphs the DOM
 ```
 
-A graph lives per cable connection (in practice: per browser tab), built
-when the channel subscribes and disposed when it unsubscribes. Effects
-subscribe to whatever signals they read; when an action writes a signal,
-exactly the affected effects re-render and broadcast.
+A graph lives per cable connection (in practice: per browser tab), built when the channel subscribes and disposed when it unsubscribes. Effects subscribe to whatever signals they read; when an action writes a signal, exactly the affected effects re-render and broadcast.
 
-Incubating inside the hibiki repo while the core gem is pre-release; will
-be extracted to its own repository once hibiki 0.1.0 ships and this API
-stabilizes. Rails >= 8.0 (what's tested), Ruby >= 3.4.
+Supports Rails >= 7.1, Ruby >= 3.4.
 
-## Usage
+## Rails quick start
+
+### Installation
+
+**Step 1** - Install the gem (`hibiki_rails` depends on the core `hibiki` gem)
 
 ```ruby
-class CounterChannel < ApplicationCable::Channel
-  include Hibiki::Rails::Channel
-
-  # Runs once on the graph's own thread, inside Hibiki.root.
-  def build_graph
-    @count = Hibiki::State.new(0)
-    @step  = Hibiki::State.new(1)
-    doubled = Hibiki::Derived.new { @count.value * 2 }
-
-    Hibiki::Effect.new do
-      broadcast_replace target: "count", partial: "counter/count",
-                        locals: { count: @count.value, doubled: doubled.value }
-    end
-    Hibiki::Effect.new do
-      broadcast_replace target: "step", partial: "counter/step",
-                        locals: { step: @step.value }
-    end
-  end
-
-  # Actions are plain methods that touch signals directly: each one runs
-  # on the graph thread inside one Hibiki.batch, so N writes still mean
-  # one re-run per affected effect.
-  def increment = @count.value += @step.value
-  def burst     = 10.times { @count.value += 1 }
-end
+# Gemfile
+gem "hibiki"
+gem "hibiki_rails"
 ```
 
-The page supplies a per-page-load graph id (`cid`) and listens on the
-matching stream:
+Or `gem install hibiki hibiki_rails`.
 
-```erb
-<div data-controller="counter" data-counter-cid-value="<%= @cid %>">
-  <%= turbo_stream_from "counter", @cid %>
-  <%= render "count", count: 0, doubled: 0 %>  <%# placeholder, see below %>
-  ...
-</div>
-```
+**Step 2** - Run the install generator
 
-with `@cid = SecureRandom.uuid` in the controller action. The channel
-broadcasts to `[channel_name, cid]` — override `stream_name` (and/or
-`cid`) to derive identity differently.
-
-## What the concern does
-
-- `subscribed` — rejects without a `cid` param, then runs `build_graph`
-  inside `Hibiki.root` on a dedicated worker thread (a `GraphActor`).
-  ActionCable dispatches on a thread pool with no per-channel ordering;
-  hibiki's threading model is confinement — so cable threads only enqueue,
-  and the graph lives on exactly one thread.
-- every action — the whole body is posted to that thread wrapped in one
-  `Hibiki.batch`. `rescue_from` still applies (it runs on the graph
-  thread); what it doesn't handle goes to `Rails.error` (source
-  `"hibiki_rails"`).
-- `unsubscribed` — disposes the root (running `on_cleanup` hooks) and
-  stops the worker, draining what was already queued.
-- dev reloading — an Engine hook disposes every live graph before code
-  reloads (stale effects would run old class versions forever); cable
-  clients auto-reconnect and rebuild. Graph state resets on reload, like
-  any remount.
-
-## Broadcast helpers
-
-Available inside effects (all bound to `stream_name`):
-
-- `broadcast_replace(target:, **rendering)` — `partial:`/`locals:`,
-  `html:`, or anything Turbo's renderer accepts.
-- `broadcast_morph(target:, **rendering)` — replace via Turbo 8 morphing
-  (keeps focus/scroll).
-- `broadcast_refresh` — tell the page to refresh itself.
-- `broadcast_refresh_effect(wait: 0.25) { ...read signals... }` — the
-  morph-everything style: tracks whatever the block reads and answers
-  changes with a debounced refresh, one per burst of actions rather than
-  one per action.
-
-## The packaged client
-
-The gem vendors its own JavaScript, turbo-rails-style: the engine puts
-`hibiki.js` on the app's asset path and merges the `"hibiki-rails"` pin into the
-import map, so importmap-rails apps have no install step beyond
-registering the controller — `bin/rails g hibiki:rails:install` does it
-(plus the `Helpers` include below, the `ApplicationCable` boilerplate,
-and the `@rails/actioncable` pin — a stock app has neither until its
-first `rails g channel`), or create the one-line shim yourself:
-
-```js
-// app/javascript/controllers/hibiki_controller.js
-export { default } from "hibiki-rails" // registers as "hibiki" — the helpers hardcode that identifier
+```sh
+bin/rails g hibiki:rails:install
 ```
 
-The registration is a file-backed shim on purpose: importmap apps
-eager-load it from the controllers directory, jsbundling apps get the
-matching import/register pair in `controllers/index.js` (the install
-generator appends it), and because it is derived from a real controller
-file, `bin/rails stimulus:manifest:update` regenerates it instead of
-dropping it.
+The install generator detects whether your app uses an import map:
 
-(jsbundling/vite apps: `npm install hibiki-rails` — the [npm
-package](https://www.npmjs.com/package/hibiki-rails) is the same module the
-engine vendors, and pulls in `@rails/actioncable`; release in lockstep with
-the gem.)
+- For importmap apps, installation is fully automatic — you are done.
+- For apps with a JS bundler (esbuild, vite, bun, ...), also install the companion JS client (published as an npm package) with **one of**:
+  - `npm install hibiki-rails`
+  - `yarn add hibiki-rails`
+  - `bun add hibiki-rails`
+  - or the equivalent for your setup
 
-The client is one generic Stimulus controller that drives any *island*: a
-DOM subtree bound to one channel subscription. Islands are stamped with
-the opt-in `Hibiki::Rails::Helpers` — include it where you want the bare
-names (`ApplicationHelper` for ERB, individual Phlex components); the gem
-never includes it for you:
+### Using the generator
 
-```erb
-<%= tag.div(**hibiki_island(TodosChannel, cid: @cid)) do %>
-  <%= render TodoList.new %>  <%# placeholder; replaced by DOM id %>
-  <%= tag.form(**on(:add, event: :submit)) do %>
-    <input type="text" name="title">
-    <button>add</button>
-  <% end %>
-<% end %>
-```
+You can create reactive components easily with the provided generators.
 
-- `hibiki_island(channel, cid:)` — the island root: one subscription,
-  identified by the page's `cid`.
-- `on(action, event:, with:)` — forward a DOM event (`:click` default,
-  `:change`, `:submit`) as a channel action, with `with:` as its payload.
-  A changed control also sends `{ name => value }`; a submitted form sends
-  its FormData and is reset after performing.
+Create your first reactive component by running:
 
-Transport is the channel's own subscription in both directions: render
-effects call `transmit({ html: })` and the client swaps each fragment in
-by its root DOM id (`Hibiki::Phlex.render_effect` pairs naturally):
+```sh
+# Replace [your_view_path] with your desired view path,
+# e.g. counters, posts, users/profile...
+bin/rails g hibiki:rails:stimulus counter [your_view_path]
 
-```ruby
-def build_graph
-  @list = TodoList.new
-  Hibiki::Phlex.render_effect(@list) { |html| transmit({ html: }) }
-end
+# For example, this creates "counter" component partials
+# inside app/views/static_pages
+bin/rails g hibiki:rails:stimulus counter static_pages
 ```
 
-Because the client registers its `received` callback at subscribe time —
-before the server ever runs `build_graph` — the effects' first transmits
-always land: no Turbo stream, no connected-wait, and the server-rendered
-initial HTML is only a paint-avoidance placeholder. One rule carries over
-from any replace-fragment design: never transmit a fragment containing
-the input the user is currently typing in.
-
-The `data-hibiki-*` attributes the helpers emit are a private contract
-with the vendored JS — they version together; don't hand-write them in
-app code. The protocol itself is Stimulus-free (Stimulus only hosts the
-controller lifecycle), so a hand-rolled client can drive the same
-attributes: `toy-phlex/` in the parent repo does it in ~40 lines. The
-helper interface's shape is inspired by
-[phlex-reactive](https://phlex-reactive.zoolutions.llc)'s `on(...)`
-actions.
-
-## Generators
-
-Each supported shape has a generator that scaffolds it as a *working*
-mini-example — one state, one derived, one action, one effect; run it,
-render the output from any page, click `+1`, watch it live-update — meant
-to be reshaped in place, not filled in from scratch:
+This creates a minimal working reactive component in the given view path.
 
-```sh
-bin/rails g hibiki:rails:install                  # one-time wiring: register line,
-                                                  # Helpers include, ApplicationCable
-                                                  # boilerplate + actioncable pin
-                                                  # (idempotent)
-bin/rails g hibiki:rails:stimulus NAME [VIEW_PATH]  # channel + ChannelController
-                                                    # subclass + view partial
-bin/rails g hibiki:rails:island NAME [VIEW_PATH]    # channel + helpers-stamped view
-                                                    # partial, no per-component JS
-bin/rails g hibiki:rails:phlex NAME                 # channel + Phlex component +
-                                                    # island wrapper (needs hibiki_phlex)
-```
+### Render the reactive component
 
-`VIEW_PATH` is the views directory under `app/views` (defaults to `NAME`);
-the emitted partial is self-contained (`cid` defaults to a per-render
-uuid), so `<%= render "counter/counter" %>` — or `<%= render
-CounterIsland.new %>` for the Phlex shape — is the only line a page needs.
-The `stimulus` shape works with zero wiring; `island` and `phlex` need the
-one-time `hibiki:rails:install` (they print a hint when it's missing).
-Namespaced names work (`admin/counter` pins `static channel` where the
-Stimulus identifier can't infer it). In apps without an importmap
-(jsbundling/vite), where `controllers/index.js` has no eager loader, the
-`stimulus` generator also appends the controller's import/register pair
-to it — the same lines `stimulus:manifest:update` would emit.
-
-## The initial-state pattern (Turbo transport)
-
-Islands on the Turbo-broadcast transport instead (the "Usage" example
-above) have an ordering problem the transmit transport doesn't: the
-graph's effects do their first run inside `subscribed` — usually before
-the page's `turbo_stream_from` subscription has confirmed — so the first
-broadcast would be lost. Fix the ordering on the client with the packaged
-`streamConnected` helper: wait for Turbo to stamp the `connected`
-attribute on the stream source, then subscribe the graph channel.
-
-```js
-// in the Stimulus controller driving the channel
-import { streamConnected } from "hibiki-rails"
-
-async connect() {
-  this.consumer = createConsumer()
-  await streamConnected(this.element.querySelector("turbo-cable-stream-source"))
-  this.subscription = this.consumer.subscriptions.create(
-    { channel: "CounterChannel", cid: this.cidValue }, {}
-  )
-}
+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:
+
+```erb
+<%= render "static_pages/counter" %>
 ```
 
-With that in place the server-rendered initial HTML is only a
-paint-avoidance placeholder — the first broadcast always lands and
-replaces it, so it doesn't have to match the graph's initial state.
+Congratulations! Now you have your first reactive component!
 
-## Error handling layers
+## Documentation
 
-1. `rescue_from` on the channel — handles action errors, on the graph
-   thread.
-2. `Hibiki.error_handler = ->(error, effect) { ... }` — app-level routing
-   for effect errors raised during a flush (the gem does not set this).
-3. The graph worker's per-job rescue — everything unhandled lands in
-   `Rails.error.report(..., source: "hibiki_rails")`. Override per channel
-   via `build_graph_actor` and `GraphActor.new(on_error:)`.
+Documentation site: <https://planetaska.github.io/hibiki/rails-introduction/>
 
 ## Development
 
@@ -248,5 +79,5 @@ replaces it, so it doesn't have to match the graph's initial state.
 bundle exec rake   # specs + rubocop (same as CI)
 ```
 
-The spec suite boots a minimal inline Rails app (`spec/support/dummy_app.rb`);
-the live end-to-end proof app is `spike/` in the parent repo.
+The spec suite boots a minimal inline Rails app (`spec/support/dummy_app.rb`).
+

data/app/assets/javascripts/hibiki.js

@@ -26,7 +26,9 @@
 //
 // Both shapes speak both transports. Transmit: the server's render
 // effects `transmit({ html: })` fragments that are swapped in by their
-// root DOM id; `received` is registered at subscribe time — before the
+// root DOM id, and `transmit_value` messages that update every
+// data-hibiki-value placeholder; `received` is registered at subscribe
+// time — before the
 // server runs build_graph — so the effects' first transmits always land
 // (the server-rendered initial HTML is only a paint-avoidance
 // placeholder). Turbo broadcasts: when the controller's element contains
@@ -44,6 +46,8 @@
 //                 data-hibiki-cid-value="<per-page-load id>"
 //   controls      data-hibiki-on="<event>-><action>"   e.g. "click->increment"
 //                 data-hibiki-with='{"index":3}'       optional JSON payload
+//   value sites   data-hibiki-value="<name>"           reactive-value placeholder;
+//                 the server's transmit_value message updates every match
 //
 // Register the generic controller under the identifier "hibiki" (the
 // helpers hardcode it):
@@ -94,10 +98,26 @@ export class ChannelController extends Controller {
     this.subscription.perform(action, payload)
   }
 
-  // Server → DOM (transmit transport): swap each transmitted fragment in
-  // by its root id. Broadcast-transport channels never transmit, and a
-  // non-html transmit is not ours to interpret. Subclasses may override.
-  received({ html }) {
+  // Server → DOM (transmit transport). Two message shapes:
+  //
+  // { value: { name, text } } — a reactive value (transmit_value): write
+  // the text into every [data-hibiki-value=name] placeholder, document-
+  // wide (a value may render outside its island; names are page-unique).
+  // textContent assignment keeps values text-only and preserves each
+  // site's own tag/classes, so per-placeholder styling survives updates.
+  //
+  // { html } — a fragment: swap it in by its root id.
+  //
+  // Anything else is not ours to interpret. Subclasses may override, but
+  // should call super (or handle `value`) to keep reactive values live.
+  received({ html, value }) {
+    if (value) {
+      const selector = `[data-hibiki-value="${CSS.escape(value.name)}"]`
+      for (const site of document.querySelectorAll(selector)) {
+        site.textContent = value.text
+      }
+      return
+    }
     if (!html) return
     const template = document.createElement("template")
     template.innerHTML = html

data/lib/generators/hibiki/rails/phlex/phlex_generator.rb

@@ -49,7 +49,7 @@ module Hibiki
 
             Render it from any page:
 
-              <%= render #{class_name}Island.new %>
+              <%= render Components::#{class_name}Island.new %>
 
           MSG
           register_hint

data/lib/generators/hibiki/rails/phlex/templates/channel.rb.tt

@@ -8,7 +8,7 @@ class <%= class_name %>Channel < ApplicationCable::Channel
   include Hibiki::Rails::Channel
 
   def build_graph
-    @component = <%= class_name %>.new
+    @component = Components::<%= class_name %>.new
 
     # First run is the dependency-collecting initial render.
     Hibiki::Phlex.render_effect(@component) { |html| transmit({ html: }) }

data/lib/generators/hibiki/rails/phlex/templates/component.rb.tt

@@ -5,7 +5,7 @@
 # read as ordinary method calls (no .value anywhere), Rerenderable lets
 # the channel's render effect re-render this same instance, and Helpers
 # stamps the client's wire protocol.
-class <%= class_name %> < Phlex::HTML
+class Components::<%= class_name %> < Phlex::HTML
   include Hibiki::Reactive
   include Hibiki::Phlex::Rerenderable
   include Hibiki::Rails::Helpers

data/lib/generators/hibiki/rails/phlex/templates/island_component.rb.tt

@@ -3,15 +3,15 @@
 # The island wrapper: one channel subscription per render, identified by
 # a per-page-load cid. Render from any page:
 #
-#   <%%= render <%= class_name %>Island.new %>
-class <%= class_name %>Island < Phlex::HTML
+#   <%%= render Components::<%= class_name %>Island.new %>
+class Components::<%= class_name %>Island < Phlex::HTML
   include Hibiki::Rails::Helpers
 
   def view_template
     div(**hibiki_island(<%= class_name %>Channel, cid: SecureRandom.uuid)) do
       # A throwaway instance as a paint-avoidance placeholder; the
       # channel's long-lived instance takes over from its first transmit.
-      render <%= class_name %>.new
+      render Components::<%= class_name %>.new
     end
   end
 end

data/lib/hibiki/rails/channel.rb

@@ -92,6 +92,22 @@ module Hibiki
         raise NotImplementedError, "#{self.class} must implement #build_graph"
       end
 
+      # The channel half of a single reactive value (see Helpers#reactive for
+      # the placeholder half): wraps the block in an effect that transmits
+      # `{ value: { name:, text: } }` — the packaged client writes the text
+      # into every `[data-hibiki-value=NAME]` placeholder on the page (part
+      # of the data-hibiki wire contract, versioned with the client). Call
+      # from #build_graph; the block tracks whatever signals it reads (state,
+      # derived, or an expression over several). Values are text, never
+      # markup: the client assigns textContent, so nothing is interpreted as
+      # HTML. Returns the effect, owned by the graph root like any other.
+      def transmit_value(name, &compute)
+        name = Helpers.value_name(name)
+        Hibiki::Effect.new do
+          transmit({ value: { name:, text: compute.call.to_s } })
+        end
+      end
+
       # Per-page-load graph identity, supplied by the page's subscription
       # (each tab is its own graph). Override to derive identity elsewhere.
       def cid = params[:cid]

data/lib/hibiki/rails/helpers.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "cgi/escape"
 require "json"
 
 module Hibiki
@@ -25,7 +26,30 @@ module Hibiki
     # The emitted attribute names are a private contract between these
     # helpers and the gem's JS — they version together; don't hand-write
     # them in app code.
+    #
+    # #reactive is the exception to the splat shape: it returns a complete
+    # placeholder element (`<%= reactive :doubled, 0 %>` in ERB). Phlex
+    # components splat instead: `span(**reactive_attrs(:doubled))`.
     module Helpers
+      # A reactive value's name lands in an attribute selector on both
+      # halves, so keep it to safe characters; the placeholder tag name
+      # lands in raw markup, so allowlist it too.
+      VALUE_NAME = /\A[a-z][a-z0-9_-]*\z/i
+      VALUE_TAG = /\A[a-z][a-z0-9-]*\z/i
+      private_constant :VALUE_NAME, :VALUE_TAG
+
+      # The shared name validator for both halves of a reactive value (the
+      # view-side data-hibiki-value placeholder and the channel's
+      # #transmit_value message).
+      def self.value_name(name)
+        name = name.to_s
+        unless VALUE_NAME.match?(name)
+          raise ArgumentError,
+                "reactive value name #{name.inspect} must match #{VALUE_NAME.inspect}"
+        end
+        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.
@@ -45,6 +69,29 @@ module Hibiki
         data[:hibiki_with] = JSON.generate(with) unless with.nil?
         { data: }
       end
+
+      # Placeholder for a single reactive value: `<%= reactive :doubled, 0 %>`
+      # paints `<span data-hibiki-value="doubled">0</span>`; the channel's
+      # `transmit_value(:doubled) { ... }` keeps it fresh. The same value may
+      # be placed any number of times, anywhere on the page — every
+      # placeholder updates (the client matches document-wide, so a value can
+      # render outside its island too). Names must be page-unique across
+      # channels. Only the placeholder text is server-rendered: each site
+      # keeps its own tag, classes, and attributes across updates.
+      def reactive(name, placeholder = "", tag_name: :span)
+        tag_name = tag_name.to_s
+        unless VALUE_TAG.match?(tag_name)
+          raise ArgumentError,
+                "reactive value tag #{tag_name.inspect} must match #{VALUE_TAG.inspect}"
+        end
+        html = %(<#{tag_name} data-hibiki-value="#{Helpers.value_name(name)}">) +
+               %(#{CGI.escapeHTML(placeholder.to_s)}</#{tag_name}>)
+        html.respond_to?(:html_safe) ? html.html_safe : html
+      end
+
+      # The value's attributes, for stamping the placeholder yourself — the
+      # Phlex form of #reactive: `span(**reactive_attrs(:doubled)) { "0" }`.
+      def reactive_attrs(name) = { data: { hibiki_value: Helpers.value_name(name) } }
     end
   end
 end

data/lib/hibiki/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Hibiki
   module Rails
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hibiki_rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - planetaska