admin_suite 0.4.0 → 0.6.1

data/app/views/admin_suite/panels/_chart.html.erb

@@ -1,7 +1,102 @@
-<% data = Array(panel_eval(panel.options[:data])) %>
+<%
+  raw_data =
+    begin
+      Array(panel_eval(panel.options[:data]))
+    rescue StandardError => e
+      Rails.logger&.warn(
+        "AdminSuite: chart panel #{panel.title.inspect} data raised #{e.class}: #{e.message}\n" \
+        "#{e.backtrace&.first(5)&.join("\n")}"
+      )
+      []
+    end
+  # Accept String-keyed rows (JSONB, API payloads) the same way data_table does
+  # (see lib/admin_suite/renderer.rb#data_table), and skip any row that isn't
+  # Hash-like: a data proc can *succeed* and still hand back a junk row (e.g.
+  # a bare Integer or nil mixed into the array), and indexing that with
+  # `row[:value]` raises rather than returning nil, so it must be filtered
+  # before it reaches the height math below.
+  data = raw_data.filter_map do |row|
+    row = row.symbolize_keys if row.respond_to?(:symbolize_keys)
+    next unless row.is_a?(Hash)
+
+    raw_value = row[:value]
+    # Total coercion: `Float()` (unlike `#to_f`) raises on Boolean/Hash/Array/
+    # nil/non-numeric-String values instead of silently returning 0 or
+    # blowing up later, so a junk value degrades to 0 here rather than
+    # 500ing the dashboard when the height math below reaches it.
+    numeric = begin
+      Float(raw_value)
+    rescue ArgumentError, TypeError
+      0.0
+    end
+
+    # `value` stays as originally provided (e.g. an Integer or a numeric
+    # String) so titles/labels still read "Mon: 3" rather than "Mon: 3.0" —
+    # `numeric` is the only thing the height math and the JSON series handed
+    # to Chart.js should ever touch.
+    { label: row[:label], value: raw_value, numeric: numeric }
+  end
+%>
 <% total = panel.options[:total] %>
-<% color = (panel.options[:color] || theme_primary).to_sym %>
-<% max_value = (data.map { |d| d[:value].to_f }.max || 1).to_f %>
+<%
+  # Total coercion, same idiom as `type:` below: `.to_sym` alone raises for
+  # any `color:` value that doesn't implement it (an Integer, Boolean, ...) --
+  # `NoMethodError` 500ing the whole dashboard. `.to_s` first makes it total;
+  # an unrecognized result (e.g. `color: 42` -> `:"42"`) already falls through
+  # to indigo in both the `case` below and the JS `COLOR_HEX` map, so no new
+  # fallback logic is needed here.
+  color = (panel.options[:color] || theme_primary).to_s.presence&.to_sym
+%>
+<%
+  # `type:` is validated here, not just passed through, because it flows to
+  # both the Chart.js config (an unrecognized string throws inside Chart.js)
+  # and the degraded ERB branch below — a host typo (e.g. `type: :pie`, which
+  # Chart.js itself doesn't even ship) must degrade to the bar chart, not
+  # break the dashboard or silently render nothing.
+  chart_types = %i[bar line area doughnut]
+  # `.to_s` first: `presence&.to_sym` alone raises on any non-String/Symbol
+  # scalar (an Integer, Float, or `true`/`false` don't define `#to_sym`),
+  # which is exactly the host-typo shape this fallback exists to catch.
+  # `.to_s` makes the coercion total -- `42 → "42" → :"42"` (fails the
+  # allowlist below, warns, falls back to :bar) and `nil → "" → nil` via
+  # `presence` (falls back to :bar silently, since an unspecified type is
+  # not a typo).
+  chart_type = panel.options[:type].to_s.presence&.to_sym
+  if chart_type && !chart_types.include?(chart_type)
+    Rails.logger&.warn(
+      "AdminSuite: chart panel #{panel.title.inspect} has unknown type #{chart_type.inspect}; " \
+      "falling back to :bar. Supported: #{chart_types.join(', ')}."
+    )
+    chart_type = nil
+  end
+  chart_type ||= :bar
+%>
+<%
+  # Chart height: 64px (the old `h-16` bar height) was fine for sparkline-ish
+  # CSS bars, but is not usable for a real Chart.js chart with axes/legend.
+  # Emitted as an inline style below, not an interpolated Tailwind height
+  # class (which the content scanner can't see at build time, since it's
+  # never a literal class name in source — see panels_helper.rb's span
+  # comment for the same lesson), so both the degraded bars and the upgraded
+  # canvas share an identical, explicit height and there's no layout shift
+  # when Chart.js takes over.
+  # Total coercion, same idiom as `data:`'s per-row `value` above: `presence`
+  # filters `nil`/`""`/`false`/`{}`/`[]`, but `true`, Symbols, non-empty
+  # Arrays and non-empty Hashes all survive it and none respond to `#to_i` --
+  # `NoMethodError` 500ing the whole dashboard. `Integer(Float(...))` raises
+  # on exactly those (plus non-numeric Strings), so anything that can't
+  # genuinely parse degrades to the default instead. `RangeError` covers its
+  # `FloatDomainError` subclass: `Float::INFINITY` and `NAN` parse fine but
+  # have no Integer form, and a host can reach them by computing a height
+  # from a ratio that divides by zero.
+  chart_height = begin
+    Integer(Float(panel.options[:height]))
+  rescue ArgumentError, TypeError, RangeError
+    192
+  end
+  chart_height = 192 if chart_height <= 0
+%>
+<% max_value = (data.map { |d| d[:numeric] }.max || 1).to_f %>
 <% max_value = 1.0 if max_value.zero? %>
 
 <% bar_color = case color
