recourse 3.0.3 → 4.0.0

data/app/views/recourses/_footer.html.erb

@@ -0,0 +1,22 @@
+<%# locals: (pagy:) %>
+<% if pagy %>
+  <div class='d-flex align-items-center' <%= tag.attributes data: limit_data(pagy) %>>
+    <%# The gem's own sentence from pagy's public readers, every figure delimited —
+        rewriting pagy's English with a regex delimited one figure, only in English.
+        The switch follows it after a dot: how much of the table is showing, then the
+        one other amount it could show. Only while there is a second page — a table
+        that fits on one is not being paginated, and there is nothing to switch. -%>
+    <div class='ps-2 flex-grow-1'>
+      <% if pagy.last > 1 %>
+        <%= t 'recourse.displaying_slice', from: number_with_delimiter(pagy.from),
+                                           to: number_with_delimiter(pagy.to),
+                                           total: number_with_delimiter(pagy.count) %>
+        <span class='fg-2'>&middot;</span>
+        <%= limit_link pagy %>
+      <% else %>
+        <%= t 'recourse.displaying', count: pagy.count %>
+      <% end %>
+    </div>
+    <div class='pe-2'><%== pagy.series_nav(:bootstrap, classes: 'pagination mb-0') if pagy.last > 1 %></div>
+  </div>
+<% end %>

data/app/views/recourses/_form.html.erb

@@ -0,0 +1,11 @@
+<% record = local_assigns[resource_key] -%>
+<%# The url is spelled out rather than left to `model:`, which would name a route
+    outside whatever namespace the resource was drawn in. -%>
+<%= form_with model: record, url: resource_form_url(record) do |form| %>
+  <% @recourse_form = form -%>
+  <div class='row'>
+    <%= render 'fields', resource_key => record %>
+  </div>
+
+  <%= form.submit class: 'btn btn-solid theme-primary' %>
+<% end %>

data/app/views/recourses/_none.html.erb

@@ -0,0 +1 @@
+<p class='fg-2'><%= t 'recourse.none', models: Recourse.downcase(resources_name) %></p>

data/app/views/recourses/_results.html.erb

@@ -0,0 +1,10 @@
+<%# locals: (resources:, pagy:) %>
+<%# Both branches, so a search that matches nothing still answers with the frame
+    it was asked for. `advance` puts the query in the address bar. -%>
+<turbo-frame id='results' data-turbo-action='advance'>
+  <% if resources.blank? %>
+    <%= render 'none' %>
+  <% else %>
+    <%= render 'table', recourses: resources, pagy: pagy %>
+  <% end %>
+</turbo-frame>

data/app/views/recourses/_row.html.erb

@@ -1,10 +1,4 @@
-<%# locals: (recourse:) -%>
-<% recourse.attributes.each do |name, value| %>
-  <%= column header: (recourse.class.ransortable_attributes.include?(name) ? sort_link(@q, name, name.upcase_first) : name) do %>
-    <% if recourse.class.ransackable_attributes.include? name %>
-      <%= search_highlight value, model: recourse.class %>
-    <% else %>
-      <%= value %>
-    <% end %>
-  <% end unless recourse.encrypted_attribute?(name) %>
-<% end %>
+<% record = local_assigns[resource_key] -%>
+<% resource_columns.each do |name| -%>
+  <%= column header: sort_header(name), class: counter_class(name) do %><%= resource_cell record, name %><% end %>
+<% end -%>

data/app/views/recourses/_scheme.html.erb

@@ -0,0 +1,14 @@
+<%# The mode a reader chose last time, back before anything is painted. Classic and
+    inline rather than a module or a Stimulus controller: both of those run after the
+    first paint, which would show the system's mode for an instant and then swap it. -%>
+<script>
+  (function () {
+    var stored
+    try { stored = JSON.parse(localStorage.getItem('<%= Recourse::SCHEME_STORAGE %>')) }
+    catch (error) { return }
+
+    if (stored && (stored.mode === 'light' || stored.mode === 'dark')) {
+      document.documentElement.dataset.bsTheme = stored.mode
+    }
+  })()
+</script>

