crud_components 0.2.0 → 0.3.0

data/lib/crud_components/admin/dependents.rb

@@ -0,0 +1,138 @@
+module CrudComponents
+  module Admin
+    # What else goes when a record is destroyed: the associations that declare a
+    # `dependent:` behaviour, counted, plus the ones that would block it.
+    class Dependents
+      DESTROYING = %i[destroy destroy_async delete_all].freeze
+      BLOCKING = %i[restrict_with_error restrict_with_exception].freeze
+
+      # How many of an item's records the confirmation page names.
+      PREVIEW = 10
+
+      Item = Struct.new(:name, :model, :count, :behavior, :cascades, :records, keyword_init: true) do
+        def destroys? = DESTROYING.include?(behavior)
+
+        # What is left over once the named ones are shown.
+        def unnamed = count - Array(records).size
+
+        def blocks? = BLOCKING.include?(behavior) && count.positive?
+
+        def nullifies? = behavior == :nullify
+
+        def human_name
+          human = model ? model.model_name.human(count: count) : name.to_s.humanize
+          count == 1 ? human : human.pluralize(I18n.locale)
+        end
+      end
+
+      # The same overview for several records at once: one item per association,
+      # counts summed, names taken across the selection.
+      class Selection
+        def initialize(records) = @records = records
+
+        def items
+          @items ||= @records.flat_map { |record| Dependents.new(record).items }
+                             .group_by(&:name).map { |name, items| merged(name, items) }
+        end
+
+        def blockers = items.select(&:blocks?)
+
+        private
+
+        def merged(name, items)
+          Item.new(name: name, model: items.first.model, behavior: items.first.behavior,
+                   count: items.sum(&:count), cascades: items.any?(&:cascades),
+                   records: items.flat_map(&:records).first(PREVIEW))
+        end
+      end
+
+      def self.for(record) = new(record).items
+
+      def initialize(record)
+        @record = record
+      end
+
+      def items
+        @items ||= (association_items + attachment_items).reject { |item| item.count.zero? }
+      end
+
+      # Anything that blocks the delete outright.
+      def blockers = items.select(&:blocks?)
+
+      private
+
+      attr_reader :record
+
+      def association_items
+        support = Structure.for(record.class).attachment_support_names
+
+        record.class.reflect_on_all_associations.filter_map do |reflection|
+          behavior = reflection.options[:dependent]&.to_sym
+          next unless behavior
+          next if support.include?(reflection.name)
+
+          Item.new(name: reflection.name, model: target_of(reflection), count: count_for(reflection),
+                   behavior: behavior, cascades: cascades?(reflection), records: preview_of(reflection))
+        end
+      end
+
+      # Attached files go with the record; they are not an association the app
+      # declared, so they are counted separately.
+      def attachment_items
+        return [] unless record.class.respond_to?(:reflect_on_all_attachments)
+
+        record.class.reflect_on_all_attachments.map do |reflection|
+          attachments = attachments_of(record.public_send(reflection.name))
+          Item.new(name: reflection.name, model: nil, count: attachments.size, behavior: :destroy,
+                   cascades: false, records: attachments.first(PREVIEW))
+        end
+      end
+
+      # The attachments behind `has_one_attached` / `has_many_attached`, each of
+      # which names a file the delete takes.
+      def attachments_of(attached)
+        return attached.attachments.to_a if attached.respond_to?(:attachments)
+
+        attached.attached? ? [attached.attachment] : []
+      rescue ActiveRecord::ActiveRecordError
+        []
+      end
+
+      def target_of(reflection)
+        reflection.klass
+      rescue NameError
+        nil
+      end
+
+      def count_for(reflection)
+        value = record.public_send(reflection.name)
+        return value.count if value.respond_to?(:count)
+
+        value.nil? ? 0 : 1
+      rescue ActiveRecord::ActiveRecordError, NameError
+        0
+      end
+
+      # The first records the delete would reach, for naming them.
+      def preview_of(reflection)
+        value = record.public_send(reflection.name)
+        return Array(value) unless value.respond_to?(:limit)
+
+        value.limit(PREVIEW).to_a
+      rescue ActiveRecord::ActiveRecordError, NameError
+        []
+      end
+
+      # Whether the target itself destroys further records — the count shown is
+      # then the first level only.
+      def cascades?(reflection)
+        target = target_of(reflection)
+        return false unless target && DESTROYING.include?(reflection.options[:dependent]&.to_sym)
+
+        target.reflect_on_all_associations.any? do |nested|
+          DESTROYING.include?(nested.options[:dependent]&.to_sym)
+        end
+      end
+    end
+  end
+end

