admin_suite 0.3.1 → 0.5.0

data/app/views/admin_suite/shared/_sidebar.html.erb

@@ -60,20 +60,26 @@
 
         <% if active %>
           <div class="mt-1 ml-11 space-y-0.5 text-sm">
-            <% portal[:sections].sort_by { |(_k, s)| s[:label].to_s }.each do |_section_key, section| %>
+            <% portal[:sections].sort_by { |(_k, s)| [ (s[:order] || 100).to_i, s[:label].to_s ] }.each do |_section_key, section| %>
               <div class="text-xs font-medium text-white/70 uppercase tracking-wider px-3 pt-2 pb-1">
                 <%= section[:label] %>
               </div>
-              <% section[:items].sort_by { |it| [ (it[:order] || 100).to_i, it[:label].to_s ] }.each do |item| %>
-                <% item_active = request.path.start_with?(item[:path].to_s) %>
-                <%= link_to item[:path],
-                    class: "flex items-center gap-2 px-3 py-1.5 rounded #{item_active ? "text-white bg-white/20" : "text-white/90 hover:bg-white/10 hover:text-white"}",
-                    data: { turbo_frame: "_top" } do %>
-                  <% if item[:icon].present? %>
-                    <%= admin_suite_icon(item[:icon], class: "w-3.5 h-3.5 text-white/90") %>
+              <% if section[:items].any? %>
+                <% section[:items].sort_by { |it| [ (it[:order] || 100).to_i, it[:label].to_s ] }.each do |item| %>
+                  <% item_active = request.path.start_with?(item[:path].to_s) %>
+                  <%= link_to item[:path],
+                      class: "flex items-center gap-2 px-3 py-1.5 rounded #{item_active ? "text-white bg-white/20" : "text-white/90 hover:bg-white/10 hover:text-white"}",
+                      data: { turbo_frame: "_top" } do %>
+                    <% if item[:icon].present? %>
+                      <%= admin_suite_icon(item[:icon], class: "w-3.5 h-3.5 text-white/90") %>
+                    <% end %>
+                    <span class="truncate"><%= item[:label] %></span>
                   <% end %>
-                  <span class="truncate"><%= item[:label] %></span>
                 <% end %>
+              <% else %>
+                <div class="px-3 py-1.5 text-xs text-white/50 italic">
+                  No resources in this section yet.
+                </div>
               <% end %>
             <% end %>
           </div>

data/app/views/layouts/admin_suite/application.html.erb

@@ -29,9 +29,17 @@
 
     <%= stylesheet_link_tag "rouge", "data-turbo-track": "reload" %>
 
-    <%# EasyMDE Markdown Editor %>
-    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/easymde@2.18.0/dist/easymde.min.css" data-turbo-track="reload">
-    <script src="https://cdn.jsdelivr.net/npm/easymde@2.18.0/dist/easymde.min.js" data-turbo-track="reload"></script>
+    <%# EasyMDE Markdown Editor: vendored (see app/assets/vendor), loaded only
+        when the page actually renders a :markdown field (see
+        AdminSuite::UI::FieldRendererRegistry's :markdown handler, which sets
+        this content_for). %>
+    <%= yield :easymde_assets %>
+
+    <%# Chart.js: vendored (see app/assets/vendor), loaded only when the page
+        actually renders a chart panel with data (see
+        app/views/admin_suite/panels/_chart.html.erb, which sets this
+        content_for). %>
+    <%= yield :chart_assets %>
 
     <% if respond_to?(:javascript_importmap_tags) %>
       <%= javascript_importmap_tags %>

data/config/routes.rb

@@ -14,6 +14,9 @@ AdminSuite::Engine.routes.draw do
   scope ":portal/:resource_name" do
     get "/", to: "resources#index", as: :resources
     get "/new", to: "resources#new", as: :new_resource
+    # Must precede "/:id" -- a literal segment match wins over the dynamic
+    # one only because Rails tries routes in declaration order.
+    get "/search", to: "resources#search", as: :search_resources
     post "/", to: "resources#create"
     get "/:id", to: "resources#show", as: :resource
     get "/:id/edit", to: "resources#edit", as: :edit_resource

data/lib/admin/base/action_executor.rb

@@ -116,14 +116,20 @@ module Admin
           "#{action.label} completed successfully",
           redirect_url: redirect_url_for_action(action, action_result)
         )
