admin_suite 0.3.1 → 0.5.0

data/test/lib/form_field_renderer_test.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+module AdminSuite
+  class FormFieldRendererTest < ActionView::TestCase
+    include AdminSuite::BaseHelper
+
+    Record = Struct.new(:name, :body, :enabled, :error_messages) do
+      # Both a class-level and an instance-level `model_name` are needed:
+      # `render_toggle_field`/`render_searchable_select`/`render_multi_select`
+      # all call `resource.class.model_name.param_key` (class-level), while
+      # `form_with` itself wants the instance-level accessor. (`extend
+      # ActiveModel::Naming` would give both via its own delegation, but
+      # then redefining `model_name` below to force the short "Record" name
+      # -- rather than the fully-qualified nested constant name -- clashes
+      # with that delegation and triggers a "method redefined" warning.
+      # Defining both explicitly avoids it.) The pre-existing instance-level
+      # `model_name` never covered the class-level call site because no test
+      # here exercised `:toggle`/`:searchable_select`/`:multi_select` before.
+      def self.model_name
+        @model_name ||= ActiveModel::Name.new(self, nil, "Record")
+      end
+
+      def to_model = self
+      def model_name = self.class.model_name
+      def persisted? = false
+      def to_key = nil
+
+      # render_form_field unconditionally calls `resource.errors[field.name]`
+      # for every field type (to add the error border class / message), so
+      # the double needs an `errors` object supporting `[]` -> Array-like
+      # (`.any?`, `.first`). Most tests here don't exercise an actual
+      # validation error, so a Hash defaulting to `[]` is sufficient; tests
+      # that do pass `error_messages` (a plain Hash of field name -> Array of
+      # messages) to get real per-field errors without losing the default.
+      def errors
+        Hash.new([]).merge(error_messages || {})
+      end
+    end
+
+    def field(name, type, **overrides)
+      Admin::Base::Resource::FieldDefinition.new(
+        {
+          name: name, type: type, required: false, label: name.to_s.humanize,
+          readonly: false, multiple: false, creatable: false, preview: true
+        }.merge(overrides)
+      )
+    end
+
+    def render_field(type, name: :name, error_messages: nil, **field_overrides)
+      record = Record.new("x", "y", true, error_messages)
+      html = nil
+      form_with(model: record, url: "/", scope: :record) { |f| html = render_form_field(f, field(name, type, **field_overrides), record) }
+      html.to_s
+    end
+
+    test "textarea type renders a textarea" do
+      assert_includes render_field(:textarea, name: :body), "<textarea"
+    end
+
+    test "email and url types render matching inputs" do
+      assert_includes render_field(:email), 'type="email"'
+      assert_includes render_field(:url), 'type="url"'
+    end
+
+    test "date and datetime types render matching inputs" do
+      assert_includes render_field(:date), 'type="date"'
+      assert_includes render_field(:datetime), 'type="datetime-local"'
+    end
+
+    test "markdown type wires the markdown editor controller" do
+      assert_includes render_field(:markdown, name: :body), "admin-suite--markdown-editor"
+    end
+
+    test "an unregistered type falls back to a text field" do
+      html = render_field(:totally_unknown_type)
+      assert_includes html, 'type="text"'
+    end
+
+    test "the label is rendered for every field" do
+      assert_includes render_field(:text), "Name"
+    end
+
+    test "a field with a validation error renders the red border and error message" do
+      html = render_field(:text, error_messages: { name: [ "is invalid" ] })
+      assert_includes html, "border-red-500"
+      assert_includes html, "is invalid"
+    end
+
+    # The full set of field types `FieldRendererRegistry` is expected to
+    # have registered (see `lib/admin_suite/ui/field_renderer_registry.rb`).
+    # Pinned explicitly here, NOT derived from the registry itself: an
+    # earlier version of this test iterated `handlers.keys` directly, which
+    # cannot detect a deletion -- a deleted key simply stops appearing in
+    # the iteration, so the loop body never runs for it and the test still
+    # passes with one fewer assertion (verified by deleting the `:toggle`
+    # registration: 42 assertions became 41, 0 failures). The
+    # size-and-membership assertion in the test below is what actually
+    # catches that; a self-referential "iterate the thing you're testing"
+    # loop cannot.
+    EXPECTED_FIELD_TYPES = %i[
+      textarea url email number toggle label select searchable_select
+      dependent_select multi_select tags image attachment trix rich_text
+      markdown file datetime date time json code text string
+    ].freeze
+
+    # :trix/:rich_text both call `f.rich_text_area`, which only exists once
+    # ActionText's FormBuilder extension is loaded -- and per the plan's
+    # Test-harness fact #2, this dummy app is deliberately database-free and
+    # never requires `action_text/engine`. Confirmed by running the
+    # rendering test with them included: `NoMethodError: undefined method
+    # 'rich_text_area'`, not a bug in FieldRendererRegistry. There is no way
+    # to pin these two types in this harness without pulling in ActionText
+    # (and, transitively, ActiveRecord) — out of scope here. Named
+    # explicitly (not an implicit skip) so `EXPECTED_FIELD_TYPES.size` and
+    # the number of types actually exercised below both stay visible and
+    # add up: 24 expected, 2 excluded, 22 rendered.
+    UNTESTABLE_WITHOUT_ACTION_TEXT = %i[trix rich_text].freeze
+
+    test "the registry has exactly the expected set of field types, no more, no fewer" do
+      assert_equal EXPECTED_FIELD_TYPES.sort, AdminSuite::UI::FieldRendererRegistry.handlers.keys.sort
+    end
+
+    test "every expected field type except the ActionText-only ones renders non-empty markup" do
+      sample_collection = [ [ "One", 1 ], [ "Two", 2 ] ]
+      needs_collection = %i[select searchable_select dependent_select multi_select tags]
+
+      (EXPECTED_FIELD_TYPES - UNTESTABLE_WITHOUT_ACTION_TEXT).each do |type|
+        overrides = needs_collection.include?(type) ? { collection: sample_collection } : {}
+        html = render_field(type, **overrides)
+        assert html.present?, "expected #{type.inspect} to render non-empty markup"
+      end
+    end
+  end
+end

