crud_components 0.1.0

data/lib/crud_components/builder.rb

@@ -0,0 +1,246 @@
+module CrudComponents
+  # The DSL evaluated inside `crud_structure do … end`. Its instance methods —
+  # {#attribute}, {#attributes}, {#action}, {#fieldset}, {#label},
+  # {#identify_by}, {#search_in} — are the public declaration API; the block
+  # runs against a Builder instance. It only collects declarations; {Structure}
+  # resolves and validates them against what Rails already knows.
+  #
+  # @example
+  #   class Book < ApplicationRecord
+  #     include CrudComponents::Model
+  #     crud_structure do
+  #       label :title
+  #       identify_by :slug
+  #       attribute :title  { filter :title; sort :title }
+  #       fieldset :index, %i[title author], actions: %i[edit destroy]
+  #     end
+  #   end
+  class Builder
+    attr_reader :model, :declarations, :actions, :fieldsets,
+                :label_decl, :identify_by_decl, :search_decl,
+                :label_preload_decl, :preload_decl, :icon_decl
+
+    # @param model [Class] the ActiveRecord model being described.
+    # @yield the `crud_structure` block, evaluated against this Builder.
+    # @api private
+    def initialize(model, &block)
+      @model = model
+      @declarations = {}
+      @actions = {}
+      @fieldsets = {}
+      instance_exec(&block)
+    end
+
+    # How a record is titled (links, headings). Give a method name or a block.
+    # @param method [Symbol, nil] a method on the record returning its label.
+    # @param preload [Array<Symbol>, Symbol, nil] associations the label reaches
+    #   into (`label :full_title, preload: %i[customer training]`). They're
+    #   eager-loaded automatically whenever this model is shown as another
+    #   model's association column — declare once, no N+1 anywhere.
+    # @yield [record] computes the label; receives the record.
+    # @return [void]
+    def label(method = nil, preload: nil, &block)
+      raise DefinitionError, "#{model}: label declared twice" if defined?(@label_decl) && @label_decl
+      raise DefinitionError, "#{model}: label takes a method name or a block, not both" if method && block
+      raise DefinitionError, "#{model}: label needs a method name or a block" unless method || block
+
+      @label_decl = block || method.to_sym
+      @label_preload_decl = preload_list(preload)
+    end
+
+    # Associations to eager-load whenever this model is rendered (as a row or as
+    # another model's association cell) — for label/render dependencies the gem
+    # can't infer. Additive with `label …, preload:`; declare more than once to
+    # accumulate. e.g. `preload :customer, :training`.
+    # @param names [Array<Symbol>] association names (nested hashes allowed).
+    # @return [void]
+    def preload(*names)
+      @preload_decl = (@preload_decl || []) + names
+    end
+
+    # The column used in URLs (`to_param`) and to resolve a bulk selection.
+    # @param column [Symbol] e.g. `:slug`. Defaults to `:id` when undeclared.
+    # @return [void]
+    def identify_by(column)
+      raise DefinitionError, "#{model}: identify_by declared twice" if @identify_by_decl
+
+      @identify_by_decl = column.to_sym
+    end
+
+    # The icon (no library prefix — paired with `css.icon_prefix`) that badges
+    # this model wherever it appears: column-picker groups, association links,
+    # path-column cells. Overrides the name-based guess in `config.model_icons`.
+    # @param name [String, Symbol] a Bootstrap-icon name, e.g. `'building'`.
+    # @return [void]
+    def icon(name)
+      raise DefinitionError, "#{model}: icon declared twice" if @icon_decl
+
+      @icon_decl = name.to_s
+    end
+
+    # The columns/associations full-text search (`?q=`) spans, in the same
+    # mini-language as the positional `filter` spec.
+    # @param spec [Array<Symbol, Hash>] e.g. `:title, authors: %i[name email]`.
+    # @yield [scope, term] a custom search; receives the scope and the term.
+    # @return [void]
+    def search_in(*spec, &block)
+      raise DefinitionError, "#{model}: search_in declared twice" if @search_decl
+      raise DefinitionError, "#{model}: search_in takes a spec or a block, not both" if spec.any? && block
+      raise DefinitionError, "#{model}: search_in needs a spec or a block" if spec.empty? && !block
+
+      @search_decl = block || spec
+    end
+
+    # Declare (or refine) one attribute. The optional block sets facets: a
+    # one-arity block is the render facet; a zero-arity block declares
+    # `filter`/`sort`/`render` (see {FacetCollector}).
+    # @param name [Symbol] the attribute/column/association name.
+    # @param options [Hash] e.g. `as:` (renderer), `form_as:`, `if:`,
+    #   `editable:`, `label:`, `null:`.
+    # @yield optional facet block.
+    # @return [void]
+    def attribute(name, **options, &block)
+      name = name.to_sym
+      if @declarations.key?(name)
+        raise DefinitionError, "#{model}: attribute :#{name} declared twice — merge the declarations"
+      end
+      if RESERVED_PARAMS.include?(name.to_s)
+        raise DefinitionError, "#{model}: :#{name} is a reserved param name " \
+                               "(#{RESERVED_PARAMS.join(', ')}) and cannot be a field"
+      end
+
+      @declarations[name] = { options: options, facets: parse_facets(name, block) }
+    end
+
+    # Declare several attributes that share the same options.
+    # @param names [Array<Symbol>] one or more attribute names.
+    # @param options [Hash] applied to each (see {#attribute}).
+    # @return [void]
+    def attributes(*names, **options)
+      raise DefinitionError, "#{model}: attributes needs at least one name" if names.empty?
+
+      names.each { |name| attribute(name, **options) }
+    end
+
+    # Declare a custom action button. The block returns its path, evaluated in
+    # the view context (and given the record for a row action).
+    # @param name [Symbol] the action name (also the i18n/route key).
+    # @param options [Hash] `on:` (`:row`/`:collection`/`:selection`), `icon:`,
+    #   `title:`, `class:`, `confirm:`, `method:`, `if:`.
+    # @yield the path block.
+    # @return [void]
+    def action(name, **options, &path_block)
+      name = name.to_sym
+      raise DefinitionError, "#{model}: action :#{name} declared twice" if @actions.key?(name)
+
+      @actions[name] = Action.new(name, **options, &path_block)
+    end
+
+    # A named selection of fields + actions for a surface (index/show/form/…).
+    # @param name [Symbol] the fieldset name.
+    # @param fields [Array<Symbol>, :all] which fields, in order (`:all` = every
+    #   declared/derived field).
+    # @param actions [Array<Symbol>, nil] curate the actions (per kind); nil keeps
+    #   the derived defaults.
+    # @param filters [Array<Symbol>, nil] filterable fields beyond the visible ones.
+    # @return [void]
+    def fieldset(name, fields = :all, actions: nil, filters: nil)
+      name = name.to_sym
+      raise DefinitionError, "#{model}: fieldset :#{name} declared twice" if @fieldsets.key?(name)
+
+      @fieldsets[name] = Fieldset.new(name, fields, actions: actions, filters: filters)
+    end
+
+    private
+
+    # Normalize a preload value to an array of includes-specs, leaving a nested
+    # hash (`{ customer: :company }`) intact (Array() would split it).
+    def preload_list(value)
+      case value
+      when nil then []
+      when Array then value
+      else [value]
+      end
+    end
+
+    # Bare block taking the record (arity 1, including `it`/`_1`) is the
+    # render facet; a zero-arity block declares facets.
+    def parse_facets(name, block)
+      return {} unless block
+      return { render: block } unless block.arity.zero?
+
+      FacetCollector.new(model, name).collect(&block)
+    end
+
+    class FacetCollector
+      NONE = Object.new
+
+      def initialize(model, name)
+        @model = model
+        @name = name
+        @facets = {}
+      end
+
+      def collect(&block)
+        instance_exec(&block)
+        @facets
+      end
+
+      def render(*args, &block)
+        once!(:render)
+        unless block && args.empty?
+          raise DefinitionError, "#{where}: the render facet takes only a block — " \
+                                 'named renderers are picked with the as: keyword on attribute'
+        end
+
+        @facets[:render] = block
+      end
+
+      # A like-spec passed positionally (same mini-language as `search_in`):
+      #   filter :title                       own column
+      #   filter :title, :subtitle            several columns, OR-combined
+      #   filter authors: %i[name email]      join, explicit columns
+      #   filter :publisher                   join, delegate to the target's search_in
+      #   filter :title, { authors: :name }   mixed
+      # plus `filter false` (off) and `filter { |scope, value| ... }` (block).
+      def filter(*spec, **assoc, &block)
+        once!(:filter)
+        spec << assoc unless assoc.empty?
+
+        case
+        when spec == [false] && !block then @facets[:filter] = false
+        when block && spec.empty? then @facets[:filter] = block
+        when !spec.empty? && !block then @facets[:filter] = spec.size == 1 ? spec.first : spec
+        else
+          raise DefinitionError, "#{where}: filter takes `false`, a column/association spec " \
+                                 '(e.g. `filter :title` or `filter authors: %i[name email]`), or a block'
+        end
+      end
+
+      def sort(arg = NONE, &block)
+        once!(:sort)
+        case
+        when arg == false && !block then @facets[:sort] = false
+        when block && arg.equal?(NONE) then @facets[:sort] = block
+        when arg.is_a?(Symbol) && !block then @facets[:sort] = arg
+        else
+          raise DefinitionError, "#{where}: sort takes `false`, an own-column symbol, or a block"
+        end
+      end
+
+      def method_missing(name, *)
+        raise DefinitionError, "#{where}: unknown facet '#{name}' — facets are render, filter and sort"
+      end
+
+      def respond_to_missing?(_name, _include_private = false) = true
+
+      private
+
+      def once!(facet)
+        raise DefinitionError, "#{where}: #{facet} facet declared twice" if @facets.key?(facet)
+      end
+
+      def where = "#{@model} attribute :#{@name}"
+    end
+  end
+end