data/lib/crud_components/admin/engine.rb

@@ -0,0 +1,22 @@
+module CrudComponents
+  module Admin
+    # The mountable admin. Does nothing until an app mounts it:
+    #
+    #   mount CrudComponents::Admin::Engine => '/admin'
+    #
+    # Its routes are drawn from {Registry}, one `resources` block per model, all
+    # pointing at ResourcesController.
+    class Engine < ::Rails::Engine
+      isolate_namespace CrudComponents::Admin
+
+      # The gem root already holds app/ and config/locales; only the route file
+      # is admin-specific, so point at it rather than at config/routes.rb (which
+      # the non-isolated main engine would draw into the host application).
+      paths['config/routes.rb'] = 'lib/crud_components/admin/routes.rb'
+
+      config.after_initialize do |app|
+        app.config.to_prepare { CrudComponents::Admin.registry.reload! }
+      end
+    end
+  end
+end

data/lib/crud_components/admin/entry.rb

@@ -0,0 +1,123 @@
+module CrudComponents
+  module Admin
+    # One registered model: everything the route drawer, the sidebar and the
+    # controller need, resolved once.
+    class Entry
+      # The seven RESTful actions, in the order routes are drawn.
+      ALL_ACTIONS = %i[index show new create edit update destroy].freeze
+
+      # Actions a member route needs a primary key for.
+      MEMBER_ACTIONS = %i[show edit update destroy].freeze
+
+      # `new` without `create` (or `edit` without `update`) is a form that can't
+      # submit, so each implies the other.
+      ACTION_PAIRS = { new: :create, create: :new, edit: :update, update: :edit }.freeze
+
+      attr_reader :model, :options
+
+      def initialize(model, options = {})
+        @model = model
+        @options = options || {}
+      end
+
+      def name = model.name
+
+      def route_key = model.model_name.route_key
+
+      def singular_route_key = model.model_name.singular_route_key
+
+      # The column a URL segment is matched against, from `identify_by`.
+      def param_key = structure.identify_by
+
+      def label = options[:label]&.to_s || model.model_name.human(count: 2)
+
+      def icon = structure.icon
+
+      # nil for a top-level model; the namespace for `Catalog::Book`.
+      def group
+        return options[:group].to_s if options[:group]
+
+        namespace = name.to_s.deconstantize
+        namespace.presence&.demodulize&.underscore&.humanize
+      end
+
+      # The declared group as a locale-independent key: what the heading is
+      # looked up under, and what `config.groups` orders by.
+      def self.group_key(value) = value.to_s.parameterize.underscore.presence
+
+      def group_key = self.class.group_key(group)
+
+      # The sidebar heading: translated when the app says so, else as declared.
+      def group_label
+        return nil unless group
+
+        I18n.t("crud_components.admin.groups.#{group_key}", default: group)
+      end
+
+      def actions
+        @actions ||= resolve_actions
+      end
+
+      def allows?(action) = actions.include?(action.to_sym)
+
+      # The base relation the admin renders, before filtering and sorting.
+      def scope
+        base = model.all
+        callable = options[:scope]
+        return base unless callable
+
+        callable.arity.zero? ? base.instance_exec(&callable) : callable.call(base)
+      end
+
+      # The fieldset the admin renders: `:admin` when declared, else every field.
+      def fieldset
+        return options[:fieldset].to_sym if options[:fieldset]
+
+        structure.declared_fieldset_names.include?(:admin) ? :admin : :default
+      end
+
+      # This model's to-many associations that point at another registered
+      # model, as [association name, entry] — one nested index each.
+      def nested_associations(registry)
+        model.reflect_on_all_associations.select(&:collection?).filter_map do |reflection|
+          target = safe_target(reflection)
+          nested = target && registry[target]
+          next unless nested&.allows?(:index) && nested.model != model
+
+          [reflection.name, nested]
+        end.uniq { |_, nested| nested.route_key }
+      end
+
+      private
+
+      def structure = Structure.for(model)
+
+      # Routes are drawn without a database in reach often enough (an asset
+      # build, a container ahead of its migrations), and asking for the primary
+      # key raises there; assume the ordinary case.
+      def primary_key?
+        !model.primary_key.nil?
+      rescue StandardError
+        true
+      end
+
+      # A polymorphic or otherwise unresolvable association has no single target.
+      def safe_target(reflection)
+        return nil if reflection.options[:polymorphic] || reflection.options[:through]
+
+        reflection.klass
+      rescue NameError
+        nil
+      end
+
+      def resolve_actions
+        declared = options[:actions]
+        list = declared ? Array(declared).map(&:to_sym) : ALL_ACTIONS.dup
+        list |= list.filter_map { |action| ACTION_PAIRS[action] }
+        list &= ALL_ACTIONS
+        list -= MEMBER_ACTIONS unless primary_key?
+        ALL_ACTIONS & list
+      end
+    end
+  end
+end

