admin_suite 0.3.0 → 0.4.0

data/lib/admin_suite/renderer.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  # Base class for panel renderers.
+  #
+  # Host apps subclass this in `app/admin/renderers/*.rb` and reference it
+  # from a show panel:
+  #
+  #   panel :costs, title: "Provider Costs", render: :provider_costs
+  #   # => Admin::Renderers::ProviderCostsRenderer
+  #
+  # Subclasses implement #render and may use the primitives below rather than
+  # hand-building markup, so panels stay visually consistent with the rest of
+  # the admin UI.
+  class Renderer
+    attr_reader :record, :view, :options
+
+    # @param record [Object] the resource being rendered
+    # @param view [ActionView::Base] the calling view/helper context
+    # @param options [Hash] leftover panel DSL options (e.g. `source:`,
+    #   `columns:`, `empty:`, `language:`) forwarded from `ShowSectionDefinition#options`.
+    #   Defaults to `{}` so Task 3's two-arg construction keeps working.
+    def initialize(record, view, options = {})
+      @record = record
+      @view = view
+      @options = options || {}
+    end
+
+    # @return [String] HTML-safe markup for the panel body
+    def render
+      raise NotImplementedError, "#{self.class.name} must implement #render"
+    end
+
+    private
+
+    def content_tag(...) = view.content_tag(...)
+    def safe_join(...) = view.safe_join(...)
+
+    # `ERB::Util#h` (aliased from `html_escape`) is a private instance method
+    # on every Rails view context, including `ActionView::Base` itself — not
+    # just in `ActionView::TestCase`. `view.h(...)` would raise a private-method
+    # `NoMethodError` on every call site, so this goes through `#send` instead.
+    def h(...) = view.send(:h, ...)
+
+    # Resolves the panel's `source:` option: a Proc called with the record
+    # (or with no args, if it takes none), a Symbol/String sent to the
+    # record, or a literal value. Falls back to `default` when no `source:`
+    # option was given.
+    def source_value(default = nil)
+      source = options[:source]
+      case source
+      when Proc then source.arity.zero? ? source.call : source.call(record)
+      when Symbol, String then record.public_send(source)
+      when nil then default
+      else source
+      end
+    end
+
+    # Pretty-printed JSON in a copyable dark block.
+    #
+    # `BaseHelper#render_json_block` takes only the data (no title), so a
+    # title, when given, is rendered as a small heading above the block
+    # rather than threaded into the helper.
+    def json_block(value, title: nil)
+      block = view.render_json_block(value)
+      return block if title.blank?
+
+      safe_join([
+        content_tag(:h4, title, class: "text-sm font-medium text-slate-500 mb-2"),
+        block
+      ])
+    end
+
+    # Syntax-highlighted text block.
+    def code_block(text, language: nil)
+      view.render_text_block(text, language)
+    end
+
+    # @param pairs [Array<Array(String, Object)>] label/value pairs
+    def key_value_list(pairs)
+      rows = pairs.map do |label, value|
+        content_tag(:div, class: "flex justify-between gap-4 py-2 border-b border-slate-100 last:border-0") do
+          safe_join([
+            content_tag(:span, label.to_s, class: "text-sm text-slate-500"),
+            content_tag(:span, value.to_s, class: "text-sm text-slate-900 text-right")
+          ])
+        end
+      end
+      content_tag(:div, safe_join(rows))
+    end
+
+    # @param rows [Array<Hash>] row hashes keyed by the column names. `columns`
+    #   is always an array of Symbols (see callers), but row hashes commonly
+    #   are not — Rails deserializes JSONB columns to String-keyed Hashes, so
+    #   rows are symbolized once here rather than requiring every caller (and
+    #   every host renderer calling this primitive directly) to remember to
+    #   do it themselves. A per-cell `row.key?(c) ? row[c] : row[c.to_s]`
+    #   would avoid the copy but re-checks both key forms on every cell of
+    #   every row; symbolizing each row once up front is both simpler and
+    #   cheaper for any table with more than one column.
+    # @param columns [Array<Symbol>] column order
+    # @param empty [String, nil] message when rows are blank
+    def data_table(rows, columns:, empty: nil)
+      return empty_state(empty || "None found.") if rows.blank?
+
+      rows = rows.map { |row| row.is_a?(Hash) ? row.symbolize_keys : row }
+
+      header = content_tag(:tr, safe_join(columns.map { |c|
+        content_tag(:th, c.to_s.humanize, class: "text-left text-xs font-medium text-slate-400 uppercase tracking-wider pb-2")
+      }))
+
+      body = rows.map do |row|
+        content_tag(:tr, safe_join(columns.map { |c|
+          content_tag(:td, row[c].to_s, class: "py-2 text-sm text-slate-900 border-t border-slate-100")
+        }))
+      end
+
+      content_tag(:div, class: "overflow-x-auto") do
+        content_tag(:table, safe_join([ content_tag(:thead, header), content_tag(:tbody, safe_join(body)) ]), class: "w-full")
+      end
+    end
+
+    # `BaseHelper#render_label_badge` takes `color:` as a keyword argument
+    # (not positional), so it is passed through as one here.
+    def badge(text, color: :slate)
+      view.render_label_badge(text, color: color)
+    end
+
+    def empty_state(message)
+      content_tag(:p, message, class: "text-slate-500 italic text-sm")
+    end
+  end
+end

