recourse 5.2.0 → 5.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70333646b284ff615c653da393325f5ea94bb7bd04f73f46b9bff27e5d693a1c
-  data.tar.gz: 1b386bf8262585fa5d3d5493e4297ea3521bac6105f8f9fffba64ecbdc7bd12d
+  metadata.gz: 0c224b5ff48a88afa37e70da5d2157d9b5229eccdc02d7d9f8ce1b85e4df31d8
+  data.tar.gz: 50da170bddd967baba9c46c276e61f750694465a2c2e11c5fe09c5e59cc84eff
 SHA512:
-  metadata.gz: 88b168334941dfe01535414620b28dffea6ceedf1583e023f586b71f33c5f6eda669c900a45bd293b28c0d2b2f262c89bfd276f6bc396f08f05bc1c9a2e062c9
-  data.tar.gz: b890abc1502680ad0fcbf1ba27bfcbca86743bbb051d2e30bc9ea171cc87f495885baa8158c3b672efb7549b64370fc2e9068883a9ecbc2c2f522d8d2ffe6c86
+  metadata.gz: 91bc98cadd2186f29b342da8804c0926f523656aec2149e8025393c4c3ba3ec034e1ae359732cb81368192ac00b70f484731640227692c18b4c5d1ed09adac1f
+  data.tar.gz: a0565fb334f552e1a403af4db94f8d878f25ae5473e6af167304785fc017d42e392e9276ece5b2fcd4475fe48511cac8216a670adc23f8269f9ee8b931573c4f

data/CHANGELOG.md

