hibiki_rails 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b21e4afc4b4e74e30f3c32286a1a75b30052e55145d25210bb3cecfbb3bc24c
-  data.tar.gz: 5c26612918d2b81c3a6a6a134710331ba656b25e9441856627ddf6b3ee093e71
+  metadata.gz: 5c47d1cec132b52f2a741ca77596ca90e524b348f385b0db5d2d2992ae0dba0c
+  data.tar.gz: 44505ec6d36cb48589f8d924819d3d6ee02b2fb0092b67e0bd0c9b8af316da1b
 SHA512:
-  metadata.gz: acf106a0cda97184c5bd9a988bab71efb8be65c76e1f5b08785f96795d7a9dc21f67a5511a9a10ffa7b5fee49d498891ce7516b926eec1868d76820fd7c42c48
-  data.tar.gz: 5e8d7b8aba5eaf643e5c6f82dcde5c824bd8f9eb1594163dd872bc0a304a6b37a796069385ec8fdc78e8bfe48dd7d9345d4f60a20b77fe3f72760d02e9b0157e
+  metadata.gz: 85985021ba53ce7e11eb4b6713905e8abee6c9e0c6babd36a1fd8debb06887994827cce847ae82a20df822d53ff14398be3f4515f416354ad1058f7562151037
+  data.tar.gz: 031d605405895afed00c8119eabf62e7e545213a059f2d7e424f78fc08623939e550231168d829131f494d7bec3e9fa352f151cf41514700d1c8a90e3a68f6a0

data/CHANGELOG.md

