crud_components 0.1.0

data/lib/crud_components/like_spec.rb

@@ -0,0 +1,113 @@
+module CrudComponents
+  # The declarative mini-language shared by `filter like:` and `search_in`:
+  # case-insensitive contains across columns, joining associations as needed.
+  #
+  #   :title                       own column
+  #   %i[title subtitle]           several own columns, OR-combined
+  #   { authors: %i[name email] }  join, explicit columns
+  #   :publisher                   join, delegate to Publisher's search_in
+  #   { user: :address }           nested join, delegate to Address
+  #
+  # Specs never contain SQL strings; conditions are built through Arel with
+  # LIKE wildcards escaped, so they are parameterized end to end.
+  module LikeSpec
+    # Only *delegation* hops (an association name resolved through the target's
+    # search_in) can form a cycle; explicit nesting is bounded by the literal
+    # spec. So the guard counts delegations only.
+    MAX_DELEGATIONS = 5
+
+    module_function
+
+    def apply(scope, spec, value)
+      model = scope.respond_to?(:model) ? scope.model : scope
+      entries = expand(model, spec)
+      return scope if entries.empty?
+
+      pattern = "%#{ActiveRecord::Base.sanitize_sql_like(value)}%"
+      condition = entries.map { |entry| entry.arel_condition(pattern) }.reduce(:or)
+      joins = entries.filter_map(&:join_fragment).reduce({}) { |acc, j| deep_merge(acc, j) }
+
+      return scope.where(condition) if joins.empty?
+
+      # distinct only matters once a join can multiply rows
+      scope.left_joins(joins).where(condition).distinct
+    end
+
+    Entry = Struct.new(:path, :klass, :column) do
+      # escape '\' must be explicit: sanitize_sql_like escapes with a
+      # backslash, which is not the default LIKE escape char on SQLite.
+      def arel_condition(pattern)
+        Arel::Table.new(klass.table_name)[column].matches(pattern, '\\')
+      end
+
+      def join_fragment
+        return nil if path.empty?
+
+        path.reverse.reduce(nil) { |inner, assoc| inner ? { assoc => inner } : assoc }
+      end
+    end
+
+    # Resolves a spec into flat [path, klass, column] entries, expanding
+    # association names without columns through the target's search_in spec.
+    # `delegations` counts only delegation hops (the cycle risk).
+    def expand(model, spec, path = [], delegations = 0)
+      if delegations > MAX_DELEGATIONS
+        raise DefinitionError, "search_in/like delegation more than #{MAX_DELEGATIONS} levels deep " \
+                               "starting at #{model} — most likely a delegation cycle"
+      end
+
+      Array.wrap(spec).flat_map do |item|
+        case item
+        when Symbol, String then expand_name(model, item.to_sym, path, delegations)
+        when Hash then item.flat_map { |assoc, sub| expand_assoc(model, assoc.to_sym, sub, path, delegations) }
+        else
+          raise DefinitionError, "invalid like-spec element #{item.inspect} for #{model} — " \
+                                 'use column symbols, association symbols, or { assoc => columns } hashes'
+        end
+      end
+    end
+
+    def expand_name(model, name, path, delegations)
+      if model.columns_hash.key?(name.to_s)
+        [Entry.new(path, model, name)]
+      elsif (reflection = model.reflect_on_association(name))
+        delegate(model, reflection, path, delegations)
+      else
+        raise DefinitionError, "like-spec references '#{name}', which is neither a column nor " \
+                               "an association of #{model}"
+      end
+    end
+
+    # Explicit nesting ({ assoc => columns }) — bounded by the spec, not a
+    # cycle risk, so it does not count against the delegation limit.
+    def expand_assoc(model, assoc, sub, path, delegations)
+      reflection = model.reflect_on_association(assoc)
+      raise DefinitionError, "like-spec references association '#{assoc}', " \
+                             "which #{model} does not have" unless reflection
+
+      expand(reflection.klass, sub, path + [assoc], delegations)
+    end
+
+    # Association name without columns: use the target model's search_in spec.
+    def delegate(model, reflection, path, delegations)
+      target = reflection.klass
+      target_spec = Structure.for(target).search_in_spec
+      if target_spec.nil?
+        raise DefinitionError, "cannot delegate like-spec to #{model}##{reflection.name}: " \
+                               "#{target}'s search_in is a custom block — spell the columns out, " \
+                               "e.g. { #{reflection.name}: %i[...] }"
+      end
+
+      expand(target, target_spec, path + [reflection.name], delegations + 1)
+    end
+
+    def deep_merge(left, right)
+      normalize = ->(j) { j.is_a?(Hash) ? j : { j => {} } }
+      l = normalize.call(left)
+      normalize.call(right).each do |key, value|
+        l[key] = l.key?(key) ? deep_merge(l[key], value) : value
+      end
+      l
+    end
+  end
+end

