crud_components 0.1.0 → 0.2.1

data/docs/security.md

@@ -125,15 +125,17 @@ The guarantees, each backed by a test:
 
 ## `?q=` search and permissions
 
-`search_in` is the model's **text identity**, used model-globally (it powers `?q=`, the
-belongs_to text fallback, and delegated specs). Two things follow:
+`search_in` is the model's **text identity**, powering `?q=`. Three things follow:
 
 - A **declared, permission-gated** column (`attribute :notes, if: :manage`) is dropped from
   the search spec for a user who can't see it — `?q=` upholds "hidden everywhere".
-- An **undeclared** column in the zero-config default spec (all string/text columns) is
-  searched model-globally by design. If a model has a sensitive string column you don't
-  want reachable via `?q=`, declare `search_in` explicitly with only the columns you want.
-  The default is broad so zero-config search "just finds things"; narrowing it is the
-  author's call.
+- The **zero-config default is "search what you see"**: the index's own string/text columns
+  plus its associations' labels. A column you never display — including a model's secret
+  columns (`encrypted_password`, `*_token`, `api_key`) — is never searched. Declare
+  `search_in` to override (a narrower column list, or a block for full-text).
+- An **association** reached by `?q=`, the belongs_to text fallback, or a spec naming it
+  (`filter :publisher`) matches the target's **label** only — never the target's other
+  columns. So filtering by a `belongs_to :user` can't probe `users.encrypted_password`,
+  even when `User` has no `crud_structure` of its own.
 
   See also: [Performance](performance.md) · [Views](views.md) · [Fields](fields.md) · [Forms](forms.md).

data/docs/views.md

@@ -15,7 +15,7 @@ this doc.
 crud_collection(records, fieldset: nil, layout: :table, query: :auto, param_prefix: nil,
                 actions: true, group_by: nil, extra_columns: nil, picker: false, picked_columns: :auto)
 crud_record(record, fieldset: nil, actions: true, layout: :record, picked_columns: :auto)
-crud_filter(model, fieldset: nil, query: nil, param_prefix: nil, layout: :filter)
+crud_filter(model, fieldset: nil, query: nil, param_prefix: nil, extra_columns: nil, sort: false, layout: :filter)
 crud_form(record, fieldset: nil, action: nil, url: nil, method: nil, layout: :form)   # see forms.md
 crud_actions(record_or_model, fieldset: nil)   # a record → row actions; a model class → collection actions
 ```
@@ -95,6 +95,10 @@ fieldset :index, %i[cover title price], filters: %i[genre published_on]
 `filters:` extends the fieldset's filterable set (sorting stays strictly visible fields);
 `crud_filter` renders all of them.
 
+The standalone `crud_filter` form takes `extra_columns:` (for dynamic-column filters) and
+`sort: true` (a sort picker for headerless surfaces) — see
+[Filtering → the standalone form](filtering.md#the-standalone-filter-form).
+
 ### Layout is a separate axis
 
 ```erb
@@ -365,7 +369,9 @@ the query into your own hands — the explicit form of what the helper does auto
 
 Everything stays an ActiveRecord relation, so any paginator and any pre-existing scope
 compose. The manual query is also how you get the filtered relation for counts, CSV
