layered-resource-rails 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8bc9f9c8cd7248c93dcfe75e5af6c62e73f15e12f7a6a2092b213bbf3c5ffaf3
-  data.tar.gz: bc8992afbc303af01d63f9a0d86e01e3141e5cff9b47b4f6d61db7b7d68c560a
+  metadata.gz: 403ad781bad901c2882718ad739de8346faa81dcce400046aa2092de5c235ab3
+  data.tar.gz: a78bb873e92d3b814c87a1d989febe815baf67fdb8b74bab8c7193a53d29a7f7
 SHA512:
-  metadata.gz: 91a5a65b3a8b3ac9108046f040e9b38d5ad58e79cd457343cea5d25cedf8c37a16d4077fcaf7d12f5a7da0ecbfa07e293c88169342048f82bc508df47d1606f1
-  data.tar.gz: eaf791793476475fc62b310fe841c186fb23561302aad6e26a06fe0f6f4c975de37e32f1fdc4360af9b3f1eb1ad41a48a34587af9939e5a72603ebed08246ede
+  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)

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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

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
@@ -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/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.1"
+    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.1
+  version: 0.4.0
 platform: ruby
 authors:
 - layered.ai