data/lib/crud_components/config.rb

@@ -0,0 +1,128 @@
+require 'active_support/ordered_options'
+
+module CrudComponents
+  class Config
+    # When changed, add it to initializer.rb
+    DEFAULT_CSS = {
+      table: 'table align-middle',
+      thead: '',
+      toolbar: 'd-flex justify-content-between align-items-center gap-2 mb-2',
+      search_form: 'd-flex gap-1',
+      filter_row: 'crud-filter-row',
+      sort_link: 'text-reset text-decoration-none',
+      record_link: 'fw-medium',
+      filter_link: 'text-reset text-decoration-none',
+      actions_cell: 'text-end',
+      button_group: 'btn-group btn-group-sm',
+      button: 'btn btn-sm btn-outline-secondary',
+      button_primary: 'btn btn-sm btn-primary',
+      button_danger: 'btn btn-sm btn-outline-danger',
+      pagination: 'pagination pagination-sm',
+      badge: 'badge text-bg-secondary',
+      badge_muted: 'badge text-bg-light',
+      input: 'form-control',
+      input_sm: 'form-control form-control-sm',
+      # named *_input to avoid OrderedOptions#select (Hash#select) collisions
+      select_input: 'form-select',
+      select_input_sm: 'form-select form-select-sm',
+      form_label: 'form-label',
+      form_summary: 'alert alert-danger',
+      filter_grid: 'row row-cols-1 g-2',
+      input_group: 'input-group flex-nowrap',
+      boolean_true: 'text-success',
+      boolean_false: 'text-danger',
+      muted: 'text-muted',
+      # icon font base + name prefix; built-in icon names are Bootstrap Icons.
+      # Swap the whole library here, e.g. 'fa fa-' for Font Awesome.
+      icon_prefix: 'bi bi-',
+      dl: 'row',
+      dt: 'col-sm-3',
+      dd: 'col-sm-9'
+    }.freeze
+
+    # Icon name (no library prefix — paired with css.icon_prefix) for each
+    # derived action. Override a glyph, or set one to nil for no icon:
+    #   config.action_icons[:destroy] = 'trash-fill'
+    DEFAULT_ACTION_ICONS = {
+      new: 'plus-lg', show: 'eye', edit: 'pencil', destroy: 'trash'
+    }.freeze
+
+    # Map of file extension → icon name (no library prefix — paired with
+    # css.icon_prefix) for the attachment icon fallback; an unmapped extension
+    # uses file_fallback_icon. Full names (not a prefix) so non-conforming ones
+    # fit too — e.g. yaml→filetype-yml, zip→file-earmark-zip. Bootstrap Icons'
+    # whole `filetype-*` family is included; override/extend per your set.
+    DEFAULT_FILE_ICONS = %w[
+      aac ai bmp cs css csv doc docx exe gif heic html java jpg js json jsx key
+      m4p md mdx mov mp3 mp4 otf pdf php png ppt pptx psd py raw rb sass scss sh
+      sql svg tiff tsx ttf txt wav woff xls xlsx xml yml
+    ].to_h { |ext| [ext, "filetype-#{ext}"] }.merge(
+      'yaml' => 'filetype-yml',          # alias of yml
+      'jpeg' => 'filetype-jpg',          # alias of jpg
+      'zip'  => 'file-earmark-zip'       # no filetype- glyph exists
+    ).freeze
+
+    # A guessed icon (no library prefix — paired with css.icon_prefix) per model,
+    # keyed by the model's singular underscored name (`model_name.element`, so
+    # `Admin::User` → "user"). Used wherever a model is badged: column-picker
+    # groups, association links, path-column cells. A model can override with
+    # `icon 'building'` in its `crud_structure`; an unmapped model with no
+    # declaration falls back to model_fallback_icon (nil = no icon). Extend it:
+    #   config.model_icons['widget'] = 'box-seam'
+    DEFAULT_MODEL_ICONS = {
+      'user' => 'person', 'person' => 'person', 'author' => 'person',
+      'member' => 'person', 'customer' => 'person', 'contact' => 'person-lines-fill',
+      'account' => 'person-circle', 'profile' => 'person-badge', 'admin' => 'person-gear',
+      'participant' => 'person', 'student' => 'mortarboard', 'teacher' => 'easel',
+      'team' => 'people', 'group' => 'people', 'role' => 'person-badge',
+      'organization' => 'building', 'company' => 'building', 'publisher' => 'building',
+      'department' => 'building', 'vendor' => 'shop', 'supplier' => 'shop',
+      'store' => 'shop', 'shop' => 'shop',
+      'book' => 'book', 'article' => 'file-earmark-text', 'post' => 'file-earmark-post',
+      'page' => 'file-earmark', 'document' => 'file-earmark', 'file' => 'file-earmark',
+      'attachment' => 'paperclip', 'report' => 'file-earmark-bar-graph',
+      'order' => 'cart', 'cart' => 'cart', 'product' => 'box-seam', 'item' => 'box',
+      'invoice' => 'receipt', 'receipt' => 'receipt', 'payment' => 'credit-card',
+      'transaction' => 'credit-card', 'subscription' => 'arrow-repeat',
+      'comment' => 'chat', 'message' => 'chat-dots', 'review' => 'star', 'rating' => 'star',
+      'notification' => 'bell', 'email' => 'envelope', 'mail' => 'envelope',
+      'tag' => 'tag', 'label' => 'tag', 'category' => 'collection', 'genre' => 'collection',
+      'project' => 'kanban', 'task' => 'check2-square', 'todo' => 'check2-square',
+      'ticket' => 'ticket', 'event' => 'calendar-event', 'appointment' => 'calendar-check',
+      'booking' => 'calendar-check', 'course' => 'mortarboard', 'lesson' => 'easel',
+      'address' => 'geo-alt', 'location' => 'geo-alt', 'place' => 'geo-alt',
+      'country' => 'globe', 'city' => 'geo-alt',
+      'image' => 'image', 'photo' => 'image', 'video' => 'camera-video', 'media' => 'collection-play',
+      'setting' => 'gear', 'permission' => 'shield-lock'
+    }.freeze
+
+    attr_accessor :select_limit, :group_collapse_threshold, :action_icons,
+                  :file_icons, :file_fallback_icon, :fast_cells, :max_path_depth,
+                  :model_icons, :model_fallback_icon
+    attr_reader :css
+
+    def initialize
+      @select_limit = 250
+      # Grouped collections open every group when the total row count is below
+      # this, and only the first group above it (the rest collapse).
+      @group_collapse_threshold = 50
+      # How many associations a path column (e.g. `publisher.country.name`) may
+      # chain through. A guard rail against runaway joins — raise it if you have
+      # legitimately deeper paths. (Crossing more than one *to-many* association
+      # is forbidden regardless of this, since that yields a list-of-lists.)
+      @max_path_depth = 3
+      # Render built-in cell types inline (in Ruby) instead of one partial per
+      # cell — an order of magnitude faster on big tables. A host override of a
+      # field partial is still honored; set false to force partials everywhere.
+      @fast_cells = true
+      @css = ActiveSupport::OrderedOptions.new.merge!(DEFAULT_CSS)
+      @action_icons = DEFAULT_ACTION_ICONS.dup
+      @file_icons = DEFAULT_FILE_ICONS.dup
+      @file_fallback_icon = 'file-earmark-text'
+      @model_icons = DEFAULT_MODEL_ICONS.dup
+      # No generic badge for an unmapped, undeclared model — set a glyph here to
+      # icon every model (e.g. 'box') if you prefer.
+      @model_fallback_icon = nil
+    end
+  end
+end

