rsb-admin 0.9.1

data/lib/rsb/admin/column_definition.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # Represents a column definition for admin resource tables.
+    #
+    # ColumnDefinition is an immutable data structure that describes how a column
+    # should be displayed in index and show views. It handles column metadata,
+    # formatting, sorting, and visibility rules.
+    #
+    # @!attribute [r] key
+    #   @return [Symbol] the attribute name to display
+    # @!attribute [r] label
+    #   @return [String] the human-readable column header
+    # @!attribute [r] sortable
+    #   @return [Boolean] whether the column can be sorted
+    # @!attribute [r] formatter
+    #   @return [Symbol, Proc, nil] optional formatter for the column value
+    # @!attribute [r] link
+    #   @return [Boolean] whether to render the value as a link to the resource
+    # @!attribute [r] visible_on
+    #   @return [Array<Symbol>] contexts where this column is visible (:index, :show)
+    #
+    # @example Building a simple column
+    #   col = ColumnDefinition.build(:email)
+    #   col.key        #=> :email
+    #   col.label      #=> "Email"
+    #   col.sortable   #=> false
+    #   col.link       #=> false
+    #
+    # @example Building an ID column (link defaults to true)
+    #   col = ColumnDefinition.build(:id)
+    #   col.link #=> true
+    #
+    # @example Building a custom column with formatter
+    #   col = ColumnDefinition.build(:status,
+    #     label: "State",
+    #     sortable: true,
+    #     formatter: :badge,
+    #     visible_on: [:index]
+    #   )
+    ColumnDefinition = Data.define(
+      :key,        # Symbol
+      :label,      # String
+      :sortable,   # Boolean
+      :formatter,  # Symbol | Proc | nil
+      :link,       # Boolean
+      :visible_on  # Array<Symbol>
+    )
+
+    class ColumnDefinition
+      # Build a ColumnDefinition with smart defaults.
+      #
+      # @param key [Symbol, String] the attribute name
+      # @param label [String, nil] the display label (defaults to humanized key)
+      # @param sortable [Boolean] whether the column is sortable (default: false)
+      # @param formatter [Symbol, Proc, nil] optional value formatter
+      # @param link [Boolean, nil] whether to link the value (default: true for :id, false otherwise)
+      # @param visible_on [Symbol, Array<Symbol>] contexts where visible (default: [:index, :show])
+      # @return [ColumnDefinition] a frozen, immutable column definition
+      #
+      # @example
+      #   ColumnDefinition.build(:created_at, label: "Created", sortable: true)
+      def self.build(key, label: nil, sortable: false, formatter: nil, link: nil, visible_on: %i[index show])
+        new(
+          key: key.to_sym,
+          label: label || key.to_s.humanize,
+          sortable: sortable,
+          formatter: formatter,
+          link: link.nil? ? (key.to_sym == :id) : link,
+          visible_on: Array(visible_on).map(&:to_sym)
+        )
+      end
+
+      # Check if this column is visible in a given context.
+      #
+      # @param context [Symbol, String] the rendering context (:index or :show)
+      # @return [Boolean] true if the column should be displayed in this context
+      #
+      # @example
+      #   col = ColumnDefinition.build(:email, visible_on: [:index])
+      #   col.visible_on?(:index) #=> true
+      #   col.visible_on?(:show)  #=> false
+      def visible_on?(context)
+        visible_on.include?(context.to_sym)
+      end
+    end
+  end
+end

data/lib/rsb/admin/configuration.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # Holds configuration options for the RSB Admin panel.
+    #
+    # Instances are created by {RSB::Admin.configuration} and configured
+    # via {RSB::Admin.configure}. Each attribute has a sensible default
+    # that can be overridden in an initializer.
+    #
+    # @example
+    #   RSB::Admin.configure do |config|
+    #     config.app_name = "My App Admin"
+    #     config.theme = :modern
+    #     config.enabled = true
+    #     config.company_name = "Acme Corp"
+    #     config.logo_url = "/images/logo.svg"
+    #     config.footer_text = "© 2024 Acme Corp"
+    #   end
+    class Configuration
+      # @return [Boolean] whether the admin panel is enabled
+      attr_accessor :enabled
+
+      # @return [String] the display name shown in the admin panel header
+      attr_accessor :app_name
+
+      # @return [String] company or product name shown in footer/login
+      attr_accessor :company_name
+
+      # @return [String] URL to logo image shown in sidebar header
+      attr_accessor :logo_url
+
+      # @return [String] custom footer text
+      attr_accessor :footer_text
+
+      # @return [Integer] default number of records per page in index views
+      attr_accessor :per_page
+
+      # @return [Symbol] the active theme key (must match a registered theme)
+      attr_accessor :theme
+
+      # @return [String, nil] optional path prefix for host-app view overrides
+      attr_accessor :view_overrides_path
+
+      # @return [String] the layout template used by admin controllers
+      attr_accessor :layout
+
+      # @return [String] from address for admin emails
+      attr_accessor :mailer_sender
+
+      # @return [ActiveSupport::Duration] verification token lifetime
+      attr_accessor :email_verification_expiry
+
+      def initialize
+        @enabled = true
+        @app_name = 'Admin'
+        @company_name = ''
+        @logo_url = ''
+        @footer_text = ''
+        @per_page = 25
+        @theme = :default
+        @view_overrides_path = nil
+        @layout = 'rsb/admin/application'
+        @mailer_sender = 'no-reply@example.com'
+        @email_verification_expiry = 24.hours
+      end
+    end
+  end
+end

