crud_components 0.1.0

data/lib/crud_components/presenters/collection.rb

@@ -0,0 +1,498 @@
+module CrudComponents
+  module Presenters
+    # The single `collection` local every layout partial receives.
+    #
+    # query: :auto (default) → build a Query from the request params and apply it
+    # query: :static         → no filter row, no sort links, params ignored
+    # query: <Query>         → manual mode (records arrive already filtered)
+    #
+    # picker:         false (default) → no column picker; true → render the gear
+    # picked_columns: :auto (default) → read ?cols=; an Array → that exact
+    #                 selection (no param read — the backend resolved it)
+    class Collection < Base
+      include ColumnSelection
+
+      attr_reader :model, :structure, :fieldset, :query, :layout, :param_prefix, :owner
+
+      def initialize(view:, records:, fieldset: nil, query: :auto, layout: :table,
+                     param_prefix: nil, actions: true, group_by: nil,
+                     extra_columns: nil, picker: false, picked_columns: :auto)
+        super(view: view)
+        unless records.respond_to?(:klass)
+          raise ArgumentError,
+                "crud_collection expects an ActiveRecord relation (e.g. Book.all, @books, or an " \
+                "authorized scope like Book.accessible_by(current_ability)), got #{records.class}. " \
+                'Pass a scope so your authorization and filtering apply before the gem renders.'
+        end
+        relation = records
+        @model = relation.klass
+        @structure = Structure.for(@model)
+        @owner = relation.respond_to?(:proxy_association) ? relation.proxy_association.owner : nil
+        @layout = layout
+        @param_prefix = param_prefix
+        @actions_enabled = actions
+        # Two orthogonal column-picker knobs (see ColumnSelection): the gear is on
+        # iff `picker`; the selection comes from the param (`:auto`) or verbatim
+        # from the resolved Array — they never both read the param.
+        @picker = picker
+        @picked_columns = normalize_picked_columns(picked_columns)
+        # User-defined columns whose data lives outside the model's table. Built
+        # fresh per request (never on the immutable Structure), so they may carry
+        # the per-page value cache.
+        @dynamic_fields = Array(extra_columns).map { |c| c.to_field(@model) }
+
+        case query
+        when :static
+          @static = true
+          @fieldset = @structure.fieldset(fieldset || :index)
+        when :auto, nil
+          @fieldset = @structure.fieldset(fieldset || :index)
+          @query = Query.new(@model, view.request.query_parameters, fieldset: @fieldset,
+                             ability: ability, param_prefix: param_prefix, extra_fields: @dynamic_fields)
+          relation = @query.apply(relation)
+        when Query
+          @query = query
+          @fieldset = fieldset ? @structure.fieldset(fieldset) : query.fieldset
+          @param_prefix = query.param_prefix
+        else
+          raise ArgumentError,
+                "crud_collection query: expects :auto, :static or a CrudComponents::Query, got #{query.inspect}"
+        end
+
+        @relation = eager_load(relation)
+        setup_grouping(group_by) if group_by
+      end
+
+      def static? = !!@static
+      def surface = :collection
+
+      def records
+        @records ||= begin
+          rows = @relation.to_a
+          # Prime each visible dynamic column's per-page cache once (no N+1); the
+          # cell resolver then reads per row from what `preload:` returned.
+          fields.each { |f| f.preload!(rows) if f.is_a?(Fields::DynamicField) }
+          rows
+        end
+      end
+
+      # Every column this user is allowed to see — declared fieldset fields plus
+      # the dynamic columns — regardless of the current visibility selection.
+      # This is what a column picker offers as the universe to choose from.
+      # (`fields`, `column_visible?` and the picker knobs come from ColumnSelection.)
+      def available_fields
+        @available_fields ||=
+          (structure.fieldset_fields(fieldset) + @dynamic_fields).select { |f| f.permitted?(permission_context) }
+      end
+
+      # Whether to offer the column picker UI for this collection.
+      def column_picker? = @picker && available_fields.any?
+
+      # The checkbox param name the picker submits (respects param_prefix).
+      def column_param_name = "#{pn('cols')}[]"
+
+      # Hidden inputs for the picker's GET form: keep every other param (filters,
+      # search, sort, other collections) but drop our own cols (the checkboxes
+      # resubmit it) and page (a column change resets paging).
+      def picker_preserved_params
+        drop = [pn('cols'), pn('page')]
+        view.request.query_parameters.reject { |key, _| drop.include?(key) }
+      end
+
+      # ── cells ────────────────────────────────────────────────────────────
+      def cell(field, record)
+        html = render_cell(field, record, surface: :collection, cell_context: cell_context)
+        if label_link_field?(field) && (path = record_link(record))
+          view.link_to(html, path, class: css.record_link, data: { turbo_action: 'advance' })
+        else
+          html
+        end
+      end
+
+      # Click-to-filter context for value renderers — only when this
+      # collection actually has a live query.
+      def cell_context
+        return nil if static? || query.nil?
+
+        @cell_context ||= CellContext.new(view: view, query: query)
+      end
+
+      def label_link_field?(field)
+        field.name == structure.label_field_name
+      end
+
+      # ── column headers ─────────────────────────────────────────────────────
+      # A column may carry custom `<th>` content: a header (String or a
+      # view-context block) and/or its own actions — declared on a DynamicColumn
+      # or on a plain `attribute`. The layout renders these *instead of* the plain
+      # human_name + sort link; for every other field these return nil/[] and the
+      # layout keeps its default behavior.
+
+      # Whether `field` brings its own header markup or header actions.
+      def custom_header?(field)
+        field.custom_header?
+      end
+
+      # The `<th>` title for `field`: a custom `header:` (a String — html_safe to
+      # carry markup — or a view-context block, e.g. a link) replaces the plain
+      # `human_name`; otherwise the `human_name` itself. `header:` substitutes only
+      # the name — the layout still wraps this in a sort link when the column is
+      # sortable, and appends any header actions.
+      def column_header(field)
+        header = field.header
+        case header
+        when nil then field.human_name
+        when Proc then view.instance_exec(&header)
+        else header
+        end
+      end
+
+      # The header actions for `field` as an Actions presenter (collection-kind:
+      # they act on the column's object × — for a :selection action — the ticked
+      # rows, not a single row), or nil. Each action's path block closes over that
+      # object; the layout renders a :selection action as a select-form submitter
+      # and any other as a link/button.
+      def column_header_actions(field)
+        return nil unless field.header_actions.any?
+
+        (@column_header_actions ||= {})[field] ||=
+          Actions.new(view: view, subject: model, structure: structure,
+                      actions: field.header_actions, owner: owner)
+      end
+
+      def record_link(record)
+        @record_links ||= {}
+        return @record_links[record.id] if @record_links.key?(record.id)
+
+        found = RouteResolver.record_path(view, record, owner: owner)
+        @record_links[record.id] = found&.first
+      end
+
+      def label_link_present?(record)
+        fields.any? { |f| label_link_field?(f) } && record_link(record).present?
+      end
+
+      # ── filtering ────────────────────────────────────────────────────────
+      def filterable?
+        !static? && query && filter_fields.any?
+      end
+
+      def filter_fields
+        @filter_fields ||= static? ? [] : query.filter_fields
+      end
+
+      def filterable_field?(field)
+        filter_fields.include?(field)
+      end
+
+      def filter_form_id
+        suffix = param_prefix ? "_#{param_prefix}" : ''
+        "crud_filter_#{model.model_name.plural}#{suffix}"
+      end
+
+      # ── header search (?q=) and reset ──────────────────────────────────────
+      def searchable?
+        !static? && query && query.searchable?
+      end
+
+      def search_param_name
+        query.param_name('q')
+      end
+
+      def search_value
+        query&.value('q')
+      end
+
+      def filtered?
+        !static? && query&.active?
+      end
+
+      # Whether the toolbar (search + collection actions) has anything to show —
+      # lets a layout skip an empty header row.
+      def show_toolbar?
+        searchable? || collection_actions&.any? || selection_actions&.any?
+      end
+
+      # Reset clears *this* collection's filter/search/sort/page params and
+      # keeps everyone else's (other prefixes, the page's own params).
+      def reset_url
+        kept = view.request.query_parameters.reject { |key, _| own_param_keys.include?(key) }
+        kept.any? ? "#{view.request.path}?#{kept.to_query}" : view.request.path
+      end
+
+      # Hidden inputs for the filter form: keep this collection's sort and
+      # every param that belongs to someone else (other prefixes, the page's
+      # own params). Drop our own filter/search params — the controls
+      # themselves resubmit those.
+      def preserved_params
+        own = filter_fields.flat_map { |f| [pn(f.name.to_s), pn("#{f.name}_geq"), pn("#{f.name}_leq")] }
+        own += [pn('q'), pn('page'), pn('per')]
+        view.request.query_parameters.reject { |key, _| own.include?(key) }
+      end
+
+      # Every param key this collection owns (for reset).
+      def own_param_keys
+        keys = filter_fields.flat_map { |f| [pn(f.name.to_s), pn("#{f.name}_geq"), pn("#{f.name}_leq")] }
+        keys + %w[q sort dir page per].map { |k| pn(k) }
+      end
+
+      # ── sorting ──────────────────────────────────────────────────────────
+      def sortable_field?(field)
+        !static? && query && query.sortable_fields.include?(field)
+      end
+
+      def sort_url(field)
+        current, dir = query.sort_state
+        next_dir = current == field.name.to_s && dir == 'asc' ? 'desc' : 'asc'
+        params = view.request.query_parameters.merge(pn('sort') => field.name.to_s, pn('dir') => next_dir)
+        "#{view.request.path}?#{params.to_query}"
+      end
+
+      # Is this the column the result is currently sorted by?
+      def sort_active?(field)
+        !sort_direction(field).nil?
+      end
+
+      # The active sort direction for a column — :asc / :desc, or nil when the
+      # result isn't sorted by it. The presenter holds no icon names: a layout
+      # turns this tri-state into whatever glyph it likes (see _table), pairing
+      # it with `sort_numeric?` to choose a numeric vs alphabetic icon.
+      def sort_direction(field)
+        current, dir = query&.sort_state
+        return nil unless current == field.name.to_s
+
+        dir.to_s == 'desc' ? :desc : :asc
+      end
+
+      # Whether this column sorts numerically (vs alphabetically) — numbers and
+      # dates do — so a layout can pick a sort-numeric vs sort-alpha glyph.
+      def sort_numeric?(field)
+        field.is_a?(Fields::NumericField) || field.is_a?(Fields::DateField)
+      end
+
+      # ── grouping ─────────────────────────────────────────────────────────
+      # A run of records sharing one group value. `key` is URL-safe (for ?open=),
+      # `label` is for display.
+      Group = Struct.new(:key, :label, :records, keyword_init: true) do
+        def count = records.size
+      end
+
+      def grouped? = !@group_by.nil?
+
+      # The records split into groups, in group order (the relation is ordered by
+      # the group key first, so consecutive records form each group).
+      def groups
+        @groups ||= records.group_by { |r| group_key_for(r) }.map do |key, recs|
+          Group.new(key: key, label: group_label_for(recs.first), records: recs)
+        end
+      end
+
+      # Default: every group open below the collapse threshold, only the first
+      # above it. Once `?open=` is set it is authoritative (and may open several).
+      def group_open?(group)
+        if open_keys.nil?
+          records.size < config.group_collapse_threshold || group == groups.first
+        else
+          open_keys.include?(group.key)
+        end
+      end
+
+      # Toggle this group in `?open=`, materializing the current open set so the
+      # first click on a default view keeps the others as they are.
+      def group_toggle_url(group)
+        current = groups.select { |g| group_open?(g) }.map(&:key)
+        toggled = current.include?(group.key) ? current - [group.key] : current + [group.key]
+        params = view.request.query_parameters.merge(pn('open') => toggled.join(','))
+        "#{view.request.path}?#{params.to_query}"
+      end
+
+      # ── pagination ─────────────────────────────────────────────────────────
+      # We render a footer pager only when the relation handed to us is already
+      # paginated — i.e. the host called `.page` (kaminari / will_paginate, which
+      # decorate the relation). The gem never paginates on its own: no records
+      # arrive limited unless you asked for it. pagy keeps its state in a
+      # separate object, not on the relation, so it can't be detected here —
+      # render `pagy_nav` yourself.
+      def paginated?
+        @relation.respond_to?(:current_page) && @relation.respond_to?(:total_pages)
+      end
+
+      # Whether to draw the footer at all — a single page needs no pager.
+      def show_pager? = paginated? && total_pages > 1
+
+      def current_page = @relation.current_page
+      def total_pages  = @relation.total_pages
+      def total_count  = @relation.total_count
+
+      # The underlying (possibly paginated) relation, for custom layouts that
+      # would rather drive their own pager — e.g. hand it to kaminari's
+      # `paginate` helper instead of rendering the gem's _pager.
+      def page_scope = @relation
+
+      # A URL for page n that keeps this collection's filters/search/sort and
+      # every other collection's params (only our own `page` changes) — so the
+      # pager composes with everything and respects `param_prefix:`.
+      def page_url(n)
+        params = view.request.query_parameters.merge(pn('page') => n)
+        "#{view.request.path}?#{params.to_query}"
+      end
+
+      # Page numbers to show, with :gap markers for elided ranges:
+      # [1, :gap, 4, 5, 6, :gap, 10]. Always includes first/last and a window
+      # around the current page.
+      def pager_pages(window: 2)
+        return [] if total_pages <= 1
+
+        shown = ([1, total_pages] + ((current_page - window)..(current_page + window)).to_a)
+                .select { |p| p >= 1 && p <= total_pages }.uniq.sort
+        shown.each_with_index.flat_map do |p, i|
+          (i.positive? && p - shown[i - 1] > 1) ? [:gap, p] : [p]
+        end
+      end
+
+      # ── actions ──────────────────────────────────────────────────────────
+      def actions_column?
+        @actions_enabled && (custom_actions_partial.present? || row_action_definitions.any?)
+      end
+
+      # The trailing column exists when there are row actions *or* a column
+      # picker (its gear lives in that column's header cell) — so the header,
+      # rows and width all agree even on a picker-only, action-less table.
+      def trailing_column?
+        actions_column? || column_picker?
+      end
+
+      def custom_actions_partial
+        fieldset.custom_actions_partial
+      end
+
+      def row_actions(record)
+        Actions.new(view: view, subject: record, structure: structure,
+                    actions: row_action_definitions, owner: owner,
+                    suppress_show: label_link_present?(record))
+      end
+
+      def collection_actions
+        return nil unless @actions_enabled
+
+        @collection_actions ||= Actions.new(view: view, subject: model, structure: structure,
+                                            actions: structure.fieldset_actions(fieldset, on: :collection),
+                                            owner: owner)
+      end
+
+      # ── selection (bulk actions) ──────────────────────────────────────────
+      # Selection actions (`action :x, on: :selection`) operate on the rows the
+      # user ticks. Rendered as submit buttons that post the checked
+      # `selected[]` slugs to the action path — no-JS works; the optional
+      # crud-select controller adds select-all / select-group / a live count.
+      def selection_actions
+        return nil unless @actions_enabled
+
+        @selection_actions ||= Actions.new(view: view, subject: model, structure: structure,
+                                           actions: structure.fieldset_actions(fieldset, on: :selection),
+                                           owner: owner)
+      end
+
+      def selectable?
+        return @selectable if defined?(@selectable)
+
+        @selectable = @actions_enabled && (selection_actions.any? || column_selection_actions?)
+      end
+
+      # A visible column may host an `on: :selection` action in its header (acting
+      # on the ticked rows × that column's object). Like a toolbar selection
+      # action, it submits the shared select-form — so it needs the checkbox
+      # column + select-form and thus makes the collection selectable.
+      def column_selection_actions?
+        fields.any? do |field|
+          column_header_actions(field)&.items&.any? { |item| item.action.selection? }
+        end
+      end
+
+      def select_form_id
+        suffix = param_prefix ? "_#{param_prefix}" : ''
+        "crud_select_#{model.model_name.plural}#{suffix}"
+      end
+
+      # The checkbox param name (respects param_prefix) — value is each row's
+      # identify_by, resolved back with CrudComponents.selected.
+      def select_param_name = "#{pn('selected')}[]"
+
+      def select_value(record) = record.public_send(structure.identify_by).to_s
+
+      def columns_count
+        fields.size + (selectable? ? 1 : 0) + (trailing_column? ? 1 : 0)
+      end
+
+      private
+
+      GROUP_NONE = 'none'.freeze
+
+      # Validate the group key and order the relation by it (groups contiguous),
+      # keeping the active sort as the secondary order.
+      def setup_grouping(group_by)
+        @group_by = group_by.to_sym
+        @group_field = structure.field(@group_by)
+        unless @group_field.is_a?(Fields::BelongsToField) || @group_field.column
+          raise ArgumentError,
+                "crud_collection group_by: :#{@group_by} must be a column, belongs_to or enum of " \
+                "#{model} — #{@group_field.class.name.split('::').last} can't be grouped (no SQL column to order by)."
+        end
+        return unless @relation.is_a?(ActiveRecord::Relation)
+
+        order_attr = @group_field.is_a?(Fields::BelongsToField) ? @group_field.reflection.foreign_key : @group_by
+        existing = @relation.order_values
+        @relation = @relation.reorder(model.arel_table[order_attr])
+        @relation = @relation.order(*existing) if existing.any?
+      end
+
+      def group_key_for(record)
+        value = record.public_send(@group_by)
+        return GROUP_NONE if value.nil?
+
+        if @group_field.is_a?(Fields::BelongsToField)
+          value.public_send(Structure.for(value.class).identify_by).to_s
+        else
+          value.to_s
+        end
+      end
+
+      def group_label_for(record)
+        value = record.public_send(@group_by)
+        return view.t('crud_components.group.none', default: '—') if value.nil?
+
+        if @group_field.is_a?(Fields::BelongsToField)
+          view.crud_label(value)
+        elsif @group_field.is_a?(Fields::EnumField)
+          @group_field.human_value(value)
+        else
+          value.to_s
+        end
+      end
+
+      # nil when ?open= is absent (use the default open rule); an array (possibly
+      # empty) when present (authoritative).
+      def open_keys
+        return @open_keys if defined?(@open_keys)
+
+        raw = view.request.query_parameters[pn('open')]
+        @open_keys = raw.nil? ? nil : raw.to_s.split(',')
+      end
+
+      def row_action_definitions
+        @row_action_definitions ||= structure.fieldset_actions(fieldset, on: :row)
+      end
+
+      def pn(key)
+        query ? query.param_name(key) : key
+      end
+
+      def eager_load(relation)
+        return relation unless relation.is_a?(ActiveRecord::Relation)
+
+        specs = fields.flat_map(&:eager_load)
+        specs.any? ? relation.includes(*specs) : relation
+      end
+    end
+  end
+end