data/app/views/recourses/_search.html.erb

@@ -0,0 +1,24 @@
+<%# locals: (query:, url:, field:, prompt:, filters:, sort:) -%>
+<%# Never `turbo-permanent`: that spans page visits too, and every index names
+    this form the same, so a sidebar click would keep the last resource's form.
+    The search controller skips the form's subtree during a morph instead. -%>
+<%= search_form_for query, url: url, html: { class: 'recourse-search d-flex flex-wrap md:flex-nowrap ' \
+                                                    'align-items-center justify-content-end gap-2 ms-auto',
+                                            role: 'search',
+                                            data: { controller: 'search', turbo_frame: :results } } do |form| %>
+  <%# Always drawn, even empty: a heading clicked after this was rendered has only
+      this field to write the new sort into. -%>
+  <%= hidden_field_tag 'q[s]', sort %>
+
+  <%= safe_join filters %>
+
+  <%# Only where there is something to search: a model may have nothing worth
+      typing at and still be worth narrowing, and the filters above are the form. -%>
+  <% if field.present? -%>
+    <div class='recourse-search-box form-control form-control-sm form-adorn d-flex'>
+      <span class='form-adorn-icon'><i class='bi bi-search'></i></span>
+      <%= form.search_field field, class: 'form-ghost', placeholder: prompt, aria: { label: prompt },
+                                   data: { action: 'input->search#submit', search_target: 'field' } %>
+    </div>
+  <% end -%>
+<% end %>

data/app/views/recourses/_sidebar.html.erb

@@ -0,0 +1,40 @@
+<ul class='nav md:flex-column' data-controller='shortcuts'>
+  <% sidebar_resources.each do |name, title, path, key| %>
+    <% current = current_resource? name %>
+    <li class='nav-item'>
+      <%= link_to resource_label(name, title, key), path,
+                  class: class_names('nav-link', active: current),
+                  aria: { current: ('page' if current) },
+                  data: { key: (title[key].downcase if key) } %>
+    </li>
+  <% end %>
+
+  <%# A reader's own say in how the page looks: the last item of the sidebar, and at the
+      foot of it wherever it is a column. Which side of the fold that lands on is the
+      layout's business rather than this file's, and so is which of the two icons shows —
+      the mode may be the system's, which only CSS knows, so both are drawn. -%>
+  <li class='nav-item recourse-scheme'>
+    <%= tag.button type: 'button', class: 'nav-link border-0 bg-transparent',
+                   data: scheme_data do %>
+      <span class='recourse-scheme-light'>
+        <i class='bi bi-moon-fill'></i>
+        <span class='visually-hidden'><%= t 'recourse.darken' %></span>
+      </span>
+      <span class='recourse-scheme-dark'>
+        <i class='bi bi-sun-fill'></i>
+        <span class='visually-hidden'><%= t 'recourse.lighten' %></span>
+      </span>
+    <% end %>
+  </li>
+
+  <%# And the way out, where the host drew a route named `exit`: a button, since ending
+      a session is never a GET, and an icon like the toggle beside it. -%>
+  <% if exit? %>
+    <li class='nav-item recourse-exit'>
+      <%= button_to exit_path, method: :delete, class: 'nav-link border-0 bg-transparent' do %>
+        <i class='bi bi-box-arrow-right'></i>
+        <span class='visually-hidden'><%= t 'recourse.exit' %></span>
+      <% end %>
+    </li>
+  <% end %>
+</ul>

data/app/views/recourses/_table.html.erb

