RubyGems - panda-core - Versions diffs - 0.12.5 → 1.1.0 - Mend

panda-core 0.12.5 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (251) hide show

data/lib/panda/core/configuration.rb CHANGED Viewed

@@ -14,6 +14,9 @@ module Panda
         :mailer_default_url_options,
         :session_token_cookie,
         :authentication_providers,
+        :authentication_provider_resolver,
+        :authentication_provider_gate,
+        :authentication_validator,
         :admin_path,
         :admin_navigation_items,
         :admin_dashboard_widgets,
@@ -26,13 +29,28 @@ module Panda
         :login_logo_path,
         :login_page_title,
         :admin_title,
+        :admin_logo,
+        :admin_settings_path,
+        :admin_logo_actions,
+        :admin_sidebar_footer,
         :initial_admin_breadcrumb,
         :dashboard_redirect_path,
         :avatar_variants,
         :avatar_max_file_size,
         :avatar_max_dimension,
         :avatar_optimization_quality,
-        :avatar_image_processor
+        :avatar_image_processor,
+        :admin_user_menu_items,
+        :additional_head_content,
+        :compact_navigation,
+        :admin_user_edit_content,
+        :admin_user_after_update,
+        :admin_user_show_content,
+        :admin_user_index_columns,
+        :restrict_user_creation,
+        :after_user_invited,
+        :invite_form_content,
+        :post_authentication_redirect
       def initialize
         @user_class = "Panda::Core::User"
@@ -46,6 +64,9 @@ module Panda
         @mailer_default_url_options = {host: "localhost:3000"}
         @session_token_cookie = :panda_session
         @authentication_providers = {}
+        @authentication_provider_resolver = nil
+        @authentication_provider_gate = nil
+        @authentication_validator = nil
         @admin_path = "/admin"
         @default_theme = "default"
@@ -74,6 +95,14 @@ module Panda
             icon: "fa-solid fa-user"
           }
+          items << {
+            label: "Settings",
+            icon: "fa-solid fa-gear",
+            children: [
+              {label: "Feature Flags", path: "#{@admin_path}/feature_flags"}
+            ]
+          }
           items
         }
         @admin_dashboard_widgets = ->(user) { [] }
@@ -83,12 +112,24 @@ module Panda
         # Profile and UI customization
         @additional_user_params = []
+        # Themes offered in the My Profile dropdown as [label, value] pairs.
+        # Assigning this REPLACES the default list — host apps registering
+        # their own theme should include any built-ins they still want, e.g.
+        #   config.available_themes = [["Default", "default"], ["Acme", "acme"]]
+        # The value is stamped as <html data-theme="..."> on admin pages;
+        # supply the matching html[data-theme='...'] variable block via
+        # config.additional_head_content (see app/assets/tailwind/application.css).
         @available_themes = [["Default", "default"], ["Sky", "sky"]]
         @login_logo_path = nil
         @login_page_title = "Panda Admin"
         @admin_title = "Panda Admin"
+        @admin_logo = nil  # Proc/lambda returning HTML for sidebar logo area (e.g. SVG + title)
+        @admin_settings_path = nil  # Path for the settings gear icon in the logo area (nil hides it)
+        @admin_logo_actions = []  # Array of {path:, icon:, title:} hashes rendered as icon links next to the settings gear
+        @admin_sidebar_footer = nil  # Proc/lambda returning HTML for the bottom of the sidebar (replaces version text)
         @initial_admin_breadcrumb = nil  # Proc that returns [label, path]
         @dashboard_redirect_path = nil  # Path to redirect to after login (defaults to admin_root_path)