data/lib/crud_components/presenters/column_selection.rb

@@ -0,0 +1,91 @@
+module CrudComponents
+  module Presenters
+    # Shared "which columns are shown" logic for any presenter that exposes
+    # `available_fields` (the permitted universe) and a `param_prefix`. Two knobs
+    # drive it (set as `@picker` and `@picked_columns` by the including presenter):
+    #
+    #   @picker         false → no picking (the fieldset governs); true → the view
+    #                   participates (a collection also renders the gear).
+    #   @picked_columns :auto → read the `?cols=` submit; an Array → that exact
+    #                   selection, **without ever reading the param** (the backend
+    #                   already resolved it — from a persisted pref, or from the
+    #                   param via {CrudComponents.selected_columns}).
+    #
+    # The chosen selection is **always intersected with `available_fields`** — so a
+    # forged or stale selection can only hide or reorder columns, never reveal one
+    # the `if:` gate forbids. Mixed into both the collection and the record
+    # presenter, so a column picker drives a table and a detail view alike.
+    module ColumnSelection
+      # The columns actually rendered: the permitted set, narrowed and ordered
+      # by the user's selection when there is one.
+      def fields
+        @fields ||= select_visible(available_fields)
+      end
+
+      # Is this column part of the current view (ticked in the picker)?
+      def column_visible?(field) = fields.include?(field)
+
+      # The column-picker universe grouped by source model (Pipedrive-style):
+      # `[[model, fields], …]` with this collection's own model first, then each
+      # associated model in first-appearance order. So `publisher`,
+      # `publisher.name` and `publisher.founded_on` cluster under Publisher.
+      def field_groups
+        by_model = available_fields.group_by(&:group_model)
+        ordered = [model, *(by_model.keys - [model])]
+        ordered.filter_map { |m| [m, by_model[m]] if by_model[m] }
+      end
+
+      # A picker group's heading text and icon (no prefix), for a grouped model.
+      def group_heading(group_model) = group_model.model_name.human
+      def group_icon(group_model) = Structure.for(group_model).icon
+
+      # The ordered column names to show, or nil for "all permitted". The selection
+      # is independent of the gear: a resolved **Array** always applies (the backend
+      # decided it — the gear may live elsewhere, e.g. a standalone picker or a
+      # detail view), verbatim and without reading the param. `:auto` reads the
+      # `?cols=` submit **only when a gear is rendered here** (`picker: true`); with
+      # no gear here, `:auto` means "don't narrow" (a stray `?cols=` is ignored).
+      def visible_columns
+        return @visible_columns if defined?(@visible_columns)
+
+        @visible_columns =
+          if @picked_columns.is_a?(Array) then @picked_columns
+          elsif @picker then cols_param
+          end
+      end
+
+      private
+
+      # Normalize the `picked_columns:` knob: `:auto`/nil → `:auto`; an Array →
+      # its symbols. Anything else is a mistake worth catching at the call site.
+      def normalize_picked_columns(value)
+        case value
+        when :auto, nil then :auto
+        when Array then value.map(&:to_sym)
+        else
+          raise ArgumentError,
+                "picked_columns: expects :auto or an Array of column names, got #{value.inspect}"
+        end
+      end
+
+      def select_visible(list)
+        names = visible_columns
+        return list unless names
+
+        names.filter_map { |name| list.find { |field| field.name == name } }
+      end
+
+      # The picker submits `cols[]=a&cols[]=b` (no-JS) or, with the crud-columns
+      # controller, a single comma-joined `cols=a,b` (prettier URL). Both forms are
+      # parsed by {CrudComponents.selected_columns} (the same reader hosts use to
+      # persist a pick) — we just symbolize the result. nil when nothing was picked.
+      def cols_param
+        CrudComponents.selected_columns(column_request_params, param_prefix: param_prefix)&.map(&:to_sym)
+      end
+
+      def column_request_params
+        view.respond_to?(:request) && view.request ? view.request.query_parameters : {}
+      end
+    end
+  end
+end