data/lib/crud_components/admin/gate.rb

@@ -0,0 +1,40 @@
+module CrudComponents
+  module Admin
+    # Who may in at all, as one verdict the controller only has to carry out.
+    # It decides nothing beyond the door: what a visitor may see and do inside
+    # is the app's ordinary ability, asked per model and per action.
+    class Gate
+      ACTION = :access
+
+      VERDICTS = %i[open block unauthorized allowed forbidden].freeze
+
+      def initialize(config, ability)
+        @config = config
+        @ability = ability
+      end
+
+      def verdict
+        return :open if @config.open_gate?
+        return :block if @config.auth_block
+        return :unauthorized if @ability.nil?
+        return :allowed if @ability.can?(ACTION, subject)
+
+        :forbidden
+      end
+
+      def unauthorized_message
+        "The admin asks `can?(#{ACTION.inspect}, #{subject.inspect})`, and nothing here answers `can?`. " \
+          'Add CanCanCan, or configure a gate of your own: ' \
+          'CrudComponents::Admin.configure { |c| c.auth_with { … } } — ' \
+          "or say `c.auth_with :none` on purpose (see docs/admin.md).\n" \
+          "In an ability: `can #{ACTION.inspect}, #{subject.inspect}`."
+      end
+
+      def forbidden_message = "not allowed to #{ACTION} the admin"
+
+      private
+
+      def subject = @config.auth_subject
+    end
+  end
+end

data/lib/crud_components/admin/registry.rb