data/test/lib/format_table_cell_test.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+module AdminSuite
+  # `format_table_cell` had no direct unit test anywhere in the suite before
+  # this file -- it was only exercised indirectly through
+  # `association_linking_test.rb`'s AR-focused fixtures. Covers the branches
+  # not already pinned there, and specifically the Integer/Float/BigDecimal
+  # delimiting added to match `format_show_value` (see
+  # `ShowValueFormatterTest#"integers and floats render delimited"`).
+  class FormatTableCellTest < ActionView::TestCase
+    include AdminSuite::BaseHelper
+
+    test "nil renders the em dash placeholder" do
+      assert_equal "—", format_table_cell(nil)
+    end
+
+    test "booleans render Yes/No" do
+      assert_equal "Yes", format_table_cell(true)
+      assert_equal "No", format_table_cell(false)
+    end
+
+    test "Time and DateTime render a short date-time" do
+      assert_equal "Jan 02, 03:04", format_table_cell(Time.utc(2026, 1, 2, 3, 4))
+      assert_equal "Jan 02, 03:04", format_table_cell(DateTime.new(2026, 1, 2, 3, 4))
+    end
+
+    test "Date renders a short date" do
+      assert_equal "Jan 02, 2026", format_table_cell(Date.new(2026, 1, 2))
+    end
+
+    test "integers and floats render delimited, matching format_show_value" do
+      assert_equal "1,234,567", format_table_cell(1_234_567)
+      assert_equal "1,234.5", format_table_cell(1234.5)
+    end
+
+    test "BigDecimal renders delimited rather than in exponential notation" do
+      result = format_table_cell(BigDecimal("9876.5"))
+      assert_includes result, "9,876"
+      refute_includes result, "0.98765e4"
+    end
+
+    test "plain strings are truncated at 50 characters" do
+      assert_equal "hello", format_table_cell("hello")
+      assert_equal ("x" * 47) + "...", format_table_cell("x" * 60)
+    end
+  end
+end

