crud_components 0.1.0

data/lib/crud_components/fields/path_field.rb

@@ -0,0 +1,327 @@
+module CrudComponents
+  module Fields
+    # A column that reaches *through* associations: a dotted name like
+    # `publisher.name` or `authors.email`. The leading segments are associations
+    # on the model; the last is an attribute (or method) on the target.
+    #
+    # A single-valued path (belongs_to / has_one) **delegates to the target
+    # model's own field** for that attribute: `publisher.founded_on` renders,
+    # filters and sorts exactly like Publisher's `founded_on` column does — a date
+    # cell, a date-range filter, an ORDER BY the date — and `publisher.price` keeps
+    # the target's `unit:`/`digits:` formatting. The path column can still override
+    # any of it (`as:`, a `filter`/`sort`/`render` facet, or its own options) —
+    # **override > target field > default**. A collection path (has_many / habtm)
+    # renders the values as a list and filters by contains-match through the join.
+    # The association is eager-loaded automatically.
+    #
+    # When the leaf attribute *is* the target's label field (`publisher.name`),
+    # the cell renders a link to that record — its model icon then a link to its
+    # show page — so a path column doubles as a jump-to-the-object.
+    #
+    # Two limits (see #validate!): the chain may be at most `config.max_path_depth`
+    # associations deep, and it may cross **at most one to-many** association —
+    # belongs_to/has_one chain freely, but a second has_many/habtm would fan a
+    # list out into a meaningless list-of-lists. `habtm → one` (authors.publisher.name)
+    # is fine; `habtm → many` is not.
+    class PathField < ComputedField
+      # Target field flavors a single-valued path delegates render/filter/sort to.
+      # belongs_to/has_one/attachment/json/computed targets keep the path's own
+      # value-type rendering and contains-match filtering (no delegation).
+      SCALAR_TARGETS = [StringField, TextField, NumericField, DateField,
+                        BooleanField, EnumField].freeze
+
+      def initialize(name, model, options = {}, facets = {})
+        super
+        @segments = name.to_s.split('.').map(&:to_sym)
+        validate!
+      end
+
+      # The list of values reached by the path: an Array for a collection path,
+      # the single value (or nil) otherwise.
+      def value(record)
+        values = leaf_values(record)
+        collection? ? values : values.first
+      end
+
+      # Single value: the target field's renderer (date/number/email/…) when it's
+      # a scalar column — so the path renders like the target — unless overridden.
+      # Collection / non-scalar target: fall back to the inferred value-type
+      # renderer (ComputedField).
+      def renderer(record = nil)
+        return options[:as] if options[:as]
+        return nil if render_block
+
+        return target_field.renderer if delegating?
+
+        super
+      end
+
+      # Target-field options (unit/digits/…) as the base, overridden by any the
+      # path column declares itself — `override > target field`.
+      def renderer_options
+        own = super
+        delegating? ? target_field.renderer_options.merge(own) : own
+      end
+
+      # Single paths render through the renderer; collection paths render as a
+      # joined list, and a path to the target's label field renders a link.
+      def render_block
+        return facets[:render] if facets[:render]
+        return list_renderer if collection?
+        return label_link_renderer if link_to_target?
+
+        nil
+      end
+
+      # @api private — runs in the view context (`view`), via the render block.
+      def render_list(view, record)
+        items = Array(value(record)).map { |v| v.to_s.strip }.reject(&:blank?)
+        return view.tag.span('—', class: CrudComponents.config.css.muted) if items.empty?
+
+        # ask the target's field how it renders (email → mailto, url → link)
+        semantic = target_field&.renderer
+        view.safe_join(items.map { |item| link_value(view, semantic, item) }, ', ')
+      end
+
+      # @api private — the label-field link (model icon + link to the record's
+      # show page), runs in the view context via the render block.
+      def render_list_label(view, record)
+        target = target_record(record)
+        muted = CrudComponents.config.css.muted
+        return view.tag.span('—', class: muted) if target.nil?
+
+        label = value(record).to_s
+        icon = view.crud_model_icon(target_model)
+        inner = view.safe_join([icon, view.tag.span(label)].compact, icon ? ' ' : '')
+        path = view.crud_record_path(target)
+        path ? view.link_to(inner, path, data: { turbo_action: 'advance' }) : inner
+      end
+
+      # Header: a breadcrumb "Parent › Attribute" (Pipedrive-style). The picker
+      # groups by `group_label` and shows the short `picker_label`, so it isn't
+      # repeated there.
+      def human_name
+        return options[:label] if options[:label].is_a?(String)
+
+        "#{group_label} › #{picker_label}"
+      end
+
+      def group_label
+        reflections.map { |ref| ref.active_record.human_attribute_name(ref.name) }.join(' › ')
+      end
+
+      def picker_label = target_model.human_attribute_name(attribute_name)
+
+      # Picker grouping: a path column sits under its target model's group, next
+      # to the association column that anchors it.
+      def group_model = target_model
+
+      # Eager-load the association chain so a whole page costs one query, not one
+      # per row (e.g. `publisher.founded_on` → includes(:publisher)).
+      def eager_load
+        spec = assoc_segments.reverse.reduce(nil) { |inner, seg| inner ? { seg => inner } : seg }
+        spec ? [spec] : []
+      end
+
+      # ── filtering ─────────────────────────────────────────────────────────────
+      # Single-valued scalar paths offer the target field's own control (a date
+      # range, an enum select, …) and apply it through the association; collection
+      # / non-scalar paths keep the safe contains-match.
+      def filterable?
+        return false if facets[:filter] == false
+        return false if CrudComponents::RESERVED_PARAMS.include?(name.to_s)
+
+        true
+      end
+
+      def filter_control
+        return :text if filter_facet
+        delegating? ? target_field.filter_control : :text
+      end
+
+      def filter_choices(query = nil)
+        return nil unless delegating? && !filter_facet
+
+        target_field.filter_choices(query)
+      end
+
+      def filter_includes_null?
+        delegating? && !filter_facet ? target_field.filter_includes_null? : false
+      end
+
+      def nullable?
+        delegating? ? target_field.nullable? : super
+      end
+
+      # The target field humanizes its own values (enum labels); a path delegates
+      # so a `publisher.status` cell badges the same text the Publisher table does.
+      def human_value(value)
+        delegating? && target_field.respond_to?(:human_value) ? target_field.human_value(value) : value
+      end
+
+      def apply_filter(scope, exact: 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
+
+        LikeSpec.apply(scope, filter_spec, exact)
+      end
+
+      # ── sorting: single-valued paths only ────────────────────────────────────
+      def sortable?
+        return false if collection? || facets[:sort] == false
+        return false if CrudComponents::RESERVED_PARAMS.include?(name.to_s)
+
+        true
+      end
+
+      def apply_sort(scope, dir)
+        return super if sort_facet
+
+        joins = eager_load.first
+        scope = scope.left_joins(joins) if joins
+        scope.reorder(target_model.arel_table[attribute_name].public_send(dir))
+      end
+
+      def collection? = reflections.any?(&:collection?)
+      def single? = !collection?
+
+      private
+
+      def assoc_segments = @segments[0..-2]
+      def attribute_name = @segments.last
+
+      def reflections
+        @reflections ||= begin
+          klass = model
+          assoc_segments.map do |seg|
+            ref = klass.reflect_on_association(seg)
+            klass = ref.klass
+            ref
+          end
+        end
+      end
+
+      def target_model = reflections.last.klass
+
+      # The target model's own field for the leaf attribute — what a single-valued
+      # path delegates to. nil when the attribute isn't a real field (a bare
+      # method): then the path keeps its value-type rendering / contains filter.
+      def target_field
+        return @target_field if defined?(@target_field)
+
+        @target_field = Structure.for(target_model).field(attribute_name)
+      rescue DefinitionError
+        @target_field = nil
+      end
+
+      # Delegate render/filter/sort to the target field when the path is
+      # single-valued and the target is a scalar column field (not an association,
+      # attachment, json or computed method).
+      def delegating?
+        single? && (tf = target_field) && SCALAR_TARGETS.any? { |k| tf.is_a?(k) }
+      end
+
+      # A single-valued path whose leaf attribute *is* the target's label field —
+      # rendered as a link to that record.
+      def link_to_target?
+        single? && !options[:as] && !facets[:render] &&
+          Structure.for(target_model).label_field_name == attribute_name
+      end
+
+      # Apply the target field's own filter through the association: filter the
+      # 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)
+        constrained = reflections.reverse.reduce(matched) do |sub, ref|
+          ref.active_record.where(ref.name => sub)
+        end
+        scope.where(model.primary_key => constrained)
+      end
+
+      # Walk the path, following each segment over every object reached so far;
+      # association collections fan out and flatten. Nils drop.
+      def leaf_values(record)
+        @segments.reduce([record]) do |objects, seg|
+          objects.flat_map do |object|
+            next [] if object.nil?
+
+            value = object.public_send(seg)
+            value.is_a?(Enumerable) ? value.to_a : [value]
+          end
+        end.compact
+      end
+
+      # The associated record a single-valued path reaches (book → book.publisher),
+      # or nil when any hop is nil. Used by the label-field link.
+      def target_record(record)
+        assoc_segments.reduce(record) do |object, seg|
+          break nil if object.nil?
+
+          object.public_send(seg)
+        end
+      end
+
+      # The like-spec the path describes, e.g. [:authors, :email] → { authors: :email }.
+      def filter_spec
+        assoc_segments.reverse.reduce(attribute_name) { |inner, seg| { seg => inner } }
+      end
+
+      def list_renderer
+        field = self
+        # `self` inside the block is the view (instance_exec'd by render_cell).
+        proc { |record| field.render_list(self, record) }
+      end
+
+      def label_link_renderer
+        field = self
+        proc { |record| field.render_list_label(self, record) }
+      end
+
+      # One list item as a link (mailto / http) when the target name calls for
+      # it, else a plain (escaped-on-join) value.
+      def link_value(view, semantic, value)
+        case semantic
+        when :email then view.mail_to(value)
+        when :url   then value.match?(%r{\Ahttps?://}i) ? view.link_to(value, value, rel: 'noopener', target: '_blank') : value
+        else value
+        end
+      end
+
+      def validate!
+        klass = model
+        to_many = 0
+        assoc_segments.each do |seg|
+          ref = klass.reflect_on_association(seg)
+          unless ref
+            raise DefinitionError,
+                  "#{model}: '#{name}' is not a valid column path — '#{seg}' is not an " \
+                  "association on #{klass}. A path column is association(s) then an attribute, " \
+                  'e.g. publisher.name or authors.email.'
+          end
+          to_many += 1 if ref.collection?
+          klass = ref.klass
+        end
+
+        max = CrudComponents.config.max_path_depth
+        if assoc_segments.size > max
+          raise DefinitionError,
+                "#{model}: column path '#{name}' chains #{assoc_segments.size} associations; the " \
+                "limit is #{max} (config.max_path_depth — raise it if you need deeper paths)."
+        end
+
+        # Chaining belongs_to/has_one is cheap and single-valued; a second
+        # to-many hop would fan a list out into a list-of-lists with no sensible
+        # flat rendering, sort or filter. One to-many (incl. habtm→one) is fine.
+        return unless to_many > 1
+
+        raise DefinitionError,
+              "#{model}: column path '#{name}' crosses #{to_many} to-many associations. At most one " \
+              'has_many/habtm hop is allowed — chain belongs_to/has_one freely, but a to-many may ' \
+              'appear only once (e.g. authors.email, or authors.publisher.name).'
+      end
+    end
+  end
+end

data/lib/crud_components/fields/string_field.rb

@@ -0,0 +1,41 @@
+module CrudComponents
+  module Fields
+    # string column: text cell, text input, escaped case-insensitive contains.
+    class StringField < Base
+      # Name-gated smart renderers: a column literally named `email` (or `*_email`)
+      # renders as a `mailto:` link; one named `url`, `website`, `link` or
+      # `homepage` renders an http(s) value as a link. Gated on the column *name*,
+      # never the value — a column that merely happens to hold a URL or an "@" is
+      # left alone, so the behaviour is predictable and you can't accidentally turn
+      # arbitrary text into links. `as:` overrides (opt out, or force a renderer).
+      URL_NAMES = %w[url website link homepage].freeze
+
+      # A column named email / url / website / link gets the matching smart
+      # renderer by default (a mailto: / http link). `as:` still overrides.
+      def default_renderer = smart_renderer || :string
+
+      # The renderer the column *name* implies (:email / :url), or nil for none.
+      # Public so a path column (publisher.email, authors.email) can reuse the same
+      # name rules by delegating to this field rather than duplicating them.
+      def smart_renderer
+        n = name.to_s
+        return :email if n == 'email' || n.end_with?('_email')
+        return :url if URL_NAMES.include?(n)
+
+        nil
+      end
+
+      def derived_filterable? = true
+      def derived_sortable? = true
+      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
+
+        # explicit escape char: backslash is not SQLite's default
+        scope.where(arel_column.matches(like_pattern(exact), '\\'))
+      end
+    end
+  end
+end

data/lib/crud_components/fields/text_field.rb

@@ -0,0 +1,9 @@
+module CrudComponents
+  module Fields
+    # text column: truncated in collections, line breaks preserved on records.
+    class TextField < StringField
+      def default_renderer = :text
+      def form_control = :text
+    end
+  end
+end

data/lib/crud_components/fieldset.rb

@@ -0,0 +1,38 @@
+module CrudComponents
+  # A named selection of fields and actions. `filters:`
+  # extends the filterable set beyond the visible fields ("filter only what
+  # you can see" is the default rule).
+  class Fieldset
+    attr_reader :name, :field_names, :action_spec, :filter_names
+
+    # @param name [Symbol] the fieldset name.
+    # @param fields [Array<Symbol>, :all] the fields, in order (`:all` = every
+    #   declared/derived field).
+    # @param actions [Array<Symbol>, String, nil] a curated list of action names,
+    #   or a custom partial path; nil keeps the derived actions.
+    # @param filters [Array<Symbol>, nil] filterable fields beyond the visible ones.
+    def initialize(name, fields = :all, actions: nil, filters: nil)
+      @name = name.to_sym
+      @field_names = fields == :all ? :all : Array(fields).map(&:to_sym)
+      @action_spec = actions
+      @filter_names = Array(filters || []).map(&:to_sym)
+    end
+
+    # @return [Boolean] whether this fieldset shows every field.
+    def all_fields? = @field_names == :all
+
+    # The curated action names (`actions: %i[edit destroy]`), or nil when the
+    # derived defaults apply.
+    # @return [Array<Symbol>, nil]
+    def action_names
+      @action_spec.is_a?(Array) ? @action_spec.map(&:to_sym) : nil
+    end
+
+    # A custom actions partial (`actions: 'books/actions'`, receiving `record`),
+    # or nil.
+    # @return [String, nil]
+    def custom_actions_partial
+      @action_spec.is_a?(String) ? @action_spec : nil
+    end
+  end
+end

data/lib/crud_components/helpers.rb

@@ -0,0 +1,259 @@
+module CrudComponents
+  # The everyday view API, included into ActionView by the engine. Every helper
+  # builds a presenter and renders a partial you can override via the host app's
+  # view path (`app/views/crud_components/…`).
+  module Helpers
+    # A set of records as a table (or any layout partial you point `layout:` at).
+    #
+    # @param records [ActiveRecord::Relation] the rows to render. Pass a scope,
+    #   not a model class, so your authorization and any pre-scoping apply before
+    #   the gem renders (e.g. `Book.accessible_by(current_ability)`).
+    # @param fieldset [Symbol, nil] which declared fieldset to use; defaults to
+    #   `:index` (or every column when the model declares nothing).
+    # @param layout [Symbol] the layout partial under `crud_components/layouts/`
+    #   — `:table` ships; add your own (e.g. `:cards`) and pass its name.
+    # @param query [Symbol, CrudComponents::Query] query mode: `:auto` (default)
+    #   reads the request params and filters/sorts; `:static` renders no filter row
+    #   or sort links (params ignored); a {Query} is manual mode (records already
+    #   filtered). See {Presenters::Collection}.
+    # @param param_prefix [Symbol, nil] namespaces this collection's params so two
+    #   auto collections can share one page.
+    # @param actions [Boolean] render the actions column + toolbar (false to place
+    #   them yourself with {#crud_actions}).
+    # @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
+    #   columns whose data lives outside the model's table (custom properties from
+    #   a separate store, JSONB, an API). Appended after the declared columns and
+    #   subject to the same `if:` permission gate; filter/sort only when the column
+    #   supplies those facets.
+    # @param picker [Boolean] render the column-picker gear in the header row
+    #   (default false). The gear stays put regardless of `picked_columns:`, so it
+    #   survives across ephemeral and persisted selections alike.
+    # @param picked_columns [Symbol, Array<Symbol>] which columns to show when the
+    #   picker is on: `:auto` (default) reads the `?cols=` submit; an `Array` shows
+    #   exactly those columns and **never reads the param** — the backend resolved
+    #   it (from a persisted preference, or from the param via
+    #   {CrudComponents.selected_columns}). A forged/stale name can only hide or
+    #   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)
+      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,
+                                             picker: picker, picked_columns: picked_columns)
+      render "crud_components/layouts/#{presenter.layout}", collection: presenter
+    end
+
+    # One record as a definition list (or any layout partial you point `layout:`
+    # at). Extend by creating your own partial — e.g. `crud_components/_card`
+    # — and passing `layout: :card`.
+    #
+    # @param record [ActiveRecord::Base] the record to show.
+    # @param fieldset [Symbol, nil] which fieldset to use; defaults to `:show`.
+    # @param actions [Boolean] render the row actions (false to place them with
+    #   {#crud_actions}).
+    # @param layout [Symbol] the partial under `crud_components/` (`:record` ships).
+    # @param picked_columns [Symbol, Array<Symbol>] narrow/order the fields shown. A
+    #   detail view has no inline gear of its own, so pass an `Array` you resolved
+    #   (e.g. from a standalone {#crud_column_picker} on the page, via
+    #   {CrudComponents.selected_columns}). `:auto` (default) means "don't narrow" —
+    #   with no gear here a stray `?cols=` is ignored.
+    # @param param_prefix [Symbol, nil] namespaces the `?cols=` param this view reads
+    #   (match it to the picker's `param_prefix:`).
+    # @param extra_columns [Array<CrudComponents::DynamicColumn>, nil] user-defined
+    #   columns whose data lives outside the model's table, shown as extra rows
+    #   (same as {#crud_collection}'s `extra_columns:`, for a detail view).
+    # @return [ActiveSupport::SafeBuffer] the rendered HTML.
+    def crud_record(record, fieldset: nil, actions: true, layout: :record, picked_columns: :auto,
+                    param_prefix: nil, extra_columns: nil)
+      presenter = Presenters::Record.new(view: self, record: record, fieldset: fieldset, actions: actions,
+                                         picked_columns: picked_columns, param_prefix: param_prefix,
+                                         extra_columns: extra_columns)
+      render "crud_components/#{layout}", record_presenter: presenter
+    end
+
+    # A standalone column picker — the same gear-and-checklist the table renders in
+    # its header, but placed wherever you like (e.g. above a `crud_record` detail
+    # view). It submits `?cols[]=` to `url` (the current page by default), so a
+    # `crud_collection`/`crud_record` on the target page picks it up via
+    # `picked_columns:` or the param directly. Persist the choice with
+    # {CrudComponents.selected_columns}.
+    #
+    # @param subject [ActiveRecord::Relation, Class, ActiveRecord::Base] anything the
+    #   columns belong to — a scope, the model class, or a record.
+    # @param fieldset [Symbol, nil] which fieldset's fields to offer (e.g. `:show`).
+    # @param extra_columns [Array<CrudComponents::DynamicColumn>, nil] dynamic columns
+    #   to include in the choices.
+    # @param picked_columns [Symbol, Array<Symbol>] which boxes are pre-ticked:
+    #   `:auto` (default) reflects the current `?cols=`; an `Array` pre-ticks that
+    #   exact selection (no param read).
+    # @param url [String, nil] where the picker form submits; defaults to the current path.
+    # @param param_prefix [Symbol, nil] namespaces the `?cols=` param.
+    # @return [ActiveSupport::SafeBuffer] the rendered HTML.
+    def crud_column_picker(subject, fieldset: nil, extra_columns: nil, picked_columns: :auto, url: nil, param_prefix: nil)
+      relation = if subject.respond_to?(:klass) then subject
+                 elsif subject.is_a?(Class) then subject.all
+                 else subject.class.all
+                 end
+      presenter = Presenters::Collection.new(view: self, records: relation, fieldset: fieldset, query: :static,
+                                             extra_columns: extra_columns, picker: true, picked_columns: picked_columns,
+                                             param_prefix: param_prefix, actions: false)
+      render 'crud_components/column_picker', collection: presenter, url: (url || request.path)
+    end
+
+    # A standalone labelled filter form (modal / sidebar) — separate from the
+    # inline filter row a table renders.
+    #
+    # @param model [Class] the ActiveRecord model whose fields drive the form.
+    # @param fieldset [Symbol, nil] which fieldset's filterable fields to offer.
+    # @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 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)
+      render "crud_components/#{layout}", filter: presenter
+    end
+
+    # A derived create/edit form. The gem renders; your controller saves using
+    # the matching permit list ({CrudComponents.permitted_attributes}), so the
+    # form and strong-params can't drift.
+    #
+    # @param record [ActiveRecord::Base] a new or persisted instance.
+    # @param fieldset [Symbol, nil] which fieldset's fields to render; defaults to
+    #   the form fieldset for the action.
+    # @param action [Symbol, nil] `:new`/`:edit`; inferred from the record when nil.
+    # @param url [String, nil] the form action URL; inferred from the record when nil.
+    # @param method [Symbol, nil] the HTTP verb; inferred when nil.
+    # @param layout [Symbol] the partial under `crud_components/` (`:form` ships).
+    # @return [ActiveSupport::SafeBuffer] the rendered HTML.
+    def crud_form(record, fieldset: nil, action: nil, url: nil, method: nil, layout: :form)
+      presenter = Presenters::Form.new(view: self, record: record, fieldset: fieldset,
+                                       action: action, url: url, method: method)
+      render "crud_components/#{layout}", form: presenter
+    end
+
+    # The action buttons for a record (row actions) or a model class (collection
+    # actions) — for manual placement when you render with `actions: false`.
+    #
+    # @param subject [ActiveRecord::Base, Class] a record (row actions) or the
+    #   model class (collection actions). A relation is rejected — collection
+    #   actions are model-level (`can?(:new, Book)`), so pass the class.
+    # @param fieldset [Symbol, nil] which fieldset's actions to use; defaults to
+    #   `:index` (collection) or `:show` (row).
+    # @return [ActiveSupport::SafeBuffer] the rendered HTML.
+    # @raise [ArgumentError] if given a relation.
+    def crud_actions(subject, fieldset: nil)
+      if subject.is_a?(ActiveRecord::Relation)
+        raise ArgumentError,
+              'crud_actions takes a record (row actions) or a model class (collection ' \
+              "actions), not a relation — pass `#{subject.klass}`, not a scope."
+      end
+      model = subject.is_a?(Class) ? subject : subject.class
+      structure = Structure.for(model)
+      kind = subject.is_a?(Class) ? :collection : :row
+      resolved_fieldset = structure.fieldset(fieldset || (kind == :collection ? :index : :show))
+      presenter = Presenters::Actions.new(view: self, subject: subject, structure: structure,
+                                          actions: structure.fieldset_actions(resolved_fieldset, on: kind))
+      render 'crud_components/actions', actions: presenter
+    end
+
+    # ── utilities (used by the gem's partials; useful in apps too) ─────────
+
+    # The display label for a record — its declared `label`, else a humanized guess.
+    # @param record [ActiveRecord::Base]
+    # @return [String]
+    def crud_label(record)
+      Structure.for(record.class).label_for(record, self)
+    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) }`)
+    # 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.
+    # @param field [CrudComponents::Fields::Base] the association field.
+    # @param record [ActiveRecord::Base] the associated record.
+    # @return [String]
+    def crud_association_label(field, record)
+      callable = field.options[:label]
+      callable.respond_to?(:call) ? callable.call(record) : crud_label(record)
+    end
+
+    # The icon markup badging a model — an `<i>` tag (paired with
+    # `css.icon_prefix`) for the model's {Structure#icon}, or nil when the model
+    # has no icon (undeclared and unmapped, with no `model_fallback_icon`). Pass a
+    # record, a model class or a relation. Extra html options merge onto the tag;
+    # `class:` adds to the icon classes.
+    #
+    #   <%= crud_model_icon(@book) %>                  # <i class="bi bi-book" aria-hidden="true">
+    #   <%= crud_model_icon(Publisher, class: 'me-1') %>
+    #
+    # @param subject [ActiveRecord::Base, Class, ActiveRecord::Relation]
+    # @return [ActiveSupport::SafeBuffer, nil]
+    def crud_model_icon(subject, **html_options)
+      name = crud_model_icon_name(subject)
+      return nil unless name
+
+      extra = Array(html_options.delete(:class))
+      classes = ["#{CrudComponents.config.css.icon_prefix}#{name}", *extra].join(' ')
+      tag.i('', class: classes, aria: { hidden: true }, **html_options)
+    end
+
+    # The bare icon name (no library prefix) for a model — {Structure#icon} for
+    # the model behind a record / class / relation, or nil. Use when you need the
+    # name rather than the `<i>` tag {#crud_model_icon} builds.
+    # @param subject [ActiveRecord::Base, Class, ActiveRecord::Relation]
+    # @return [String, nil]
+    def crud_model_icon_name(subject)
+      model = subject.respond_to?(:klass) ? subject.klass : subject.is_a?(Class) ? subject : subject.class
+      Structure.for(model).icon
+    end
+
+    # A Bootstrap-icon name (no library prefix — pair with css.icon_prefix) for a
+    # filename, by extension: config.file_icons[ext], else config.file_fallback_icon.
+    # Used by the attachment renderer's icon fallback; override that partial to
+    # customize.
+    #
+    # @param filename [String, #to_s] the file name (or path) to derive from.
+    # @return [String] the icon name.
+    def crud_file_icon(filename)
+      config = CrudComponents.config
+      ext = File.extname(filename.to_s).delete('.').downcase
+      config.file_icons.fetch(ext, config.file_fallback_icon)
+    end
+
+    # The canonical path to a record (its `show`, resolved by {RouteResolver}).
+    # @param record [ActiveRecord::Base]
+    # @param owner [ActiveRecord::Base, nil] the owner, for a nested route.
+    # @return [String, nil] the path, or nil when none resolves.
+    def crud_record_path(record, owner: nil)
+      found = RouteResolver.record_path(self, record, owner: owner)
+      found&.first
+    end
+
+    # The index a has_many cell links to: nested under the owner, else the
+    # target's filtered index, else nil.
+    # @param owner [ActiveRecord::Base] the record that owns the association.
+    # @param field [CrudComponents::Fields::HasManyField] the association field.
+    # @return [String, nil] the path, or nil when none resolves.
+    def crud_association_index_path(owner, field)
+      RouteResolver.collection_index_path(self, field.target, owner, field.name)
+    end
+
+    # Inline the gem's stylesheet (the column-picker float styles) as a <style>
+    # tag — drop `<%= crud_components_styles %>` once in your layout <head>. This
+    # is the pipeline-agnostic way to load it: it needs no asset compilation, so
+    # it works the same under cssbundling/sass, importmap, sprockets or propshaft.
+    # Hosts whose pipeline serves engine assets can instead link the same file
+    # with `stylesheet_link_tag "crud_components"`.
+    def crud_components_styles
+      nonce = content_security_policy_nonce if respond_to?(:content_security_policy_nonce)
+      tag.style(CrudComponents.bundled_css.html_safe, type: 'text/css', nonce: nonce)
+    end
+  end
+end