-      rescue ActiveRecord::RecordInvalid => e
-        failure_result("Validation failed: #{e.record.errors.full_messages.join(', ')}")
-      rescue AASM::InvalidTransition => e
-        failure_result("Invalid state transition: #{e.message}")
+      rescue StandardError => e
+        # Neither constant is referenced unless the host actually defines it:
+        # a bare `rescue SomeGem::Error` raises NameError *while handling* the
+        # original exception in hosts without that gem, masking the real error.
+        if defined?(ActiveRecord::RecordInvalid) && e.is_a?(ActiveRecord::RecordInvalid)
+          failure_result("Validation failed: #{e.record.errors.full_messages.join(', ')}")
+        elsif e.class.name.to_s.include?("InvalidTransition")
+          failure_result("Invalid state transition: #{e.message}")
+        else
+          raise
+        end
       end
 
       def redirect_url_for_action(action, action_result)
-        return nil unless action.name.to_sym == :duplicate
         return nil unless action_result.respond_to?(:persisted?) && action_result.persisted?
         return nil unless resource_class.respond_to?(:portal_name) && resource_class.respond_to?(:resource_name_plural)
 
@@ -188,55 +194,17 @@ module Admin
         nil
       end
 
+      # Loads action handler files configured via `AdminSuite.config.action_globs`.
+      #
+      # Kept as a thin wrapper (rather than calling DefinitionLoader directly
+      # from `find_handler_class`) because `test/lib/action_executor_test.rb`
+      # exercises this exact method name against `self.class.handlers_loaded`.
+      #
+      # @return [void]
       def load_action_handlers_for_admin_suite!
         return unless defined?(AdminSuite)
 
-        # Track whether we've already loaded handlers to avoid expensive repeated globs.
-        # In development, this flag is reset by the Rails reloader (see engine.rb).
-        # In production/test, it persists for the process lifetime.
-        return if self.class.handlers_loaded
-
-        files = Array(AdminSuite.config.action_globs).flat_map { |g| Dir[g] }.uniq
-
-        # Set the flag even if no files found - we've done the glob and shouldn't repeat it
-        if files.empty?
-          self.class.handlers_loaded = true
-          return
-        end
-
-        files.each do |file|
-          begin
-            if Rails.env.development?
-              load file
-            else
-              require file
-            end
-          rescue StandardError, ScriptError => e
-            log_action_handler_load_error(file, e)
-
-            # Fail fast in dev/test so broken handler files are immediately discoverable.
-            raise if Rails.env.development? || Rails.env.test?
-          end
-        end
-
-        # We attempted to load the configured handlers. Avoid repeating expensive globs
-        # and file loads for the rest of the process lifetime.
-        self.class.handlers_loaded = true
-      end
-
-      def log_action_handler_load_error(file, error)
-        message = "[AdminSuite] Failed to load action handler file #{file}: #{error.class}: #{error.message}"
-
-        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
-          Rails.logger.error(message)
-
-          backtrace = Array(error.backtrace).take(20).join("\n")
-          Rails.logger.error(backtrace) unless backtrace.empty?
-        else
-          warn(message)
-        end
-      rescue StandardError
-        nil
+        AdminSuite::DefinitionLoader.load!(:actions)
       end
     end
   end

data/lib/admin/base/filter_builder.rb

@@ -3,6 +3,13 @@
 module Admin
   module Base
     class FilterBuilder
+      # Matches the index search box's existing floor: below this,
+      # `apply_search` leaves the scope untouched rather than emitting a
+      # near-useless single/double-character ILIKE. `search_predicate`
+      # (below) is where this now lives, since it's shared with
+      # `ResourcesController#search`.
+      MIN_SEARCH_LENGTH = 3
+
       attr_reader :resource_class, :params
 
       def initialize(resource_class, params)
@@ -26,6 +33,43 @@ module Admin
         params.permit(*permitted_keys).to_h.symbolize_keys
       end
 
