crud_components 0.1.0

data/lib/crud_components/presenters/record.rb

@@ -0,0 +1,57 @@
+module CrudComponents
+  module Presenters
+    # The single `record_presenter` local of the record partial.
+    class Record < Base
+      include ColumnSelection
+
+      attr_reader :record, :model, :structure, :fieldset, :param_prefix
+
+      def initialize(view:, record:, fieldset: nil, actions: true, picked_columns: :auto,
+                     param_prefix: nil, extra_columns: nil)
+        super(view: view)
+        @record = record
+        @model = record.class
+        @structure = Structure.for(@model)
+        @fieldset = @structure.fieldset(fieldset || :show)
+        @actions_enabled = actions
+        @param_prefix = param_prefix
+        # Dynamic columns work on a detail view too — user-defined properties
+        # whose data lives outside the model's table, shown as extra rows.
+        @dynamic_fields = Array(extra_columns).map { |c| c.to_field(@model).preload!([record]) }
+        # A column picker can narrow/order this dl too, but a detail view has no
+        # inline gear of its own (no `picker:` knob) — the gear is a standalone
+        # `crud_column_picker` on the page. So pass `picked_columns:` an Array you
+        # resolved (e.g. via `CrudComponents.selected_columns(params)`); `:auto`
+        # here means "don't narrow" (no gear → a stray `?cols=` is ignored).
+        # (`fields`, `column_visible?` and the picker logic come from ColumnSelection.)
+        @picker = false
+        @picked_columns = normalize_picked_columns(picked_columns)
+      end
+
+      def title
+        structure.label_for(record, view)
+      end
+
+      # Every field this user may see on this record — declared fields plus the
+      # dynamic columns; the picker's universe.
+      def available_fields
+        @available_fields ||= (structure.fieldset_fields(fieldset) + @dynamic_fields)
+                              .select { |f| f.permitted?(permission_context, record) }
+      end
+
+      def value_html(field)
+        render_cell(field, record, surface: :record)
+      end
+
+      # Row actions for this record; a derived :show button to the page we
+      # are already on would be noise.
+      def actions
+        return nil unless @actions_enabled
+
+        @actions ||= Actions.new(view: view, subject: record, structure: structure,
+                                 actions: structure.fieldset_actions(fieldset, on: :row),
+                                 suppress_show: true)
+      end
+    end
+  end
+end

data/lib/crud_components/query.rb