@@ -0,0 +1,176 @@
+module CrudComponents
+  module Admin
+    # Which models the admin administers, resolved once and memoized. The route
+    # drawer, the sidebar and the controller all read from here.
+    class Registry
+      def initialize(config)
+        @config = config
+      end
+
+      # Registered models, in sidebar/route order.
+      def entries
+        @entries ||= build
+      end
+
+      # The entry for a model class or model name, or nil when unregistered.
+      def [](model)
+        key = model.is_a?(Class) ? model.name : model.to_s
+        index[key]
+      end
+
+      def registered?(model) = !self[model].nil?
+
+      # Entries grouped for the sidebar: [heading (nil = ungrouped), entries].
+      def groups(list = entries)
+        list.group_by(&:group_label)
+            .sort_by { |heading, grouped| [group_rank(grouped.first.group_key), heading.to_s] }
+      end
+
+      # Where a group sits in the configured order; unlisted groups come last.
+      # Ordered by the declared name, so a translated heading keeps its place.
+      def group_rank(key)
+        position = Array(config.groups).index { |name| Entry.group_key(name) == key }
+        position || Array(config.groups).size
+      end
+
+      def reload!
+        @entries = nil
+        @index = nil
+        @except_names = nil
+        @admin_options = nil
+        self
+      end
+
+      private
+
+      attr_reader :config
+
+      def index
+        @index ||= entries.to_h { |entry| [entry.name, entry] }
+      end
+
+      def build
+        return explicit_entries if config.only
+
+        discovered = candidates.reject { |model| excluded?(model) }
+        sort(discovered.map { |model| Entry.new(model, admin_options(model) || {}) })
+      end
+
+      # `only` is a directive: the listed models are registered in the listed
+      # order, whether or not discovery would have found them.
+      def explicit_entries
+        Array(config.only).filter_map do |name|
+          model = constantize(name)
+          next unless model && usable?(model) && admin_options(model) != false
+
+          Entry.new(model, admin_options(model) || {})
+        end
+      end
+
+      def candidates
+        load_model_constants
+        ActiveRecord::Base.descendants
+      end
+
+      # Resolves every constant under the model directories, and nothing else.
+      # Deliberately not `Rails.application.eager_load!`: routes are drawn in
+      # every process, including rake tasks and asset builds, which switch
+      # eager loading off on purpose — and where an app's own initializers may
+      # not have the credentials that eager loading would ask for.
+      def load_model_constants
+        return unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+        model_dirs.each do |dir|
+          Dir.glob(File.join(dir, '**', '*.rb')).sort.each do |file|
+            file.delete_prefix("#{dir}/").delete_suffix('.rb').camelize.safe_constantize
+          end
+        end
+      end
+
+      # The application's own model directories, and only those. An engine's
+      # app/models holds the framework's own tables — loading Active Storage's
+      # Blob, for one, builds the configured storage service on the spot, which
+      # an asset build has no credentials for. Registering a model from an
+      # engine is what `config.only` is for.
+      def model_dirs
+        Rails.application.config.paths['app/models'].existent
+      end
+
+      def excluded?(model)
+        return true unless usable?(model)
+        return true if internal?(model)
+        return true if admin_options(model) == false
+        return true if except_names.include?(model.name)
+        return true if sti_subclass?(model) && !declares_admin?(model)
+
+        false
+      end
+
+      # Anonymous and throwaway classes are skipped: a route and a controller
+      # need a name that resolves back to the same class. Nothing here asks the
+      # database — routes are drawn before the schema exists often enough (a
+      # fresh checkout, a container that boots ahead of its migrations) that a
+      # registry which quietly comes up empty is the worse failure.
+      def usable?(model)
+        return false unless model.is_a?(Class) && model.name
+        return false if model.abstract_class?
+        return false if model == ActiveRecord::Base
+
+        model.name.safe_constantize.equal?(model)
+      end
+
+      def internal?(model)
+        return true if model.name.include?('HABTM_')
+
+        root = model.name.split('::').first
+        config.excluded_namespaces.include?(root)
+      end
+
+      def sti_subclass?(model) = model.base_class != model
+
+      # The `admin` declaration, read from the DSL block rather than from a
+      # resolved Structure: routes are drawn before a model's columns can be
+      # asked for (there may be no database, and resolving an attachment field
+      # would build the storage service). Inherited from an STI parent.
+      def admin_options(model)
+        @admin_options ||= {}
+        return @admin_options[model] if @admin_options.key?(model)
+
+        @admin_options[model] = declaration_of(model, inherited: true)
+      end
+
+      # Whether this very class declared `admin`, ignoring an STI parent's.
+      def declares_admin?(model)
+        !declaration_of(model, inherited: false).nil?
+      end
+
+      def declaration_of(model, inherited:)
+        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).admin_decl
+          end
+          break unless inherited
+
+          klass = klass.superclass
+          break if klass.nil? || klass == ActiveRecord::Base
+        end
+        nil
+      end
+
+      def except_names
+        @except_names ||= Array(config.except).map { |name| name.is_a?(Class) ? name.name : name.to_s }
+      end
+
+      def constantize(name)
+        model = name.is_a?(Class) ? name : name.to_s.safe_constantize
+        model if model.respond_to?(:columns_hash)
+      end
+
+      def sort(list)
+        list.sort_by { |entry| [group_rank(entry.group_key), entry.group_label.to_s, entry.label.to_s] }
+      end
+    end
+  end
+end