data/lib/admin_suite/renderer_registry.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  # Maps panel `render:` keys to Renderer classes.
+  #
+  # Two independent stores, so a host following the deprecation advice
+  # printed for a legacy renderer (or simply overriding a built-in) actually
+  # takes effect:
+  #
+  # - `register` / `lookup` — explicit registrations: a host initializer (or
+  #   a spec) calling `RendererRegistry.register(:key, SomeClass)`.
+  # - `register_default` / `lookup_default` — the gem's own boot-time
+  #   registrations (the four built-ins, their two aliases, and the four
+  #   deprecated Gleania renderers — see `lib/admin_suite.rb`).
+  #
+  # `AdminSuite::BaseHelper#render_custom_section` checks `lookup`, then a
+  # host `Admin::Renderers::<Key>Renderer` class, then `lookup_default` —
+  # explicit beats host-class beats gem-default. See that method for the
+  # full precedence chain (legacy `config.custom_renderers` procs come
+  # first, ahead of all of this).
+  module RendererRegistry
+    @registry = {}
+    @defaults = {}
+
+    class << self
+      # Explicit registration (host apps, initializers, specs). Takes
+      # precedence over everything but a legacy `config.custom_renderers`
+      # proc.
+      def register(key, klass)
+        @registry[key.to_sym] = klass
+      end
+
+      # Gem boot-time registration. Only consulted after a host's own
+      # explicit registration and its `Admin::Renderers::<Key>Renderer`
+      # class have both been checked and found nothing.
+      def register_default(key, klass)
+        @defaults[key.to_sym] = klass
+      end
+
+      # @return [Class, nil] the explicit registration for `key`, if any
+      def lookup(key)
+        @registry[key.to_sym]
+      end
+
+      # @return [Class, nil] the gem-default registration for `key`, if any
+      def lookup_default(key)
+        @defaults[key.to_sym]
+      end
+
+      # Every key known to either store (explicit ∪ default).
+      #
+      # @return [Array<Symbol>]
+      def registered
+        (@defaults.keys | @registry.keys)
+      end
+
+      # Test-support only. Removes a single *explicit* registration.
+      #
+      # There is intentionally no bulk `reset!`, and this never touches the
+      # default store: AdminSuite's own built-in renderers register
+      # themselves as defaults at require time, once, for the life of the
+      # process. Specs that register scratch/probe renderers via `register`
+      # should call `unregister` for exactly the key(s) they added, in a
+      # teardown.
+      def unregister(key)
+        @registry.delete(key.to_sym)
+      end
+    end
+  end
+end

data/lib/admin_suite/renderers/code_renderer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Renderers
+    # Syntax-highlighted code panel.
+    class CodeRenderer < Renderer
+      def render
+        text = source_value(record.respond_to?(:code) ? record.code : record.to_s)
+        return empty_state(options[:empty] || "Nothing to display.") if text.blank?
+
+        code_block(text.to_s, language: options[:language])
+      end
+    end
+  end
+end

