layered-resource-rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfe32848fe680ff7bcbafa8c72d1d7c46a83fb48c3a440411eae26f5fe766cb3
-  data.tar.gz: 9c47bbcff2783c5423cc1d0d7360d27934ed18debbb3bedda72af65b8995b312
+  metadata.gz: 403ad781bad901c2882718ad739de8346faa81dcce400046aa2092de5c235ab3
+  data.tar.gz: a78bb873e92d3b814c87a1d989febe815baf67fdb8b74bab8c7193a53d29a7f7
 SHA512:
-  metadata.gz: 5b79478c63e11f9cd96af0df6aa89ed46e8f133ac90c2f05842d0a2f19cec7156faf70aa9f75c803a4c7655b20e771c0e11c0d6d95c2bba927582d1a30b9116b
-  data.tar.gz: 013feae5be9a1c9e717434411d7f9d2de288cff2669400ae14477a27cdc104098a0d78d45584366da675be3892dec955fd3ba6104a1f1a3f3e0903fc00518c7c
+  metadata.gz: 16d28757cc081b902fad287938d6668893b12cc17e9e39d6c0419ef79ea6908ad796236796725dadfc3c14e3540fad66bd85e579f7c0b6308d361cc654131524
+  data.tar.gz: 59cbe7172af51a80c7107792e9109d5fb4b41a2934933462ee39543b2e7e6807daa012cbdc6d3d82a220681ab913b27c6652fdabaaf51555fdfc4e5920ed3dd8

data/.claude/skills/layered-resource-rails/SKILL.md

