crud_components 0.1.0

data/lib/crud_components/fields/base.rb

@@ -0,0 +1,260 @@
+module CrudComponents
+  module Fields
+    # One subclass per field flavor (one row of the README's combination
+    # table). A field knows how it renders (which partial), how it filters
+    # (which control + how params reach SQL), and whether it sorts.
+    #
+    # Facets declared in an `attribute` block override exactly one of those:
+    # :render (block), :filter (like-spec / block / false), :sort
+    # (column symbol / block / false).
+    class Base
+      attr_reader :name, :model, :options, :facets
+
+      def initialize(name, model, options = {}, facets = {})
+        @name = name.to_sym
+        @model = model
+        @options = options
+        @facets = facets
+      end
+
+      def human_name
+        return options[:label] if options[:label].is_a?(String)
+
+        model.human_attribute_name(name)
+      end
+
+      # ── column header (issue #4) ───────────────────────────────────────────
+      # A column may own its `<th>`: a custom `header:` (a String rendered as-is —
+      # mark it html_safe for markup — or a view-context block, e.g. a link), and
+      # `header_actions:` — plain Action objects rendered in the header. A
+      # `:selection` action there acts on the ticked rows (it submits the shared
+      # select-form); any other action renders as a link/button. Available on every
+      # field flavor: a DynamicColumn passes them through its options, a declared
+      # `attribute` takes them as options too.
+      def header = options[:header]
+      def header_actions = Array(options[:header_actions])
+
+      # Whether this column brings its own header markup or header actions — the
+      # layout falls back to the plain human_name + sort link when it doesn't.
+      def custom_header? = !header.nil? || header_actions.any?
+
+      # Column-picker grouping: the heading this column sits under (a path
+      # column groups under the association(s) it reaches through), or nil for an
+      # own column. `picker_label` is the label shown within that group.
+      def group_label = nil
+      def picker_label = human_name
+
+      # The model the column-picker groups this column under (Pipedrive-style):
+      # its own model for a plain column, the *associated* model for an
+      # association or path column — so `publisher`, `publisher.name` and
+      # `publisher.founded_on` all sit under "Publisher".
+      def group_model = model
+
+      # The DB column backing this field, if any (nil for associations and
+      # computed fields).
+      def column
+        model.columns_hash[name.to_s]
+      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?
+        !!column&.null
+      end
+
+      # Whether this field's filter offers a "not set" (IS NULL) choice.
+      def filter_includes_null?
+        false
+      end
+
+      def value(record)
+        record.public_send(name)
+      end
+
+      # ── rendering ────────────────────────────────────────────────────────
+      def renderer(_record = nil)
+        options[:as] || default_renderer
+      end
+
+      def default_renderer
+        :string
+      end
+
+      def render_block
+        facets[:render]
+      end
+
+      def renderer_options
+        options.except(:as, :if, :form_as, :label, :header, :header_actions)
+      end
+
+      # ── permissions ──────────────────────────────────────────────────────
+      def permitted?(context, record = nil)
+        Permission.permitted?(options[:if], model, context, record)
+      end
+
+      # ── filtering ────────────────────────────────────────────────────────
+      def filterable?
+        return false if facets[:filter] == false
+        return false if CrudComponents::RESERVED_PARAMS.include?(name.to_s)
+        return true if filter_facet
+
+        derived_filterable?
+      end
+
+      def filter_facet
+        facets[:filter].is_a?(Proc) || facets[:filter].is_a?(Array) ||
+          facets[:filter].is_a?(Hash) || facets[:filter].is_a?(Symbol) ? facets[:filter] : nil
+      end
+
+      def derived_filterable?
+        false
+      end
+
+      # Which filter control partial to render: :text, :select, :boolean,
+      # :number_range or :date_range.
+      def filter_control
+        filter_facet ? :text : derived_filter_control
+      end
+
+      def derived_filter_control
+        :text
+      end
+
+      def filter_choices(_query = nil)
+        nil
+      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
+
+          apply_filter_facet(scope, exact)
+        else
+          apply_derived_filter(scope, exact:, geq:, leq:)
+        end
+      end
+
+      def apply_filter_facet(scope, value)
+        facet = filter_facet
+        if facet.is_a?(Proc)
+          facet.call(scope.extending(WhereLike), value)
+        else
+          LikeSpec.apply(scope, facet, value)
+        end
+      end
+
+      def apply_derived_filter(scope, **)
+        scope
+      end
+
+      # ── sorting ──────────────────────────────────────────────────────────
+      def sortable?
+        return false if facets[:sort] == false
+        return false if CrudComponents::RESERVED_PARAMS.include?(name.to_s)
+        return true if sort_facet
+
+        derived_sortable?
+      end
+
+      def sort_facet
+        facets[:sort].is_a?(Proc) || facets[:sort].is_a?(Symbol) ? facets[:sort] : nil
+      end
+
+      def derived_sortable?
+        false
+      end
+
+      def apply_sort(scope, dir)
+        case (facet = sort_facet)
+        when Proc then facet.call(scope, dir)
+        when Symbol then scope.reorder(model.arel_table[facet].public_send(dir))
+        else scope.reorder(model.arel_table[name].public_send(dir))
+        end
+      end
+
+      # ── forms ──────────────────────────────────────────────────────────────
+      # Columns that exist but are never user-editable in a derived form.
+      NON_EDITABLE_COLUMNS = %w[id created_at updated_at].freeze
+
+      # Whether this field appears as an *input* in a derived form. `editable:`
+      # overrides; a symbol/Proc means "editable, subject to a can? check"
+      # (see editable_permitted?).
+      def editable?
+        case options[:editable]
+        when false then false
+        when nil then default_editable?
+        else true
+        end
+      end
+
+      def default_editable?
+        false
+      end
+
+      def editable_permitted?(context, record = nil)
+        condition = options[:editable]
+        return true unless condition.is_a?(Symbol) || condition.is_a?(Proc)
+
+        # recordless: false — a record-dependent `editable:` can't be granted by
+        # the class-level permit list (no record there); deny by default and let
+        # the per-record form check decide where a record is present.
+        Permission.permitted?(condition, model, context, record, recordless: false)
+      end
+
+      # The form-input flavor; nil = no form representation (json, computed).
+      def form_control
+        nil
+      end
+
+      # The form-input partial to render: crud_components/form_fields/_<name>.
+      # Defaults to the field's form_control type; override per field with
+      # `form_as:` (mirrors `as:` for the read-only/display renderer). The
+      # partial receives the simple_form builder `f`, the `field`, and `form`.
+      def form_partial
+        options[:form_as] || form_control
+      end
+
+      # What this field contributes to a strong-params permit list — a symbol
+      # or a nested hash; collected by Structure#permitted_params.
+      def permit_param
+        name
+      end
+
+      # ── loading ──────────────────────────────────────────────────────────
+      # Includes-specs (symbols/nested hashes for ActiveRecord#includes) to
+      # eager-load when this column is shown. Base contributes the per-attribute
+      # `preload:` — associations a render block / custom renderer reaches on the
+      # listed model. Association fields override to also nest the target's
+      # identity_preloads under the association name.
+      def eager_load
+        declared_preloads
+      end
+
+      # The `preload:` option as an array of includes-specs (a nested hash kept
+      # intact, unlike Array()).
+      def declared_preloads
+        case (p = options[:preload])
+        when nil then []
+        when Array then p
+        else [p]
+        end
+      end
+
+      private
+
+      def arel_column
+        model.arel_table[name]
+      end
+
+      def like_pattern(value)
+        "%#{ActiveRecord::Base.sanitize_sql_like(value)}%"
+      end
+    end
+  end
+end