@@ -23,23 +118,68 @@ end %>
   </div>
 
   <% if data.any? %>
-    <div class="flex items-end gap-1 h-16">
-      <% data.each do |d| %>
-        <% value = d[:value].to_f %>
-        <% height_float = (value / max_value) * 100.0 %>
-        <% height_float = 0.0 if height_float.nan? || height_float.infinite? %>
-        <% height = height_float.round %>
-        <% height = [height, 2].max if value.positive? %>
-        <div class="flex-1 h-full flex flex-col items-center justify-end">
-          <div class="w-full rounded-t <%= bar_color %> transition-all" style="height: <%= height %>%"
-               title="<%= "#{d[:label]}: #{d[:value]}" %>"></div>
-        </div>
+    <%
+      # Load the vendored Chart.js assets only on pages that actually render a
+      # chart with data, via a dedicated content_for hook consumed by the
+      # layout (see app/views/layouts/admin_suite/application.html.erb).
+      # Mirrors the EasyMDE hook in
+      # lib/admin_suite/ui/field_renderer_registry.rb's :markdown handler.
+      # Guarded so multiple chart panels on one page don't emit the tags twice.
+    %>
+    <% unless content_for?(:chart_assets) %>
+      <% content_for(:chart_assets) do %>
+        <%# "vendor/chart.umd.min" (not bare "chart.umd.min"): Propshaft resolves
+            assets by path relative to a load-path root, and app/assets/vendor
+            lives *under* the already-registered app/assets root, so its files
+            are found at "vendor/chart.umd.min.js". %>
+        <%= javascript_include_tag "vendor/chart.umd.min", "data-turbo-track": "reload" %>
       <% end %>
-    </div>
+    <% end %>
 
-    <div class="flex gap-1 mt-2">
-      <% data.each do |d| %>
-        <div class="flex-1 text-center text-xs text-slate-400" title="<%= d[:label] %>"><%= d[:label] %></div>
+    <%
+      # Chart.js gets the coerced numeric series, never the raw display
+      # value — a Boolean/Hash/Array/nil `value` would otherwise reach
+      # Chart.js as-is and break the chart, even though it's already been
+      # safely zeroed out for the CSS bars above.
+      series_for_chart_js = data.map { |d| { label: d[:label], value: d[:numeric] } }
+    %>
+    <div data-controller="admin-suite--chart"
+         data-admin-suite--chart-series-value="<%= series_for_chart_js.to_json %>"
+         data-admin-suite--chart-type-value="<%= chart_type %>"
+         data-admin-suite--chart-color-value="<%= color %>"
+         data-admin-suite--chart-height-value="<%= chart_height %>">
+      <% if chart_type == :doughnut %>
+        <%# A stacked bar makes no sense as a doughnut's degraded (no-JS)
+            state -- there's no "height" a doughnut slice maps to. A plain
+            labelled value list carries the same data legibly instead. %>
+        <div class="divide-y divide-slate-100" data-admin-suite--chart-target="list">
+          <% data.each do |d| %>
+            <div class="flex items-center justify-between py-1.5 text-sm">
+              <span class="text-slate-600 truncate" title="<%= d[:label] %>"><%= d[:label] %></span>
+              <span class="font-medium text-slate-900"><%= d[:value] %></span>
+            </div>
+          <% end %>
+        </div>
+      <% else %>
+        <div class="flex items-end gap-1" data-admin-suite--chart-target="bars" style="height: <%= chart_height %>px;">
+          <% data.each do |d| %>
+            <% value = d[:numeric] %>
+            <% height_float = (value / max_value) * 100.0 %>
+            <% height_float = 0.0 if height_float.nan? || height_float.infinite? %>
+            <% height = height_float.round %>
+            <% height = [height, 2].max if value.positive? %>
+            <div class="flex-1 h-full flex flex-col items-center justify-end">
+              <div class="w-full rounded-t <%= bar_color %> transition-all" style="height: <%= height %>%"
+                   title="<%= "#{d[:label]}: #{d[:value]}" %>"></div>
+            </div>
+          <% end %>
+        </div>
+
+        <div class="flex gap-1 mt-2" data-admin-suite--chart-target="labels">
+          <% data.each do |d| %>
+            <div class="flex-1 text-center text-xs text-slate-400" title="<%= d[:label] %>"><%= d[:label] %></div>
+          <% end %>
+        </div>
       <% end %>
     </div>
   <% else %>