+        @additional_head_content = nil  # Proc/lambda returning HTML to inject into <head> (e.g. theme stylesheets, fonts)
         # Avatar configuration
         @avatar_variants = {
@@ -101,6 +142,159 @@ module Panda
         @avatar_max_dimension = 800
         @avatar_optimization_quality = 85
         @avatar_image_processor = :vips # or :mini_magick
+        # Navigation density — false (spacious, default) or true (compact, for apps with many nav items)
+        @compact_navigation = false
+        # User management hooks — Procs that host apps set to inject content into user views/callbacks
+        @admin_user_edit_content = nil   # Proc(user, form_builder, view_context) → HTML
+        @admin_user_after_update = nil   # Proc(user, params, current_user)
+        @admin_user_show_content = nil   # Proc(user, view_context) → HTML
+        @admin_user_index_columns = nil  # Proc(user, view_context) → HTML
+        # Authentication restriction — when truthy, find_or_create_from_auth_hash
+        # will NOT create new User records for unknown emails on OAuth login.
+        # Accepts a boolean or a callable (receives auth_hash, returns truthy to restrict).
+        @restrict_user_creation = false
+        # Invitation hooks — host app can extend the invite flow
+        @after_user_invited = nil        # Proc(user, params, current_user) — called after successful invite
+        @invite_form_content = nil       # Proc(form_builder, view_context) → HTML — extra fields in invite form
+        # Post-authentication redirect — Proc(user, request) → URL string or nil.
+        # Called after successful OAuth login. Return a URL to redirect there,
+        # or nil to fall through to the default redirect logic.
+        @post_authentication_redirect = nil
+        # Legacy extensible user menu items (prefer NavigationRegistry with position: :bottom)
+        @admin_user_menu_items = []
+        # Register default user menu as a bottom navigation section (idempotent)
+        register_default_user_menu
+      end
+      # Returns the authentication providers for the given request.
+      # If an +authentication_provider_resolver+ proc is configured it is
+      # called with the request to allow per-tenant provider filtering.
+      # Otherwise the static +authentication_providers+ hash is returned.
+      def resolved_authentication_providers(request = nil)
+        if authentication_provider_resolver && request
+          authentication_provider_resolver.call(request)
+        else
+          authentication_providers
+        end
+      end
+      # Register a new admin navigation section via {NavigationRegistry}.
+      #
+      # Sections with the same label as an existing base section are skipped.
+      # Use +after:+ or +before:+ to control positioning relative to other sections.
+      #
+      # @param label [String] Section label displayed in the sidebar
+      # @param icon [String] FontAwesome icon class (e.g. "fa-solid fa-users")
+      # @param after [String, nil] Insert after the section with this label
+      # @param before [String, nil] Insert before the section with this label
+      # @param visible [Proc, nil] Lambda receiving user, hides section when false
+      # @param permission [Symbol, nil] Permission key — hides section unless user is authorized
+      # @param position [Symbol] :top (default) or :bottom
+      # @yield [NavigationRegistry::SectionContext] Optional block for adding items
+      #
+      # @example Add a section with items
+      #   config.insert_admin_menu_section "Members",
+      #     icon: "fa-solid fa-users",
+      #     after: "Website" do |section|
+      #       section.item "Onboarding", path: "members/onboarding"
+      #     end
+      #
+      # @see NavigationRegistry.section
+      def insert_admin_menu_section(label, icon: nil, after: nil, before: nil, visible: nil, permission: nil, position: :top, &block)
+        Panda::Core::NavigationRegistry.section(label, icon: icon, after: after, before: before, visible: visible, permission: permission, position: position, &block)
+      end
+      # Register an item to be appended to an existing admin navigation section.
+      #
+      # If the target section doesn't exist at build time, the item is silently
+      # skipped. Use +path:+ for admin-relative paths or +url:+ for absolute URLs.
+      #
+      # @param label [String] Item label displayed in the sidebar
+      # @param section [String] Label of the target section to add to
+      # @param path [String, nil] Relative path (auto-prefixed with admin_path)
+      # @param url [String, nil] Absolute URL (used as-is, no prefixing)
+      # @param target [String, nil] HTML target attribute (e.g. "_blank")
+      # @param visible [Proc, nil] Lambda receiving user, hides item when false
+      # @param before [Symbol, String, nil] :all or label — position within section
+      # @param after [Symbol, String, nil] :all or label — position within section
+      # @param method [Symbol, nil] HTTP method (e.g. :delete)
+      # @param button_options [Hash] Extra options for button_to
+      # @param path_helper [Symbol, nil] Route helper resolved at build time
+      #
+      # @example Add to an existing section
+      #   config.insert_admin_menu_item "Feature Flags",
+      #     section: "Settings",
+      #     path: "feature_flags"
+      #
+      # @example Permission-gated item
+      #   config.insert_admin_menu_item "Suggestions",
+      #     section: "Tools",
+      #     path: "cms/content_suggestions",
+      #     permission: :review_content
+      #
+      # @see NavigationRegistry.item
+      # rubocop:disable Metrics/ParameterLists
+      def insert_admin_menu_item(label, section:, path: nil, url: nil, target: nil,
+        visible: nil, permission: nil, before: nil, after: nil, method: nil, button_options: {}, path_helper: nil)
+        Panda::Core::NavigationRegistry.item(
+          label, section: section, path: path, url: url, target: target,
+          visible: visible, permission: permission, before: before, after: after,
+          method: method, button_options: button_options, path_helper: path_helper
+        )
+      end
+      # rubocop:enable Metrics/ParameterLists
+      # Convenience: add an item to the user menu (bottom section).
+      # @param label [String] Item label
+      # @param path [String, nil] Path (auto-prefixed with admin_path)
+      # @param url [String, nil] Full URL (used as-is)
+      # @param visible [Proc, nil] Lambda receiving user, hides item when false
+      # @param position [Symbol] :before_logout (default) or :top
+      def insert_admin_user_menu_item(label, path: nil, url: nil, visible: nil, position: :before_logout)
+        before_opt = (position == :before_logout) ? "Logout" : nil
+        before_opt = :all if position == :top
+        Panda::Core::NavigationRegistry.item(
+          label, section: "My Account", path: path, url: url,
+          visible: visible, before: before_opt
+        )
+      end
+      # Register a post-build filter that conditionally hides items by label.
+      # @param label [String] Label to match
+      # @param visible [Proc] Lambda receiving user — item hidden when false
+      def filter_admin_menu(label, visible:)
+        Panda::Core::NavigationRegistry.filter(label, visible: visible)
+      end
+      # Register a dashboard widget via WidgetRegistry.
+      # @param label [String] Widget label
+      # @param component [Proc] Lambda receiving user, returns a component instance
+      # @param visible [Proc, nil] Lambda receiving user, hides widget when false
+      # @param position [Integer] Sort order (lower first)
+      def register_admin_dashboard_widget(label, component:, visible: nil, position: 0)
+        Panda::Core::WidgetRegistry.register(label, component: component, visible: visible, position: position)
+      end
+      private
+      # Register the default user menu items as a bottom navigation section.
+      # Idempotent: skips if "My Account" is already registered.
+      def register_default_user_menu
+        return if Panda::Core::NavigationRegistry.sections.any? { |s| s[:label] == "My Account" }
+        Panda::Core::NavigationRegistry.section("My Account", position: :bottom) do |s|
+          s.item "My Profile", path: "my_profile/edit"
+          s.item "Login & Security", path: "my_profile/logins"
+          s.item "Logout", path_helper: :admin_logout_path, method: :delete,
+            button_options: {id: "logout-link", data: {turbo: false}}
+        end
       end
     end

data/lib/panda/core/engine/admin_controller_config.rb CHANGED Viewed

@@ -11,12 +11,9 @@ module Panda
           # Create AdminController alias after controllers are loaded
           # This allows other gems to inherit from Panda::Core::AdminController
           config.to_prepare do
-            # Use on_load to ensure ActionController is available
-            ActiveSupport.on_load(:action_controller_base) do
-              # Create the alias if it doesn't exist
-              unless Panda::Core.const_defined?(:AdminController)
-                Panda::Core.const_set(:AdminController, Panda::Core::Admin::BaseController)
-              end
+            unless Panda::Core.const_defined?(:AdminController)
+              admin_base = "Panda::Core::Admin::BaseController".safe_constantize
+              Panda::Core.const_set(:AdminController, admin_base) if admin_base
             end
           end
         end

data/lib/panda/core/engine/autoload_config.rb CHANGED Viewed

@@ -6,17 +6,29 @@ module Panda
       module AutoloadConfig
         extend ActiveSupport::Concern
+        # Custom autoload paths for panda-core
+        # Note: Must be Strings (not Pathnames) for Rails 8.1.2+ compatibility
+        AUTOLOAD_DIRECTORIES = %w[
+          app/builders
+          app/components
+          app/services
+          app/models
+          app/helpers
+          app/constraints
+        ].freeze
         included do
-          # These must run BEFORE initialization, so this is allowed
-          config.autoload_paths << root.join("app/builders")
-          config.autoload_paths << root.join("app/components")
-          config.autoload_paths << root.join("app/services")
-          config.autoload_paths << root.join("app/models")
-          config.autoload_paths << root.join("app/helpers")
-          config.autoload_paths << root.join("app/constraints")
+          # Use initializer with before: to ensure paths are added before
+          # Rails freezes the autoload_paths array in Rails 8.1.2+
+          initializer "panda_core.set_autoload_paths", before: :set_autoload_paths do |app|
+            AUTOLOAD_DIRECTORIES.each do |dir|
+              path = root.join(dir).to_s
+              next unless File.directory?(path)
-          # Mirror eager-load as needed
-          config.eager_load_paths.concat(config.autoload_paths)
+              app.config.autoload_paths << path unless app.config.autoload_paths.include?(path)
+              app.config.eager_load_paths << path unless app.config.eager_load_paths.include?(path)
+            end
+          end
         end
       end
     end

data/lib/panda/core/engine/omniauth_config.rb CHANGED Viewed

@@ -26,27 +26,42 @@ module Panda
           "developer" => :developer
         }.freeze
