rsb-admin 0.9.1

data/lib/rsb/admin/settings_schema.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    class SettingsSchema
+      def self.build
+        RSB::Settings::Schema.new('admin') do
+          setting :enabled,
+                  type: :boolean,
+                  default: true,
+                  group: 'General',
+                  description: 'Enable or disable the admin panel'
+
+          setting :app_name,
+                  type: :string,
+                  default: 'Admin',
+                  group: 'Branding',
+                  description: 'Admin panel title'
+
+          setting :company_name,
+                  type: :string,
+                  default: '',
+                  group: 'Branding',
+                  description: 'Company or product name'
+
+          setting :logo_url,
+                  type: :string,
+                  default: '',
+                  group: 'Branding',
+                  description: 'URL to logo image (sidebar header)'
+
+          setting :footer_text,
+                  type: :string,
+                  default: '',
+                  group: 'Branding',
+                  description: 'Custom footer text'
+
+          setting :theme,
+                  type: :string,
+                  default: 'default',
+                  enum: -> { RSB::Admin.themes.keys.map(&:to_s) },
+                  group: 'General',
+                  description: 'Admin panel theme'
+
+          setting :per_page,
+                  type: :integer,
+                  default: 25,
+                  group: 'General',
+                  description: 'Default pagination size'
+
+          setting :require_two_factor,
+                  type: :boolean,
+                  default: false,
+                  group: 'Security',
+                  description: 'Require all admin users to enable two-factor authentication'
+        end
+      end
+    end
+  end
+end