data/lib/admin_suite/renderers/json_renderer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Renderers
+    # Pretty-printed JSON panel. `source:` defaults to the record's attributes.
+    class JsonRenderer < Renderer
+      def render
+        value = source_value(record.respond_to?(:attributes) ? record.attributes : record)
+        return empty_state(options[:empty] || "Nothing to display.") if value.blank?
+
+        json_block(value)
+      end
+    end
+  end
+end

data/lib/admin_suite/renderers/key_value_renderer.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Renderers
+    # Label/value list panel. `source:` returns a Hash or an Array of
+    # [key, value] pairs.
+    #
+    # Unlike `data_table`, the `key_value_list` primitive has no `empty:`
+    # option (see Task 4 report for why) — emptiness is handled here instead.
+    class KeyValueRenderer < Renderer
+      def render
+        value = source_value({})
+        pairs =
+          case value
+          when Hash then value.to_a
+          when Array then value
+          when nil then []
+          else
+            # A Hash is handled above; anything else that coerces via #to_a
+            # (AR relations, Sets, ...) is supported the same way `Array(value)`
+            # supported it before this guard existed — only reject things
+            # that genuinely aren't enumerable.
+            unless value.respond_to?(:to_a)
+              raise ArgumentError, "key_value expects a Hash or an Array of pairs, got #{value.class}"
+            end
+            value.to_a
+          end
+        return empty_state(options[:empty] || "Nothing to display.") if pairs.blank?
+
+        unless pairs.all? { |pair| pair.is_a?(Array) && pair.size == 2 }
+          raise ArgumentError, "key_value expects a Hash or an Array of [key, value] pairs, " \
+                                "got an Array containing non-pair elements"
+        end
+
+        key_value_list(pairs.map { |k, v| [ k.to_s.humanize, v ] })
+      end
+    end
+  end
+end