data/lib/rsb/admin/engine.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    class Engine < ::Rails::Engine
+      isolate_namespace RSB::Admin
+
+      initializer 'rsb_admin.i18n' do
+        config.i18n.load_path += Dir[RSB::Admin::Engine.root.join('config', 'locales', '**', '*.yml')]
+      end
+
+      # Register settings schema
+      initializer 'rsb_admin.register_settings', after: 'rsb_settings.ready' do
+        RSB::Settings.registry.register(RSB::Admin.settings_schema)
+      end
+
+      # Trigger on_load hooks — this is where rsb-auth, rsb-entitlements,
+      # and third-party gems register their admin sections.
+      # Deferred to after_initialize so all engine autoload paths are set up
+      # and model constants (e.g. RSB::Auth::Identity) are resolvable.
+      initializer 'rsb_admin.ready' do |app|
+        app.config.after_initialize do
+          ActiveSupport.run_load_hooks(:rsb_admin, RSB::Admin.registry)
+        end
+      end
+
+      config.generators do |g|
+        g.test_framework :minitest, fixture: false
+        g.assets false
+        g.helper false
+      end
+    end
+  end
+end

data/lib/rsb/admin/filter_definition.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # Represents a filter definition for admin resource queries.
+    #
+    # FilterDefinition is an immutable data structure that describes how to filter
+    # an ActiveRecord relation. It supports multiple filter types (text, select,
+    # boolean, date ranges, number ranges) and can use custom scopes or default
+    # filtering logic.
+    #
+    # @!attribute [r] key
+    #   @return [Symbol] the attribute name to filter on
+    # @!attribute [r] label
+    #   @return [String] the human-readable filter label
+    # @!attribute [r] type
+    #   @return [Symbol] the filter type (:text, :select, :boolean, :date_range, :number_range)
+    # @!attribute [r] options
+    #   @return [Array, Proc, nil] options for select filters (array or callable)
+    # @!attribute [r] scope
+    #   @return [Symbol, Proc, nil] custom scope method name or lambda for filtering
+    #
+    # @example Building a text filter
+    #   filter = FilterDefinition.build(:email)
+    #   filter.type #=> :text
+    #
+    # @example Building a select filter with options
+    #   filter = FilterDefinition.build(:status,
+    #     type: :select,
+    #     options: %w[active suspended banned]
+    #   )
+    #
+    # @example Building a filter with custom scope
+    #   filter = FilterDefinition.build(:search,
+    #     scope: ->(rel, val) { rel.where("name LIKE ? OR email LIKE ?", "%#{val}%", "%#{val}%") }
+    #   )
+    FilterDefinition = Data.define(
+      :key,      # Symbol
+      :label,    # String
+      :type,     # Symbol — :text, :select, :boolean, :date_range, :number_range
+      :options,  # Array | Proc | nil
+      :scope     # Symbol | Proc | nil
+    )
+
+    class FilterDefinition
+      # Build a FilterDefinition with smart defaults.
+      #
+      # @param key [Symbol, String] the attribute name to filter
+      # @param label [String, nil] the display label (defaults to humanized key)
+      # @param type [Symbol] the filter type (default: :text)
+      # @param options [Array, Proc, nil] options for select-type filters
+      # @param scope [Symbol, Proc, nil] custom filtering logic
+      # @return [FilterDefinition] a frozen, immutable filter definition
+      #
+      # @example
+      #   FilterDefinition.build(:created_at, type: :date_range)
+      def self.build(key, label: nil, type: :text, options: nil, scope: nil)
+        new(
+          key: key.to_sym,
+          label: label || key.to_s.humanize,
+          type: type.to_sym,
+          options: options,
+          scope: scope
+        )
+      end
+
+      # Apply this filter to an ActiveRecord relation.
+      #
+      # If the filter has a custom scope (Proc or Symbol), it will be used.
+      # Otherwise, default filtering logic based on the filter type will be applied.
+      #
+      # @param relation [ActiveRecord::Relation] the relation to filter
+      # @param value [Object] the filter value (ignored if blank)
+      # @return [ActiveRecord::Relation] the filtered relation
+      #
+      # @example Applying a text filter
+      #   filter = FilterDefinition.build(:email, type: :text)
+      #   filtered = filter.apply(User.all, "john")
+      #   # Generates: WHERE email LIKE '%john%'
+      #
+      # @example Applying with blank value (no-op)
+      #   filter.apply(User.all, "") #=> returns User.all unchanged
+      def apply(relation, value)
+        return relation if value.blank?
+
+        if scope.is_a?(Proc)
+          scope.call(relation, value)
+        elsif scope.is_a?(Symbol)
+          relation.send(scope, value)
+        else
+          apply_default_scope(relation, value)
+        end
+      end
+
+      private
+
+      # Apply default filtering logic based on the filter type.
+      #
+      # @param relation [ActiveRecord::Relation] the relation to filter
+      # @param value [Object] the filter value
+      # @return [ActiveRecord::Relation] the filtered relation
+      # @api private
+      def apply_default_scope(relation, value)
+        case type
+        when :text
+          relation.where("#{key} LIKE ?", "%#{value}%")
+        when :select, :boolean
+          relation.where(key => value)
+        when :date_range
+          from = value[:from]
+          to = value[:to]
+          scope = relation
+          scope = scope.where("#{key} >= ?", from) if from.present?
+          scope = scope.where("#{key} <= ?", to) if to.present?
+          scope
+        when :number_range
+          min = value[:min]
+          max = value[:max]
+          scope = relation
+          scope = scope.where("#{key} >= ?", min) if min.present?
+          scope = scope.where("#{key} <= ?", max) if max.present?
+          scope
+        else
+          relation.where(key => value)
+        end
+      end
+    end
+  end
+end