-        included do
-          if respond_to?(:initializer)
-            initializer "panda_core.omniauth" do |app|
-              require_relative "../oauth_providers"
-              Panda::Core::OAuthProviders.setup
-              load_yaml_provider_overrides!
-              mount_omniauth_middleware(app)
+        class_methods do
+          # Load YAML provider overrides during engine definition (before middleware setup)
+          def load_yaml_provider_overrides_early!
+            path = Panda::Core::Engine.root.join("config/providers.yml")
+            return unless File.exist?(path)
+            yaml = YAML.load_file(path) || {}
+            (yaml["providers"] || {}).each do |name, settings|
+              Panda::Core.config.authentication_providers[name.to_s] ||= {}
+              Panda::Core.config.authentication_providers[name.to_s].deep_merge!(settings)
+            end
+          end
-              # Configure OmniAuth globals AFTER all initializers have run
-              # This ensures Panda::Core.config.admin_path has been set by the app
-              app.config.after_initialize do
-                configure_omniauth_globals
-              end
+          # Configure OmniAuth globals
+          def configure_omniauth_globals
+            OmniAuth.configure do |c|
+              c.allowed_request_methods = [:post]
+              c.path_prefix = "#{Panda::Core.config.admin_path}/auth"
+              # OmniAuth's built-in AuthenticityTokenProtection uses
+              # Rack::Protection's :csrf session key, but Rails stores its
+              # CSRF token under :_csrf_token. This session key mismatch
+              # causes "Forbidden" errors when submitting the admin login form.
+              #
+              # Disabling OmniAuth's request_validation_phase is safe because:
+              # - Production OAuth providers (Google, GitHub, Microsoft) are
+              #   protected by the OAuth state parameter in the callback phase
+              # - The developer provider only runs in development/test
+              # - The login form still requires POST (allowed_request_methods)
+              c.request_validation_phase = nil
             end
           end
         end