data/lib/crud_components/admin/routes.rb

@@ -0,0 +1,37 @@
+CrudComponents::Admin::Engine.routes.draw do
+  root 'dashboard#show'
+
+  registry = CrudComponents::Admin.registry
+  drawn = {}
+
+  registry.entries.each do |entry|
+    next if entry.actions.empty?
+
+    if (clash = drawn[entry.route_key])
+      raise CrudComponents::Admin::Error,
+            "#{entry.name} and #{clash} both route to /#{entry.route_key} — " \
+            'drop one with `admin false` or `config.except`'
+    end
+
+    drawn[entry.route_key] = entry.name
+    resources entry.route_key, controller: 'resources', only: entry.actions,
+                               defaults: { crud_model: entry.name } do
+      if entry.allows?(:destroy)
+        collection do
+          # /books/delete confirms the selection, /books/<id>/delete one record.
+          get :delete, action: :delete_selected, controller: 'resources'
+          delete :destroy_selected, controller: 'resources'
+        end
+        member { get :delete, controller: 'resources' }
+      end
+
+      # An index per to-many association pointing here, so the owner's
+      # "+n more" links and its association cells resolve.
+      entry.nested_associations(registry).each do |association, nested|
+        resources nested.route_key, controller: 'resources', only: :index,
+                                    defaults: { crud_model: nested.name, crud_owner: entry.name,
+                                                crud_association: association.to_s }
+      end
+    end
+  end
+end

data/lib/crud_components/admin/view_helpers.rb