data/lib/crud_components/markup.rb

@@ -0,0 +1,36 @@
+module CrudComponents
+  # Soft-dependency markup rendering: works with whichever gem the host app
+  # already has; raises at structure build (not here) when none is present.
+  module Markup
+    module_function
+
+    def markdown(source)
+      source = source.to_s
+      if defined?(Commonmarker)
+        Commonmarker.to_html(source)
+      elsif defined?(CommonMarker)
+        CommonMarker.render_html(source)
+      elsif defined?(Redcarpet)
+        @redcarpet ||= Redcarpet::Markdown.new(Redcarpet::Render::HTML.new)
+        @redcarpet.render(source)
+      elsif defined?(Kramdown)
+        Kramdown::Document.new(source).to_html
+      else
+        source
+      end
+    end
+
+    def asciidoc(source)
+      return source.to_s unless defined?(Asciidoctor)
+
+      Asciidoctor.convert(source.to_s, safe: :safe)
+    end
+
+    def highlight_json(pretty)
+      return nil unless defined?(Rouge)
+
+      formatter = Rouge::Formatters::HTMLInline.new(Rouge::Themes::Github.new)
+      formatter.format(Rouge::Lexers::JSON.new.lex(pretty))
+    end
+  end
+end

data/lib/crud_components/model.rb

@@ -0,0 +1,33 @@
+module CrudComponents
+  # `include CrudComponents::Model` adds the crud_structure DSL. It is only
+  # needed to declare things — rendering works for any ActiveRecord model.
+  module Model
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def crud_structure(&block)
+        raise ArgumentError, 'crud_structure requires a block' unless block
+
+        if instance_variable_defined?(:@_crud_structure_block) && @_crud_structure_block
+          raise DefinitionError, "crud_structure already declared on #{self} — merge the two blocks " \
+                                 '(the second one would otherwise silently win)'
+        end
+
+        @_crud_structure_block = block
+        @_crud_structure = nil
+      end
+
+      # The strong-params permit list is {CrudComponents.permitted_attributes}
+      # (a model class works whether or not it includes this concern), so there
+      # is one way to ask for it — no model-side alias to drift from it.
+
+      # For tests and code reloading.
+      def reset_crud_structure!
+        @_crud_structure_block = nil
+        @_crud_structure = nil
+      end
+    end
+  end
+end

data/lib/crud_components/permission_context.rb

@@ -0,0 +1,62 @@
+module CrudComponents
+  # The minimal context `if:` conditions run in when there is no view around
+  # (i.e. inside Query). Exposes `can?` backed by the passed ability; without
+  # an ability nothing is permitted — safe by default.
+  class PermissionContext
+    def initialize(ability)
+      @ability = ability
+    end
+
+    def can?(action, subject)
+      return false unless @ability
+
+      @ability.can?(action, subject)
+    end
+  end
+
+  # Shared evaluation of `if:`/`editable:` options on attributes and actions. A
+  # callable may depend on the **ability** (`can?` is available in its context),
+  # the **record** (a one-arity lambda / `it`-proc receives it), or both:
+  #   if: ->(book) { can?(:edit, book) && book.published? }
+  #
+  # `recordless:` is what a *record-dependent* condition evaluates to when there
+  # is no record to decide about — a column-level / strong-params check, where
+  # the lambda can't run (it would hit `nil`). It is `true` for visibility
+  # (`if:` — show the column; the record/form surfaces still apply the
+  # per-record decision) and `false` for editability (`editable:` — a
+  # class-level permit list must not grant per-record write access, so stay
+  # safe). Ability-only conditions (Symbol, zero-arity lambda) don't need a
+  # record and are evaluated regardless.
+  module Permission
+    module_function
+
+    def permitted?(condition, model, context, record = nil, recordless: true)
+      return true if condition.nil?
+
+      case condition
+      when Symbol
+        # Sugar for can?(symbol, record) — the record being decided about — so a
+        # symbol matches the derived action check (can?(:edit, @book)). For a
+        # column-level decision there is no record, so fall back to the model
+        # class (can?(symbol, Book)).
+        context.can?(condition, record || model)
+      when Proc
+        if condition.lambda? && condition.arity.zero?
+          context.instance_exec(&condition)          # ability-only — no record needed
+        elsif record.nil?
+          recordless                                 # record-dependent, but nothing to decide on
+        else
+          context.instance_exec(record, &condition)  # receives the record; can? still in scope
+        end
+      else
+        if !condition.respond_to?(:call)
+          !!condition
+        elsif record.nil?
+          recordless
+        else
+          condition.call(record)
+        end
+      end
+    end
+  end
+end