-        private
-        # 1. YAML overrides
+        # Instance method for loading YAML provider overrides (for testing)
+        # @deprecated Use class method load_yaml_provider_overrides_early! instead
         def load_yaml_provider_overrides!
           path = Panda::Core::Engine.root.join("config/providers.yml")
           return unless File.exist?(path)
@@ -58,31 +73,15 @@ module Panda
           end
         end
-        # 2. Global settings
-        def configure_omniauth_globals
-          OmniAuth.configure do |c|
-            c.allowed_request_methods = [:post]
-            c.path_prefix = "#{Panda::Core.config.admin_path}/auth"
-          end
-        end
-        # 3. Middleware insertion
-        def mount_omniauth_middleware(app)
-          ctx = self  # Capture the Engine/Concern context
-          Panda::Core::Middleware.use(app, OmniAuth::Builder) do
-            Panda::Core.config.authentication_providers.each do |name, settings|
-              ctx.send(:configure_provider, self, name, settings)
-            end
-          end
-        end
-        # 4. Provider builder
+        # Configure a single provider on the OmniAuth builder
+        # @param builder [OmniAuth::Builder] the OmniAuth builder instance
+        # @param name [String] the provider name (may be an alias)
+        # @param settings [Hash] provider configuration
         def configure_provider(builder, name, settings)
           symbol = PROVIDER_REGISTRY[name.to_s]
           unless symbol