@@ -0,0 +1,110 @@
+module CrudComponents
+  # Applies URL params to a relation: filtering, global search, sorting.
+  #
+  # The uniform rule: a param is applied iff it names a filterable field of
+  # the fieldset in play that the current user may see (or one of the
+  # reserved params q/sort/dir/page/per). Everything else never reaches SQL.
+  class Query
+    SORT_DIRECTIONS = %w[asc desc].freeze
+
+    attr_reader :model, :structure, :fieldset, :param_prefix
+
+    def initialize(model, params, fieldset: nil, ability: nil, param_prefix: nil, extra_fields: [])
+      @model = model
+      @structure = Structure.for(model)
+      @fieldset = fieldset.is_a?(Fieldset) ? fieldset : @structure.fieldset(fieldset)
+      @params = extract(params)
+      @permission = PermissionContext.new(ability)
+      @param_prefix = param_prefix
+      @extra_fields = extra_fields
+    end
+
+    def apply(scope)
+      scope = apply_filters(scope)
+      scope = apply_search(scope)
+      apply_sort(scope)
+    end
+
+    def fieldset_name = fieldset.name
+
+    def filter_fields
+      (structure.fieldset_filter_fields(fieldset) + @extra_fields.select(&:filterable?))
+        .select { |f| f.permitted?(@permission) }
+    end
+
+    def sortable_fields
+      (structure.fieldset_sortable_fields(fieldset) + @extra_fields.select(&:sortable?))
+        .select { |f| f.permitted?(@permission) }
+    end
+
+    def searchable? = structure.searchable?
+
+    # Current value of a (logical, unprefixed) param — for filter controls.
+    def value(key) = param(key)
+
+    def active?
+      keys = filter_fields.flat_map { |f| [f.name.to_s, "#{f.name}_geq", "#{f.name}_leq"] }
+      (keys + ['q']).any? { |key| param(key) }
+    end
+
+    # [field_name_string, direction_string] or nil.
+    def sort_state
+      field = current_sort_field
+      field && [field.name.to_s, direction]
+    end
+
+    def param_name(key) = "#{prefix}#{key}"
+
+    private
+
+    def prefix = param_prefix ? "#{param_prefix}_" : ''
+
+    def param(key)
+      raw = @params[param_name(key)]
+      raw.is_a?(String) && raw.present? ? raw : nil
+    end
+
+    def extract(params)
+      hash = if params.respond_to?(:to_unsafe_h)
+               params.to_unsafe_h
+             else
+               params.to_h
+             end
+      hash.transform_keys(&:to_s)
+    end
+
+    def apply_filters(scope)
+      filter_fields.reduce(scope) do |current, field|
+        exact = param(field.name.to_s)
+        geq = param("#{field.name}_geq")
+        leq = param("#{field.name}_leq")
+        next current unless exact || geq || leq
+
+        field.apply_filter(current, exact: exact, geq: geq, leq: leq)
+      end
+    end
+
+    def apply_search(scope)
+      q = param('q')
+      return scope unless q && structure.searchable?
+
+      structure.apply_search(scope, q, permission: @permission)
+    end
+
+    def current_sort_field
+      sort = param('sort')
+      sort && sortable_fields.find { |f| f.name.to_s == sort }
+    end
+
+    def direction
+      SORT_DIRECTIONS.include?(param('dir')) ? param('dir') : 'asc'
+    end
+
+    def apply_sort(scope)
+      field = current_sort_field
+      return scope unless field
+
+      field.apply_sort(scope, direction.to_sym)
+    end
+  end
+end

data/lib/crud_components/route_resolver.rb