data/lib/rsb/admin/test_kit/helpers.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    module TestKit
+      module Helpers
+        extend ActiveSupport::Concern
+
+        included do
+          teardown do
+            RSB::Admin.reset!
+          end
+        end
+
+        def create_test_admin!(permissions: nil, superadmin: false, no_role: false, email: nil,
+                               password: 'test-password-secure')
+          email ||= "test-admin-#{SecureRandom.hex(4)}@example.com"
+
+          if no_role
+            return RSB::Admin::AdminUser.create!(
+              email: email,
+              password: password,
+              password_confirmation: password
+            )
+          end
+
+          if superadmin || permissions.nil?
+            role = RSB::Admin::Role.create!(
+              name: "Test Superadmin #{SecureRandom.hex(4)}",
+              permissions: { '*' => ['*'] }
+            )
+          else
+            # For empty permissions, use a sentinel value that passes validation
+            perm = permissions.empty? ? { '_none' => [] } : permissions
+            role = RSB::Admin::Role.create!(
+              name: "Test Role #{SecureRandom.hex(4)}",
+              permissions: perm
+            )
+          end
+
+          RSB::Admin::AdminUser.create!(
+            email: email,
+            password: password,
+            password_confirmation: password,
+            role: role
+          )
+        end
+
+        def sign_in_admin(admin, password: 'test-password-secure')
+          post rsb_admin.login_path, params: { email: admin.email, password: password }
+        end
+
+        def assert_admin_authorized
+          assert_response :success
+        end
+
+        # Assert that admin access was denied.
+        #
+        # Checks that the response is either a redirect (302, for unauthenticated users
+        # redirected to login) or a forbidden response (403, for authenticated users
+        # without permission). After RFC-002, 403 responses include a rendered
+        # forbidden page body.
+        #
+        # @return [void]
+        #
+        # @raise [Minitest::Assertion] if response is not 302 or 403
+        #
+        # @example Verify a restricted admin is denied
+        #   restricted = create_test_admin!(permissions: { "dashboard" => ["index"] })
+        #   sign_in_admin(restricted)
+        #   get "/admin/roles"
+        #   assert_admin_denied
+        def assert_admin_denied
+          assert_includes [302, 403], response.status
+        end
+
+        # Assert that the forbidden page is rendered with proper content.
+        #
+        # Verifies that the response has a 403 status and contains the expected
+        # forbidden page elements: "Access Denied" title and explanation message.
+        # Optionally checks for the presence or absence of the "Go to Dashboard" link.
+        #
+        # @param dashboard_link [Boolean, nil] if true, asserts dashboard link is present;
+        #   if false, asserts it's absent; if nil, doesn't check (default: nil)
+        #
+        # @return [void]
+        #
+        # @raise [Minitest::Assertion] if forbidden page is not rendered correctly
+        #
+        # @example Basic forbidden page check
+        #   get "/admin/roles"
+        #   assert_admin_forbidden_page
+        #
+        # @example Verify no dashboard link for no-role user
+        #   get "/admin/dashboard"
+        #   assert_admin_forbidden_page(dashboard_link: false)
+        #
+        # @example Verify dashboard link present
+        #   get "/admin/roles"
+        #   assert_admin_forbidden_page(dashboard_link: true)
+        def assert_admin_forbidden_page(dashboard_link: nil)
+          assert_response :forbidden
+
+          # Use assert_select to properly handle HTML entities
+          assert_select 'h1', text: I18n.t('rsb.admin.shared.access_denied'),
+                              message: "Expected 'Access Denied' title in forbidden page"
+          assert_select 'p', text: I18n.t('rsb.admin.shared.access_denied_message'),
+                             message: 'Expected explanation message in forbidden page'
+
+          return if dashboard_link.nil?
+
+          if dashboard_link
+            assert_select 'a', text: I18n.t('rsb.admin.shared.go_to_dashboard'),
+                               message: "Expected 'Go to Dashboard' link in forbidden page"
+          else
+            assert_select 'a', text: I18n.t('rsb.admin.shared.go_to_dashboard'), count: 0,
+                               message: "Expected NO 'Go to Dashboard' link in forbidden page"
+          end
+        end
+
+        def assert_admin_resource_registered(model_class, category:)
+          registration = RSB::Admin.registry.find_resource(model_class)
+          assert registration, "#{model_class} not registered in admin"
+          assert_equal category, registration.category_name
+        end
+
+        def with_fresh_admin_registry
+          old_registry = RSB::Admin.registry
+          RSB::Admin.instance_variable_set(:@registry, RSB::Admin::Registry.new)
+          yield RSB::Admin.registry
+        ensure
+          RSB::Admin.instance_variable_set(:@registry, old_registry)
+        end
+
+        # Assert that a column header appears in the response body.
+        #
+        # This method verifies that a table column with the given label is rendered
+        # in the current response. It uses `assert_select` to check for a `<th>` tag
+        # containing the label text (case-insensitive). Useful for verifying that
+        # registered columns appear in resource index views.
+        #
+        # @param label [String] the column header text to look for
+        #
+        # @return [void]
+        #
+        # @raise [Minitest::Assertion] if the column header is not found
+        #
+        # @example Verify email column renders
+        #   get "/admin/users"
+        #   assert_admin_column_rendered("Email")
+        #
+        # @example Verify custom column label
+        #   get "/admin/identities"
+        #   assert_admin_column_rendered("Identity Email")
+        def assert_admin_column_rendered(label)
+          assert_select 'th', text: /#{Regexp.escape(label)}/i,
+                              message: "Expected column '#{label}' in table header"
+        end
+
+        # Assert that a filter input exists in the response.
+        #
+        # This method verifies that a filter form field with the given key is rendered
+        # in the current response. It uses `assert_select` to check for an input/select
+        # element with a name attribute matching the filter parameter format `q[key]`.
+        # Useful for verifying that registered filters appear in resource index views.
+        #
+        # @param key [String, Symbol] the filter key to look for
+        #
+        # @return [void]
+        #
+        # @raise [Minitest::Assertion] if the filter input is not found
+        #
+        # @example Verify email filter renders
+        #   get "/admin/users"
+        #   assert_admin_filter_rendered("email")
+        #
+        # @example Verify status filter renders
+        #   get "/admin/identities"
+        #   assert_admin_filter_rendered(:status)
+        def assert_admin_filter_rendered(key)
+          assert_select "[name*='q[#{key}]']",
+                        message: "Expected filter for '#{key}'"
+        end
+
+        # Assert that breadcrumbs contain specific items.
+        #
+        # This method verifies that the breadcrumb navigation contains the given labels
+        # in the current response body. It performs a simple text match for each label,
+        # which is sufficient since breadcrumbs render their labels as plain text.
+        # Useful for verifying navigation context in admin views.
+        #
+        # @param labels [Array<String>] one or more breadcrumb labels to look for
+        #
+        # @return [void]
+        #
+        # @raise [Minitest::Assertion] if any breadcrumb label is not found
+        #
+        # @example Verify dashboard breadcrumb
+        #   get "/admin/users"
+        #   assert_admin_breadcrumbs("Dashboard")
+        #
+        # @example Verify full breadcrumb trail
+        #   get "/admin/identities/123"
+        #   assert_admin_breadcrumbs("Dashboard", "Authentication", "Identities", "#123")
+        def assert_admin_breadcrumbs(*labels)
+          labels.each do |label|
+            assert_match label, response.body,
+                         "Expected breadcrumb '#{label}' in response"
+          end
+        end
+
+        # Assert that a form field exists in the response.
+        #
+        # This method verifies that a form field with the given key is rendered
+        # in the current response. It uses `assert_select` to check for an input/select/textarea
+        # element with a name attribute containing the field key in Rails form format `[key]`.
+        # Useful for verifying that registered form fields appear in new/edit views.
+        #
+        # @param key [String, Symbol] the form field key to look for
+        #
+        # @return [void]
+        #
+        # @raise [Minitest::Assertion] if the form field is not found
+        #
+        # @example Verify email field renders
+        #   get "/admin/users/new"
+        #   assert_admin_form_field("email")
+        #
+        # @example Verify name field renders
+        #   get "/admin/users/1/edit"
+        #   assert_admin_form_field(:name)
+        def assert_admin_form_field(key)
+          assert_select "[name*='[#{key}]']",
+                        message: "Expected form field '#{key}'"
+        end
+
+        # Assert that page tabs are rendered for a static page.
+        #
+        # This method verifies that page action tabs with the given labels are rendered
+        # in the current response body. It performs a simple text match for each label,
+        # which works because page tabs render their labels as plain text within tab links.
+        # Useful for verifying that registered page actions appear as tabs.
+        #
+        # @param labels [Array<String>] one or more page tab labels to look for
+        #
+        # @return [void]
+        #
+        # @raise [Minitest::Assertion] if any page tab label is not found
+        #
+        # @example Verify analytics page tabs
+        #   get "/admin/analytics"
+        #   assert_admin_page_tabs("Overview", "By Metric")
+        #
+        # @example Verify settings page tabs
+        #   get "/admin/settings"
+        #   assert_admin_page_tabs("General", "Security", "Billing")
+        def assert_admin_page_tabs(*labels)
+          labels.each do |label|
+            assert_match label, response.body,
+                         "Expected page tab '#{label}' in response"
+          end
+        end
+
+        # Assert that the current theme CSS is loaded in the layout.
+        #
+        # This method verifies that the stylesheet link tag for the specified theme
+        # is present in the current response. It first checks that the theme is registered,
+        # then uses `assert_select` to verify the CSS link tag exists with the theme's
+        # CSS path in its href attribute. Useful for verifying theme application.
+        #
+        # @param theme_key [String, Symbol] the theme key to verify (e.g., :default, :modern)
+        #
+        # @return [void]
+        #
+        # @raise [Minitest::Assertion] if the theme is not registered or CSS link is not found
+        #
+        # @example Verify default theme is loaded
+        #   get "/admin/dashboard"
+        #   assert_admin_theme(:default)
+        #
+        # @example Verify modern theme is loaded
+        #   # After configuring: RSB::Admin.configuration.theme = :modern
+        #   get "/admin/dashboard"
+        #   assert_admin_theme(:modern)
+        def assert_admin_theme(theme_key)
+          theme = RSB::Admin.themes[theme_key.to_sym]
+          assert theme, "Theme '#{theme_key}' not registered"
+          assert_select "link[href*='#{theme.css}']",
+                        message: "Expected theme CSS '#{theme.css}' in layout"
+        end
+
+        # Assert that a custom dashboard page is registered with the given controller.
+        #
+        # Verifies that `RSB::Admin.registry.dashboard_page` is present and
+        # its controller matches the expected value. Useful for extension gems
+        # that register a custom dashboard to verify their registration works.
+        #
+        # @param controller [String] the expected controller path
+        #
+        # @return [void]
+        #
+        # @raise [Minitest::Assertion] if no dashboard override or wrong controller
+        #
+        # @example Verify dashboard override
+        #   RSB::Admin.registry.register_dashboard(controller: "admin/dashboard")
+        #   assert_admin_dashboard_override(controller: "admin/dashboard")
+        def assert_admin_dashboard_override(controller:)
+          page = RSB::Admin.registry.dashboard_page
+          assert page, 'Expected a dashboard override to be registered'
+          assert_equal controller, page.controller,
+                       "Expected dashboard controller '#{controller}', got '#{page.controller}'"
+        end
+      end
+    end
+  end
+end

