panda-core 0.12.2 → 1.1.0

data/lib/panda/core/navigation_registry.rb

@@ -0,0 +1,455 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    # Declarative registry for extending admin sidebar navigation.
+    #
+    # Gems and host apps register navigation sections and items at boot time,
+    # and the registry merges them with the base +admin_navigation_items+ lambda
+    # at render time. This avoids the fragile lambda-wrapping pattern where each
+    # gem must capture the existing proc, create a new one, and manipulate the
+    # resulting array with index lookups and insertions.
+    #
+    # == Path resolution
+    #
+    # * +path:+ — auto-prefixed with +admin_path+ (e.g. <tt>path: "feature_flags"</tt>
+    #   becomes <tt>"/admin/feature_flags"</tt>)
+    # * +url:+ — used as-is, for full URLs or absolute paths
+    # * +path_helper:+ — a route helper symbol resolved at build time via +helpers+
+    # * +target:+ — HTML target attribute (e.g. <tt>"_blank"</tt>), omitted when +nil+
+    #
+    # == Visibility and filtering
+    #
+    # * +visible:+ — lambda receiving user, evaluated at build time; item/section
+    #   hidden when false
+    # * +filter()+ — post-build removal of items/sections by label, conditional
+    #   on a user-receiving lambda
+    #
+    # == Usage
+    #
+    # Convenience methods on {Panda::Core::Configuration} delegate here, so the
+    # typical usage is inside a +Panda::Core.configure+ block:
+    #
+    #   # In a host app initializer or engine:
+    #   Panda::Core.configure do |config|
+    #     # Add a new section with items, positioned after "Website"
+    #     config.insert_admin_menu_section "Members",
+    #       icon: "fa-solid fa-users",
+    #       after: "Website" do |section|
+    #         section.item "Onboarding", path: "members/onboarding"
+    #       end
+    #
+    #     # Add an item to an existing section
+    #     config.insert_admin_menu_item "Feature Flags",
+    #       section: "Settings",
+    #       path: "feature_flags"
+    #
+    #     # Permission-based visibility
+    #     config.insert_admin_menu_item "Suggestions",
+    #       section: "Tools",
+    #       path: "cms/content_suggestions",
+    #       visible: -> (user) { user.admin? || user.has_permission?(:review_content) }
+    #
+    #     # Post-build filter (hides for non-admins)
+    #     config.filter_admin_menu "Roles",
+    #       visible: -> (user) { user.admin? }
+    #
+    #     # Bottom section (rendered with UserMenuComponent)
+    #     config.insert_admin_menu_section "Notifications",
+    #       position: :bottom do |s|
+    #         s.item "All", path: "notifications"
+    #       end
+    #   end
+    #
+    # You can also call the class methods directly:
+    #
+    #   Panda::Core::NavigationRegistry.section("Tools", icon: "fa-solid fa-wrench")
+    #   Panda::Core::NavigationRegistry.item("Database", section: "Tools", path: "tools/database")
+    #
+    # == Build order
+    #
+    # {.build} is called once per request by the sidebar component:
+    #
+    # 1. The base +admin_navigation_items+ lambda is called (backward compatible)
+    # 2. Registered sections are inserted (skipped if a section with the same label
+    #    already exists in the base)
+    # 3. Registered items are appended to their target sections
+    # 4. Legacy +admin_user_menu_items+ are migrated into the "My Account" bottom section
+    # 5. Visibility lambdas are evaluated; items/sections hidden when +visible:+ returns false
+    # 6. Post-build filters are applied
+    #
+    # Paths are resolved at build time, so +admin_path+ can be configured after
+    # registrations are made.
+    class NavigationRegistry
+      # Collects items added inside a {.section} block.
+      #
+      # @example
+      #   NavigationRegistry.section("Members", icon: "fa-solid fa-users") do |s|
+      #     s.item "Onboarding", path: "members/onboarding"
+      #     s.item "Directory", path: "members/directory"
+      #   end
+      class SectionContext
+        attr_reader :items
+
+        def initialize
+          @items = []
+        end
+
+        # Register an item within this section.
+        # @param label [String] Display label
+        # @param path [String, nil] Relative path (auto-prefixed with admin_path at build time)
+        # @param url [String, nil] Absolute URL (used as-is)
+        # @param target [String, nil] HTML target attribute (e.g. "_blank")
+        # @param visible [Proc, nil] Lambda receiving user, hides item when false
+        # @param permission [Symbol, nil] Permission key — item hidden unless user is authorized.
+        #   Checked via +config.authorization_policy+. Overridden by +visible:+ if both given.
+        # @param method [Symbol, nil] HTTP method (e.g. :delete for logout buttons)
+        # @param button_options [Hash] Extra options for button_to rendering
+        # @param path_helper [Symbol, nil] Route helper name, resolved at build time via helpers
+        # rubocop:disable Metrics/ParameterLists
+        def item(label, path: nil, url: nil, target: nil, visible: nil, permission: nil,
+          method: nil, button_options: {}, path_helper: nil, badge: nil, badge_color: nil)
+          effective_visible = visible || permission_to_visible(permission)
+          @items << {
+            label: label, path: path, url: url, target: target,
+            visible: effective_visible, method: method, button_options: button_options,
+            path_helper: path_helper, badge: badge, badge_color: badge_color
+          }
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        private
+
+        # Convert a permission key into a visibility lambda.
+        # @param permission [Symbol, nil]
+        # @return [Proc, nil]
+        def permission_to_visible(permission)
+          return nil unless permission
+
+          ->(user) {
+            next true if user.respond_to?(:admin?) && user.admin?
+            policy = Panda::Core.config.authorization_policy
+            policy&.call(user, permission, nil) || false
+          }
+        end
+      end
+
+      @sections = []
+      @items = []
+      @filters = []
+
+      class << self
+        attr_reader :sections, :items, :filters
+
+        # Register a new navigation section.
+        #
+        # If a section with the same label already exists in the base navigation
+        # (from the +admin_navigation_items+ lambda), the registration is skipped
+        # at build time — this prevents duplicate 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 — section hidden unless user is authorized.
+        #   Checked via +config.authorization_policy+. Overridden by +visible:+ if both given.
+        # @param position [Symbol] :top (default) or :bottom — controls sidebar placement
+        # @yield [SectionContext] Optional block for adding items to the section
+        #
+        # @example Add a section with items after "Website"
+        #   section("Members", icon: "fa-solid fa-users", after: "Website") do |s|
+        #     s.item "Onboarding", path: "members/onboarding"
+        #   end
+        #
+        # @example Add a permission-gated section
+        #   section("Settings", icon: "fa-solid fa-gear", permission: :manage_settings)
+        #
+        # @example Add a bottom section (rendered with UserMenuComponent)
+        #   section("Notifications", position: :bottom) do |s|
+        #     s.item "All", path: "notifications"
+        #   end
+        # rubocop:disable Metrics/ParameterLists
+        def section(label, icon: nil, after: nil, before: nil, visible: nil, permission: nil, position: :top, &block)
+          context = SectionContext.new
+          yield context if block
+
+          effective_visible = visible || permission_to_visible(permission)
+
+          @sections << {
+            label: label,
+            icon: icon,
+            after: after,
+            before: before,
+            visible: effective_visible,
+            position: position,
+            items: context.items
+          }
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        # Register an item to be appended to a named section.
+        #
+        # The target section can come from either the base lambda or a
+        # previously registered section. If the section doesn't exist at
+        # build time, the item is silently skipped.
+        #
+        # @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 permission [Symbol, nil] Permission key — item hidden unless user is authorized.
+        #   Checked via +config.authorization_policy+. Overridden by +visible:+ if both given.
+        # @param before [Symbol, String, nil] :all to insert at beginning, or label to insert before
+        # @param after [Symbol, String, nil] :all to insert at end (default), or label to insert after
+        # @param method [Symbol, nil] HTTP method (e.g. :delete for logout buttons)
+        # @param button_options [Hash] Extra options for button_to rendering
+        # @param path_helper [Symbol, nil] Route helper name, resolved at build time via helpers
+        #
+        # @example Add to an existing section with auto-prefixed path
+        #   item("Feature Flags", section: "Settings", path: "feature_flags")
+        #
+        # @example Permission-gated item
+        #   item("Roles", section: "Settings", path: "cms/roles",
+        #     permission: :manage_roles)
+        # rubocop:disable Metrics/ParameterLists
+        def item(label, section:, path: nil, url: nil, target: nil, visible: nil, permission: nil,
+          before: nil, after: nil, method: nil, button_options: {}, path_helper: nil)
+          effective_visible = visible || permission_to_visible(permission)
+          @items << {
+            label: label,
+            section: section,
+            path: path,
+            url: url,
+            target: target,
+            visible: effective_visible,
+            before: before,
+            after: after,
+            method: method,
+            button_options: button_options,
+            path_helper: path_helper
+          }
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        # Register a post-build filter that conditionally hides items by label.
+        # Walks all sections and their children during build().
+        # @param label [String] Label to match
+        # @param visible [Proc] Lambda receiving user — item hidden when false
+        def filter(label, visible:)
+          @filters << {label: label, visible: visible}
+        end
+
+        # Build the final navigation array for the current user.
+        #
+        # Called once per request by the sidebar component. Combines the base
+        # +admin_navigation_items+ lambda with all registered sections, items,
+        # and filters.
+        #
+        # @param user [Object] The current authenticated user
+        # @param helpers [Object, nil] View helpers for resolving path_helper: symbols
+        # @return [Array<Hash>] Navigation items ready for rendering
+        def build(user, helpers: nil)
+          base = Panda::Core.config.admin_navigation_items&.call(user) || []
+          admin_path = Panda::Core.config.admin_path
+
+          # Convert permission: keys from base lambda items into _visible lambdas
+          apply_permission_visibility!(base)
+
+          # Apply registered sections
+          @sections.each do |section|
+            # Skip if a section with this label already exists in base
+            next if base.any? { |item| item[:label] == section[:label] }
+
+            entry = {label: section[:label], icon: section[:icon], position: section[:position], _visible: section[:visible]}
+            if section[:items].any?
+              entry[:children] = section[:items].map { |item|
+                resolved = resolve_item(item, admin_path, helpers)
+                resolved[:_visible] = item[:visible]
+                resolved
+              }
+            end
+
+            insert_section(base, entry, after: section[:after], before: section[:before])
+          end
+
+          # Apply registered items to their target sections
+          @items.each do |item|
+            target_section = base.find { |s| s[:label] == item[:section] }
+            next unless target_section
+
+            target_section[:children] ||= []
+            resolved = resolve_item(item, admin_path, helpers)
+            resolved[:_visible] = item[:visible]
+
+            insert_item(target_section[:children], resolved, before: item[:before], after: item[:after])
+          end
+
+          # Migrate legacy admin_user_menu_items into the "My Account" bottom section
+          legacy_items = Panda::Core.config.admin_user_menu_items
+          if legacy_items&.any?
+            my_account = base.find { |s| s[:label] == "My Account" && s[:position] == :bottom }
+            if my_account
+              legacy_items.each do |menu_item|
+                next if menu_item[:path].blank? && menu_item[:url].blank?
+                resolved = {label: menu_item[:label], path: menu_item[:path]}
+                resolved[:_visible] = menu_item[:visible]
+                # Insert before Logout if it exists
+                logout_idx = my_account[:children]&.index { |c| c[:label] == "Logout" }
+                if logout_idx
+                  my_account[:children].insert(logout_idx, resolved)
+                else
+                  (my_account[:children] ||= []) << resolved
+                end
+              end
+            end
+          end
+
+          # Apply section-level visible: — remove sections hidden for this user
+          base.reject! { |entry| entry[:_visible] && !entry[:_visible].call(user) }
+
+          # Apply item-level visible: — remove children hidden for this user
+          base.each do |entry|
+            next unless entry[:children]
+            entry[:children].reject! { |child| child[:_visible] && !child[:_visible].call(user) }
+          end
+
+          # Apply registered filters — walk all sections and children
+          @filters.each do |filter|
+            base.reject! { |entry| entry[:label] == filter[:label] && !filter[:visible].call(user) }
+            base.each do |entry|
+              next unless entry[:children]
+              entry[:children].reject! { |child| child[:label] == filter[:label] && !filter[:visible].call(user) }
+            end
+          end
+
+          # Clean up internal keys before returning
+          base.each do |entry|
+            entry.delete(:_visible)
+            entry[:position] ||= :top
+            entry[:children]&.each { |child| child.delete(:_visible) }
+          end
+
+          base
+        end
+
+        # Clear all registrations and re-register defaults (for test isolation).
+        # This ensures the default "My Account" bottom section is always present
+        # after a reset, preventing order-dependent test failures.
+        def reset!
+          @sections = []
+          @items = []
+          @filters = []
+          Panda::Core.config.send(:register_default_user_menu)
+        end
+
+        private
+
+        # Convert permission: keys into _visible lambdas for base nav items.
+        # Walks sections and their children from the base lambda.
+        def apply_permission_visibility!(items)
+          items.each do |item|
+            if item[:permission] && !item[:_visible]
+              item[:_visible] = permission_to_visible(item.delete(:permission))
+            end
+            next unless item[:children]
+            item[:children].each do |child|
+              if child[:permission] && !child[:_visible]
+                child[:_visible] = permission_to_visible(child.delete(:permission))
+              end
+            end
+          end
+        end
+
+        # Convert a permission key into a visibility lambda.
+        # Admin users always pass; others are checked via authorization_policy.
+        # @param permission [Symbol, nil]
+        # @return [Proc, nil]
+        def permission_to_visible(permission)
+          return nil unless permission
+
+          ->(user) {
+            next true if user.respond_to?(:admin?) && user.admin?
+            policy = Panda::Core.config.authorization_policy
+            policy&.call(user, permission, nil) || false
+          }
+        end
+
+        # Resolve path:, url:, or path_helper: into a final :path value.
+        # Includes :target, :method, :button_options when present.
+        def resolve_item(item, admin_path, helpers = nil)
+          resolved = {label: item[:label]}
+
+          if item[:path_helper] && helpers
+            resolved[:path] = helpers.panda_core.public_send(item[:path_helper])
+          elsif item[:url]
+            resolved[:path] = item[:url]
+          elsif item[:path]
+            resolved[:path] = "#{admin_path}/#{item[:path]}"
+          elsif item[:path_helper]
+            # Keep path_helper for template-level resolution when helpers unavailable
+            resolved[:path_helper] = item[:path_helper]
+          end
+
+          resolved[:target] = item[:target] if item[:target]
+          resolved[:method] = item[:method] if item[:method]
+          resolved[:button_options] = item[:button_options] if item[:button_options]&.any?
+          resolved[:badge] = item[:badge] if item[:badge]
+          resolved[:badge_color] = item[:badge_color] if item[:badge_color]
+          resolved
+        end
+
+        # Insert a section entry into the base array at the correct position.
+        def insert_section(base, entry, after: nil, before: nil)
+          if after
+            index = base.index { |item| item[:label] == after }
+            if index
+              base.insert(index + 1, entry)
+              return
+            end
+          end
+
+          if before
+            index = base.index { |item| item[:label] == before }
+            if index
+              base.insert(index, entry)
+              return
+            end
+          end
+
+          # Default: append to end
+          base << entry
+        end
+
+        # Insert an item into a section's children at the correct position.
+        def insert_item(children, entry, before: nil, after: nil)
+          if before == :all
+            children.insert(0, entry)
+            return
+          end
+
+          if before.is_a?(String)
+            index = children.index { |child| child[:label] == before }
+            if index
+              children.insert(index, entry)
+              return
+            end
+          end
+
+          if after.is_a?(String)
+            index = children.index { |child| child[:label] == after }
+            if index
+              children.insert(index + 1, entry)
+              return
+            end
+          end
+
+          # Default (including after: :all): append to end
+          children << entry
+        end
+      end
+    end
+  end
+end

