administratum 0.2.4

data/lib/administratum/page_dsl.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Administratum
+  # Class-level DSL for custom pages (Administratum::Page subclasses in app/admin).
+  module PageDSL
+    include DSL::Common
+
+    def definition
+      @definition ||= superclass.respond_to?(:definition) ? superclass.definition.dup : Definition.new
+    end
+
+    # Marks a class as a base for other pages: it gets no route or menu entry.
+    def abstract_page!
+      @abstract_page = true
+    end
+
+    def abstract_page?
+      @abstract_page == true || name == "Administratum::Page"
+    end
+
+    def label(text)
+      definition.label = text
+    end
+
+    # An extra route on the page, /<route_key>/<name>, handled by the method of that name.
+    def page_action(name, method: :get)
+      definition.add_action(name, http_method: method, scope: :collection)
+    end
+
+    # Buttons on a page default to its header.
+    def button(name, on: :page, **)
+      super
+    end
+
+    # ReportsPage => "reports"; Stats::WeeklyPage => "stats_weekly".
+    def route_key
+      definition.route_key || name.delete_suffix("Page").underscore.tr("/", "_")
+    end
+
+    def page_title
+      definition.label || route_key.humanize
+    end
+
+    def menu_label
+      definition.menu.label || page_title
+    end
+  end
+end