@@ -1,43 +1,48 @@
-<%# locals: (recourses:, pagy: nil, cached: true) -%>
-<% name = @lookup_context.find('row', @lookup_context.prefixes, true).short_identifier.split('/')[-2] %>
-<% key = name.singularize.to_sym %>
-
-<%= turbo_frame_tag :results, data: { turbo_action: :advance }, class: 'w-100' do %>
-  <% if recourses.empty? %>
-    <p>No <%= controller_path.split('/').last %>.</p>
-  <% else %>
-    <%# cache_if cached, [recourses, (recourses.unscoped.size if cached), controller_path].compact do %>
-      <div class='table-responsive'>
-        <table class='table caption-top table-hover align-middle md:table-stacked'>
-          <thead>
-            <tr>
-              <% @recourse_headers = true %>
-              <%= render 'row', key => recourses.first %>
-              <!-- <th scope='col' class='text-end'>Edit</th> -->
-            </tr>
-          </thead>
-          <tbody>
-            <% @recourse_headers = false %>
-            <% recourses.each do |recourse| %>
-              <%# cache_if (cached && !params.key?(:q)), [recourse, controller_path] do %>
-                <tr>
-                  <%= render 'row', key => recourse %>
-                  <%#= column header: 'Edit', class: 'text-end' do %>
-                    <%#= edit_link_to action: :edit, id: 1 %>
-                  <%# end %>
-                </tr>
-              <%# end %>
-            <% end %>
-        </tbody>
-        </table>
-      </div>
-
-      <% if pagy %>
-        <div class='d-flex align-items-center'>
-          <div class='ps-2 flex-grow-1'><%== pagy.info_tag.gsub(/of (\d*?) in total/) { "of #{number_with_delimiter $1} in total" } %></div>
-          <div class='pe-2'><%== pagy.series_nav(:bootstrap, classes: 'pagination mb-0') if pagy.last > 1 %></div>
-        </div>
-      <% end %>
-    <%# end %>
-  <% end %>
+<%# locals: (recourses:, pagy:) %>
+<%# A sorted or filtered table is drawn live: two requests can ask for one relation
+    and want different headings, since only one of them clicked a heading to get it. -%>
+<%# The key carries three riders. The row partial's digest: a host's `_row` is
+    resolved at render, which the fragment's own template digest never follows.
+    And the column list: which columns a table shows is decided in Ruby —
+    `recourse_hidden`, timestamps, counters — that no digest covers either. And the
+    bookmarks, which are the viewer's rather than the relation's — so this is what
+    keeps one person's kept rows off another person's page as well as what expires
+    the fragment when a square is clicked. And the zone, for the same reason again:
+    a timestamp is drawn against the reader's own clock, so without it the first
+    person to load a table would settle what hour everybody else read. -%>
+<% key = [recourses, row_digest, resource_columns, bookmark_digest, Time.zone.name] -%>
+<% cache_if cacheable_table?, key do %>
+  <% actions = resource_actions %>
+  <div class='table-responsive'>
+    <table class='table caption-top table-hover align-middle sm:table-stacked'>
+      <thead>
+        <tr>
+          <% @recourse_headers = true %>
+          <%# The square a row is kept by opens the table, ahead of the pages it
+              leads to: whether this row is one of mine, before what to do with it. -%>
+          <%= column header: bookmark_header, class: 'recourse-actions' if resource_bookmarks %>
+          <% actions.each do |action| -%>
+            <%= column header: action_header(action), class: 'recourse-actions' %>
+          <% end -%>
+          <%= render 'row', resource_key => nil %>
+        </tr>
+      </thead>
+      <tbody>
+        <% @recourse_headers = false %>
+        <% recourses.each do |recourse| %>
+          <tr <%= tag.attributes id: Recourse.row_id(recourse), class: bookmark_row_class(recourse) %>>
+            <% if resource_bookmarks -%>
+              <%= column header: bookmark_header, class: 'recourse-actions' do %><%= bookmark_button recourse %><% end %>
+            <% end -%>
+            <% actions.each do |action| -%>
+              <%= column header: action_header(action), class: 'recourse-actions' do %><%= resource_action_link action, recourse %><% end %>
+            <% end -%>
+            <%= render 'row', resource_key => recourse %>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
 <% end %>
+
+<%= render 'footer', pagy: pagy %>

data/app/views/recourses/_values.html.erb

@@ -0,0 +1,3 @@
+<% shown_columns.each do |name| -%>
+  <%= value name %>
+<% end -%>

data/app/views/recourses/edit.html.erb