data/lib/crud_components/presenters/filter.rb

@@ -0,0 +1,38 @@
+module CrudComponents
+  module Presenters
+    # The single `filter` local of the standalone filter form partial.
+    # Renders the fieldset's filterable fields (including its `filters:`
+    # extension); never auto-submits — users compose several filters here.
+    class Filter < Base
+      attr_reader :model, :structure, :query
+
+      def initialize(view:, model:, fieldset: nil, query: nil, param_prefix: nil)
+        super(view: view)
+        @model = model.is_a?(Class) ? model : model.klass
+        @structure = Structure.for(@model)
+        @query = if query.is_a?(Query)
+                   query
+                 else
+                   Query.new(@model, view.request.query_parameters,
+                             fieldset: @structure.fieldset(fieldset || :index),
+                             ability: ability, param_prefix: param_prefix)
+                 end
+      end
+
+      def fields = query.filter_fields
+      def searchable? = query.searchable?
+      def form_path = view.request.path
+      def reset_path = view.request.path
+
+      def param_name(key) = query.param_name(key)
+      def value(key) = query.value(key)
+
+      # Keep sort and foreign params; our own controls resubmit themselves.
+      def preserved_params
+        own = fields.flat_map { |f| [param_name(f.name.to_s), param_name("#{f.name}_geq"), param_name("#{f.name}_leq")] }
+        own += [param_name('q'), param_name('page'), param_name('per')]
+        view.request.query_parameters.reject { |key, _| own.include?(key) }
+      end
+    end
+  end
+end