data/lib/admin_suite/renderers/legacy_gleania.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Renderers
+    # The four Gleania-specific LLM chat-transcript renderers, moved verbatim
+    # out of `AdminSuite::BaseHelper` (role-coloured message bubbles, tool-call
+    # panels, prompt-template mustache highlighting).
+    #
+    # These are deprecated: they still work in 0.4.0 (logging a warning once
+    # per key per process the first time each is used), and are DELETED in
+    # 0.5.0 (Phase 2b). Gleania is expected to migrate to host-side renderer
+    # classes under `app/admin/renderers/*.rb` before then.
+    #
+    # The renderer bodies below are intentionally byte-equivalent to the
+    # BaseHelper methods they replace, other than `resource` -> `record` and
+    # routing BaseHelper method calls (`render_json_block`, `simple_format`,
+    # `concat`) through `view.` — this class is not `included` into the view,
+    # so those calls can't resolve as bare method sends the way they did
+    # inside the helper module. Do not "improve" this markup: a byte-for-byte
+    # move keeps gleania's Assistant/AI portal pages pixel-identical, and
+    # makes the 0.5.0 deletion a clean removal.
+    module LegacyGleania
+      extend AdminSuite::Deprecation
+
+      DEPRECATION_MESSAGE_FORMAT =
+        "AdminSuite: the :%<key>s renderer is deprecated and will be removed in 0.5.0. " \
+        "Move it to app/admin/renderers in your app."
+
+      class << self
+        # Fires the deprecation sink at most once per `key` per process.
+        # `warn_once_sink` and `reset_deprecation_notices!` come from
+        # `AdminSuite::Deprecation`, extended above.
+        #
+        # @param key [Symbol]
+        # @return [void]
+        def warn_once(key)
+          super(key, format(DEPRECATION_MESSAGE_FORMAT, key: key))
+        end
+      end
+
+      # Verbatim from `BaseHelper#render_prompt_template`.
+      class PromptTemplateRenderer < Renderer
+        def render
+          LegacyGleania.warn_once(:prompt_template_preview)
+
+          template = record.respond_to?(:prompt_template) ? record.prompt_template : nil
+          return content_tag(:p, "No template defined", class: "text-slate-500 italic") if template.blank?
+
+          highlighted_template = h(template).gsub(/\{\{(\w+)\}\}/) do
+            "<span class=\"text-amber-400 bg-amber-900/30 px-1 rounded\">{{#{$1}}}</span>"
+          end
+
+          content_tag(:div, class: "relative group") do
+            view.concat(content_tag(:div, class: "absolute top-2 right-2 flex items-center gap-2") do
+              view.concat(content_tag(:span, "TEMPLATE", class: "text-xs font-medium text-slate-400 uppercase tracking-wider"))
+              view.concat(content_tag(:button,
+                '<svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z"/></svg>'.html_safe,
+                type: "button",
+                class: "p-1 text-slate-400 hover:text-slate-600 opacity-0 group-hover:opacity-100 transition-opacity",
+                data: { controller: "admin-suite--clipboard", action: "click->admin-suite--clipboard#copy", "admin-suite--clipboard-text-value": template },
+                title: "Copy to clipboard"))
+            end)
+
+            view.concat(content_tag(:pre, class: "bg-slate-900 text-slate-100 p-4 rounded-lg overflow-x-auto text-sm font-mono max-h-[600px] overflow-y-auto whitespace-pre-wrap leading-relaxed") do
+              highlighted_template.html_safe
+            end)
+
+            variables = template.scan(/\{\{(\w+)\}\}/).flatten.uniq
+            if variables.any?
+              view.concat(content_tag(:div, class: "mt-3 pt-3 border-t border-slate-700") do
+                view.concat(content_tag(:span, "Variables: ", class: "text-sm text-slate-400"))
+                view.concat(content_tag(:div, class: "inline-flex flex-wrap gap-1 mt-1") do
+                  variables.each do |var|
+                    view.concat(content_tag(:code, "{{#{var}}}", class: "text-xs px-2 py-0.5 bg-amber-900/30 text-amber-400 rounded"))
+                  end
+                end)
+              end)
+            end
+          end
+        end
+      end
+
+      # Verbatim from `BaseHelper#render_messages_preview`.
+      class MessagesPreviewRenderer < Renderer
+        def render
+          LegacyGleania.warn_once(:messages_preview)
+
+          messages = record.respond_to?(:messages) ? record.messages : []
+          if messages.respond_to?(:chronological)
+            messages = messages.chronological
+          end
+          messages = messages.limit(50) if messages.respond_to?(:limit)
+          messages = Array.wrap(messages)
+
+          return content_tag(:p, "No messages", class: "text-slate-500 italic") if messages.blank?
+
+          content_tag(:div, class: "space-y-4 max-h-[600px] overflow-y-auto -mx-6 -mb-6 p-6 pt-0") do
+            messages.each_with_index do |msg, idx|
+              if msg.respond_to?(:role)
+                role = msg.role
+                content = msg.content
+                created_at = msg.respond_to?(:created_at) ? msg.created_at : nil
+              else
+                role = msg["role"] || msg[:role] || "unknown"
+                content = msg["content"] || msg[:content] || ""
+                created_at = msg["created_at"] || msg[:created_at]
+              end
+
+              role_class = case role.to_s
+              when "user" then "bg-blue-50 border-blue-200"
+              when "assistant" then "bg-emerald-50 border-emerald-200"
+              when "tool" then "bg-amber-50 border-amber-200"
+              when "system" then "bg-slate-50 border-slate-200"
+              else "bg-slate-50 border-slate-200"
+              end
+
+              role_icon = case role.to_s
+              when "user"
+                '<svg class="w-4 h-4 text-blue-500" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M16 7a4 4 0 11-8 0 4 4 0 018 0zM12 14a7 7 0 00-7 7h14a7 7 0 00-7-7z"/></svg>'.html_safe
+              when "assistant"
+                '<svg class="w-4 h-4 text-emerald-500" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 3v2m6-2v2M9 19v2m6-2v2M5 9H3m2 6H3m18-6h-2m2 6h-2M7 19h10a2 2 0 002-2V7a2 2 0 00-2-2H7a2 2 0 00-2 2v10a2 2 0 002 2zM9 9h6v6H9V9z"/></svg>'.html_safe
+              when "tool"
+                '<svg class="w-4 h-4 text-amber-500" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z"/></svg>'.html_safe
+              else
+                '<svg class="w-4 h-4 text-slate-400" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 12h.01M12 12h.01M16 12h.01M21 12c0 4.418-4.03 8-9 8a9.863 9.863 0 01-4.255-.949L3 20l1.395-3.72C3.512 15.042 3 13.574 3 12c0-4.418 4.03-8 9-8s9 3.582 9 8z"/></svg>'.html_safe
+              end
+
+              view.concat(content_tag(:div, class: "rounded-lg border p-4 #{role_class}") do
+                view.concat(content_tag(:div, class: "flex items-center justify-between mb-3") do
+                  view.concat(content_tag(:div, class: "flex items-center gap-2") do
+                    view.concat(role_icon)
+                    view.concat(content_tag(:span, role.to_s.capitalize, class: "text-sm font-medium text-slate-700"))
+                  end)
+                  view.concat(content_tag(:div, class: "flex items-center gap-2 text-xs text-slate-400") do
+                    view.concat(content_tag(:span, created_at.strftime("%H:%M:%S"))) if created_at.respond_to?(:strftime)
+                    view.concat(content_tag(:span, "##{idx + 1}"))
+                  end)
+                end)
+
+                content_str = content.to_s
+                if role.to_s == "tool" && content_str.start_with?("{", "[")
+                  begin
+                    parsed = JSON.parse(content_str)
+                    view.concat(view.render_json_block(parsed))
+                  rescue JSON::ParserError
+                    view.concat(content_tag(:div, view.simple_format(h(content_str)), class: "prose prose-sm max-w-none"))
+                  end
+                else
+                  view.concat(content_tag(:div, view.simple_format(h(content_str)), class: "prose prose-sm max-w-none"))
+                end
+              end)
+            end
+          end
+        end
+      end
+
+      # Verbatim from `BaseHelper#render_tool_args_preview`.
+      class ToolArgsRenderer < Renderer
+        def render
+          LegacyGleania.warn_once(:tool_args_preview)
+
+          args = record.respond_to?(:args) ? record.args : (record.respond_to?(:arguments) ? record.arguments : {})
+          result = record.respond_to?(:result) ? record.result : nil
+          error = record.respond_to?(:error) ? record.error : nil
+
+          content_tag(:div, class: "space-y-6") do
+            view.concat(content_tag(:div) do
+              view.concat(content_tag(:h4, "Arguments", class: "text-sm font-medium text-slate-500 mb-2"))
+              if args.present? && args != {}
+                view.concat(view.render_json_block(args))
+              else
+                view.concat(content_tag(:p, "No arguments", class: "text-slate-400 italic text-sm"))
+              end
+            end)
+
+            if result.present? && result != {}
+              view.concat(content_tag(:div, class: "pt-4 border-t border-slate-200") do
+                view.concat(content_tag(:h4, "Result", class: "text-sm font-medium text-slate-500 mb-2"))
+                view.concat(view.render_json_block(result))
+              end)
+            end
+
+            if error.present?
+              view.concat(content_tag(:div, class: "pt-4 border-t border-slate-200") do
+                view.concat(content_tag(:h4, "Error", class: "text-sm font-medium text-red-500 mb-2"))
+                view.concat(content_tag(:div, class: "bg-red-50 border border-red-200 rounded-lg p-4") do
+                  content_tag(:pre, h(error.to_s), class: "text-sm text-red-700 whitespace-pre-wrap font-mono")
+                end)
+              end)
+            end
+          end
+        end
+      end
+
+      # Verbatim from `BaseHelper#render_turn_messages_preview`.
+      class TurnMessagesRenderer < Renderer
+        def render
+          LegacyGleania.warn_once(:turn_messages_preview)
+
+          user_msg = record.respond_to?(:user_message) ? record.user_message : nil
+          asst_msg = record.respond_to?(:assistant_message) ? record.assistant_message : nil
+
+          content_tag(:div, class: "space-y-4") do
+            if user_msg
+              view.concat(content_tag(:div, class: "rounded-lg border p-4 bg-blue-50 border-blue-200") do
+                view.concat(content_tag(:div, class: "flex items-center gap-2 mb-2") do
+                  view.concat('<svg class="w-4 h-4 text-blue-500" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M16 7a4 4 0 11-8 0 4 4 0 018 0zM12 14a7 7 0 00-7 7h14a7 7 0 00-7-7z"/></svg>'.html_safe)
+                  view.concat(content_tag(:span, "User", class: "text-sm font-medium text-slate-700"))
+                end)
+                view.concat(content_tag(:div, view.simple_format(h(user_msg.respond_to?(:content) ? user_msg.content.to_s : user_msg.to_s)), class: "prose prose-sm max-w-none"))
+              end)
+            end
+
+            if asst_msg
+              view.concat(content_tag(:div, class: "rounded-lg border p-4 bg-emerald-50 border-emerald-200") do
+                view.concat(content_tag(:div, class: "flex items-center gap-2 mb-2") do
+                  view.concat('<svg class="w-4 h-4 text-emerald-500" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 3v2m6-2v2M9 19v2m6-2v2M5 9H3m2 6H3m18-6h-2m2 6h-2M7 19h10a2 2 0 002-2V7a2 2 0 00-2-2H7a2 2 0 00-2 2v10a2 2 0 002 2zM9 9h6v6H9V9z"/></svg>'.html_safe)
+                  view.concat(content_tag(:span, "Assistant", class: "text-sm font-medium text-slate-700"))
+                end)
+                view.concat(content_tag(:div, view.simple_format(h(asst_msg.respond_to?(:content) ? asst_msg.content.to_s : asst_msg.to_s)), class: "prose prose-sm max-w-none"))
+              end)
+            end
+
+            view.concat(content_tag(:p, "No messages found", class: "text-slate-400 italic text-sm")) unless user_msg || asst_msg
+          end
+        end
+      end
+    end
+  end
+end