-exports, or charts.
+exports, or charts. To permit the query's params yourself or rebuild filter-preserving
+links by hand, the query exposes the params it reads — see
+[the params a query reads](filtering.md#the-params-a-query-reads).
 
 **The footer pager renders itself** when the relation you pass is already paginated —
 i.e. you called `.page` and it decorates the relation (kaminari, will_paginate). The gem

data/lib/crud_components/builder.rb

@@ -34,7 +34,7 @@ module CrudComponents
     # How a record is titled (links, headings). Give a method name or a block.
     # @param method [Symbol, nil] a method on the record returning its label.
     # @param preload [Array<Symbol>, Symbol, nil] associations the label reaches
-    #   into (`label :full_title, preload: %i[customer training]`). They're
+    #   into (`label :display_title, preload: %i[publisher authors]`). They're
     #   eager-loaded automatically whenever this model is shown as another
     #   model's association column — declare once, no N+1 anywhere.
     # @yield [record] computes the label; receives the record.
@@ -51,7 +51,7 @@ module CrudComponents
     # Associations to eager-load whenever this model is rendered (as a row or as
     # another model's association cell) — for label/render dependencies the gem
     # can't infer. Additive with `label …, preload:`; declare more than once to
-    # accumulate. e.g. `preload :customer, :training`.
+    # accumulate. e.g. `preload :publisher, :authors`.
     # @param names [Array<Symbol>] association names (nested hashes allowed).
     # @return [void]
     def preload(*names)
@@ -154,7 +154,7 @@ module CrudComponents
     private
 
     # Normalize a preload value to an array of includes-specs, leaving a nested
-    # hash (`{ customer: :company }`) intact (Array() would split it).
+    # hash (`{ publisher: :books }`) intact (Array() would split it).
     def preload_list(value)
       case value
       when nil then []

data/lib/crud_components/dynamic_column.rb

@@ -12,13 +12,21 @@ module CrudComponents
   #       PropertyValue.where(definition: prop, subject: records).index_by(&:subject_id)
   #     },
   #     sort:   ->(scope, dir) { ... },              # optional — omit for display-only
-  #     filter: ->(scope, value) { ... }) { |record, loaded| loaded[record.id]&.value }
+  #     filter: ->(scope, geq:, leq:) { ... }) { |record, loaded| loaded[record.id]&.value }
   #
   # The block is the value resolver: `|record|` or `|record, loaded|`, where
   # `loaded` is whatever `preload:` returned. It returns a plain value that the
   # `as:` renderer (or, with no `as:`, the value's type) displays — exactly like
-  # a computed field. `filter:`/`sort:` are the same facet blocks the DSL takes;
-  # supply them only when the data is reachable in SQL, otherwise the column is
+  # a computed field.
+  #
+  # `sort:` is the same facet block the DSL takes. `filter:` reaches SQL too, but
+  # the control it renders follows the column's type: a `filter:` block that
+  # declares keyword params (`geq:`/`leq:`, `eq:`, `contains:`) filters as the
+  # `as:` type does — a `:number` column gets a number range, `:date` a date range,
+  # `:boolean` a yes/no select. Override the filter type with `filter_as:` (and
+  # `filter_choices:` for a select) when it differs from `as:`. A positional
+  # `filter: ->(scope, value)` block stays a plain text filter. Supply `filter:`/
+  # `sort:` only when the data is reachable in SQL, otherwise the column is
   # display-only and never reaches the query layer.
   #
   # A dynamic column often *is* a domain object (a mail, a resource), so its

data/lib/crud_components/fields/attachment_field.rb

@@ -10,13 +10,35 @@ module CrudComponents
       end
 
       def eager_load
-        [many? ? :"#{name}_attachments" : :"#{name}_attachment", *declared_preloads]
+        [attachment_reflection, *declared_preloads]
+      end
+
+      # ── filtering ──────────────────────────────────────────────────────────
+      # An attachment has no value to type into a box, but "has a cover / has no
+      # cover" is the natural question — so it filters by presence: a 3-state
+      # any/present/absent control that composes into the query as an EXISTS /
+      # NOT EXISTS over the backing *_attachment(s) association.
+      def derived_filterable? = true
+      def derived_filter_control = :presence
+
+      def apply_derived_filter(scope, value: nil, **)
+        case value
+        when CrudComponents::PRESENT_FILTER_VALUE then scope.where.associated(attachment_reflection)
+        when CrudComponents::ABSENT_FILTER_VALUE  then scope.where.missing(attachment_reflection)
+        else scope
+        end
       end
 
       # ── forms ────────────────────────────────────────────────────────────
       def default_editable? = true
       def form_control = :file
       def permit_param = many? ? { name => [] } : name
+
+      private
+
+      # The has_one_attached / has_many_attached association the eager-load and the
+      # presence filter join through.
+      def attachment_reflection = many? ? :"#{name}_attachments" : :"#{name}_attachment"
     end
   end
 end

data/lib/crud_components/fields/base.rb

@@ -56,6 +56,14 @@ module CrudComponents
         model.columns_hash[name.to_s]
       end
 
+      # How this field feeds the default ?q= ("search what you see"): its own
+      # string/text column, or nil for fields with no free-text column behind
+      # them (numbers, dates, enums, attachments, computed). Associations
+      # override this to contribute their target's label.
+      def search_spec_entry
+        name if column && %i[string text].include?(column.type)
+      end
+
       # Whether the backing column permits NULL — gates the "not set" filter
       # choice and the 3-state form control for nullable boolean/enum fields.
       def nullable?
@@ -85,7 +93,7 @@ module CrudComponents
       end
 
       def renderer_options
-        options.except(:as, :if, :form_as, :label, :header, :header_actions)
+        options.except(:as, :if, :form_as, :label, :header, :header_actions, :filter_as, :filter_choices)
       end
 
       # ── permissions ──────────────────────────────────────────────────────
@@ -97,7 +105,7 @@ module CrudComponents
       def filterable?
         return false if facets[:filter] == false
         return false if CrudComponents::RESERVED_PARAMS.include?(name.to_s)
-        return true if filter_facet
+        return true if typed_filter || filter_facet
 
         derived_filterable?
       end
@@ -107,6 +115,16 @@ module CrudComponents
           facets[:filter].is_a?(Hash) || facets[:filter].is_a?(Symbol) ? facets[:filter] : nil
       end
 
+      # The internal {TypedFilter} for a `filter:` block that declares keyword params
+      # (eq:/geq:/leq:/contains:) — its value type comes from `filter_as:` or `as:`,
+      # so it renders the matching control and receives cast values. A positional
+      # `->(scope, value)` block has none (plain text filter); nil for everyone else.
+      def typed_filter
+        return @typed_filter if defined?(@typed_filter)
+
+        @typed_filter = build_typed_filter
+      end
+
       def derived_filterable?
         false
       end
@@ -114,6 +132,8 @@ module CrudComponents
       # Which filter control partial to render: :text, :select, :boolean,
       # :number_range or :date_range.
       def filter_control
+        return typed_filter.control if typed_filter
+
         filter_facet ? :text : derived_filter_control
       end
 
@@ -121,22 +141,26 @@ module CrudComponents
         :text
       end
 
-      def filter_choices(_query = nil)
-        nil
+      def filter_choices(query = nil)
+        typed_filter&.filter_choices(query)
       end
 
       def range_filter?
         filter_control == :number_range || filter_control == :date_range
       end
 
-      # `exact`, `geq`, `leq` are the raw param values (Strings or nil).
-      def apply_filter(scope, exact: nil, geq: nil, leq: nil)
-        if filter_facet
-          return scope unless exact
+      # The raw param values (Strings or nil): `value` is the bare `?field=`, `geq`
+      # and `leq` the range bounds. How a field reads `value` is up to it — an
+      # exact match for a number/enum, a substring for text.
+      def apply_filter(scope, value: nil, geq: nil, leq: nil)
+        if typed_filter
+          typed_filter.apply(scope, value:, geq:, leq:)
+        elsif filter_facet
+          return scope unless value
 
-          apply_filter_facet(scope, exact)
+          apply_filter_facet(scope, value)
         else
-          apply_derived_filter(scope, exact:, geq:, leq:)
+          apply_derived_filter(scope, value:, geq:, leq:)
         end
       end
 
@@ -170,9 +194,15 @@ module CrudComponents
         false
       end
 
+      # An explicit `?sort=` must win over any order a prior stage set (a search
+      # backend's relevance rank, a default scope). The Symbol/derived branches
+      # already `.reorder`; a Proc facet is handed a scope whose prior order is
+      # cleared, so a block using the obvious `.order(...)` overrides the rank too
+      # rather than appending to it (see issue #23). A block may still `.reorder`
+      # itself — that composes fine on an already-cleared scope.
       def apply_sort(scope, dir)
         case (facet = sort_facet)
-        when Proc then facet.call(scope, dir)
+        when Proc then facet.call(scope.reorder(nil), dir)
         when Symbol then scope.reorder(model.arel_table[facet].public_send(dir))
         else scope.reorder(model.arel_table[name].public_send(dir))
         end
@@ -248,6 +278,36 @@ module CrudComponents
 
       private
 
+      # Maps a render type (`as:` / `filter_as:`) to a filter value type. An
+      # unmapped value (a custom renderer) falls back to text.
+      RENDER_TO_FILTER_TYPE = {
+        number: :numeric, numeric: :numeric,
+        date: :date, datetime: :date,
+        boolean: :boolean,
+        enum: :select, select: :select,
+        string: :text, text: :text
+      }.freeze
+
+      def build_typed_filter
+        facet = facets[:filter]
+        return facet if facet.is_a?(CrudComponents::TypedFilter)   # already built (escape hatch)
+        return nil unless facet.is_a?(Proc) && keyword_filter_block?(facet)
+
+        CrudComponents::TypedFilter.new(filter_type, facet, choices: options[:filter_choices])
+      end
+
+      # A filter block opts into a typed control by declaring keyword params
+      # (eq:/geq:/leq:/contains:); a positional `->(scope, value)` stays plain text.
+      def keyword_filter_block?(block)
+        block.parameters.any? { |kind, _| %i[key keyreq keyrest].include?(kind) }
+      end
+
+      # The filter's value type: `filter_as:` if given, else inferred from the
+      # render type `as:`, else text.
+      def filter_type
+        RENDER_TO_FILTER_TYPE.fetch(options[:filter_as] || options[:as], :text)
+      end
+
       def arel_column
         model.arel_table[name]
       end

data/lib/crud_components/fields/belongs_to_field.rb

@@ -2,8 +2,9 @@ module CrudComponents
   module Fields
     # belongs_to / has_one: nil-safe link via the target's label. The filter
     # (belongs_to only) accepts both the target's identify_by value (what the
-    # select submits) and free text matched against the target's search_in —
-    # one param, two OR-combined parameterized subqueries.
+    # select submits) and free text matched against the target's label — the
+    # name shown in the cell — one param, two OR-combined parameterized
+    # subqueries.
     class BelongsToField < Base
       def default_renderer = :association
 
@@ -23,11 +24,26 @@ module CrudComponents
         Structure.for(target)
       end
 
+      # Default ?q= reaches the target's label (the name shown in the cell).
+      # Skipped for polymorphic (no single target) or a block/columnless label.
+      def search_spec_entry
+        name if !reflection.polymorphic? && target_structure.label_column_name
+      end
+
       def derived_filterable?
         reflection.belongs_to? && !reflection.polymorphic?
       end
 
-      def derived_sortable? = false
+      # Sortable by the column behind the target's label — the name shown in the
+      # cell — reached with a join. A block label, or a label that isn't a real
+      # column, has no SQL ordering, so the column isn't sortable then.
+      def derived_sortable? = sort_column.present?
+
+      def apply_sort(scope, dir)
+        return super if sort_facet
+
+        scope.left_joins(name).reorder(target.arel_table[sort_column].public_send(dir))
+      end
 
       # select (a dropdown of all targets) below `select_limit` rows, else free
       # text. Counted per render, not memoized: the field instance lives on the
@@ -44,17 +60,17 @@ module CrudComponents
               .sort_by(&:first)
       end
 
-      def apply_derived_filter(scope, exact: nil, **)
-        return scope unless exact
+      def apply_derived_filter(scope, value: nil, **)
+        return scope unless value
 
-        identified = scope.where(name => target.where(target_structure.identify_by => exact))
-        searched = like_subquery(scope, exact)
+        identified = scope.where(name => target.where(target_structure.identify_by => value))
+        searched = like_subquery(scope, value)
         searched ? identified.or(searched) : identified
       end
 
       # Load the association, nesting the target's identity_preloads (its label's
       # own association deps) plus any per-column `preload:` so the target's
-      # label never N+1s. e.g. { order: %i[customer training] }.
+      # label never N+1s. e.g. { book: %i[publisher authors] }.
       # A polymorphic belongs_to has no single target class, so we can't nest its
       # label's preloads — just preload the association itself (Rails groups it by
       # type); the cell still renders each record's label and links it at runtime.
@@ -80,11 +96,22 @@ module CrudComponents
 
       private
 
+      # The target column to ORDER BY: the field behind its label when that's a
+      # real column, else nil (a block label or computed attribute can't be sorted
+      # in SQL). Polymorphic belongs_to has no single target, so never sortable.
+      def sort_column
+        return nil if reflection.polymorphic?
+
+        target_structure.label_column_name
+      end
+
+      # Free text matches the target's label only — the name shown in the cell.
+      # A block/computed label has no column to match, so there's no text filter.
       def like_subquery(scope, value)
-        spec = target_structure.search_in_spec
-        return nil if spec.nil? || spec.empty?
+        label = target_structure.label_column_name
+        return nil unless label
 
-        scope.where(name => LikeSpec.apply(target.all, spec, value))
+        scope.where(name => LikeSpec.apply(target.all, [label], value))
       end
     end
   end

data/lib/crud_components/fields/boolean_field.rb

@@ -18,8 +18,8 @@ module CrudComponents
       # A nullable column offers a "not set" (IS NULL) choice in the filter.
       def filter_includes_null? = nullable?
 
-      def apply_derived_filter(scope, exact: nil, **)
-        case exact&.downcase
+      def apply_derived_filter(scope, value: nil, **)
+        case value&.downcase
         when *TRUE_VALUES then scope.where(name => true)
         when *FALSE_VALUES then scope.where(name => false)
         when CrudComponents::NULL_FILTER_VALUE then nullable? ? scope.where(name => nil) : scope

data/lib/crud_components/fields/date_field.rb

@@ -14,8 +14,8 @@ module CrudComponents
       def default_editable? = !NON_EDITABLE_COLUMNS.include?(name.to_s)
       def form_control = datetime? ? :datetime : :date
 
-      def apply_derived_filter(scope, exact: nil, geq: nil, leq: nil)
-        if (d = cast(exact)) then scope = apply_day(scope, d) end
+      def apply_derived_filter(scope, value: nil, geq: nil, leq: nil)
+        if (d = cast(value)) then scope = apply_day(scope, d) end
         if (d = cast(geq)) then scope = scope.where(arel_column.gteq(lower_bound(d))) end
         if (d = cast(leq)) then scope = scope.where(arel_column.lteq(upper_bound(d))) end
         scope

data/lib/crud_components/fields/enum_field.rb

@@ -29,11 +29,11 @@ module CrudComponents
       # A nullable column offers a "not set" (IS NULL) choice in the filter.
       def filter_includes_null? = nullable?
 
-      def apply_derived_filter(scope, exact: nil, **)
-        return scope.where(name => nil) if exact == CrudComponents::NULL_FILTER_VALUE && nullable?
-        return scope unless exact && enum_keys.include?(exact)
+      def apply_derived_filter(scope, value: nil, **)
+        return scope.where(name => nil) if value == CrudComponents::NULL_FILTER_VALUE && nullable?
+        return scope unless value && enum_keys.include?(value)
 
-        scope.where(name => exact)
+        scope.where(name => value)
       end
     end
   end

data/lib/crud_components/fields/has_many_field.rb

@@ -1,7 +1,7 @@
 module CrudComponents
   module Fields
-    # has_many / habtm: truncated list of links ("a, b +3 more"). No derived
-    # filter or sort; opt in with `filter like: :assoc` (delegation).
+    # has_many / habtm: truncated list of links ("a, b +3 more"). Filters by the
+    # children's label (the names shown in the list); no derived sort.
     class HasManyField < Base
       def default_renderer = :association_list
 
@@ -45,6 +45,26 @@ module CrudComponents
       end
 
       def target_structure = Structure.for(target)
+
+      # Default ?q= reaches the children's label (the names shown in the list).
+      # Skipped when the target's label is a block/columnless.
+      def search_spec_entry
+        name if target_structure.label_column_name
+      end
+
+      # ── filter ─────────────────────────────────────────────────────────────
+      # "Filter what you see": a free-text contains-match against the children's
+      # label — the names shown in the list — so an owner matches when at least
+      # one of its children does. Skipped when the target's label is a
+      # block/columnless (no single column to match). Mirrors belongs_to, which
+      # filters by its target's label the same way.
+      def derived_filterable? = target_structure.label_column_name.present?
+
+      def apply_derived_filter(scope, value: nil, **)
+        return scope unless value
+
+        LikeSpec.apply(scope, name, value)
+      end
     end
   end
 end

data/lib/crud_components/fields/numeric_field.rb

@@ -9,8 +9,8 @@ module CrudComponents
       def default_editable? = !NON_EDITABLE_COLUMNS.include?(name.to_s)
       def form_control = :number
 
-      def apply_derived_filter(scope, exact: nil, geq: nil, leq: nil)
-        if (v = cast(exact)) then scope = scope.where(name => v) end
+      def apply_derived_filter(scope, value: nil, geq: nil, leq: nil)
+        if (v = cast(value)) then scope = scope.where(name => v) end
         if (v = cast(geq)) then scope = scope.where(arel_column.gteq(v)) end
         if (v = cast(leq)) then scope = scope.where(arel_column.lteq(v)) end
         scope

data/lib/crud_components/fields/path_field.rb

@@ -159,12 +159,12 @@ module CrudComponents
         delegating? && target_field.respond_to?(:human_value) ? target_field.human_value(value) : value
       end
 
-      def apply_filter(scope, exact: nil, geq: nil, leq: nil)
+      def apply_filter(scope, value: nil, geq: nil, leq: nil)
         return super if filter_facet      # an author-supplied facet wins
-        return delegate_filter(scope, exact: exact, geq: geq, leq: leq) if delegating?
-        return scope unless exact
+        return delegate_filter(scope, value: value, geq: geq, leq: leq) if delegating?
+        return scope unless value
 
-        LikeSpec.apply(scope, filter_spec, exact)
+        LikeSpec.apply(scope, filter_spec, value)
       end
 
       # ── sorting: single-valued paths only ────────────────────────────────────
@@ -233,8 +233,8 @@ module CrudComponents
       # target model on its own table (so `where(col => …)` binds correctly), then
       # constrain the root through the association chain — an IN subquery, no JOIN,
       # so it can't multiply rows.
-      def delegate_filter(scope, exact:, geq:, leq:)
-        matched = target_field.apply_filter(target_model.all, exact: exact, geq: geq, leq: leq)
+      def delegate_filter(scope, value:, geq:, leq:)
+        matched = target_field.apply_filter(target_model.all, value: value, geq: geq, leq: leq)
         constrained = reflections.reverse.reduce(matched) do |sub, ref|
           ref.active_record.where(ref.name => sub)
         end

data/lib/crud_components/fields/string_field.rb

@@ -30,11 +30,11 @@ module CrudComponents
       def default_editable? = !NON_EDITABLE_COLUMNS.include?(name.to_s)
       def form_control = :string
 
-      def apply_derived_filter(scope, exact: nil, **)
-        return scope unless exact
+      def apply_derived_filter(scope, value: nil, **)
+        return scope unless value
 
         # explicit escape char: backslash is not SQLite's default
-        scope.where(arel_column.matches(like_pattern(exact), '\\'))
+        scope.where(arel_column.matches(like_pattern(value), '\\'))
       end
     end
   end

data/lib/crud_components/helpers.rb

@@ -20,6 +20,10 @@ module CrudComponents
     #   auto collections can share one page.
     # @param actions [Boolean] render the actions column + toolbar (false to place
     #   them yourself with {#crud_actions}).
+    # @param search_bar [Boolean] render the toolbar's `?q=` search box (default
+    #   true). Pass false to drop just this collection's box — e.g. when a
+    #   page-level search already covers it. The box only; the model stays
+    #   searchable elsewhere and an explicit `?q=` still applies in `:auto` mode.
     # @param group_by [Symbol, nil] a column, belongs_to or enum to group rows
     #   under collapsible headers.
     # @param extra_columns [Array<CrudComponents::DynamicColumn>, nil] user-defined
@@ -38,10 +42,12 @@ module CrudComponents
     #   reorder, never reveal a column the `if:` gate forbids.
     # @return [ActiveSupport::SafeBuffer] the rendered HTML.
     def crud_collection(records, fieldset: nil, layout: :table, query: :auto, param_prefix: nil,
-                        actions: true, group_by: nil, extra_columns: nil, picker: false, picked_columns: :auto)
+                        actions: true, search_bar: true, group_by: nil, extra_columns: nil,
+                        picker: false, picked_columns: :auto)
       presenter = Presenters::Collection.new(view: self, records: records, fieldset: fieldset,
                                              query: query, layout: layout, param_prefix: param_prefix,
-                                             actions: actions, group_by: group_by, extra_columns: extra_columns,
+                                             actions: actions, search_bar: search_bar, group_by: group_by,
+                                             extra_columns: extra_columns,
                                              picker: picker, picked_columns: picked_columns)
       render "crud_components/layouts/#{presenter.layout}", collection: presenter
     end