data/lib/crud_components/fields/belongs_to_field.rb

@@ -0,0 +1,91 @@
+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.
+    class BelongsToField < Base
+      def default_renderer = :association
+
+      def reflection
+        @reflection ||= model.reflect_on_association(name)
+      end
+
+      def target
+        reflection.klass
+      end
+
+      # Picker grouping: a belongs_to/has_one column anchors its target's group
+      # (polymorphic has no single target, so it groups under its own model).
+      def group_model = reflection.polymorphic? ? model : target
+
+      def target_structure
+        Structure.for(target)
+      end
+
+      def derived_filterable?
+        reflection.belongs_to? && !reflection.polymorphic?
+      end
+
+      def derived_sortable? = false
+
+      # select (a dropdown of all targets) below `select_limit` rows, else free
+      # text. Counted per render, not memoized: the field instance lives on the
+      # process-cached Structure, so a memoized count would freeze at its boot-time
+      # value and render the wrong control once the table grows past the limit.
+      # One COUNT per filter-row render is negligible next to rendering the table.
+      def derived_filter_control
+        target.count <= CrudComponents.config.select_limit ? :select : :text
+      end
+
+      def filter_choices(_query = nil)
+        structure = target_structure
+        target.all.map { |record| [structure.label_for(record).to_s, record.public_send(structure.identify_by)] }
+              .sort_by(&:first)
+      end
+
+      def apply_derived_filter(scope, exact: nil, **)
+        return scope unless exact
+
+        identified = scope.where(name => target.where(target_structure.identify_by => exact))
+        searched = like_subquery(scope, exact)
+        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] }.
+      # 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.
+      def eager_load
+        return [name] if reflection.polymorphic?
+
+        nested = (target_structure.identity_preloads + declared_preloads).uniq
+        [nested.empty? ? name : { name => nested }]
+      end
+
+      # ── forms ────────────────────────────────────────────────────────────
+      # Assigned via the foreign key; the select submits real ids (forms are
+      # POST bodies, not shareable URLs — unlike the filter, which uses
+      # identify_by).
+      def default_editable? = reflection.belongs_to? && !reflection.polymorphic?
+      def form_control = :belongs_to
+      def permit_param = reflection.foreign_key.to_sym
+
+      def form_choices
+        structure = target_structure
+        target.all.map { |record| [structure.label_for(record).to_s, record.id] }.sort_by(&:first)
+      end
+
+      private
+
+      def like_subquery(scope, value)
+        spec = target_structure.search_in_spec
+        return nil if spec.nil? || spec.empty?
+
+        scope.where(name => LikeSpec.apply(target.all, spec, value))
+      end
+    end
+  end
+end