data/lib/crud_components/presenters/form.rb

@@ -0,0 +1,57 @@
+module CrudComponents
+  module Presenters
+    # The single `form` local of the form partial. Derives a form from the
+    # same field metadata everything else uses; the host app's controller
+    # owns saving (with the matching CrudComponents.permitted_attributes list).
+    #
+    # Field selection falls back: the action's fieldset → :form → :default.
+    # A visible field that isn't editable (by type or permission) renders
+    # read-only rather than vanishing.
+    class Form < Base
+      attr_reader :record, :model, :structure, :action
+
+      def initialize(view:, record:, fieldset: nil, action: nil, url: nil, method: nil)
+        super(view: view)
+        @record = record
+        @model = record.class
+        @structure = Structure.for(@model)
+        @action = (action || (record.persisted? ? :edit : :new)).to_sym
+        @fieldset = fieldset ? @structure.fieldset(fieldset) : @structure.form_fieldset(@action)
+        @url = url
+        @method = method
+      end
+
+      # Visible fields that have a form representation (computed/json skipped).
+      def fields
+        structure.fieldset_fields(@fieldset)
+                 .select { |f| f.form_control && f.permitted?(permission_context, record) }
+      end
+
+      def editable?(field)
+        field.editable? && field.editable_permitted?(permission_context, record)
+      end
+
+      def any_errors?
+        record.errors.any?
+      end
+
+      # Errors not attached to a visible field — base errors, or errors on a
+      # column the form doesn't show. Rendered in the summary so "fix N errors"
+      # is never a dead end with nothing to fix.
+      def summary_errors
+        shown = fields.map(&:name)
+        record.errors.reject { |error| shown.include?(error.attribute) }.map(&:full_message)
+      end
+
+      # form_with options; nil url/method let Rails infer from the record.
+      def form_options
+        { url: @url, method: @method }.compact
+      end
+
+      # Read-only display reuses the value renderer (record surface).
+      def display(field)
+        render_cell(field, record, surface: :record)
+      end
+    end
+  end
+end