data/lib/rsb/admin/test_kit/resource_test_case.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    module TestKit
+      class ResourceTestCase < ActionDispatch::IntegrationTest
+        include RSB::Admin::TestKit::Helpers
+
+        class_attribute :resource_class
+        class_attribute :category
+        class_attribute :record_factory
+        class_attribute :resource_registry_block
+
+        setup do
+          # Re-register the resource if a registry block is provided
+          self.class.resource_registry_block&.call
+          @superadmin = create_test_admin!(superadmin: true)
+          @registration = RSB::Admin.registry.find_resource(resource_class) if resource_class
+        end
+
+        # Define how to register the resource (called in setup after reset)
+        def self.registers_in_admin(&block)
+          self.resource_registry_block = block
+        end
+
+        def test_resource_is_registered_in_admin_registry
+          skip 'no resource_class configured' unless resource_class
+          assert @registration, "#{resource_class} not found in admin registry"
+          assert_equal category, @registration.category_name
+        end
+
+        def test_index_page_renders
+          skip 'no resource_class configured' unless resource_class
+          skip 'no :index action registered' unless @registration&.action?(:index)
+          record_factory&.call
+          sign_in_admin(@superadmin)
+          get admin_resources_path
+          assert_admin_authorized
+        end
+
+        def test_show_page_renders
+          skip 'no resource_class configured' unless resource_class
+          skip 'no :show action registered' unless @registration&.action?(:show)
+          record = record_factory&.call
+          skip 'no record_factory configured' unless record
+          sign_in_admin(@superadmin)
+          get admin_resource_path(record)
+          assert_admin_authorized
+        end
+
+        def test_admin_with_no_permissions_is_denied
+          skip 'no resource_class configured' unless resource_class
+          skip 'no :index action registered' unless @registration&.action?(:index)
+          restricted = create_test_admin!(permissions: {})
+          sign_in_admin(restricted)
+          get admin_resources_path
+          assert_admin_denied
+        end
+
+        # Contract test: Verify that registered columns appear in the index table.
+        #
+        # This test ensures that all columns defined for the resource via the DSL
+        # (or auto-detected from the model schema) are rendered as table headers
+        # in the index view. It creates a test record, signs in as superadmin,
+        # visits the index page, and asserts that each column's label appears
+        # in a `<th>` element. Skips if no records exist (table won't render).
+        #
+        # For auto-detected columns, assertions are more forgiving since some
+        # columns may be filtered out by the view (e.g., SKIP_INDEX_COLUMNS).
+        # For explicitly-defined columns, all columns must render.
+        #
+        # @return [void]
+        #
+        # @raise [Minitest::Skip] if resource_class is not configured, :index action not registered, or no records exist
+        def test_index_page_renders_registered_columns
+          skip 'no resource_class configured' unless resource_class
+          skip 'no :index action' unless @registration&.action?(:index)
+          record = record_factory&.call
+          skip 'no record_factory configured or record creation failed' unless record&.persisted?
+          sign_in_admin(@superadmin)
+          get admin_resources_path
+          assert_admin_authorized
+
+          # Verify table renders (requires at least one th element)
+          begin
+            assert_select 'th', minimum: 1
+          rescue Minitest::Assertion
+            skip 'table not rendered (no records found in view)'
+          end
+
+          # Check columns - be forgiving with auto-detected columns
+          auto_detected = @registration.columns.nil?
+          @registration.index_columns.each do |col|
+            next if col.label.blank?
+
+            if auto_detected
+              # For auto-detected columns, silently skip if column doesn't render
+              # (it may be filtered by view logic we don't control)
+              begin
+                assert_admin_column_rendered(col.label)
+              rescue Minitest::Assertion
+                # Skip this column
+                next
+              end
+            else
+              # For explicitly-defined columns, all must render
+              assert_admin_column_rendered(col.label)
+            end
+          end
+        end
+
+        # Contract test: Verify that registered filters appear in the index view.
+        #
+        # This test ensures that all filters defined for the resource via the DSL
+        # are rendered as form inputs in the index view. It signs in as superadmin,
+        # visits the index page, and asserts that each filter's input element exists
+        # with the correct name attribute format `q[key]`.
+        #
+        # @return [void]
+        #
+        # @raise [Minitest::Skip] if resource_class is not configured or no filters defined
+        def test_index_page_renders_registered_filters
+          skip 'no resource_class configured' unless resource_class
+          skip 'no filters' unless @registration&.filters&.any?
+          sign_in_admin(@superadmin)
+          get admin_resources_path
+          assert_admin_authorized
+          @registration.filters.each do |filter|
+            assert_admin_filter_rendered(filter.key)
+          end
+        end
+
+        # Contract test: Verify that registered form fields appear in the new form.
+        #
+        # This test ensures that all form fields defined for the resource via the DSL
+        # (or auto-detected from the model schema) are rendered as form inputs in the
+        # new view. It signs in as superadmin, visits the new page, and asserts that
+        # each field's input element exists with the correct name attribute.
+        #
+        # @return [void]
+        #
+        # @raise [Minitest::Skip] if resource_class is not configured, :new action not registered, or no form_fields defined
+        def test_new_page_renders_registered_form_fields
+          skip 'no resource_class configured' unless resource_class
+          skip 'no :new action' unless @registration&.action?(:new)
+          skip 'no form_fields' unless @registration&.form_fields&.any?
+          sign_in_admin(@superadmin)
+          get "#{admin_resources_path}/new"
+          assert_admin_authorized
+          @registration.new_form_fields.each do |field|
+            assert_admin_form_field(field.key)
+          end
+        end
+
+        # Contract test: Verify that breadcrumbs are rendered in resource views.
+        #
+        # This test ensures that the breadcrumb navigation is present in resource views,
+        # including at minimum the "Dashboard" home breadcrumb. It signs in as superadmin,
+        # visits the index page, and asserts that the dashboard breadcrumb appears.
+        #
+        # @return [void]
+        #
+        # @raise [Minitest::Skip] if resource_class is not configured or :index action not registered
+        def test_breadcrumbs_are_rendered
+          skip 'no resource_class configured' unless resource_class
+          skip 'no :index action' unless @registration&.action?(:index)
+          sign_in_admin(@superadmin)
+          get admin_resources_path
+          assert_admin_authorized
+          assert_admin_breadcrumbs('Dashboard')
+        end
+
+        private
+
+        def create_resource(**overrides)
+          record_factory&.call(**overrides)
+        end
+
+        def admin_resources_path
+          rsb_admin.send(:"#{resource_class.model_name.route_key}_path")
+        rescue NoMethodError
+          "/admin/#{resource_class.model_name.route_key}"
+        end
+
+        def admin_resource_path(record)
+          rsb_admin.send(:"#{resource_class.model_name.singular_route_key}_path", record)
+        rescue NoMethodError
+          "/admin/#{resource_class.model_name.route_key}/#{record.id}"
+        end
+      end
+    end
+  end
+end

