crud_components 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 300e08f93a98c2af440d843de88c42796428591c842cf037a6969c76f0bbfce6
-  data.tar.gz: 65b817f9e2663d64159142b157b6326887f52f5bf93e684294d1288cfb4c5693
+  metadata.gz: 3039812d78a4d8677f871959497a18eb9f2236627a84a0d046b72a520c0ba34c
+  data.tar.gz: 70b36787f0e28e2f51af0cfdf3361dc860fcdfb048d90365ddf4ebf128759372
 SHA512:
-  metadata.gz: 1ad9372ab031db1343c6afccf5f2f8525e593e00e23da8ee3b9a868b2e11a0dbbb5971dea96d348d2689517de69ea0da1aa9f9e589fa64dc825767f66717c72d
-  data.tar.gz: 4b5f31a8f4e4b77a3fcef9ca7a27ce31ee4e254c071c5710b1b9816e1d59d5412db40551ffba641b3e50a928386d91fcb4ead63e09ad0013d284d67dffbd0f55
+  metadata.gz: 7af65ee9f9aea26c3e6fc132fbe29ad3fbf2a3c8e931e209ee72dd7cb2a57cab670875a3c14fad3907ea316138a58d272729bfd6239d68be9cacf360b4e94fa9
+  data.tar.gz: 7a220eec077f9845b682c3a081e971d2a488a7d09a7bacfb6f514023fff92a3340000420d5bca17b648dfd424522c1f32a31f505eb81c2eb3331c2718fddbf87