data/lib/admin_suite/renderers/table_from_renderer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module Renderers
+    # Table panel over an Array of Hashes. Columns default to the first row's keys.
+    class TableFromRenderer < Renderer
+      def render
+        rows = source_value([]) || []
+        # A Hash source is the contract violation worth naming; other
+        # Enumerables (AR relations, Sets, ...) coerce cleanly via #to_a and
+        # were supported before this guard existed — don't narrow that away.
+        rows = rows.to_a if !rows.is_a?(Array) && !rows.is_a?(Hash) && rows.respond_to?(:to_a)
+        unless rows.is_a?(Array)
+          raise ArgumentError, "table_from expects an Array of Hashes, got #{rows.class}"
+        end
+
+        columns = options[:columns].presence || rows.first&.keys || []
+        data_table(rows, columns: columns.map(&:to_sym), empty: options[:empty])
+      end
+    end
+  end
+end

data/lib/admin_suite/section_definition.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  # A navigation section within a portal. Sections group resources in the
+  # sidebar; declaring one lets a portal control its label, icon and order
+  # instead of accepting the humanized key and alphabetical placement.
+  class SectionDefinition
+    attr_reader :key
+
+    def initialize(key)
+      @key = key.to_sym
+      @label = nil
+      @icon = nil
+      @order = nil
+      @description = nil
+    end
+
+    def label(value = nil)
+      @label = value if value.present?
+      @label
+    end
+
+    def icon(value = nil)
+      @icon = value if value.present?
+      @icon
+    end
+
+    def order(value = nil)
+      @order = value unless value.nil?
+      @order
+    end
+
+    def description(value = nil)
+      @description = value if value.present?
+      @description
+    end
+
+    def to_nav_meta
+      { label: @label, icon: @icon, order: @order, description: @description }.compact
+    end
+  end
+end