@@ -4,6 +4,112 @@ 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.5.0 — 2026-08-05
+
+### Added
+
+**`--phlex` on both scaffold generators.** `bin/rails g hibiki:rails:scaffold
+Book title:string --phlex` emits Phlex components under `app/views/books/*.rb`,
+namespaced `Views::`, instead of ERB templates. Purely additive: without the
+flag nothing about the generated output changes, byte for byte.
+
+Only the view layer moves. The channels, the query object, the ReactiveForm,
+the model injections, every action and the whole `data-hibiki-*` protocol are
+the same either way — the controller gains an explicit `render Views::…` at
+each of its six render sites, and the two `broadcast_morph` calls swap
+`partial:`/`locals:` for `renderable:`, and that is the entire difference
+outside the templates.
+
+Needs `phlex-rails` and `bin/rails g phlex:install`. The generator warns when
+either is missing and writes the files anyway, so the scaffold can come first.
+
+Four things worth knowing, because they are not what an ERB reader expects.
+Phlex renders `String`, `Symbol`, `Integer` and `Float` and raises on anything
+else, so date, time and decimal columns are emitted with an explicit `to_s`.
+Phlex omits a `false`-valued attribute entirely, so the page control's
+`data-turbo` is the string `"false"`. Phlex emits no whitespace between
+siblings, so the components space their inline neighbours explicitly. And
+`options_for_select` outputs directly and raises if its return value is passed
+on, so both select sites take their options from a block.
+
+The page control is still the one component with a per-`--css` fork, in both
+trees. Under Phlex the plain-Tailwind fork's *reason* dissolves — a hoisted
+template local becomes an ordinary constant — but it stays forked so the two
+trees match file for file and a future `--css` decision stays a diff rather
+than a judgement call.
+
+### Changed
+
+**The loading and connection recipes are an asset, not a partial.** They were a
+103-line inline `<style>` emitted as `app/views/<resource>/_busy.html.erb` and
+rendered once per page; they are now
+`app/assets/stylesheets/hibiki_busy.css`, written once per app.
+
+Per resource was always wrong: every rule keys on an attribute the client
+stamps and none of them mentions a model, so a two-resource app carried two
+byte-identical copies. It also put CSS somewhere a Content-Security-Policy that
+forbids inline styles would reject.
+
+The generator wires it for you: a cssbundling or tailwindcss-rails entry
+stylesheet gets an `@import`, a layout already using
+`stylesheet_link_tag :app` or `:all` needs nothing, and anything else gets a
+`stylesheet_link_tag` injected into the layout. Only when none of those applies
+does it print the line to add. Every branch is idempotent.
+
+**If you re-run the generator on an app scaffolded before this**, the old
+`_busy.html.erb` stays on disk — a generator never deletes — and nothing
+renders it any more. The post-install output names it; delete it.
+
+The rules are deliberately unlayered, and the file says so: two of them set
+`display` on elements that also carry Tailwind utilities, and unlayered
+declarations beat `@layer utilities` whatever the link order.
+
+### Fixed
+
+**The npm package no longer drags in a second copy of `@rails/actioncable`.**
+It moves from `dependencies` to `peerDependencies` at `>= 7.0`, matching
+turbo-rails' own range.
+
+Why there were two: `@rails/actioncable`'s npm `latest` dist-tag is 7.2.302 even
+though 8.x is published, and resolvers prefer `latest` when it satisfies the
+range. So turbo-rails' `>=7.0` took 7.2.302 while this package's `>= 8.0` was
+forced up to 8.1.301, and both ended up in the bundle — about 16 KB of duplicate
+client, and two separate module instances that could never share a consumer.
+A fresh install happened to hoist a single copy; the duplicate appeared when
+adding hibiki-rails to an app whose lockfile already pinned 7.2.302, which is
+every existing app.
+
+If your bundler warns about an unmet peer, install `@rails/actioncable`
+explicitly — but a stock Rails app already has it via turbo-rails, and both bun
+and npm 7+ auto-install a missing peer. The client uses only `createConsumer`,
+`subscriptions.create` and `subscription.perform`, all stable since Action
+Cable 6, so the lower floor changes nothing at runtime.
+
+### Changed — BREAKING
+
+**The Rails floor is now 8.0.** `actioncable` and `railties` move from
+`>= 7.1` to `>= 8.0`, and the 7.1 / 7.2 CI legs are gone. Ruby stays at `>= 3.4`.
+
+This is a correction as much as a policy change: **generated controllers never
+ran on Rails 7.** `hibiki:rails:scaffold` emits `params.expect` at two sites,
+inherited from Rails 8's own scaffold, and `ActionController::Parameters#expect`
+does not exist before 8.0 — so a generated controller raised `NoMethodError` on
+the first request to `show`, `edit`, `update`, `create` or `destroy` on 7.1 and
+7.2. The generator suite never caught it because those specs assert on emitted
+source text and never boot the result.
+
+The alternative — branching the template on `Rails::VERSION` — was rejected: it
+would also need a way to *execute* generated output on the old legs, which is
+more work than dropping two CI legs for a version combination (Rails 7.x on
+Ruby >= 3.4) that barely exists.
+
+**If you are on Rails 7.1 or 7.2, stay on 0.4.0.** It remains available and is
+unaffected; nothing in 0.5.0 is a security fix for it. Note that the *runtime*
+half of the gem — channels, the graph, the broadcast helpers, the client — has
+no known 8.0-only dependency; it is the generators whose output does. The floor
+applies to the whole gem anyway, because shipping a gem whose headline generator
+cannot run on its own declared floor is what got us here.
+
 ## 0.4.0 — 2026-08-03
 
 ### Added

data/README.md

@@ -10,7 +10,7 @@ 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.
 
-Supports Rails >= 7.1, Ruby >= 3.4.
+Supports Rails >= 8.0, Ruby >= 3.4.
 
 ## Rails quick start
 
@@ -80,6 +80,13 @@ 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.
 
+Pass `--phlex` for Phlex components under `app/views/books/*.rb` instead of ERB
+templates. It needs `phlex-rails` and `bin/rails g phlex:install`, and it
+changes the view layer only — the channels, the query object, the form and the
+whole client protocol are the same either way. Note this is a different thing
+from the `hibiki_phlex` gem, which makes a component own reactive state; here
+the channel owns the state and the components are ordinary stateless views.
+
 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.
@@ -90,6 +97,12 @@ 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.
 
+One file lands outside the resource: `app/assets/stylesheets/hibiki_busy.css`,
+which styles the loading and connection state the client stamps. It is written
+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.
 
