hibiki_rails 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e95a440701dfeb3c02a3f6535b59cc18e51d66569dd76f9d793153f671120edc
-  data.tar.gz: 14869e53518e44f14089c7a1be15c166a51e9f61ff87867cd9fcbb848b20a3dc
+  metadata.gz: dfd1da2a9d64baab573c47345a55fbe7f985c3e6781f2e0d04879043b0889dcc
+  data.tar.gz: f012a899f4c6b675b75102f217dc9e37feaa827e4c63097cc1a86de353dce543
 SHA512:
-  metadata.gz: 3937c28fbcd8ec47e540a2837b6c48d34b4152553037491a576a67b22679d58578c09c4b63ea316390a1a5d5d49e9c37b29fe277dd8150484a881899ee8f1b00
-  data.tar.gz: 88ca77fa4732bf3d08f7b207c57ec457bc601afa7111dda3d4660b51d62a1b305b88c9a98b1801cfdc5a29f2723f8d29f5b617b545cd3c9c952e1b3c9aef8329
+  metadata.gz: 46110572a666ccd8f7c44114433259ebb901d50d7625ce7ff3468de7c0a34bbc6038766cf611eb977b1126d54fab8dbc018a55aa0a3aaab91553cf43fdcca048
+  data.tar.gz: 8b71c3b742e04e93b9e58707dcf7ebd1dda9319a0894108e07a5a560008f24591a43969e3ce1c4572e4c3ad76d0cf4fc025dd9fe3f518141bdf870e58261ab73

data/CHANGELOG.md

@@ -4,6 +4,57 @@ 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.13.0 — 2026-09-07
+
+### Changed
+
+**The scaffold's query object lives in `app/queries`.** `hibiki:rails:scaffold`
+and `scaffold_controller` write `app/queries/book_query.rb` where they wrote
+`app/models/book_query.rb`. The constant is unchanged. `app/queries` is the
+directory the query-object gems (ARQO, querifier, query_delegator) already
+generate into, so a query one of them writes for the same model meets ours as
+a file conflict instead of a second `BookQuery` that Rails loads first. The
+move costs no extra restart: the scaffold already creates `app/forms`, and one
+restart picks up both.
+
+- Apps scaffolded earlier need nothing. Move the file with `git mv` when
+  convenient; `hibiki:rails:multiselect` and `upload_field` find it in either
+  place.
+- A `--force` re-run writes `app/queries`. Rails autoloads `app/models` first,
+  so the post-install output asks you to delete the old file.
+
+## 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/README.md

@@ -112,8 +112,8 @@ once per app, shared by every generated resource, and wired into your stylesheet
 or layout automatically — the post-install output says which, or gives you the
 line to add when it cannot tell.
 
-Restart the server afterwards: `app/forms/` is new, and Rails works out its
-autoload paths at boot.
+Restart the server afterwards: `app/forms/` and `app/queries/` are new, and
+Rails works out its autoload paths at boot.
 
 ### Render the reactive component
 

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

@@ -98,7 +98,7 @@ module Hibiki
 
         # Rows are strict_loading, so the display line raises without these.
         def inject_query_preload
-          inject_includes query_path,
+          inject_includes existing_query_path,
                           with_existing: /matched_scope\.includes\(([^)]*)\)/,
                           without: "apply_sort(matched_scope)",
                           wrapped: "apply_sort(matched_scope.includes(:#{association_name}))"

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

@@ -18,7 +18,7 @@ Example:
     This will create:
         db/migrate/XXXXXXXXXXXX_create_books.rb
         app/models/book.rb
-        app/models/book_query.rb
+        app/queries/book_query.rb
         app/channels/books_channel.rb
         app/channels/book_channel.rb
         app/forms/book_form.rb
@@ -28,7 +28,8 @@ Example:
     And add to config/routes.rb:
         resources :books
 
-    Restart the server afterwards if it is running — app/forms is new.
+    Restart the server afterwards if it is running — app/forms and
+    app/queries are new.
 
     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

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

@@ -17,7 +17,7 @@ Example:
     bin/rails generate hibiki:rails:scaffold_controller Book
 
     This will create:
-        app/models/book_query.rb
+        app/queries/book_query.rb
         app/channels/books_channel.rb
         app/channels/book_channel.rb
         app/forms/book_form.rb