data/app/views/admin_suite/resources/index.html.erb

@@ -125,6 +125,14 @@
               </div>
             <% end %>
 
+            <div>
+              <label class="block text-sm font-medium text-slate-700 mb-1">Per page</label>
+              <%= select_tag :per_page,
+                  options_for_select([ 25, 50, 100 ], @pagy&.limit),
+                  class: "form-input w-full",
+                  data: { "admin-suite--live-filter-target": "input", action: "change->admin-suite--live-filter#submit" } %>
+            </div>
+
             <div class="flex gap-2 pt-2">
               <button type="submit" class="admin-suite-btn-primary flex-1 text-sm font-medium rounded-lg transition-colors">
                 Apply
@@ -143,9 +151,9 @@
       <%= turbo_frame_tag "resource_results", data: { turbo_action: "advance" } do %>
         <div class="bg-white rounded-xl border border-slate-200 overflow-hidden">
           <% if @collection.any? %>
-          <div class="overflow-x-auto">
+          <div class="overflow-x-auto overflow-y-auto max-h-[70vh]">
             <table class="min-w-full divide-y divide-slate-200">
-              <thead class="bg-slate-50">
+              <thead class="bg-slate-50 sticky top-0 z-10">
                 <tr>
                   <%
                     current_sort = params[:sort]&.to_sym || resource_config.index_config.default_sort
@@ -189,9 +197,21 @@
               </thead>
               <tbody class="divide-y divide-slate-200">
                 <% @collection.each do |record| %>
-                  <tr class="hover:bg-slate-50">
+                  <%
+                    show_path = url_for(action: :show, id: record.to_param)
+                  %>
+                  <%= tag.tr class: "hover:bg-slate-50 cursor-pointer",
+                      data: {
+                        record_id: record.to_param,
+                        controller: "admin-suite--click-actions",
+                        action: "click->admin-suite--click-actions#navigate",
+                        "admin-suite--click-actions-url-value": show_path
+                      } do %>
                     <% resource_config.index_config.columns_list.each do |column| %>
-                      <td class="px-4 py-3 text-sm text-slate-900">
+                      <%
+                        td_class = [ "px-4 py-3 text-sm text-slate-900", column_align_class(column.align), column.css_class ].reject(&:blank?).join(" ")
+                      %>
+                      <td class="<%= td_class %>">
                         <%= render_column_value(record, column) %>
                       </td>
                     <% end %>
@@ -211,7 +231,7 @@
                         <% end %>
                       </div>
                     </td>
-                  </tr>
+                  <% end %>
                 <% end %>
               </tbody>
             </table>

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

@@ -64,16 +64,22 @@
               <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

@@ -35,6 +35,12 @@
         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 %>
       <%= javascript_import_module_tag "admin_suite_application" %>

data/config/routes.rb

@@ -7,6 +7,11 @@ AdminSuite::Engine.routes.draw do
   get "docs(/)", to: "docs#index", as: :docs
   get "docs/*path", to: "docs#show", as: :doc, format: false
 
+  # Must precede the portal catch-all, which would otherwise treat "mcp" as
+  # a portal name.
+  post "mcp", to: "mcp#create", as: :mcp
+  match "mcp", to: "mcp#create", via: [:get, :delete]
+
   # Portal dashboards (e.g. /ops, /email). Accept optional trailing slash.
   get ":portal(/)", to: "portals#show", as: :portal
 
@@ -14,6 +19,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/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

@@ -41,11 +41,6 @@ module Admin
     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.5.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
@@ -172,28 +167,13 @@ module Admin
           @read_only == true
         end
 
