layered-resource-rails 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83a0686237527aabd89c6fa83f98c8a2bbab1a02deff48528e8e5baed7f8b874
-  data.tar.gz: 744e768aff2d5c624c9a243ccfbc9d92cf80de3a559fec9c320c89d51e7e197e
+  metadata.gz: bfe32848fe680ff7bcbafa8c72d1d7c46a83fb48c3a440411eae26f5fe766cb3
+  data.tar.gz: 9c47bbcff2783c5423cc1d0d7360d27934ed18debbb3bedda72af65b8995b312
 SHA512:
-  metadata.gz: ebe053f334e9ad89c835add54f1c60bf5c8c863cb175ec42932e7d9cf0809eef73d65646a96505da64cd9062207dc722eb672d4662cad612ca70259eecac9c60
-  data.tar.gz: a148f47dc69bbd3fb799bd1b8b49d2b4bf90dbc3854e2c75fec7dd88dd5c8efcb8e99ec7af434d6c2b76370d2243ca3eb9f7d512113aeba3ae46effe8bc76194
+  metadata.gz: 5b79478c63e11f9cd96af0df6aa89ed46e8f133ac90c2f05842d0a2f19cec7156faf70aa9f75c803a4c7655b20e771c0e11c0d6d95c2bba927582d1a30b9116b
+  data.tar.gz: 013feae5be9a1c9e717434411d7f9d2de288cff2669400ae14477a27cdc104098a0d78d45584366da675be3892dec955fd3ba6104a1f1a3f3e0903fc00518c7c

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

@@ -2,7 +2,7 @@
 name: layered-resource-rails
 description: Installs, configures, and builds with the layered-resource-rails gem - a Rails 8+ engine providing convention-over-configuration CRUD scaffolding with search, sort, and pagination. Use when adding layered-resource-rails to a Rails app, defining resource classes, mounting `layered_resources` routes, ejecting views or controllers, or troubleshooting setup.
 license: Apache-2.0
-compatibility: Requires Ruby on Rails >= 8.0, layered-ui-rails ~> 0.9, ransack ~> 4.0, pagy ~> 43.2
+compatibility: Requires Ruby on Rails >= 8.0, layered-ui-rails ~> 0.27, ransack ~> 4.0, pagy ~> 43.2
 metadata:
   author: layered.ai
   version: "1.0"
@@ -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
@@ -102,7 +104,7 @@ end
 | `model Post` | The ActiveRecord class this resource manages |
 | `columns [...]` | Index table columns. Each entry is `{ attribute:, label:, primary:, link:, render: }` |
 | `fields [...]` | Form fields for new/edit. Omit to disable CRUD forms |
-| `search_fields [...]` | Ransack attributes the index search box matches against. Association-walking entries like `:user_name` (for `belongs_to :user` + `users.name`) join into the association |
+| `search_fields [...]` | Ransack attributes the index search box matches against. Association-walking entries like `:user_name` (for `belongs_to :user` + `users.name`) join into the association. The box searches as the term is typed (debounced, into the index Turbo frame) with a clear button built into the field - no Search or Clear buttons. Typed searches `replace` history rather than pushing; the caret survives the re-render and the result count is announced |
 | `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"` |
@@ -110,6 +112,8 @@ end
 | `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 |
 
+The trail always ends with the current page (collection name on `index`, record label on `show`, `New`/`Edit` on the forms), and only that crumb carries `aria-current="page"`. Parent record crumbs link to their show page when the parent resource routes `:show`.
+
 ### 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)
@@ -159,7 +163,7 @@ Field `as:` follows Rails' `form_with` field helpers - `:text`, `:checkbox`, `:d
 
 ### Filters
 