data/lib/generators/hibiki/rails/scaffold_controller/scaffold_controller_generator.rb

@@ -86,7 +86,7 @@ module Hibiki
           # Captured BEFORE anything is written, so post_install can tell which
           # app/* directories are new — Rails computes autoload paths from that
           # glob at boot, and a new one needs a restart.
-          @new_app_dirs = %w[app/forms app/channels app/models app/views].reject { exists?(it) }
+          @new_app_dirs = %w[app/forms app/queries app/channels app/models app/views].reject { exists?(it) }
         end
 
         # One file per app, not per resource, and the only thing this generator

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

@@ -49,19 +49,26 @@ module Hibiki
         def scaffold_controller_class_name = "#{controller_class_name}Controller"
 
         # ---- destinations ----------------------------------------------------
-        #
-        # The query object goes in app/models, NOT a new app/queries: Rails
-        # computes autoload paths from the app/* glob at boot, so a new
-        # top-level directory is not autoloadable until a server restart.
-        # app/forms already costs one restart; two would be gratuitous.
 
         def view_dir = File.join("app/views", controller_file_path)
         def collection_channel_path = File.join("app/channels", "#{controller_file_path}_channel.rb")
         def member_channel_path = File.join("app/channels", *class_path, "#{file_name}_channel.rb")
         def model_path = File.join("app/models", *class_path, "#{file_name}.rb")
-        def query_path = File.join("app/models", *class_path, "#{file_name}_query.rb")
+        def query_path = File.join("app/queries", *class_path, "#{file_name}_query.rb")
         def form_path = File.join("app/forms", *class_path, "#{file_name}_form.rb")
 
+        # Scaffolds before 0.13.0 wrote the query object to app/models. The
+        # add-on generators read existing_query_path so their injections land
+        # in the file the app loads; the scaffold itself always writes query_path.
+        def legacy_query_path = File.join("app/models", *class_path, "#{file_name}_query.rb")
+
+        def existing_query_path
+          return query_path if File.exist?(File.join(destination_root, query_path))
+          return legacy_query_path if File.exist?(File.join(destination_root, legacy_query_path))
+
+          query_path
+        end
+
         def scaffold_controller_path
           File.join("app/controllers", "#{controller_file_path}_controller.rb")
         end

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

@@ -23,6 +23,7 @@ module Hibiki
         # stylesheet, a leftover file. None of them is about the resource.
         def app_notices
           restart_notice
+          stale_query_notice
           # These live with the code that chose their branch, like
           # parent_notices — the outcomes are those modules' vocabulary.
           stylesheet_notice
@@ -49,6 +50,16 @@ module Hibiki
                                "Please restart if the server is running.", :yellow
         end
 
+        # Scaffolds before 0.13.0 wrote the query object to app/models, which
+        # autoloads ahead of app/queries: until the old copy goes, it is the one
+        # the app loads. A generator never deletes.
+        def stale_query_notice
+          return unless exists?(legacy_query_path)
+
+          say_status :stale, "#{legacy_query_path} has moved to #{query_path}. " \
+                             "Please delete the old file.", :yellow
+        end
+
         def rebuild_css_notice
           return unless css?
 

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

@@ -103,13 +103,14 @@ module Hibiki
         # Rows are strict_loading and frozen, so the thumbnail raises without
         # these — on the index AND on show-page repaints (the member channel).
         def inject_query_preload
-          return if wired?(query_path, /\.#{with_attached}\b/)
+          path = existing_query_path
+          return if wired?(path, /\.#{with_attached}\b/)
 
-          unless wired?(query_path, QUERY_WINDOW_SCOPE)
-            return manual_wiring(query_path, "  # preload the attachment:\n  .#{with_attached}")
+          unless wired?(path, QUERY_WINDOW_SCOPE)
+            return manual_wiring(path, "  # preload the attachment:\n  .#{with_attached}")
           end
 
-          gsub_file(query_path, QUERY_WINDOW_SCOPE) do |match|
+          gsub_file(path, QUERY_WINDOW_SCOPE) do |match|
             head, scope, tail = match.match(QUERY_WINDOW_SCOPE).captures
             "#{head}#{scope}.#{with_attached}#{tail}"
           end

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.13.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.13.0
 platform: ruby
 authors:
 - planetaska