data/lib/crud_components/dynamic_column.rb

@@ -0,0 +1,68 @@
+module CrudComponents
+  # A column whose data lives *outside* the model's own table — a user-defined
+  # property kept in a separate store (definition + value tables, a JSONB blob,
+  # an external API). The model knows nothing about it; you build one per request
+  # from wherever your custom properties live and hand it to `crud_collection`
+  # via `extra_columns:`.
+  #
+  #   CrudComponents::DynamicColumn.new(:priority,
+  #     label: 'Priority', as: :number,
+  #     if:      -> { can?(:read, prop) },           # same gate as a field's if:
+  #     preload: ->(records) {                       # batch-load once per page (no N+1)
+  #       PropertyValue.where(definition: prop, subject: records).index_by(&:subject_id)
+  #     },
+  #     sort:   ->(scope, dir) { ... },              # optional — omit for display-only
+  #     filter: ->(scope, value) { ... }) { |record, loaded| loaded[record.id]&.value }
+  #
+  # The block is the value resolver: `|record|` or `|record, loaded|`, where
+  # `loaded` is whatever `preload:` returned. It returns a plain value that the
+  # `as:` renderer (or, with no `as:`, the value's type) displays — exactly like
+  # a computed field. `filter:`/`sort:` are the same facet blocks the DSL takes;
+  # supply them only when the data is reachable in SQL, otherwise the column is
+  # display-only and never reaches the query layer.
+  #
+  # A dynamic column often *is* a domain object (a mail, a resource), so its
+  # header can carry a link and its own bulk actions, rendered in the `<th>`:
+  #
+  #   CrudComponents::DynamicColumn.new(:mail_42,
+  #     label:  'Welcome mail',
+  #     header: -> { link_to mail.name, mail },             # HTML-safe String or a view-context block
+  #     header_actions: [                                   # the same Action API as row/collection actions
+  #       CrudComponents::Action.new(:send_all, icon: 'send', method: :post) { send_all_path(mail) },
+  #       CrudComponents::Action.new(:unschedule_all, method: :post) { unschedule_all_path(mail) }
+  #     ],
+  #     preload: ->(records) { ... }) { |record, loaded| loaded[record.id] }
+  #
+  # `header:` replaces the plain `human_name` text (a String is rendered as-is —
+  # mark it `html_safe` if it carries markup; a block is `instance_exec`ed in the
+  # view, so it may call `link_to` and friends). `header_actions:` renders after
+  # the header; an `on: :selection` action acts on the ticked rows (it submits the
+  # shared select-form, so its path closes over the column's object × the
+  # selection), while any other action renders as a plain link/button.
+  #
+  # header:/header_actions: are not consumed here — they ride along in `options`
+  # and are read off the field by Fields::Base, exactly like a declared
+  # attribute's `attribute :x, header_actions: […]`.
+  class DynamicColumn
+    attr_reader :name, :options, :facets, :preload_block, :value_block
+
+    # Keys consumed here; everything else (as:, if:, label:, header:,
+    # header_actions:, unit:, digits:, …) flows into `options` just like a
+    # declared attribute's options.
+    FACET_KEYS = %i[filter sort render].freeze
+
+    def initialize(name, preload: nil, **opts, &value_block)
+      @name = name.to_sym
+      @value_block = value_block
+      @preload_block = preload
+      @facets = opts.slice(*FACET_KEYS).compact
+      @options = opts.except(*FACET_KEYS)
+    end
+
+    # A request-scoped field bound to `model`. Not memoized on the Structure, so
+    # it may carry the per-request value cache (see Fields::DynamicField).
+    def to_field(model)
+      Fields::DynamicField.new(self, model)
+    end
+  end
+end