data/lib/panda/core/oauth_providers.rb

@@ -1,6 +1,25 @@
 module Panda
   module Core
     module OAuthProviders
+      # Provider metadata for display purposes
+      PROVIDER_INFO = {
+        microsoft_graph: {
+          name: "Microsoft",
+          icon: "fa-brands fa-microsoft",
+          color: "#00a4ef"
+        },
+        google_oauth2: {
+          name: "Google",
+          icon: "fa-brands fa-google",
+          color: "#4285f4"
+        },
+        github: {
+          name: "GitHub",
+          icon: "fa-brands fa-github",
+          color: "#333"
+        }
+      }.freeze
+
       def self.setup
         providers = []
 
@@ -27,6 +46,14 @@ module Panda
 
         providers
       end
+
+      def self.info(provider)
+        PROVIDER_INFO[provider.to_sym] || {
+          name: provider.to_s.titleize,
+          icon: "fa-solid fa-circle-user",
+          color: "#6b7280"
+        }
+      end
     end
   end
 end

data/lib/panda/core/permission_registry.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    # Registry for controller-level permission requirements.
+    #
+    # Gems and host apps register which permissions are needed for each
+    # controller action. The {AdminAuthorization} concern reads this registry
+    # at request time to enforce access control.
+    #
+    # == Usage
+    #
+    #   # In a gem engine (config.to_prepare or initializer):
+    #   Panda::Core::PermissionRegistry.register(
+    #     "Panda::CMS::Admin::PagesController",
+    #     index: :edit_content,
+    #     edit: :edit_content,
+    #     destroy: :delete_content
+    #   )
+    #
+    #   # In a host app initializer:
+    #   Panda::Core::PermissionRegistry.register(
+    #     "Admin::HealthcareProvidersController",
+    #     index: :manage_providers,
+    #     destroy: :manage_providers
+    #   )
+    #
+    # Actions not registered are allowed for any authenticated admin user.
+    # Controllers not registered are also allowed (open by default).
+    #
+    # == How enforcement works
+    #
+    # The {AdminAuthorization} concern calls {.permission_for} to look up
+    # the required permission, then delegates to +authorize!+ (from
+    # {Authorizable}) which checks +config.authorization_policy+.
+    #
+    # Without panda-cms-pro, the default policy is +user.admin?+ — so only
+    # admins pass permission checks. With Pro loaded, the policy uses the
+    # role system, allowing non-admin users with the right permissions.
+    class PermissionRegistry
+      class << self
+        # Register permission requirements for a controller.
+        #
+        # Merges with any previously registered permissions for the same
+        # controller, so multiple gems can contribute to the same controller.
+        #
+        # @param controller_name [String] Fully-qualified controller class name
+        # @param permissions [Hash{Symbol => Symbol}] action → permission_key mapping
+        def register(controller_name, **permissions)
+          registry[controller_name] = (registry[controller_name] || {}).merge(permissions)
+        end
+
+        # Look up the required permission for a specific controller action.
+        #
+        # @param controller_name [String] Fully-qualified controller class name
+        # @param action [Symbol] The controller action name
+        # @return [Symbol, nil] The required permission key, or nil if not registered
+        def permission_for(controller_name, action)
+          registry.dig(controller_name, action)
+        end
+
+        # Return all registered permissions for a controller.
+        #
+        # @param controller_name [String] Fully-qualified controller class name
+        # @return [Hash{Symbol => Symbol}, nil] action → permission_key mapping
+        def permissions_for(controller_name)
+          registry[controller_name]
+        end
+
+        # Return the full registry (deep copy).
+        # @return [Hash]
+        def all
+          registry.transform_values(&:dup)
+        end
+
+        # Clear all registrations (for test isolation).
+        def reset!
+          @registry = {}
+        end
+
+        private
+
+        def registry
+          @registry ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/panda/core/search_registry.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    class SearchRegistry
+      @providers = []
+
+      class << self
+        attr_reader :providers
+
+        # Register a search provider (idempotent — overwrites any existing provider with the same name)
+        # @param name [String] Provider name (e.g., "pages", "posts")
+        # @param search_class [Class] Class that responds to .editor_search(query, limit:)
+        #   and optionally .admin_search(query, limit:) for richer global search results
+        def register(name:, search_class:)
+          @providers.reject! { |p| p[:name] == name }
+          @providers << {name: name, search_class: search_class}
+        end
+
+        # Search all registered providers (editor format)
+        # @param query [String] Search query
+        # @param limit [Integer] Max results per provider
+        # @return [Array<Hash>] Array of { href:, name:, description: }
+        def search(query, limit: 5)
+          return [] if query.blank?
+
+          @providers.flat_map do |provider|
+            provider[:search_class].editor_search(query, limit: limit)
+          rescue => e
+            Rails.logger.warn("[panda-core] Search provider #{provider[:name]} failed: #{e.message}") if defined?(Rails.logger)
+            []
+          end
+        end
+
+        # Search all registered providers (admin format with grouping)
+        # @param query [String] Search query
+        # @param limit [Integer] Max results per provider
+        # @return [Hash] { groups: [{ name:, icon:, results: [{ href:, name:, description: }] }] }
+        def admin_search(query, limit: 5)
+          return {groups: []} if query.blank?
+
+          groups = @providers.filter_map do |provider|
+            klass = provider[:search_class]
+            next unless klass.respond_to?(:admin_search)
+
+            results = klass.admin_search(query, limit: limit)
+            next if results.empty?
+
+            config = klass.respond_to?(:searchable_config) ? klass.searchable_config : {}
+            {
+              name: config[:group] || provider[:name].to_s.titleize,
+              icon: config[:icon],
+              results: results
+            }
+          rescue => e
+            Rails.logger.warn("[panda-core] Admin search provider #{provider[:name]} failed: #{e.message}") if defined?(Rails.logger)
+            nil
+          end
+
+          {groups: groups}
+        end
+
+        def reset!
+          @providers = []
+        end
+      end
+    end
+  end
+end

data/lib/panda/core/seeds/file_categories.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    module Seeds
+      module FileCategories
+        DEFAULTS = [
+          {name: "Media Library", slug: "media-library", icon: "fa-solid fa-photo-film", position: 0},
+          {name: "Page Images", slug: "page-images", icon: "fa-solid fa-file-image", position: 1},
+          {name: "Post Images", slug: "post-images", icon: "fa-solid fa-newspaper", position: 2},
+          {name: "User Avatars", slug: "user-avatars", icon: "fa-solid fa-user-circle", position: 3},
+          {name: "Website Avatars", slug: "website-avatars", icon: "fa-solid fa-users", position: 4},
+          {name: "Form Uploads", slug: "form-uploads", icon: "fa-solid fa-file-arrow-up", position: 5},
+          {name: "Social Media", slug: "social-media", icon: "fab fa-instagram", position: 6}
+        ].freeze
+
+        def self.seed!
+          DEFAULTS.each do |attrs|
+            Panda::Core::FileCategory.find_or_create_by!(slug: attrs[:slug]) do |category|
+              category.name = attrs[:name]
+              category.icon = attrs[:icon]
+              category.position = attrs[:position]
+              category.system = true
+            end
+          end
+        end
+      end
+    end
+  end
+end