@@ -0,0 +1,123 @@
+module CrudComponents
+  # Resolves derived actions and record links to routes: the most specific
+  # conventional route first (association-scoped when the collection came
+  # from an association), then the top-level route, then nil — a nil means
+  # the button/link is omitted, never broken.
+  module RouteResolver
+    module_function
+
+    def action_path(view, action, record: nil, model: nil, owner: nil)
+      if action.path_block
+        subject = record || model
+        return view.instance_exec(subject, &action.path_block)
+      end
+
+      if action.collection?
+        collection_path(view, action, model, owner)
+      else
+        member_path(view, action, record, owner)
+      end
+    end
+
+    # The plain link to a record (label cells, association cells):
+    # show route, then edit. Returns [path, kind] or nil.
+    def record_path(view, record, owner: nil)
+      path = try_helpers(view, member_candidates(nil, record, owner))
+      return [path, :show] if path
+
+      path = try_helpers(view, member_candidates('edit_', record, owner))
+      path ? [path, :edit] : nil
+    end
+
+    # Whether the record has a plain (show) route — feeds the
+    # ":show button only without a label link" rule.
+    def show_path(view, record, owner: nil)
+      try_helpers(view, member_candidates(nil, record, owner))
+    end
+
+    # The index a has_many "+n more" link points at:
+    #   1. the nested index under the owner (publisher_books_path(publisher)),
+    #   2. else the target's index filtered by the owner — but ONLY when the
+    #      target actually has a filterable belongs_to back to the owner
+    #      (publisher→books works; a habtm like author↔books does not, so we
+    #      do not emit a link that would silently show everything),
+    #   3. else nil (the renderer shows "+n more" as plain text).
+    # `assoc_name` is the owner's reflection name (e.g. :books).
+    def collection_index_path(view, target, owner, assoc_name)
+      return nil unless owner
+
+      key = target.model_name.route_key
+      owner_key = owner.model_name.singular_route_key
+      nested = "#{owner_key}_#{key}_path"
+      return safe_url(view, nested, owner) if view.respond_to?(nested)
+
+      flat = "#{key}_path"
+      return nil unless view.respond_to?(flat)
+
+      filter = inverse_filter(target, owner, assoc_name)
+      return nil unless filter
+
+      safe_url(view, flat, **{ filter[:param] => filter[:value] })
+    end
+
+    # The target's belongs_to that mirrors the owner's collection (matched by
+    # foreign key), if it is filterable — with the owner's identify_by value.
+    def inverse_filter(target, owner, assoc_name)
+      owner_reflection = owner.class.reflect_on_association(assoc_name)
+      return nil unless owner_reflection&.foreign_key
+
+      fk = owner_reflection.foreign_key.to_s
+      inverse = target.reflect_on_all_associations(:belongs_to).find { |r| r.foreign_key.to_s == fk }
+      return nil unless inverse
+
+      field = Structure.for(target).field(inverse.name)
+      return nil unless field.filterable?
+
+      identify = Structure.for(owner.class).identify_by
+      { param: inverse.name, value: owner.public_send(identify) }
+    rescue CrudComponents::DefinitionError
+      nil
+    end
+
+    def safe_url(view, helper, *args, **kwargs)
+      kwargs.empty? ? view.public_send(helper, *args) : view.public_send(helper, *args, **kwargs)
+    rescue ActionController::UrlGenerationError, NoMethodError
+      nil
+    end
+
+    def member_path(view, action, record, owner)
+      prefix = { show: nil, destroy: nil, edit: 'edit_' }.fetch(action.name, "#{action.name}_")
+      try_helpers(view, member_candidates(prefix, record, owner))
+    end
+
+    def collection_path(view, action, model, owner)
+      prefix = action.name == :new ? 'new_' : "#{action.name}_"
+      key = action.name == :new ? model.model_name.singular_route_key : model.model_name.route_key
+      candidates = []
+      candidates << ["#{prefix}#{owner.model_name.singular_route_key}_#{key}_path", [owner]] if owner
+      candidates << ["#{prefix}#{key}_path", []]
+      try_helpers(view, candidates)
+    end
+
+    def member_candidates(prefix, record, owner)
+      key = record.model_name.singular_route_key
+      candidates = []
+      candidates << ["#{prefix}#{owner.model_name.singular_route_key}_#{key}_path", [owner, record]] if owner
+      candidates << ["#{prefix}#{key}_path", [record]]
+      candidates
+    end
+
+    def try_helpers(view, candidates)
+      candidates.each do |helper, args|
+        next unless view.respond_to?(helper)
+
+        begin
+          return view.public_send(helper, *args)
+        rescue ActionController::UrlGenerationError, NoMethodError
+          next
+        end
+      end
+      nil
+    end
+  end
+end

data/lib/crud_components/structure.rb