data/lib/admin_suite/ui/field_renderer_registry.rb

@@ -12,10 +12,17 @@ module AdminSuite
           handlers[type.to_sym] = block
         end
 
-        def render(type, view:, f:, field:, resource:, field_class:)
-          handler = handlers[type.to_sym]
-          return nil unless handler
+        # Fallback for unregistered field types: a plain text input. Keeps the
+        # registry total so callers never need a secondary rendering path.
+        def default_handler
+          @default_handler ||= ->(_view, f, field, _resource, field_class) {
+            f.text_field(field.name, class: field_class, placeholder: field.placeholder,
+                         readonly: field.readonly)
+          }
+        end
 
+        def render(type, view:, f:, field:, resource:, field_class:)
+          handler = handlers[type.to_sym] || default_handler
           handler.call(view, f, field, resource, field_class)
         end
       end
@@ -86,7 +93,27 @@ AdminSuite::UI::FieldRendererRegistry.register(:rich_text) do |_view, f, field,
   f.rich_text_area(field.name, class: "prose max-w-none")
 end
 
-AdminSuite::UI::FieldRendererRegistry.register(:markdown) do |_view, f, field, resource, field_class|
+AdminSuite::UI::FieldRendererRegistry.register(:markdown) do |view, f, field, resource, field_class|
+  # Load the vendored EasyMDE assets only on pages that actually render a
+  # markdown field, via a dedicated content_for hook consumed by the layout
+  # (see app/views/layouts/admin_suite/application.html.erb). Guarded so
+  # multiple markdown fields on one form don't emit the tags twice. This
+  # relies on Rails rendering the full view (and any partials/forms it
+  # includes) before the layout is rendered, so content_for set here is
+  # available by the time the layout yields it.
+  unless view.content_for?(:easymde_assets)
+    view.content_for(:easymde_assets) do
+      # "vendor/easymde.min" (not bare "easymde.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/easymde.min.{js,css}".
+      view.safe_join([
+        view.stylesheet_link_tag("vendor/easymde.min", "data-turbo-track": "reload"),
+        view.javascript_include_tag("vendor/easymde.min", "data-turbo-track": "reload")
+      ])
+    end
+  end
+
   f.text_area(field.name, class: "#{field_class} font-mono", rows: field.rows || 12, data: { controller: "admin-suite--markdown-editor" }, placeholder: field.placeholder)
 end
 