@@ -0,0 +1,10 @@
+<% content_for :title, resource_record_label %>
+
+<% content_for :actions do %>
+  <%= destroy_resource_button resource_record %>
+<% end %>
+
+<%# The card is the parent's on a page nested under one, as it is for a nested index. -%>
+<%= render layout: 'card', locals: { record: resource_parent || resource_record } do %>
+  <%= render 'form', resource_key => resource_record %>
+<% end %>

data/app/views/recourses/index.html.erb

@@ -1,30 +1,33 @@
-<% resources = instance_variable_get("@#{controller_path.split('/').last}") || @resources %>
+<% content_for :title, resources_name %>
 
-<% content_for :title, controller_path.split('/').last.singularize.humanize.pluralize if @where&.empty? %>
-
-<% model = controller_name.classify.constantize %>
+<% if (new_path = new_resource_path) %>
+  <% content_for :actions do %>
+    <%= link_to t('recourse.add', model: resource_name), new_path,
+                class: 'btn theme-primary btn-sm btn-outline ms-3' %>
+  <% end %>
+<% elsif bare_create? %>
+  <%# `create` routed without `new`: the host has said there is nothing worth
+      asking, so a button posts the record whole and the index returns with it. -%>
+  <% content_for :actions do %>
+    <%= button_to t('recourse.create'), url_for(action: :create),
+                  class: 'btn theme-primary btn-sm btn-solid', form_class: 'ms-3' %>
+  <% end %>
+<% end %>
 
 <% content_for :search do %>
-  <script>
-    function debounce(method) {
-      let timer
-      return (...args) => {
-        clearTimeout(timer)
-        timer = setTimeout(() => { method.apply(this, args) }, 300);
-      }
-    }
-    const debouncedSubmit = debounce((form) => form.requestSubmit())
-  </script>
-  <%= search_form q: @q, model: model, url: request.path %>
-<% end if model.recourse_searchable? %>
-
-<% content_for :actions do %>
-  <% begin %>
-    <%= link_to "Add #{controller_path.split('/').last.singularize}", url_for(action: :new), class: 'btn theme-primary btn-sm btn-outline ms-3'%>
-  <% rescue ActionController::UrlGenerationError %>
-  <% end %>
+  <%= search_form %>
 <% end %>
 
-<% locals = { @lookup_context.find('table', @lookup_context.prefixes, true).short_identifier.split('/')[-2].to_sym => resources } %>
+<%# Outside the frame, so a search keystroke's frame navigation never tears the
+    cable connection down and reopens it. -%>
+<%= refresh_subscription %>
 
-<%= render 'table', locals.merge(pagy: @pagy, cached: model.recourse_cachable?) %>
+<%# A nested index is a page of the parent record, so it sits in the record's own
+    card, beside the record's other pages — its tab, the count, the current one. -%>
+<% if resource_parent %>
+  <%= render layout: 'card', locals: { record: resource_parent } do %>
+    <%= render 'results', resources: @resources, pagy: @pagy %>
+  <% end %>
+<% else %>
+  <%= render 'results', resources: @resources, pagy: @pagy %>
+<% end %>

data/app/views/recourses/new.html.erb

@@ -0,0 +1,3 @@
+<% content_for :title, t('recourse.new', model: resource_name) %>
+
+<%= render 'form', resource_key => resource_record %>

data/app/views/recourses/show.html.erb

@@ -0,0 +1,10 @@
+<% content_for :title, resource_record_label %>
+
+<%# A page nested under a record is that record's page, the way a nested index is:
+    the card is the parent's, so the tabs on it are about the record the path names
+    above this one rather than about this one. -%>
+<%= render layout: 'card', locals: { record: resource_parent || resource_record } do %>
+  <div class='row recourse-values'>
+    <%= render 'values', resource_key => resource_record %>
+  </div>
+<% end %>

data/config/locales/recourse.en.yml

