layered-resource-rails 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83a0686237527aabd89c6fa83f98c8a2bbab1a02deff48528e8e5baed7f8b874
-  data.tar.gz: 744e768aff2d5c624c9a243ccfbc9d92cf80de3a559fec9c320c89d51e7e197e
+  metadata.gz: '0429425d0767f40488539bbaef1d13ef629598c52a40592ecc914d9196a6f3e7'
+  data.tar.gz: a45581d887a80412baaeab41ffc0e0310eaaeb1bd495cc11576c12d957424416
 SHA512:
-  metadata.gz: ebe053f334e9ad89c835add54f1c60bf5c8c863cb175ec42932e7d9cf0809eef73d65646a96505da64cd9062207dc722eb672d4662cad612ca70259eecac9c60
-  data.tar.gz: a148f47dc69bbd3fb799bd1b8b49d2b4bf90dbc3854e2c75fec7dd88dd5c8efcb8e99ec7af434d6c2b76370d2243ca3eb9f7d512113aeba3ae46effe8bc76194
+  metadata.gz: 7571835a600e4d34659fcfedcd6573c2593a3653fdd23f8c80fa823ea7014b3226078492b8eb217a2247ccbf500d266d77495939f07b65d5178ffed3c53e3196
+  data.tar.gz: 9e980c9c01d37611a40c6172007932e4f62ac1e58702d2a8490c5c902e920985e72a099db7a31d7b890e2a82b779806718a2e416ba32898bccebf7d5679724a0

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

@@ -39,6 +39,8 @@ This produces:
 - `app/layered_resources/post_resource.rb` with `columns` and `fields` derived from the attributes
 - `layered_resources :posts` appended to `config/routes.rb`
 
+A `references` attribute (e.g. `speaker:references`) becomes a `:speaker_id` field - inferred as a combobox of the associated records - but is left out of `columns`, since a raw foreign key is rarely the column an index wants. Polymorphic references are left out of both: setting one takes a `_type` too, so write that field yourself.
+
 Useful flags:
 
 - `--skip-model` - the model already exists
@@ -194,10 +196,14 @@ layered_resources :posts, except: [:destroy]                   # everything but
 layered_resources :posts, controller: "posts"                  # use a custom controller
 layered_resources :posts, resource: "Admin::PostResource"      # explicit resource class
 layered_resources :posts, namespace: "Admin"                   # derives Admin::PostResource and Admin::ResourcesController
+layered_resources :posts, layout: "manage"                     # render inside app/views/layouts/manage.html.erb
+layered_resources :posts, layout: false                        # render with no layout
 ```
 
 Incoherent `only:` combos raise at boot time - e.g. `:new` without `:create`, or `:edit` without `:update`.
 
+`layout:` is the hook for putting a resource on a host-app layout **without ejecting a controller** - reach for it before generating one just to write a `layout` line. It applies to every action on that route, and each route decides independently, so the same resource can be plain under `/posts` and wrapped under `/manage/posts`. A `layout` declared in an ejected controller replaces the hook and wins. Anything but a String, Symbol, or `false` raises at boot.
+
 ### Nested routes
 
 ```ruby
@@ -344,6 +350,8 @@ rails g layered:resource:views posts        # copies index/show/new/edit ERB int
 rails g layered:resource:controller posts   # generates a controller subclass for custom actions
 ```
 
+Pass the **plural** name: a singular one is pluralised (`talk` → `TalksController`) because `layered_resources` routes under the plural and `controller:` must match. Don't eject a controller just to set a layout - use the route's `layout:` option.
+
 The controller's `_prefixes` is overridden so `app/views/layered/<plural>/` overrides win automatically - no extra wiring. Delete any individual ejected template to fall back to the gem default.
 
 To outgrow the gem entirely: drop the inheritance, write a plain Rails controller, swap `layered_resources :posts` for `resources :posts` in routes.
@@ -440,6 +448,7 @@ To make an association searchable, add a Ransack-walk-shaped entry to `search_fi
 - **`NoMethodError: undefined method 'l_ui_table'`** - the host app hasn't installed `layered-ui-rails`. Run `bin/rails generate layered:ui:install`.
 - **Search/sort returns empty** - the attribute isn't in `search_fields`, or Ransack's `ransackable_attributes` on the model excludes it. The resource patches Ransack only when itself is the auth object; verify nothing in the host app removes the attribute unconditionally.
 - **`only:` validation error at boot** - `:new` requires `:create`, `:edit` requires `:update`. Adjust the action list.