-        # Deprecated no-op, removed in 0.5.0.
-        #
-        # `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))
+        # Opts this resource out of the model-facing MCP surface.
+        def mcp(enabled)
+          @mcp_enabled = enabled
+        end
+
+        def mcp_enabled?
+          @mcp_enabled.nil? ? true : !!@mcp_enabled
         end
 
         # Returns the resource name derived from class name
@@ -272,7 +252,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 = []
@@ -283,6 +263,7 @@ module Admin
           @filters_list = []
           @stats_list = []
           @per_page = 25
+          @includes_list = []
         end
 
         def searchable(*fields)
@@ -299,6 +280,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?
@@ -335,12 +333,13 @@ module Admin
             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, :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
@@ -412,7 +411,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
 
@@ -439,6 +439,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
       )
 
@@ -495,7 +501,7 @@ module Admin
         # 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
+          paginate pagination per_page collapsible collapsed hide_blank
         ].freeze
 
         def build_section(name, options)
@@ -523,6 +529,13 @@ module Admin
             per_page: options[:per_page],
             collapsible: options[:collapsible] || 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
@@ -531,6 +544,7 @@ 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/auth/host_user.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Auth
+    # Authenticates against the host application's own user.
+    #
+    # This is the standard strategy and the one the docs lead with: most
+    # adopters already have a users table with a role, or a separate
+    # admin/developer user type. HTTP Basic and any future mechanism are
+    # additional.
+    #
+    #   config.auth_strategy = :host_user
+    #   config.auth_options  = { resolve: ->(controller) { controller.current_user } }
+    #
+    # The resolver returns the host's user object, or nil to deny. Whatever
+    # it returns is passed through `Auth.normalize_actor`, so `config.authorize`
+    # always receives a real object or nil -- never a bare `true`.
+    class HostUser < Strategy
+      def authenticate!(controller)
+        resolver = options[:resolve]
+
+        unless resolver.respond_to?(:call)
+          Rails.logger&.error(
+            "AdminSuite: auth_strategy :host_user requires config.auth_options[:resolve] " \
+            "(a callable taking the controller). Denying every request until it is set."
+          )
+          return nil
+        end
+
+        actor =
+          begin
+            resolver.call(controller)
+          rescue StandardError => e
+            Rails.logger&.warn("AdminSuite: :host_user resolver raised #{e.class}: #{e.message}; denying.")
+            nil
+          end
+
+        Auth.normalize_actor(actor)
+      end
+    end
+  end
+end

data/lib/admin_suite/auth/strategy.rb

@@ -12,7 +12,7 @@ module AdminSuite
       attr_reader :options
 
       def initialize(options = {})
-        @options = options
+        @options = options.symbolize_keys
       end
 
       # @param controller [ActionController::Base]

data/lib/admin_suite/auth.rb

@@ -24,10 +24,25 @@ module AdminSuite
       def registered
         @registry.keys
       end
+
+      # One definition of "is this a usable actor?", shared by every surface.
+      #
+      # Legacy `HostHook` returns `true` to mean "authenticated, but I could
+      # not name anybody". That is an answer to a different question than
+      # authorization asks, so it is not an actor. Lives here rather than in
+      # a controller so the MCP surface -- which has no controller -- cannot
+      # drift from the web UI's interpretation.
+      def normalize_actor(value)
+        return nil if value.nil? || value.equal?(true) || value.equal?(false)
+
+        value
+      end
     end
   end
 end
 
 require "admin_suite/auth/http_basic"
 require "admin_suite/auth/host_hook"
+require "admin_suite/auth/host_user"
 AdminSuite::Auth.register(:http_basic, AdminSuite::Auth::HttpBasic)
+AdminSuite::Auth.register(:host_user, AdminSuite::Auth::HostUser)

data/lib/admin_suite/authorization_context.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  # Surface-agnostic context handed to `config.authorize`.
+  #
+  # Replaces the old `controller:` keyword, which could not be honestly
+  # populated for a non-HTTP surface. `surface` lets one hook express
+  # different policy per entry point -- e.g. reads from anywhere, writes
+  # only from the human UI.
+  class AuthorizationContext
+    SURFACES = %i[web mcp].freeze
+
+    attr_reader :surface, :controller, :request
+
+    def initialize(surface:, controller: nil, request: nil)
+      unless SURFACES.include?(surface)
+        raise ArgumentError, "Unknown AdminSuite authorization surface #{surface.inspect}. Expected one of #{SURFACES.inspect}."
+      end
+
+      @surface = surface
+      @controller = controller
+      @request = request
+    end
+
+    def web? = surface == :web
+    def mcp? = surface == :mcp
+  end
+end