hibiki_rails 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e95a440701dfeb3c02a3f6535b59cc18e51d66569dd76f9d793153f671120edc
-  data.tar.gz: 14869e53518e44f14089c7a1be15c166a51e9f61ff87867cd9fcbb848b20a3dc
+  metadata.gz: 514349fcd04fc813cc4833144b4355c56958e9055dda33aefbdc547517d73bfd
+  data.tar.gz: 1a9729ad926d72f9bdfb1b4411544893f59c3ebb40d2dd552165bed1299218e5
 SHA512:
-  metadata.gz: 3937c28fbcd8ec47e540a2837b6c48d34b4152553037491a576a67b22679d58578c09c4b63ea316390a1a5d5d49e9c37b29fe277dd8150484a881899ee8f1b00
-  data.tar.gz: 88ca77fa4732bf3d08f7b207c57ec457bc601afa7111dda3d4660b51d62a1b305b88c9a98b1801cfdc5a29f2723f8d29f5b617b545cd3c9c952e1b3c9aef8329
+  metadata.gz: eb8e0207e6b1281f7085e7258a9ed189f836b0427ea3172acf3711b118f80f1a0a8fa97474d5f4ff4deaf69ef0bec8d6083f3b09a3ee1178cb836335453f3d76
+  data.tar.gz: 1f4c370144b71c7baea0b3960d69d761b562f6590f281b079f1bf9a26173e7d83c415e262924030e02e4d5bd62876eab7b62c2a12b8a145298ea1d60ff2a5480

data/CHANGELOG.md