+- **`<Name>Resource declares column :foo, but <Model> has no public method by that name`** - a column names something the model doesn't publicly answer to (a typo, or a private method - cells are read with `public_send`). Define or `delegate` a public method, fix the attribute name, or give the column a `render:` proc (procs are exempt from the check).
 - **Ejected view not picked up** - the controller looks under `app/views/layered/<plural_name>/`, where `<plural_name>` is the symbol passed to `layered_resources` (ignoring Rails namespaces). The generator mirrors this; if you've moved files manually, match that path.
 
 ## Further reference

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file. This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.2.0] - 2026-09-10
+
+### Routing and controllers
+
+- `layered_resources :posts, layout: "manage"` renders a resource's pages inside one of the host app's layouts, and `layout: false` renders them with no layout at all. The option belongs to the route rather than the resource, so the same resource can be plain under `/posts` and wrapped in admin chrome under `/manage/posts`. Previously the only way to put a resource on an app layout was to eject a controller purely to write one `layout` line. A `layout` declared in an ejected controller still wins; a route declaring no layout resolves exactly as before, landing on the host's `ApplicationController` layout.
+
+### Columns
+
+- A column naming a method the model has no public answer for now raises before the table renders, naming the resource, the attribute, and the model, and suggesting the `delegate`. It used to surface as a bare `NoMethodError` from inside a column partial. Columns with a `render:` proc are exempt — the proc decides what to call, and `attribute:` is then only the header and sort key.
+
+### Generators
+
+- `rails g layered:resource talk speaker:references` now emits a `:speaker_id` field, which infers a combobox of the associated records. References stay out of `columns` (a raw foreign key is rarely the column an index wants), but excluding them from `fields` too left the generated form with no way to set the association — and since `belongs_to` is required by default, every create failed with "Speaker must exist". Polymorphic references stay out of both: setting one takes a `_type` as well.
+- `rails g layered:resource:controller talk` now generates `TalksController` and advises `layered_resources :talks, controller: "talks"`. It used to generate `talk_controller.rb` and advise `layered_resources :talk`, which moved the collection from `/talks` to `/talk` and broke every path helper pointing at it.
+
 ## [0.1.0] - 2026-08-30
 
 Initial release.

data/README.md

@@ -73,6 +73,8 @@ rails g layered:resource:scaffold post title:string body:text
 
 This invokes Rails' built-in `model` generator (so you get the migration and model), writes `app/layered_resources/post_resource.rb` with `columns` and `fields` derived from the attributes, and appends `layered_resources :posts` to `config/routes.rb`. Views are intentionally not generated - the gem's defaults render until you eject them with `rails g layered:resource:views posts`.
 
+A `references` attribute (e.g. `speaker:references`) becomes a `:speaker_id` field - which infers a combobox of the associated records - but is left out of `columns`, since a raw foreign key is rarely the column you want on an index. Polymorphic references are left out of both: setting one takes a `_type` as well, so it needs a field you write yourself.
+
 Pass `--skip-model` if the model already exists. Restrict which CRUD actions get routed with `--actions index show` (emits `only:`) or `--except destroy` (emits `except:`). Pass `--controller` to also eject a controller and wire it into the route, or `--views` to eject the templates upfront.
 
 If the model already exists and you just want the resource class plus its route, use `rails g layered:resource post title:string body:text` instead. It writes `app/layered_resources/post_resource.rb` and appends `layered_resources :posts` - pass `--skip-route` to skip the route line.
