hibiki_rails 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2776ffca09f5d60a467d985550fb12c36570a5a22fd5eb7b0a54ee45c30a68e0
-  data.tar.gz: 3a05960da6f7ab9d80a2f6574f6413491610314fd3917a62b48c48127b866830
+  metadata.gz: b661448cbe2b84a20e26f5cd0bffaf2cf7be8c755f0f1b9c692f77e9f5798430
+  data.tar.gz: b09c3b35032a6990ab08c17e424a147e9e667905a4f9e9378062d52583e213d6
 SHA512:
-  metadata.gz: 29f7fc27b77dbb5e32e94440afc233da170b4095b77bac378426f834a47da38065b5b35881c63dcefe4e3c0053849f0fd2fd23d87d80708aebbec207fe765e93
-  data.tar.gz: 5f85d166f5ff9dec3dc23a4d8e4aae9fbece2f53ee63b10a163622e799c77f6b989743f27a935db3c1915b9bb56c96332462b983ccf3fc0cd7ab9ea8f5477fa4
+  metadata.gz: dc4013a0867b606341dd9af0135a82ab9e5a8c6b5f5cabd788eea48e0f3b604a708d31aa21c044f8639a5f2951242986b710d893b968246d03703359d562235b
+  data.tar.gz: d407a4c966366e5b11d9db6eaf7e789dcd4e086ca028dad0b2bc9b69bc4ec8f6b110339e338894b51851aa8ace18f08ef2339ce9198cf7a9226dc48d11b8c592

data/CHANGELOG.md

