rsb-admin 0.9.1

data/lib/rsb/admin/page_registration.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # Represents a custom page registration in the admin panel.
+    #
+    # PageRegistration is an immutable data structure that describes a custom admin
+    # page (not a resource-based CRUD interface). It handles page metadata, controller
+    # routing, and custom actions.
+    #
+    # @!attribute [r] key
+    #   @return [Symbol] unique identifier for this page
+    # @!attribute [r] label
+    #   @return [String] the human-readable page name
+    # @!attribute [r] icon
+    #   @return [String, nil] optional icon identifier
+    # @!attribute [r] controller
+    #   @return [String] the controller path (e.g., "admin/dashboard")
+    # @!attribute [r] category_name
+    #   @return [String] the category this page belongs to
+    # @!attribute [r] actions
+    #   @return [Array<Hash>] array of action definitions with :key, :label, :method, :confirm
+    #
+    # @example Building a simple dashboard page
+    #   page = PageRegistration.build(
+    #     key: :dashboard,
+    #     label: "Dashboard",
+    #     icon: "home",
+    #     controller: "admin/dashboard",
+    #     category_name: "System"
+    #   )
+    #
+    # @example Building a page with custom actions
+    #   page = PageRegistration.build(
+    #     key: :usage,
+    #     label: "Usage Reports",
+    #     controller: "admin/usage",
+    #     category_name: "Billing",
+    #     actions: [
+    #       { key: :index, label: "Overview" },
+    #       { key: :export, label: "Export CSV", method: :post }
+    #     ]
+    #   )
+    PageRegistration = Data.define(
+      :key,           # Symbol
+      :label,         # String
+      :icon,          # String | nil
+      :controller,    # String
+      :category_name, # String
+      :actions        # Array<Hash> — [{key: :index, label: "Overview"}, ...]
+    )
+
+    class PageRegistration
+      # Build a PageRegistration with normalized actions.
+      #
+      # @param key [Symbol, String] unique identifier for the page
+      # @param label [String] the display label
+      # @param icon [String, nil] optional icon identifier
+      # @param controller [String] the controller path
+      # @param category_name [String] the category name
+      # @param actions [Array<Hash>] array of action definitions (default: [])
+      # @return [PageRegistration] a frozen, immutable page registration
+      #
+      # @example
+      #   PageRegistration.build(
+      #     key: :settings,
+      #     label: "Settings",
+      #     controller: "admin/settings",
+      #     category_name: "System"
+      #   )
+      def self.build(key:, label:, controller:, category_name:, icon: nil, actions: [])
+        new(
+          key: key.to_sym,
+          label: label,
+          icon: icon,
+          controller: controller,
+          category_name: category_name,
+          actions: normalize_actions(actions)
+        )
+      end
+
+      # Wrap old-style Hash pages into PageRegistration for backwards compatibility.
+      #
+      # @param hash [Hash] legacy page hash with :key, :label, :icon, :controller, :category_name, :actions
+      # @return [PageRegistration] a frozen page registration
+      #
+      # @example
+      #   legacy = { key: :sessions, label: "Sessions", controller: "admin/sessions", category_name: "Auth" }
+      #   page = PageRegistration.from_hash(legacy)
+      def self.from_hash(hash)
+        build(
+          key: hash[:key],
+          label: hash[:label],
+          icon: hash[:icon],
+          controller: hash[:controller],
+          category_name: hash[:category_name],
+          actions: hash[:actions] || []
+        )
+      end
+
+      # Get all action keys for this page.
+      #
+      # @return [Array<Symbol>] array of action keys
+      #
+      # @example
+      #   page.action_keys #=> [:index, :show, :export]
+      def action_keys
+        actions.map { |a| a[:key] }
+      end
+
+      # Find an action definition by key.
+      #
+      # @param key [Symbol, String] the action key to find
+      # @return [Hash, nil] the action hash or nil if not found
+      #
+      # @example
+      #   action = page.find_action(:export)
+      #   action[:method] #=> :post
+      def find_action(key)
+        actions.find { |a| a[:key] == key.to_sym }
+      end
+
+      # Normalize action definitions with defaults.
+      #
+      # @param actions [Array<Hash>] raw action definitions
+      # @return [Array<Hash>] normalized action hashes
+      # @api private
+      private_class_method def self.normalize_actions(actions)
+        actions.map do |action|
+          {
+            key: action[:key].to_sym,
+            label: action[:label] || action[:key].to_s.humanize,
+            method: (action[:method] || :get).to_sym,
+            confirm: action[:confirm]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/rsb/admin/registry.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    class Registry
+      attr_reader :categories, :dashboard_page
+
+      def initialize
+        @categories = {}
+        @dashboard_page = nil
+      end
+
+      # Register a category with resources and pages
+      def register_category(name, &block)
+        category = @categories[name] ||= CategoryRegistration.new(name)
+        category.instance_eval(&block) if block_given?
+        category
+      end
+
+      # Register resources into an existing category
+      def register_in(category_name, &block)
+        register_category(category_name, &block)
+      end
+
+      # Register a pre-built CategoryRegistration object
+      def register(category_registration)
+        name = category_registration.name
+        if @categories[name]
+          @categories[name].merge(category_registration)
+        else
+          @categories[name] = category_registration
+        end
+      end
+
+      # Register a custom dashboard page override.
+      #
+      # When registered, the built-in dashboard controller dispatches to the
+      # custom controller instead of rendering the default view. Calling this
+      # method multiple times replaces the previous registration (last-write-wins).
+      #
+      # @param controller [String] the controller path (e.g., "admin/dashboard")
+      # @param actions [Array<Hash>] optional action definitions for tab navigation
+      #   (e.g., `[{ key: :index, label: "Overview" }, { key: :metrics, label: "Metrics" }]`)
+      #
+      # @return [PageRegistration] the created dashboard page registration
+      #
+      # @raise [ArgumentError] if controller is blank
+      #
+      # @example Simple override
+      #   registry.register_dashboard(controller: "admin/dashboard")
+      #
+      # @example Override with tab actions
+      #   registry.register_dashboard(
+      #     controller: "admin/dashboard",
+      #     actions: [
+      #       { key: :index, label: "Overview" },
+      #       { key: :metrics, label: "Metrics" }
+      #     ]
+      #   )
+      def register_dashboard(controller:, actions: [])
+        raise ArgumentError, 'controller must be present' if controller.nil? || controller.to_s.strip.empty?
+
+        @dashboard_page = PageRegistration.build(
+          key: :dashboard,
+          label: 'Dashboard',
+          icon: 'home',
+          controller: controller,
+          category_name: 'System',
+          actions: actions
+        )
+      end
+
+      # Query
+      def find_resource(model_class)
+        @categories.each_value do |cat|
+          resource = cat.find_resource(model_class)
+          return resource if resource
+        end
+        nil
+      end
+
+      def find_resource_by_route_key(key)
+        all_resources.find { |r| r.route_key == key }
+      end
+
+      def find_page_by_key(key)
+        key_sym = key.to_sym
+        categories.each_value do |category|
+          category.pages.each do |page|
+            return page if page.key == key_sym
+          end
+        end
+        nil
+      end
+
+      def category?(name)
+        @categories.key?(name)
+      end
+
+      def all_resources
+        @categories.values.flat_map(&:resources)
+      end
+
+      def all_pages
+        @categories.values.flat_map(&:pages)
+      end
+    end
+  end
+end

data/lib/rsb/admin/resource_dsl_context.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # DSL context for defining resource columns, filters, and form fields inline.
+    #
+    # This class provides the block context for the resource registration DSL.
+    # It allows you to declaratively define columns, filters, and form fields
+    # within a resource registration block.
+    #
+    # @!attribute [r] columns
+    #   @return [Array<ColumnDefinition>] the column definitions added via {#column}
+    #
+    # @!attribute [r] filters
+    #   @return [Array<FilterDefinition>] the filter definitions added via {#filter}
+    #
+    # @!attribute [r] form_fields
+    #   @return [Array<FormFieldDefinition>] the form field definitions added via {#form_field}
+    #
+    # @example Defining columns, filters, and form fields for a User resource
+    #   registry.register_category "Users" do
+    #     resource User, icon: "users", actions: [:index, :show] do
+    #       column :id, link: true
+    #       column :email, sortable: true
+    #       column :status, formatter: :badge
+    #
+    #       filter :email, type: :text
+    #       filter :status, type: :select, options: %w[active suspended]
+    #
+    #       form_field :email, type: :email, required: true
+    #       form_field :name, type: :text, required: true
+    #     end
+    #   end
+    #
+    # @see CategoryRegistration#resource
+    # @see ColumnDefinition
+    # @see FilterDefinition
+    # @see FormFieldDefinition
+    class ResourceDSLContext
+      attr_reader :columns, :filters, :form_fields
+
+      # Initialize a new DSL context with empty arrays.
+      #
+      # @api private
+      def initialize
+        @columns = []
+        @filters = []
+        @form_fields = []
+      end
+
+      # Define a column to display on index and show pages.
+      #
+      # Columns control how data is displayed in tables and detail views.
+      # Options are passed directly to {ColumnDefinition.build}.
+      #
+      # @param key [Symbol, String] the attribute name to display
+      # @param options [Hash] column configuration options
+      # @option options [String] :label the human-readable column header
+      # @option options [Boolean] :sortable whether the column can be sorted
+      # @option options [Symbol, Proc] :formatter optional formatter for the column value
+      # @option options [Boolean] :link whether to render the value as a link
+      # @option options [Array<Symbol>] :visible_on contexts where visible (`:index`, `:show`)
+      #
+      # @return [void]
+      #
+      # @example Basic column
+      #   column :email
+      #
+      # @example Column with options
+      #   column :status, label: "Account Status", sortable: true, formatter: :badge
+      #
+      # @example Column visible only on show page
+      #   column :notes, visible_on: [:show]
+      #
+      # @see ColumnDefinition.build
+      def column(key, **options)
+        @columns << ColumnDefinition.build(key, **options)
+      end
+
+      # Define a filter for querying records on the index page.
+      #
+      # Filters allow users to narrow down the displayed records.
+      # Options are passed directly to {FilterDefinition.build}.
+      #
+      # @param key [Symbol, String] the attribute name to filter on
+      # @param options [Hash] filter configuration options
+      # @option options [String] :label the human-readable filter label
+      # @option options [Symbol] :type the filter type (`:text`, `:select`, `:boolean`, `:date_range`, `:number_range`)
+      # @option options [Array, Proc] :options options for select-type filters
+      # @option options [Symbol, Proc] :scope custom filtering logic
+      #
+      # @return [void]
+      #
+      # @example Text filter
+      #   filter :email, type: :text
+      #
+      # @example Select filter with options
+      #   filter :status, type: :select, options: %w[active suspended banned]
+      #
+      # @example Filter with custom scope
+      #   filter :search, scope: ->(rel, val) { rel.where("name LIKE ? OR email LIKE ?", "%#{val}%", "%#{val}%") }
+      #
+      # @see FilterDefinition.build
+      def filter(key, **options)
+        @filters << FilterDefinition.build(key, **options)
+      end
+
+      # Define a form field for new and edit forms.
+      #
+      # Form fields control how data is entered on create/update forms.
+      # Options are passed directly to {FormFieldDefinition.build}.
+      #
+      # @param key [Symbol, String] the attribute name for this field
+      # @param options [Hash] form field configuration options
+      # @option options [String] :label the human-readable field label
+      # @option options [Symbol] :type the field type (`:text`, `:textarea`, `:select`, `:checkbox`, `:number`, `:email`, `:password`, `:datetime`, `:hidden`, `:json`)
+      # @option options [Array, Proc] :options options for select-type fields
+      # @option options [Boolean] :required whether the field is required
+      # @option options [String] :hint optional help text displayed below the field
+      # @option options [Array<Symbol>] :visible_on contexts where visible (`:new`, `:edit`)
+      #
+      # @return [void]
+      #
+      # @example Required email field
+      #   form_field :email, type: :email, required: true
+      #
+      # @example Textarea with hint
+      #   form_field :bio, type: :textarea, hint: "Tell us about yourself"
+      #
+      # @example Field visible only on new form
+      #   form_field :password, type: :password, required: true, visible_on: [:new]
+      #
+      # @see FormFieldDefinition.build
+      def form_field(key, **options)
+        @form_fields << FormFieldDefinition.build(key, **options)
+      end
+    end
+  end
+end

data/lib/rsb/admin/resource_registration.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # Represents a registered resource in the admin panel.
+    #
+    # ResourceRegistration stores metadata about a model that should be accessible
+    # in the admin interface, including its category, actions, icon, and optionally
+    # a custom controller to handle requests.
+    #
+    # @example Registering a resource with default generic controller
+    #   ResourceRegistration.new(
+    #     model_class: User,
+    #     category_name: "Users",
+    #     icon: "user",
+    #     actions: [:index, :show]
+    #   )
+    #
+    # @example Registering a resource with custom controller
+    #   ResourceRegistration.new(
+    #     model_class: Identity,
+    #     category_name: "Authentication",
+    #     icon: "users",
+    #     actions: [:index, :show, :suspend, :activate],
+    #     controller: "rsb/auth/admin/identities"
+    #   )
+    class ResourceRegistration
+      # @return [Class] the ActiveRecord model class this registration represents
+      attr_reader :model_class
+
+      # @return [String] the name of the category this resource belongs to
+      attr_reader :category_name
+
+      # @return [String, nil] the icon identifier for this resource
+      attr_reader :icon
+
+      # @return [String] the human-readable label for this resource
+      attr_reader :label
+
+      # @return [Array<Symbol>] the list of allowed actions for this resource
+      attr_reader :actions
+
+      # @return [Hash] additional options passed during registration
+      attr_reader :options
+
+      # @return [String, nil] the controller path for custom controller (e.g., "rsb/auth/admin/identities")
+      attr_reader :controller
+
+      # @return [Array<ColumnDefinition>, nil] column definitions for this resource
+      attr_reader :columns
+
+      # @return [Array<FilterDefinition>, nil] filter definitions for this resource
+      attr_reader :filters
+
+      # @return [Array<FormFieldDefinition>, nil] form field definitions for this resource
+      attr_reader :form_fields
+
+      # @return [Integer, nil] number of records per page
+      attr_reader :per_page
+
+      # @return [Hash, nil] default sort configuration (e.g., { column: :created_at, direction: :desc })
+      attr_reader :default_sort
+
+      # @return [Array<Symbol>, nil] searchable field names
+      attr_reader :search_fields
+
+      # Initialize a new resource registration.
+      #
+      # @param model_class [Class] the ActiveRecord model class
+      # @param category_name [String] the category this resource belongs to
+      # @param icon [String, nil] optional icon identifier
+      # @param label [String, nil] optional custom label (defaults to humanized plural model name)
+      # @param actions [Array<Symbol>] allowed actions (default: [])
+      # @param controller [String, nil] optional custom controller path for delegation
+      # @param columns [Array<ColumnDefinition>, nil] column definitions
+      # @param filters [Array<FilterDefinition>, nil] filter definitions
+      # @param form_fields [Array<FormFieldDefinition>, nil] form field definitions
+      # @param per_page [Integer, nil] records per page
+      # @param default_sort [Hash, nil] default sort configuration
+      # @param search_fields [Array<Symbol>, nil] searchable field names
+      # @param options [Hash] additional options
+      def initialize(model_class:, category_name:, icon: nil, label: nil, actions: [], controller: nil,
+                     columns: nil, filters: nil, form_fields: nil,
+                     per_page: nil, default_sort: nil, search_fields: nil,
+                     **options)
+        @model_class = model_class
+        @category_name = category_name
+        @icon = icon
+        @label = label || model_class.model_name.human.pluralize
+        @actions = actions.map(&:to_sym)
+        @controller = controller
+        @columns = columns
+        @filters = filters
+        @form_fields = form_fields
+        @per_page = per_page
+        @default_sort = default_sort
+        @search_fields = search_fields&.map(&:to_sym)
+        @options = options
+      end
+
+      # Check if a specific action is allowed for this resource.
+      #
+      # @param action [Symbol, String] the action to check
+      # @return [Boolean] true if the action is in the allowed actions list
+      def action?(action)
+        @actions.include?(action.to_sym)
+      end
+
+      # Check if this resource uses a custom controller.
+      #
+      # When true, requests to this resource will be delegated to the custom
+      # controller instead of being handled by the generic ResourcesController.
+      #
+      # @return [Boolean] true if a custom controller is configured
+      def custom_controller?
+        @controller.present?
+      end
+
+      # Get the route key for this resource's model.
+      #
+      # @return [String] the pluralized route key (e.g., "identities" for Identity model)
+      def route_key
+        model_class.model_name.route_key
+      end
+
+      # Returns columns visible on index views.
+      #
+      # If no columns were explicitly defined via the DSL, this method
+      # auto-detects columns from the model's database schema, excluding
+      # sensitive columns (passwords, tokens, etc.).
+      #
+      # @return [Array<ColumnDefinition>] columns to display on index view
+      #
+      # @example With explicit columns
+      #   registration.columns #=> [ColumnDefinition(:id), ColumnDefinition(:email)]
+      #   registration.index_columns #=> [ColumnDefinition(:id), ColumnDefinition(:email)]
+      #
+      # @example With auto-detection
+      #   registration.columns #=> nil
+      #   registration.index_columns #=> [ColumnDefinition(:id), ColumnDefinition(:email), ...]
+      #
+      # @see #auto_detect_columns
+      def index_columns
+        return auto_detect_columns.select { |c| c.visible_on?(:index) } unless columns
+
+        columns.select { |c| c.visible_on?(:index) }
+      end
+
+      # Returns columns visible on show (detail) views.
+      #
+      # If no columns were explicitly defined via the DSL, this method
+      # auto-detects columns from the model's database schema, excluding
+      # sensitive columns (passwords, tokens, etc.).
+      #
+      # Show views typically display more columns than index views, including
+      # timestamps and metadata fields.
+      #
+      # @return [Array<ColumnDefinition>] columns to display on show view
+      #
+      # @see #auto_detect_columns
+      def show_columns
+        return auto_detect_columns.select { |c| c.visible_on?(:show) } unless columns
+
+        columns.select { |c| c.visible_on?(:show) }
+      end
+
+      # Returns form fields for new (create) forms.
+      #
+      # If no form fields were explicitly defined via the DSL, this method
+      # auto-detects editable fields from the model's database schema,
+      # excluding sensitive columns, ID, and timestamps.
+      #
+      # @return [Array<FormFieldDefinition>] form fields for new form
+      #
+      # @example With explicit form fields
+      #   registration.form_fields #=> [FormFieldDefinition(:email), FormFieldDefinition(:name)]
+      #   registration.new_form_fields #=> [FormFieldDefinition(:email), FormFieldDefinition(:name)]
+      #
+      # @example With auto-detection
+      #   registration.form_fields #=> nil
+      #   registration.new_form_fields #=> [FormFieldDefinition(:email), FormFieldDefinition(:name), ...]
+      #
+      # @see #auto_detect_form_fields
+      def new_form_fields
+        return auto_detect_form_fields.select { |f| f.visible_on?(:new) } unless form_fields
+
+        form_fields.select { |f| f.visible_on?(:new) }
+      end
+
+      # Returns form fields for edit (update) forms.
+      #
+      # If no form fields were explicitly defined via the DSL, this method
+      # auto-detects editable fields from the model's database schema,
+      # excluding sensitive columns, ID, and timestamps.
+      #
+      # @return [Array<FormFieldDefinition>] form fields for edit form
+      #
+      # @see #auto_detect_form_fields
+      def edit_form_fields
+        return auto_detect_form_fields.select { |f| f.visible_on?(:edit) } unless form_fields
+
+        form_fields.select { |f| f.visible_on?(:edit) }
+      end
+
+      private
+
+      # Column names that contain sensitive data and should never be displayed.
+      #
+      # These columns are excluded from auto-detection to prevent accidental
+      # exposure of passwords, tokens, and other secrets in the admin interface.
+      #
+      # @api private
+      SENSITIVE_COLUMNS = %w[
+        password_digest token encrypted_password
+        reset_password_token confirmation_token
+        unlock_token otp_secret
+      ].freeze
+
+      # Column names that should be excluded from auto-detected form fields.
+      #
+      # These are typically read-only columns managed by the database or
+      # framework (ID, timestamps) that users should not edit directly.
+      #
+      # @api private
+      SKIP_FORM_COLUMNS = %w[
+        id created_at updated_at
+      ].freeze
+
+      # Column names that should be excluded from index tables.
+      #
+      # These are typically noisy columns (timestamps, metadata) that clutter
+      # table views but are useful in detail views.
+      #
+      # @api private
+      SKIP_INDEX_COLUMNS = %w[
+        created_at updated_at metadata
+      ].freeze
+
+      # Auto-detect column definitions from the model's database schema.
+      #
+      # This method introspects the model's columns and creates a
+      # {ColumnDefinition} for each non-sensitive column. Used as a fallback
+      # when no explicit columns are defined via the DSL.
+      #
+      # Columns in SKIP_INDEX_COLUMNS are marked as visible only on show views,
+      # not index views.
+      #
+      # @return [Array<ColumnDefinition>] auto-detected column definitions
+      # @return [Array] empty array if the model doesn't respond to `column_names`
+      #
+      # @api private
+      def auto_detect_columns
+        return [] unless model_class.respond_to?(:column_names)
+
+        model_class.column_names
+                   .reject { |c| SENSITIVE_COLUMNS.include?(c) }
+                   .map do |c|
+                     # Skip index for timestamp/metadata columns
+                     if SKIP_INDEX_COLUMNS.include?(c)
+                       ColumnDefinition.build(c.to_sym, visible_on: [:show])
+                     else
+                       ColumnDefinition.build(c.to_sym)
+                     end
+                   end
+      end
+
+      # Auto-detect form field definitions from the model's database schema.
+      #
+      # This method introspects the model's columns and creates a
+      # {FormFieldDefinition} for each editable column. Excludes sensitive
+      # columns, ID, and timestamps. Used as a fallback when no explicit
+      # form fields are defined via the DSL.
+      #
+      # @return [Array<FormFieldDefinition>] auto-detected form field definitions
+      # @return [Array] empty array if the model doesn't respond to `column_names`
+      #
+      # @api private
+      def auto_detect_form_fields
+        return [] unless model_class.respond_to?(:column_names)
+
+        model_class.column_names
+                   .reject { |c| SENSITIVE_COLUMNS.include?(c) || SKIP_FORM_COLUMNS.include?(c) }
+                   .map { |c| FormFieldDefinition.build(c.to_sym) }
+      end
+    end
+  end
+end