rsb-admin 0.9.1

data/lib/generators/rsb/admin/theme/theme_generator.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # Rails generator for scaffolding custom admin themes.
+    #
+    # This generator creates either a host-app theme (default) or a complete
+    # Rails engine gem for distributable themes. Both modes include:
+    # - CSS with all required `--rsb-admin-*` variables
+    # - View overrides (sidebar and header)
+    # - Theme registration code
+    #
+    # @example Generate a host-app theme
+    #   rails generate rsb:admin:theme corporate
+    #
+    # @example Generate a theme as a Rails engine gem
+    #   rails generate rsb:admin:theme corporate --engine
+    class ThemeGenerator < Rails::Generators::NamedBase
+      namespace 'rsb:admin:theme'
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Scaffold a new RSB Admin theme.'
+
+      class_option :engine, type: :boolean, default: false,
+                            desc: 'Generate as a Rails engine gem (for distribution)'
+
+      # Creates the theme scaffold based on the `--engine` option.
+      #
+      # Dispatches to either {#create_host_app_scaffold} for host-app themes
+      # or {#create_engine_scaffold} for engine gems.
+      #
+      # @return [void]
+      def create_theme
+        if options[:engine]
+          create_engine_scaffold
+        else
+          create_host_app_scaffold
+        end
+      end
+
+      # Prints post-generation instructions to the console.
+      #
+      # Instructions differ based on whether a host-app or engine scaffold
+      # was generated.
+      #
+      # @return [void]
+      def print_instructions
+        say ''
+        if options[:engine]
+          say "Theme engine scaffold created at #{engine_dir}/", :green
+          say ''
+          say 'Next steps:'
+          say "  1. cd #{engine_dir}"
+          say "  2. Customize the CSS variables in app/assets/stylesheets/rsb/admin/themes/#{file_name}.css"
+          say "  3. Customize views in app/views/rsb/admin/themes/#{file_name}/views/"
+          say '  4. Build: bundle exec rake build'
+          say "  5. Add to host app Gemfile: gem 'rsb-admin-#{file_name}-theme', path: '#{engine_dir}'"
+        else
+          say 'Theme scaffold created!', :green
+          say ''
+          say 'Next steps:'
+          say "  1. Customize CSS variables in app/assets/stylesheets/admin/themes/#{file_name}.css"
+          say "  2. Customize views in app/views/admin/themes/#{file_name}/views/"
+          say "  3. Activate via Settings page or: RSB::Admin.configure { |c| c.theme = :#{file_name} }"
+        end
+        say ''
+      end
+
+      private
+
+      # ── Host App Scaffold ──────────────────────────
+
+      # Creates a host-app theme scaffold with CSS, views, and an initializer.
+      #
+      # Files created:
+      # - `app/assets/stylesheets/admin/themes/{name}.css`
+      # - `app/views/admin/themes/{name}/views/shared/_sidebar.html.erb`
+      # - `app/views/admin/themes/{name}/views/shared/_header.html.erb`
+      # - `config/initializers/rsb_admin_{name}_theme.rb`
+      #
+      # @return [void]
+      # @api private
+      def create_host_app_scaffold
+        # CSS with all variables
+        template 'theme.css.tt',
+                 "app/assets/stylesheets/admin/themes/#{file_name}.css"
+
+        # Copy default sidebar and header as starting points
+        copy_engine_view('shared/_sidebar.html.erb',
+                         "app/views/admin/themes/#{file_name}/views/shared/_sidebar.html.erb")
+        copy_engine_view('shared/_header.html.erb',
+                         "app/views/admin/themes/#{file_name}/views/shared/_header.html.erb")
+
+        # Initializer to register the theme
+        create_file "config/initializers/rsb_admin_#{file_name}_theme.rb", <<~RUBY
+          RSB::Admin.register_theme :#{file_name},
+            label: "#{class_name}",
+            css: "admin/themes/#{file_name}",
+            views_path: "admin/themes/#{file_name}/views"
+        RUBY
+      end
+
+      # ── Engine Scaffold ────────────────────────────
+
+      # Creates a complete Rails engine gem scaffold for the theme.
+      #
+      # Creates a directory structure with:
+      # - Gemspec with `rsb-admin` dependency
+      # - Engine class with theme registration
+      # - CSS and view assets
+      # - Gemfile and Rakefile
+      #
+      # @return [void]
+      # @api private
+      def create_engine_scaffold
+        # Gemspec
+        create_file "#{engine_dir}/rsb-admin-#{file_name}-theme.gemspec", <<~GEMSPEC
+          Gem::Specification.new do |s|
+            s.name        = "rsb-admin-#{file_name}-theme"
+            s.version     = "0.1.0"
+            s.summary     = "#{class_name} theme for RSB Admin"
+            s.description = "A custom theme for the RSB Admin panel."
+            s.license     = "MIT"
+            s.authors     = ["TODO: Your name"]
+
+            s.files = Dir["{app,lib}/**/*", "LICENSE", "README.md"]
+            s.require_paths = ["lib"]
+
+            s.add_dependency "rsb-admin"
+          end
+        GEMSPEC
+
+        # Main lib file
+        create_file "#{engine_dir}/lib/rsb/admin/#{file_name}_theme.rb", <<~RUBY
+          require "rsb/admin/#{file_name}_theme/engine"
+        RUBY
+
+        # Engine
+        create_file "#{engine_dir}/lib/rsb/admin/#{file_name}_theme/engine.rb", <<~RUBY
+          module RSB
+            module Admin
+              module #{class_name}Theme
+                class Engine < ::Rails::Engine
+                  isolate_namespace RSB::Admin::#{class_name}Theme
+
+                  initializer "rsb_admin_#{file_name}_theme.register" do
+                    RSB::Admin.register_theme :#{file_name},
+                      label: "#{class_name}",
+                      css: "rsb/admin/themes/#{file_name}",
+                      views_path: "rsb/admin/themes/#{file_name}/views"
+                  end
+                end
+              end
+            end
+          end
+        RUBY
+
+        # CSS with all variables
+        template 'theme.css.tt',
+                 "#{engine_dir}/app/assets/stylesheets/rsb/admin/themes/#{file_name}.css"
+
+        # Copy default sidebar and header as starting points
+        copy_engine_view('shared/_sidebar.html.erb',
+                         "#{engine_dir}/app/views/rsb/admin/themes/#{file_name}/views/shared/_sidebar.html.erb")
+        copy_engine_view('shared/_header.html.erb',
+                         "#{engine_dir}/app/views/rsb/admin/themes/#{file_name}/views/shared/_header.html.erb")
+
+        # Gemfile
+        create_file "#{engine_dir}/Gemfile", <<~GEMFILE
+          source "https://rubygems.org"
+
+          gemspec
+
+          gem "rsb-admin", path: "../../"
+        GEMFILE
+
+        # Rakefile
+        create_file "#{engine_dir}/Rakefile", <<~RAKE
+          require "bundler/gem_tasks"
+        RAKE
+      end
+
+      # Returns the directory name for the engine gem.
+      #
+      # @return [String] the engine directory name
+      # @api private
+      def engine_dir
+        "rsb-admin-#{file_name}-theme"
+      end
+
+      # Returns the theme name (same as file_name).
+      #
+      # @return [String] the theme name
+      # @api private
+      def theme_name
+        file_name
+      end
+
+      # Copies a view file from the RSB Admin engine to a destination path.
+      #
+      # If the source view doesn't exist in the engine, prints a skip message
+      # instead of failing.
+      #
+      # @param relative_path [String] the view path relative to `rsb/admin/`
+      # @param destination [String] the destination path for the copied view
+      # @return [void]
+      # @api private
+      def copy_engine_view(relative_path, destination)
+        source = RSB::Admin::Engine.root.join('app', 'views', 'rsb', 'admin', relative_path)
+        if File.exist?(source)
+          create_file destination, File.read(source)
+        else
+          say_status :skip, "#{relative_path} (source not found)", :yellow
+        end
+      end
+    end
+  end
+end