@@ -111,11 +117,19 @@ module CrudComponents
     # @param query [CrudComponents::Query, nil] reuse an existing query's values;
     #   nil reads the request params.
     # @param param_prefix [Symbol, nil] namespaces the form's params.
+    # @param extra_columns [Array<CrudComponents::DynamicColumn>, nil] dynamic columns
+    #   (the same you'd hand {#crud_collection}) whose filters should appear in the
+    #   form — so a card/list surface gets its user-defined-property filters without
+    #   hand-building a {Query}. Ignored when you pass a prebuilt `query:` (it already
+    #   carries its own `extra_fields:`).
+    # @param sort [Boolean] also render a sort field/direction picker (default false).
+    #   For a **headerless** surface (a card grid / list with no `<th>` sort links)
+    #   this is the way to choose `?sort=&dir=`; a table carries the links itself.
     # @param layout [Symbol] the partial under `crud_components/` (`:filter` ships).
     # @return [ActiveSupport::SafeBuffer] the rendered HTML.
-    def crud_filter(model, fieldset: nil, query: nil, param_prefix: nil, layout: :filter)
-      presenter = Presenters::Filter.new(view: self, model: model, fieldset: fieldset,
-                                         query: query, param_prefix: param_prefix)
+    def crud_filter(model, fieldset: nil, query: nil, param_prefix: nil, extra_columns: nil, sort: false, layout: :filter)
+      presenter = Presenters::Filter.new(view: self, model: model, fieldset: fieldset, query: query,
+                                         param_prefix: param_prefix, extra_columns: extra_columns, sort: sort)
       render "crud_components/#{layout}", filter: presenter
     end
 
@@ -172,7 +186,7 @@ module CrudComponents
     end
 
     # The label for an associated record in an association column: a per-column
-    # `label:` callable (`attribute :order, label: ->(o) { o.full_title(short: true) }`)
+    # `label:` callable (`attribute :publisher, label: ->(p) { p.display_title(short: true) }`)
     # when given, else the target's default {#crud_label}. Used by the
     # association / association_list renderers so a column can re-title the
     # associated record for its context while keeping the nil-safe link.