data/lib/crud_components/presenters/actions.rb

@@ -0,0 +1,51 @@
+module CrudComponents
+  module Presenters
+    # Resolves a list of actions for a subject (record or model class) into
+    # renderable items. Derived actions are self-disabling: no permission or
+    # no resolvable route → no button, never a broken link.
+    class Actions < Base
+      Item = Struct.new(:action, :path, keyword_init: true)
+
+      def initialize(view:, subject:, structure: nil, actions: nil, owner: nil, suppress_show: false)
+        super(view: view)
+        @subject = subject
+        @model = subject.is_a?(Class) ? subject : subject.class
+        @structure = structure || Structure.for(@model)
+        @list = actions
+        @owner = owner
+        @suppress_show = suppress_show
+      end
+
+      def kind = @subject.is_a?(Class) ? :collection : :row
+
+      def items
+        @items ||= list.filter_map do |action|
+          next if action.name == :show && action.derived? && @suppress_show
+          next unless action.permitted?(permission_context, @subject)
+
+          path = RouteResolver.action_path(view, action,
+                                           record: kind == :row ? @subject : nil,
+                                           model: @model, owner: @owner)
+          next unless path
+
+          Item.new(action: action, path: path)
+        end
+      end
+
+      def any? = items.any?
+
+      # Bootstrap btn-group only renders cleanly when every child is a direct
+      # `.btn`. A non-GET action is a button_to *form*, which breaks the
+      # group's edge radii — so we only join when all actions are GET links.
+      def joinable?
+        items.all? { |item| item.action.http_method == :get }
+      end
+
+      private
+
+      def list
+        @list || @structure.fieldset_actions(@structure.default_fieldset, on: kind)
+      end
+    end
+  end
+end

data/lib/crud_components/presenters/base.rb

@@ -0,0 +1,95 @@
+module CrudComponents
+  module Presenters
+    # Presenters are the single local each partial receives — they hold the
+    # logic so the templates stay dumb markup.
+    class Base
+      attr_reader :view
+
+      def initialize(view:)
+        @view = view
+      end
+
+      def config = CrudComponents.config
+      def css = config.css
+
+      # can?-shaped context for `if:` checks; the view itself when CanCanCan
+      # (or anything can?-shaped) is around.
+      def permission_context
+        @permission_context ||= view.respond_to?(:can?) ? view : PermissionContext.new(nil)
+      end
+
+      # An ability object for Query (auto mode).
+      def ability
+        if view.respond_to?(:current_ability)
+          view.current_ability
+        elsif view.respond_to?(:can?)
+          ViewAbility.new(view)
+        end
+      end
+
+      class ViewAbility
+        def initialize(view) = @view = view
+
+        def can?(action, subject) = @view.can?(action, subject)
+      end
+
+      # Where the gem's own field partials live — used to tell a host override
+      # apart from the shipped partial (so the fast path only skips the latter).
+      GEM_VIEW_ROOT = File.expand_path('../../../app/views', __dir__).freeze
+
+      # Renders one field value: the render block (in view context, record as
+      # argument), a fast inline renderer (built-in types, no host override), or
+      # the renderer partial `crud_components/fields/_<name>`. `cell_context`
+      # (a CellContext or nil) lets value renderers build click-to-filter links;
+      # it is nil on surfaces without a query.
+      def render_cell(field, record, surface:, cell_context: nil)
+        # The render block gets the record *and* the field's value — so a block on
+        # a DynamicColumn can read its `preload:`-ed value without an `as:` partial.
+        # Extra arg is harmless for one-arg blocks/procs (Proc ignores surplus args).
+        return view.instance_exec(record, field.value(record), &field.render_block) if field.render_block
+
+        renderer = field.renderer(record) || :string
+        locals = { value: field.value(record), record: record, field: field,
+                   surface: surface, cell_context: cell_context }
+        if fast_cell?(renderer)
+          cells.render(renderer, **locals)
+        else
+          view.render("crud_components/fields/#{renderer}", **locals)
+        end
+      end
+
+      # Renders one filter control partial `crud_components/filters/_<control>`.
+      def render_filter_control(field, query, form_id: nil, compact: false, autosubmit: false)
+        view.render("crud_components/filters/#{field.filter_control}",
+                    field: field, query: query, form_id: form_id, compact: compact,
+                    autosubmit: autosubmit, param_name: query.param_name(field.name.to_s),
+                    css: css)
+      end
+
+      private
+
+      def cells
+        @cells ||= Cells.new(view)
+      end
+
+      # Fast inline path only for built-in renderers the host hasn't overridden.
+      def fast_cell?(renderer)
+        config.fast_cells && Cells.handles?(renderer) && !host_overrides_field_partial?(renderer)
+      end
+
+      # Does the resolved fields/_<renderer> partial come from the host app
+      # rather than the gem? Memoized per presenter (one table = one instance).
+      def host_overrides_field_partial?(renderer)
+        (@field_partial_override ||= {}).fetch(renderer) do
+          @field_partial_override[renderer] =
+            begin
+              template = view.lookup_context.find(renderer.to_s, ['crud_components/fields'], true)
+              !template.identifier.to_s.start_with?(GEM_VIEW_ROOT)
+            rescue StandardError
+              true # can't tell → use the (overridable) partial, never wrong output
+            end
+        end
+      end
+    end
+  end
+end