-`filters` declares structured index controls complementing the single free-text `search_fields` box. The UI: an **Add filter** button opens a popover listing the declared filters; picking one adds it as an unset **tag** at the end of the row (the `f[]` param tracks added tags and their order for as long as they're shown) with its controls popover already open, ready to take a value; pressing the tag's label reopens the popover, and its ✕ removes it. Short single-choice filters apply instantly via links; ranges/text/multi-selects/comboboxes apply via a small GET form. Every filter is a Ransack predicate in the URL, so filters compose with search, sort, and pagination — the search form and each filter form round-trip the other `q` params (and `f[]` entries) as hidden fields (no JavaScript; the one-shot `fo` param marks which tag's popover renders open).
+`filters` declares structured index controls complementing the single free-text `search_fields` box. The UI: an **Add filter** button opens a popover listing the declared filters; picking one adds it as an unset **tag** at the end of the row (the `f[]` param tracks added tags and their order for as long as they're shown) with its controls popover already open, ready to take a value; pressing the tag's label reopens the popover, and its ✕ removes it. Short single-choice filters apply instantly via links; ranges/text/multi-selects/comboboxes apply via a small GET form. Every filter is a Ransack predicate in the URL, so filters compose with search, sort, and pagination — the search form and each filter form round-trip the other `q` params (and `f[]` entries) as hidden fields (the one-shot `fo` param marks which tag's popover renders open). The filter controls are plain links and forms with no JavaScript; only the search box's type-to-search is scripted. Because the filters are hidden fields inside the search form, clearing the term client-side keeps them.
 
 ```ruby
 filters :status,          # enum     -> multi-select of its values  (status_in)
@@ -181,7 +185,7 @@ Override per attribute with a trailing hash: `as:` (force control type: `:select
 
 **The predicate set is closed.** Each control type maps to a fixed predicate (`:select`/`:combobox` → `_in`/`_eq`, `:boolean` → `_eq`, `:string` → `_cont`, ranges → `_gteq`+`_lteq`) and there is no `predicate:` option, so predicates Ransack can otherwise express (`_not_null`, `_matches`) aren't reachable through the DSL. In particular a **"is this set / unset" filter on a nullable timestamp** (a `locked_at`-style column) has no inferred control: `as: :boolean` emits `locked_at_eq=true`, which casts against a datetime column and matches nothing. Back the flag with a real boolean column the write path maintains, or eject the filter partials and emit the predicate yourself. Filtered attributes *are* allowlisted, so `q[locked_at_not_null]=1` works hand-typed in the URL — it just has no UI control.
 
-The bar renders inside the index Turbo frame between search box and table, built from `l_ui_popover` and the `_filters`/`_filter_control` partials — eject with `rails g layered:resource:views` to customise.
+The bar renders inside the index Turbo frame between search box and table, built from `l_ui_popover` and the `_filters`/`_filter_control` partials — eject with `rails g layered:resource:views` to customise. The search box is the `_search` partial, which calls `l_ui_search_form` in block mode with `l_ui_search_control`. Both take `live: true` (opt-in in layered-ui-rails 0.27 - it is not inferred from `turbo_frame:`, and the control defaults to `live: false` on its own), and the form passes `count: @pagy&.count` so results are announced.
 
 ## Route DSL
 
@@ -194,10 +198,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 +352,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 +450,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,34 @@
 
 All notable changes to this project will be documented in this file. This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.3.0] - 2026-09-21
+
+### Changed
+
+- The index search box searches as the term is typed. The **Search** and **Clear** buttons are gone: the box submits into the index Turbo frame as the field changes, debounced so a typed word is one request rather than one per letter, and the field carries its own clear button - shown only once there is something to clear, and reachable by keyboard with Escape clearing the field too. A typed search `replace`s the history entry rather than pushing one, so Back leaves the index instead of replaying the term letter by letter; the term still lives in the URL, so a search stays shareable and survives a reload, and sort links, pagination and filter chips still advance.
+- With no button press to signal a change, the number of results is now announced to screen readers after each search (`count:` is passed from `@pagy`), the caret is preserved across the frame re-render so a word is never interrupted mid-letter, and the box is a labelled `search` landmark. The form still submits on Enter and works without JavaScript.
+- The two search branches on the index - one for resources with `filters`, one without - are now a single `_search.html.erb` partial, ejected by `rails g layered:resource:views` along with the rest. Because the active filters are hidden fields inside the search form, clearing the term keeps them, which is what `layered_search_clear_path` used to compute; that helper is still there for an ejected view that wants the same link.
+- Requires `layered-ui-rails` ~> 0.27, which is where the type-to-search control (`live:`, `count:`, the in-field clear button) landed.
+
+### Fixed
+
+- The breadcrumb trail ends with the page it is on - the collection name on `index`, the record's label on `show`, **New** or **Edit** on the form pages - and only that last crumb is marked `aria-current="page"`. The trail used to stop at the parent record, and because `l_ui_breadcrumb_item` marks any unlinked crumb as the current page, a nested index pointed a screen reader at its parent while `show` marked nothing at all. Crumbs now go through a `layered_breadcrumb_item` helper that lets only the current one through unlinked, and a parent record links to its own show page when its resource routes `:show`, so the middle of a trail is no longer a dead end.
+
+## [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

@@ -45,7 +45,7 @@ curl -fsSL https://raw.githubusercontent.com/layered-ai-public/layered-resource-
 ## Requirements
 
 - Ruby on Rails >= 8.0
-- [layered-ui-rails](https://github.com/layered-ai-public/layered-ui-rails) ~> 0.25 (>= 0.25.1)
+- [layered-ui-rails](https://github.com/layered-ai-public/layered-ui-rails) ~> 0.27
 - Ransack ~> 4.0
 - Pagy ~> 43.2
 
@@ -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
@@ -175,6 +186,8 @@ end
 
 Nested routes prepend it to the derived parent trail (e.g. Home / Users / Alice). Pass `nil` as the path to render unlinked text.
 
+Every trail ends with the page you're on - the collection name on `index`, the record's label on `show`, `New` or `Edit` on the form pages - and that last crumb is the only one marked `aria-current="page"`. Parent crumbs never are, whether or not they link: a parent record links to its own show page when its resource routes `:show`, and renders as plain text when it doesn't.
+
 **Record label:** a record is labelled by its **primary column** (the one marked `primary: true`, else the first) wherever the gem has to name it: the `show` and `edit` page titles, a row's actions menu, and its options in another resource's picker. Declare `label_attribute` when that column isn't the record's name — a `primary:` column rendered by a `render:` proc, say:
 
 ```ruby
@@ -365,6 +378,14 @@ The Ransack allowlists are scoped to the resource: the association and the assoc
 
 A walked search field is also sortable — `q[s]=user_name asc` orders the index by `users.name` — because Ransack derives its sort allowlist from the search allowlist. Associations not declared in `search_fields` stay unsearchable and unsortable.
 
+### How the search box behaves
+
+There is no Search button to press. The box searches as the term is typed, debounced so a typed word is one request rather than one per letter, and the results re-render inside the index's Turbo frame. The field carries its own clear button, which appears once there is something to clear; Escape in the field clears it too.
+
+Each search **replaces** the history entry rather than pushing one, so Back leaves the index instead of replaying the term letter by letter. The term still lives in the URL, so a search remains shareable and survives a reload — and sort links, pagination and filter chips still push history as before.
+
+The parts that matter for accessibility are handled for you: the caret stays put across the re-render, so a word is never interrupted mid-letter; the number of results is announced to screen readers after each search, since with no button press there is otherwise nothing to say the page changed; and the box is a labelled `search` landmark. The form still submits on Enter and works without JavaScript.
+
 ### Search placeholder
 
 The index search box's placeholder is derived from `search_fields` via `human_attribute_name`, so attribute renames declared in the standard Rails i18n location flow through automatically. Given `search_fields [:title, :user_sid]`:
@@ -465,7 +486,7 @@ A counter-cache column reads straight off the parent row, so the index renders i
 
 Where `search_fields` gives a single free-text box, `filters` adds structured controls for narrowing the index by specific attributes. The UI follows the "add filter" pattern: an **Add filter** button opens a popover listing the declared filters; picking one adds it as a **tag** with its controls popover already open, ready to take a value; pressing the tag's label reopens the popover, and its ✕ removes it. Booleans and short single-choice selects apply instantly on click; multi-selects, comboboxes, ranges, and text filters have an Apply button.
 
-Under the hood every filter is a Ransack predicate in the query string, so filters compose with search, sort, and pagination — all coexist in the URL and survive each other's submits (the search form and each filter form round-trip the other params as hidden fields; no JavaScript involved). The lightweight `f[]` param records which tags were added and in what order — new tags join the end of the row (after any pinned ones) and stay put when set; a tag's ✕ removes its entry.
+Under the hood every filter is a Ransack predicate in the query string, so filters compose with search, sort, and pagination — all coexist in the URL and survive each other's submits (the search form and each filter form round-trip the other params as hidden fields). The filter controls themselves are plain links and forms, with no JavaScript involved; only the search box's type-to-search is scripted. The lightweight `f[]` param records which tags were added and in what order — new tags join the end of the row (after any pinned ones) and stay put when set; a tag's ✕ removes its entry.
 
 Declare `filters` with a list of attributes. The control and predicate are inferred from each column:
 
@@ -579,7 +600,7 @@ filters :created_at,
 
 Pinned filters render as tags from the start, so the common ones are one click away instead of two; the **Add filter** button only renders while there are unpinned filters left to add (pin everything and it disappears). A `default:` applies whenever the request carries no state for that filter — the tag shows it as active and every link and form round-trips it explicitly from then on. Clearing a defaulted filter writes an explicit blank (`q[status_eq]=`) rather than dropping the param, so the default doesn't immediately re-apply.
 
-The filter bar renders inside the index's Turbo frame between the search box and the table; eject the views (`rails g layered:resource:views`) to customise placement — the bar is the `_filters` partial, and each control is `_filter_control`.
+The filter bar renders inside the index's Turbo frame between the search box and the table; eject the views (`rails g layered:resource:views`) to customise placement — the search box is the `_search` partial, the bar is `_filters`, and each control is `_filter_control`.
 
 ## Column rendering
 
@@ -607,6 +628,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 +883,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

@@ -25,6 +25,12 @@ module Layered
         helper Layered::Ui::PagyHelper
         helper Layered::Ui::BreadcrumbsHelper
         helper Layered::Resource::FiltersHelper
+        helper Layered::Resource::BreadcrumbsHelper
+
+        # 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
@@ -195,6 +201,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/breadcrumbs.rb

@@ -48,32 +48,50 @@ module Layered
 
               crumbs = []
 
-              # Link to the parent's layered index if a route exists
+              # The parent's own ancestors, filled in from the current
+              # request - needed by both of the parent's path helpers.
               if collection_entry
                 rs = collection_entry[:routes] || Rails.application.routes
+                ancestor_args = collection_entry[:parent_params].index_with { |p| params[p] }
+                ancestor_args = nil unless ancestor_args.values.all?(&:present?)
+              end
+
+              # Link to the parent's layered index if a route exists
+              if collection_entry && ancestor_args
                 helper = :"#{collection_key}_path"
                 if rs.url_helpers.method_defined?(helper)
-                  ancestor_args = collection_entry[:parent_params].each_with_object({}) do |p, h|
-                    h[p] = params[p]
-                  end
-                  if ancestor_args.values.all?(&:present?)
-                    path = rs.url_helpers.send(helper, default_url_options.merge(ancestor_args))
-                    crumbs << { label: model_class.model_name.human.pluralize, path: path }
-                  end
+                  path = rs.url_helpers.send(helper, default_url_options.merge(ancestor_args))
+                  crumbs << { label: model_class.model_name.human.pluralize, path: path }
                 end
               end
 
-              # Add the specific record breadcrumb
+              # 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])
               if record
                 label = record.try(:name) || record.try(:title) || "#{model_class.model_name.human} ##{record.id}"
-                crumbs << { label: label, path: nil }
+                crumbs << { label: label, path: layered_parent_record_path(collection_entry, collection_key, ancestor_args, record) }
               end
 
               crumbs
             end
           end
         end
+
+        # 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)
+          return nil unless collection_entry && ancestor_args
+          return nil unless collection_entry[:actions].include?(:show)
+
+          rs = collection_entry[:routes] || Rails.application.routes
+          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))
+        end
       end
     end
   end

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/app/helpers/layered/resource/breadcrumbs_helper.rb

@@ -0,0 +1,19 @@
+module Layered
+  module Resource
+    # Renders one crumb of a layered resource's breadcrumb trail.
+    #
+    # `l_ui_breadcrumb_item` marks every unlinked crumb as
+    # aria-current="page", which is only correct for the crumb that *is* the
+    # current page. A derived trail routinely carries unlinked crumbs that
+    # aren't - a parent record with no show route, an unlinked
+    # `root_breadcrumb` - so only the crumb a view flags as `current:` is
+    # passed through unlinked; the rest render as plain, uncurrent text.
+    module BreadcrumbsHelper
+      def layered_breadcrumb_item(label, path = nil, current: false)
+        return l_ui_breadcrumb_item(label, current ? nil : path) if path || current
+
+        tag.li(tag.span(label), class: "l-ui-breadcrumbs__item")
+      end
+    end
+  end
+end

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

@@ -235,8 +235,12 @@ module Layered
         @resource.search_fields.map(&:to_s).join("_or_") + "_cont"
       end
 
-      # Clear link for the search box that drops only the search term,
-      # keeping active filters and sort.
+      # A path that drops only the search term, keeping active filters and sort.
+      #
+      # The search box no longer needs this - it clears client-side by
+      # submitting its own form with an empty field, and the filters are hidden
+      # fields inside that form, so they ride along. Kept for an ejected view or
+      # a host app that wants the same "clear just the term" link.
       def layered_search_clear_path
         layered_filter_path_with(layered_filter_query_params.except(layered_search_field_key))
       end

data/app/views/layered/resource/resources/_search.html.erb

@@ -0,0 +1,24 @@
+<%# The search box. Searching happens as the term is typed (live: true), so
+    there is no Search button to press, and the field carries its own clear
+    button. live: needs the turbo_frame: to land the response in, and count:
+    so the size of the result set is announced once it has.
+
+    Any active filter and sort params ride along as hidden fields, so a search
+    composes with them rather than replacing them - which is also what makes
+    clearing the term client-side keep the filters: an empty term is submitted
+    through this same form. %>
+<div class="l-ui-mt-4">
+  <%= l_ui_search_form(@q,
+        url: layered_collection_path,
+        label: "Search #{@model.model_name.human.pluralize.downcase}",
+        live: true,
+        count: @pagy&.count,
+        turbo_frame: turbo_frame_name) do |f| %>
+    <%= layered_filter_hidden_fields(except: layered_search_field_key) if layered_filters.any? %>
+    <div class="l-ui-search-inline">
+      <%= l_ui_search_control(f, layered_search_field_key,
+            placeholder: @resource.search_placeholder,
+            live: true) %>
+    </div>
+  <% end %>
+</div>

data/app/views/layered/resource/resources/edit.html.erb

@@ -2,9 +2,10 @@
   <div>
     <%= l_ui_breadcrumbs do %>
       <% layered_breadcrumbs.each do |crumb| %>
-        <%= l_ui_breadcrumb_item crumb[:label], crumb[:path] %>
+        <%= layered_breadcrumb_item crumb[:label], crumb[:path] %>
       <% end %>
-      <%= l_ui_breadcrumb_item @model.model_name.human.pluralize, layered_collection_path %>
+      <%= layered_breadcrumb_item @model.model_name.human.pluralize, layered_collection_path %>
+      <%= layered_breadcrumb_item "Edit", current: true %>
     <% end %>
 
     <h1 class="l-ui-heading">Edit <%= @model.model_name.human.downcase %></h1>

data/app/views/layered/resource/resources/index.html.erb

@@ -2,11 +2,14 @@
 
 <div class="l-ui-spread">
   <div>
+    <%# The trail ends on this page, so it carries aria-current - the
+        parent crumbs before it never do, linked or not. %>
     <% if layered_breadcrumbs.any? %>
       <%= l_ui_breadcrumbs do %>
         <% layered_breadcrumbs.each do |crumb| %>
-          <%= l_ui_breadcrumb_item crumb[:label], crumb[:path] %>
+          <%= layered_breadcrumb_item crumb[:label], crumb[:path] %>
         <% end %>
+        <%= layered_breadcrumb_item @model.model_name.human.pluralize, current: true %>
       <% end %>
     <% end %>
 
@@ -29,32 +32,7 @@
 
 <%= turbo_frame_tag turbo_frame_name, data: { turbo_action: "advance" } do %>
   <% if @resource.search_fields.any? %>
-    <div class="l-ui-mt-4">
-      <% if layered_filters.any? %>
-        <%# With filters declared, the search form must round-trip the active
-            filter and sort q params as hidden fields so its submit composes
-            with them; Clear drops only the search term. %>
-        <%= l_ui_search_form(@q, url: layered_collection_path, turbo_frame: turbo_frame_name) do |f| %>
-          <%= layered_filter_hidden_fields(except: layered_search_field_key) %>
-          <%= f.label layered_search_field_key, "Search", class: "l-ui-sr-only" %>
-          <div class="l-ui-search-inline">
-            <%= f.text_field layered_search_field_key,
-                  class: "l-ui-form__field", placeholder: @resource.search_placeholder %>
-            <%= f.submit "Search", class: "l-ui-button l-ui-button--primary" %>
-            <%= link_to "Clear", layered_search_clear_path,
-                  class: "l-ui-button l-ui-button--outline",
-                  data: { turbo_frame: turbo_frame_name, turbo_action: "advance" } %>
-          </div>
-        <% end %>
-      <% else %>
-        <%= l_ui_search_form(@q,
-              url: layered_collection_path,
-              fields: @resource.search_fields,
-              placeholder: @resource.search_placeholder,
-              clear: true,
-              turbo_frame: turbo_frame_name) %>
-      <% end %>
-    </div>
+    <%= render "search", turbo_frame_name: turbo_frame_name %>
   <% end %>
 
   <% if layered_filters.any? %>

data/app/views/layered/resource/resources/new.html.erb

@@ -2,9 +2,10 @@
   <div>
     <%= l_ui_breadcrumbs do %>
       <% layered_breadcrumbs.each do |crumb| %>
-        <%= l_ui_breadcrumb_item crumb[:label], crumb[:path] %>
+        <%= layered_breadcrumb_item crumb[:label], crumb[:path] %>
       <% end %>
-      <%= l_ui_breadcrumb_item @model.model_name.human.pluralize, layered_collection_path %>
+      <%= layered_breadcrumb_item @model.model_name.human.pluralize, layered_collection_path %>
+      <%= layered_breadcrumb_item "New", current: true %>
     <% end %>
 
     <h1 class="l-ui-heading">New <%= @model.model_name.human.downcase %></h1>

data/app/views/layered/resource/resources/show.html.erb

@@ -6,11 +6,12 @@
     <% if layered_breadcrumbs.any? || index_path %>
       <%= l_ui_breadcrumbs do %>
         <% layered_breadcrumbs.each do |crumb| %>
-          <%= l_ui_breadcrumb_item crumb[:label], crumb[:path] %>
+          <%= layered_breadcrumb_item crumb[:label], crumb[:path] %>
         <% end %>
         <% if index_path %>
-          <%= l_ui_breadcrumb_item @model.model_name.human.pluralize, index_path %>
+          <%= layered_breadcrumb_item @model.model_name.human.pluralize, index_path %>
         <% end %>
+        <%= layered_breadcrumb_item record_label, current: true %>
       <% end %>
     <% end %>
 

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/generators/layered/resource/views/views_generator.rb

@@ -16,7 +16,7 @@ module Layered
         desc "Copy the gem's view templates into app/views/layered/<name>/ for full customisation."
 
         VIEWS = %w[index.html.erb show.html.erb new.html.erb edit.html.erb
-                   _filters.html.erb _filter_control.html.erb].freeze
+                   _search.html.erb _filters.html.erb _filter_control.html.erb].freeze
 
         def copy_views
           VIEWS.each do |view|

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.3.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.3.0
 platform: ruby
 authors:
 - layered.ai
@@ -29,20 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.25'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.25.1
+        version: '0.27'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.25'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.25.1
+        version: '0.27'
 - !ruby/object:Gem::Dependency
   name: pagy
   requirement: !ruby/object:Gem::Requirement
@@ -223,6 +217,7 @@ files:
 - app/controllers/layered/resource/internal/columns.rb
 - app/controllers/layered/resource/internal/routing.rb
 - app/controllers/layered/resource/resources_controller.rb
+- app/helpers/layered/resource/breadcrumbs_helper.rb
 - app/helpers/layered/resource/filters_helper.rb
 - app/views/layered/resource/columns/_badge.html.erb
 - app/views/layered/resource/columns/_boolean.html.erb
@@ -230,6 +225,7 @@ files:
 - app/views/layered/resource/columns/_text.html.erb
 - app/views/layered/resource/resources/_filter_control.html.erb
 - app/views/layered/resource/resources/_filters.html.erb
+- app/views/layered/resource/resources/_search.html.erb
 - app/views/layered/resource/resources/edit.html.erb
 - app/views/layered/resource/resources/index.html.erb
 - app/views/layered/resource/resources/new.html.erb