@@ -0,0 +1,72 @@
+en:
+  # Namespaced rather than `default`, so a host's own date and time formats stand.
+  date:
+    formats:
+      recourse: "%b %-d, %Y"
+  time:
+    formats:
+      recourse: "%b %-d at %I:%M%P %Z"
+  recourse:
+    add: Add %{model}
+    ago: "%{distance} ago"
+    all: All %{models}
+    all_values: All
+    blank: "—"
+    bookmark: Bookmark
+    bookmark_added: Bookmark added
+    bookmark_error: Bookmark could not be saved.
+    bookmark_removed: Bookmark removed
+    cancel: Cancel
+    clear: Clear search
+    create: Create
+    created: "%{model} was created."
+    created_error: "%{model} could not be created."
+    darken: Darken the page
+    delete: Delete %{model}
+    deleted: "%{model} was deleted."
+    exit: Log out
+    displaying:
+      one: Displaying 1 item
+      other: Displaying %{count} items
+    displaying_slice: Displaying items %{from}-%{to} of %{total} in total
+    edit: Edit
+    format: Please match the format %{example}
+    from_now: "in %{distance}"
+    # How many values a list holds, which is what its summary reads before anybody
+    # opens it.
+    items:
+      one: 1 item
+      other: "%{count} items"
+    lighten: Lighten the page
+    missing_model: You declared `recourses :%{name}` in your routes file, but this app
+      has no %{model} model.
+    nested: You nested `recourses %{names}` inside `resources :%{parent}`, which does
+      not namespace what it holds. Nest it under `recourses :%{parent}` instead.
+    # What a menu with several picks reads as, the first named and the rest counted.
+    more: "%{first} + %{count} more"
+    new: New %{model}
+    no_results: No results found
+    none: "No %{models}."
+    optional: Optional
+    per_page: "%{limit} per page"
+    ambiguous: "matches more than one record, so it does not say which: %{label}"
+    reference: "%{model} %{attribute}"
+    reveal: Show
+    search: Search…
+    searched_cont: Filter by %{list}
+    searched_eq: Filter by exact %{list}
+    select: Select…
+    show: Show
+    unbookmark: Remove bookmark
+    unknown_color: "`Recourse.color` is one of %{colors}, or nil for Bootstrap's own
+      blue. It cannot be %{color}."
+    updated: "%{model} was updated."
+    updated_error: "%{model} could not be updated."
+    unset: None
+    deletion:
+      delete: Delete
+      title: Delete %{record}?
+      going: "%{list} will be deleted with it."
+      staying: "%{list} will be kept, without its %{model}."
+      under: Anything under those goes too.
+      undone: This cannot be undone.

data/lib/recourse/bookmarks.rb

@@ -0,0 +1,51 @@
+# Reopened for the one thing a host says about how a viewer keeps a row.
+module Recourse
+  class << self
+    # What a host wrote in the initializer, kept unresolved: a Proc is the only shape
+    # that can name the viewer, since a relation built at boot would hold the agent
+    # who was signed in then — which is nobody.
+    attr_reader :declared_bookmarks
+  end
+
+  # How bookmarks are stored: a Proc answering the viewer's rows, or a relation or a
+  # model where nobody in particular is looking. Nil turns the column off everywhere.
+  def self.bookmarks=(bookmarks)
+    @declared_bookmarks = bookmarks
+  end
+
+  # Whether a host declared any, asked while the routes draw — where resolving one
+  # would run a host's Proc long before there is a request for it to read.
+  def self.bookmarks? = !@declared_bookmarks.nil?
+
+  # The viewer's bookmarks, resolved for this request.
+  def self.bookmarks
+    bookmarks = @declared_bookmarks
+    bookmarks = bookmarks.call if bookmarks.respond_to? :call
+
+    bookmarks&.all
+  end
+
+  # How a model's bookmarks point back at it: its own `has_many` at the bookmark
+  # class, which is both the opt-in and everything needed to write one. A model that
+  # cannot hold a bookmark has not declared one, so it gets no column.
+  def self.bookmarks_for(model)
+    return unless bookmarks?
+
+    klass = bookmarks.klass
+    model.reflect_on_all_associations(:has_many).find { |one| one.klass == klass }
+  end
+
+  # The viewer's bookmarks of one model: the type narrows them where the association
+  # is polymorphic, and where it is not there is nothing to narrow by — `type` is set
+  # from `as:` and nil without it, so a host whose bookmarks belong to one model needs
+  # no type column and is asked for none. The ids behind the icons, the row a click
+  # writes and the row a click drops all start here.
+  def self.bookmarks_of(reflection)
+    return bookmarks unless reflection.type
+
+    # `polymorphic_name` rather than the class's own: it resolves through `base_class`,
+    # which is what Rails writes into the column, so a subclass stays filed with the
+    # table it shares.
+    bookmarks.where reflection.type => reflection.polymorphic_name
+  end
+end