@@ -4,6 +4,83 @@ 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.9.0 — 2026-08-17
+
+### Added
+
+**`reactive_nested` — nested forms over `accepts_nested_attributes_for`.**
+`reactive_nested :credits, "CreditForm"` on a ReactiveForm declares a signal
+holding an array of child forms; the child class may itself declare
+`reactive_nested`, so depth is composition — nothing counts levels. `#to_h`
+serializes the tree as recursive `*_attributes` (with `id:` and `_destroy:`),
+so `#commit` persists everything in the record's one save; a failed commit
+distributes each child record's errors onto the matching child form, and
+`dirty?` tracks child edits, adds, removes, and destroy-marks for free. New
+instance API: `nested_add` / `nested_remove` (a persisted child is marked
+`_destroy`, a new one leaves the array), `nested_key` (`"c<id>"` / `"n<seq>"`
+— stable DOM identity across repaints), `mark_for_destruction`. The form
+also unloads its nested associations after every commit attempt: a failed
+save leaves AR-built children in the in-memory association, and without the
+unload a later success would insert them twice.
+
+**`Hibiki::Rails::NestedActions` — generic channel actions for nested
+forms.** Opt-in include next to `Hibiki::Rails::Channel`: `nested_add`,
+`nested_remove`, `nested_move` (reorder to an index among visible
+siblings — with position stamped from array order, up/down controls are
+all a reorderable list needs), and `nested_set_field`, addressing any node by a
+`dom` + `path` payload (`"credits/c3/contributions/n1"` — association names
+alternating with child keys, any depth). Every hop is gated against the form
+classes' declarations, keys against live children, fields against
+`hibiki_attributes`. The default form resolver understands the scaffold's
+`@form`/`@editing_id` and `@new_form`/`@creating` ivars; override the private
+`nested_form_for(dom)` for anything else. No client change — nested controls
+name themselves `"#{path}/#{field}"` and ride the existing payload mechanics.
+
+**`hibiki:rails:nested` — generate one parent→child edge of a nested form.**
+`bin/rails g hibiki:rails:nested Song Credit`, then `... Credit Contribution`
+for the next level — depth is composition, each run wires one edge. The child
+model must exist and `belongs_to` the parent; attribute arguments only
+reorder or subset what the schema already knows. Emits the child ReactiveForm
+and a `_<child>_fields` partial (or Phlex component) with path-addressed
+inputs, injects the ordered `has_many` + `accepts_nested_attributes_for`,
+`reactive_nested`, the `NestedActions` include, preloads, and the classic
+`fields_for` + `params.expect` degraded path into the full-page form. A
+`position` column is detected for ordering (`--position=COLUMN` names one,
+adding the migration; `--skip-position` opts out) and ordered edges get
+up/down controls. Works against a scaffolded collection (root mode) or an
+already-nested parent's fields partial (deep mode), on both view layers.
+
+**`perform(action, payload)` is public API — and a `performOn` helper.**
+The blessed seam for app JS (a drag library's drop handler, any third-party
+widget) to fire actions on an island's graph through the island's OWN
+subscription. Reach the controller instance with Stimulus's standard
+`application.getControllerForElementAndIdentifier(islandEl, "hibiki")`, or
+skip the incantation with the new export — `performOn(element, action,
+payload)` finds the island containing `element` and performs through it,
+Stimulus context not required. The return value is the contract: truthy (the
+trip's sequence number) means the action was accepted — sent live, or queued
+during the island's initial connect window — and a repaint is coming, so
+leave the DOM as the user arranged it; `undefined` means it was dropped (the
+island is offline, the socket turned out to be dead, or no island contains
+the element) and the caller owns recovery: revert the gesture, or stand back
+and let the next repaint self-heal. Nothing queues across an offline gap, on
+purpose — a reconnect builds a fresh server-side graph, and replaying intent
+formed against the old one is worse than dropping it. Hand-writing
+`data-hibiki-*` attributes and subclassing `ChannelController` to reach an
+existing island remain unsupported: the attributes are a private contract,
+and a subclass opens a second subscription with a second graph nobody paints
+from.
+
+### Fixed
+
+**`perform` during an offline gap reported success while dropping the
+payload.** Between a socket drop and the reconnect, `perform` returned the
+trip's sequence number as if the action had been accepted, while sending
+nothing and queueing nothing. Declared actions never noticed (the fallback
+machinery gates on island state before performing), but with the return
+value now public API the lie mattered: it returns `undefined` there, the
+same dropped signal as a dead socket caught at send.
+
 ## 0.8.0 — 2026-08-15
 
 ### Added

data/app/assets/javascripts/hibiki.js

@@ -80,6 +80,36 @@
 // element entering the viewport). Everything that is not "which event"
 // is a sibling attribute, so the token grammar never has to grow.
 //
+// App JS reaching the graph — the ONE public seam. A gesture that needs
+// script (drag-and-drop, a third-party widget) fires its action through
+// the island's OWN subscription: `perform(action, payload)` on the island
+// controller instance is public API. Reach the instance with Stimulus's
+// standard lookup —
+//
+//   const islandEl = element.closest('[data-controller~="hibiki"]')
+//   const island = application.getControllerForElementAndIdentifier(islandEl, "hibiki")
+//   island?.perform("nested_move", { path, to })
+//
+// — or skip the incantation with the performOn export at the bottom of
+// this file (works outside Stimulus too):
+//
+//   import { performOn } from "hibiki-rails"
+//   performOn(element, "nested_move", { path, to })
+//
+// The return value is the whole contract: truthy (the trip's seq) means
+// the action was ACCEPTED — sent live, or queued during the initial
+// connect window — so a repaint is coming and the caller should leave the
+// DOM as the user arranged it (the morph lands as a visual no-op). Falsy
+// (undefined) means it was DROPPED — the island is offline, or the socket
+// turned out to be dead at send — and the caller owns recovery: revert
+// the gesture, or stand back and let the next repaint self-heal. Nothing
+// queues across an offline gap on purpose (a reconnect builds a fresh
+// server-side graph, so replayed intent would land on state it was not
+// formed against). Everything else is NOT a seam: the data-hibiki-*
+// attributes are private, and subclassing ChannelController to reach an
+// existing island opens a SECOND subscription — a second server-side
+// graph nobody paints from.
+//
 // Register the generic controller under the identifier "hibiki" (the
 // helpers hardcode it):
 //
@@ -93,6 +123,13 @@ import { createConsumer } from "@rails/actioncable"
 // and go with the DOM, the socket stays.
 let consumer
 
+// Live islands by root element, for performOn's ancestor walk — membership
+// here, not an attribute probe, so the helper couples to neither the
+// identifier string nor the wire attributes. Generic islands only:
+// ChannelController subclasses have `this.perform`. WeakMap so a removed
+// island pins nothing even if disconnect never ran.
+const islands = new WeakMap()
+
 // camelCase Stimulus method name → snake_case Ruby channel action.
 const underscore = (name) => name.replace(/([A-Z])/g, "_$1").toLowerCase()
 
@@ -238,8 +275,11 @@ export class ChannelController extends Controller {
   // ActionCable's own Subscription#perform already writes `action`.)
   //
   // Returns the seq so a caller that knows which control fired can attach
-  // it; nobody has to. Returns undefined instead when the socket turned
-  // out to be closed under a subscription still believed live.
+  // it; nobody has to. Returns undefined instead when the payload went
+  // nowhere: the socket turned out to be closed under a subscription still
+  // believed live, or the island was already offline. Public API on the
+  // island controller (the header's "App JS reaching the graph") — truthy
+  // = accepted, falsy = dropped and the caller owns recovery.
   perform(action, payload = {}) {
     const seq = ++this.seq
     payload.hbk = seq
@@ -275,8 +315,11 @@ export class ChannelController extends Controller {
     if (!this.connectedOnce) {
       this.beginBusy(seq)
       this.queued.push([action, payload])
+      return seq
     }
-    return seq
+    // The offline gap: dropped, and the return says so — a truthy seq here
+    // would tell a public caller a repaint is coming when none is.
+    return undefined
   }
 
   // ActionCable's `connected`, i.e. the server confirmed the subscription.
@@ -517,6 +560,7 @@ export default class HibikiController extends ChannelController {
   }
 
   async connect() {
+    islands.set(this.element, this)
     // Before the listeners, not after: a click delegated in the next
     // millisecond reaches perform(), which needs the busy map and the
     // queue to exist. This is also what stamps data-hibiki-state
@@ -580,6 +624,7 @@ export default class HibikiController extends ChannelController {
   }
 
   disconnect() {
+    islands.delete(this.element)
     for (const [type, handler] of this.listeners) {
       this.element.removeEventListener(type, handler)
     }
@@ -726,6 +771,21 @@ export default class HibikiController extends ChannelController {
 
 export { HibikiController }
 
+// The public seam without the Stimulus lookup (the header's "App JS
+// reaching the graph"): fire an action through the subscription of the
+// island CONTAINING element. Same return contract as perform — the seq
+// when accepted, undefined when dropped or when no island contains the
+// element (a structural mistake, hence the warn; the offline case stays
+// quiet because it is expected weather).
+export function performOn(element, action, payload = {}) {
+  for (let node = element; node; node = node.parentElement) {
+    const island = islands.get(node)
+    if (island) return island.perform(action, payload)
+  }
+  console.warn("hibiki: performOn found no island containing", element)
+  return undefined
+}
+
 // The Turbo-broadcast race helper the base uses internally, still
 // exported for custom (non-Stimulus) clients: resolves once Turbo stamps
 // the `connected` attribute on the given <turbo-cable-stream-source>.

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

@@ -113,7 +113,15 @@ module Hibiki
           option_label: "label cursor-pointer justify-start gap-2",
           option_note: "p-2 opacity-60 italic",
           checkbox_sm: "checkbox checkbox-sm",
-          filter_input: "input input-sm w-full mb-2"
+          filter_input: "input input-sm w-full mb-2",
+
+          # The nested fieldset (hibiki:rails:nested): one bordered card per
+          # child row, a legend on the fieldset, and the small row controls
+          # (↑/↓/Remove/Add).
+          fieldset_legend: "fieldset-legend px-2",
+          nested_row: "border border-base-300 rounded-box p-3 mb-2 space-y-2",
+          btn_ghost_sm: "btn btn-sm btn-ghost",
+          btn_outline_sm: "btn btn-sm btn-outline"
         }.freeze
 
         # DaisyUI is a plugin over Tailwind, and the merge says so literally:
@@ -167,7 +175,11 @@ module Hibiki
           option_label: "flex cursor-pointer items-center gap-2 py-1 text-sm",
           option_note: "p-2 text-gray-500 italic",
           checkbox_sm: CHECKBOX,
-          filter_input: "#{FIELD_FULL} mb-2 text-sm"
+          filter_input: "#{FIELD_FULL} mb-2 text-sm",
+          fieldset_legend: "px-2 text-sm font-medium text-gray-700",
+          nested_row: "rounded-md border border-gray-200 p-3 mb-2 space-y-2",
+          btn_ghost_sm: SECONDARY_BUTTON.sub("px-3 py-2", "px-2 py-1"),
+          btn_outline_sm: SECONDARY_BUTTON.sub("px-3 py-2", "px-2 py-1")
         ).freeze
 
         # Every lookup misses, so every class argument is omitted entirely.

data/lib/generators/hibiki/rails/nested/USAGE

@@ -0,0 +1,30 @@
+Description:
+    Wires one parent→child edge of a nested form onto a resource that
+    hibiki:rails:scaffold_controller already generated: the child's
+    ReactiveForm, a _<child>_fields partial with path-addressed inputs
+    (riding the generic Hibiki::Rails::NestedActions channel actions),
+    reactive_nested on the parent form, model wiring (has_many +
+    accepts_nested_attributes_for allow_destroy), the classic fields_for
+    fallback in the full-page form, and the controller's params.expect
+    double-array group.
+
+    Parent and Child models must exist and be migrated, and Child must
+    declare belongs_to :<parent>. An optional field list narrows or orders
+    the child's form fields; the facts stay the schema's.
+
+    Depth is composition: run once per edge. A run whose Parent is itself a
+    nested child (its _<parent>_fields partial exists) nests into that
+    partial instead of the row form.
+
+    Ordering: a `position` column on the child (or --position=COLUMN) makes
+    the fieldset ordered — the has_many gains an order scope, the parent
+    form stamps positions from array order, and rows get ↑/↓ buttons. The
+    named column is added by migration when missing; --skip-position opts
+    out entirely.
+
+Examples:
+    bin/rails g hibiki:rails:nested Song Credit
+
+    bin/rails g hibiki:rails:nested Credit Contribution
+
+    bin/rails g hibiki:rails:nested Song Credit artist:references role:string --position=rank

data/lib/generators/hibiki/rails/nested/nested_generator.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/resource_helpers"
+require "rails/generators/active_record"
+require_relative "../generator_helpers"
+require_relative "../scaffold_helpers"
+require_relative "../scaffold_view_helpers"
+require_relative "../scaffold_phlex_helpers"
+require_relative "../scaffold_model_injection"
+require_relative "../scaffold_schema"
+require_relative "../css_variant"
+require_relative "../nested_helpers"
+require_relative "../nested_injections"
+
+module Hibiki
+  module Rails
+    module Generators
+      # One parent→child edge of a nested form, onto a resource
+      # hibiki:rails:scaffold_controller already generated: the child's
+      # ReactiveForm and fields partial (path-addressed inputs riding the
+      # generic Hibiki::Rails::NestedActions), reactive_nested on the parent
+      # form, the model wiring, the classic fields_for fallback in the
+      # full-page form, and the controller's params.expect double-array group.
+      #
+      # Depth is composition — run once per edge. A run whose parent is
+      # itself a nested child injects into the parent's own fields partial
+      # instead of the row form, and nests every other wiring one level
+      # deeper.
+      class NestedGenerator < ::Rails::Generators::NamedBase
+        include ::Rails::Generators::ResourceHelpers
+        include ::ActiveRecord::Generators::Migration
+        include GeneratorHelpers
+        include ScaffoldHelpers
+        include ScaffoldViewHelpers
+        include ScaffoldPhlexHelpers
+        include ScaffoldModelInjection
+        include NestedHelpers
+        include NestedInjections
+
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Wires one parent→child edge of a nested form (reactive_nested " \
+             "+ the generic nested_* actions) onto a hibiki:rails scaffold."
+
+        argument :child, type: :string, banner: "Child"
+        argument :attributes, type: :array, default: [], banner: "field[:type] field[:type]"
+
+        class_option :css, type: :string, enum: CssVariant::NAMES,
+                           desc: "Markup variant for the generated view (default: detect)"
+        class_option :position, type: :string,
+                                desc: "Order the rows by this child column — added by migration " \
+                                      "when missing (default: a column named position, when present)"
+        class_option :skip_position, type: :boolean, default: false,
+                                     desc: "No ordering, even when the child has a position column"
+        class_option :phlex, type: :boolean,
+                             desc: "Emit a Phlex fields component (default: detect from the scaffold)"
+
+        # Everything that can refuse, before anything is written.
+        def preflight
+          check_wireable!
+          warn_without_phlex_rails
+        end
+
+        def create_child_form
+          template "child_form.rb.tt", child_form_path
+        end
+
+        def create_fields_view
+          if phlex?
+            template "fields_component.rb.tt", fields_view_target
+          else
+            template "_fields.html.erb.tt", fields_view_target
+          end
+        end
+
+        def create_position_migration
+          return unless (@position_migration = position_migration_needed?)
+
+          migration_template "position_migration.rb.tt",
+                             "db/migrate/add_#{position_column}_to_#{child_table_name}.rb"
+        end
+
+        def wire_model
+          inject_parent_model
+        end
+
+        def wire_form
+          inject_form_nested
+        end
+
+        # BEFORE the fieldset injection: the threading guards probe for each
+        # options local's name, and the injected render line would satisfy
+        # them vacuously.
+        def wire_channel
+          inject_channel_include
+          inject_edit_preload
+          inject_option_collections
+        end
+
+        def wire_views
+          inject_container_fieldset
+        end
+
+        def wire_page_form
+          inject_page_form
+        end
+
+        def wire_controller
+          inject_permitted_params
+        end
+
+        def post_install
+          if @position_migration
+            say_status :migrate, "#{child_table_name}.#{position_column} was added — " \
+                                 "run bin/rails db:migrate before using the fieldset.", :yellow
+          end
+          schema.belongs_tos.each do |column|
+            say_status :assoc, "using #{column.association_class_name}##{column.label_column} as " \
+                               "the #{column.human_name.downcase} option label — edit " \
+                               "@#{column.options_local} in #{resource_channel_path} if that's wrong", :blue
+          end
+        end
+
+        private
+
+        # The scaffold's own view layer, read from what it left on disk; an
+        # explicit --phlex wins. Deep mode reads it off the parent's fields
+        # partial instead of the row form.
+        def phlex?
+          return @phlex if defined?(@phlex)
+
+          @phlex = if !options[:phlex].nil?
+                     options[:phlex]
+                   elsif root_mode?
+                     exists?(view_path("row_form.rb"))
+                   else
+                     parent_fields_files.any? { it.end_with?(".rb") } &&
+                       parent_fields_files.none? { it.end_with?(".html.erb") }
+                   end
+        end
+
+        def css_variant
+          @css_variant ||= (options[:css] || CssVariant.detect(destination_root)).to_sym
+        end
+
+        def css(token) = CssVariant.token(css_variant, token)
+        def css? = css_variant != :none
+      end
+    end
+  end
+end

data/lib/generators/hibiki/rails/nested/templates/_fields.html.erb.tt

@@ -0,0 +1,43 @@
+<%#- ESCAPING: <%% emits runtime ERB into the generated view; a bare <% loops
+     over the schema at generation time. #{...} inside an escaped tag is
+     runtime Ruby and passes through untouched. -%>
+<%%# locals: (<%= child_singular %>:, dom:, path:<%= schema.belongs_tos.map { ", #{it.options_local}: []" }.join %>, index: 0, count: 1) -%>
+<%%# One <%= child_human_singular.downcase %> row. `path` addresses this node for the nested_* actions;
+    input names ride "#{path}/#{field}", so a submit's FormData can never
+    collide with the parent form's own attribute names. %>
+<%% dom_path = "#{dom}_#{path.tr('/', '_')}" %>
+<div id="<%%= dom_path %>"<%= css_attr(:nested_row) %>>
+<% schema.columns.each do |column| -%>
+<% if column.type == :boolean -%>
+  <div<%= css_attr(:checkbox_wrap) %>>
+    <%%= label_tag "#{dom_path}_<%= column.name %>"<%= css? ? %(, class: "#{css(:label)}") : "" %> do %>
+      <%%= check_box_tag <%= wrapped_list(nested_toggle_args(column), indent: 24).lstrip %> %>
+      <%= column.human_name %>
+    <%% end %>
+  </div>
+<% elsif column.belongs_to? -%>
+  <%%= label_tag "#{dom_path}_<%= column.name %>", "<%= column.human_name %>"<%= css? ? %(, class: "#{css(:label)}") : "" %> %>
+  <%%= select_tag <%= wrapped_list(nested_select_args(column), indent: 17).lstrip %> %>
+  <%%= render "shared/field_error", message: <%= child_singular %>.error_for(:<%= column.name %>) %>
+<% else -%>
+  <%%= label_tag "#{dom_path}_<%= column.name %>", "<%= column.human_name %>"<%= css? ? %(, class: "#{css(:label)}") : "" %> %>
+  <%%= <%= column.tag_field_helper %> <%= wrapped_list(nested_field_args(column), indent: column.tag_field_helper.length + 7).lstrip %> %>
+  <%%= render "shared/field_error", message: <%= child_singular %>.error_for(:<%= column.name %>) %>
+<% end -%>
+
+<% end -%>
+  <div<%= css_attr(:form_actions) %>>
+<% if ordered? -%>
+    <%%# Reorder: `to` is the index among visible rows — <%= position_column %>
+        persists from array order at save. %>
+    <%% if index.positive? %>
+      <%%= tag.button("↑", <%= wrapped_list(nested_move_args(:up), indent: 21).lstrip %>) %>
+    <%% end %>
+    <%% if index < count - 1 %>
+      <%%= tag.button("↓", <%= wrapped_list(nested_move_args(:down), indent: 21).lstrip %>) %>
+    <%% end %>
+<% end -%>
+    <%%= tag.button("Remove <%= child_human_singular.downcase %>", type: "button"<%= css? ? %(, class: "#{css(:btn_ghost_sm)}") : "" %>,
+                   **on(:nested_remove, with: { dom: dom, path: path })) %>
+  </div>
+</div>

data/lib/generators/hibiki/rails/nested/templates/child_form.rb.tt

@@ -0,0 +1,34 @@
+<%# GENERATION-time ERB only. -%>
+class <%= child_form_class_name %>
+  include Hibiki::Rails::ReactiveForm
+
+  # The strong-params analogue: a channel action cannot assign past this list.
+  # Writers cast through the model's own type_for_attribute.
+<% if ordered? -%>
+  # <%= position_column %> is deliberately absent: the parent form's to_h
+  # stamps it from the array order, so the visual order IS the ordering.
+<% end -%>
+  reactive_attributes <%= child_class_name %>, <%= wrapped_symbols(schema.attribute_names, indent: child_class_name.length + 24).lstrip %>
+
+<% if schema.live_errors.any? -%>
+  # Live validation before any round trip, derived from what the model
+  # declares. The model's own validates stay authoritative at commit time.
+  derived(:live_errors) do
+    {
+<% schema.live_errors.each_with_index do |(name, clause), index| -%>
+      <%= name %>: <%= clause %><%= "," unless index == schema.live_errors.size - 1 %>
+<% end -%>
+    }.compact
+  end
+<% else -%>
+  # Empty until the model declares validators — add clauses here (or
+  # validators on the model) and they light up with no other change.
+  derived(:live_errors) { {} }
+<% end -%>
+
+  derived(:valid?) { live_errors.empty? }
+
+  # The record's mirrored errors win once a commit has actually failed. Live
+  # errors wait for dirty? — a freshly added row must not paint them.
+  def error_for(name) = super || (live_errors[name.to_sym] if dirty?)
+end

data/lib/generators/hibiki/rails/nested/templates/fields_component.rb.tt

@@ -0,0 +1,70 @@
+<%#- ESCAPING: none — plain Ruby out, every <% is generation time. #{...}
+     inside a quoted string is runtime Ruby and passes through untouched. -%>
+# frozen_string_literal: true
+
+# One <%= child_human_singular.downcase %> row of the nested fieldset. `@path` addresses this node
+# for the nested_* actions; input names ride "#{path}/#{field}", so a submit's
+# FormData can never collide with the parent form's own attribute names.
+class <%= fields_component_class_name %> < Views::Base
+<%= phlex_includes(:label_tag, *row_field_helper_modules,
+                   *(%i[select_tag options_for_select] if schema.belongs_tos.any?), hibiki: true) %>
+
+<%= initializer_source([[child_singular, nil], %w[dom], %w[path],
+                        *schema.belongs_tos.map { [it.options_local.to_s, "[]"] },
+                        %w[index 0], %w[count 1]]) %>
+
+  def view_template
+    div(id: dom_path<%= css? ? %(, class: "#{css(:nested_row)}") : "" %>) do
+<% schema.columns.each do |column| -%>
+      <%= column.name %>_field
+<% end -%>
+      controls
+    end
+  end
+
+  private
+
+  def dom_path = "#{@dom}_#{@path.tr('/', '_')}"
+
+<% schema.columns.each do |column| -%>
+  def <%= column.name %>_field
+<% if column.type == :boolean -%>
+    div<%= arg_list(*css_args(:checkbox_wrap)) %> do
+      label_tag<%= arg_list(%("\#{dom_path}_#{column.name}"), *css_args(:label)) %> do
+        check_box_tag <%= wrapped_list(nested_toggle_args(column), indent: 22).lstrip %>
+        whitespace
+        plain "<%= column.human_name %>"
+      end
+    end
+<% elsif column.belongs_to? -%>
+    label_tag <%= wrapped_list([%("\#{dom_path}_#{column.name}"), %("#{column.human_name}"), *css_args(:label)], indent: 14).lstrip %>
+    # options_for_select outputs directly, so the options are a block here —
+    # phlex-rails' own prescription.
+    select_tag<%= arg_list(*nested_select_head_args(column), indent: 15) %> do
+      <%= nested_select_options_source(column) %>
+    end
+<%= render_call(:field_error, [%(message: #{nested_record_ref}.error_for(:#{column.name}))], indent: 4, shared: true) %>
+<% else -%>
+    label_tag <%= wrapped_list([%("\#{dom_path}_#{column.name}"), %("#{column.human_name}"), *css_args(:label)], indent: 14).lstrip %>
+    <%= column.tag_field_helper %> <%= wrapped_list(nested_field_args(column), indent: column.tag_field_helper.length + 5).lstrip %>
+<%= render_call(:field_error, [%(message: #{nested_record_ref}.error_for(:#{column.name}))], indent: 4, shared: true) %>
+<% end -%>
+  end
+
+<% end -%>
+  def controls
+    div<%= arg_list(*css_args(:form_actions)) %> do
+<% if ordered? -%>
+      # Reorder: `to` is the index among visible rows — <%= position_column %>
+      # persists from array order at save.
+      if @index.positive?
+        button<%= arg_list(*nested_move_args(:up), indent: 15) %> { "↑" }
+      end
+      if @index < @count - 1
+        button<%= arg_list(*nested_move_args(:down), indent: 15) %> { "↓" }
+      end
+<% end -%>
+      button<%= arg_list(%(type: "button"), *css_args(:btn_ghost_sm), "**on(:nested_remove, with: { dom: @dom, path: @path })", indent: 13) %> { "Remove <%= child_human_singular.downcase %>" }
+    end
+  end
+end

data/lib/generators/hibiki/rails/nested/templates/position_migration.rb.tt

@@ -0,0 +1,7 @@
+<%# GENERATION-time ERB only. -%>
+class Add<%= position_column.camelize %>To<%= child_table_name.camelize %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    # Ordered nested rows: the parent form stamps this from array order.
+    add_column :<%= child_table_name %>, :<%= position_column %>, :integer
+  end
+end