-            Rails.logger.warn("[panda-core] Unknown OmniAuth provider: #{name.inspect}")
+            Rails.logger.warn("[panda-core] Unknown OmniAuth provider: #{name.inspect}") if defined?(Rails.logger)
             return
           end
@@ -91,7 +90,7 @@ module Panda
           # Skip providers without credentials (except developer which doesn't need them)
           has_credentials = settings[:client_id].present? && settings[:client_secret].present?
           if symbol != :developer && !has_credentials
-            Rails.logger.info("[panda-core] Skipping OmniAuth provider #{name.inspect}: missing client_id or client_secret")
+            Rails.logger.info("[panda-core] Skipping OmniAuth provider #{name.inspect}: missing client_id or client_secret") if defined?(Rails.logger)
             return
           end
@@ -104,6 +103,77 @@ module Panda
             builder.provider symbol, options
           end
         end
+        included do
+          # Only run Rails Engine-specific code when included into an actual Engine
+          # This prevents errors when the module is included into test dummy classes
+          next unless self < ::Rails::Engine
+          # Load YAML overrides early during engine definition so they're available
+          # when the OmniAuth middleware block is evaluated
+          load_yaml_provider_overrides_early!
+          if respond_to?(:initializer)
+            # Set up OAuth providers
+            config.before_initialize do |app|
+              require_relative "../oauth_providers"
+              Panda::Core::OAuthProviders.setup
+            end
+            # Configure OmniAuth globals AFTER all initializers have run
+            # This ensures Panda::Core.config.admin_path has been set by the app
+            initializer "panda_core.omniauth_globals" do |app|
+              app.config.after_initialize do
+                Panda::Core::Engine.configure_omniauth_globals
+              end
+            end
+          end
+          # Add OmniAuth middleware during engine configuration
+          # Rails 8.1.2+ freezes the middleware stack before initializers run
+          config.app_middleware.use OmniAuth::Builder do
+            # Capture the builder instance for provider configuration
+            builder = self
+            Panda::Core.config.authentication_providers.each do |name, settings|
+              symbol = PROVIDER_REGISTRY[name.to_s]
+              unless symbol
+                Rails.logger.warn("[panda-core] Unknown OmniAuth provider: #{name.inspect}") if defined?(Rails.logger)
+                next
+              end
+              next if symbol == :developer && !Rails.env.development?
+              # Skip providers without credentials (except developer which doesn't need them)
+              has_credentials = settings[:client_id].present? && settings[:client_secret].present?
+              if symbol != :developer && !has_credentials
+                Rails.logger.info("[panda-core] Skipping OmniAuth provider #{name.inspect}: missing client_id or client_secret") if defined?(Rails.logger)
+                next
+              end
+              options = (settings[:options] || {}).dup
+              options[:name] = settings[:path_name] if settings[:path_name].present?
+              # Inject a setup lambda that gates providers per-request (e.g. per-tenant)
+              # and allows dynamic redirect_uri override for multi-subdomain OAuth flows.
+              gate = Panda::Core.config.authentication_provider_gate
+              if gate && symbol != :developer
+                provider_name = name.to_s
+                options[:setup] = ->(env) {
+                  unless gate.call(provider_name, env)
+                    raise OmniAuth::Error, "Provider not enabled for this workspace"
+                  end
+                }
+              end
+              if settings[:client_id] && settings[:client_secret]
+                builder.provider symbol, settings[:client_id], settings[:client_secret], options
+              else
+                builder.provider symbol, options
+              end
+            end
+          end
+        end
       end
     end
   end