data/lib/rsb/admin/form_field_definition.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # Represents a form field definition for admin resource forms.
+    #
+    # FormFieldDefinition is an immutable data structure that describes how a form
+    # field should be rendered and validated in new/edit forms. It handles field
+    # type, options, validation, hints, and visibility rules.
+    #
+    # @!attribute [r] key
+    #   @return [Symbol] the attribute name for this field
+    # @!attribute [r] label
+    #   @return [String] the human-readable field label
+    # @!attribute [r] type
+    #   @return [Symbol] the field type (:text, :textarea, :select, :checkbox, :number, :email, :password, :datetime, :hidden, :json)
+    # @!attribute [r] options
+    #   @return [Array, Proc, nil] options for select-type fields (array or callable)
+    # @!attribute [r] required
+    #   @return [Boolean] whether the field is required
+    # @!attribute [r] hint
+    #   @return [String, nil] optional help text displayed below the field
+    # @!attribute [r] visible_on
+    #   @return [Array<Symbol>] contexts where this field is visible (:new, :edit)
+    #
+    # @example Building a simple text field
+    #   field = FormFieldDefinition.build(:name)
+    #   field.key       #=> :name
+    #   field.label     #=> "Name"
+    #   field.type      #=> :text
+    #   field.required  #=> false
+    #
+    # @example Building a required email field
+    #   field = FormFieldDefinition.build(:email,
+    #     type: :email,
+    #     required: true,
+    #     hint: "We'll never share your email"
+    #   )
+    #
+    # @example Building a select field with options
+    #   field = FormFieldDefinition.build(:role,
+    #     type: :select,
+    #     options: %w[admin user guest],
+    #     required: true
+    #   )
+    FormFieldDefinition = Data.define(
+      :key,        # Symbol
+      :label,      # String
+      :type,       # Symbol — :text, :textarea, :select, :checkbox, :number, :email, :password, :datetime, :hidden, :json
+      :options,    # Array | Proc | nil
+      :required,   # Boolean
+      :hint,       # String | nil
+      :visible_on  # Array<Symbol>
+    )
+
+    class FormFieldDefinition
+      # Build a FormFieldDefinition with smart defaults.
+      #
+      # @param key [Symbol, String] the attribute name
+      # @param label [String, nil] the display label (defaults to humanized key)
+      # @param type [Symbol] the field type (default: :text)
+      # @param options [Array, Proc, nil] options for select-type fields
+      # @param required [Boolean] whether the field is required (default: false)
+      # @param hint [String, nil] optional help text
+      # @param visible_on [Symbol, Array<Symbol>] contexts where visible (default: [:new, :edit])
+      # @return [FormFieldDefinition] a frozen, immutable form field definition
+      #
+      # @example
+      #   FormFieldDefinition.build(:description, type: :textarea, required: true)
+      def self.build(key, label: nil, type: :text, options: nil, required: false, hint: nil, visible_on: %i[new edit])
+        new(
+          key: key.to_sym,
+          label: label || key.to_s.humanize,
+          type: type.to_sym,
+          options: options,
+          required: required,
+          hint: hint,
+          visible_on: Array(visible_on).map(&:to_sym)
+        )
+      end
+
+      # Check if this field is visible in a given context.
+      #
+      # @param context [Symbol, String] the rendering context (:new or :edit)
+      # @return [Boolean] true if the field should be displayed in this context
+      #
+      # @example
+      #   field = FormFieldDefinition.build(:password, visible_on: [:new])
+      #   field.visible_on?(:new)  #=> true
+      #   field.visible_on?(:edit) #=> false
+      def visible_on?(context)
+        visible_on.include?(context.to_sym)
+      end
+    end
+  end
+end

