crud_components 0.1.0 → 0.2.0

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_field_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,11 +60,11 @@ 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
 
@@ -80,11 +96,23 @@ 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?
+
+        col = target_structure.label_field_name
+        col if col && target.column_names.include?(col.to_s)
+      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_field_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_field_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_field_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
 

data/lib/crud_components/like_spec.rb

@@ -5,17 +5,12 @@ module CrudComponents
   #   :title                       own column
   #   %i[title subtitle]           several own columns, OR-combined
   #   { authors: %i[name email] }  join, explicit columns
-  #   :publisher                   join, delegate to Publisher's search_in
-  #   { user: :address }           nested join, delegate to Address
+  #   :publisher                   join, search Publisher's label (what you see)
+  #   { user: :address }           nested join, search Address's label
   #
   # Specs never contain SQL strings; conditions are built through Arel with
   # LIKE wildcards escaped, so they are parameterized end to end.
   module LikeSpec
-    # Only *delegation* hops (an association name resolved through the target's
-    # search_in) can form a cycle; explicit nesting is bounded by the literal
-    # spec. So the guard counts delegations only.
-    MAX_DELEGATIONS = 5
-
     module_function
 
     def apply(scope, spec, value)
@@ -29,8 +24,14 @@ module CrudComponents
 
       return scope.where(condition) if joins.empty?
 
-      # distinct only matters once a join can multiply rows
-      scope.left_joins(joins).where(condition).distinct
+      # A join can multiply rows, so the match has to be de-duplicated. We do it
+      # with an id subquery rather than SELECT DISTINCT: DISTINCT compares every
+      # selected column, which Postgres can't do for a json (or other
+      # non-comparable) column the scope happens to select — it raises "could not
+      # identify an equality operator for type json". The subquery sidesteps that
+      # and keeps the join (and its rows) out of the outer query entirely.
+      key = model.arel_table[model.primary_key]
+      scope.where(key.in(model.left_joins(joins).where(condition).select(key).arel))
     end
 
     Entry = Struct.new(:path, :klass, :column) do
@@ -47,19 +48,16 @@ module CrudComponents
       end
     end
 
-    # Resolves a spec into flat [path, klass, column] entries, expanding
-    # association names without columns through the target's search_in spec.
-    # `delegations` counts only delegation hops (the cycle risk).
-    def expand(model, spec, path = [], delegations = 0)
-      if delegations > MAX_DELEGATIONS
-        raise DefinitionError, "search_in/like delegation more than #{MAX_DELEGATIONS} levels deep " \
-                               "starting at #{model} — most likely a delegation cycle"
-      end
-
+    # Resolves a spec into flat [path, klass, column] entries. A bare
+    # association name resolves to the target's label column — the text you
+    # actually see in that association's cell — so it can never reach a
+    # target's hidden columns (passwords, tokens, …) and there is no
+    # search_in chain to form a cycle.
+    def expand(model, spec, path = [])
       Array.wrap(spec).flat_map do |item|
         case item
-        when Symbol, String then expand_name(model, item.to_sym, path, delegations)
-        when Hash then item.flat_map { |assoc, sub| expand_assoc(model, assoc.to_sym, sub, path, delegations) }
+        when Symbol, String then expand_name(model, item.to_sym, path)
+        when Hash then item.flat_map { |assoc, sub| expand_assoc(model, assoc.to_sym, sub, path) }
         else
           raise DefinitionError, "invalid like-spec element #{item.inspect} for #{model} — " \
                                  'use column symbols, association symbols, or { assoc => columns } hashes'
@@ -67,38 +65,39 @@ module CrudComponents
       end
     end
 
-    def expand_name(model, name, path, delegations)
+    def expand_name(model, name, path)
       if model.columns_hash.key?(name.to_s)
         [Entry.new(path, model, name)]
       elsif (reflection = model.reflect_on_association(name))
-        delegate(model, reflection, path, delegations)
+        delegate(model, reflection, path)
       else
         raise DefinitionError, "like-spec references '#{name}', which is neither a column nor " \
                                "an association of #{model}"
       end
     end
 
-    # Explicit nesting ({ assoc => columns }) — bounded by the spec, not a
-    # cycle risk, so it does not count against the delegation limit.
-    def expand_assoc(model, assoc, sub, path, delegations)
+    # Explicit nesting ({ assoc => columns }) — spell the target's columns out.
+    def expand_assoc(model, assoc, sub, path)
       reflection = model.reflect_on_association(assoc)
       raise DefinitionError, "like-spec references association '#{assoc}', " \
                              "which #{model} does not have" unless reflection
 
-      expand(reflection.klass, sub, path + [assoc], delegations)
+      expand(reflection.klass, sub, path + [assoc])
     end
 
-    # Association name without columns: use the target model's search_in spec.
-    def delegate(model, reflection, path, delegations)
+    # Association name without columns: search the target's label column — the
+    # name shown in its cell ("search what you see"). A block/computed label has
+    # no single column to match, so ask for the columns explicitly.
+    def delegate(model, reflection, path)
       target = reflection.klass
-      target_spec = Structure.for(target).search_in_spec
-      if target_spec.nil?
-        raise DefinitionError, "cannot delegate like-spec to #{model}##{reflection.name}: " \
-                               "#{target}'s search_in is a custom block — spell the columns out, " \
+      label = Structure.for(target).label_field_name
+      if label.nil?
+        raise DefinitionError, "cannot search #{model}##{reflection.name} by label: " \
+                               "#{target}'s label is a custom block, not a column — spell the columns out, " \
                                "e.g. { #{reflection.name}: %i[...] }"
       end
 
-      expand(target, target_spec, path + [reflection.name], delegations + 1)
+      [Entry.new(path + [reflection.name], target, label)]
     end
 
     def deep_merge(left, right)