data/lib/crud_components/engine.rb

@@ -0,0 +1,25 @@
+require 'simple_form'   # form rendering delegates to simple_form (a runtime dep)
+require_relative 'route_resolver'
+require_relative 'markup'
+require_relative 'presenters/base'
+require_relative 'presenters/column_selection'
+require_relative 'presenters/cells'
+require_relative 'presenters/cell_context'
+require_relative 'presenters/actions'
+require_relative 'presenters/collection'
+require_relative 'presenters/record'
+require_relative 'presenters/filter'
+require_relative 'presenters/form'
+require_relative 'helpers'
+
+module CrudComponents
+  # Dependency-free engine: adds the gem's view path (partials under
+  # app/views/crud_components/), the helpers, and the generators.
+  class Engine < ::Rails::Engine
+    initializer 'crud_components.helpers' do
+      ActiveSupport.on_load(:action_view) do
+        include CrudComponents::Helpers
+      end
+    end
+  end
+end

data/lib/crud_components/errors.rb

@@ -0,0 +1,9 @@
+module CrudComponents
+  class Error < StandardError; end
+
+  # DSL misuse, detected when the structure is built (boot / first use).
+  class DefinitionError < Error; end
+
+  # An explicitly requested fieldset that the model does not declare.
+  class UnknownFieldsetError < Error; end
+end

data/lib/crud_components/fields/attachment_field.rb

@@ -0,0 +1,22 @@
+module CrudComponents
+  module Fields
+    # Active Storage attachment: rendered by content type — image inline,
+    # previewable (e.g. PDF) as a preview, otherwise an icon + filename link.
+    class AttachmentField < Base
+      def default_renderer = :attachment
+
+      def many?
+        @many ||= model.reflect_on_attachment(name).macro == :has_many_attached
+      end
+
+      def eager_load
+        [many? ? :"#{name}_attachments" : :"#{name}_attachment", *declared_preloads]
+      end
+
+      # ── forms ────────────────────────────────────────────────────────────
+      def default_editable? = true
+      def form_control = :file
+      def permit_param = many? ? { name => [] } : name
+    end
+  end
+end