data/test/lib/index_includes_test.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# Fixtures for the `includes:` DSL option (Task 4, phase 2b). A scope that
+# genuinely supports `#includes` and records/validates the call, so the
+# controller's "apply when the scope responds" and "degrade when
+# `.includes` itself raises" paths are both exercisable end-to-end. The
+# `LinkingFixtures::Deal`/`ReadOnlyResourceFixtures::Relation` pair (no
+# `#includes` at all) already covers the "skip silently" path -- reused
+# below rather than duplicated.
+module IndexIncludesFixtures
+  class IncludesCapableRelation
+    include Enumerable
+
+    KNOWN_ASSOCIATIONS = %i[company owner].freeze
+
+    attr_reader :includes_calls
+
+    def initialize(records)
+      @records = records
+      @includes_calls = []
+    end
+
+    def each(&block) = @records.each(&block)
+    def count(*) = @records.count
+    def offset(*) = self
+    def limit(*) = self
+
+    # Mirrors real ActiveRecord's eventual `ActiveRecord::AssociationNotFoundError`
+    # for an unknown association name -- raised here at call time (rather
+    # than lazily, as real AR does) so the controller's rescue path around
+    # the `.includes` call site is directly exercisable.
+    def includes(*associations)
+      flat = associations.flatten
+      invalid = flat.reject { |a| KNOWN_ASSOCIATIONS.include?(a.respond_to?(:to_sym) ? a.to_sym : a) }
+      raise ArgumentError, "Association named #{invalid.first.inspect} was not found" if invalid.any?
+
+      @includes_calls << flat
+      self
+    end
+  end
+
+  class Widget
+    extend ActiveModel::Naming
+
+    attr_reader :id, :name
+
+    def initialize(id:, name:)
+      @id = id
+      @name = name
+    end
+
+    RELATION = IncludesCapableRelation.new([ new(id: 1, name: "Widget One") ])
+
+    def self.all = RELATION
+    def self.column_names = %w[id name]
+    def self.primary_key = "id"
+    def self.columns_hash = { "id" => Struct.new(:type).new(:integer) }
+    def self.find(id) = all.find { |w| w.to_param == id.to_s }
+    def to_param = id.to_s
+    def attributes = { "id" => id, "name" => name }
+  end
+
+  class BadWidget
+    extend ActiveModel::Naming
+
+    attr_reader :id, :name
+
+    def initialize(id:, name:)
+      @id = id
+      @name = name
+    end
+
+    RELATION = IncludesCapableRelation.new([ new(id: 1, name: "Bad Widget") ])
+
+    def self.all = RELATION
+    def self.column_names = %w[id name]
+    def self.primary_key = "id"
+    def self.columns_hash = { "id" => Struct.new(:type).new(:integer) }
+    def self.find(id) = all.find { |w| w.to_param == id.to_s }
+    def to_param = id.to_s
+    def attributes = { "id" => id, "name" => name }
+  end
+
+  # Self-contained (this file is runnable standalone via
+  # `rake test TEST=test/lib/index_includes_test.rb`, so it can't reach
+  # into fixtures defined only in association_linking_test.rb): a scope
+  # with no `#includes` method at all, mirroring
+  # `ReadOnlyResourceFixtures::Relation`, backing a resource that
+  # nonetheless declares `includes :company`. Exercises the "skip
+  # silently, don't raise" path.
+  class NoIncludesWidget
+    extend ActiveModel::Naming
+
+    attr_reader :id, :name
+
+    def initialize(id:, name:)
+      @id = id
+      @name = name
+    end
+
+    def self.all = ReadOnlyResourceFixtures::Relation.new([ new(id: 1, name: "Plain Widget") ])
+    def self.column_names = %w[id name]
+    def self.primary_key = "id"
+    def self.columns_hash = { "id" => Struct.new(:type).new(:integer) }
+    def self.find(id) = all.find { |w| w.to_param == id.to_s }
+    def to_param = id.to_s
+    def attributes = { "id" => id, "name" => name }
+  end
+end
+
+module Admin
+  module Resources
+    class IndexIncludesWidgetResource < Admin::Base::Resource
+      model IndexIncludesFixtures::Widget
+      portal :ops
+      section :observability
+
+      index do
+        columns { column :name }
+        includes :company, :owner
+      end
+    end
+
+    class IndexIncludesBadWidgetResource < Admin::Base::Resource
+      model IndexIncludesFixtures::BadWidget
+      portal :ops
+      section :observability
+
+      index do
+        columns { column :name }
+        includes :nonexistent_association
+      end
+    end
+
+    class IndexIncludesNoIncludesWidgetResource < Admin::Base::Resource
+      model IndexIncludesFixtures::NoIncludesWidget
+      portal :ops
+      section :observability
+
+      index do
+        columns { column :name }
+        includes :company
+      end
+    end
+  end
+end
+
+module AdminSuite
+  class IndexIncludesTest < ActionDispatch::IntegrationTest
+    test "IndexConfig#includes stores the list of associations" do
+      config = Admin::Base::Resource::IndexConfig.new
+      config.includes(:company, :owner)
+      assert_equal [ :company, :owner ], config.includes_list
+    end
+
+    test "IndexConfig#includes defaults to an empty list" do
+      assert_equal [], Admin::Base::Resource::IndexConfig.new.includes_list
+    end
+
+    test "IndexConfig#includes drops a nil association instead of storing garbage" do
+      config = Admin::Base::Resource::IndexConfig.new
+      config.includes(nil)
+      assert_equal [], config.includes_list
+    end
+
+    test "IndexConfig#includes tolerates a String association name" do
+      config = Admin::Base::Resource::IndexConfig.new
+      config.includes("company")
+      assert_equal [ "company" ], config.includes_list
+    end
+
+    test "the DSL exposes includes: on a resource's index_config" do
+      assert_equal [ :company, :owner ], Admin::Resources::IndexIncludesWidgetResource.index_config.includes_list
+    end
+
+    test "the controller applies includes: to a scope that responds to includes" do
+      IndexIncludesFixtures::Widget::RELATION.includes_calls.clear
+
+      get "/internal/admin_suite/ops/index_includes_widgets"
+      assert_response :success
+
+      assert_equal [ [ :company, :owner ] ], IndexIncludesFixtures::Widget::RELATION.includes_calls
+    end
+
+    test "a scope whose includes raises for a bad association degrades instead of 500ing" do
+      logged = []
+      Rails.logger.stub(:warn, ->(msg) { logged << msg }) do
+        get "/internal/admin_suite/ops/index_includes_bad_widgets"
+      end
+
+      assert_response :success
+      assert_includes response.body, "Bad Widget"
+      # The rescue in `apply_index_includes` logs the failure -- pinning
+      # that here so the "skipped silently" test below (which asserts NO
+      # warn fires) is actually distinguishing two different code paths,
+      # not just two tests that both happen to pass.
+      assert_equal 1, logged.size
+      assert_includes logged.first, "nonexistent_association"
+    end
+
+    test "a scope that does not respond to includes is skipped silently, not raised" do
+      refute IndexIncludesFixtures::NoIncludesWidget.all.respond_to?(:includes)
+
+      logged = []
+      Rails.logger.stub(:warn, ->(msg) { logged << msg }) do
+        get "/internal/admin_suite/ops/index_includes_no_includes_widgets"
+      end
+
+      assert_response :success
+      assert_includes response.body, "Plain Widget"
+      # `apply_index_includes`'s `respond_to?(:includes)` guard exists so a
+      # scope that can never support includes doesn't spam a warning on
+      # every request. Deleting that guard would still return a 200 here
+      # (the catch-all rescue produces an identical response), so the
+      # response alone doesn't prove the guard does anything -- this
+      # asserts its actual purpose: no warn fires on this path. Contrast
+      # with the bad-association test above, where one does.
+      assert_empty logged
+    end
+  end
+end