data/lib/rsb/admin/icons.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # Lucide icon system for the admin panel.
+    #
+    # Provides a curated subset of 30 Lucide icons as inline SVG strings.
+    # All icons use currentColor for stroke, allowing them to inherit text color.
+    #
+    # @example Render an icon
+    #   RSB::Admin::Icons.render("users") # => "<svg ...>...</svg>"
+    #   RSB::Admin::Icons.render("users", size: 24) # => "<svg width=\"24\" height=\"24\" ...>...</svg>"
+    #
+    # @example Unknown icon returns empty string (no error)
+    #   RSB::Admin::Icons.render("nonexistent") # => ""
+    #
+    # @example List all available icons
+    #   RSB::Admin::Icons::ICONS.keys # => ["home", "users", "mail", ...]
+    module Icons
+      # Hash of icon names to SVG markup strings.
+      # Each SVG uses the placeholder "SIZE" for width/height values.
+      # All SVGs use currentColor for stroke to inherit text color.
+      #
+      # Available icons: alert-circle, alert-triangle, arrow-down, arrow-up, bar-chart,
+      # check-circle, chevron-left, chevron-right, credit-card, edit, eye, filter, home,
+      # info, key, layout-dashboard, lock, log-out, mail, monitor, moon, plus, receipt,
+      # search, settings, shield, sun, trash, users, users-cog, x
+      ICONS = {
+        'home' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8"/><path d="M3 10a2 2 0 0 1 .709-1.528l7-5.999a2 2 0 0 1 2.582 0l7 5.999A2 2 0 0 1 21 10v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg>',
+        'users' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2"/><circle cx="9" cy="7" r="4"/><path d="M22 21v-2a4 4 0 0 0-3-3.87"/><path d="M16 3.13a4 4 0 0 1 0 7.75"/></svg>',
+        'mail' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect width="20" height="16" x="2" y="4" rx="2"/><path d="m22 7-8.97 5.7a1.94 1.94 0 0 1-2.06 0L2 7"/></svg>',
+        'monitor' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect width="20" height="14" x="2" y="3" rx="2"/><line x1="8" x2="16" y1="21" y2="21"/><line x1="12" x2="12" y1="17" y2="21"/></svg>',
+        'smartphone' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect width="14" height="20" x="5" y="2" rx="2" ry="2"/><path d="M12 18h.01"/></svg>',
+        'tablet' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect width="16" height="20" x="4" y="2" rx="2" ry="2"/><line x1="12" x2="12.01" y1="18" y2="18"/></svg>',
+        'credit-card' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect width="20" height="14" x="2" y="5" rx="2"/><line x1="2" x2="22" y1="10" y2="10"/></svg>',
+        'shield' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z"/></svg>',
+        'bar-chart' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="12" x2="12" y1="20" y2="10"/><line x1="18" x2="18" y1="20" y2="4"/><line x1="6" x2="6" y1="20" y2="16"/></svg>',
+        'settings' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z"/><circle cx="12" cy="12" r="3"/></svg>',
+        'users-cog' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2"/><circle cx="9" cy="7" r="4"/><circle cx="19" cy="11" r="2"/><path d="M19 8v1"/><path d="M19 13v1"/><path d="m21.6 9.5-.87.5"/><path d="m17.27 12-.87.5"/><path d="m21.6 12.5-.87-.5"/><path d="m17.27 10-.87-.5"/></svg>',
+        'key' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m15.5 7.5 2.3 2.3a1 1 0 0 0 1.4 0l2.1-2.1a1 1 0 0 0 0-1.4L19 4"/><path d="m21 2-9.6 9.6"/><circle cx="7.5" cy="15.5" r="5.5"/></svg>',
+        'lock' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect width="18" height="11" x="3" y="11" rx="2" ry="2"/><path d="M7 11V7a5 5 0 0 1 10 0v4"/></svg>',
+        'chevron-right' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m9 18 6-6-6-6"/></svg>',
+        'chevron-left' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m15 18-6-6 6-6"/></svg>',
+        'search' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>',
+        'filter' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polygon points="22 3 2 3 10 12.46 10 19 14 21 14 12.46 22 3"/></svg>',
+        'globe' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20"/><path d="M2 12h20"/></svg>',
+        'plus' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 12h14"/><path d="M12 5v14"/></svg>',
+        'edit' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z"/></svg>',
+        'trash' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 6h18"/><path d="M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6"/><path d="M8 6V4c0-1 1-2 2-2h4c1 0 2 1 2 2v2"/></svg>',
+        'eye' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M2.062 12.348a1 1 0 0 1 0-.696 10.75 10.75 0 0 1 19.876 0 1 1 0 0 1 0 .696 10.75 10.75 0 0 1-19.876 0"/><circle cx="12" cy="12" r="3"/></svg>',
+        'log-out' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4"/><polyline points="16 17 21 12 16 7"/><line x1="21" x2="9" y1="12" y2="12"/></svg>',
+        'arrow-up' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m5 12 7-7 7 7"/><path d="M12 19V5"/></svg>',
+        'arrow-down' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 5v14"/><path d="m19 12-7 7-7-7"/></svg>',
+        'x' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 6 6 18"/><path d="m6 6 12 12"/></svg>',
+        'alert-circle' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="12" x2="12" y1="8" y2="12"/><line x1="12" x2="12.01" y1="16" y2="16"/></svg>',
+        'alert-triangle' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>',
+        'check-circle' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/><path d="m9 11 3 3L22 4"/></svg>',
+        'info' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/></svg>',
+        'layout-dashboard' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect width="7" height="9" x="3" y="3" rx="1"/><rect width="7" height="5" x="14" y="3" rx="1"/><rect width="7" height="9" x="14" y="12" rx="1"/><rect width="7" height="5" x="3" y="16" rx="1"/></svg>',
+        'sun' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.93 4.93 1.41 1.41"/><path d="m17.66 17.66 1.41 1.41"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.34 17.66-1.41 1.41"/><path d="m19.07 4.93-1.41 1.41"/></svg>',
+        'moon' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"/></svg>',
+        'receipt' => '<svg xmlns="http://www.w3.org/2000/svg" width="SIZE" height="SIZE" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 2v20l2-1 2 1 2-1 2 1 2-1 2 1 2-1 2 1V2l-2 1-2-1-2 1-2-1-2 1-2-1-2 1Z"/><path d="M14 8H8"/><path d="M16 12H8"/><path d="M13 16H8"/></svg>'
+      }.freeze
+
+      # Render an icon SVG string with specified dimensions.
+      #
+      # Looks up the icon by name in the ICONS hash and replaces the "SIZE"
+      # placeholder with the requested pixel size. If the icon is not found,
+      # returns an empty string (no error is raised - rule #9).
+      #
+      # @param name [String, Symbol] The icon name (e.g., "users", :home)
+      # @param size [Integer] The width and height of the icon in pixels
+      #
+      # @return [ActiveSupport::SafeBuffer] HTML-safe SVG string, or empty string if icon not found
+      #
+      # @example Render a users icon at default size
+      #   RSB::Admin::Icons.render("users")
+      #   # => '<svg xmlns="..." width="18" height="18" ...>...</svg>'
+      #
+      # @example Render a home icon at custom size
+      #   RSB::Admin::Icons.render(:home, size: 32)
+      #   # => '<svg xmlns="..." width="32" height="32" ...>...</svg>'
+      #
+      # @example Unknown icon returns empty string
+      #   RSB::Admin::Icons.render("unknown")
+      #   # => ""
+      def self.render(name, size: 18)
+        svg = ICONS[name.to_s]
+        return ''.html_safe unless svg
+
+        svg.gsub('SIZE', size.to_s).html_safe
+      end
+    end
+  end
+end