administratum 0.2.4

data/config/routes.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+Administratum::Engine.routes.draw do
+  # Registers the Devise/Warden scope only; the engine has its own controllers.
+  devise_for :users, class_name: "Administratum::User", singular: :administratum_user, module: :devise,
+                     router_name: :administratum, skip: :all
+
+  get "sign_in", to: "sessions#new", as: :sign_in
+  post "sign_in", to: "sessions#create"
+  delete "sign_out", to: "sessions#destroy", as: :sign_out
+  resource :password_reset, only: %i[new create edit update]
+
+  Administratum::Routing.draw(self)
+
+  root to: "dashboard#index"
+end

data/db/migrate/20261016000000_create_administratum_users.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class CreateAdministratumUsers < ActiveRecord::Migration[8.0]
+  def change
+    create_table :administratum_users do |t|
+      t.string :email, null: false, default: ""
+      t.string :encrypted_password, null: false, default: ""
+      t.string :reset_password_token
+      t.datetime :reset_password_sent_at
+      t.datetime :remember_created_at
+      t.timestamps
+    end
+
+    add_index :administratum_users, :email, unique: true
+    add_index :administratum_users, :reset_password_token, unique: true
+  end
+end

data/lib/administratum/configuration.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Administratum
+  # Global settings, set from config/initializers/administratum.rb.
+  class Configuration
+    STYLESHEET_MODES = %i[bundled host].freeze
+
+    # Name shown in the top bar and the page title.
+    attr_accessor :app_name
+    # Path or URL to a logo image. Shown instead of the app name when set.
+    attr_accessor :logo
+    # Controller the engine's ApplicationController inherits from, as a string.
+    attr_accessor :parent_controller
+    # Partial rendered on the dashboard. nil renders the built-in resource overview.
+    attr_accessor :dashboard
+    # Sender address for password reset emails.
+    attr_accessor :mailer_sender
+    # Default page size on index pages.
+    attr_accessor :per_page
+    # Whether Administratum::UserAdmin is mounted, so admins can manage admin users.
+    attr_accessor :manage_users
+    # A lambda receiving the view context, returning extra tags for <head>.
+    attr_accessor :head
+    # A partial rendered inside <head>, alternative to `head`.
+    attr_accessor :head_partial
+    # Extra helper modules made available in every admin view.
+    attr_accessor :helpers
+    # Directories scanned for resource definitions, relative to Rails.root.
+    attr_accessor :resource_paths
+    # View directory for resource templates: app/views/<view_prefix>/<route_key>.
+    attr_accessor :view_prefix
+    # Token overrides, e.g. { primary: "#7c3aed" } becomes --color-adm-primary.
+    attr_reader :theme, :dark_theme
+    attr_reader :stylesheet, :field_types
+
+    def initialize
+      @app_name = "Administratum"
+      @parent_controller = "ActionController::Base"
+      @mailer_sender = "admin@example.com"
+      @per_page = 25
+      @manage_users = true
+      @helpers = []
+      @resource_paths = ["app/admin"]
+      @view_prefix = "admin"
+      @theme = {}
+      @dark_theme = {}
+      @stylesheet = :bundled
+      @field_types = FieldTypes.new
+    end
+
+    def theme=(tokens)
+      @theme = tokens.to_h
+    end
+
+    def dark_theme=(tokens)
+      @dark_theme = tokens.to_h
+    end
+
+    def stylesheet=(mode)
+      mode = mode.to_sym
+      raise ArgumentError, "stylesheet must be one of #{STYLESHEET_MODES.join(', ')}" unless STYLESHEET_MODES.include?(mode)
+
+      @stylesheet = mode
+    end
+  end
+end