data/test/lib/legacy_renderer_deprecation_test.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+module AdminSuite
+  class LegacyRendererDeprecationTest < ActionView::TestCase
+    include ::ERB::Util
+    include AdminSuite::BaseHelper
+
+    Prompt = Struct.new(:prompt_template)
+
+    setup { AdminSuite::Renderers::LegacyGleania.reset_deprecation_notices! }
+
+    test "the legacy prompt renderer still renders its template" do
+      html = render_custom_section(Prompt.new("Hello {{name}}"), :prompt_template_preview)
+      assert_includes html, "Hello"
+      assert_includes html, "name"
+    end
+
+    test "using a legacy renderer logs a deprecation once per key" do
+      logged = []
+      AdminSuite::Renderers::LegacyGleania.stub(:warn_once_sink, ->(msg) { logged << msg }) do
+        2.times { render_custom_section(Prompt.new("x"), :prompt_template_preview) }
+      end
+      assert_equal 1, logged.size
+      assert_includes logged.first, "deprecated"
+      # Deliberately a hardcoded literal, not read off
+      # DEPRECATION_MESSAGE_FORMAT: reading the version out of the constant
+      # under test and asserting the message contains it is true by
+      # construction (format() only substitutes %<key>s, never the version
+      # digits), so it can never fail on a wrong retarget -- exactly the
+      # property this test exists to catch. If the removal target changes
+      # again, this literal must be updated by hand; that's the point.
+      assert_includes logged.first, "0.6.0"
+    end
+
+    test "the gem no longer includes the host CustomRenderersHelper constant" do
+      source = AdminSuite::Engine.root.join("app/helpers/admin_suite/base_helper.rb").read
+      refute_includes source, "Internal::Developer::CustomRenderersHelper"
+    end
+  end
+end