data/lib/administratum/paths.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Administratum
+  # Builds paths for a resource class from the route names Routing draws.
+  # `context` is anything that responds to the engine's *_path helpers.
+  class Paths
+    def initialize(resource, context)
+      @resource = resource
+      @context = context
+    end
+
+    def index(parent = nil, **query)
+      call(collection_name, nested? ? [parent] : [], query)
+    end
+
+    def new(parent = nil, **query)
+      call("new_#{nested? ? "#{parent_key}_" : ''}#{singular}", nested? ? [parent] : [], query)
+    end
+
+    def show(record, **query)
+      call(member_name, member_args(record), query)
+    end
+
+    def edit(record, **query)
+      call("edit_#{member_name}", member_args(record), query)
+    end
+
+    # Path for a custom action. Member actions take the record, collection
+    # actions take the parent (when nested) or nothing.
+    def action(name, record_or_parent = nil, **query)
+      action = @resource.definition.custom_actions.fetch(name.to_sym)
+      if action.member?
+        call("#{name}_#{member_name}", member_args(record_or_parent), query)
+      else
+        call("#{name}_#{collection_name}", nested? ? [record_or_parent] : [], query)
+      end
+    end
+
+    # Where a form for `record` submits to.
+    def form(record, parent = nil)
+      record.persisted? ? show(record) : index(parent || parent_of(record))
+    end
+
+    def parent_of(record)
+      return unless nested?
+
+      record.public_send(@resource.definition.parent.name)
+    end
+
+    private
+
+    def call(name, args, query)
+      @context.public_send(:"#{name}_path", *args, **query)
+    end
+
+    def nested?
+      @resource.definition.parent.present?
+    end
+
+    def shallow?
+      nested? && @resource.definition.parent.shallow
+    end
+
+    def singular
+      @resource.singular_route_key
+    end
+
+    def parent_key
+      @resource.parent_resource.singular_route_key
+    end
+
+    def collection_name
+      base = @resource.route_key == singular ? "#{singular}_index" : @resource.route_key
+      nested? ? "#{parent_key}_#{base}" : base
+    end
+
+    def member_name
+      nested? && !shallow? ? "#{parent_key}_#{singular}" : singular
+    end
+
+    def member_args(record)
+      nested? && !shallow? ? [parent_of(record), record] : [record]
+    end
+  end
+end

data/lib/administratum/ransackable.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Administratum
+  # Prepended to each managed model's singleton class. When Ransack is called
+  # with auth_object: :administratum, the attributes a resource declares as
+  # filters or sortable columns are allowed, so models need no allowlist of
+  # their own. Other callers see the model's own allowlist unchanged.
+  module Ransackable
+    def self.install(model)
+      return if model.singleton_class.include?(self)
+
+      model.singleton_class.prepend(self)
+    end
+
+    def ransackable_attributes(auth_object = nil)
+      return super unless auth_object == :administratum
+
+      Administratum.registry.ransackable_attributes_for(self) | own_allowlist(:ransackable_attributes, auth_object)
+    end
+
+    def ransackable_associations(auth_object = nil)
+      return super unless auth_object == :administratum
+
+      own_allowlist(:ransackable_associations, auth_object)
+    end
+
+    private
+
+    # The model's own allowlist, if it defines one. Ransack's default either
+    # raises (Ransack 4.1+) or, in some 4.x versions, allows every column with a
+    # deprecation warning; neither should widen what the admin can search.
+    def own_allowlist(name, auth_object)
+      definition = method(name).super_method
+      return [] if definition.nil? || definition.owner.name.to_s.start_with?("Ransack::")
+
+      Array(definition.call(auth_object)).map(&:to_s)
+    rescue RuntimeError
+      []
+    end
+  end
+end

data/lib/administratum/registry.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Administratum
+  # Finds every resource class. Classes are not stored here: they are looked up
+  # through Class#descendants after eager loading the resource directories, so
+  # code reloading in development needs no bookkeeping.
+  class Registry
+    def resources
+      ensure_loaded!
+      Administratum::Resource.descendants
+                             .select { |klass| live?(klass) && !klass.abstract_resource? && enabled?(klass) }
+                             .sort_by(&:name)
+                             .each { |klass| Ransackable.install(klass.definition.model) }
+    end
+
+    def find_by_controller_id(id)
+      resources.find { |klass| klass.controller_id == id }
+    end
+
+    def pages
+      ensure_loaded!
+      Administratum::Page.descendants.select { |klass| live?(klass) && !klass.abstract_page? }.sort_by(&:name)
+    end
+
+    def find_page_by_controller_id(id)
+      pages.find { |klass| klass.controller_id == id }
+    end
+
+    def top_level
+      resources.reject { |klass| klass.definition.parent }
+    end
+
+    def children_of(resource)
+      resources.select { |klass| klass.parent_resource == resource }
+    end
+
+    # The resource that manages `model` at the top level, falling back to any.
+    def for_model(model)
+      candidates = resources.select { |klass| klass.definition.model == model }
+      candidates.find { |klass| klass.definition.parent.nil? } || candidates.first
+    end
+
+    def menu_items
+      resources.reject { |klass| klass.definition.menu.hidden || klass.definition.parent || !klass.definition.action_enabled?(:index) }
+               .sort_by { |klass| [klass.definition.menu.priority, klass.plural_label] }
+    end
+
+    # Resources and pages for the top navigation, by priority then label.
+    def navigation
+      (menu_items + pages.reject { |page| page.definition.menu.hidden })
+        .sort_by { |klass| [klass.definition.menu.priority, klass.menu_label] }
+    end
+
+    def ransackable_attributes_for(model)
+      resources.select { |klass| model <= klass.definition.model }.flat_map { |klass| klass.definition.ransackable_attributes }.uniq
+    end
+
+    def resource_dirs
+      dirs = Administratum.config.resource_paths.map { |path| Rails.root.join(path).to_s }
+      dirs << Administratum::Engine.root.join("app/admin").to_s
+      dirs.select { |dir| Dir.exist?(dir) }
+    end
+
+    def reset!
+      @loaded = false
+    end
+
+    private
+
+    def ensure_loaded!
+      return if @loaded
+
+      @loaded = true
+      resource_dirs.each { |dir| load_dir(dir) }
+    end
+
+    # Another admin (ActiveAdmin, say) may own app/admin and take it away from
+    # Zeitwerk. Skip such a directory rather than break route loading.
+    def load_dir(dir)
+      Rails.autoloaders.main.eager_load_dir(dir)
+    rescue Zeitwerk::Error => e
+      Rails.logger&.warn("[Administratum] Skipping #{dir}: #{e.message}. Point config.resource_paths at a directory " \
+                         "Rails autoloads, e.g. app/admin_next.")
+    end
+
+    # After a reload, stale classes can linger in descendants until GC.
+    def live?(klass)
+      klass.name.present? && klass.name.safe_constantize == klass
+    end
+
+    def enabled?(klass)
+      Administratum.config.manage_users || klass.name != "Administratum::UserAdmin"
+    end
+  end
+end

data/lib/administratum/routing.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Administratum
+  # Draws one `resources` block per resource class, nesting children under
+  # their parent. Each route points at a controller name that
+  # Administratum::Resources resolves back to the resource class.
+  module Routing
+    module_function
+
+    def draw(router)
+      Administratum.registry.reset!
+      Administratum.registry.top_level.each { |resource| draw_resource(router, resource) }
+      Administratum.registry.pages.each { |page| draw_page(router, page) }
+    end
+
+    # GET /<route_key> plus one route per page_action, named <route_key>_page
+    # and <action>_<route_key>_page.
+    def draw_page(router, page)
+      controller = "pages/#{page.controller_id}"
+      key = page.route_key
+      router.get key, to: "#{controller}#index", as: "#{key}_page"
+      page.definition.custom_actions.each_value do |action|
+        router.public_send(action.http_method, "#{key}/#{action.name}", to: "#{controller}##{action.name}", as: "#{action.name}_#{key}_page")
+      end
+    end
+
+    def draw_resource(router, resource, nested: false)
+      definition = resource.definition
+      options = { controller: "resources/#{resource.controller_id}", only: definition.enabled_actions }
+      options[:shallow] = true if nested && definition.parent.shallow
+
+      router.resources(resource.route_key.to_sym, **options) do
+        definition.member_actions.each { |action| router.public_send(action.http_method, action.name, on: :member) }
+        definition.collection_actions.each { |action| router.public_send(action.http_method, action.name, on: :collection) }
+        Administratum.registry.children_of(resource).each { |child| draw_resource(router, child, nested: true) }
+      end
+    end
+  end
+
+  # Rails resolves "administratum/resources/fantasy_admin" to the constant
+  # Administratum::Resources::FantasyAdminController. Instead of defining those
+  # constants (which would go stale on reload), look the resource up each time.
+  module Resources
+    def self.const_missing(name)
+      id = name.to_s.delete_suffix("Controller").underscore
+      Administratum.registry.find_by_controller_id(id) || super
+    end
+  end
+
+  # The same lookup for "administratum/pages/<controller_id>".
+  module Pages
+    def self.const_missing(name)
+      id = name.to_s.delete_suffix("Controller").underscore
+      Administratum.registry.find_page_by_controller_id(id) || super
+    end
+  end
+end

data/lib/administratum/tailwind.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Administratum
+  # Host Tailwind mode: generates a CSS file with absolute paths into the
+  # installed gem, so an app's Tailwind v4 build can include Administratum's
+  # tokens, components and class sources. Import it after "tailwindcss" and
+  # override any --color-adm-* token in your own @theme.
+  module Tailwind
+    module_function
+
+    def root
+      File.expand_path("../..", __dir__)
+    end
+
+    def contents
+      <<~CSS
+        /* Generated by bin/rails administratum:tailwind:sync. Do not edit; do not commit. */
+        @import "#{root}/app/assets/tailwind/administratum/theme.css";
+        @import "#{root}/app/assets/tailwind/administratum/components.css";
+        @source "#{root}/app/views";
+        @source "#{root}/app/helpers";
+        @source "#{root}/app/assets/javascripts";
+      CSS
+    end
+
+    def write(path)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, contents)
+      path
+    end
+  end
+end