@@ -107,7 +120,7 @@ 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.
+Release notes and upgrade advice: [CHANGELOG.md](CHANGELOG.md). **Rails 7.1 and 7.2 are supported up to 0.4.0 only** — 0.5.0 raises the floor to 8.0. If you are staying on 0.4.0 with Rails 7.x, read the 0.3.0 entry: it fixes channel lifecycle methods that were client-invocable on those versions.
 
 ## Development
 

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

@@ -121,10 +121,13 @@ module Hibiki
           badge_warning: "inline-flex items-center rounded-full bg-amber-100 px-2 py-1 " \
                          "text-xs font-medium text-amber-800",
           # `inline-block` is load-bearing, not decoration: a bare span is
-          # inline, where h-3/w-3 do nothing. It is safe against the
-          # visibility rules because this stylesheet is linked in <head> and
-          # the transport <style> is in the body, so equal specificity goes
-          # hibiki's way.
+          # inline, where h-3/w-3 do nothing. It also collides with
+          # .hbk-control-busy's `display: none` at equal specificity — the
+          # transport stylesheet wins because it is UNLAYERED and Tailwind's
+          # utilities are in @layer utilities, which beats them whatever the
+          # link order. (Before 0.5.0 the rules were a <style> in the body and
+          # won on document order instead; that is why the stylesheet's header
+          # now says not to wrap it in a layer.)
           spinner: "inline-block h-3 w-3 animate-spin rounded-full border-2 " \
                    "border-current border-r-transparent align-[-0.15em]",
           warning_text: "text-amber-600",

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