data/lib/recourse/broadcasting.rb

@@ -0,0 +1,33 @@
+require 'active_support'
+
+module Recourse
+  # Extends every Active Record model with the refreshes its index listens for, so
+  # a table redraws itself wherever it is open when a row of it changes.
+  module Broadcasting
+    # Whether saving a record refreshes every open index listing it. On for every
+    # recoursed model; a host quiets one with `def recourse_broadcasts? = false`.
+    def recourse_broadcasts? = true
+
+    # True once the refresh broadcasts are attached, which is also what the index
+    # checks before subscribing: a stream nobody broadcasts on is not worth a socket.
+    def recourse_broadcasting? = @recourse_broadcasting || false
+
+    # Attaches the broadcasts, once per class: every committed change goes to the
+    # model's plural stream, the one its index subscribes to — plain
+    # `broadcasts_refreshes` would send updates and destroys to per-record streams
+    # the index never hears. The ivar dies with the class on a dev reload, so the
+    # next request attaches to the fresh class again. Quiet without turbo-rails and
+    # Active Job, which is when the model has no `broadcasts_refreshes_to`.
+    def recourse_broadcast
+      return if recourse_broadcasting? || !recourse_broadcasts?
+      return unless respond_to? :broadcasts_refreshes_to
+
+      @recourse_broadcasting = true
+      broadcasts_refreshes_to ->(record) { record.model_name.plural }
+    end
+  end
+end
+
+ActiveSupport.on_load :active_record do
+  extend Recourse::Broadcasting
+end

data/lib/recourse/colors.rb

@@ -0,0 +1,32 @@
+# Reopened for the one thing a host says about how every page looks.
+module Recourse
+  # Color families a host may call primary. Six of the sixteen Bootstrap ships; the
+  # other ten are declined rather than forgotten.
+  COLORS = %i[blue gray orange purple pink brown].freeze
+
+  # Families whose 500 step carries dark text rather than white, because white on it
+  # reads worse. The dark one is `--bs-gray-975`, the darkest neutral a palette has:
+  # upstream already gives warning and info a dark label for the same reason, and white
+  # on `orange-500` is 2.90:1, under the 3:1 a button's label owes.
+  DARK_INKS = %i[amber blue brown cyan gray green lime orange pewter teal yellow].freeze
+
+  class << self
+    # Which family the pages call primary, or nil for Bootstrap's own blue.
+    attr_reader :color
+  end
+
+  # Picks the primary color, and says which six there are when handed anything else. A
+  # typo would otherwise write `var(--bs-purpel-500)` into every page and go unnoticed
+  # until somebody looked at a button.
+  def self.color=(color)
+    name = color&.to_sym
+    unless name.nil? || COLORS.include?(name)
+      raise Error, I18n.t('recourse.unknown_color', color:, colors: COLORS.to_sentence)
+    end
+
+    @color = name
+  end
+
+  # Which text a family's 500 step carries, named as the token upstream spells it with.
+  def self.ink(family) = DARK_INKS.include?(family) ? 'gray-975' : 'white'
+end

data/lib/recourse/columns.rb