data/lib/administratum/definition.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+module Administratum
+  # Everything a resource class declares through the DSL. Each resource class
+  # owns one; subclasses start from a deep copy of their parent's.
+  #
+  # Declarations are stored as given and resolved lazily (types inferred from
+  # the schema on first use), because resource classes are loaded to draw
+  # routes, which also happens when the database doesn't exist yet.
+  class Definition
+    BUILT_IN_ACTIONS = %i[index show new create edit update destroy].freeze
+
+    Field = Struct.new(:name, :declared_type, :options, :definition, keyword_init: true) do
+      def model = definition.model
+      def type = (declared_type || Administratum.field_types.infer(model, name)).to_sym
+      def label = options[:label]
+      def hint = options[:hint]
+    end
+
+    Column = Struct.new(:name, :declared_type, :label, :declared_sortable, :block, :condition, :csv, :definition,
+                        keyword_init: true) do
+      def model = definition.model
+
+      def type
+        return declared_type if declared_type
+        return :association if model.reflect_on_association(name)&.macro == :belongs_to
+
+        case model.columns_hash[name.to_s]&.type
+        when :boolean then :boolean
+        when :datetime then :datetime
+        when :date then :date
+        else :text
+        end
+      end
+
+      def sortable
+        declared_sortable.nil? ? block.nil? && model.columns_hash.key?(name.to_s) : declared_sortable
+      end
+    end
+
+    Filter = Struct.new(:name, :declared_type, :label, :declared_collection, :declared_predicate, :definition,
+                        keyword_init: true) do
+      def model = definition.model
+
+      def type
+        return declared_type if declared_type
+        return :select if belongs_to_reflection
+
+        case model.columns_hash[name.to_s]&.type
+        when :boolean then :boolean
+        when :integer, :float, :decimal then :number
+        when :date, :datetime then :date_range
+        else :string
+        end
+      end
+
+      def predicate
+        declared_predicate || (type == :string ? :cont : :eq)
+      end
+
+      def collection
+        return declared_collection if declared_collection
+        return unless type == :select
+
+        reflection = belongs_to_reflection
+        -> { reflection.klass.all } if reflection
+      end
+
+      def keys
+        type == :date_range ? ["#{name}_gteq", "#{name}_lteq"] : ["#{name}_#{predicate}"]
+      end
+
+      private
+
+      def belongs_to_reflection
+        return unless name.to_s.end_with?("_id")
+
+        reflection = model.reflect_on_association(name.to_s.delete_suffix("_id").to_sym)
+        reflection if reflection&.macro == :belongs_to
+      end
+    end
+
+    CustomAction = Struct.new(:name, :http_method, :scope, keyword_init: true) do
+      def member? = scope == :member
+    end
+
+    Button = Struct.new(:name, :label, :pages, :action, :to, :http_method, :confirm, :condition, :style, :panel, :upload,
+                        keyword_init: true)
+
+    Parent = Struct.new(:name, :class_name, :shallow, :association, keyword_init: true) do
+      def model = class_name.constantize
+      def param = :"#{name}_id"
+    end
+
+    Menu = Struct.new(:label, :priority, :hidden, keyword_init: true)
+
+    # A tab above the index table. Without a block it calls the model scope of the same name.
+    IndexScope = Struct.new(:name, :label, :block, :default, :count, keyword_init: true) do
+      def apply(relation) = block ? block.call(relation) : relation.public_send(name)
+      def display_label = label || I18n.t("administratum.scopes.#{name}", default: name.to_s.humanize)
+    end
+
+    attr_accessor :model, :title_attribute, :permitted, :parent, :form_template, :scope_block, :route_key, :label,
+                  :plural_label, :per_page, :default_sort, :csv
+    attr_reader :fields, :columns, :custom_actions, :buttons, :show_attributes, :enabled_actions, :menu, :index_scopes
+
+    def initialize
+      @fields = []
+      @columns = []
+      @filters = nil
+      @custom_actions = {}
+      @buttons = []
+      @show_attributes = []
+      @index_scopes = []
+      @enabled_actions = BUILT_IN_ACTIONS.dup
+      @menu = Menu.new(priority: 100, hidden: false)
+      @csv = false
+    end
+
+    def initialize_copy(source)
+      super
+      @fields = rebind(source.fields)
+      @columns = rebind(source.columns)
+      @filters = source.declared_filters && rebind(source.declared_filters)
+      @custom_actions = source.custom_actions.dup
+      @buttons = source.buttons.map(&:dup)
+      @show_attributes = rebind(source.show_attributes)
+      @index_scopes = source.index_scopes.dup
+      @enabled_actions = source.enabled_actions.dup
+      @menu = source.menu.dup
+    end
+
+    def declared_filters
+      @filters
+    end
+
+    def title
+      title_attribute || %i[title name].find { |attr| model.column_names.include?(attr.to_s) || model.method_defined?(attr) }
+    end
+
+    # Filters default to a "contains" search on the title attribute.
+    def filters
+      return @filters if @filters
+
+      title && model.column_names.include?(title.to_s) ? [build_filter(title)] : []
+    end
+
+    def add_filter(name, **)
+      @filters ||= []
+      @filters.reject! { |filter| filter.name == name.to_sym }
+      @filters << build_filter(name, **)
+    end
+
+    def clear_filters!
+      @filters = []
+    end
+
+    def build_filter(name, as: nil, label: nil, collection: nil, predicate: nil)
+      Filter.new(name: name.to_sym, declared_type: as&.to_sym, label:, declared_collection: collection,
+                 declared_predicate: predicate&.to_sym, definition: self)
+    end
+
+    def index_columns
+      return columns if columns.any?
+
+      [:id, title, :updated_at].compact.uniq.select { |name| model.column_names.include?(name.to_s) }.map { |name| build_column(name) }
+    end
+
+    def add_column(name, as: nil, label: nil, sortable: nil, csv: true, &)
+      columns.reject! { |column| column.name == name.to_sym }
+      columns << build_column(name, as:, label:, sortable:, csv:, &)
+    end
+
+    def build_column(name, as: nil, label: nil, sortable: nil, csv: true, &block)
+      Column.new(name: name.to_sym, declared_type: as&.to_sym, label:, declared_sortable: sortable, block:, csv:,
+                 definition: self)
+    end
+
+    def add_field(name, as: nil, **options)
+      fields.reject! { |field| field.name == name.to_sym }
+      fields << Field.new(name: name.to_sym, declared_type: as&.to_sym, options:, definition: self)
+    end
+
+    def field(name)
+      fields.find { |field| field.name == name.to_sym }
+    end
+
+    # The argument list passed to `permit`, with hash entries last as strong params requires.
+    def permitted_params
+      return permitted if permitted
+
+      scalars = []
+      nested = {}
+      fields.each do |field|
+        case Administratum.field_types.fetch(field.type).param
+        when :array then nested[field.name] = []
+        when :hash then nested[field.name] = {}
+        else scalars << field.name
+        end
+      end
+      nested.empty? ? scalars : scalars + [nested]
+    end
+
+    # Attribute names Ransack may filter and sort on for this resource.
+    def ransackable_attributes
+      names = filters.map { |filter| filter.name.to_s }
+      names += index_columns.select(&:sortable).map { |column| column.name.to_s }
+      names << title.to_s if title
+      names += Array(default_sort).map { |sort| sort.to_s.split.first }
+      names.uniq & model.column_names
+    end
+
+    def add_action(name, http_method:, scope:)
+      custom_actions[name.to_sym] = CustomAction.new(name: name.to_sym, http_method: http_method.to_sym, scope:)
+    end
+
+    def member_actions
+      custom_actions.values.select(&:member?)
+    end
+
+    def collection_actions
+      custom_actions.values.reject(&:member?)
+    end
+
+    def member_action_names
+      %i[show edit update destroy] + member_actions.map(&:name)
+    end
+
+    def enable_actions(only: nil, except: nil)
+      list = only ? Array(only).map(&:to_sym) : BUILT_IN_ACTIONS.dup
+      list -= Array(except).map(&:to_sym)
+      # A form is useless without the action that receives it.
+      list |= [:create] if list.include?(:new)
+      list |= [:update] if list.include?(:edit)
+      @enabled_actions = list & BUILT_IN_ACTIONS
+    end
+
+    def action_enabled?(name)
+      enabled_actions.include?(name.to_sym)
+    end
+
+    def add_button(name, on:, label: nil, action: nil, to: nil, method: nil, confirm: nil, condition: nil, style: :secondary,
+                   panel: nil, upload: false)
+      buttons << Button.new(name: name.to_sym, label:, pages: Array(on).map(&:to_sym), action: (action || name).to_sym, to:,
+                            http_method: method&.to_sym, confirm:, condition:, style: style.to_sym, panel:, upload:)
+    end
+
+    def buttons_for(page)
+      buttons.select { |button| button.pages.include?(page.to_sym) }
+    end
+
+    def add_index_scope(name, label: nil, default: false, count: true, &block)
+      index_scopes.reject! { |index_scope| index_scope.name == name.to_sym }
+      index_scopes << IndexScope.new(name: name.to_sym, label:, block:, default:, count:)
+    end
+
+    # The tab named by `name`, else the default tab (the first one unless one says `default: true`).
+    def index_scope(name)
+      index_scopes.find { |index_scope| index_scope.name.to_s == name.to_s } ||
+        index_scopes.find(&:default) || index_scopes.first
+    end
+
+    def add_show_attribute(name, as: nil, label: nil, condition: nil, &)
+      show_attributes << build_column(name, as:, label:, sortable: false, &).tap { |column| column.condition = condition }
+    end
+
+    def resolved_show_attributes
+      return show_attributes if show_attributes.any?
+
+      names = [:id] + fields.reject { |field| %i[password hidden].include?(field.type) }.map(&:name)
+      names = index_columns.map(&:name) if fields.empty?
+      names += %i[created_at updated_at]
+      names.uniq.select { |name| model.column_names.include?(name.to_s) || model.method_defined?(name) }
+           .map { |name| build_column(name, sortable: false) }
+    end
+
+    private
+
+    def rebind(items)
+      items.map { |item| item.dup.tap { |copy| copy.definition = self } }
+    end
+  end
+end