data/lib/admin_suite/ui/form_field_renderer.rb

@@ -4,12 +4,9 @@ require "admin_suite/ui/field_renderer_registry"
 
 module AdminSuite
   module UI
-    # Overrides `render_form_field` to use a registry of field renderers,
-    # while leaving the legacy implementation available via `super`.
+    # Implements `render_form_field` using a registry of field renderers.
     module FormFieldRenderer
       def render_form_field(f, field, resource)
-        return super unless defined?(AdminSuite::UI::FieldRendererRegistry)
-
         return if field.if_condition.present? && !field.if_condition.call(resource)
         return if field.unless_condition.present? && field.unless_condition.call(resource)
 
@@ -33,9 +30,6 @@ module AdminSuite
                 field_class: field_class
               )
 
-            # If the registry doesn't know how to render, fall back to legacy behavior.
-            return super if field_html.nil?
-
             concat(field_html)
 
             concat(content_tag(:p, field.help, class: "mt-1 text-sm text-slate-500")) if field.help.present?

data/lib/admin_suite/ui/show_formatter_registry.rb

@@ -102,6 +102,15 @@ AdminSuite::UI::ShowFormatterRegistry.register_class(Float) do |value, view, _re
   view.content_tag(:span, view.number_with_delimiter(value), class: "font-mono")
 end
 
+AdminSuite::UI::ShowFormatterRegistry.register_class(BigDecimal) do |value, view, _record, _field|
+  # `.to_f` avoids number_with_delimiter rendering exponential notation
+  # (e.g. "0.98765e4") for BigDecimal input, at the cost of Float precision
+  # for values beyond Float's exact range (e.g. sub-cent monetary sums).
+  # That's an accepted display-only tradeoff here — don't "fix" this by
+  # dropping the conversion, or exponential notation comes back.
+  view.content_tag(:span, view.number_with_delimiter(value.to_f), class: "font-mono")
+end
+
 AdminSuite::UI::ShowFormatterRegistry.register_default do |value, view, _record, field_name|
   value_str = value.to_s