@@ -25,8 +25,13 @@ Example:
         app/forms/book_form.rb
         app/controllers/books_controller.rb
         app/views/books/*
+        app/assets/stylesheets/hibiki_busy.css
     And add to config/routes.rb:
         resources :books
 
     Restart the server afterwards: Rails computes autoload paths from the
     app/* glob at boot, and app/forms is 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
+    phlex-rails gem and `bin/rails g phlex:install`.

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

@@ -45,6 +45,8 @@ module Hibiki
         class_option :skip_search, type: :boolean, default: false,
                                    desc: "Omit the search box and the LIKE terms behind it"
         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"
 
         def initialize(...)
           super

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

@@ -28,7 +28,12 @@ Example:
         app/forms/book_form.rb
         app/controllers/books_controller.rb
         app/views/books/*
+        app/assets/stylesheets/hibiki_busy.css
     And modify:
         app/models/book.rb
         app/models/author.rb   # each model a belongs_to points at
         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`.

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

@@ -8,7 +8,9 @@ require_relative "../scaffold_view_helpers"
 require_relative "../scaffold_model_injection"
 require_relative "../scaffold_parent_injection"
 require_relative "../scaffold_parent_notices"
+require_relative "../scaffold_phlex_helpers"
 require_relative "../scaffold_post_install"
+require_relative "../scaffold_transport_stylesheet"
 require_relative "../scaffold_schema"
 require_relative "../css_variant"
 
@@ -29,10 +31,12 @@ module Hibiki
         include GeneratorHelpers
         include ScaffoldHelpers
         include ScaffoldViewHelpers
+        include ScaffoldPhlexHelpers
         include ScaffoldModelInjection
         include ScaffoldParentInjection
         include ScaffoldParentNotices
         include ScaffoldPostInstall
+        include ScaffoldTransportStylesheet
 
         TEMPLATE_ROOT = File.expand_path("templates", __dir__)
 
@@ -55,6 +59,8 @@ module Hibiki
                                  desc: "Rows per page"
         class_option :skip_routes, type: :boolean,
                                    desc: "Don't add routes to config/routes.rb"
+        class_option :phlex, type: :boolean, default: false,
+                             desc: "Emit Phlex components under app/views instead of ERB templates"
 
         # Deliberately NO check_class_collision on the controller. Rails' own
         # scaffold_controller assumes a brand-new resource; this one's primary
@@ -62,6 +68,13 @@ module Hibiki
         # controller existing is the normal case rather than an error. Thor's
         # per-file conflict prompt is the right granularity for that.
 
+        # First, so a --phlex app missing its wiring reads that at the TOP of
+        # the output rather than under forty created-file lines. It only warns,
+        # so the files are written either way — see ScaffoldPhlexHelpers.
+        def check_phlex_wiring
+          warn_without_phlex_rails
+        end
+
         # Resolving the schema first means a missing model or an unmigrated
         # table aborts before anything is written, rather than half-way through.
         def resolve_schema
@@ -72,6 +85,14 @@ module Hibiki
           @new_app_dirs = %w[app/forms app/channels app/models app/views].reject { exists?(it) }
         end
 
+        # One file per app, not per resource, and the only thing this generator
+        # writes outside app/{channels,models,forms,views,controllers}. It
+        # carries no model knowledge at all — the rules key on the client's
+        # attributes — so a second resource finds it already there.
+        def create_stylesheet
+          create_transport_stylesheet
+        end
+
         def create_channels
           template "channel.rb.tt", collection_channel_path
           template "member_channel.rb.tt", member_channel_path
@@ -91,7 +112,9 @@ module Hibiki
         end
 
         def create_views
-          %w[index show new edit _form _list _controls _field_error _busy].each do |view|
+          return create_phlex_views if phlex?
+
+          %w[index show new edit _form _list _controls _field_error].each do |view|
             template "views/#{view}.html.erb.tt", view_path("#{view}.html.erb")
           end
 
@@ -149,18 +172,48 @@ module Hibiki
 
         private
 
+        # No underscore, no .html.erb, and no _row/_row_form rename: all three
+        # are Rails PARTIAL conventions, and a Phlex component is reached by
+        # constant. Dropping the rename also drops a step — the file is
+        # row.rb because Zeitwerk wants basename.camelize, and calling it
+        # book.rb would put Views::Books::Book one reformat away from shadowing
+        # the model inside its own namespace.
+        #
+        # Private, because a public method on a Thor generator is a command.
+        def create_phlex_views
+          %w[index show new edit form list row row_form controls field_error].each do |view|
+            template "views/#{view}.rb.tt", view_path("#{view}.rb")
+          end
+
+          template "views/pagination.rb.tt", view_path("pagination.rb") unless infinite?
+        end
+
         # Ordered so an app's own lib/templates/... override wins first, then
-        # the per-variant fork, then the one shared template set. Only
-        # _pagination has a per-variant file — a tag-name change under `none`
-        # and a shared-local extraction under `tailwind`, neither of which a
-        # class-token map can express — so everything else falls through to
-        # shared/ and there is exactly one template set to maintain.
+        # the view layer, then the per-variant fork, then the one shared
+        # template set. Only the page control has a per-variant file — a
+        # tag-name change under `none` and a shared-local extraction under
+        # `tailwind`, neither of which a class-token map can express — so
+        # everything else falls through to shared/.
+        #
+        # The two layers' templates never collide (list.rb.tt vs
+        # _list.html.erb.tt), so the phlex roots could have lived beside the
+        # ERB ones. They are a subtree instead because `ls` is where this
+        # phase's permanent cost should be visible: every view change is now
+        # two templates, forever.
         def source_paths
           @source_paths ||= [*self.class.source_paths_for_search,
+                             *phlex_source_paths,
                              File.join(TEMPLATE_ROOT, css_variant.to_s),
                              File.join(TEMPLATE_ROOT, "shared")]
         end
 
+        def phlex_source_paths
+          return [] unless phlex?
+
+          [File.join(TEMPLATE_ROOT, "phlex", css_variant.to_s),
+           File.join(TEMPLATE_ROOT, "phlex", "shared")]
+        end
+
         # Explicit attributes always win, matching Rails' own precedence; the
         # schema decides the column list only when the argument list is empty.
         # That order also happens to be the only workable one, because
@@ -246,6 +299,11 @@ module Hibiki
 
         def infinite? = options[:infinite_scroll]
         def searchable? = schema.searchable? && !options[:skip_search]
+
+        # The view layer. It reaches the templates and nothing else: the graph,
+        # the query object, the form, the actions and the whole data-hibiki
+        # protocol are the same either way.
+        def phlex? = options[:phlex]
       end
     end
   end

data/lib/generators/hibiki/rails/scaffold_controller/templates/phlex/daisyui/views/pagination.rb.tt

@@ -0,0 +1,89 @@
+<%#- ESCAPING: none — plain Ruby out, every <% is generation time. -%>
+# frozen_string_literal: true
+
+# The numbered page control. It lives INSIDE the replaced fragment, like every
+# other control in there: page_count is a server number, so a single-page list
+# simply stops rendering this element. Placed outside the fragment it would
+# never be re-rendered and could only ever change its TEXT (reactive values are
+# textContent-only), leaving a control whose links point at pages that no
+# longer exist.
+#
+# SCROLL. The links are anchors to the list, not buttons, and that IS the
+# scroll answer — the client only preventDefaults `submit`, so the click both
+# performs the action and does the browser's own fragment jump, which puts the
+# top of the list back in view exactly as a full page load would. No client
+# capability needed. data-turbo="false" keeps Turbo Drive out of it: a
+# same-page hash with Turbo off is a plain scroll, not a navigation.
+#
+# THE STRING "false", not the boolean. Phlex OMITS a false-valued attribute
+# entirely, so `turbo: false` would emit no data-turbo at all and Turbo Drive
+# would take the click back. The ERB twin's boolean is right there and wrong
+# here.
+#
+# No generation token — a page number is idempotent, so a double fire is one
+# write and one render.
+#
+# PENDING. Nothing here asks for it: the client stamps data-hibiki-busy on the
+# control that fired, so the clicked page link dims itself while the trip is
+# out, and the swap that answers it destroys the attribute along with the link.
+# The bar above the list is the other half — the anchor jump has already put it
+# in view by then.
+class <%= view_class_name(:pagination) %> < Views::Base
+<%= phlex_includes(:link_to, hibiki: true) %>
+
+<%= initializer_source([%w[page 1], %w[page_count 1]]) %>
+
+  def view_template
+    # The id-carrying wrapper stays put and stays BARE. It always renders, so
+    # idiomorph always has a node to pair with, and it holds no layout classes
+    # of its own — with no page control it is empty, and padding here would
+    # leave dead vertical space on a list that has none.
+    div(id: "<%= pagination_dom_id %>") do
+      nav<%= arg_list(*css_args(:pagination_nav), %(aria_label: "Pagination")) %> { items } if @page_count > 1
+    end
+  end
+
+  private
+
+  def items
+    # Prev/next stay rendered and go inert at the ends rather than
+    # disappearing, so the control keeps its width across a page change — one
+    # that reflows under the pointer is how you mis-click a list that just
+    # repainted. A span, not a disabled link: there is no page to name, so
+    # there is no action to stamp.
+    @page == 1 ? inert("«") : step("«", @page - 1, rel: "prev", label: "Previous page")
+    whitespace
+
+    <%= query_class_name %>.page_numbers(page: @page, page_count: @page_count).each do |n|
+      if n.nil?
+        span(class: "join-item btn btn-disabled", aria_hidden: "true") { "…" }
+      elsif n == @page
+        # aria-current is the only thing that tells a screen reader which page
+        # it is on: the visual cue is a class, and the link text is just a
+        # number either way.
+        span(class: "join-item btn btn-active", aria_current: "page") { n.to_s }
+      else
+        step(n.to_s, n, label: "Page #{n}")
+      end
+
+      # Phlex emits nothing between siblings; without this the page numbers run
+      # together, which under --css=none is all there is to separate them.
+      whitespace
+    end
+
+    @page == @page_count ? inert("»") : step("»", @page + 1, rel: "next", label: "Next page")
+  end
+
+  def inert(glyph)
+    span(class: "join-item btn btn-disabled", aria_disabled: "true") { glyph }
+  end
+
+  # `on` returns a { data: } hash, so an element needing its OWN data
+  # attributes has to MERGE rather than splat: a bare ** after
+  # `data: { turbo: "false" }` would silently replace it and the anchor would
+  # stop scrolling.
+  def step(text, n, label:, rel: nil)
+    link_to text, "#<%= list_dom_id %>", class: "join-item btn", rel:, "aria-label": label,
+            data: { turbo: "false" }.merge(on(:go_to_page, with: { page: n })[:data])
+  end
+end

data/lib/generators/hibiki/rails/scaffold_controller/templates/phlex/none/views/pagination.rb.tt

@@ -0,0 +1,88 @@
+<%#- ESCAPING: none — plain Ruby out, every <% is generation time. -%>
+# frozen_string_literal: true
+
+# The numbered page control. It lives INSIDE the replaced fragment, like every
+# other control in there: page_count is a server number, so a single-page list
+# simply stops rendering this element. Placed outside the fragment it would
+# never be re-rendered and could only ever change its TEXT (reactive values are
+# textContent-only), leaving a control whose links point at pages that no
+# longer exist.
+#
+# SCROLL. The links are anchors to the list, not buttons, and that IS the
+# scroll answer — the client only preventDefaults `submit`, so the click both
+# performs the action and does the browser's own fragment jump, which puts the
+# top of the list back in view exactly as a full page load would. No client
+# capability needed. data-turbo="false" keeps Turbo Drive out of it: a
+# same-page hash with Turbo off is a plain scroll, not a navigation.
+#
+# THE STRING "false", not the boolean. Phlex OMITS a false-valued attribute
+# entirely, so `turbo: false` would emit no data-turbo at all and Turbo Drive
+# would take the click back. The ERB twin's boolean is right there and wrong
+# here.
+#
+# No generation token — a page number is idempotent, so a double fire is one
+# write and one render.
+#
+# PENDING. Nothing here asks for it: the client stamps data-hibiki-busy on the
+# control that fired, so the clicked page link dims itself while the trip is
+# out, and the swap that answers it destroys the attribute along with the link.
+# The bar above the list is the other half — the anchor jump has already put it
+# in view by then.
+#
+# The sharpest of the three forks, and the one Phlex does NOT dissolve. Both
+# styled variants mark the current page with a CLASS. With no stylesheet there
+# is nothing to carry that signal, so the current page has to change ELEMENT —
+# strong rather than a styled span — and the inert prev/next markers become
+# plain text. aria-current still does the work for a screen reader either way;
+# what changes is that sighted users need the element.
+class <%= view_class_name(:pagination) %> < Views::Base
+<%= phlex_includes(:link_to, hibiki: true) %>
+
+<%= initializer_source([%w[page 1], %w[page_count 1]]) %>
+
+  def view_template
+    # The id-carrying wrapper always renders, so idiomorph always has a node to
+    # pair with.
+    div(id: "<%= pagination_dom_id %>") do
+      nav(aria_label: "Pagination") { items } if @page_count > 1
+    end
+  end
+
+  private
+
+  def items
+    # Prev/next stay rendered and go inert at the ends rather than
+    # disappearing, so the control keeps its position across a page change. A
+    # span, not a disabled link: there is no page to name, so there is no
+    # action to stamp.
+    @page == 1 ? inert("«") : step("«", @page - 1, rel: "prev", label: "Previous page")
+    whitespace
+
+    <%= query_class_name %>.page_numbers(page: @page, page_count: @page_count).each do |n|
+      if n.nil?
+        span(aria_hidden: "true") { "…" }
+      elsif n == @page
+        strong(aria_current: "page") { n.to_s }
+      else
+        step(n.to_s, n, label: "Page #{n}")
+      end
+
+      # Phlex emits nothing between siblings; without this the page numbers run
+      # together, which under --css=none is all there is to separate them.
+      whitespace
+    end
+
+    @page == @page_count ? inert("»") : step("»", @page + 1, rel: "next", label: "Next page")
+  end
+
+  def inert(glyph)
+    span(aria_disabled: "true") { glyph }
+  end
+
+  # `on` returns a { data: } hash, so an element needing its OWN data
+  # attributes has to MERGE rather than splat, or the anchor stops scrolling.
+  def step(text, n, label:, rel: nil)
+    link_to text, "#<%= list_dom_id %>", rel:, "aria-label": label,
+            data: { turbo: "false" }.merge(on(:go_to_page, with: { page: n })[:data])
+  end
+end