+      # Builds the shared ILIKE-over-searchable_fields predicate -- the exact
+      # logic `apply_search` below uses for the index's own search box --
+      # extracted so `ResourcesController#search` (the searchable_select
+      # endpoint) can reuse it verbatim instead of growing a second,
+      # divergent search path over the same whitelist.
+      #
+      # The term is always returned as a value to be bound (`"%term%"`),
+      # never interpolated into the SQL text -- only the (whitelisted) field
+      # *names* from `index_config.searchable_fields` go into the conditions
+      # string, exactly as `apply_search` has always built it. That keeps
+      # this safe against SQL metacharacters in `term`: whatever a caller
+      # passes ends up as a single bound parameter, not part of the query
+      # text.
+      #
+      # Returns nil when no predicate should be applied at all: no index
+      # config, no declared `searchable` fields, a blank term, or a term
+      # shorter than `MIN_SEARCH_LENGTH`. What a nil predicate *means* is
+      # left to the caller -- `apply_search` treats it as "don't filter"
+      # (falls back to the unfiltered scope, correct for an index filter
+      # box), while `ResourcesController#search` treats it as "no results"
+      # (correct for a raw JSON data endpoint, which must never hand back
+      # the unfiltered table just because the query was blank/too short or
+      # the resource has no searchable fields to check).
+      #
+      # @param index_config [Admin::Base::Resource::IndexConfig, nil]
+      # @param term [String, nil]
+      # @return [Array(String, String), nil] [sql_conditions, "%term%"]
+      def self.search_predicate(index_config, term)
+        return nil if index_config.nil?
+        return nil if term.blank?
+        return nil if index_config.searchable_fields.empty?
+        return nil if term.to_s.length < MIN_SEARCH_LENGTH
+
+        conditions = index_config.searchable_fields.map { |field| "#{field} ILIKE :search" }.join(" OR ")
+        [ conditions, "%#{term}%" ]
+      end
+
       private
 
       def index_config
@@ -34,12 +78,11 @@ module Admin
 
       def apply_search(scope)
         return scope unless index_config
-        return scope if params[:search].blank?
-        return scope if index_config.searchable_fields.empty?
-        return scope if params[:search].to_s.length < 3
 
-        search_term = "%#{params[:search]}%"
-        conditions = index_config.searchable_fields.map { |field| "#{field} ILIKE :search" }.join(" OR ")
+        predicate = self.class.search_predicate(index_config, params[:search])
+        return scope unless predicate
+
+        conditions, search_term = predicate
         scope.where(conditions, search: search_term)
       end
 

data/lib/admin/base/resource.rb

@@ -39,6 +39,13 @@ module Admin
     #     end
     #   end
     class Resource
+      extend AdminSuite::Deprecation
+
+      EXPORTABLE_DEPRECATION_MESSAGE_FORMAT =
+        "AdminSuite: %<resource>s calls `exportable`, which is a deprecated " \
+        "no-op and will be removed in 0.6.0. It never actually implemented " \
+        "export in any released version — safe to delete the call."
+
       class << self
         # Model configuration
         attr_reader :model_class, :portal_name, :section_name, :nav_label, :nav_icon, :nav_order
@@ -55,9 +62,6 @@ module Admin
         # Actions configuration
         attr_reader :actions_config
 
-        # Export configuration
-        attr_reader :export_formats
-
         # Sets the model class for this resource
         #
         # @param klass [Class] The ActiveRecord model class
@@ -157,14 +161,6 @@ module Admin
           @actions_config.instance_eval(&block) if block_given?
         end
 
-        # Configures export formats
-        #
-        # @param formats [Array<Symbol>] Export formats (:json, :csv)
-        # @return [void]
-        def exportable(*formats)
-          @export_formats = formats
-        end
-
         # Declares whether the generic resource routes may mutate records.
         # Read-only resources retain index/show access while the controller
         # rejects direct requests to every built-in mutation endpoint.
@@ -176,6 +172,32 @@ module Admin
           @read_only == true
         end
 
+        # Deprecated no-op; removal targeted at 0.6.0 (moved from the
+        # originally-planned 0.5.0 -- pending the gleania/trust_growth host
+        # migrations).
+        #
+        # `exportable` was write-only in every prior release -- it never had
+        # a reader and never drove any export behavior -- but hosts still
+        # call it from resource-definition bodies (gleania: 30 files;
+        # trust_growth: 1). A real removal would raise `NoMethodError` at
+        # definition-load time, and in production `DefinitionLoader` logs
+        # and swallows that, so the resource just silently vanishes from the
+        # admin. Kept as a no-op instead, so those files keep loading.
+        #
+        # Deliberately does not restore `@export_formats` or any reader --
+        # only the harmless no-op comes back.
+        #
+        # @param _formats [Array<Symbol>] ignored
+        # @return [void]
+        def exportable(*_formats)
+          # `warn_once`, `warn_once_sink` and `reset_deprecation_notices!`
+          # come from `AdminSuite::Deprecation`, extended above. Keyed on the
+          # resource class itself, so each resource warns independently (and
+          # only once) rather than one call anywhere silencing every other
+          # resource's first call.
+          warn_once(name, format(EXPORTABLE_DEPRECATION_MESSAGE_FORMAT, resource: name))
+        end
+
         # Returns the resource name derived from class name
         #
         # @return [String]