@@ -0,0 +1,80 @@
+# Reopened for the order a row reads in, which a table, a show page and a form all ask
+# for the same way.
+module Recourse
+  # Which part of a row a column belongs to. What a column holds is the gem's to know
+  # and where the schema put it is the host's, so both have a say: the kind picks the
+  # band, and the order inside the band is the one the table already has. Extended onto
+  # `Recourse`, so this is `Recourse.ordered` wherever it is called from.
+  module Columns
+    # The bands, in the order a row reads. What kind of row this is and what state it is
+    # in, whose it is, what it says, its flags, the long values a narrow column suits
+    # least, when it happened, the two Rails keeps — and last of all the counts, which
+    # say nothing about the row itself, only how much hangs off it. So they close the
+    # row at the far edge rather than opening it beside the buttons they resemble.
+    #
+    # A flag follows what the row says rather than leading it. A yes or a no is narrow
+    # enough to have led on width alone, but it reads as a note *about* the row, and a
+    # reader scanning a table is looking for the name it belongs to first.
+    BANDS = %i[state reference scalar boolean long date timestamp counter].freeze
+
+    # Values that are paragraphs rather than words, under every name an adapter has for
+    # them: PostgreSQL reports `jsonb` where SQLite and MySQL report `json`.
+    LONG_KINDS = %i[text json jsonb].freeze
+
+    # And the ones that are a point in time, whichever part of one they keep.
+    DATE_KINDS = %i[date datetime time].freeze
+
+    # Whether a column holds a list of values rather than one. A PostgreSQL array
+    # reports a type wrapping a subtype, and so does a `serialize` of an Array; asked
+    # that way rather than by an adapter's own class, which only exists where that
+    # adapter is loaded. But wrapping a subtype is not enough on its own: an enum and a
+    # range always answered the same way, and since Rails 8.2 so does every decorator
+    # a column may wear — time zone conversion on a timestamp, `normalizes`, a lock. What
+    # sets a list apart is that its value is changed in place, which `Mutable` marks and
+    # none of those are.
+    def list_column?(model, column)
+      type = model.type_for_attribute column
+
+      type.respond_to?(:subtype) && type.is_a?(ActiveModel::Type::Helpers::Mutable)
+    end
+
+    # The columns of a model in the order a row reads them, given whichever of them the
+    # caller is drawing. Grouped rather than sorted: `group_by` keeps the order it was
+    # given inside each group, which is what leaves an order the schema already carries
+    # standing, and `sort_by` would not — Ruby's sort is not stable.
+    def ordered(model, names)
+      keys = reference_keys model
+
+      names.group_by { |name| BANDS.index band(model, name, keys) }.sort.flat_map(&:last)
+    end
+
+  private
+
+    # Asked in the order that settles it. A counter is one whatever it is stored as; the
+    # column Rails keeps a subclass in says what kind of row this is, as an enum says
+    # what state it is in; and a key is an integer, so it has to be recognised as a key
+    # before its type is asked about at all.
+    def band(model, name, keys)
+      return :counter if model.recourse_counters.key? name
+      return :state if name == model.inheritance_column || model.defined_enums.key?(name)
+      return :timestamp if TIMESTAMPS.include? name
+      return :reference if keys.include? name
+
+      band_of model.type_for_attribute(name).type
+    end
+
+    def band_of(kind)
+      return :boolean if kind == :boolean
+      return :long if LONG_KINDS.include? kind
+      return :date if DATE_KINDS.include? kind
+
+      :scalar
+    end
+
+    def reference_keys(model)
+      model.recourse_references.map { |reference| reference.foreign_key.to_s }
+    end
+  end
+
+  extend Columns
+end

data/lib/recourse/controllers.rb

@@ -0,0 +1,26 @@
+module Recourse
+  # Defines the controller classes a host app has not written for itself.
+  module Controllers
+    # Creates a controller for the named resource unless the host app has one. The
+    # name arrives with whatever namespace it was drawn in — `admin/contacts` — so
+    # the constant lands where Rails will look for it.
+    def self.define_missing(path, base = nil)
+      class_name = "#{path.camelize}Controller"
+      # const_defined? is true for a Zeitwerk autoload, so files on disk count too.
+      return if Object.const_defined? class_name
+
+      namespace(class_name.deconstantize).const_set class_name.demodulize,
+                                                    Class.new(base || RecoursesController)
+    end
+
+    # The module a namespaced controller belongs in, made where the host has none of
+    # its own: `namespace :admin` draws routes whether or not an `Admin` exists.
+    private_class_method def self.namespace(name)
+      name.split('::').reduce Object do |scope, part|
+        next scope.const_get part, false if scope.const_defined? part, false
+
+        scope.const_set part, Module.new
+      end
+    end
+  end
+end