data/lib/crud_components/fields/boolean_field.rb

@@ -0,0 +1,31 @@
+module CrudComponents
+  module Fields
+    # boolean column: ✓/✗ cell, any/yes/no select; values cast & validated,
+    # invalid ones leave the scope unchanged.
+    class BooleanField < Base
+      def default_renderer = :boolean
+      def derived_filterable? = true
+      def derived_sortable? = true
+      def derived_filter_control = :boolean
+      def default_editable? = true
+      def form_control = :boolean
+
+      # Stricter than ActiveModel's cast (which makes any junk string true):
+      # only recognizable values filter, everything else is ignored.
+      TRUE_VALUES = %w[true t 1 yes on].freeze
+      FALSE_VALUES = %w[false f 0 no off].freeze
+
+      # 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
+        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
+        else scope
+        end
+      end
+    end
+  end
+end

data/lib/crud_components/fields/computed_field.rb

@@ -0,0 +1,34 @@
+module CrudComponents
+  module Fields
+    # A name Rails doesn't know: a public model method (rendered by its value
+    # type) or a declared render block. Query behavior only through facets —
+    # a Ruby-computed value has no SQL meaning until a facet gives it one.
+    class ComputedField < Base
+      def renderer(record = nil)
+        return options[:as] if options[:as]
+        return nil if render_block
+
+        record ? renderer_for_value(value(record)) : :string
+      end
+
+      def default_renderer = :string
+
+      def value(record)
+        render_block ? nil : record.public_send(name)
+      end
+
+      private
+
+      def renderer_for_value(value)
+        case value
+        when Numeric then :number
+        when Date then :date
+        when Time, DateTime then :datetime
+        when true, false then :boolean
+        when Hash, Array then :json
+        else :string
+        end
+      end
+    end
+  end
+end

data/lib/crud_components/fields/date_field.rb

@@ -0,0 +1,51 @@
+module CrudComponents
+  module Fields
+    # date/datetime column: from–to range plus exact day; datetime ranges are
+    # whole-day-inclusive (a `leq` of 2026-01-31 includes that entire day).
+    class DateField < Base
+      def datetime?
+        @datetime ||= %i[datetime timestamp timestamptz].include?(model.columns_hash[name.to_s]&.type)
+      end
+
+      def default_renderer = datetime? ? :datetime : :date
+      def derived_filterable? = true
+      def derived_sortable? = true
+      def derived_filter_control = :date_range
+      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
+        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
+      end
+
+      private
+
+      def apply_day(scope, day)
+        if datetime?
+          scope.where(arel_column.gteq(lower_bound(day)).and(arel_column.lteq(upper_bound(day))))
+        else
+          scope.where(name => day)
+        end
+      end
+
+      def lower_bound(day)
+        datetime? ? day.beginning_of_day : day
+      end
+
+      def upper_bound(day)
+        datetime? ? day.end_of_day : day
+      end
+
+      def cast(value)
+        return nil if value.nil?
+
+        Date.parse(value)
+      rescue ArgumentError, TypeError, RangeError
+        nil
+      end
+    end
+  end
+end

data/lib/crud_components/fields/dynamic_field.rb