data/lib/crud_components/presenters/cell_context.rb

@@ -0,0 +1,28 @@
+module CrudComponents
+  module Presenters
+    # Passed to value renderers so a cell can offer click-to-filter (enum
+    # badges, boolean icons) — respecting the active query's fieldset
+    # whitelist and param_prefix. Nil on surfaces without a query (the record
+    # page, static collections), so renderers must null-check it.
+    class CellContext
+      def initialize(view:, query:)
+        @view = view
+        @query = query
+      end
+
+      # Is this field one the current query would actually act on?
+      def filterable?(field)
+        @query.filter_fields.include?(field)
+      end
+
+      # A URL that adds (or replaces) this field's filter, keeping every other
+      # active param — prefixed correctly for multi-collection pages.
+      def filter_url(field, value)
+        params = @view.request.query_parameters.merge(
+          @query.param_name(field.name.to_s) => value.to_s
+        )
+        "#{@view.request.path}?#{params.to_query}"
+      end
+    end
+  end
+end

data/lib/crud_components/presenters/cells.rb

@@ -0,0 +1,160 @@
+module CrudComponents
+  module Presenters
+    # Fast inline cell renderers — Ruby equivalents of the
+    # crud_components/fields/_*.html.erb partials, built with the tag/link
+    # helpers so a big table skips one partial render per cell (the dominant
+    # cost: a partial cell is ~200µs, this is ~10–20µs). Output matches the
+    # partials (same elements, classes, links, escaping).
+    #
+    # Used only when the renderer is one of these built-ins AND the host hasn't
+    # overridden its partial (Base#render_cell checks both). markdown/asciidoc
+    # and any custom `as:` renderer keep using their partials.
+    class Cells
+      BUILTINS = %i[string text number boolean date datetime enum
+                    association association_list json attachment].freeze
+
+      def self.handles?(renderer) = BUILTINS.include?(renderer)
+
+      def initialize(view)
+        @v = view
+      end
+
+      def render(renderer, value:, record:, field:, surface:, cell_context:)
+        public_send(renderer, value, record, field, surface, cell_context)
+      end
+
+      def string(value, _record, _field, surface, _cc)
+        return dash if blank?(value)
+
+        surface == :collection ? @v.truncate(value.to_s, length: 120) : esc(value)
+      end
+
+      def text(value, _record, _field, surface, _cc)
+        return dash if blank?(value)
+        return @v.truncate(value.to_s, length: 120) if surface == :collection
+
+        @v.tag.div(esc(value), class: 'crud-text', style: 'white-space: pre-line')
+      end
+
+      def number(value, _record, field, _surface, _cc)
+        return dash if value.nil?
+
+        o = field.renderer_options
+        formatted = o[:digits] ? @v.number_with_precision(value, precision: o[:digits], delimiter: ',')
+                               : @v.number_with_delimiter(value)
+        o[:unit] ? @v.safe_join([formatted, " #{o[:unit]}"]) : @v.safe_join([formatted])
+      end
+
+      def boolean(value, _record, field, _surface, cc)
+        return dash if value.nil?
+
+        icon = @v.tag.span(value ? '✓' : '✗', class: value ? css.boolean_true : css.boolean_false)
+        filter_link(cc, field, value, icon) { icon }
+      end
+
+      def date(value, _record, _field, _surface, _cc)
+        value.nil? ? dash : esc(@v.l(value.to_date))
+      end
+
+      def datetime(value, _record, _field, _surface, _cc)
+        value.nil? ? dash : esc(@v.l(value, format: :short))
+      end
+
+      def enum(value, _record, field, _surface, cc)
+        return dash if value.nil?
+
+        label = field.respond_to?(:human_value) ? field.human_value(value) : value
+        badge = @v.tag.span(label, class: css.badge)
+        filter_link(cc, field, value, badge,
+                    title: @v.t('crud_components.filter_by', name: label, default: "Filter by #{label}")) { badge }
+      end
+
+      def association(value, record, field, _surface, _cc)
+        return dash if value.nil?
+
+        label = @v.crud_association_label(field, value)
+        path = @v.crud_record_path(value, owner: record)
+        path ? @v.link_to(label, path, data: { turbo_action: 'advance' }) : esc(label)
+      end
+
+      def association_list(value, record, field, surface, _cc)
+        items = value.to_a
+        return dash if items.empty?
+
+        shown = surface == :collection ? items.first(3) : items
+        links = @v.safe_join(shown.map { |item| association_item(field, item, record) }, ', ')
+        return links if items.size <= shown.size
+
+        more = @v.t('crud_components.more', count: items.size - shown.size, default: '+%{count} more')
+        index_path = @v.crud_association_index_path(record, field)
+        more_html = index_path ? @v.link_to(more, index_path, class: css.muted, data: { turbo_action: 'advance' })
+                               : @v.tag.span(more, class: css.muted)
+        @v.safe_join([links, ' ', more_html])
+      end
+
+      def json(value, _record, _field, surface, _cc)
+        return dash if value.nil?
+
+        pretty = value.is_a?(String) ? value : JSON.pretty_generate(value)
+        pretty = @v.truncate(pretty, length: 120) if surface == :collection
+        highlighted = CrudComponents::Markup.highlight_json(pretty)
+        inner = highlighted ? @v.raw(highlighted) : pretty
+        @v.tag.pre(@v.tag.code(inner), class: 'crud-json mb-0')
+      end
+
+      def attachment(value, _record, field, surface, _cc)
+        return dash unless value.respond_to?(:attached?) && value.attached?
+
+        if field.respond_to?(:many?) && field.many?
+          thumbs = value.map { |a| attachment_thumb(a, surface) }
+          @v.tag.span(@v.safe_join(thumbs), class: 'd-inline-flex flex-wrap gap-1')
+        else
+          attachment_thumb(value, surface)
+        end
+      end
+
+      private
+
+      def config = CrudComponents.config
+      def css = config.css
+
+      def blank?(value) = value.nil? || value == ''
+
+      # The muted em-dash shown for a nil/blank value.
+      def dash = @v.tag.span('—', class: css.muted)
+
+      # html_escape — matches ERB `<%= value %>` (passes SafeBuffers through).
+      def esc(value) = ERB::Util.html_escape(value)
+
+      # Wrap `content` in a click-to-filter link when the query would act on the
+      # field, else yield the bare content (the no-JS / no-query path).
+      def filter_link(cell_context, field, value, content, **link_options)
+        return yield unless cell_context&.filterable?(field)
+
+        @v.link_to(content, cell_context.filter_url(field, value),
+                   class: css.filter_link, data: { turbo_action: 'advance' }, **link_options)
+      end
+
+      def association_item(field, item, owner)
+        label = @v.crud_association_label(field, item)
+        path = @v.crud_record_path(item, owner: owner)
+        path ? @v.link_to(label, path, data: { turbo_action: 'advance' }) : label.to_s
+      end
+
+      def attachment_thumb(attachment, surface)
+        style = surface == :record ? 'max-height: 16rem' : 'max-height: 2.5rem'
+        if attachment.image?
+          @v.image_tag(attachment, class: 'rounded crud-image', style: style)
+        elsif attachment.previewable? && CrudComponents.previews_available?
+          @v.image_tag(attachment.preview(resize_to_limit: [600, 600]), class: 'rounded crud-image', style: style)
+        else
+          @v.link_to(@v.rails_blob_path(attachment, disposition: 'attachment'),
+                     class: 'd-inline-flex align-items-center gap-1 text-decoration-none') do
+            @v.safe_join([@v.tag.i('', class: "#{css.icon_prefix}#{@v.crud_file_icon(attachment.filename)}"),
+                          @v.tag.span(attachment.filename)])
+          end
+        end
+      end
+    end
+  end
+end