data/lib/generators/rsb/admin/views/views_generator.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # Generator to export RSB Admin views to the host application for customization.
+    #
+    # This generator copies view files from the RSB Admin engine (or a specific theme)
+    # to the host application's view override path. It supports selective export via
+    # `--only` group filtering and theme-specific views via `--theme`.
+    #
+    # @example Export all views
+    #   rails generate rsb:admin:views
+    #
+    # @example Export only sidebar and header
+    #   rails generate rsb:admin:views --only sidebar,header
+    #
+    # @example Export modern theme views
+    #   rails generate rsb:admin:views --theme modern
+    #
+    # @example Force overwrite existing files
+    #   rails generate rsb:admin:views --force
+    class ViewsGenerator < Rails::Generators::Base
+      namespace 'rsb:admin:views'
+      desc 'Export RSB Admin views to your application for customization.'
+
+      class_option :only, type: :string, default: nil,
+                          desc: 'Comma-separated list of view groups to export (sidebar,header,layout,breadcrumbs,resources,fields,dashboard,sessions)'
+      class_option :theme, type: :string, default: nil,
+                           desc: 'Export views for a specific theme (e.g., modern)'
+      class_option :force, type: :boolean, default: false,
+                           desc: 'Overwrite existing files'
+
+      # Mapping of view groups to their file paths (relative to the views root).
+      # Paths use the partial naming convention (with underscore prefix for partials).
+      VIEW_GROUPS = {
+        'sidebar' => ['shared/_sidebar.html.erb'],
+        'header' => ['shared/_header.html.erb'],
+        'layout' => ['layouts/rsb/admin/application.html.erb'],
+        'breadcrumbs' => ['shared/_breadcrumbs.html.erb'],
+        'resources' => [
+          'resources/index.html.erb',
+          'resources/show.html.erb',
+          'resources/new.html.erb',
+          'resources/edit.html.erb',
+          'resources/_table.html.erb',
+          'resources/_filters.html.erb',
+          'resources/_form.html.erb',
+          'resources/_pagination.html.erb'
+        ],
+        'fields' => [
+          'shared/fields/_text.html.erb',
+          'shared/fields/_textarea.html.erb',
+          'shared/fields/_select.html.erb',
+          'shared/fields/_checkbox.html.erb',
+          'shared/fields/_number.html.erb',
+          'shared/fields/_email.html.erb',
+          'shared/fields/_password.html.erb',
+          'shared/fields/_datetime.html.erb',
+          'shared/fields/_json.html.erb'
+        ],
+        'dashboard' => ['dashboard/index.html.erb'],
+        'sessions' => ['sessions/new.html.erb']
+      }.freeze
+
+      # Copies the selected view files from the engine to the host application.
+      #
+      # This is the main action that exports views, handling group filtering,
+      # theme selection, and skip/force logic for existing files.
+      #
+      # @return [void]
+      def copy_views
+        groups = selected_groups
+        source_root = resolve_source_root
+
+        unless File.directory?(source_root)
+          say_status :error, "Source directory not found: #{source_root}", :red
+          return
+        end
+
+        files_copied = 0
+        files_skipped = 0
+
+        groups.each_value do |paths|
+          paths.each do |relative_path|
+            source = source_path_for(relative_path)
+            destination = File.join(target_directory, relative_path)
+
+            unless File.exist?(source)
+              say_status :skip, "#{relative_path} (not found in source)", :yellow
+              next
+            end
+
+            if File.exist?(destination) && !options[:force]
+              say_status :skip, "#{relative_path} (already exists, use --force to overwrite)", :yellow
+              files_skipped += 1
+            else
+              copy_file_with_status(source, destination)
+              files_copied += 1
+            end
+          end
+        end
+
+        say ''
+        say "Exported #{files_copied} view(s) to #{target_directory}/", :green
+        say "Skipped #{files_skipped} existing file(s)." if files_skipped.positive?
+      end
+
+      # Sets up the view_overrides_path configuration if not already configured.
+      #
+      # Creates an initializer that configures the override path when the
+      # configuration is currently nil. This ensures views exported to the
+      # host app will be found by the engine.
+      #
+      # @return [void]
+      def setup_override_path
+        return if RSB::Admin.configuration.view_overrides_path.present?
+
+        override_path = 'rsb_admin_overrides'
+        initializer_path = 'config/initializers/rsb_admin_views.rb'
+
+        if File.exist?(File.join(destination_root, initializer_path))
+          say_status :skip, initializer_path, :yellow
+          return
+        end
+
+        create_file initializer_path, <<~RUBY
+          RSB::Admin.configure do |config|
+            config.view_overrides_path = "#{override_path}"
+          end
+        RUBY
+
+        say ''
+        say "Created initializer to set view_overrides_path = \"#{override_path}\"", :green
+      end
+
+      # Prints instructions about the view override chain.
+      #
+      # Explains how the Rails view resolution works with the exported files,
+      # helping developers understand the priority order.
+      #
+      # @return [void]
+      def print_instructions
+        say ''
+        say 'View override chain (highest priority first):', :cyan
+        say "  1. app/views/#{override_path_name}/ (your customizations)"
+        say '  2. Theme views (if active theme has view overrides)'
+        say '  3. RSB Admin engine defaults (fallback)'
+        say ''
+        say 'Edit the exported files to customize your admin panel.'
+        say "Files you didn't export will continue using engine defaults."
+        say ''
+      end
+
+      private
+
+      # Returns the filtered set of view groups based on the `--only` option.
+      #
+      # If `--only` is not specified, returns all groups. If specified, validates
+      # group names and exits with an error message if any invalid groups are found.
+      #
+      # @return [Hash{String => Array<String>}] filtered view groups hash
+      # @raise [SystemExit] if invalid group names are provided
+      def selected_groups
+        if options[:only]
+          keys = options[:only].split(',').map(&:strip)
+          invalid = keys - VIEW_GROUPS.keys
+          if invalid.any?
+            say_status :error,
+                       "Unknown view group(s): #{invalid.join(', ')}. Valid groups: #{VIEW_GROUPS.keys.join(', ')}", :red
+            exit 1
+          end
+          VIEW_GROUPS.slice(*keys)
+        else
+          VIEW_GROUPS
+        end
+      end
+
+      # Resolves the source root directory based on the `--theme` option.
+      #
+      # If a theme is specified, uses the theme's views_path if available,
+      # otherwise falls back to engine defaults. If no theme is specified,
+      # uses the engine's default view directory.
+      #
+      # @return [String] absolute path to the source view directory
+      # @raise [SystemExit] if an invalid theme name is provided
+      def resolve_source_root
+        if options[:theme]
+          theme_key = options[:theme].to_sym
+          theme = RSB::Admin.themes[theme_key]
+          if theme.nil?
+            say_status :error, "Unknown theme: #{options[:theme]}. Available: #{RSB::Admin.themes.keys.join(', ')}",
+                       :red
+            exit 1
+          end
+
+          if theme.views_path
+            # Theme has custom views — use them as source
+            RSB::Admin::Engine.root.join('app', 'views', theme.views_path).to_s
+          else
+            # Theme has no custom views — fall back to engine defaults
+            engine_views_root
+          end
+        else
+          engine_views_root
+        end
+      end
+
+      # Returns the full source path for a given relative view path.
+      #
+      # Handles the special case of layout files, which live under `app/views/layouts/`
+      # instead of the namespaced view directory.
+      #
+      # @param relative_path [String] the relative path from VIEW_GROUPS
+      # @return [String] absolute path to the source file
+      def source_path_for(relative_path)
+        if relative_path.start_with?('layouts/')
+          RSB::Admin::Engine.root.join('app', 'views', relative_path).to_s
+        else
+          File.join(resolve_source_root, relative_path)
+        end
+      end
+
+      # Returns the engine's default namespaced views root directory.
+      #
+      # @return [String] absolute path to rsb/admin view directory in the engine
+      def engine_views_root
+        RSB::Admin::Engine.root.join('app', 'views', 'rsb', 'admin').to_s
+      end
+
+      # Returns the target directory where views will be exported.
+      #
+      # Uses the configured view_overrides_path or the default "rsb_admin_overrides".
+      #
+      # @return [String] absolute path to the target view directory
+      def target_directory
+        File.join(destination_root, 'app', 'views', override_path_name)
+      end
+
+      # Returns the configured or default override path name.
+      #
+      # @return [String] the view override path name
+      def override_path_name
+        RSB::Admin.configuration.view_overrides_path || 'rsb_admin_overrides'
+      end
+
+      # Copies a file and prints a status message.
+      #
+      # Creates parent directories if needed and reports the relative path
+      # that was created.
+      #
+      # @param source [String] absolute path to source file
+      # @param destination [String] absolute path to destination file
+      # @return [void]
+      def copy_file_with_status(source, destination)
+        FileUtils.mkdir_p(File.dirname(destination))
+        FileUtils.cp(source, destination)
+        relative = destination.sub("#{destination_root}/", '')
+        say_status :create, relative, :green
+      end
+    end
+  end
+end