@@ -108,6 +108,7 @@ end
 | `search_placeholder "..."` | Replaces the search box placeholder. Default derives from `search_fields` via `human_attribute_name`, so `activerecord.attributes.<model>.<attr>` i18n renames flow through (association walks resolve each half against its own model) |
 | `filters :a, :b, c: {...}` | Structured filter controls on the index — an "Add filter" popover plus removable tags. Control + Ransack predicate inferred per column; trailing hash overrides per attribute. See [Filters](#filters) |
 | `label_attribute :title` | Attribute a record is labelled by (page titles, row action menus, another resource's picker). Defaults to the `primary:` column, else the first. Falls back through `name`/`title`/`label`/`email`, then the model's own `to_s`, then `"Post #12"` |
+| `lookup_attribute :uid` | Attribute a record is looked up by from its URL `:id` (`find_by!(uid:)` within `scope`, so out of scope is still a 404), and that the gem's links put there - primary column, row actions, `link:` columns, parent breadcrumbs. Defaults to `:id` (`scope.find` + `to_param`, so FriendlyId still works). Override `self.find_record(controller, id)` / `self.record_param(record)` for anything else |
 | `default_sort attribute:, direction:` | Default sort order for the index |
 | `per_page n` | Pagination size (default 15) |
 | `root_breadcrumb "Home", "/"` | Static first crumb in the breadcrumb trail (e.g. back to the host app's dashboard). Without it, top-level resources render no trail; nested routes prepend it to the derived parent trail |
@@ -117,7 +118,7 @@ The trail always ends with the current page (collection name on `index`, record
 ### Column options
 
 - `as: :type` - pins the cell to a column partial instead of the type-inferred default. Built in: `:text`, `:datetime`, `:badge`, `:boolean`; an unrecognised type raises `ArgumentError` at render time rather than rendering an empty cell. See [Column rendering](#column-rendering)
-- `primary: true` - marks the cell that links to the record's edit (or show) page (defaults to first column)
+- `primary: true` - marks the cell that links to the record's edit (or show) page (defaults to first column). Add `link: false` to leave it unlinked - for a `render:` proc that links somewhere else itself (e.g. a conversation's own page rather than its edit form)
 - `label: "Custom"` - overrides the humanised attribute name
 - `sortable:` - whether the header renders a sort link. **Defaults to `false` for any attribute that isn't a real DB column** (virtual attributes, delegated association values), because a Ransack sort link on one 500s when clicked. Pass `sortable: true` to opt back in - you then own the associated model's `ransackable_attributes` (see [Associations](#associations))
 - `link: :route_key` - wraps the column's rendered value in a link to a nested route (e.g. `:users_posts`); composes with `as:` (pair with `as: :badge` for a badge link)
@@ -177,7 +178,7 @@ Inference by column type: `enum`/`belongs_to` -> multi-select (`_in`; `multiple:
 
 **Long option lists switch control.** A select-type filter renders as the plain list (multi-select: checkboxes + Apply; single-choice: instant-apply links) up to `Layered::Resource.filter_combobox_threshold` options (10), and as a type-ahead **combobox** past it — a checkbox list of every user is no way to pick one. A single-choice combobox posts a scalar (no `[]`), so `_eq` gets the value rather than an array. The count is taken per request, after a `collection:` callable resolves, so the control follows the data; the decision lives in `layered_filter_control` (the view helper), not in `resolved_filters`, for exactly that reason. Declaring `as:` pins the control and opts out: `as: :select` keeps the list however long, `as: :combobox` uses the combobox however short.
 
-**Remote options.** `url:` fetches the options from an endpoint as the user types instead of rendering a collection — such a filter is always a combobox (nothing to render or count). Give it as a callable (`-> { user_options_path }`) so it resolves per request in the view, where route helpers exist. The endpoint is an ordinary host-app action including `Layered::Ui::ComboboxOptions` and returning `l_ui_combobox_options(scope, label:, search:)` — the gem never routes it, so it's authorised however any index is. Since the browser has no collection to look a label up in, an active remote filter's values are labelled server-side from the records (same `name`/`title`/`label`/`email` fallbacks), so the tag reads "User: Alice" not "User: 12"; a `url:` over a plain column has no records and its values label themselves. `min_chars:` and `text:` pass through too; the write-side options (`create:`, `create_name:`, `reorder:`) deliberately don't — a filter picks among values that already exist.
+**Remote options.** `url:` fetches the options from an endpoint as the user types instead of rendering a collection — such a filter is always a combobox (nothing to render or count). Give it as a callable (`-> { user_options_path }`) so it resolves per request in the view, where route helpers exist. The endpoint is an ordinary host-app action including `Layered::Ui::ComboboxOptions` and returning `l_ui_combobox_options(scope, label:, search:)` — the gem never routes it, so it's authorised however any index is. Since the browser has no collection to look a label up in, an active remote filter's values are labelled server-side from the records (same `name`/`title`/`label`/`email` fallbacks), so the tag reads "User: Alice" not "User: 12"; a `url:` over a plain column has no records and its values label themselves. The label lookup is confined to records the resource's `scope(controller)` references (via the foreign key), so a hand-edited id outside it - e.g. another tenant's user - labels itself instead of leaking a name; the cost is that an in-scope option with no matching records also shows its raw id. `min_chars:` and `text:` pass through too; the write-side options (`create:`, `create_name:`, `reorder:`) deliberately don't — a filter picks among values that already exist.
 
 **The blank a combobox posts.** `l_ui_combobox` emits a leading blank hidden input so clearing every token submits an empty collection rather than omitting the key. Ransack prunes blanks from an `_in` array itself, and `layered_filter_query_params` prunes them too — an array left with nothing becomes an explicit `""`, the same shape the Clear link writes, so the tag reads as inactive *and* a `default:` doesn't immediately re-apply.
 

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file. This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.4.0] - 2026-10-04
+
+### Added
+
+- `lookup_attribute :uid` on a resource looks its records up by an attribute other than `id` - an unguessable token, a slug - with `find_by!` inside `scope`, so a record outside it is still a 404. The gem's own links (the primary column, row actions, `link:` columns into a nested resource, and parent breadcrumbs) put the same attribute in the URL. The default stays `:id`, with `scope.find` and `to_param` as before. `find_record(controller, id)` and `record_param(record)` are the override points behind it
+- `link: false` on a column leaves the primary column unlinked, for a `render:` proc that links somewhere other than the edit form itself. Before, the gem wrapped such a proc's link in its own
+
+## [0.3.1] - 2026-10-04
+
+### Security
+
+- A remote (`url:`) `belongs_to` filter no longer labels records outside the resource's `scope`. Its current values come from the query string, and the labels for the tag and combobox tokens were looked up with an unscoped `klass.where(id: ...)`, so hand-editing the id (`?q[user_id_in][]=`) revealed the name or e-mail of any record, including another tenant's. The lookup now only reads records the resource's `scope(controller)` references through the foreign key. Any other value shows its raw id instead.
+
 ## [0.3.0] - 2026-09-21
 
 ### Changed

data/README.md

@@ -205,6 +205,18 @@ end
 
 When the attribute has no value, the label falls back to the first of `name`/`title`/`label`/`email` that does, then to the model's own `to_s` if it defines one, and finally to `"Post #12"` — never a bare `#<Post:0x...>`.
 
+**Lookup attribute:** records are looked up by the `:id` in their URL, the Rails way: member links use `to_param` and the lookup is `scope.find`. Declare `lookup_attribute` when records are addressed by something else - an unguessable token, say, so ids can't be enumerated:
+
+```ruby
+class ConversationResource < Layered::Resource::Base
+  model Conversation
+
+  lookup_attribute :uid   # /conversations/Xk3…/edit, found with find_by!(uid:)
+end
+```
+
+Every member action (`show`, `edit`, `update`, `destroy`, and custom `member` routes) finds the record by it within `scope`, so one outside the scope is still a 404. The gem's own links - the primary column, the row actions, `link:` columns into a nested resource, and parent breadcrumbs - put the same attribute in the URL. For a lookup the attribute can't express, override `self.find_record(controller, id)` (and `self.record_param(record)`, which produces the URL value).
+
 **Custom scope (e.g. tenant isolation):**
 
 ```ruby
@@ -564,7 +576,7 @@ end
 
 A remote combobox has no collection in the browser to look a label up in, so an active filter's current values are labelled server-side from the records themselves (the same `name`/`title`/`label`/`email` fallbacks) — the tag reads "User: Alice", not "User: 12". A `url:` on a plain column has no records to read, so its values label themselves.
 
-> **Label lookups are not scoped.** Whatever scoping the `url:` endpoint applies covers the options it *serves*; it does not cover the labels. Current values arrive in the query string, and the gem labels them with an unscoped `klass.where(id: ...)` — so hand-editing `?q[user_id_in][]=` to an id outside the endpoint's scope still renders that record's label in the tag and the combobox token. This is the same position a `belongs_to` filter's default `klass.all` options take, and it discloses one label at a time; treat it as a reason not to rely on a filter's option scoping to keep an association's names or e-mail addresses private.
+Current values arrive in the query string, so they can be hand-edited to any id — and the gem can't see whatever scoping the `url:` endpoint applies. Labels are therefore only read for records the resource's own `scope` references (users with a post the viewer can see, say); any other value labels itself. A guessed `?q[user_id_in][]=` for another tenant's user shows "User: 42", not their name. The flip side is that a value from the endpoint with no matching records in scope also shows its id, next to an empty table. (A `belongs_to` filter *without* `url:` renders `klass.all` as its options — pass a scoped `collection:` if those labels are private.)
 
 `min_chars:` and `text:` pass through to `l_ui_combobox` alongside `url:`. The write-side combobox options (`create:`, `create_name:`, `reorder:`) don't: a filter picks among values that already exist.
 
@@ -639,6 +651,15 @@ column a `render:` proc that produces the value.
 
 A column with a `render:` proc is exempt - the proc decides what to call, and `attribute:` is then just the header and sort key.
 
+The primary column links to the record's edit page (or its show page when the resource isn't editable). Pass `link: false` to leave it unlinked - when its `render:` proc links somewhere more useful itself, say:
+
+```ruby
+columns [
+  { attribute: :name, primary: true, link: false,
+    render: ->(record, view) { view.link_to(record.name, view.conversation_path(record)) } }
+]
+```
+
 ### Sortable headers
 
 A column header renders a sort link only when the attribute is sortable. This defaults to `true` for real DB columns and `false` for anything else - virtual attributes and delegated association values - because Ransack can't sort those without the associated model allowlisting the underlying field, and the sort link would 500 when clicked. Set `sortable: true` on the column to opt back in; you're then responsible for that model's `ransackable_attributes` (see [Associations](#associations)).
@@ -917,17 +938,16 @@ cd test/dummy && bin/rails db:setup && bin/dev
 
 ### Deploying the dummy app
 
-The dummy app can be deployed with [Kamal](https://kamal-deploy.org). Set the required environment variables and deploy from `test/dummy`:
+The dummy app can be deployed with [Kamal](https://kamal-deploy.org). Copy `.env.deploy.example` to `.env.deploy` (gitignored), fill in `KAMAL_DEPLOY_IP`, `KAMAL_DEPLOY_DOMAIN`, and `KAMAL_SSH_KEY`, then run `bin/deploy`:
 
 ```bash
-cd test/dummy
-export KAMAL_DEPLOY_IP=<server-ip>
-export KAMAL_DEPLOY_DOMAIN=<domain>
-export KAMAL_SSH_KEY=<path-to-ssh-key>
-kamal deploy
+cp .env.deploy.example .env.deploy
+bin/deploy setup   # first run on a new server
+bin/deploy         # kamal deploy
+bin/deploy logs    # any other kamal subcommand passes straight through
 ```
 
-`KAMAL_DEPLOY_DOMAIN` defaults to `layered-resource-rails.layered.ai`. `SECRET_KEY_BASE` is read from `test/dummy/.kamal/secrets`, which is gitignored - create it locally before the first deploy.
+`SECRET_KEY_BASE` is read from `test/dummy/.kamal/secrets`, which is gitignored - create it locally before the first deploy.
 
 ## Contributing
 

data/app/controllers/layered/resource/controller.rb

@@ -63,7 +63,7 @@ module Layered
       end
 
       def show
-        @record = @resource.scope(self).find(params[:id])
+        @record = @resource.find_record(self, params[:id])
         authorize_layered_record(@record)
         @page_title = layered_record_label(@record)
       end
@@ -89,14 +89,14 @@ module Layered
       end
 
       def edit
-        @record = @resource.scope(self).find(params[:id])
+        @record = @resource.find_record(self, params[:id])
         authorize_layered_record(@record)
         @form_url = layered_member_path(@record)
         @page_title = "Edit #{layered_record_label(@record)}"
       end
 
       def update
-        @record = @resource.scope(self).find(params[:id])
+        @record = @resource.find_record(self, params[:id])
         authorize_layered_record(@record)
         if @record.update(layered_resource_params)
           redirect_to @resource.after_save_path(self, @record),
@@ -109,7 +109,7 @@ module Layered
       end
 
       def destroy
-        @record = @resource.scope(self).find(params[:id])
+        @record = @resource.find_record(self, params[:id])
         authorize_layered_record(@record)
         redirect_path = @resource.after_save_path(self, @record)
         model_name = @resource.model.model_name.human
@@ -217,7 +217,7 @@ module Layered
 
       # For custom member actions declared in a `layered_resources` block,
       # populate @record from params[:id] so action bodies don't have to
-      # repeat `@resource.scope(self).find(params[:id])`. Skip this with
+      # repeat `@resource.find_record(self, params[:id])`. Skip this with
       # `skip_before_action :load_layered_member_record, only: [:foo]` if
       # the action doesn't need the record (or shouldn't 404 on a missing
       # one).
@@ -228,7 +228,7 @@ module Layered
         member_actions = @_route_entry[:member_actions] || []
         return unless member_actions.include?(action_name.to_sym)
 
-        @record = @resource.scope(self).find(params[:id])
+        @record = @resource.find_record(self, params[:id])
         authorize_layered_record(@record)
       end
 

data/app/controllers/layered/resource/internal/breadcrumbs.rb

@@ -35,9 +35,10 @@ module Layered
               # parent that lives in the same namespace.
               collection_key = parent_collection_keys[key]
               collection_entry = collection_key && Layered::Resource::Routing.lookup(collection_key)
+              parent_resource = collection_entry && collection_entry[:resource].constantize
               model_class =
-                if collection_entry
-                  collection_entry[:resource].constantize.model
+                if parent_resource
+                  parent_resource.model
                 elsif current_namespace
                   "#{current_namespace}::#{model_name.classify}".safe_constantize ||
                     model_name.classify.safe_constantize
@@ -67,11 +68,13 @@ module Layered
 
               # Add the specific record breadcrumb, linked to its own show
               # page when the parent resource has one - a crumb that isn't
-              # the current page shouldn't be a dead end.
-              record = model_class.find_by(id: params[key])
+              # the current page shouldn't be a dead end. The param holds
+              # whatever the parent resource addresses its records by.
+              lookup_attribute = parent_resource ? parent_resource.lookup_attribute : :id
+              record = model_class.find_by(lookup_attribute => params[key])
               if record
                 label = record.try(:name) || record.try(:title) || "#{model_class.model_name.human} ##{record.id}"
-                crumbs << { label: label, path: layered_parent_record_path(collection_entry, collection_key, ancestor_args, record) }
+                crumbs << { label: label, path: layered_parent_record_path(collection_entry, parent_resource, collection_key, ancestor_args, record) }
               end
 
               crumbs
@@ -82,7 +85,7 @@ module Layered
         # The parent record's show path, or nil when the parent isn't a
         # layered resource, doesn't route :show, or can't be addressed
         # from here.
-        def layered_parent_record_path(collection_entry, collection_key, ancestor_args, record)
+        def layered_parent_record_path(collection_entry, parent_resource, collection_key, ancestor_args, record)
           return nil unless collection_entry && ancestor_args
           return nil unless collection_entry[:actions].include?(:show)
 
@@ -90,7 +93,7 @@ module Layered
           helper = :"#{collection_key.to_s.singularize}_path"
           return nil unless rs.url_helpers.method_defined?(helper)
 
-          rs.url_helpers.send(helper, default_url_options.merge(ancestor_args).merge(id: record.to_param))
+          rs.url_helpers.send(helper, default_url_options.merge(ancestor_args).merge(id: parent_resource.record_param(record)))
         end
       end
     end

data/app/controllers/layered/resource/internal/columns.rb

@@ -154,7 +154,8 @@ module Layered
         # and only falls back to show for read-only resources that still
         # expose a detail page. The "primary" column is the one marked
         # primary: true (or the first column if none is). Columns that already
-        # declare a custom link: are left alone.
+        # declare a custom link: are left alone, and `link: false` leaves the
+        # column unlinked - for a `render:` proc that links somewhere else.
         def apply_primary_column_link
           singular = @layered_route_key.singularize
           helper = if @resource_can_edit
@@ -172,13 +173,13 @@ module Layered
 
           @columns = @columns.each_with_index.map do |col, i|
             next col unless i == primary_index
-            next col if col[:link]
+            next col if col.key?(:link)
 
             inner_render = col[:render]
             col.merge(
               render: ->(record) {
                 value = inner_render.call(record)
-                view.link_to value, routes_proxy.send(helper, record), data: { turbo_frame: "_top" }
+                view.link_to value, routes_proxy.send(helper, @resource.record_param(record)), data: { turbo_frame: "_top" }
               }
             )
           end
@@ -224,7 +225,10 @@ module Layered
                 value = inner_render.call(record)
                 args = opts.dup
                 ancestor_params.each { |p| args[p] = record.public_send(p) }
-                args[immediate_parent] = record.id
+                # The parent is this resource's record, so it goes in the URL
+                # the way this resource's own links put it - its id unless
+                # the resource declares a `lookup_attribute`.
+                args[immediate_parent] = @resource.lookup_attribute == :id ? record.id : @resource.record_param(record)
                 path = rs.url_helpers.send(path_helper, args)
                 view.link_to value, path, data: { turbo_frame: "_top" }
               }

data/app/controllers/layered/resource/internal/routing.rb

@@ -52,7 +52,7 @@ module Layered
                   "No #{action || 'member'} route registered for #{@layered_route_key}. " \
                   "Include the matching action in only:."
           end
-          layered_routes.send(helper, record)
+          layered_routes.send(helper, @resource.record_param(record))
         end
       end
     end

data/app/helpers/layered/resource/filters_helper.rb

@@ -286,15 +286,23 @@ module Layered
 
       # Value => label for the filter's currently-set values. A remote filter
       # has no collection to read them from, so an association's are looked up
-      # by id; anything else (a remote filter over a plain column) resolves to
+      # by key; anything else (a remote filter over a plain column) resolves to
       # nothing and the value stands in for its own label.
+      #
+      # The values come straight from the query string, and the gem can't see
+      # whatever scoping the `url:` endpoint applies, so the lookup is confined
+      # to records the resource's own `scope` references: a hand-edited id for,
+      # say, another tenant's user labels itself rather than disclosing that
+      # user's name.
       def layered_filter_option_labels(filter, values)
         if filter[:url].present?
           reflection = filter[:reflection]
           return {} if reflection.nil?
 
-          reflection.klass.where(id: values)
-                    .to_h { |record| [record.id.to_s, layered_filter_record_label(record)] }
+          primary_key = reflection.association_primary_key
+          referenced = @resource.scope(controller).unscope(:order).select(reflection.foreign_key)
+          reflection.klass.where(primary_key => values).where(primary_key => referenced)
+                    .to_h { |record| [record.public_send(primary_key).to_s, layered_filter_record_label(record)] }
         else
           layered_filter_collection(filter).to_h { |label, value| [value, label] }
         end

data/lib/layered/resource/base.rb

@@ -126,6 +126,40 @@ module Layered
           Layered::Resource.record_label(record, attribute: label_attribute)
         end
 
+        # The attribute a record is looked up by from the `:id` in its URL,
+        # and that the gem's own member links put there. Defaults to `:id`,
+        # which keeps Rails' own behaviour: links use `to_param` and the
+        # lookup is `scope.find`, so a gem that overrides both (FriendlyId,
+        # say) still works. Declare it when records are addressed by
+        # something else - an unguessable token, a slug:
+        #
+        #   lookup_attribute :uid
+        def lookup_attribute(value = nil)
+          if value
+            @lookup_attribute = value.to_sym
+          else
+            inherited_attribute(:@lookup_attribute) || :id
+          end
+        end
+
+        # The record named by `id`, within `scope` - raising
+        # ActiveRecord::RecordNotFound (a 404) when it is outside it. Every
+        # member action looks its record up through here, so override it for
+        # a lookup `lookup_attribute` can't express.
+        def find_record(controller, id)
+          relation = scope(controller)
+          return relation.find(id) if lookup_attribute == :id
+
+          relation.find_by!(lookup_attribute => id)
+        end
+
+        # What a member URL carries for `record`: the inverse of `find_record`.
+        def record_param(record)
+          return record.to_param if lookup_attribute == :id
+
+          record.public_send(lookup_attribute).to_s
+        end
+
         # Declares structured filter controls for the index table. Each entry
         # is either a bare attribute (control + Ransack predicate inferred from
         # the column type, enum, or association) or an attribute with an

data/lib/layered/resource/version.rb

@@ -1,5 +1,5 @@
 module Layered
   module Resource
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: layered-resource-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - layered.ai
@@ -288,7 +288,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Convention-over-configuration CRUD for Rails 8+ with Ransack and Pagy built
   in.