@@ -7,6 +7,42 @@ For more information about changelogs, check [Keep a Changelog](http://keepachan
 
 ## [Unreleased]
 
+## 5.3.0 - 2026-09-16
+
+* [Feature] A record's files are a field, a value and a page
+
+  Back from the 4.0.0 development tree: a `has_one_attached` is a file field on the form
+  and a value on the record's page, a `has_many_attached :photos` beside
+  `recourses :photos, only: %i[index destroy]` under the record is a table of Active
+  Storage's blobs — searched, sorted and paged like any other — and a submitted file is
+  attached after the save rather than assigned, so an edit that touched only a name never
+  purges what the record had. New this time: a file a browser can be shown is a picture
+  first, a `<picture>` 100 pixels tall of a representation made 200 tall — WebP at quality
+  80 with its metadata stripped where the browser takes it, the file's own kind where not
+  — in the link that opens the whole file inline — the image scaled, or the frame a
+  previewer takes of a video or a PDF where the host has `ffmpeg` or `poppler` — on the
+  table and on the record's page alike. And a Delete on each row of the table, which
+  takes the file off the record and leaves the blob to Active Storage. Files are still
+  added on the record's form, and a shelf is still not counted on its tab: there is no
+  `belongs_to` to hang a counter cache on.
+
+* [Feature] A table routed `destroy` without `edit` offers Delete on each row
+
+  The Delete button stood on the edit page and nowhere else, so a resource with a
+  `destroy` and no `edit` — a file attached to a record, a row joining two — had no way to
+  be deleted from the gem's own screens. Its table now draws a third action column, the
+  trash icon in `fg-danger`, a `button_to` carrying the same confirmation the edit page's
+  button does. A table whose rows have an edit page is unchanged.
+
+* [Fix] A filter narrows a table again
+
+  A combobox became a `<select>` in 5.0.0 and its picks are submitted one value each, but the
+  search read them the way it read the comma-joined string before it — so `q[team_id_in][]=1`
+  arrived as the array `["1"]`, was written out as the one value `["1"]`, and was cast to the
+  id 0 no row holds. Every filter menu in the gem came to an empty table, whatever was ticked.
+  The picks are now taken as the values they arrive as, and `All …`, which submits one empty
+  value, is no filter rather than a filter nothing answers.
+
 ## 5.2.0 - 2026-09-14
 
 * [Feature] A table of places can be read as a map

data/README.md

@@ -47,7 +47,8 @@ Every recourse with `new` or `edit` gets a form with appropriate browser formatt
 
 <img width="3824" height="1220" alt="Image" src="https://github.com/user-attachments/assets/ebe5108b-bbd1-4cd1-a635-89eef0e6fc50" />
 
-Every recourse with `destroy` gets a button with a detailed confirmation message:
+Every recourse with `destroy` gets a button with a detailed confirmation message — on its
+edit page, or on each row of its table where no `edit` is routed:
 
 [image]
 
@@ -123,37 +124,76 @@ A controller the app already defines is left alone.
 
 ## Step 5. Enjoy the extras
 
-Here are some bonus features the gem provides. Customize them by editing their values in
-your `config/initializers/recourse.rb` file:
+The rest of what the gem offers, in four parts. The first two are a line each in
+`config/initializers/recourse.rb`; the last two need nothing beyond what the model
+already declares.
 
-- [`Recourse.color=`](https://rubydoc.info/gems/recourse/Recourse#color%3D-class_method):
-  which Bootstrap family is primary on every page.
-- [`Recourse.theme=`](https://rubydoc.info/gems/recourse/Recourse#theme%3D-class_method):
-  which color scheme every page is drawn in, one of `Recourse::THEMES.keys` — eight from
-  code editors and Bootstrap's own. Readers rotate through them, light and dark, from the
-  moon at the foot of the sidebar; their choice stays in their browser.
-- [`Recourse.bookmarks=`](https://rubydoc.info/gems/recourse/Recourse#bookmarks%3D-class_method):
-  a Proc answering the viewer's bookmark rows. Every table of a model with a `has_many`
-  at that class then opens with a square to keep a row by, kept rows first.
+### Color and theme
+
+[`Recourse.color=`](https://rubydoc.info/gems/recourse/Recourse#color%3D-class_method)
+says which Bootstrap family is primary on every page, and
+[`Recourse.theme=`](https://rubydoc.info/gems/recourse/Recourse#theme%3D-class_method)
+says which color scheme the pages are drawn in — one of `Recourse::THEMES.keys`: eight
+palettes taken from code editors, plus Bootstrap's own.
 
 ```ruby
 Recourse.color = :orange
 Recourse.theme = :nord
+```
+
+The theme is where a reader starts, not where they stay. The moon at the foot of the
+sidebar rotates through every palette, light and dark, and the one they pick stays in
+their browser.
+
+### Bookmarks
+
+[`Recourse.bookmarks=`](https://rubydoc.info/gems/recourse/Recourse#bookmarks%3D-class_method)
+takes a Proc answering the rows the viewer has kept:
+
+```ruby
 Recourse.bookmarks = -> { Keepsake.where agent: Current.agent }
 ```
 
+A Proc rather than a relation, because at boot the viewer is nobody. Every model with a
+`has_many` at that class then opens its table with a square to keep a row by, and kept
+rows come first. A model that cannot hold a bookmark gets no column.
+
 <img width="3824" height="1220" alt="Image" src="https://github.com/user-attachments/assets/d1db4adb-0b5c-4e41-8bb6-cf72a35288f0" />
 
+### Attachments
+
+What a model keeps as files needs nothing declared either. A `has_one_attached :logo` is
+a file field on the form and, on the record's page, the picture Active Storage makes of
+the file — 100 pixels tall, WebP where the browser takes it, opening the whole file in a
+new tab — or the file's name where nothing can be drawn of it.
+
+A `has_many_attached :photos` earns a page of its own, nested under the record:
+
+```ruby
+recourses :photos, only: %i[index destroy]
+```
+
+That page is a table of the files with their pictures, and a Delete on each row that
+takes the file off the record. Files are added on the record's own form, where a chosen
+file joins a shelf and replaces a single one, and a field nobody touched leaves
+everything as it was. `recourse_hidden :photos` keeps a file off every screen the way it
+keeps a column off.
+
+Drawing a picture of an image needs `image_processing`; video and PDF also need the
+host's `ffmpeg` and `poppler`.
+
+### Maps
+
 A table whose model keeps a `google_place_id`, or a `latitude` and a `longitude`, can be
 read as a Google map of the same page: the footer under it offers `Display as map`, and
 `/counties.map` draws this page's rows in the frame and over the footer the table has, so
-search, sort and pages work the same on either shape. A place ID is filled in as an area
-where the model is a geography Google draws boundaries for — a `State`, a `County`, a `City`
-or a `ZIP`, by name — and pinned at the place for any other model; a point is a pin. The key
-and the map ID are the host's credentials, and the map's style has the matching **Feature
-layers** turned on in the Cloud console — Postal code for ZIPs, Administrative area level 2
-for counties. A host with a Content Security Policy allows `maps.googleapis.com` for scripts
-and connections and Google's tile hosts for images.
+search, sort and pages work the same on either shape.
+
+A point is a pin. A place ID is filled in as an area where the model is a geography
+Google draws boundaries for — a `State`, a `County`, a `City` or a `ZIP`, by name — and
+pinned at the place for any other model.
+
+The key and the map ID are the host's own credentials:
 
 ```yaml
 # config/credentials.yml.enc
@@ -162,6 +202,11 @@ google_maps:
   map_id: 4f2a…
 ```
 
+The map's style has the matching **Feature layers** turned on in the Cloud console —
+Postal code for ZIPs, Administrative area level 2 for counties. A host with a Content
+Security Policy allows `maps.googleapis.com` for scripts and connections, and Google's
+tile hosts for images.
+
 
 ## Development
 

data/app/controllers/concerns/recourse/attachment_resolution.rb

@@ -0,0 +1,44 @@
+module Recourse
+  # An index over what a record has attached rather than over a model of its own.
+  # `has_many_attached :photos` and `recourses :photos, only: :index` under the same
+  # record is the whole declaration: Rails already generates the association this
+  # reads, and Active Storage already has the model it lists.
+  module AttachmentResolution
+    extend ActiveSupport::Concern
+
+  private
+
+    # The attachment this page lists, or nil where the name is a model like any
+    # other. `has_one_attached` is not one: a single file is a value on the record's
+    # own page, and a table of one row says less than the field it replaced.
+    def attachment_reflection
+      return unless defined?(ActiveStorage::Reflection) && attachment_parent
+
+      reflection = attachment_parent.class.attachment_reflections[controller_name]
+
+      reflection if reflection.is_a? ActiveStorage::Reflection::HasManyAttachedReflection
+    end
+
+    # The record the path names, asked before the model is settled: a blob holds no key
+    # pointing back at what it hangs off, and what this page is about turns on which
+    # record that is. The same lookup `find_parent` falls back on, kept for the request.
+    def attachment_parent
+      return @attachment_parent if defined? @attachment_parent
+
+      @attachment_parent = path_parent
+    end
+
+    # The blobs themselves, through the association `has_many_attached` generated —
+    # a real relation, so the search, the sort and the page all still apply.
+    def attachment_relation
+      attachment_parent.association(:"#{controller_name}_blobs").reader
+    end
+
+    # The row joining the record to one of its files, which is what a delete on this
+    # page removes: the file stays as long as anything else still points at it, and
+    # Active Storage purges it once nothing does.
+    def attachment_of(blob)
+      attachment_parent.association(:"#{controller_name}_attachments").reader.find_by! blob: blob
+    end
+  end
+end

data/app/controllers/concerns/recourse/attachment_writing.rb

@@ -0,0 +1,70 @@
+module Recourse
+  # The files a form submits, which are written after the record rather than with it.
+  # An attachment row points at an id, and a record being created has none until it is
+  # saved — so a write here is always two steps where a column's is one.
+  module AttachmentWriting
+    extend ActiveSupport::Concern
+
+  private
+
+    # A new record, then the files that came with it, in one transaction: a record
+    # half-saved is worse than one not saved.
+    def create_resource(record)
+      record.transaction { super && attach_submitted_files(record) }
+    end
+
+    # The same for one that already exists.
+    def update_resource(record)
+      super && attach_submitted_files(record)
+    end
+
+    # On a page of what a record has attached, the row between the two goes and the
+    # file stays for whatever else points at it; everywhere else the record itself goes.
+    def destroy_resource(record)
+      return super unless attachment_reflection
+
+      attachment_of(record).destroy!
+    end
+
+    # Attached rather than assigned, which is the whole reason this exists. Rails'
+    # generated writer replaces every attachment rather than adding to them, and reads
+    # a blank field as an instruction to delete the lot — so an edit that touched only
+    # a name would purge what the record had. `Attached::Many#attach` appends and
+    # `Attached::One#attach` replaces the one, which is what each means on a form.
+    #
+    # `each` answers the list it was given, which is truthy even when it is empty — so
+    # a model with nothing attached never turns a save that worked into a failure.
+    def attach_submitted_files(record)
+      Recourse.attachment_names(resource_class).each do |name|
+        files = submitted_files name
+        attached(record, name).attach(*files) if files.present?
+      end
+    end
+
+    # Built rather than read off the record: the reader Active Storage generates is
+    # reachable only by its own name, and this is the object that reader returns.
+    def attached(record, name)
+      return ActiveStorage::Attached::Many.new name, record if
+        Recourse.attachment_many? resource_class, name
+
+      ActiveStorage::Attached::One.new name, record
+    end
+
+    # What the form sent for one attachment, as a list either way. Blanks are dropped
+    # rather than trusted: the browser sends an empty file input as an empty string,
+    # and Active Storage would read a list of those as `delete everything`.
+    def submitted_files(name)
+      Array(params.dig(controller_name.singularize.to_sym, name)).compact_blank
+    end
+
+    # What a form may submit for one: a list of files where the model keeps several,
+    # and one file where it keeps one. Permitted alongside the columns, so a host
+    # running `action_on_unpermitted_parameters` at `:raise` is not tripped by a field
+    # the gem itself drew — and dropped again before anything reaches the record.
+    def attachment_filters
+      Recourse.attachment_names(resource_class).map do |name|
+        Recourse.attachment_many?(resource_class, name) ? { name => [] } : name
+      end
+    end
+  end
+end

data/app/controllers/concerns/recourse/parent_resolution.rb

@@ -12,7 +12,7 @@ module Recourse
 
     # The record a key points at where the resource has one, and otherwise the record
     # the path names: a page nested by the path alone — the memos of a team no memo
-    # belongs to — still sits under something.
+    # belongs to, the blobs a record has attached — still sits under something.
     def find_parent
       @recourse_parent_association = parent_association
       @recourse_parent = @recourse_parent_association ? parent_model.find(parent_id) : path_parent
@@ -34,7 +34,7 @@ module Recourse
     # What the route settled and every action honours: the index lists rows carrying
     # these columns, and `new` and `create` build records that do.
     def parent_columns
-      return {} if @recourse_parent_association.nil?
+      return {} if attachment_reflection || @recourse_parent_association.nil?
 
       { @recourse_parent_association.foreign_key => @recourse_parent.id }
     end

data/app/controllers/concerns/recourse/reference_resolution.rb

@@ -22,6 +22,10 @@ module Recourse
       record.update attributes
     end
 
+    # And the record gone. `destroy!`, so a callback that stops one says so rather than
+    # leaving the page claiming it worked.
+    def destroy_resource(record) = record.destroy!
+
     # A foreign key whose label is typed arrives as that label, so it is looked up
     # here. Nothing found leaves the key nil, and `belongs_to` reports it missing.
     def resolve_references(attributes)

data/app/controllers/concerns/recourse/resource_resolution.rb

@@ -25,8 +25,13 @@ module Recourse
       false
     end
 
-    # The model the route is named after.
-    def resource_class = recourse_model
+    # The model the route is named after — or Active Storage's, where the name is
+    # something the parent has attached rather than a model of this app's own.
+    def resource_class
+      return ActiveStorage::Blob if attachment_reflection
+
+      recourse_model
+    end
 
     # The model this screen is about, and the second thing a host overrides to put a
     # page of its own behind a screen the gem otherwise draws whole:
@@ -39,7 +44,11 @@ module Recourse
       Recourse.model controller_name
     end
 
+    # What the page calls one of its rows: the model's own word, or the route's for a
+    # page of files — `Photo was deleted.`, never `Blob`.
     def human_name
+      return controller_name.singularize.humanize if attachment_reflection
+
       resource_class.model_name.human
     end
 
@@ -50,15 +59,17 @@ module Recourse
     # `def resource_params = params.expect(provider: %i[name cid])`.
     def resource_params
       # The parent is merged after resolving, so the one the route names is never
-      # mistaken for a label.
-      submitted_attributes.merge parent_columns
+      # mistaken for a label; the files go no further than the permit that let them
+      # through, being attached rather than assigned.
+      submitted_attributes.except(*Recourse.attachment_names(resource_class))
+                          .merge parent_columns
     end
 
     # What the form sent, with a typed reference read back as the id it names. A bare
     # `Create` submits no attributes at all, so the key may be absent: the parent a
     # nested route names is everything such a record starts from.
     def submitted_attributes
-      permitted = Recourse.editable_columns resource_class
+      permitted = Recourse.editable_columns(resource_class) + attachment_filters
       key = controller_name.singularize.to_sym
       return {} unless params.key? key
 

data/app/controllers/recourse/base_controller.rb

@@ -3,7 +3,7 @@ module Recourse
   # its own behavior above it — `class RecoursesController < Recourse::BaseController`
   # with a `before_action :authenticate!` guards every screen the gem serves.
   class BaseController < ApplicationController
-    include Pagy::Method,
+    include Pagy::Method, AttachmentResolution, AttachmentWriting,
             Landing, Paging, ListResolution, ParentNaming,
             ParentResolution, ReferenceResolution, ResourceResolution,
             Zoning
@@ -64,7 +64,7 @@ module Recourse
     # Deletes the record and shows the index without it. `destroy!`, so a callback that
     # stops one says so rather than leaving the page claiming it worked.
     def destroy
-      @recourse.destroy!
+      destroy_resource @recourse
       wrote t('recourse.deleted', model: human_name)
     end
 
@@ -80,6 +80,8 @@ module Recourse
     # `def recourse_relation = County.with_boosts_for(@recourse_parent)`. Private, so
     # overriding it adds a query and never an action.
     def recourse_relation
+      return attachment_relation if attachment_reflection
+
       resource_class.where parent_columns
     end
   end

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

@@ -1,3 +1,6 @@
 <% editable_columns.each do |name| -%>
   <%= field name %>
 <% end -%>
+<% attachment_names.each do |name| -%>
+  <%= attachment_field name %>
+<% end -%>

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

@@ -1,4 +1,8 @@
 <% record = local_assigns[resource_key] -%>
+<%# A file is a picture before it is a row, where there is a picture to draw. -%>
+<% if blob_resource? -%>
+  <%= column header: t('recourse.preview') do %><%= blob_preview record %><% end %>
+<% end -%>
 <% 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/_values.html.erb

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

data/config/locales/recourse.en.yml

@@ -13,6 +13,13 @@ en:
     all_values: All
     as_map: Display as map
     as_table: Display as table
+    # One message in four spellings: what a record is holding, under the field that
+    # adds to it.
+    attached:
+      many: "%{count} files attached (%{files})"
+      none: No file attached
+      none_many: No files attached
+      one: 1 file attached (%{files})
     blank: "—"
     bookmark: Bookmark
     bookmark_added: Bookmark added
@@ -27,6 +34,7 @@ en:
     darken: Dark
     delete: Delete %{model}
     deleted: "%{model} was deleted."
+    destroy: Delete
     exit: Exit
     displaying:
       one: Displaying 1 item
@@ -54,6 +62,7 @@ en:
     none: "No %{models}."
     optional: Optional
     per_page: "%{limit} per page"
+    preview: Preview
     ambiguous: "matches more than one record, so it does not say which: %{label}"
     reference: "%{model} %{attribute}"
     reveal: Show

data/lib/recourse/attachments.rb

@@ -0,0 +1,28 @@
+# Reopened for what a record keeps beside its columns, which a form, a show page and
+# the params a write permits each have to ask a model about.
+module Recourse
+  # What Active Storage was told a model has attached. Extended onto `Recourse`, so
+  # every one of these is `Recourse.something` wherever it is called from.
+  module Attachments
+    # The attachments a screen offers, in the order the model declared them, less
+    # whatever it asked to keep off one: `recourse_hidden :photos` hides a file exactly
+    # as it hides a column. Empty for a class Active Storage never reached — a host
+    # that installed none of it — which is the same guard `AttachmentResolution`
+    # already carries as `defined?(ActiveStorage::Reflection)`.
+    def attachment_names(model)
+      return [] unless model.respond_to? :attachment_reflections
+
+      model.attachment_reflections.keys - hidden_columns(model)
+    end
+
+    # Whether that name holds several files or one, which is the only thing a field and
+    # a write each need to know about it: a field offers `multiple` for the one and not
+    # the other, and a write appends to the one where it replaces the other. Read off
+    # the reflection's own `macro`, so neither of Active Storage's classes is named.
+    def attachment_many?(model, name)
+      model.attachment_reflections[name]&.macro == :has_many_attached
+    end
+  end
+
+  extend Attachments
+end

data/lib/recourse/blobs.rb

@@ -0,0 +1,22 @@
+module Recourse
+  # What a table of attachments reads off Active Storage's own model, which was never
+  # asked how it wanted drawing. Extended onto the blob through the load hook Rails
+  # publishes for it, so nothing here is a patch.
+  module Blobs
+    # A blob is known by the name it was uploaded under. Every other model answers
+    # `:name`, and Active Storage has no such column — point a combobox at one
+    # without this and the select raises.
+    def recourse_label = :filename
+
+    # The service's business rather than the reader's: where the file sits, what it
+    # is called there, what it hashes to, and whatever the analyzer wrote down.
+    def recourse_hidden = %i[key checksum service_name metadata]
+
+    # Newest first, which is the order somebody looking at what was attached wants.
+    def recourse_order = { created_at: :desc }
+  end
+end
+
+ActiveSupport.on_load :active_storage_blob do
+  extend Recourse::Blobs
+end

data/lib/recourse/helpers/actions.rb

@@ -1,16 +1,18 @@
 module Recourse
   module Helpers
-    # The action columns a row opens with: a look at a record, then a change to it.
+    # The action columns a row opens with: a look at a record, a change to it, and —
+    # where the routes drew nowhere else to put it — the end of it.
     module Actions
-      # The two pages a record has, named as the concepts an icon set knows rather
-      # than as one set's own word for them, so what draws them is Unicon's business
-      # here as everywhere else. A row's links and a card's tabs read the same map,
-      # so the two cannot drift apart — and its order is the order a row opens with.
-      ICONS = { show: :view, edit: :edit }.freeze
+      # The pages a record has and the one thing done to it without a page, named as
+      # the concepts an icon set knows rather than as one set's own word for them, so
+      # what draws them is Unicon's business here as everywhere else. A row's links and
+      # a card's tabs read the same map, so the two cannot drift apart — and its order
+      # is the order a row opens with.
+      ICONS = { show: :view, edit: :edit, destroy: :delete }.freeze
 
     private
 
-      # Which of those two this table draws a column for. Read into a local by the
+      # Which of those this table draws a column for. Read into a local by the
       # table, so the routes are asked once per render rather than twice for the
       # heading and twice more for every row.
       def resource_actions
@@ -29,14 +31,33 @@ module Recourse
 
       # Whether a record's own page is there to be linked to, wherever its routes
       # were drawn: a nested table's rows lead to the resource's own pages, the ones
-      # a nested route leaves to it, so the columns are the same either way.
+      # a nested route leaves to it, so the columns are the same either way. A delete
+      # is the exception, standing on the table only where no page would carry it.
       def resource_action?(action)
+        return destroy_action_path.present? if action == :destroy
+
         routed_action? action.to_s, resource_controller_path
       end
 
-      # The icon linking to one of those pages, or nothing where the page is not
-      # routed. Which of the two it is, is the whole difference between them.
+      # Where a row is deleted from, or nil. The Delete button stands on the edit page
+      # where the routes drew one; a resource routed `destroy` and no `edit` — a file
+      # attached to a record, a row joining two — has no page of its own to carry it,
+      # so the table does, at whichever of the two paths drew the route: the nesting's
+      # own, or the resource's. Remembered per render, since the table asks per row.
+      def destroy_action_path
+        return @recourse_destroy_path if defined? @recourse_destroy_path
+
+        paths = [controller.controller_path, resource_controller_path].uniq
+        @recourse_destroy_path = if paths.none? { |path| routed_action? 'edit', path }
+                                   paths.find { |path| routed_action? 'destroy', path }
+                                 end
+      end
+
+      # The icon linking to one of those pages, or the button that deletes the row, or
+      # nothing where the page is not routed.
       def resource_action_link(action, record)
+        return destroy_button record if action == :destroy
+
         path = resource_action_path action, record
         return unless path
 
@@ -51,6 +72,17 @@ module Recourse
 
         url_for controller: "/#{resource_controller_path}", action: action, id: record
       end
+
+      # The icon alone, red for what it does, and the same warning the edit page's button
+      # carries in front of it, which the bundle draws as its dialog.
+      def destroy_button(record)
+        path = url_for controller: "/#{destroy_action_path}", action: :destroy, id: record
+
+        button_to icon_tag(ICONS[:destroy], class: 'fg-danger'), path,
+                  method: :delete, class: 'btn btn-sm btn-link btn-icon p-0',
+                  aria: { label: t('recourse.delete', model: resource_name) },
+                  form: { data: { turbo_confirm: destroy_warning(record) } }
+      end
     end
   end
 end

data/lib/recourse/helpers/attachments.rb

@@ -0,0 +1,66 @@
+module Recourse
+  module Helpers
+    # The field a form offers for putting a file on a record, and the note under it
+    # saying what the record is holding already.
+    module Attachments
+    private
+
+      # The attachments this screen's model keeps, which the form draws after every
+      # column it has: a file input is the widest control on the page.
+      def attachment_names
+        Recourse.attachment_names resource_model
+      end
+
+      # One labelled file input, in the grid a column's field sits in. `multiple` where
+      # the model keeps several, and no hidden blank beside it: nothing here is ever
+      # assigned, so a field nobody touched is one the write passes over.
+      def attachment_field(name)
+        label = resource_model.human_attribute_name name
+
+        tag.div class: ROW do
+          safe_join [
+            @recourse_form.label(name, label, class: 'form-label'),
+            @recourse_form.file_field(name, **attachment_options(name)),
+            attached_note(name),
+          ].compact
+        end
+      end
+
+      # A file input carries none of a column's constraints, so its options are the
+      # class, the note under it, and whether it takes several files at once.
+      def attachment_options(name)
+        described = field_note_id name if resource_record&.persisted?
+        options = { class: 'form-control', aria: { describedby: described } }
+        return options unless Recourse.attachment_many? resource_model, name
+
+        options.merge multiple: true, include_hidden: false
+      end
+
+      # What the record is holding, under the field that adds to it: choosing a file
+      # joins what is there or replaces it, and which of the two it is depends on what
+      # is there. Only where there is a record to ask — a form making one has nothing
+      # attached yet, so it has nothing to report and says nothing.
+      def attached_note(name)
+        return unless resource_record&.persisted?
+
+        field_note attached_reading(name), field_note_id(name)
+      end
+
+      def attached_reading(name)
+        files = attached_filenames name
+        return attached_nothing name if files.empty?
+        return t 'recourse.attached.one', files: files.first if files.one?
+
+        t 'recourse.attached.many', count: files.size, files: files.to_sentence
+      end
+
+      # A field for one file reads `No file attached` where a field for several reads
+      # `No files attached`, since which it is decides what choosing one will do.
+      def attached_nothing(name)
+        many = Recourse.attachment_many? resource_model, name
+
+        t "recourse.attached.#{many ? 'none_many' : 'none'}"
+      end
+    end
+  end
+end

data/lib/recourse/helpers/blobs.rb

@@ -0,0 +1,80 @@
+module Recourse
+  module Helpers
+    # What a page reads off Active Storage's own objects: the row behind a file, the way
+    # to open the file itself, and the picture a browser can make of it. Paired with
+    # `Recourse::Blobs`, which is what tells the blob model how it wants drawing.
+    module Blobs
+      # How tall a preview stands on the page. The picture behind it is made twice as
+      # tall, so a screen with two pixels to the point has every one of them.
+      PREVIEW_HEIGHT = 100
+
+      # How a picture is saved for the trip: lossy at a quality the eye forgives at this
+      # size, and stripped of whatever the camera wrote — neither is worth the bytes.
+      PREVIEW_SAVER = { quality: 80, strip: true }.freeze
+
+    private
+
+      # True for the filename of a blob, and for nothing else — a host model with a
+      # column of that name is drawing its own value, not Active Storage's.
+      def blob_filename?(column) = column == 'filename' && blob_resource?
+
+      # By name, so an app with no Active Storage never mentions the constant.
+      def blob_resource? = resource_model.name == 'ActiveStorage::Blob'
+
+      # The file itself, in a tab of its own: an admin opening one is leaving the page
+      # they were reading, and a file that replaced it would lose their place. Inline,
+      # so the browser shows a picture and plays a video rather than saving either.
+      # Whatever the caller hands over is what the link reads as.
+      def blob_link(blob, read)
+        link_to read, main_app.rails_blob_path(blob, disposition: :inline),
+                target: '_blank', rel: 'noopener'
+      end
+
+      # A picture of the file where Active Storage can make one — the image itself
+      # scaled down, or the frame a previewer takes of a video or a PDF — inside the link
+      # that opens the whole file. Nothing for a file nothing can draw. A `<picture>`
+      # offering WebP first, the smallest a browser can be sent, and the file's own kind
+      # under it for one that cannot take WebP; either at half the pixels it was made
+      # with, and the height is the attribute's, so no class here may say `height: auto`,
+      # as `img-thumbnail` does.
+      def blob_preview(blob)
+        return unless blob.representable?
+
+        blob_link blob, tag.picture(safe_join([preview_source(blob), preview_image(blob)]))
+      end
+
+      def preview_source(blob)
+        tag.source srcset: preview_path(blob, format: :webp, saver: PREVIEW_SAVER),
+                   type: 'image/webp'
+      end
+
+      def preview_image(blob)
+        image_tag preview_path(blob), alt: blob.filename.to_s, height: PREVIEW_HEIGHT,
+                                      class: 'border rounded', loading: 'lazy'
+      end
+
+      # The address of one scaling of the file, made on first request and kept.
+      def preview_path(blob, **saving)
+        representation = blob.representation resize_to_limit: [nil, PREVIEW_HEIGHT * 2], **saving
+
+        main_app.rails_representation_path representation
+      end
+
+      # The blobs one attachment holds, as a list whichever kind it is. Read through
+      # the associations Active Storage generated rather than through the reader it
+      # named, which is the trade `AttachmentResolution` already makes next door.
+      def attached_blobs(name)
+        return resource_record.association(:"#{name}_blobs").reader.to_a if
+          Recourse.attachment_many? resource_model, name
+
+        Array resource_record.association(:"#{name}_blob").reader
+      end
+
+      # And the names they were uploaded under, which is what a reader is told a
+      # record is holding.
+      def attached_filenames(name)
+        attached_blobs(name).map { |blob| blob.filename.to_s }
+      end
+    end
+  end
+end

data/lib/recourse/helpers/cells.rb

@@ -79,6 +79,8 @@ module Recourse
         return search_highlight named_cell(resource, association), column if association
 
         value = resource.attributes[column]
+        return blob_link resource, value if blob_filename? column
+
         counted = resource_model.recourse_counters[column]
 
         # A count is the bare number — the icon in the heading already says what it

data/lib/recourse/helpers/previews.rb

@@ -0,0 +1,40 @@
+module Recourse
+  module Helpers
+    # An attached file on a record's own page: shown where a browser can make a picture
+    # of it, and named where it cannot, either opening the file.
+    module Previews
+    private
+
+      # The attachments a record's own page reads out, which are the ones it keeps a
+      # single file under. A `has_many_attached` is a table of its own — a page a host
+      # nests under the record — and a row of pictures says more there than a list
+      # squeezed into a value's row would.
+      def shown_attachments
+        attachment_names.reject { |name| Recourse.attachment_many? resource_model, name }
+      end
+
+      # One labelled file, in the grid a column's value sits in.
+      def attachment_value(name)
+        label = resource_model.human_attribute_name name
+
+        tag.div class: ROW do
+          safe_join [tag.div(label, class: 'form-label'), attachment_control(name)]
+        end
+      end
+
+      # Nothing attached reads as the dash every other empty value reads as.
+      def attachment_control(name)
+        blob = attached_blobs(name).first
+        read = blob ? attached_file(blob) : t('recourse.blank')
+
+        tag.div read, class: 'form-control-plaintext'
+      end
+
+      # The picture where there is one to draw, and the name where there is not — a
+      # spreadsheet is a download and nothing else. Either opens the file.
+      def attached_file(blob)
+        blob_preview(blob) || blob_link(blob, blob.filename.to_s)
+      end
+    end
+  end
+end

data/lib/recourse/helpers/resources.rb

@@ -3,13 +3,22 @@ module Recourse
     # What the page is about and what it is called: the model behind it, the record
     # on it, and the words both are read out under.
     module Resources
-      # Human, plural name of the resource on the page, e.g. `Contacts`. `known_title`,
-      # since a host page wearing this layout may be named after no model at all — a
-      # contact's home is a `Location`, and the path is the only word for it.
-      def resources_name = Recourse.known_title(controller.controller_name)
+      # Human, plural name of the resource on the page, e.g. `Contacts`. A page of
+      # attachments is named after what the record calls them rather than after Active
+      # Storage's own word for the row: `Photos`, never `Blobs`. `known_title`, since a
+      # host page wearing this layout may be named after no model at all — a contact's
+      # home is a `Location`, and the path is the only word for it.
+      def resources_name
+        return controller.controller_name.humanize if blob_resource?
 
-      # Singular, lowercase name of the resource, e.g. 'contact'.
+        Recourse.known_title controller.controller_name
+      end
+
+      # Singular, lowercase name of the resource, e.g. 'contact' — and 'photo' on a page
+      # of files, for the same reason as above.
       def resource_name
+        return Recourse.downcase controller.controller_name.singularize.humanize if blob_resource?
+
         Recourse.downcase resource_model.model_name.human
       end
 
@@ -38,7 +47,8 @@ module Recourse
 
     private
 
-      # Resolved by the controller, where a host may have named a model the route does not.
+      # Resolved by the controller, which is the one that knows whether the name is a
+      # model of this app's, something a record has attached, or a model a host named.
       def resource_model
         controller_assign('recourse_model') || Recourse.model(controller.controller_name)
       end

data/lib/recourse/helpers.rb

@@ -1,4 +1,6 @@
 require_relative 'helpers/actions'
+require_relative 'helpers/attachments'
+require_relative 'helpers/blobs'
 require_relative 'helpers/bookmarks'
 require_relative 'helpers/buttons'
 require_relative 'helpers/cards'
@@ -24,6 +26,7 @@ require_relative 'helpers/names'
 require_relative 'helpers/navigation'
 require_relative 'helpers/parents'
 require_relative 'helpers/pictures'
+require_relative 'helpers/previews'
 require_relative 'helpers/references'
 require_relative 'helpers/resources'
 require_relative 'helpers/refreshes'
@@ -42,11 +45,11 @@ require_relative 'helpers/zones'
 module Recourse
   # View helpers for the pages the gem renders, and what the parts share.
   module Helpers
-    include Actions, Bookmarks, Buttons, Cards,
+    include Actions, Attachments, Blobs, Bookmarks, Buttons, Cards,
             Cells, Choices, Colors, Comboboxes, Constraints, Counters, Deletions, Densities,
             Details,
             Examples, Fields, Filters, Flashes, Formats, Inputs, Kinds, Limits, Maps,
-            Names, Navigation, Parents, Pictures, References, Refreshes,
+            Names, Navigation, Parents, Pictures, Previews, References, Refreshes,
             Routing,
             Resources, Rows, Searches, Shortcuts, Sidebars, Sorts, Tabs, Themes,
             Times, Values, Zones

data/lib/recourse/search.rb

@@ -56,18 +56,26 @@ module Recourse
 
     # Ransack reads nothing it has not been shown — `ransackable_attributes` is the
     # allowlist — so what arrives here needs no permitting, only untangling: a list
-    # predicate is split back into values, and a filter nobody set is dropped,
-    # since `IN ()` would match no row rather than every one.
+    # predicate is gathered into the values it was picked as, and a filter nobody set
+    # is dropped, since `IN ()` would match no row rather than every one.
     def conditions(params)
       # `?q=anything` reaches here as a String rather than as parameters of its own,
       # and a search nobody asked for reaches here as nil. Neither is a condition.
       return {} unless params.is_a? ActionController::Parameters
 
       params.to_unsafe_h.filter_map do |key, value|
+        value = list_values value if key.match? LIST_PREDICATES
         next if value.blank?
 
-        [key, key.match?(LIST_PREDICATES) ? value.to_s.split(',') : value]
+        [key, value]
       end.to_h
     end
+
+    # A multiple select submits one value per pick, so a list predicate arrives as an
+    # array — and as a lone value where a link carried one. Never split on a comma:
+    # that was the shape before a combobox became a `<select>`, and it read `["48"]`,
+    # the array written out, as one value, which Ransack cast to the 0 no row holds.
+    # Emptied of its blanks after, since the way back to no filter submits one.
+    def list_values(value) = Array(value).compact_blank
   end
 end

data/lib/recourse/version.rb

@@ -1,4 +1,4 @@
 module Recourse
   # Version of the gem, read by the gemspec and by hosts checking compatibility.
-  VERSION = '5.2.0'
+  VERSION = '5.3.0'
 end

data/lib/recourse.rb

@@ -4,6 +4,8 @@ require 'ransack'
 require 'unicon'
 
 require_relative 'recourse/version'
+require_relative 'recourse/attachments'
+require_relative 'recourse/blobs'
 require_relative 'recourse/bookmarks'
 require_relative 'recourse/colors'
 require_relative 'recourse/columns'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: recourse
 version: !ruby/object:Gem::Version
-  version: 5.2.0
+  version: 5.3.0
 platform: ruby
 authors:
 - claudiob
@@ -121,6 +121,8 @@ files:
 - MIT-LICENSE
 - README.md
 - app/controllers/bookmarks_controller.rb
+- app/controllers/concerns/recourse/attachment_resolution.rb
+- app/controllers/concerns/recourse/attachment_writing.rb
 - app/controllers/concerns/recourse/landing.rb
 - app/controllers/concerns/recourse/list_resolution.rb
 - app/controllers/concerns/recourse/paging.rb
@@ -156,6 +158,8 @@ files:
 - app/views/recourses/show.html.erb
 - config/locales/recourse.en.yml
 - lib/recourse.rb
+- lib/recourse/attachments.rb
+- lib/recourse/blobs.rb
 - lib/recourse/bookmarks.rb
 - lib/recourse/broadcasting.rb
 - lib/recourse/colors.rb
@@ -165,6 +169,8 @@ files:
 - lib/recourse/engine.rb
 - lib/recourse/helpers.rb
 - lib/recourse/helpers/actions.rb
+- lib/recourse/helpers/attachments.rb
+- lib/recourse/helpers/blobs.rb
 - lib/recourse/helpers/bookmarks.rb
 - lib/recourse/helpers/buttons.rb
 - lib/recourse/helpers/cards.rb
@@ -190,6 +196,7 @@ files:
 - lib/recourse/helpers/navigation.rb
 - lib/recourse/helpers/parents.rb
 - lib/recourse/helpers/pictures.rb
+- lib/recourse/helpers/previews.rb
 - lib/recourse/helpers/references.rb
 - lib/recourse/helpers/refreshes.rb
 - lib/recourse/helpers/resources.rb