data/lib/rsb/admin/breadcrumb_item.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # Represents a breadcrumb item in admin navigation.
+    #
+    # BreadcrumbItem is an immutable data structure representing a single item
+    # in a breadcrumb trail. The path is nil for the current (last) item.
+    #
+    # @!attribute [r] label
+    #   @return [String] the text to display for this breadcrumb
+    # @!attribute [r] path
+    #   @return [String, nil] the URL path (nil for the current/last item)
+    #
+    # @example Building a breadcrumb trail
+    #   [
+    #     BreadcrumbItem.new(label: "Admin", path: "/admin"),
+    #     BreadcrumbItem.new(label: "Users", path: "/admin/users"),
+    #     BreadcrumbItem.new(label: "John Doe", path: nil) # current page
+    #   ]
+    BreadcrumbItem = Data.define(
+      :label,  # String
+      :path    # String | nil — nil for current (last) item
+    )
+  end
+end

data/lib/rsb/admin/category_registration.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # Represents a category of admin resources and pages.
+    #
+    # Categories group related resources and pages in the admin interface sidebar.
+    # Each category has a name and contains collections of resources (CRUD interfaces
+    # for models) and pages (custom non-CRUD interfaces).
+    #
+    # @!attribute [r] name
+    #   @return [String] the category name
+    #
+    # @!attribute [r] resources
+    #   @return [Array<ResourceRegistration>] registered resources in this category
+    #
+    # @!attribute [r] pages
+    #   @return [Array<PageRegistration>] registered pages in this category
+    #
+    # @example Creating a category with resources and pages
+    #   category = CategoryRegistration.new("Users")
+    #   category.resource User, icon: "users", actions: [:index, :show]
+    #   category.page :dashboard, label: "Dashboard", controller: "admin/dashboard"
+    #
+    # @see Registry#register_category
+    # @see ResourceRegistration
+    # @see PageRegistration
+    class CategoryRegistration
+      attr_reader :name, :resources, :pages
+
+      # Initialize a new category with an empty set of resources and pages.
+      #
+      # @param name [String] the category name
+      #
+      # @example
+      #   category = CategoryRegistration.new("Authentication")
+      def initialize(name)
+        @name = name
+        @resources = []
+        @pages = []
+      end
+
+      # Register a resource (ActiveRecord model) in this category.
+      #
+      # Resources can be registered with or without a configuration block.
+      # When a block is provided, it runs in the context of {ResourceDSLContext}
+      # and allows you to define columns, filters, and form fields inline.
+      #
+      # @param model_class [Class] the ActiveRecord model class to register
+      # @param icon [String, nil] optional icon identifier for the resource
+      # @param label [String, nil] optional custom label (defaults to humanized plural model name)
+      # @param actions [Array<Symbol>] allowed actions for this resource (default: `[:index, :show]`)
+      # @param controller [String, nil] optional custom controller path for delegation
+      # @param per_page [Integer, nil] number of records per page for index
+      # @param default_sort [Hash, nil] default sort configuration (e.g., `{ column: :created_at, direction: :desc }`)
+      # @param search_fields [Array<Symbol>, nil] searchable field names
+      # @param options [Hash] additional options passed to the registration
+      # @yield [ResourceDSLContext] optional block for defining columns, filters, and form fields
+      #
+      # @return [void]
+      #
+      # @example Basic resource registration
+      #   resource User, icon: "users", actions: [:index, :show]
+      #
+      # @example Resource with inline DSL
+      #   resource User, icon: "users", actions: [:index, :show, :edit, :update] do
+      #     column :id, link: true
+      #     column :email, sortable: true
+      #     filter :email, type: :text
+      #     form_field :email, type: :email, required: true
+      #   end
+      #
+      # @example Resource with custom controller
+      #   resource Identity, controller: "admin/identities", actions: [:index, :show, :suspend]
+      #
+      # @see ResourceDSLContext
+      # @see ResourceRegistration
+      def resource(model_class, icon: nil, label: nil, actions: %i[index show], controller: nil,
+                   per_page: nil, default_sort: nil, search_fields: nil,
+                   **options, &block)
+        dsl = nil
+        if block
+          dsl = ResourceDSLContext.new
+          dsl.instance_eval(&block)
+        end
+
+        @resources << ResourceRegistration.new(
+          model_class: model_class,
+          category_name: @name,
+          icon: icon,
+          label: label || model_class.model_name.human.pluralize,
+          actions: actions,
+          controller: controller,
+          columns: dsl&.columns&.presence,
+          filters: dsl&.filters&.presence,
+          form_fields: dsl&.form_fields&.presence,
+          per_page: per_page,
+          default_sort: default_sort,
+          search_fields: search_fields,
+          **options
+        )
+      end
+
+      # Register a custom page in this category.
+      #
+      # Pages are non-CRUD admin interfaces that require custom controllers.
+      # Unlike resources, pages don't map to a specific model.
+      #
+      # @param key [Symbol, String] unique identifier for this page
+      # @param label [String] the human-readable page name
+      # @param icon [String, nil] optional icon identifier
+      # @param controller [String] the controller path (e.g., "admin/dashboard")
+      # @param actions [Array<Hash>] custom action definitions with `:key`, `:label`, `:method`, `:confirm`
+      #
+      # @return [PageRegistration] the created page registration
+      #
+      # @example Basic page
+      #   page :dashboard, label: "Dashboard", icon: "home", controller: "admin/dashboard"
+      #
+      # @example Page with custom actions
+      #   page :usage, label: "Usage Reports", controller: "admin/usage",
+      #     actions: [
+      #       { key: :index, label: "Overview" },
+      #       { key: :export, label: "Export CSV", method: :post, confirm: "Export data?" }
+      #     ]
+      #
+      # @see PageRegistration
+      def page(key, label:, controller:, icon: nil, actions: [])
+        registration = PageRegistration.build(
+          key: key,
+          label: label,
+          icon: icon,
+          controller: controller,
+          category_name: @name,
+          actions: actions
+        )
+        @pages << registration
+        registration
+      end
+
+      # Find a resource registration by its model class.
+      #
+      # @param model_class [Class] the ActiveRecord model class to search for
+      #
+      # @return [ResourceRegistration, nil] the matching resource registration, or nil if not found
+      #
+      # @example
+      #   category.find_resource(User) #=> ResourceRegistration instance or nil
+      def find_resource(model_class)
+        @resources.find { |r| r.model_class == model_class }
+      end
+
+      # Merge another category's resources and pages into this category.
+      #
+      # This is used when multiple gems or initializers register resources
+      # in the same category. All resources and pages are combined.
+      #
+      # @param other [CategoryRegistration] the category to merge from
+      #
+      # @return [void]
+      #
+      # @example
+      #   category1 = CategoryRegistration.new("Auth")
+      #   category1.resource User, actions: [:index]
+      #
+      #   category2 = CategoryRegistration.new("Auth")
+      #   category2.resource Session, actions: [:index]
+      #
+      #   category1.merge(category2)
+      #   category1.resources.size #=> 2
+      def merge(other)
+        @resources.concat(other.resources)
+        @pages.concat(other.pages)
+      end
+    end
+  end
+end