hibiki_rails 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c47d1cec132b52f2a741ca77596ca90e524b348f385b0db5d2d2992ae0dba0c
-  data.tar.gz: 44505ec6d36cb48589f8d924819d3d6ee02b2fb0092b67e0bd0c9b8af316da1b
+  metadata.gz: cd126c85e743e5ec9c89e54a1ffaba4cb04e6b6b0ef89868d60023168a0936a7
+  data.tar.gz: 00b4dfa1606348df1039cf5b69d1129c170fd418966b3db120964b71eba1e1c6
 SHA512:
-  metadata.gz: 85985021ba53ce7e11eb4b6713905e8abee6c9e0c6babd36a1fd8debb06887994827cce847ae82a20df822d53ff14398be3f4515f416354ad1058f7562151037
-  data.tar.gz: 031d605405895afed00c8119eabf62e7e545213a059f2d7e424f78fc08623939e550231168d829131f494d7bec3e9fa352f151cf41514700d1c8a90e3a68f6a0
+  metadata.gz: 3c1e7d75c946f79cc898c20c2c3a8457ba78c152963f8b8155dd70a26308c138b31acc4b7a732e037d6bc28e933fb542a509d2dabee2e03602727d7e5e81b6d6
+  data.tar.gz: 6edf4361a4edbda81b933167cb6a7e08030cb50aac694c601a22c2210036eab5c56b101a449d3ea174a5485347e7c9c6e1cc86f9da123cbfe02e0e1ed34f41dd

data/CHANGELOG.md

@@ -4,6 +4,26 @@ 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.1 — 2026-08-08
+
+### Changed
+
+**Generator output and messages slimmed down.** The scaffold templates used to
+carry long design-rationale comments into every generated file; they are now
+one-to-three-line hints, with the docs holding the prose. The safety notes a
+user editing the file actually needs stayed: public channel methods are
+client-invocable actions, ActionCable's exact-arity rule, the untrusted
+subscribe param, Phlex omitting `false`-valued attributes, and the busy
+stylesheet's do-not-wrap-in-a-layer rule.
+
+The generators' status notices were shortened the same way — they still say
+what to do, just not why at essay length.
+
+No behavior change anywhere: no code inside any template moved, and neither
+the runtime nor the packaged client changed (the npm 0.5.1 exists only to keep
+the lockstep rule). Re-running a scaffold with `--force` rewrites the views
+with the shorter comments; that diff is the whole upgrade.
+
 ## 0.5.0 — 2026-08-05
 
 ### Added

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

@@ -71,8 +71,7 @@ module Hibiki
         def wiring_hint
           return if hibiki_registered? && helpers_included?
 
-          say_status :hint, "the packaged client is not fully wired " \
-                            "(register line and/or Helpers include) — run: " \
+          say_status :hint, "the packaged client is not fully wired. Run: " \
                             "bin/rails g hibiki:rails:install", :yellow
         end
       end

data/lib/generators/hibiki/rails/install/install_generator.rb

@@ -103,8 +103,7 @@ module Hibiki
 
         def bundler_note
           say_status :skip, "#{IMPORTMAP} not found — with a JS bundler, " \
-                            "npm/yarn add hibiki-rails instead (it pulls in " \
-                            "@rails/actioncable)", :yellow
+                            "npm/yarn/bun add hibiki-rails instead", :yellow
         end
       end
     end

data/lib/generators/hibiki/rails/install/templates/hibiki_controller.js.tt

@@ -1,7 +1,4 @@
-// Registers the packaged hibiki client (the "hibiki-rails" module: the
-// engine's importmap pin, or the npm package in bundler apps) as the
-// "hibiki" Stimulus controller — the Ruby helpers hardcode that
-// identifier in data-controller. File-backed on purpose: `bin/rails
-// stimulus:manifest:update` re-derives this exact registration from the
-// filename, so it survives manifest rewrites.
+// Registers the packaged hibiki client as "hibiki" Stimulus controller.
+// `bin/rails stimulus:manifest:update` re-derives this,
+// so it survives manifest rewrites.
 export { default } from "hibiki-rails"

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

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
 # Generated by hibiki:rails:island — a working mini-example: one state,