@@ -163,6 +165,15 @@ layered_resources :posts, except: [:destroy]
 
 The default `show` view is intentionally a blank canvas - the gem doesn't auto-render an attribute list, since generated detail pages tend to be low-value and always need customizing. The index links each record's title to its **edit** page, not its show page, so `show` is only worth keeping if you're going to build a real detail view (eject it with `rails g layered:resource:views` and fill in the template). If you're not, pass `except: [:show]` to drop the route.
 
+**Layout:** the gem's controller renders inside your `ApplicationController`'s layout. Point a route at a different one - an admin chrome, say - without ejecting a controller:
+
+```ruby
+layered_resources :posts, layout: "manage"   # app/views/layouts/manage.html.erb
+layered_resources :posts, layout: false      # no layout at all
+```
+
+The option covers every action on that route, and each route decides independently, so the same resource can be plain under `/posts` and wrapped under `/manage/posts`. An ejected controller that declares its own `layout` wins over the route option.
+
 **Root breadcrumb:** top-level resources render no breadcrumb trail by default. Declare a static first crumb — typically a link back to the host app's dashboard:
 
 ```ruby
@@ -607,6 +618,17 @@ rails g layered:resource:column priority_badge     # scaffold a brand-new type
 
 A custom partial receives `record`, `value`, and `options` (the column hash) as locals - read keys like `:variants` or `:format` straight off `options`.
 
+A column's `attribute:` has to be something the model publicly answers to - a DB column, an association, an `attribute`, a delegated method, or any public method you define (the default renderer reads the cell with `public_send`). Naming one it doesn't have raises before the table renders, telling you which resource and which attribute:
+
+```
+PostResource declares column :author_name, but Post has no public method by that
+name. Add it to Post (`delegate :author_name, to: :<association>` for an
+associated model's attribute), correct the column's attribute:, or give the
+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.
+
 ### 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)).
@@ -851,7 +873,7 @@ This copies the gem's actual `index`, `show`, `new`, and `edit` templates into `
 rails g layered:resource:controller posts
 ```
 
-This gives you a controller that inherits from the base - override any of the standard CRUD actions and call `super` when you only want to tweak behaviour.
+This gives you a controller that inherits from the base - override any of the standard CRUD actions and call `super` when you only want to tweak behaviour. Pass a singular name and it's pluralised (`talk` generates `TalksController`): `layered_resources` declares its routes under the plural name and `controller:` has to match, so a `talk_controller.rb` would only be reachable by moving the collection from `/talks` to `/talk`.
 
 If you outgrow the gem entirely, drop the inheritance and write a plain Rails controller:
 

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

@@ -26,6 +26,11 @@ module Layered
         helper Layered::Ui::BreadcrumbsHelper
         helper Layered::Resource::FiltersHelper
 
+        # Hooks the route's `layout:` option in. Returning nil (the common
+        # case) falls through to Rails' normal layout resolution, so routes
+        # without the option are unaffected.
+        layout :layered_resource_layout
+
         before_action :load_layered_resource
         before_action :load_layered_member_record
         before_action :require_layered_fields, only: %i[new create edit update]
@@ -195,6 +200,20 @@ module Layered
         @resource_can_show    = resource_actions.include?(:show)
       end
 
+      # The layout named by `layered_resources :posts, layout: "manage"`,
+      # or nil when the route declared none — which Rails reads as "resolve
+      # the layout the usual way", landing on the host's
+      # ApplicationController layout. `layout: false` renders bare. Nil is
+      # also what an ejected controller sees before `load_layered_resource`
+      # has run (e.g. rendering an error page), which is the right default
+      # there too.
+      def layered_resource_layout
+        layout = @_route_entry && @_route_entry[:layout]
+        return nil if layout.nil?
+
+        layout == false ? false : layout.to_s
+      end
+
       # 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

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

@@ -13,12 +13,42 @@ module Layered
         # that doesn't already have one, then wraps columns with a `link:`
         # option in a link to the named route.
         def decorate_columns
+          validate_column_attributes!
           apply_column_sortability
           apply_column_renderers
           apply_column_links
           apply_primary_column_link if action_name == "index"
         end
 
+        # `columns` is declarative, so a column naming a method the model
+        # doesn't have is checkable before anything renders. Without this the
+        # miss surfaces as a bare NoMethodError raised from inside a column
+        # partial, naming neither the resource nor the column. Columns with a
+        # `render:` proc are exempt: the proc decides what to call, and
+        # `attribute` is then just a header/sort key.
+        def validate_column_attributes!
+          model = @resource.model
+          # Attribute readers are defined lazily, so ask for them before
+          # asking whether they exist.
+          model.define_attribute_methods
+
+          # Public only: the default renderer reads the cell with
+          # `record.public_send`, so a private method is as unrenderable as
+          # a missing one.
+          missing = @columns.reject { |col| col[:render] }
+                            .filter_map { |col| col[:attribute] }
+                            .reject { |attr| model.method_defined?(attr) }
+          return if missing.empty?
+
+          raise ArgumentError,
+                "#{@resource.name} declares column#{'s' if missing.size > 1} " \
+                "#{missing.map(&:inspect).join(', ')}, but #{model.name} has no public method " \
+                "by that name. " \
+                "Add it to #{model.name} (`delegate :#{missing.first}, to: :<association>` for " \
+                "an associated model's attribute), correct the column's attribute:, or give the " \
+                "column a `render:` proc that produces the value."
+        end
+
         # Marks columns sortable: false unless they map to a real DB column.
         # Virtual / association-derived columns (e.g. :user_name on Post) can't
         # be sorted by Ransack without the associated model also having

data/lib/generators/layered/resource/controller/controller_generator.rb

@@ -28,6 +28,14 @@ module Layered
           template "controller.rb.tt", path
         end
 
+        def note_pluralisation
+          return unless pluralised?
+
+          say ""
+          say "Named the controller #{file_name} (not #{given_name}): layered_resources " \
+              "declares its routes under the plural name, and controller: has to match."
+        end
+
         def show_routing_instructions
           say ""
           say "Point the route at the new controller:"
@@ -45,8 +53,26 @@ module Layered
 
         private
 
+        # `layered_resources` declares its routes under the plural name, and
+        # `controller:` has to name the controller's own path, so a singular
+        # argument is pluralised. Generating `talk_controller.rb` and telling
+        # the user to write `layered_resources :talk, controller: "talk"`
+        # would move the collection from /talks to /talk and break every
+        # path helper already pointing at it.
         def file_name
-          @_file_name ||= super.sub(/_?controller$/i, "")
+          @_file_name ||= given_name.pluralize
+        end
+
+        # The name as typed, minus any `_controller` suffix. `super` here
+        # would re-enter the override, so read NamedBase's own reader.
+        def given_name
+          @_given_name ||= Rails::Generators::NamedBase
+                           .instance_method(:file_name).bind_call(self)
+                           .sub(/_?controller$/i, "")
+        end
+
+        def pluralised?
+          given_name != file_name
         end
       end
     end

data/lib/generators/layered/resource/resource_generator.rb

@@ -44,12 +44,22 @@ module Layered
           singular_name.camelize
         end
 
+        # `speaker_id` is a poor index column - the table wants the
+        # speaker's label, which is the consumer's call - so references are
+        # left out of `columns`.
         def column_attributes
           attributes.reject { |a| a.reference? || a.password_digest? }
         end
 
+        # References belong in `fields` as their foreign key: `belongs_to` is
+        # required by default, so a form without the FK cannot create a
+        # record. A `:<name>_id` field infers a combobox of the associated
+        # records (see `Layered::Resource::Base#infer_association_field`).
+        # Polymorphic references stay out: setting one needs a `_type` as
+        # well, and there is no single class whose records could fill a
+        # picker.
         def field_attributes
-          column_attributes
+          attributes.reject { |a| a.password_digest? || (a.reference? && a.polymorphic?) }
         end
 
         def field_as(attr)

data/lib/generators/layered/resource/templates/resource.rb.tt

@@ -12,7 +12,7 @@ class <%= resource_class_name %>Resource < Layered::Resource::Base
 
   fields [
 <% field_attributes.each_with_index do |attr, i| -%>
-    { attribute: :<%= attr.name %><%= field_as(attr) %> }<%= "," unless i == field_attributes.length - 1 %>
+    { attribute: :<%= attr.column_name %><%= field_as(attr) %> }<%= "," unless i == field_attributes.length - 1 %>
 <% end -%>
   ]
 <% end -%>

data/lib/layered/resource/routing.rb

@@ -6,11 +6,12 @@ module Layered
       @registry = Concurrent::Map.new
 
       class << self
-        def register(route_key, resource_class_name, actions: [], routes: nil, parent_params: [], parent_collection_keys: {}, resource_name: nil, member_actions: [], collection_actions: [])
+        def register(route_key, resource_class_name, actions: [], routes: nil, parent_params: [], parent_collection_keys: {}, resource_name: nil, member_actions: [], collection_actions: [], layout: nil)
           @registry[route_key.to_s] = {
             resource: resource_class_name.to_s,
             actions: actions,
             routes: routes,
+            layout: layout,
             parent_params: parent_params,
             parent_collection_keys: parent_collection_keys,
             resource_name: resource_name.to_s,
@@ -82,7 +83,13 @@ module Layered
         end
       end
 
-      def layered_resources(resource_name, resource: nil, controller: nil, namespace: nil, only: RESOURCE_ACTIONS, except: nil, **options, &block)
+      # `layout:` renders the resource's pages inside one of the host app's
+      # layouts (`layout: "manage"` → `app/views/layouts/manage.html.erb`),
+      # or without one (`layout: false`). Without it the controller keeps
+      # Rails' normal resolution, which lands on the host's
+      # `ApplicationController` layout. An explicit `layout` declaration in
+      # an ejected controller replaces the hook and wins over this option.
+      def layered_resources(resource_name, resource: nil, controller: nil, namespace: nil, layout: nil, only: RESOURCE_ACTIONS, except: nil, **options, &block)
         # When called inside `resources :foo do ... end` (or `resource :foo do`),
         # Rails has set up a resource_scope but hasn't pushed the parent's
         # path into @scope. Push it ourselves via scope(path:) and recurse.
@@ -107,7 +114,7 @@ module Layered
               begin
                 layered_resources(resource_name,
                                   resource: resource, controller: controller, namespace: namespace,
-                                  only: only, except: except, **options, &block)
+                                  layout: layout, only: only, except: except, **options, &block)
               ensure
                 @scope.frame[:as] = saved_as
               end
@@ -124,6 +131,13 @@ module Layered
         # `scope path: "foo", module: "foo"` and pass `namespace:` here.
         namespace = namespace.to_s.presence
 
+        unless layout.nil? || layout == false || layout.is_a?(String) || layout.is_a?(Symbol)
+          raise ArgumentError,
+                "layered_resources :#{resource_name} got layout: #{layout.inspect}. " \
+                "Pass a layout name (String or Symbol, resolved under app/views/layouts) " \
+                "or `false` to render without a layout."
+        end
+
         resource_class_name = resource ||
           (namespace ? "#{namespace}::#{resource_name.to_s.classify}Resource" : "#{resource_name.to_s.classify}Resource")
         route_key = resource_name.to_s
@@ -282,7 +296,8 @@ module Layered
                                             parent_collection_keys: parent_collection_keys,
                                             resource_name: route_key,
                                             member_actions: custom_member.map { |a| a[:action] },
-                                            collection_actions: custom_collection.map { |a| a[:action] })
+                                            collection_actions: custom_collection.map { |a| a[:action] },
+                                            layout: layout)
 
         route_defaults = (options[:defaults] || {}).merge(
           _layered_resource_route_key: as_base

data/lib/layered/resource/version.rb

@@ -1,5 +1,5 @@
 module Layered
   module Resource
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: layered-resource-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - layered.ai