@@ -252,7 +274,7 @@ module Admin
       # Index view configuration
       class IndexConfig
         attr_reader :searchable_fields, :sortable_fields, :default_sort, :default_sort_direction,
-                    :columns_list, :filters_list, :stats_list, :per_page
+                    :columns_list, :filters_list, :stats_list, :per_page, :includes_list
 
         def initialize
           @searchable_fields = []
@@ -263,6 +285,7 @@ module Admin
           @filters_list = []
           @stats_list = []
           @per_page = 25
+          @includes_list = []
         end
 
         def searchable(*fields)
@@ -279,6 +302,23 @@ module Admin
           @per_page = count
         end
 
+        # Kills the index's association N+1 (Task 3 made `belongs_to`
+        # columns render as links, so each one now genuinely dereferences
+        # the association -- one query per row without this). The
+        # controller applies this to the filtered scope only when the
+        # scope actually responds to `#includes` -- PORO test doubles and
+        # some host scopes don't -- and swallows a bad association name
+        # (typo, renamed association) by logging and rendering
+        # unoptimized rather than 500ing. `nil` entries (e.g. a stray
+        # `includes nil`) are dropped rather than stored and handed to the
+        # scope verbatim.
+        #
+        # @param associations [Array<Symbol, String>]
+        # @return [void]
+        def includes(*associations)
+          @includes_list = associations.flatten.compact
+        end
+
         def columns(&block)
           builder = ColumnsBuilder.new
           builder.instance_eval(&block) if block_given?
@@ -309,19 +349,19 @@ module Admin
           @columns << ColumnDefinition.new(
             name: name,
             content: content,
-            render: options[:render],
             header: options[:header] || name.to_s.humanize,
             css_class: options[:class],
             type: options[:type],
             toggle_field: options[:toggle_field],
             label_color: options[:label_color],
             label_size: options[:label_size],
-            sortable: options[:sortable] || false
+            sortable: options[:sortable] || false,
+            align: options[:align]
           )
         end
       end
 
-      ColumnDefinition = Struct.new(:name, :content, :render, :header, :css_class, :type, :toggle_field, :label_color, :label_size, :sortable, keyword_init: true)
+      ColumnDefinition = Struct.new(:name, :content, :header, :css_class, :type, :toggle_field, :label_color, :label_size, :sortable, :align, keyword_init: true)
 
       class FiltersBuilder
         attr_reader :filters
@@ -393,7 +433,8 @@ module Admin
             variants: options[:variants],
             label_color: options[:label_color],
             label_size: options[:label_size],
-            parent_field: options[:parent_field]
+            parent_field: options[:parent_field],
+            resource: options[:resource]
           )
         end
 
@@ -420,6 +461,12 @@ module Admin
         :collection, :create_url, :accept, :rows, :readonly,
         :if_condition, :unless_condition, :multiple, :creatable,
         :preview, :variants, :label_color, :label_size, :parent_field,
+        # `resource:` (e.g. `resource: :companies`) lets a `searchable_select`
+        # field resolve its search URL automatically against the gem's own
+        # search endpoint, rather than requiring every host to supply a
+        # `collection:` String pointing at a hand-rolled route. See
+        # `render_searchable_select` in `app/helpers/admin_suite/base_helper.rb`.
+        :resource,
         keyword_init: true
       )
 
@@ -470,7 +517,25 @@ module Admin
 
         private
 
+        # Struct members already given a dedicated home above. Everything
+        # else in the panel/section DSL call (`source:`, `empty:`,
+        # `language:`, plus `columns:` again — see below) is forwarded
+        # verbatim to the renderer via `ShowSectionDefinition#options`.
+        RESERVED_SECTION_OPTION_KEYS = %i[
+          fields association limit render title display link_to resource
+          paginate pagination per_page collapsible collapsed hide_blank
+        ].freeze
+
         def build_section(name, options)