data/lib/administratum/dsl.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module Administratum
+  # Class-level DSL for resource classes. See README for the full reference.
+  module DSL
+    # Declarations shared by resources and pages.
+    module Common
+      # A button on one or more pages (:index, :show, :new, :edit, :row, :page or a
+      # custom action's name). It triggers the custom action of the same name
+      # unless `action:` or `to:` (a lambda returning a path) is given.
+      def button(name, on:, label: nil, action: nil, to: nil, method: nil, confirm: nil, if: nil, style: :secondary,
+                 panel: nil, upload: false)
+        definition.add_button(name, on:, label:, action:, to:, method:, confirm:, condition: binding.local_variable_get(:if),
+                                    style:, panel:, upload:)
+      end
+
+      # `menu false` hides it from navigation.
+      def menu(options = {})
+        if options == false
+          definition.menu.hidden = true
+        else
+          definition.menu.label = options[:label] if options[:label]
+          definition.menu.priority = options[:priority] if options[:priority]
+        end
+      end
+
+      def route(key)
+        definition.route_key = key.to_s
+      end
+
+      def controller_id
+        name.underscore.tr("/", "_")
+      end
+    end
+
+    include Common
+
+    # Builds `form do ... end` field lists.
+    class FormBuilder
+      def initialize(definition)
+        @definition = definition
+      end
+
+      def field(name, as: nil, **options)
+        @definition.add_field(name, as:, **options)
+      end
+    end
+
+    # Builds `index do ... end` column lists.
+    class IndexBuilder
+      def initialize(definition)
+        @definition = definition
+      end
+
+      def column(name, as: nil, label: nil, sortable: nil, csv: true, &block)
+        @definition.add_column(name, as:, label:, sortable:, csv:, &block)
+      end
+    end
+
+    # Builds `show do ... end` attribute lists.
+    class ShowBuilder
+      def initialize(definition)
+        @definition = definition
+      end
+
+      # `if:` takes a lambda, run in the view, that receives the record when it takes an argument.
+      def attribute(name, as: nil, label: nil, if: nil, &)
+        @definition.add_show_attribute(name, as:, label:, condition: binding.local_variable_get(:if), &)
+      end
+    end
+
+    def definition
+      @definition ||= superclass.respond_to?(:definition) ? superclass.definition.dup : Definition.new
+      @definition.model ||= inferred_model unless abstract_resource?
+      @definition
+    end
+
+    # Marks a class as a base for other resources: it gets no routes or menu entry.
+    def abstract_resource!
+      @abstract_resource = true
+    end
+
+    def abstract_resource?
+      @abstract_resource == true || name == "Administratum::Resource"
+    end
+
+    def model(klass = nil)
+      definition.model = klass if klass
+      definition.model
+    end
+
+    def title(attribute)
+      definition.title_attribute = attribute.to_sym
+    end
+
+    def label(singular, plural: nil)
+      definition.label = singular
+      definition.plural_label = plural
+    end
+
+    # Replaces the filter list. `filters` with no arguments disables filtering.
+    def filters(*names)
+      definition.clear_filters!
+      names.each { |name| definition.add_filter(name) }
+    end
+
+    def filter(name, as: nil, label: nil, collection: nil, predicate: nil)
+      definition.add_filter(name, as:, label:, collection:, predicate:)
+    end
+
+    def index(per_page: nil, sort: nil, csv: nil, &block)
+      definition.per_page = per_page if per_page
+      definition.default_sort = sort if sort
+      definition.csv = csv unless csv.nil?
+      IndexBuilder.new(definition).instance_eval(&block) if block
+    end
+
+    def form(template: nil, &block)
+      definition.form_template = template if template
+      FormBuilder.new(definition).instance_eval(&block) if block
+    end
+
+    def show(&)
+      ShowBuilder.new(definition).instance_eval(&)
+    end
+
+    # Strong-params style list of writable attributes. Defaults to the form fields.
+    def permit(*attributes)
+      definition.permitted = attributes
+    end
+
+    # With a block only, narrows every query this resource makes (the block receives the relation).
+    # With a name, adds a tab above the index: `scope :published` calls Post.published, or pass a
+    # block. Options: `default: true`, `label:`, `count: false` to skip the count query.
+    def scope(name = nil, label: nil, default: false, count: true, &block)
+      return definition.add_index_scope(name, label:, default:, count:, &block) if name
+
+      definition.scope_block = block
+    end
+
+    # Nests this resource under another: `parent :fantasy, shallow: true`.
+    def parent(name, shallow: false, association: nil, class_name: nil)
+      definition.parent = Definition::Parent.new(
+        name: name.to_sym,
+        class_name: class_name || name.to_s.classify,
+        shallow:,
+        association: (association || definition.model.model_name.plural).to_sym
+      )
+    end
+
+    def actions(only: nil, except: nil)
+      definition.enable_actions(only:, except:)
+    end
+
+    def member_action(name, method: :get)
+      definition.add_action(name, http_method: method, scope: :member)
+    end
+
+    def collection_action(name, method: :get)
+      definition.add_action(name, http_method: method, scope: :collection)
+    end
+
+    def route_key
+      definition.route_key || definition.model.model_name.route_key
+    end
+
+    def singular_route_key
+      definition.route_key ? definition.route_key.singularize : definition.model.model_name.singular_route_key
+    end
+
+    def parent_resource
+      return unless definition.parent
+
+      Administratum.registry.for_model(definition.parent.model)
+    end
+
+    def singular_label
+      definition.label || definition.model.model_name.human
+    end
+
+    def plural_label
+      definition.plural_label || definition.model.model_name.human(count: 2, default: singular_label.pluralize)
+    end
+
+    def menu_label
+      definition.menu.label || plural_label
+    end
+
+    private
+
+    def inferred_model
+      name&.delete_suffix("Admin")&.safe_constantize
+    end
+  end
+end