-# one derived, one action, one broadcasting effect. The concern owns the
-# actor, the root, the per-action batch, and the [channel_name, cid]
-# stream convention; this class is just the graph and its actions.
+# one derived, one action, one broadcasting effect.
 class <%= class_name %>Channel < ApplicationCable::Channel
   include Hibiki::Rails::Channel
 

data/lib/generators/hibiki/rails/island/templates/display.html.erb.tt

@@ -1,5 +1,4 @@
-<%%# The root id is the broadcast replacement key — keep it in sync with the
-    channel effect's target. %>
+<%%# The root id is the replacement key. Keep in sync with channel effect's target. %>
 <p id="<%= display_dom_id %>">
   count: <strong><%%= count %></strong> &middot; doubled: <strong><%%= doubled %></strong>
 </p>

data/lib/generators/hibiki/rails/island/templates/island.html.erb.tt

@@ -1,13 +1,9 @@
-<%%# Stamped through Hibiki::Rails::Helpers (hibiki_island / on) — never
-    write the underlying data attributes by hand, they are private to the
-    gem and version with its packaged JS. %>
+<%%# Reactive island generated by hibiki_rails %>
 <%% cid = local_assigns.fetch(:cid) { SecureRandom.uuid } %>
 <%%= tag.div(**hibiki_island(<%= class_name %>Channel, cid:)) do %>
   <%%= turbo_stream_from "<%= stream_name %>", cid %>
 
-  <%%# Paint-avoidance placeholder only: the controller subscribes AFTER the
-      Turbo stream above confirms, so the graph's first broadcast replaces
-      this. %>
+  <%%# Placeholder only: the graph's first broadcast replaces this. %>
   <%%= render "<%= view_dir %>/<%= file_name %>_display", count: 0, doubled: 0 %>
 
   <p><%%= tag.button("+1", **on(:increment)) %></p>

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

@@ -27,9 +27,8 @@ module Hibiki
         def warn_without_hibiki_phlex
           require "hibiki/phlex"
         rescue LoadError
-          say_status :warn, "hibiki_phlex is not in this bundle — the generated channel " \
-                            "calls Hibiki::Phlex.render_effect. Add `gem \"hibiki_phlex\"` " \
-                            "(and `gem \"phlex-rails\"` to render components from views).", :yellow
+          say_status :warn, "hibiki_phlex is not in this bundle. " \
+                            "Add `gem \"hibiki_phlex\"`.", :yellow
         end
 
         def create_channel
@@ -64,7 +63,7 @@ module Hibiki
         def register_hint
           return if hibiki_registered?
 
-          say_status :hint, "the packaged client is not registered — run: " \
+          say_status :hint, "the packaged client is not registered. Run: " \
                             "bin/rails g hibiki:rails:install", :yellow
         end
       end

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

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
-# Generated by hibiki:rails:phlex — the component owns the state
-# (Hibiki::Reactive); the channel owns the transport. One render effect,
-# re-rendering THE SAME INSTANCE, its HTML transmitted over the channel's
-# own subscription and swapped in by the fragment's root DOM id.
+# Generated by hibiki:rails:phlex
 class <%= class_name %>Channel < ApplicationCable::Channel
   include Hibiki::Rails::Channel
 

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

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 
-# Generated by hibiki:rails:phlex — a working mini-example. The component
-# is a plain Ruby object: Hibiki::Reactive gives it per-instance signals
-# 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.
+# Generated by hibiki:rails:phlex
 class Components::<%= class_name %> < Phlex::HTML
   include Hibiki::Reactive
   include Hibiki::Phlex::Rerenderable
@@ -14,11 +10,10 @@ class Components::<%= class_name %> < Phlex::HTML
   derived(:doubled) { count * 2 }
 
   def view_template
-    # The root id is the swap key for transmitted fragments — page-unique.
+    # The root id is the swap key for transmitted fragments; keep page-unique.
     div(id: "<%= component_dom_id %>") do
       p { "count: #{count} · doubled: #{doubled}" }
-      # Inside the swapped fragment on purpose: the island's root-scoped
-      # delegation keeps the button working across replacements.
+      # The island's delegation keeps the button working across replacements.
       button(**on(:increment)) { "+1" }
     end
   end

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

@@ -1,16 +1,14 @@
 # frozen_string_literal: true
 
-# The island wrapper: one channel subscription per render, identified by
-# a per-page-load cid. Render from any page:
-#
+# Generated by hibiki:rails:phlex
+# Render from any page:
 #   <%%= 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.