data/lib/administratum/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Administratum
+  VERSION = "0.2.4"
+end

data/lib/administratum.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "csv"
+require "devise"
+require "ransack"
+require "pagy"
+
+require "administratum/version"
+require "administratum/configuration"
+require "administratum/field_types"
+require "administratum/definition"
+require "administratum/dsl"
+require "administratum/page_dsl"
+require "administratum/paths"
+require "administratum/registry"
+require "administratum/ransackable"
+require "administratum/routing"
+require "administratum/engine"
+
+module Administratum
+  class Error < StandardError; end
+
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  def self.configure
+    yield config
+  end
+
+  def self.registry
+    @registry ||= Registry.new
+  end
+
+  def self.field_types
+    config.field_types
+  end
+
+  # Used by tests to start from a clean configuration.
+  def self.reset_config!
+    @config = Configuration.new
+  end
+end

data/lib/generators/administratum/install/install_generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Administratum
+  module Generators
+    # rails g administratum:install
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :path, type: :string, default: "/administratum", desc: "Where to mount the admin"
+
+      def copy_initializer
+        template "administratum.rb", "config/initializers/administratum.rb"
+      end
+
+      def create_admin_directory
+        empty_directory "app/admin"
+        create_file "app/admin/.keep", ""
+      end
+
+      def copy_migrations
+        rake "administratum:install:migrations"
+      end
+
+      def mount_engine
+        route %(mount Administratum::Engine => "#{options[:path]}")
+      end
+
+      def show_next_steps
+        say <<~TEXT
+
+          Administratum is installed. Next:
+            1. bin/rails db:migrate
+            2. bin/rails administratum:create_user EMAIL=you@example.com
+            3. bin/rails g administratum:resource YourModel
+            4. Visit #{options[:path]}
+        TEXT
+      end
+    end
+  end
+end