data/lib/administratum/engine.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Administratum
+  class Engine < ::Rails::Engine
+    isolate_namespace Administratum
+
+    initializer "administratum.devise" do
+      require "devise/orm/active_record"
+    end
+
+    # Redraw routes when a resource file changes, since routes are derived
+    # from the resource definitions.
+    initializer "administratum.reloading" do |app|
+      checker = nil
+
+      config.after_initialize do
+        dirs = Administratum.registry.resource_dirs.index_with { ["rb"] }
+        checker = ActiveSupport::FileUpdateChecker.new([], dirs) { nil }
+        app.reloaders << checker
+      end
+
+      config.to_prepare do
+        Administratum.registry.reset!
+        if checker&.updated?
+          checker.execute
+          app.reload_routes!
+        end
+      end
+    end
+  end
+end

data/lib/administratum/field_types.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Administratum
+  # Registry of form field types. Each type is a partial plus the shape its
+  # value takes in strong params (:scalar, :array or :hash).
+  class FieldTypes
+    Type = Struct.new(:name, :partial, :param, keyword_init: true)
+
+    PARAM_SHAPES = %i[scalar array hash].freeze
+
+    BUILT_IN = {
+      string: :scalar,
+      textarea: :scalar,
+      number: :scalar,
+      boolean: :scalar,
+      select: :scalar,
+      multi_select: :array,
+      belongs_to: :scalar,
+      has_many_ids: :array,
+      date: :scalar,
+      datetime: :scalar,
+      email: :scalar,
+      password: :scalar,
+      hidden: :scalar,
+      json: :scalar,
+      island: :scalar
+    }.freeze
+
+    COLUMN_TYPES = {
+      text: :textarea,
+      integer: :number,
+      float: :number,
+      decimal: :number,
+      boolean: :boolean,
+      date: :date,
+      datetime: :datetime,
+      json: :json,
+      jsonb: :json
+    }.freeze
+
+    def initialize
+      @types = {}
+      BUILT_IN.each { |name, param| register(name, partial: "administratum/fields/#{name}", param:) }
+    end
+
+    # Registers a field type. The partial receives form:, field:, resource: and value:.
+    def register(name, partial:, param: :scalar)
+      raise ArgumentError, "param must be one of #{PARAM_SHAPES.join(', ')}" unless PARAM_SHAPES.include?(param)
+
+      @types[name.to_sym] = Type.new(name: name.to_sym, partial:, param:)
+    end
+
+    def fetch(name)
+      @types.fetch(name.to_sym) { raise Administratum::Error, "Unknown field type :#{name}. Register it with config.field_types.register." }
+    end
+
+    def key?(name)
+      @types.key?(name.to_sym)
+    end
+
+    # Picks a field type from the model's column when `as:` is not given.
+    def infer(model, attribute)
+      name = attribute.to_s
+      return :password if name.include?("password")
+      return :email if name == "email"
+
+      reflection = model.reflect_on_association(name.delete_suffix("_id").to_sym)
+      return :belongs_to if name.end_with?("_id") && reflection&.macro == :belongs_to
+      return :has_many_ids if name.end_with?("_ids")
+
+      column = model.columns_hash[name]
+      return :string unless column
+
+      COLUMN_TYPES.fetch(column.type, :string)
+    end
+  end
+end