+      # Placeholder; the channel takes over from the first transmit.
       render Components::<%= class_name %>.new
     end
   end

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

@@ -8,9 +8,9 @@ Description:
     Everything is derived from the field list you pass, exactly as Rails'
     scaffold derives its own output. Stock `rails g scaffold` is untouched.
 
-    The generated index is live: search, filter, sort and pagination are signal
-    state, edits happen in place, and a write from anywhere — another tab,
-    another user, the plain controller, a console — repaints every open list.
+    The generated index is live: search, filter, sort, and pagination are all
+    reactive, edits happen in place, and changes from anywhere update every open
+    list.
 
 Example:
     bin/rails generate hibiki:rails:scaffold Book title:string author:references
@@ -29,8 +29,7 @@ Example:
     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.
+    Restart the server afterwards if it is running — 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

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

@@ -1,21 +1,18 @@
 Description:
-    Generates a reactive CRUD resource for a model that ALREADY exists — the
-    overlay half of hibiki:rails:scaffold.
+    Generates a reactive CRUD resource for a model that already exists.
 
-    With no field list the model's own schema is read: columns and types,
-    belongs_to reflections, and the validators behind per-field live errors.
-    Pass fields explicitly to override that, or when the table has not been
-    migrated yet.
+    With no field list, the model's schema is used to determine columns, types,
+    associations, and validators. Pass fields explicitly to override this or
+    when the table hasn't been migrated yet.
 
-    The generated index is live: search, filter, sort and pagination are signal
-    state, edits happen in place, and a write from anywhere repaints every open
+    The generated index is live: search, filter, sort, and pagination are all
+    reactive, edits happen in place, and changes from anywhere update every open
     list.
 
-    Two models are MODIFIED. This one gets a delegate per belongs_to plus the
-    after_commit broadcast the whole thing hangs off; each model a belongs_to
-    POINTS AT gets the has_many half Rails' scaffold never writes, and a ping,
-    because a row prints the parent's label rather than its id. Both are
-    idempotent, both are announced, and anything already declared is left alone.
+    Two models are MODIFIED. This one gets a delegate for each belongs_to and
+    an after_commit broadcast. The related models get the missing has_many
+    association and a ping so changes are reflected here. Existing declarations
+    are left alone.
 
 Example:
     bin/rails generate hibiki:rails:scaffold_controller Book

data/lib/generators/hibiki/rails/scaffold_controller/templates/daisyui/views/_pagination.html.erb.tt

@@ -2,44 +2,19 @@
      item as two tokens (`join-item btn`), so each of the six variants below can
      repeat them inline — which is exactly what plain Tailwind cannot do. -%>
 <%%# locals: (page: 1, page_count: 1) -%>