data/lib/generators/administratum/install/templates/administratum.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+Administratum.configure do |config|
+  # Shown in the top bar and the browser title.
+  config.app_name = "<%= Rails.application.class.module_parent_name.titleize %> Admin"
+
+  # config.logo = "admin/logo.svg"
+  # config.mailer_sender = "admin@example.com"
+  # config.per_page = 25
+
+  # Controller the admin inherits from. Use it for app-wide before_actions.
+  # config.parent_controller = "ActionController::Base"
+
+  # Partial rendered on the dashboard instead of the resource overview.
+  # config.dashboard = "admin/dashboard"
+
+  # Load your own JS (islands, Turbo, Stimulus…) and CSS into the admin <head>.
+  # config.head = ->(view) { view.javascript_importmap_tags("admin") }
+  # config.head = ->(view) { view.vite_javascript_tag("admin") }
+  # config.head_partial = "admin/head"
+
+  # Colour tokens (--color-adm-*). Applied on top of the bundled stylesheet.
+  # config.theme = { primary: "#7c3aed" }
+  # config.dark_theme = { primary: "#a78bfa" }
+
+  # :bundled uses the stylesheet shipped with the gem; :host means your
+  # Tailwind v4 build includes Administratum (see bin/rails administratum:tailwind:sync).
+  # config.stylesheet = :bundled
+
+  # Custom field types: a partial that receives form:, field:, resource:, value:.
+  # config.field_types.register :tags, partial: "admin/fields/tags"
+
+  # Extra helper modules for admin views.
+  # config.helpers = [ApplicationHelper]
+
+  # Resource templates are looked up in app/views/<view_prefix>/<resource>.
+  # config.view_prefix = "admin"
+
+  # Set to false to hide admin user management.
+  # config.manage_users = true
+end

data/lib/generators/administratum/resource/resource_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Administratum
+  module Generators
+    # rails g administratum:resource Post
+    class ResourceGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      SKIPPED_COLUMNS = %w[id created_at updated_at].freeze
+
+      def create_resource_file
+        template "resource.rb", File.join("app/admin", class_path, "#{file_name}_admin.rb")
+      end
+
+      private
+
+      def model_class
+        class_name.safe_constantize
+      end
+
+      def field_names
+        return [] unless model_class&.table_exists?
+
+        model_class.column_names - SKIPPED_COLUMNS - %w[encrypted_password password_digest]
+      end
+    end
+  end
+end

data/lib/generators/administratum/resource/templates/resource.rb.tt

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class <%= class_name %>Admin < Administratum::Resource
+  # filters :name
+
+  # index do
+  #   column :name
+  #   column :created_at
+  # end
+
+  form do
+<% if field_names.any? -%>
+<% field_names.each do |name| -%>
+    field :<%= name %>
+<% end -%>
+<% else -%>
+    # field :name
+<% end -%>
+  end
+end

data/lib/tasks/administratum.rake

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+namespace :administratum do
+  desc "Create an admin user: EMAIL=you@example.com [PASSWORD=secret]"
+  task create_user: :environment do
+    email = ENV.fetch("EMAIL") { abort "Set EMAIL=you@example.com" }
+    password = ENV["PASSWORD"].presence || SecureRandom.base58(16)
+    user = Administratum::User.create!(email:, password:, password_confirmation: password)
+    puts "Created #{user.email}"
+    puts "Password: #{password}" if ENV["PASSWORD"].blank?
+  end
+
+  namespace :tailwind do
+    desc "Write the import file that adds Administratum to your own Tailwind v4 build"
+    task :sync do
+      require "administratum/tailwind"
+      path = Administratum::Tailwind.write(ENV.fetch("OUTPUT", "app/assets/tailwind/administratum.gen.css"))
+      puts "Wrote #{path}"
+    end
+  end
+end
+
+# Keep the generated import file current wherever assets are built.
+# Declaring the prerequisite (rather than looking the task up) works whichever
+# order the rake files load in.
+# The generated file is gitignored, so on a fresh checkout it only exists after
+# a sync; also hook in when the initializer opts into host mode.
+host_mode = File.exist?("config/initializers/administratum.rb") &&
+            File.read("config/initializers/administratum.rb").match?(/^\s*config\.stylesheet\s*=\s*:host/)
+if host_mode || File.exist?("app/assets/tailwind/administratum.gen.css")
+  %w[assets:precompile vite:build].each { |name| task(name).enhance(["administratum:tailwind:sync"]) }
+end