data/lib/rsb/admin/test_kit.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'rsb/admin/test_kit/helpers'
+require 'rsb/admin/test_kit/resource_test_case'
+
+module RSB
+  module Admin
+    module TestKit
+    end
+  end
+end

data/lib/rsb/admin/theme_definition.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # Represents a theme definition for the admin panel.
+    #
+    # ThemeDefinition is an immutable data structure that describes a visual theme
+    # for the admin interface, including CSS, JavaScript, and optional view overrides.
+    #
+    # @!attribute [r] key
+    #   @return [Symbol] unique theme identifier (e.g., :default, :modern)
+    # @!attribute [r] label
+    #   @return [String] the human-readable theme name
+    # @!attribute [r] css
+    #   @return [String] the asset path for the theme's CSS file
+    # @!attribute [r] js
+    #   @return [String, nil] optional asset path for the theme's JavaScript file
+    # @!attribute [r] views_path
+    #   @return [String, nil] optional view override path prefix
+    #
+    # @example Building a minimal theme
+    #   theme = ThemeDefinition.new(
+    #     key: :default,
+    #     label: "Default Theme",
+    #     css: "rsb/admin/themes/default",
+    #     js: nil,
+    #     views_path: nil
+    #   )
+    #
+    # @example Building a full-featured theme
+    #   theme = ThemeDefinition.new(
+    #     key: :modern,
+    #     label: "Modern Theme",
+    #     css: "rsb/admin/themes/modern",
+    #     js: "rsb/admin/themes/modern",
+    #     views_path: "rsb/admin/themes/modern/views"
+    #   )
+    ThemeDefinition = Data.define(
+      :key,        # Symbol — :default, :modern, or custom
+      :label,      # String
+      :css,        # String — asset path
+      :js,         # String | nil — asset path for optional JS
+      :views_path  # String | nil — view override path prefix
+    )
+  end
+end