data/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+Notable changes since [v0.1.0](https://github.com/itadventurer/crud_components/releases/tag/v0.1.0).
+This project follows [semantic versioning](https://semver.org).
+
+## Unreleased
+
+## v0.2.1 — 2026-08-01
+
+### Changed
+
+- Verified against **Rails 8.1** — the CI matrix now covers it alongside 7.1, 7.2 and 8.0. The gem's runtime API and its declared dependencies are unchanged; the rest is tooling (GitHub Actions bumped, demo image on Ruby 4.0, CI installs libvips so the playground's Active Storage previews load).
+
+### Fixed
+
+- An association column whose target labels itself with a *method* rather than a column (e.g. `label :display_title`) no longer raises `DefinitionError` ("… is neither a column nor an association of …") when its filter or `?q=` search runs. The label-based text match — and the `belongs_to` sort — are skipped whenever there is no column behind the label, as they already were for a block label. A `belongs_to` still filters by value; spell the columns out (`filter publisher: :name`) to match such a target as text.
+
+## v0.2.0 — 2026-07-14
+
+### Added
+
+- Typed filter controls for dynamic columns: a `filter:` block with keyword params (`geq:`/`leq:`, `eq:`, `contains:`) filters as the column's `as:` type — a number/date range, a yes/no or a dropdown instead of a text box (override with `filter_as:`/`filter_choices:`). ([#20](https://github.com/itadventurer/crud_components/issues/20))
+- `crud_filter` accepts `extra_columns:` and an opt-in `sort:` picker for headerless layouts. ([#22](https://github.com/itadventurer/crud_components/issues/22))
+- A `belongs_to` column sorts by its target's label (via a join), matching the existing filter-by-label. ([#27](https://github.com/itadventurer/crud_components/pull/27))
+- `crud_collection` takes `search_bar:` (default true) to drop the toolbar's `?q=` search box for one collection. ([#29](https://github.com/itadventurer/crud_components/pull/29))
+- `Query` exposes the params it understands: `#permitted_keys` (the strong-params list for the filters it reads), `#filter_params` (the present subset of this request, for filter-preserving links) and `#active_filters` (active values by logical name, for chips) — so a host no longer hand-maintains a permit list that mirrors the columns. ([#31](https://github.com/itadventurer/crud_components/issues/31))
+- Active Storage attachment columns filter by **presence**: a 3-state _any / present / absent_ dropdown (`EXISTS` / `NOT EXISTS`), covering `has_one_attached` and `has_many_attached`. ([#32](https://github.com/itadventurer/crud_components/issues/32))
+- A `has_many`/habtm column filters by its children's **label** — the names shown in the cell — matching `belongs_to`'s filter-by-label; skipped when the target labels itself with a block. ([#36](https://github.com/itadventurer/crud_components/pull/36))
+
+### Changed
+
+- "Search what you see": searching an association (the `?q=` of a model, the belongs_to text filter, or a bare association name in a spec) now matches the target's **label** — the name shown in its cell — instead of the target's full `search_in`. A free-text filter can no longer reach a target's hidden columns (passwords, tokens), so a `belongs_to` to a model without its own `crud_structure` is safe by default. The undeclared `search_in` default is likewise derived from the displayed fields (own string/text columns plus associations' labels). Declare `search_in` to override. ([#28](https://github.com/itadventurer/crud_components/issues/28))
+
+### Fixed
+
+- Dynamic columns keep their inline filter and sort link when a prebuilt `Query` is passed. ([#21](https://github.com/itadventurer/crud_components/issues/21))
+- A proc `sort` facet overrides a prior order (e.g. a search rank) instead of appending to it. ([#23](https://github.com/itadventurer/crud_components/issues/23))
+- The inline filter row's apply/reset button now renders on any filterable table, even one with row actions and the column picker both off (previously the button was missing). ([#35](https://github.com/itadventurer/crud_components/pull/35))
+- `LikeSpec` dedupes joined matches with an id subquery instead of `SELECT DISTINCT`, fixing `PG::UndefinedFunction` on Postgres when a model carrying a `json` column has one of its associations filtered. ([#37](https://github.com/itadventurer/crud_components/pull/37))

data/README.md

@@ -146,15 +146,15 @@ together in one block:
 ```ruby
 attribute :author_names do
   render { |book| book.authors.map(&:name).to_sentence }
-  filter :authors                  # delegate to Author's search_in; or spell it out: filter authors: :name
+  filter :authors                  # match Author's label; or spell it out: filter authors: :name
   sort   { |scope, dir| scope.left_joins(:authors).order('authors.name' => dir) }
 end
 ```
 
 The **search spec** — the mini-language `filter` and `search_in` share — builds joins +
 parameterized, wildcard-escaped ILIKE from column/association names, nothing to sanitize.
-An association name alone *delegates* to that model's `search_in`. →
-[Fields → the search spec](docs/fields.md#the-search-spec)
+An association name alone matches that model's **label** (the name you see). →
+[Filtering → the search spec](docs/filtering.md#the-search-spec)
 
 ### Columns the model doesn't know about
 
@@ -212,12 +212,12 @@ the param. It's also a standalone helper (`crud_column_picker`) you can drop abo
 ```ruby
 label :title              # default: name → title → first string column, else "Book #42"
 identify_by :slug         # Use slug in the URLs
-search_in :title, :subtitle, :publisher   # :publisher delegates to Publisher's search_in
+search_in :title, :subtitle, :publisher   # :publisher matches Publisher's label
 ```
 
 `label` + `identify_by` + `search_in` are a model's **identity** — and they define how
-*other* models render, link and filter it through their associations. Declare Order's
-identity once and every `belongs_to :order` column gets it for free. →
+*other* models render, link and filter it through their associations. Declare Publisher's
+identity once and every `belongs_to :publisher` column gets it for free. →
 [Fields → identity](docs/fields.md#identity-label-identify_by-search_in)
 
 ### Buttons / Actions
@@ -322,7 +322,7 @@ The whole DSL:
 | `attribute` / `attributes`   | improve one/several fields (model-global)                                  |
 | `render` / `filter` / `sort` | facets inside an `attribute` block — override exactly one derived behavior |
 | `label`, `identify_by`       | identity: display name; the column URL params resolve                      |
-| `search_in`                  | the model's text identity (`?q=`, and what delegation expands to)          |
+| `search_in`                  | the model's text identity (`?q=`); default is "search what you see"        |
 | `action`                     | buttons, per row or per collection                                         |
 | `fieldset`                   | a named *selection* of fields and actions                                  |
 
@@ -357,7 +357,7 @@ Keyed by what a field *is* — with zero config, every row applies without decla
 | enum                      | i18n'd badge (click to filter; `—` if null)  | select of enum keys (+ "not set" if nullable)                                        | validated against the enum; "not set" → IS NULL         | yes         |
 | json column               | pretty `<pre>` (rouge if present)            | —                                                                                    | —                                                       | no          |
 | Active Storage attachment | image / preview / icon by content type       | —                                                                                    | —                                                       | no          |
-| `belongs_to`              | nil-safe link via target's `label`           | select valued by target's `identify_by` (text over `search_in` above `select_limit`) | `where(assoc: Target.where(identify_by => v))`          | v2          |
+| `belongs_to`              | nil-safe link via target's `label`           | select valued by target's `identify_by` (text over target's `label` above `select_limit`) | `where(assoc: Target.where(identify_by => v))`          | v2          |
 | `has_many` / habtm        | "a, b +n more" links                         | opt-in via `filter` facet                                                            | —                                                       | no          |
 | public model method       | by value type                                | —                                                                                    | —                                                       | —           |
 | `render` block / `as:`    | as declared                                  | — *(unless `filter` facet)*                                                          | — *(unless `sort` facet)*                               | facet-gated |
@@ -430,7 +430,7 @@ gear, `picked_columns:` seeds it (`:auto` reads `?cols=`; an Array is verbatim,
 ```ruby
 label(method = nil, &block)
 identify_by(column)                               # default :id
-search_in(*spec) | search_in { |scope, q| … }     # default: own string/text columns
+search_in(*spec) | search_in { |scope, q| … }     # default: "search what you see" (displayed fields + labels)
 attribute(name, as: nil, form_as: nil, if: nil, editable: nil, **renderer_options, &block)
 attributes(*names, **shared_options)
   # bare block (arity 1)  = render markup
@@ -456,7 +456,10 @@ a block; an `as:` renderer with no matching partial or a missing gem.
 ```ruby
 CrudComponents::Query.new(model, params, fieldset: :default, ability: nil, param_prefix: nil)
                                             # #apply(scope) → relation; #active?
-CrudComponents.permitted_attributes(model, action: :update, ability: nil)  # strong-params list
+                                            # #permitted_keys → strong-params list for the filters it reads
+                                            # #filter_params → present subset, for filter-preserving links
+                                            # #active_filters → active values by logical name, for chips
+CrudComponents.permitted_attributes(model, action: :update, ability: nil)  # strong-params list (forms)
 CrudComponents.configure { |config| … }     # css/icon maps, select_limit, defaults
 ```
 
@@ -465,7 +468,8 @@ CrudComponents.configure { |config| … }     # css/icon maps, select_limit, def
 
 | Doc                                        | What                                                                             |
 | ------------------------------------------ | -------------------------------------------------------------------------------- |
-| [docs/fields.md](docs/fields.md)           | Fields, renderers, facets, the search spec, identity, per-flavor behavior        |
+| [docs/fields.md](docs/fields.md)           | Fields, renderers, facets, dynamic & path columns, identity, per-flavor behavior |
+| [docs/filtering.md](docs/filtering.md)     | The `filter` facet, the search spec, typed filter controls, the standalone form  |
 | [docs/views.md](docs/views.md)             | The helpers, fieldsets, actions & route resolution, the manual query, pagination |
 | [docs/forms.md](docs/forms.md)             | `crud_form`, the permit list, `editable:`, form controls, attachments            |
 | [docs/security.md](docs/security.md)       | Permissions (`if:`/`editable:`), the whitelist, and the injection-safe URL model |

data/RELEASING.md

@@ -21,24 +21,29 @@ publisher above. After that, every release is hands-off.
 
 ## Cutting a release
 
-1. **Bump the version** in `lib/crud_components/version.rb`. Open it as a normal
-   PR; merge to `main`.
+1. **Bump the version and close the changelog.** Set the new version in
+   `lib/crud_components/version.rb`, and in `CHANGELOG.md` rename the
+   `## Unreleased` heading to `## vX.Y.Z — YYYY-MM-DD`, adding a fresh empty
+   `## Unreleased` above it. Open as a normal PR; merge to `main`.
 
 2. **Publish the release** for the matching tag — the workflow expects `vX.Y.Z`
-   to equal the version in `version.rb`:
+   to equal the version in `version.rb` — using that version's changelog section
+   as the notes:
 
    ```bash
-   gh release create v0.1.0 --title v0.1.0 --generate-notes
+   notes=$(awk '/^## v[0-9]/{ if (seen) exit; seen=1; next } seen' CHANGELOG.md)
+   gh release create v0.1.0 --title v0.1.0 --notes "$notes"
    ```
 
-   (or use the GitHub UI → *Draft a new release* → pick the tag →
-   *Generate release notes*). Publishing fires the workflow, which runs the
-   tests, builds the gem, attaches a build-provenance attestation, and pushes it.
+   (or use the GitHub UI → *Draft a new release* → pick the tag, and paste that
+   section.) Publishing fires the workflow, which runs the tests, builds the gem,
+   attaches a build-provenance attestation, and pushes it.
 
 That's it — `gem-push.yml` does the build + push; you never touch credentials.
 
 ### Versioning
 
 [SemVer](https://semver.org): new backward-compatible features → minor (`0.x`),
-bug-fixes → patch. Release notes are generated from the merged PRs
-(`--generate-notes`); there is no hand-maintained changelog.
+bug-fixes → patch. Release notes are the version's section in `CHANGELOG.md` —
+keep its `## Unreleased` list current as you merge user-facing PRs, and step 1
+turns it into the release.

data/app/views/crud_components/_filter.html.erb

@@ -23,6 +23,26 @@
         <%= filter.render_filter_control(field, filter.query) %>
       </div>
     <% end %>
+    <%# Sort picker for headerless surfaces (cards/lists) — a table carries its own
+        header sort links, so this is opt-in via `sort: true`. %>
+    <% if filter.sort_control? %>
+      <% sort_field, sort_dir = filter.sort_state %>
+      <div class="col">
+        <span class="<%= css.form_label %>"><%= t('crud_components.filter.sort_by', default: 'Sort by') %></span>
+        <div class="<%= css.input_group %>">
+          <%= select_tag filter.param_name('sort'),
+                         options_for_select([[t('crud_components.filter.unsorted', default: '—'), '']] +
+                                            filter.sort_field_choices, sort_field),
+                         class: css.select_input, id: nil,
+                         aria: { label: t('crud_components.filter.sort_by', default: 'Sort by') } %>
+          <%= select_tag filter.param_name('dir'),
+                         options_for_select([[t('crud_components.filter.asc', default: 'Ascending'), 'asc'],
+                                             [t('crud_components.filter.desc', default: 'Descending'), 'desc']], sort_dir),
+                         class: css.select_input, id: nil,
+                         aria: { label: t('crud_components.filter.direction', default: 'Direction') } %>
+        </div>
+      </div>
+    <% end %>
   </div>
   <div class="mt-3 d-flex gap-2">
     <button type="submit" class="<%= css.button_primary %>">

data/app/views/crud_components/filters/_date.html.erb

@@ -0,0 +1,5 @@
+<%# Locals: field, query, form_id, compact, autosubmit, param_name, css %>
+<%= tag.input type: 'date', name: param_name,
+              value: query.value(field.name.to_s),
+              class: compact ? css.input_sm : css.input, form: form_id,
+              aria: { label: field.human_name } %>

data/app/views/crud_components/filters/_number.html.erb

@@ -0,0 +1,6 @@
+<%# Locals: field, query, form_id, compact, autosubmit, param_name, css %>
+<%= tag.input type: 'number', step: 'any', name: param_name,
+              value: query.value(field.name.to_s),
+              class: compact ? css.input_sm : css.input, form: form_id,
+              placeholder: (field.human_name if compact),
+              aria: { label: field.human_name } %>

data/app/views/crud_components/filters/_presence.html.erb

@@ -0,0 +1,13 @@
+<%# Locals: field, query, form_id, compact, autosubmit, param_name, css
+    Present / absent control for an attachment column — the query turns the value
+    into an EXISTS / NOT EXISTS (see Fields::AttachmentField). %>
+<% choices = [
+     [t('crud_components.filter.any', default: '–'), ''],
+     [t('crud_components.filter.present', default: 'Present'), CrudComponents::PRESENT_FILTER_VALUE],
+     [t('crud_components.filter.absent', default: 'Absent'), CrudComponents::ABSENT_FILTER_VALUE]
+   ] %>
+<%= select_tag param_name,
+               options_for_select(choices, query.value(field.name.to_s)),
+               class: compact ? css.select_input_sm : css.select_input, form: form_id, id: nil,
+               data: (autosubmit ? { action: 'change->crud-filter#submit' } : {}),
+               aria: { label: field.human_name } %>

data/config/locales/crud_components.de.yml

@@ -24,12 +24,19 @@ de:
     filter:
       any: "–"
       not_set: "Nicht gesetzt"
+      present: "Vorhanden"
+      absent: "Nicht vorhanden"
       "yes": "Ja"
       "no": "Nein"
       search: "Suche"
       apply: "Anwenden"
       submit: "Filtern"
       reset: "Zurücksetzen"
+      sort_by: "Sortieren nach"
+      unsorted: "–"
+      direction: "Richtung"
+      asc: "Aufsteigend"
+      desc: "Absteigend"
     pager:
       label: "Seitennummerierung"
       summary: "Seite %{page} von %{total} · %{count} gesamt"

data/config/locales/crud_components.en.yml

@@ -25,12 +25,19 @@ en:
     filter:
       any: "–"
       not_set: "Not set"
+      present: "Present"
+      absent: "Absent"
       "yes": "Yes"
       "no": "No"
       search: "Search"
       apply: "Apply"
       submit: "Filter"
       reset: "Reset"
+      sort_by: "Sort by"
+      unsorted: "–"
+      direction: "Direction"
+      asc: "Ascending"
+      desc: "Descending"
     pager:
       label: "Pagination"
       summary: "Page %{page} of %{total} · %{count} total"

data/crud_components.gemspec

@@ -20,6 +20,7 @@ Gem::Specification.new do |spec|
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
   spec.metadata['rubygems_mfa_required'] = 'true'
 
   # Prefer git, but fall back to a glob so the gem (and the demo image) build

data/docs/fields.md

@@ -29,7 +29,7 @@ attribute :token, filter: false                       # opt a derived field out
 `attributes` (plural) applies shared options to several fields at once:
 
 ```ruby
-attributes :participants, :owner, if: :manage
+attributes :purchase_price, :shop_margin, if: :manage
 ```
 
 The field universe is always *all* derived columns/associations plus declared computed
@@ -152,7 +152,10 @@ meaning until a facet tells the gem how to express it.
 
 > **Query-block contract.** `filter`/`sort`/`search_in` blocks receive `(scope, value)`
 > (or `(scope, dir)` for sort) and return a relation. There is no view context at query
-> time; the scope arrives extended with `where_like` (below).
+> time; the scope arrives extended with `where_like`.
+
+For the `filter` facet's spec mini-language, typed controls and the standalone form, see
+[Filtering & search](filtering.md).
 
 ## Dynamic columns
 
@@ -206,6 +209,10 @@ CrudComponents::DynamicColumn.new(:priority, as: :number,
 ) { |record, loaded| loaded[record.id]&.value }
 ```
 
+A dynamic column filters the way it renders: give its `filter:` block keyword params
+(`geq:`/`leq:`, `eq:`, `contains:`) and it gets the control its `as:` type wants — a number/date
+range, a yes/no select, a dropdown; see [Filtering → typed filter controls](filtering.md#typed-filter-controls).
+
 `if:` follows the same rules as a declared field's: a denied column is absent from the
 table, the filter row, sorting and `?cols=` — everywhere. See the column picker in
 [views.md](views.md#column-picker) for letting users choose which of these they see, and
@@ -261,9 +268,9 @@ These are not specific to `DynamicColumn` — a declared `attribute :status, hea
 takes the same options. Everything works in the non-grouped and grouped (`group_by:`) layouts,
 and plays with the column picker (a hidden column simply renders no header). The
 `/column_headers` page in `test/dummy` is a full worked example. This is what lets a
-participants × mails / × resources **matrix** live entirely in `crud_collection` — one
-`DynamicColumn` per mail/resource, its controls in its own header — instead of a hand-built
-controls strip above the table.
+books × properties **matrix** live entirely in `crud_collection` — one `DynamicColumn` per
+property, its controls in its own header — instead of a hand-built controls strip above
+the table.
 
 ## Path columns
 
@@ -289,7 +296,7 @@ fieldset :index, %i[title publisher.name authors.email]
   then a link to its show page — so a path column doubles as a jump-to-the-object.
 - A **list** path (has_many / habtm) renders the values joined — `authors.email` shows
   every author's email (each linkified, since `email` is a smart-rendered name) — and is
-  **filterable** (a contains-match through the join, via the [search spec](#the-search-spec))
+  **filterable** (a contains-match through the join, via the [search spec](filtering.md#the-search-spec))
   but not sortable by default (no single value to order by; add a `sort` facet if you have a
   meaningful aggregate).
 
@@ -312,51 +319,12 @@ limits report a clear `DefinitionError`.
 `attribute(:"authors.email", if: :manage)` to gate it, or give it a block to override how it
 renders, filters or sorts.
 
-## The search spec
-
-One declarative mini-language for "case-insensitive contains across these columns,
-joining as needed" — shared by `filter` (passed positionally) and `search_in`:
-
-```ruby
-filter :title                                  # own column
-filter :title, :subtitle                       # several own columns, OR-combined
-filter authors: %i[name email]                 # join, explicit columns
-filter user: { address: %i[street town] }      # nested joins, explicit columns
-filter :publisher                              # join, DELEGATE to Publisher's search_in
-filter :title, { authors: :name }              # mixed
-```
-
-The **delegation form** — an association name *without* columns — means "search it the
-way that model defines being searched" (its `search_in`). It is the idiomatic style and
-stays correct as the target model's definition evolves.
-
-The gem turns a spec into `left_joins` plus parameterized, wildcard-escaped `ILIKE`
-(via `sanitize_sql_like` with an explicit `\` escape char, so `%`, `_` and `\` are all
-literal). A spec contains only column/association names you wrote — **no SQL strings**,
-nothing to sanitize. A joined match is `DISTINCT`; an own-column spec is not (no join to
-dedupe). Delegation cycles are guarded (max 5 delegation hops) and raise rather than
-stack-overflow.
-
-### The escape hatch
-
-A block is the escape hatch for genuinely custom logic; the scope it receives carries
-the same machinery, so you keep the safe pit of success without `sanitize_sql_like`:
-
-```ruby
-filter do |scope, value|
-  scope.where(active: true).where_like({ authors: :name }, value)
-end
-```
-
-`where_like(spec, value)` is available on every scope handed to a filter/search block.
-Raw SQL in a block is possible — and then explicitly your responsibility.
-
 ## Identity: `label`, `identify_by`, `search_in`, `icon`
 
 ```ruby
 label :title              # method or block; default: name → title → first string column → "Book #42"
 identify_by :slug         # default: :id
-search_in :title, :subtitle, :publisher   # default: own string/text columns
+search_in :title, :subtitle, :publisher   # default: the index's string/text fields + associations' labels
 icon 'book'               # default: guessed from the model name (config.model_icons), else none
 ```
 
@@ -364,13 +332,17 @@ icon 'book'               # default: guessed from the model name (config.model_i
   Block form: `label { |book| "#{book.title} (#{book.published_on&.year})" }`. With no
   string column at all it falls back to `"Book #42"` (`model_name.human` + ` #` + id).
   When the label reaches into associations, declare them with `preload:` so they're
-  eager-loaded wherever this model is shown — `label :full_title, preload: %i[publisher]`
+  eager-loaded wherever this model is shown — `label :display_title, preload: %i[publisher]`
   ([Performance](performance.md#eager-loading-render-dependencies)).
 - **`identify_by`** — the column URL params use to identify a record of this model. With
   `identify_by :slug`, a filter URL reads `?publisher=tor-books` and resolves via
   `Publisher.where(slug: …)`.
-- **`search_in`** — the model's text identity: what `?q=` searches, what the belongs_to
-  text-filter fallback matches, and what delegated specs (`filter :publisher`) expand to.
+- **`search_in`** — the model's text identity: what `?q=` searches. Undeclared, it's
+  "search what you see" — the index's own string/text columns plus its associations'
+  labels — so secret columns you don't display are never searched. Declare it to override
+  (a custom column list, or a block for full-text/`tsvector`). The belongs_to text-filter
+  fallback and an association named in a spec (`filter :publisher`) match the target's
+  **label** only, never its `search_in`.
 - **`icon`** — a Bootstrap-icon name (no `bi-` prefix — paired with `config.css.icon_prefix`,
   swap the whole library there) that badges the model wherever it appears: column-picker
   groups, association links, path-column cells. Undeclared, it's guessed from the model name
@@ -429,8 +401,8 @@ with `preload: %i[publisher]` — [Performance](performance.md#eager-loading-ren
 | enum                      | i18n'd badge (nil `—`), click-to-filter      | select of keys                                           | yes  | values validated against the enum; nullable column adds a "not set" (IS NULL) choice |
 | json                      | `<pre>` (rouge if present)                   | —                                                        | —    | not form-editable in v1                                                              |
 | Active Storage attachment | image / preview / icon by content type       | —                                                        | —    | form shows current; keep/add/remove via signed_ids                                   |
-| `belongs_to`              | nil-safe link via target `label`             | select (≤ `select_limit`) / text over target `search_in` | v2   | resolves by `identify_by`                                                            |
-| `has_many` / habtm        | "a, b +n more" links                         | opt-in `filter` facet                                    | no   | "+n more" links to nested/filtered index                                             |
+| `belongs_to`              | nil-safe link via target `label`             | select (≤ `select_limit`) / text over target `label`    | v2   | resolves by `identify_by`                                                            |
+| `has_many` / habtm        | "a, b +n more" links                         | text over the children's `label` (columnless label: facet) | no   | "+n more" links to nested/filtered index                                             |
 | public method             | by value type                                | —                                                        | —    | needs a facet to filter/sort                                                         |
 | `render` block            | block output                                 | —                                                        | —    | facets add filter/sort                                                               |
 
@@ -438,5 +410,5 @@ Click-to-filter: in a collection, an enum badge and a boolean icon link to set t
 column's filter (respecting the fieldset whitelist and `param_prefix`). The inline
 filter row uses compact controls; the standalone `crud_filter` form uses full-size ones.
 
-See also: [Views & fieldsets](views.md) · [Forms](forms.md) · [Security](security.md) ·
-[Extending](extending.md).
+See also: [Filtering & search](filtering.md) · [Views & fieldsets](views.md) · [Forms](forms.md) ·
+[Security](security.md) · [Extending](extending.md).

data/docs/filtering.md

@@ -0,0 +1,167 @@
+# Filtering & search
+
+How a collection narrows its rows: the per-field `filter` facet, the search spec shared by
+`filter` and `search_in`, typed filter controls for dynamic columns, and the standalone
+`crud_filter` form. For how params reach SQL as a whole (the query tri-state) see
+[views.md](views.md#the-query-tri-state); for the security rule ("only filter what you can
+see") see [security.md](security.md).
+
+> See it live: the [**filters demo**](https://crud-components.zelenin.de/books) (inline
+> filter row + sidebar) and [**custom fields**](https://crud-components.zelenin.de/custom_fields)
+> (typed controls on user-defined columns).
+
+## The `filter` facet
+
+Every column is filterable by default through the control its type implies — a string by
+substring, a number/date by range, an enum/boolean by select, an association by its target's
+**label** (the name shown in the cell): a `belongs_to` as a select/text, a `has_many`/habtm as
+text matching any child. A *computed* column, or an association whose label has no column
+behind it — a block, or a method name like `label :display_title` — opts in with the `filter`
+facet (a [search spec](#the-search-spec) or a block):
+
+```ruby
+attribute :author_names do
+  render { |book| book.authors.map(&:name).to_sentence }
+  filter authors: :name                       # spec: contains-match through the join
+end
+
+attribute :token, filter: false               # opt a derived field out of filtering
+```
+
+A `has_many`/habtm column filters by its children's label with no extra config — typing in its
+filter box keeps owners that have a matching child. Here `/publishers` (which lists each
+publisher's **books**) is narrowed to publishers holding a book whose title contains "winter":
+
+![The /publishers filter row: a text box under the Books column holding "winter", and the rows below narrowed to publishers that have a matching book](screenshots/has-many-filter.png)
+
+A `filter`/`search_in` block receives `(scope, value)` and returns a relation; the scope
+arrives extended with `where_like` (see [the escape hatch](#the-escape-hatch)).
+
+## Typed filter controls
+
+A [dynamic column](fields.md#dynamic-columns) **filters the way it renders**. Give its
+`filter:` block keyword params and it gets the control its `as:` type wants — a date column a
+date range, a number column a number range, a boolean a yes/no select:
+
+```ruby
+CrudComponents::DynamicColumn.new(:published_on, as: :date,
+  filter: ->(scope, geq:, leq:) { … })          # → a date-range control
+```
+
+The block declares which of `geq:` / `leq:` / `eq:` / `contains:` it handles and is called
+with **only those** — each value already cast to the type (`:number` → `BigDecimal`, `:date`
+→ `Date`, `:boolean` → `true`/`false`), or `nil` when the param is blank or doesn't parse, so
+junk never reaches SQL. The keywords also choose the control: a number/date block that asks for
+a bound (`geq:`/`leq:`) renders a **range**, one that asks only for `eq:` a **single field**. So
+one block drives both the SQL and the UI.
+
+![The /custom_fields filter row: a text box for the string property, a number range for the numeric one, a yes/no/any select for the boolean and a date range for the date](screenshots/typed-filters.png)
+
+A positional `filter: ->(scope, value)` block (no keywords) stays a plain text filter — the
+simplest case, unchanged. See [`/custom_fields`](https://crud-components.zelenin.de/custom_fields)
+for one filter per flavor (`test/dummy/app/models/property_definition.rb`).
+
+### When the filter type isn't the render type
+
+`filter_as:` overrides the filter type independently of `as:` (the same way `form_as:` overrides
+the form input) — for a custom renderer, or when you want a different control. A `:select` adds
+its options with `filter_choices:`:
+
+```ruby
+CrudComponents::DynamicColumn.new(:rating, as: :stars,        # renders as stars…
+  filter_as: :number, filter: ->(scope, geq:, leq:) { … })   # …but filters as a number range
+
+CrudComponents::DynamicColumn.new(:binding, as: :string,
+  filter_as: :select, filter_choices: [%w[Hard hardcover], %w[Soft paperback]],
+  filter: ->(scope, eq:) { … })                              # a dropdown
+```
+
+`filter_choices:` takes `[[label, value], …]` (or a callable returning them).
+
+## The search spec
+
+One declarative mini-language for "case-insensitive contains across these columns,
+joining as needed" — shared by `filter` (passed positionally) and `search_in`:
+
+```ruby
+filter :title                                  # own column
+filter :title, :subtitle                       # several own columns, OR-combined
+filter authors: %i[name email]                 # join, explicit columns
+filter user: { address: %i[street town] }      # nested joins, explicit columns
+filter :publisher                              # join, match Publisher's label (what you see)
+filter :title, { authors: :name }              # mixed
+```
+
+The **label form** — an association name *without* columns — matches the target's
+**label**: the name shown in that association's cell ("search what you see"). It is the
+idiomatic style and never reaches the target's other columns, so a secret column on the
+target can't be probed through an association. When the target's label has no column behind
+it — a custom block, or a method name like `label :display_title` — spell the columns out
+(`filter authors: :name`).
+
+The gem turns a spec into `left_joins` plus parameterized, wildcard-escaped `ILIKE`
+(via `sanitize_sql_like` with an explicit `\` escape char, so `%`, `_` and `\` are all
+literal). A spec contains only column/association names you wrote — **no SQL strings**,
+nothing to sanitize. A joined match is `DISTINCT`; an own-column spec is not (no join to
+dedupe).
+
+### The escape hatch
+
+A block is the escape hatch for genuinely custom logic; the scope it receives carries
+the same machinery, so you keep the safe pit of success without `sanitize_sql_like`:
+
+```ruby
+filter do |scope, value|
+  scope.where(active: true).where_like({ authors: :name }, value)
+end
+```
+
+`where_like(spec, value)` is available on every scope handed to a filter/search block.
+Raw SQL in a block is possible — and then explicitly your responsibility.
+
+## The standalone filter form
+
+`crud_collection` renders an inline filter row; `crud_filter` renders the same filters as a
+**standalone form** (a sidebar or modal) you place yourself. It takes the same `extra_columns:`
+as `crud_collection`, so a card grid gets its [dynamic-column](fields.md#dynamic-columns)
+filters without hand-building a `Query`:
+
+```erb
+<%= crud_collection @books, layout: :cards, extra_columns: @columns %>
+<%= crud_filter   Book, extra_columns: @columns, sort: true %>
+```
+
+A table carries sort links in its column headers, but a **headerless** surface (cards, a list)
+has none — so pass **`sort: true`** to render a field + direction picker built from the query's
+sortable fields. It submits `?sort=&dir=` with the rest of the form, needs no JavaScript, and is
+opt-in (a table doesn't need it).
+
+![The cards view's filter sidebar: a filter per field, then a "Sort by" field-and-direction picker at the bottom](screenshots/filter-sidebar.png)
+
+See it live on the [cards layout](https://crud-components.zelenin.de/books?layout=cards).
+
+## The params a query reads
+
+`crud_collection` and `crud_filter` build and read their own `Query`, so you rarely touch
+params directly. When you do drive a [manual query](views.md#the-manual-query-pagination-and-big-tables)
+from a controller, the query already knows exactly which params it reads — a param only
+applies if it names a filterable field you can see (plus the reserved `q`/`sort`/`dir`), so
+junk never reaches SQL and it's safe without a permit list. But a controller usually wants
+that param surface anyway: to strong-params it, and to rebuild **filter-preserving links** (a
+pager, a breadcrumb, a "clear search" target). Rather than hand-maintain a list that mirrors
+the columns and drifts when they change, ask the query:
+
+```ruby
+@query.permitted_keys   # prefixed param names it reads: each filter field's value and
+                        # `_geq`/`_leq` bounds, plus q/sort/dir. (page/per are yours.)
+@query.filter_params    # the present subset of *this* request, by real param name —
+                        # e.g. { "title" => "hobbit", "price_geq" => "10", "sort" => "name" }
+@query.active_filters   # active filter/search values by logical name, for chips —
+                        # e.g. { "title" => "hobbit", "q" => "dragons" }
+```
+
+`filter_params` is the one to thread into link helpers (`books_path(**@query.filter_params)`)
+instead of keeping a hand-kept params shim; it already respects `param_prefix:`. All three are
+fieldset- and permission-bound: a key a user can't see is never listed.
+
+See also: [Fields & rendering](fields.md) · [Views & fieldsets](views.md) · [Security](security.md).

data/docs/performance.md

@@ -13,7 +13,7 @@ config can't guess.
   [Fast cell rendering](#fast-cell-rendering).
 - **belongs_to filters degrade gracefully.** A belongs_to filter renders a `<select>` of
   the target's records up to `config.select_limit` (default 250); beyond that it switches
-  to a text input over the target's `search_in`, so a 50k-row association never builds a
+  to a text input over the target's `label`, so a 50k-row association never builds a
   giant `<select>`. (A typeahead/autocomplete is a later version.)
 - **Long text truncates** in collections — the full value renders on the record page.