@@ -0,0 +1,156 @@
+module CrudComponents
+  module Admin
+    # View helpers for the engine's own templates. Included explicitly by the
+    # engine's controllers, so they never reach the host app's views.
+    module ViewHelpers
+      # The engine's index path for a registered model. Built from the engine's
+      # own route set rather than a bare helper name, which a host helper of the
+      # same name would shadow.
+      def admin_index_path(entry)
+        CrudComponents::Admin.path_for(entry.model, :index)
+      end
+
+      # Whether these could be deleted on their own. A cascade takes them either
+      # way; the confirmation page says so. No ability means no opinion.
+      def admin_may_destroy?(model)
+        return true unless model && respond_to?(:can?)
+
+        can?(:destroy, model)
+      end
+
+      # The ticked rows as one dependent item, so the confirmation page names
+      # them the same way it names everything else that goes.
+      def admin_selection_item(model, records)
+        CrudComponents::Admin::Dependents::Item.new(
+          name: nil, model: model, count: records.size, behavior: :destroy, cascades: false,
+          records: records.first(CrudComponents::Admin::Dependents::PREVIEW)
+        )
+      end
+
+      # What the ticked rows are identified by, for the form that deletes them.
+      def admin_selected_values(records)
+        records.map { |record| record.public_send(CrudComponents::Structure.for(record.class).identify_by).to_s }
+      end
+
+      # One record a delete would take, named: an attachment names its file and
+      # opens it, anything else links to its own admin page.
+      def admin_dependent_link(record, owner: nil)
+        return admin_attachment_link(record) if admin_attachment?(record)
+
+        path = crud_record_path(record, owner: owner)
+        path ? link_to(crud_label(record), path, data: { turbo_action: 'advance' }) : crud_label(record)
+      end
+
+      # The index holding the rest of a dependent item: nested under the owner,
+      # else the target's index filtered by it, else nil.
+      def admin_dependents_path(owner, item)
+        return nil unless item.model
+
+        CrudComponents::RouteResolver.collection_index_path(self, item.model, owner, item.name)
+      end
+
+      def admin_icon(name, css_class: nil)
+        return nil unless name
+
+        tag.i(nil, class: ["#{CrudComponents.config.css.icon_prefix}#{name}", css_class].compact.join(' '))
+      end
+
+      # Whether this entry is the one being looked at.
+      def admin_current_entry?(entry)
+        params[:crud_model].to_s == entry.name
+      end
+
+      def admin_title = CrudComponents::Admin.config.resolved_title
+
+      # The admin layout's stylesheet, inlined (CSP-nonce aware).
+      def admin_styles
+        nonce = content_security_policy_nonce if respond_to?(:content_security_policy_nonce)
+        tag.style(CrudComponents::Admin.bundled_css.html_safe, type: 'text/css', nonce: nonce)
+      end
+
+      # The bulk action, or nil for a model with no destroy route. Like the row's
+      # delete it leads to the confirmation page, not straight to a DELETE.
+      def admin_destroy_selected_action(entry)
+        return nil unless entry.allows?(:destroy)
+
+        CrudComponents::Action.new(
+          :destroy_selected, on: :selection, method: :get, confirm: false, icon: 'trash',
+          if: :destroy, title: t('crud_components.admin.destroy_selected', default: 'Delete selected')
+        ) { public_send("delete_#{entry.route_key}_path") }
+      end
+
+      # The delete button: a link to the confirmation page rather than a DELETE
+      # behind a browser dialog. Keeps the derived action's icon and label.
+      def admin_delete_action(entry)
+        return nil unless entry.allows?(:destroy)
+
+        CrudComponents::Action.new(:destroy, on: :row, method: :get, confirm: false) do |record|
+          public_send("delete_#{entry.singular_route_key}_path", record)
+        end
+      end
+
+      # The row action linking a record to the host app's own page for it.
+      # Resolves through crud_app_path, so it disappears when there is none.
+      def admin_show_in_app_action
+        CrudComponents::Action.new(
+          :show_in_app, on: :row, icon: 'box-arrow-up-right',
+          title: t('crud_components.admin.show_in_app', default: 'Show in app')
+        ) { |record| crud_app_path(record) }
+      end
+
+      # Active Storage routes live in the application's route set, not in an
+      # isolated engine's; attachment cells reach them through these two.
+      def polymorphic_url(record, options = {})
+        return main_app.polymorphic_url(record, options) if active_storage_object?(record)
+
+        super
+      end
+
+      def polymorphic_path(record, options = {})
+        return main_app.polymorphic_path(record, options) if active_storage_object?(record)
+
+        super
+      end
+
+      # A route helper the engine does not have falls through to the host
+      # application's routes — the admin renders the host's partials and render
+      # blocks, and those call the host's routes.
+      def method_missing(name, *args, **options, &block)
+        return super unless forwardable_route_helper?(name)
+
+        main_app.public_send(name, *args, **options, &block)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        forwardable_route_helper?(name) || super
+      end
+
+      private
+
+      def forwardable_route_helper?(name)
+        return false unless name.to_s.end_with?('_path', '_url')
+        return false unless respond_to?(:main_app)
+
+        main_app.respond_to?(name)
+      end
+
+      def admin_attachment?(record)
+        defined?(ActiveStorage) && record.is_a?(ActiveStorage::Attachment)
+      end
+
+      # The filename, linked to the file itself; a blob that is gone is named
+      # but not linked.
+      def admin_attachment_link(attachment)
+        blob = attachment.blob
+        return attachment.name.to_s.humanize unless blob
+
+        link_to(blob.filename.to_s, rails_blob_path(attachment, disposition: :inline),
+                target: '_blank', rel: 'noopener')
+      end
+
+      def active_storage_object?(object)
+        defined?(ActiveStorage) && object.class.name.to_s.start_with?('ActiveStorage::')
+      end
+    end
+  end
+end