data/lib/panda/core/engine/pending_migrations_check.rb ADDED Viewed

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+module Panda
+  module Core
+    class Engine < ::Rails::Engine
+      module PendingMigrationsCheck
+        extend ActiveSupport::Concern
+        included do
+          initializer "panda_core.pending_migrations_check", after: :load_config_initializers do
+            config.after_initialize do
+              next unless Rails.env.local?
+              check_for_pending_panda_migrations
+            rescue ActiveRecord::NoDatabaseError, ActiveRecord::ConnectionNotEstablished, NoMethodError
+              # Skip when DB isn't available (asset precompilation, etc.)
+              # or when migration API differs across Rails versions
+            end
+          end
+        end
+        private
+        def check_for_pending_panda_migrations
+          paths = ActiveRecord::Migrator.migrations_paths
+          context = ActiveRecord::MigrationContext.new(paths)
+          return unless context.needs_migration?
+          pending = context.open.pending_migrations
+          panda_pending = pending.select { |m| m.filename.match?(/panda/i) }
+          return if panda_pending.empty?
+          install_tasks = Panda::Core::ModuleRegistry.modules.keys
+            .unshift("panda-core").uniq
+            .map { |gem_name| "#{gem_name.tr("-", "_")}:install:migrations" }
+            .join(" ")
+          Rails.logger.warn(
+            "\n⚠️  #{panda_pending.size} pending Panda migration(s) detected.\n" \
+            "   Run: bin/rails #{install_tasks} db:migrate\n"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/panda/core/engine/sqlite_schema_compatibility.rb ADDED Viewed

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+module Panda
+  module Core
+    module SqliteSchemaCompatibility
+      extend ActiveSupport::Concern
+      included do
+        initializer "panda_core.sqlite_schema_compatibility" do
+          next unless ActiveRecord::Base.configurations.configs_for(env_name: Rails.env).any? { |cfg| cfg.adapter == "sqlite3" }
+          require "active_record/connection_adapters/sqlite3_adapter"
+          sqlite_adapter = ActiveRecord::ConnectionAdapters::SQLite3Adapter
+          unless sqlite_adapter.singleton_class.method_defined?(:native_database_types_with_panda_sqlite_compatibility)
+            sqlite_adapter.singleton_class.prepend(Module.new do
+              def native_database_types_with_panda_sqlite_compatibility
+                super.merge(
+                  uuid: {name: "varchar"},
+                  jsonb: {name: "json"}
+                )
+              end
+              alias_method :native_database_types, :native_database_types_with_panda_sqlite_compatibility
+            end)
+          end
+          table_definition = ActiveRecord::ConnectionAdapters::SQLite3::TableDefinition
+          # Rails' SQLite TableDefinition intentionally omits these helpers, but our
+          # cross-database migrations/schema use them. We define them once at boot.
+          table_definition.send(:define_column_methods, :uuid) unless table_definition.method_defined?(:uuid)
+          table_definition.send(:define_column_methods, :jsonb) unless table_definition.method_defined?(:jsonb)
+        end
+      end
+    end
+  end
+end

data/lib/panda/core/engine/{phlex_config.rb → view_component_config.rb} RENAMED Viewed

@@ -3,8 +3,8 @@
 module Panda
   module Core
     class Engine < ::Rails::Engine
-      # Phlex configuration
-      module PhlexConfig
+      # ViewComponent configuration
+      module ViewComponentConfig
         extend ActiveSupport::Concern
         included do
@@ -26,12 +26,10 @@ module Panda
             end
           end
-          # Load Phlex base component after Rails application is initialized
+          # Load ViewComponent base component after Rails application is initialized
           # This ensures Rails.application.routes is available
-          initializer "panda_core.phlex_base", after: :load_config_initializers do
-            require "phlex"
-            require "phlex-rails"
-            require "literal"
+          initializer "panda_core.view_component_base", after: :load_config_initializers do
+            require "view_component"
             require "tailwind_merge"
             # Load the base component