data/lib/rsb/admin/themes/modern.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    module Themes
+      # Self-contained registration for the Modern theme.
+      #
+      # This module encapsulates all registration logic for the built-in Modern
+      # theme. It exists as a clear boundary so the modern theme can eventually
+      # be extracted to a separate gem (`rsb-admin-modern-theme`).
+      #
+      # To extract to a separate gem:
+      # 1. Move this module + assets + views to rsb-admin-modern-theme gem
+      # 2. Replace the call in RSB::Admin.register_built_in_themes with a
+      #    dependency on the new gem
+      # 3. The gem's engine calls RSB::Admin::Themes::Modern.register! in
+      #    an initializer
+      #
+      # @example Register the modern theme
+      #   RSB::Admin::Themes::Modern.register!
+      module Modern
+        # Registers the Modern theme with RSB::Admin.
+        #
+        # This method registers the theme definition including CSS (with dark
+        # mode support), JavaScript (toggle + persistence), and view overrides
+        # (sidebar, header).
+        #
+        # @return [RSB::Admin::ThemeDefinition] the registered theme definition
+        #
+        # @example
+        #   RSB::Admin::Themes::Modern.register!
+        #   RSB::Admin.themes[:modern]
+        #   # => #<data RSB::Admin::ThemeDefinition key=:modern, ...>
+        def self.register!
+          RSB::Admin.register_theme :modern,
+                                    label: 'Modern',
+                                    css: 'rsb/admin/themes/modern',
+                                    js: 'rsb/admin/themes/modern',
+                                    views_path: 'rsb/admin/themes/modern/views'
+        end
+      end
+    end
+  end
+end

data/lib/rsb/admin/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative '../../../../lib/rsb/version' unless defined?(RSB::VERSION)
+
+module RSB
+  module Admin
+    VERSION = RSB::VERSION
+  end
+end