data/test/lib/renderer_test.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# Reopened (never redefined) so RendererTest can define/remove scratch
+# `Admin::Renderers::<Key>Renderer` probe classes per test, for Finding 2's
+# host-class-vs-gem-default precedence tests below.
+module Admin
+  module Renderers
+  end
+end
+
+module AdminSuite
+  class RendererTest < ActionView::TestCase
+    # See ShowValueFormatterTest for why this is needed: BaseHelper's
+    # primitives (via render_json_block / render_text_block) call bare `h`,
+    # which ActionView::TestCase::Behavior does not provide on its own.
+    include ::ERB::Util
+    include AdminSuite::BaseHelper
+
+    Record = Struct.new(:id, :payload)
+
+    class GreetingRenderer < AdminSuite::Renderer
+      def render
+        content_tag(:p, "Hello #{record.id}")
+      end
+    end
+
+    class PrimitivesRenderer < AdminSuite::Renderer
+      def render
+        safe_join([
+          key_value_list([ [ "Status", "active" ] ]),
+          data_table([ { name: "a", count: 1 } ], columns: %i[name count]),
+          badge("live", color: :green),
+          empty_state("nothing here")
+        ])
+      end
+    end
+
+    setup { AdminSuite::RendererRegistry.register(:greeting, GreetingRenderer) }
+    teardown { AdminSuite::RendererRegistry.unregister(:greeting) }
+
+    test "a renderer subclass receives the record and renders" do
+      assert_includes GreetingRenderer.new(Record.new(7), self).render, "Hello 7"
+    end
+
+    test "the base class requires #render" do
+      assert_raises(NotImplementedError) { AdminSuite::Renderer.new(Record.new(1), self).render }
+    end
+
+    test "registry lookup returns the registered class and raises for unknown keys" do
+      assert_equal GreetingRenderer, AdminSuite::RendererRegistry.lookup(:greeting)
+      assert_nil AdminSuite::RendererRegistry.lookup(:nope)
+    end
+
+    test "registered lists every registered key" do
+      assert_includes AdminSuite::RendererRegistry.registered, :greeting
+    end
+
+    test "primitives render key-value pairs, tables, badges and empty states" do
+      html = PrimitivesRenderer.new(Record.new(1), self).render
+      assert_includes html, "Status"
+      assert_includes html, "active"
+      # data_table humanizes column names for the header (see Renderer#data_table),
+      # so ":count" renders as "Count", not "count".
+      assert_includes html, "Count"
+      assert_includes html, "live"
+      assert_includes html, "nothing here"
+    end
+
+    test "data_table renders its empty message when rows are blank" do
+      html = AdminSuite::Renderer.new(Record.new(1), self).send(:data_table, [], columns: %i[a], empty: "no rows")
+      assert_includes html, "no rows"
+    end
+
+    test "render_custom_section resolves a registered renderer class" do
+      assert_includes render_custom_section(Record.new(9), :greeting), "Hello 9"
+    end
+
+    # Lookup-precedence regression guard. Tasks 4 and 5 both insert new
+    # branches into render_custom_section (built-ins, then the deprecated
+    # Gleania four) between the registry lookup and the "Unknown" fallback —
+    # this pins the two boundaries already in place today so neither task can
+    # silently invert them.
+    test "a legacy custom_renderers proc wins over a registered renderer class" do
+      key = :precedence_probe
+      AdminSuite::RendererRegistry.register(key, GreetingRenderer)
+      saved = AdminSuite.config.custom_renderers[key]
+      AdminSuite.config.custom_renderers[key] = ->(record, _view) { "legacy-proc-#{record.id}" }
+
+      html = render_custom_section(Record.new(5), key)
+
+      assert_includes html, "legacy-proc-5"
+      refute_includes html, "Hello 5"
+    ensure
+      AdminSuite::RendererRegistry.unregister(key)
+      AdminSuite.config.custom_renderers.delete(key)
+      AdminSuite.config.custom_renderers[key] = saved if saved
+    end
+
+    # Finding 4 of the whole-branch review: `config.custom_renderers` procs
+    # were deprecated on paper only (CHANGELOG, 0.4.0) with no runtime
+    # signal -- unlike the four legacy Gleania renderers, which warn once
+    # per key. trust_growth has 23 of these procs and needs a way to notice
+    # during the migration window.
+    test "using a legacy custom_renderers proc logs a deprecation once per key" do
+      key = :legacy_proc_warning_probe
+      AdminSuite::LegacyCustomRendererProcs.reset_deprecation_notices!
+      AdminSuite.config.custom_renderers[key] = ->(record, _view) { "legacy-proc-#{record.id}" }
+
+      logged = []
+      AdminSuite::LegacyCustomRendererProcs.stub(:warn_once_sink, ->(msg) { logged << msg }) do
+        2.times { render_custom_section(Record.new(5), key) }
+      end
+
+      assert_equal 1, logged.size
+      assert_includes logged.first, key.to_s
+      assert_includes logged.first, "deprecated"
+      # Deliberately a hardcoded literal, not read off
+      # DEPRECATION_MESSAGE_FORMAT: reading the version out of the constant
+      # under test and asserting the message contains it is true by
+      # construction (format() only substitutes %<key>s, never the version
+      # digits), so it can never fail on a wrong retarget -- exactly the
+      # property this test exists to catch. If the removal target changes
+      # again, this literal must be updated by hand; that's the point.
+      assert_includes logged.first, "0.6.0"
+    ensure
+      AdminSuite.config.custom_renderers.delete(key)
+    end
+
+    # Finding 2 of the whole-branch review: render_custom_section used to
+    # resolve `RendererRegistry.lookup(key) || host_renderer_class(key)`,
+    # but the gem's own built-ins and the deprecated Gleania four were
+    # registered into that same `lookup` store at require time -- so a host
+    # that followed the deprecation advice ("Move it to app/admin/renderers
+    # in your app") and defined its own `Admin::Renderers::<Key>Renderer`
+    # was silently shadowed, and the deprecation warning never stopped.
+    # Built-ins/deprecated-four now live in a separate `register_default`
+    # store, checked only *after* a host renderer class.
+    test "a host renderer class beats a gem default registered under the same key" do
+      key = :host_beats_default_probe
+      AdminSuite::RendererRegistry.register_default(key, GreetingRenderer)
+      Admin::Renderers.const_set(:HostBeatsDefaultProbeRenderer, Class.new(AdminSuite::Renderer) do
+        def render
+          "host-class-#{record.id}"
+        end
+      end)
+
+      html = render_custom_section(Record.new(7), key)
+
+      assert_includes html, "host-class-7"
+      refute_includes html, "Hello 7"
+    ensure
+      # `register_default` seeds AdminSuite's *permanent* default store (the
+      # same one the built-ins live in), so this probe key must be removed
+      # via `unregister_default` -- unlike `unregister`, which only ever
+      # touches the explicit store and would silently leave this key behind
+      # for every test that runs afterward.
+      AdminSuite::RendererRegistry.unregister_default(key)
+      if Admin::Renderers.const_defined?(:HostBeatsDefaultProbeRenderer, false)
+        Admin::Renderers.send(:remove_const, :HostBeatsDefaultProbeRenderer)
+      end
+    end
+
+    test "an explicit registration still beats a host renderer class" do
+      key = :explicit_beats_host_probe
+      AdminSuite::RendererRegistry.register(key, GreetingRenderer)
+      Admin::Renderers.const_set(:ExplicitBeatsHostProbeRenderer, Class.new(AdminSuite::Renderer) do
+        def render
+          "host-class-#{record.id}"
+        end
+      end)
+
+      html = render_custom_section(Record.new(8), key)
+
+      assert_includes html, "Hello 8"
+      refute_includes html, "host-class-8"
+    ensure
+      AdminSuite::RendererRegistry.unregister(key)
+      if Admin::Renderers.const_defined?(:ExplicitBeatsHostProbeRenderer, false)
+        Admin::Renderers.send(:remove_const, :ExplicitBeatsHostProbeRenderer)
+      end
+    end
+
+    test "a registered renderer class wins over the built-in case branches" do
+      # :json_preview has a legacy case branch; a registered class must take it over.
+      #
+      # Task 4 registers :json_preview as a permanent alias to JsonRenderer,
+      # but via `register_default` (the gem-defaults store), not `register`
+      # (the explicit store). `lookup` below only ever reads the explicit
+      # store, so `previous` is nil here -- there is no explicit registration
+      # to save or restore, and the `ensure` branch's plain `unregister` is
+      # a safe no-op that cannot touch the permanent default alias (which
+      # only `unregister_default` could remove). This test still needs the
+      # save/restore shape below in case some future test registers
+      # :json_preview explicitly and forgets to clean up after itself.
+      previous = AdminSuite::RendererRegistry.lookup(:json_preview)
+      AdminSuite::RendererRegistry.register(:json_preview, GreetingRenderer)
+      assert_includes render_custom_section(Record.new(6), :json_preview), "Hello 6"
+    ensure
+      if previous
+        AdminSuite::RendererRegistry.register(:json_preview, previous)
+      else
+        AdminSuite::RendererRegistry.unregister(:json_preview)
+      end
+    end
+
+    # json_block/code_block/badge each delegate to a BaseHelper primitive whose
+    # real signature differs from the brief's illustrative sketch
+    # (render_json_block takes no `title:`; render_label_badge takes `color:`
+    # as a keyword, not positional) — these primitives were adapted to match,
+    # per the task's explicit instruction. Covered directly since the brief's
+    # own PrimitivesRenderer test never exercises json_block or code_block.
+    test "json_block renders pretty-printed JSON, with an optional title heading" do
+      renderer = AdminSuite::Renderer.new(Record.new(1), self)
+      html = renderer.send(:json_block, { a: 1 })
+      assert_includes html, "language-json"
+      assert_includes html, "&quot;a&quot;"
+
+      titled = renderer.send(:json_block, { a: 1 }, title: "Payload")
+      assert_includes titled, "Payload"
+      assert_includes titled, "language-json"
+    end
+
+    test "code_block renders a syntax-highlighted text block" do
+      html = AdminSuite::Renderer.new(Record.new(1), self).send(:code_block, "SELECT 1", language: :sql)
+      assert_includes html, "SELECT 1"
+      assert_includes html, "language-sql"
+    end
+
+    test "badge renders the label with its color class, passed as a keyword" do
+      html = AdminSuite::Renderer.new(Record.new(1), self).send(:badge, "live", color: :green)
+      assert_includes html, "live"
+      assert_includes html, "bg-green-100"
+    end
+  end
+end