@@ -4,6 +4,38 @@ 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.12.0 — 2026-09-06
+
+### Added
+
+**`island` — the ERB block helper for the island root.** One call
+generates the cid, stamps the root with `hibiki_island`, and derives the
+channel's `turbo_stream_from` inside it:
+
+```erb
+<%= island CounterChannel do |cid| %>
+  ...
+<% end %>
+```
+
+- `cid:` defaults to a fresh UUID; the block receives it either way.
+- The stream source is derived from the channel class
+  (`turbo_stream_from channel.channel_name, cid`), so renaming the channel
+  cannot leave a hand-typed streamable behind. `transport: :transmit`
+  leaves it out: for a channel that transmits, or one that overrides
+  `stream_name` and writes its own line in the block. (`:broadcast` is the
+  default; the option is a named value rather than a boolean so it cannot
+  be mistaken for Turbo's own `data-turbo="false"`.)
+- `params:` passes through; `tag_name:` picks the root element; any other
+  keyword lands on it, with a `data:` hash merged beneath the island's own
+  keys.
+- Class-only (`constantize` a dynamic name at the call site) and ERB-only
+  (it needs ActionView's `capture`). Phlex components keep
+  `div(**hibiki_island(...))`, which remains the primitive.
+
+Generators are unchanged: their output keeps the explicit three-line form.
+No client change; the npm release is the lockstep bump.
+
 ## 0.11.0 — 2026-09-05
 
 ### Changed

data/lib/hibiki/rails/helpers.rb

@@ -2,6 +2,7 @@
 
 require "cgi/escape"
 require "json"
+require "securerandom"
 
 module Hibiki
   module Rails
@@ -24,7 +25,8 @@ module Hibiki
     # Both helpers return a `{ data: { ... } }` hash: splat it into Phlex
     # element methods or Rails tag helpers (`tag.div(**hibiki_island(...))`).
     # When the element needs other attributes on the same `data:` key, merge
-    # the hashes yourself (Phlex's `mix` does this).
+    # the hashes yourself (Phlex's `mix` does this). In ERB, #island wraps
+    # the root, the cid, and the Turbo stream source into one block helper.
     #
     # The emitted attribute names are a private contract between these
     # helpers and the gem's JS — they version together; don't hand-write
@@ -53,7 +55,12 @@ module Hibiki
       # the emitted markup instead of being an invisible default.
       DEFAULT_INPUT_DEBOUNCE = 250
 
-      private_constant :VALUE_NAME, :VALUE_TAG, :EVENT_NAME
+      # How an island's channel sends HTML back: Turbo broadcasts to a named
+      # stream (the root needs a stream source inside), or transmit down the
+      # subscription itself (it does not).
+      TRANSPORTS = %i[broadcast transmit].freeze
+
+      private_constant :VALUE_NAME, :VALUE_TAG, :EVENT_NAME, :TRANSPORTS
 
       # The shared name validator for both halves of a reactive value (the
       # view-side data-hibiki-value placeholder and the channel's
@@ -67,6 +74,23 @@ module Hibiki
         name
       end
 
+      # A tag name lands in raw markup, so it is allowlisted wherever a
+      # helper takes one.
+      def self.tag_name(name, of)
+        name = name.to_s
+        raise ArgumentError, "#{of} tag #{name.inspect} must match #{VALUE_TAG.inspect}" unless VALUE_TAG.match?(name)
+
+        name
+      end
+
+      # #island's transport option, allowlisted so a typo names itself.
+      def self.transport(value)
+        return value if TRANSPORTS.include?(value)
+
+        raise ArgumentError,
+              "island transport #{value.inspect} must be one of #{TRANSPORTS.map(&:inspect).join(', ')}"
+      end
+
       # The shared validator for both halves of an `event->action` token.
       def self.event_name(name)
         name = name.to_s
@@ -105,6 +129,33 @@ module Hibiki
         { data: }
       end
 
+      # The ERB spelling of the island root: a fresh cid, the #hibiki_island
+      # root, and the channel's own `turbo_stream_from channel_name, cid`
+      # inside it, in one block. The block receives the cid.
+      #
+      #   <%= island CounterChannel do |cid| %>
+      #     ...
+      #   <% end %>
+      #
+      # `transport: :transmit` leaves the stream source out — for a channel
+      # that transmits, or one that overrides #stream_name and writes its own
+      # turbo_stream_from inside the block. Other keywords land on the root
+      # element; a `data:` hash is merged beneath the island's own keys.
+      # Class-only: a dynamic name is `"#{kind.camelize}Channel".constantize`
+      # at the call site, never taken from a request param. Phlex components
+      # keep `div(**hibiki_island(...))`.
+      def island(channel, cid: nil, params: nil, transport: :broadcast, tag_name: :div, **attributes,
+                 &block)
+        island_guards!(channel, block)
+        tag_name = Helpers.tag_name(tag_name, "island")
+        transport = Helpers.transport(transport)
+        cid ||= SecureRandom.uuid
+        attributes[:data] = attributes[:data].to_h.merge(hibiki_island(channel, cid:, params:)[:data])
+        content = capture(cid, &block)
+        content = island_stream(channel, cid, content) if transport == :broadcast
+        tag.public_send(tag_name, content, **attributes)
+      end
+
       # Forward an event on this element as a channel action.
       #
       # `event:` names the event, or a list of them — the left side of the
@@ -169,11 +220,7 @@ module Hibiki
       # 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
+        tag_name = Helpers.tag_name(tag_name, "reactive value")
         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
@@ -185,6 +232,25 @@ module Hibiki
 
       private
 
+      # #island's preconditions: a block, an ActionView receiver, a channel
+      # class.
+      def island_guards!(channel, block)
+        raise ArgumentError, "island needs a block" unless block
+        unless respond_to?(:output_buffer) && respond_to?(:tag)
+          raise ArgumentError, "island is ERB-only; use div(**hibiki_island(...)) in a Phlex component"
+        end
+        return if channel.is_a?(Class) && channel.respond_to?(:channel_name)
+
+        raise ArgumentError,
+              "island takes a channel class, got #{channel.inspect}; " \
+              "constantize a dynamic name at the call site"
+      end
+
+      # The broadcast transport's stream source, ahead of the block's content.
+      def island_stream(channel, cid, content)
+        safe_join([turbo_stream_from(channel.channel_name, cid), content])
+      end
+
       # #on's per-control modifiers, kept out of the token grammar. Each is
       # omitted when it matches the client's own default, so the common call
       # still stamps exactly one attribute.

data/lib/hibiki/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Hibiki
   module Rails
-    VERSION = "0.11.0"
+    VERSION = "0.12.0"
   end
 end

metadata

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