@@ -0,0 +1,343 @@
+module CrudComponents
+  # The resolved, validated description of how a model appears in the UI.
+  # Built lazily per model class and memoized; works for models without any
+  # declaration (rule zero: everything is derived from what Rails knows).
+  class Structure
+    RENDERER_GEMS = {
+      markdown: %w[commonmarker redcarpet kramdown],
+      asciidoc: %w[asciidoctor]
+    }.freeze
+
+    class << self
+      def for(model)
+        unless model.respond_to?(:columns_hash)
+          raise ArgumentError, "#{model.inspect} is not an ActiveRecord model class"
+        end
+
+        cached = model.instance_variable_get(:@_crud_structure) if model.instance_variable_defined?(:@_crud_structure)
+        return cached if cached
+
+        structure = new(model, find_builder(model))
+        model.instance_variable_set(:@_crud_structure, structure)
+        structure
+      end
+
+      private
+
+      # Class-level ivars are not inherited; walk up for STI subclasses.
+      def find_builder(model)
+        klass = model
+        while klass.respond_to?(:instance_variable_defined?)
+          if klass.instance_variable_defined?(:@_crud_structure_block)
+            block = klass.instance_variable_get(:@_crud_structure_block)
+            return Builder.new(model, &block) if block
+          end
+          klass = klass.superclass
+          break if klass.nil? || klass == ActiveRecord::Base
+        end
+        nil
+      end
+    end
+
+    # identity_preloads: associations to eager-load whenever this model is shown
+    # as another model's association cell (its label/render dependencies), from
+    # `label …, preload:` and the standalone `preload` declaration.
+    attr_reader :model, :identify_by, :identity_preloads
+
+    def initialize(model, builder = nil)
+      @model = model
+      @declarations = builder&.declarations || {}
+      @label_decl = builder&.label_decl
+      @identify_by = builder&.identify_by_decl || :id
+      @icon_decl = builder&.icon_decl
+      @search_decl = builder&.search_decl
+      @identity_preloads = ((builder&.label_preload_decl || []) + (builder&.preload_decl || [])).uniq
+      @declared_actions = builder&.actions || {}
+      @declared_fieldsets = builder&.fieldsets || {}
+      @fields = {}
+      validate!
+    end
+
+    # ── fields ───────────────────────────────────────────────────────────────
+    def field(name)
+      @fields[name.to_sym] ||= resolve_field(name.to_sym)
+    end
+
+    # The :all set: every column (foreign keys swapped for their belongs_to),
+    # then Active Storage attachments, then non-belongs_to associations
+    # (has_many / habtm / has_one), then any declared computed fields — all
+    # derived, in a stable order.
+    def default_field_names
+      @default_field_names ||= begin
+        base = column_field_names + attachment_field_names + association_field_names
+        base + (@declarations.keys - base)
+      end
+    end
+
+    # Active Storage attachments (has_one_attached / has_many_attached),
+    # surfaced as image fields — derived, no declaration needed.
+    def attachment_field_names
+      @attachment_field_names ||=
+        model.respond_to?(:reflect_on_all_attachments) ? model.reflect_on_all_attachments.map(&:name) : []
+    end
+
+    # has_many / habtm / has_one — belongs_to already arrive via the FK swap.
+    # Active Storage's generated join associations (images_attachments/_blobs)
+    # and ActionText's rich-text associations are not user-facing columns.
+    def association_field_names
+      @association_field_names ||=
+        model.reflect_on_all_associations.reject(&:belongs_to?).map(&:name)
+              .reject { |n| n.to_s.start_with?('rich_text_', 'with_attached_') }
+              .reject { |n| attachment_support_names.include?(n) }
+    end
+
+    # The join associations behind each attachment — excluded from the field
+    # universe, since the attachment itself is the field.
+    def attachment_support_names
+      @attachment_support_names ||=
+        attachment_field_names.flat_map do |att|
+          %W[#{att}_attachment #{att}_attachments #{att}_blob #{att}_blobs].map(&:to_sym)
+        end
+    end
+
+    # ── fieldsets ────────────────────────────────────────────────────────────
+    # :default always exists; :index and :show fall back to :default when not
+    # declared; any other name must be declared (typo protection).
+    def fieldset(name = :default)
+      name = (name || :default).to_sym
+      return @declared_fieldsets[name] if @declared_fieldsets.key?(name)
+      return default_fieldset if %i[default index show].include?(name)
+
+      known = (@declared_fieldsets.keys + [:default]).uniq
+      raise UnknownFieldsetError, "#{model} has no fieldset :#{name} — " \
+                                  "available: #{known.map(&:inspect).join(', ')}"
+    end
+
+    def default_fieldset
+      @default_fieldset ||= Fieldset.new(:default, :all)
+    end
+
+    def fieldset_fields(fieldset)
+      names = fieldset.all_fields? ? default_field_names : fieldset.field_names
+      names.map { |name| field(name) }
+    end
+
+    def fieldset_filter_fields(fieldset)
+      (fieldset_fields(fieldset) + fieldset.filter_names.map { |name| field(name) })
+        .uniq.select(&:filterable?)
+    end
+
+    def fieldset_sortable_fields(fieldset)
+      fieldset_fields(fieldset).select(&:sortable?)
+    end
+
+    # ── forms ──────────────────────────────────────────────────────────────
+    # Form field selection falls back most-specific-first:
+    #   the action's own fieldset → :form → :default.
+    def form_fieldset(action = nil)
+      names = [action, :form, :default].compact
+      names.each do |name|
+        return @declared_fieldsets[name] if @declared_fieldsets.key?(name)
+      end
+      default_fieldset
+    end
+
+    # Editable, permitted fields of the form fieldset, as a strong-params
+    # permit list (symbols and nested hashes) — the controller's single
+    # source of truth, so form and params can never drift.
+    def permitted_params(action, context)
+      fields = fieldset_fields(form_fieldset(action))
+      fields.select { |f| f.permitted?(context) && f.editable? && f.editable_permitted?(context) && f.form_control }
+            .map(&:permit_param)
+    end
+
+    # ── identity ─────────────────────────────────────────────────────────────
+    def label_source
+      return @label_decl if @label_decl
+
+      @label_source ||= %i[name title].find { |attr| model.columns_hash.key?(attr.to_s) } ||
+                        model.columns.find { |col| col.type == :string }&.name&.to_sym
+    end
+
+    def label_for(record, context = nil)
+      case (source = label_source)
+      when Proc then context ? context.instance_exec(record, &source) : source.call(record)
+      when Symbol then record.public_send(source)
+      else "#{model.model_name.human} ##{record.id}"
+      end
+    end
+
+    # The field whose cell carries the record link (nil for block labels).
+    def label_field_name
+      label_source.is_a?(Symbol) ? label_source : nil
+    end
+
+    # The icon name (no library prefix) badging this model: the declared `icon`,
+    # else the name-based guess in `config.model_icons` (keyed by the singular
+    # underscored model name), else `config.model_fallback_icon` (nil = none).
+    # Resolved per call so a host's config changes apply without rebuilding.
+    def icon
+      @icon_decl || CrudComponents.config.model_icons[model.model_name.element] ||
+        CrudComponents.config.model_fallback_icon
+    end
+
+    # ── search ───────────────────────────────────────────────────────────────
+    # nil when search_in is a custom block (delegation is then impossible).
+    def search_in_spec
+      return nil if @search_decl.is_a?(Proc)
+
+      @search_in_spec ||= (@search_decl.presence || default_search_spec)
+    end
+
+    def default_search_spec
+      model.columns.select { |col| %i[string text].include?(col.type) }
+           .map { |col| col.name.to_sym }
+    end
+
+    def searchable?
+      @search_decl.is_a?(Proc) || search_in_spec.any?
+    end
+
+    def apply_search(scope, query_string, permission: nil)
+      if @search_decl.is_a?(Proc)
+        @search_decl.call(scope.extending(WhereLike), query_string)
+      else
+        spec = permission ? permitted_search_spec(permission) : search_in_spec
+        spec.any? ? LikeSpec.apply(scope, spec, query_string) : scope
+      end
+    end
+
+    # A declared, permission-gated column (`attribute :x, if: :manage`) is
+    # hidden everywhere including ?q= — so drop it from the search spec for a
+    # user who may not see it. Undeclared columns in the default spec are
+    # model-global search by design and stay.
+    def permitted_search_spec(permission)
+      search_in_spec.reject do |entry|
+        entry.is_a?(Symbol) && model.columns_hash.key?(entry.to_s) &&
+          @declarations.key?(entry) && !field(entry).permitted?(permission)
+      end
+    end
+
+    # ── actions ──────────────────────────────────────────────────────────────
+    def actions
+      @actions ||= begin
+        derived = %i[new show edit destroy].to_h { |name| [name, Action.new(name, derived: true)] }
+        merged = derived.merge(@declared_actions)
+        custom = @declared_actions.keys - derived.keys
+        order = [:new, :show, :edit, *custom, :destroy]
+        order.to_h { |name| [name, merged.fetch(name)] }
+      end
+    end
+
+    def action(name)
+      actions[name.to_sym] || raise(DefinitionError, "#{model} has no action :#{name} — " \
+                                                     "available: #{actions.keys.map(&:inspect).join(', ')}")
+    end
+
+    # A fieldset's actions: list is authoritative per kind: listing only row
+    # actions curates the row buttons without losing the derived :new button
+    # (and vice versa). An empty list hides everything.
+    def fieldset_actions(fieldset, on:)
+      of_kind = ->(a) { a.public_send("#{on}?") }
+      names = fieldset.action_names
+      return actions.values.select(&of_kind) if names.nil?
+      return [] if names.empty?
+
+      listed = names.map { |name| action(name) }.select(&of_kind)
+      listed.any? ? listed : actions.values.select(&of_kind)
+    end
+
+    # ── validation (DefinitionError with a way out, at first build) ──────────
+    private
+
+    def validate!
+      @declarations.each_key { |name| field(name) }
+      validate_renderer_gems!
+      validate_fieldsets!
+    end
+
+    def validate_renderer_gems!
+      @declarations.each do |name, decl|
+        gems = RENDERER_GEMS[decl[:options][:as]]
+        next unless gems
+        next if gems.any? { |gem_name| try_require(gem_name) }
+
+        raise DefinitionError, "#{model}.#{name}: as: :#{decl[:options][:as]} needs one of these gems " \
+                               "in your bundle: #{gems.join(', ')}"
+      end
+    end
+
+    def try_require(gem_name)
+      require gem_name
+      true
+    rescue LoadError
+      false
+    end
+
+    def validate_fieldsets!
+      @declared_fieldsets.each_value do |fs|
+        fs.field_names.each { |name| field(name) } unless fs.all_fields?
+        fs.filter_names.each do |name|
+          next if field(name).filterable?
+
+          raise DefinitionError, "#{model}: fieldset :#{fs.name} lists :#{name} under filters:, " \
+                                 'but that field is not filterable — give it a filter facet first'
+        end
+        fs.action_names&.each { |name| action(name) }
+      end
+    end
+
+    def resolve_field(name)
+      decl = @declarations[name] || {}
+      field_class_for(name, decl[:facets] || {})
+        .new(name, model, decl[:options] || {}, decl[:facets] || {})
+    end
+
+    def field_class_for(name, facets)
+      if name.to_s.include?('.')
+        Fields::PathField
+      elsif model.defined_enums.key?(name.to_s)
+        Fields::EnumField
+      elsif (reflection = model.reflect_on_association(name))
+        reflection.collection? ? Fields::HasManyField : Fields::BelongsToField
+      elsif model.respond_to?(:reflect_on_attachment) && model.reflect_on_attachment(name)
+        Fields::AttachmentField
+      elsif (column = model.columns_hash[name.to_s])
+        column_field_class(column)
+      elsif facets[:render] || model.method_defined?(name)
+        Fields::ComputedField
+      else
+        raise DefinitionError, "#{model} has no column, enum, association or public method '#{name}'. " \
+                               "Computed fields need a render facet: attribute(:#{name}) { |record| ... }"
+      end
+    end
+
+    def column_field_class(column)
+      case column.type
+      when :text then Fields::TextField
+      when :integer, :float, :decimal then Fields::NumericField
+      when :date, :datetime, :timestamp, :timestamptz then Fields::DateField
+      when :boolean then Fields::BooleanField
+      when :json, :jsonb then Fields::JsonField
+      else Fields::StringField
+      end
+    end
+
+    def column_field_names
+      @column_field_names ||= begin
+        by_foreign_key = {}
+        polymorphic_type_columns = []
+        model.reflect_on_all_associations(:belongs_to).each do |ref|
+          by_foreign_key[ref.foreign_key.to_s] = ref.name
+          polymorphic_type_columns << ref.foreign_type.to_s if ref.polymorphic?
+        end
+
+        model.columns.filter_map do |col|
+          next nil if polymorphic_type_columns.include?(col.name)
+
+          by_foreign_key[col.name] || col.name.to_sym
+        end.uniq
+      end
+    end
+  end
+end

data/lib/crud_components/version.rb

@@ -0,0 +1,3 @@
+module CrudComponents
+  VERSION = '0.1.0'.freeze
+end

data/lib/crud_components/where_like.rb

@@ -0,0 +1,13 @@
+module CrudComponents
+  # Extended onto every scope handed to filter/search blocks, so custom query
+  # logic keeps the safe ILIKE machinery without hand-written SQL:
+  #
+  #   filter do |scope, value|
+  #     scope.where(active: true).where_like({ authors: :name }, value)
+  #   end
+  module WhereLike
+    def where_like(spec, value)
+      CrudComponents::LikeSpec.apply(self, spec, value)
+    end
+  end
+end