-<%%# 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.
-
-    No generation token — a page number is idempotent, so a double fire is one
-    write and one render.
-
-    `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. %>
-<%%# 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 numbered page control, inside the replaced fragment so it re-renders
+    with the list. The links are anchors to the list, so a click also does the
+    browser's own fragment jump; data-turbo="false" keeps Turbo Drive out.
+    `on` returns a { data: } hash — merge, don't splat, or the anchor stops
+    scrolling. %>
 <%% page_data = ->(n) { { turbo: false }.merge(on(:go_to_page, with: { page: n })[:data]) } %>
-<%%# 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. %>
+<%%# The wrapper always renders (so idiomorph has a node to pair with) and
+    stays bare — layout classes here would leave dead space when empty. %>
 <div id="<%= pagination_dom_id %>">
   <%% if page_count > 1 %>
     <nav<%= css_attr(:pagination_nav) %> aria-label="Pagination">
-      <%%# 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. %>
+      <%%# Prev/next go inert at the ends rather than disappearing, so the
+          control keeps its width across a page change. %>
       <%% if page == 1 %>
         <span class="join-item btn btn-disabled" aria-disabled="true">«</span>
       <%% else %>
@@ -51,9 +26,6 @@
         <%% if n.nil? %>
           <span class="join-item btn btn-disabled" aria-hidden="true">…</span>
         <%% 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 %></span>
         <%% else %>
           <%%= link_to n, "#<%= list_dom_id %>", class: "join-item btn",

data/lib/generators/hibiki/rails/scaffold_controller/templates/none/views/_pagination.html.erb.tt

@@ -2,36 +2,21 @@
      the current page with a CLASS (btn-active, or a background utility). 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, because there is no stylesheet to help. A class-token map cannot
+     inert prev/next markers become plain text. A class-token map cannot
      express a change of tag name. -%>
 <%%# locals: (page: 1, page_count: 1) -%>
-<%%# 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.
-
-    SCROLL. The links are anchors to the list, not buttons — the client only
-    preventDefaults `submit`, so the click both performs the action and does the
-    browser's own fragment jump. data-turbo="false" keeps Turbo Drive out of it.
-
-    `on` returns a { data: } hash, so an element needing its OWN data attributes
-    has to MERGE rather than splat, or the anchor stops scrolling. %>
-<%%# 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 numbered page control, inside the replaced fragment so it re-renders
+    with the list. The links are anchors to the list, so a click also does the
+    browser's own fragment jump; data-turbo="false" keeps Turbo Drive out.
+    `on` returns a { data: } hash — merge, don't splat, or the anchor stops
+    scrolling. %>
 <%% page_data = ->(n) { { turbo: false }.merge(on(:go_to_page, with: { page: n })[:data]) } %>
-<%%# The id-carrying wrapper always renders, so idiomorph always has a node to
-    pair with. %>
+<%%# The wrapper always renders, so idiomorph always has a node to pair with. %>
 <div id="<%= pagination_dom_id %>">
   <%% if page_count > 1 %>
     <nav aria-label="Pagination">
-      <%%# 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. %>
+      <%%# Prev/next go inert at the ends rather than disappearing, so the
+          control keeps its position across a page change. %>
       <%% if page == 1 %>
         <span aria-disabled="true">«</span>
       <%% else %>

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

@@ -1,43 +1,17 @@
 <%#- 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 numbered page control, inside the replaced fragment so it re-renders
+# with the list. The links are anchors to the list, so a click also does the
+# browser's own fragment jump; data-turbo="false" keeps Turbo Drive out.
 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.
+    # The wrapper always renders (so idiomorph has a node to pair with) and
+    # stays bare — layout classes here would leave dead space when empty.
     div(id: "<%= pagination_dom_id %>") do
       nav<%= arg_list(*css_args(:pagination_nav), %(aria_label: "Pagination")) %> { items } if @page_count > 1
     end
@@ -46,11 +20,8 @@ class <%= view_class_name(:pagination) %> < Views::Base
   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.
+    # Prev/next go inert at the ends rather than disappearing, so the control
+    # keeps its width across a page change.
     @page == 1 ? inert("«") : step("«", @page - 1, rel: "prev", label: "Previous page")
     whitespace
 
@@ -58,16 +29,12 @@ class <%= view_class_name(:pagination) %> < Views::Base
       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.
+      # Phlex emits nothing between siblings.
       whitespace
     end
 
@@ -78,10 +45,8 @@ class <%= view_class_name(:pagination) %> < Views::Base
     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.
+  # The STRING "false", not the boolean — Phlex omits false-valued attributes.
+  # And merge, don't splat: the anchor needs its own data attribute too.
   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])

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

@@ -1,48 +1,19 @@
 <%#- 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.
+# The numbered page control, inside the replaced fragment so it re-renders
+# with the list. The links are anchors to the list, so a click also does the
+# browser's own fragment jump; data-turbo="false" keeps Turbo Drive out.
 #
-# 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.
+# Unstyled, so the current page changes ELEMENT (strong) — there is no class
+# to carry the signal.
 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.
+    # The 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
@@ -51,10 +22,8 @@ class <%= view_class_name(:pagination) %> < Views::Base
   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.
+    # Prev/next go inert at the ends rather than disappearing, so the control
+    # keeps its position across a page change.
     @page == 1 ? inert("«") : step("«", @page - 1, rel: "prev", label: "Previous page")
     whitespace
 
@@ -67,8 +36,7 @@ class <%= view_class_name(:pagination) %> < Views::Base
         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.
+      # Phlex emits nothing between siblings.
       whitespace
     end
 
@@ -79,8 +47,8 @@ class <%= view_class_name(:pagination) %> < Views::Base
     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.
+  # The STRING "false", not the boolean — Phlex omits false-valued attributes.
+  # And merge, don't splat: the anchor needs its own data attribute too.
   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])