@@ -0,0 +1,44 @@
+module CrudComponents
+  module Fields
+    # The field flavor behind a {CrudComponents::DynamicColumn}: a column with no
+    # row in the model's table. It renders like a ComputedField (value typed, or
+    # `as:`), but the value comes from the column's resolver block rather than a
+    # method on the record, and a `preload:` lambda primes a per-page cache so a
+    # whole table costs one fetch, not one per row.
+    #
+    # Unlike the built-in fields — memoized on the immutable Structure and shared
+    # across every request — a DynamicField is built fresh per `crud_collection`
+    # call, so it may safely hold request state (the loaded cache). Filtering and
+    # sorting work only through the column's `filter:`/`sort:` facets; without
+    # them the column never reaches SQL, which keeps the query whitelist intact.
+    class DynamicField < ComputedField
+      # header:/header_actions: arrive via the column's options and are read by
+      # Fields::Base#header / #header_actions / #custom_header? — the layout picks
+      # them up through the Collection presenter, same as a declared attribute's.
+      def initialize(column, model)
+        super(column.name, model, column.options, column.facets)
+        @value_block = column.value_block
+        @preload_block = column.preload_block
+        @loaded = nil
+      end
+
+      # Run the batch loader once over the page's records; the resolver then
+      # reads per-record from whatever it returned. Called by the presenter just
+      # before rendering, only for the columns that end up visible.
+      def preload!(records)
+        @loaded = @preload_block&.call(records)
+        self
+      end
+
+      def value(record)
+        return super unless @value_block
+
+        @value_block.arity == 1 ? @value_block.call(record) : @value_block.call(record, @loaded)
+      end
+
+      # Never backed by a real DB column — keep column/nullable introspection
+      # nil so nothing tries to read model.columns_hash[name].
+      def column = nil
+    end
+  end
+end

data/lib/crud_components/fields/enum_field.rb

@@ -0,0 +1,40 @@
+module CrudComponents
+  module Fields
+    # enum: badge cell, select of enum keys, values validated against the
+    # enum definition — invalid ones leave the scope unchanged.
+    class EnumField < Base
+      def default_renderer = :enum
+      def derived_filterable? = true
+      def derived_sortable? = true
+      def derived_filter_control = :select
+      def default_editable? = true
+      def form_control = :enum
+
+      def form_choices
+        enum_keys.map { |key| [human_value(key), key] }
+      end
+
+      def enum_keys
+        model.defined_enums[name.to_s].keys
+      end
+
+      def filter_choices(_query = nil)
+        enum_keys.map { |key| [human_value(key), key] }
+      end
+
+      def human_value(key)
+        model.human_attribute_name("#{name}.#{key}", default: key.to_s.humanize)
+      end
+
+      # 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)
+
+        scope.where(name => exact)
+      end
+    end
+  end
+end

data/lib/crud_components/fields/has_many_field.rb

@@ -0,0 +1,50 @@
+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).
+    class HasManyField < Base
+      def default_renderer = :association_list
+
+      def reflection
+        @reflection ||= model.reflect_on_association(name)
+      end
+
+      def target
+        reflection.klass
+      end
+
+      # Picker grouping: a has_many/habtm column anchors its target's group, so
+      # `authors`, `authors.name` and `authors.email` all sit under "Author".
+      def group_model = target
+
+      # Load the association, nesting each target's identity_preloads (+ this
+      # column's `preload:`) so rendering the list's labels never N+1s.
+      def eager_load
+        nested = (target_structure.identity_preloads + declared_preloads).uniq
+        [nested.empty? ? name : { name => nested }]
+      end
+
+      # The index a "+n more" / list link points at: the nested route under
+      # the owner if it resolves, else the target's index filtered by the
+      # owner. Resolved in the view (RouteResolver); here we just expose the
+      # association so the renderer can build it.
+      def collection_link_target = target
+
+      # ── forms ────────────────────────────────────────────────────────────
+      # Editable only for habtm (and simple has_many) via the *_ids setter —
+      # reassigning ids is safe; nested attributes are out of scope.
+      def habtm? = reflection.macro == :has_and_belongs_to_many
+      def default_editable? = habtm?
+      def form_control = :habtm
+      def ids_method = "#{name.to_s.singularize}_ids".to_sym
+      def permit_param = { ids_method => [] }
+
+      def form_choices
+        structure = target_structure
+        target.all.map { |record| [structure.label_for(record).to_s, record.id] }.sort_by(&:first)
+      end
+
+      def target_structure = Structure.for(target)
+    end
+  end
+end

data/lib/crud_components/fields/json_field.rb

@@ -0,0 +1,10 @@
+module CrudComponents
+  module Fields
+    # json/jsonb column: pretty-printed <pre>; no derived filter or sort.
+    class JsonField < Base
+      def default_renderer = :json
+      # JSON columns are not form-editable in v1: round-tripping raw JSON
+      # through a textarea needs parse-on-assign. Renders read-only.
+    end
+  end
+end

data/lib/crud_components/fields/numeric_field.rb

@@ -0,0 +1,31 @@
+module CrudComponents
+  module Fields
+    # numeric column: min–max range plus exact match; unparsable values ignored.
+    class NumericField < Base
+      def default_renderer = :number
+      def derived_filterable? = true
+      def derived_sortable? = true
+      def derived_filter_control = :number_range
+      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
+        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
+      end
+
+      private
+
+      def cast(value)
+        return nil if value.nil?
+
+        decimal = BigDecimal(value)
+        decimal.finite? ? decimal : nil # reject NaN / Infinity — they aren't filters
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+  end
+end