+          # `columns:` is deliberately NOT excluded here even though it also
+          # populates the dedicated `columns` member below (used today by
+          # association-table display). Built-in renderers like
+          # `:table_from` only ever see `section.options`, not the section
+          # itself, so `columns:` has to reach `options[:columns]` too or a
+          # DSL author's explicit column list would be silently dropped in
+          # favor of the renderer's own inference.
+          leftover_options = options.except(*RESERVED_SECTION_OPTION_KEYS)
+
           ShowSectionDefinition.new(
             name: name,
             fields: options[:fields] || [],
@@ -485,7 +550,15 @@ module Admin
             paginate: options[:paginate] || options[:pagination] || false,
             per_page: options[:per_page],
             collapsible: options[:collapsible] || false,
-            collapsed: options[:collapsed] || false
+            collapsed: options[:collapsed] || false,
+            # `fields:`-only rows whose value is blank (nil or `.empty?`)
+            # are omitted entirely -- see `show_value_blank?` in
+            # `AdminSuite::BaseHelper`, which reads this member. Default
+            # `false`: no existing show page changes unless it opts in.
+            # Deliberately NOT `value.blank?` -- that's true for `false`
+            # and `0`, both of which are meaningful, rendered values today.
+            hide_blank: options[:hide_blank] || false,
+            options: leftover_options
           )
         end
       end
@@ -493,6 +566,8 @@ module Admin
       ShowSectionDefinition = Struct.new(
         :name, :fields, :association, :limit, :render, :title,
         :display, :columns, :link_to, :resource, :paginate, :per_page, :collapsible, :collapsed,
+        :hide_blank,
+        :options,
         keyword_init: true
       )
 

data/lib/admin_suite/configuration.rb

@@ -17,7 +17,6 @@ module AdminSuite
       :action_globs,
       :portal_globs,
       :dashboard_globs,
-      :portals,
       :custom_renderers,
       :icon_renderer,
       :docs_url,
@@ -25,7 +24,6 @@ module AdminSuite
       :partials,
       :theme,
       :host_stylesheet,
-      :tailwind_cdn,
       :root_dashboard_title,
       :root_dashboard_description,
       :root_dashboard_definition,
@@ -33,6 +31,22 @@ module AdminSuite
       :on_action_executed,
       :resolve_action_handler
 
+    attr_reader :portals
+
+    # Records that the host explicitly assigned portals (even to `{}`), so
+    # the engine's built-in defaults are never re-applied over explicit
+    # host intent. See #portals_configured?.
+    def portals=(value)
+      @portals_configured = true
+      @portals = value
+    end
+
+    # True once the host has assigned `config.portals` itself, distinct
+    # from the engine having applied its own defaults.
+    def portals_configured?
+      @portals_configured == true
+    end
+
     def initialize
       @authenticate = nil
       @current_actor = nil
@@ -49,6 +63,7 @@ module AdminSuite
       @portal_globs = []
       @dashboard_globs = []
       @portals = {}
+      @portals_configured = false
       @custom_renderers = {}
       @icon_renderer = nil
       @docs_url = nil
@@ -56,7 +71,6 @@ module AdminSuite
       @partials = {}
       @theme = { primary: :indigo, secondary: :purple }
       @host_stylesheet = nil
-      @tailwind_cdn = true
       @root_dashboard_title = nil
       @root_dashboard_description = nil
       @root_dashboard_definition = nil
@@ -64,5 +78,20 @@ module AdminSuite
       @on_action_executed = nil
       @resolve_action_handler = nil
     end
+
+    # Sets the built-in default portals without marking portals as
+    # host-configured.
+    #
+    # Engine-internal: public so `AdminSuite::Engine.apply_default_portals!`
+    # can call it directly, without reaching past `Configuration`'s privacy
+    # via `send`. Not part of the host-facing configuration API -- a host
+    # app should never call this itself; use `config.portals = { ... }` (or
+    # `config.portals = {}` to suppress the built-in defaults). This
+    # deliberately bypasses the public `portals=` writer so gem-applied
+    # defaults stay distinguishable from an explicit host assignment
+    # (including an explicit `{}` meant to suppress defaults).
+    def default_portals!(value)
+      @portals = value
+    end
   end
 end