admin_suite 0.4.0 → 0.5.0

data/app/controllers/admin_suite/resources_controller.rb

@@ -7,7 +7,15 @@ module AdminSuite
 
     before_action :require_resource_config!
     before_action :enforce_read_only!, only: %i[new create edit update destroy toggle]
-    before_action :set_resource, if: -> { params[:id].present? && !%w[index new create].include?(action_name) }
+    # `search` is excluded even though it can receive an `:id`-shaped query
+    # param: unlike show/edit/update/destroy, a record has no business
+    # participating in this action at all. Without this exclusion, a stray
+    # `?id=` would (a) hand an attacker-chosen record to `config.authorize`'s
+    # `record:` on an action that should never carry one, and (b) let a
+    # denied actor distinguish 404 (bad id) from 403 (denied) -- an
+    # existence oracle over `find_friendly_resource!`'s slug/uuid/token
+    # lookups, on a resource they have no read access to.
+    before_action :set_resource, if: -> { params[:id].present? && !%w[index new create search].include?(action_name) }
     before_action :authorize_admin_suite!
 
     helper_method :resource_config, :resource_class, :resource, :collection, :current_portal, :resource_name
@@ -23,6 +31,26 @@ module AdminSuite
     def show
     end
 
+    # GET /:portal/:resource_name/search?q=term
+    #
+    # Feeds `searchable_select_controller.js`'s `fetchOptions`, which expects
+    # a bare JSON array (not `{results: [...]}`) of objects each carrying
+    # `id`/`value` and `name`/`title`/`label`. Matches that contract exactly
+    # -- the JS needs no changes.
+    #
+    # Reuses `FilterBuilder.search_predicate`, the same ILIKE-over-
+    # `searchable_fields` logic the index's own search box uses, so this can
+    # only ever search the resource's declared `searchable` whitelist --
+    # never an arbitrary column supplied via `q`. `require_resource_config!`
+    # and `authorize_admin_suite!` (both already-registered before_actions,
+    # the latter driven by `AUTHORIZATION_VERBS["search"] = :read` below)
+    # gate this exactly like every other action on this controller: unknown
+    # resource names 404 before either runs, and a denying `config.authorize`
+    # 403s before any query executes.
+    def search
+      render json: search_results.first(SEARCH_RESULT_LIMIT).map { |record| search_result_json(record) }
+    end
+
     # GET /:portal/:resource_name/new
     def new
       @resource = resource_class.new
@@ -129,15 +157,49 @@ module AdminSuite
 
     private
 
+    # Hard cap on searchable_select results, regardless of table size or how
+    # permissive the resource's `searchable` list is.
+    SEARCH_RESULT_LIMIT = 25
+
     # Controller action -> authorization verb.
     AUTHORIZATION_VERBS = {
-      "index" => :read, "show" => :read,
+      "index" => :read, "show" => :read, "search" => :read,
       "new" => :create, "create" => :create,
       "edit" => :update, "update" => :update, "toggle" => :update,
       "destroy" => :destroy,
       "execute_action" => :execute, "bulk_action" => :execute
     }.freeze
 
+    # Filters the resource's own records by `params[:q]` via the shared
+    # `FilterBuilder` predicate. A nil predicate (blank `q`, no index config,
+    # no declared `searchable` fields, or `q` shorter than
+    # `FilterBuilder::MIN_SEARCH_LENGTH`) means no results at all here --
+    # deliberately *not* the "fall back to unfiltered scope" behavior
+    # `FilterBuilder#apply_search` uses for the index filter box. A raw JSON
+    # endpoint must never hand back arbitrary rows just because the query
+    # was empty or the resource isn't configured for search.
+    #
+    # @return [Enumerable]
+    def search_results
+      predicate = Admin::Base::FilterBuilder.search_predicate(resource_config&.index_config, params[:q])
+      return [] unless predicate
+
+      conditions, search_term = predicate
+      resource_class.where(conditions, search: search_term)
+    end
+
+    # @param record [Object]
+    # @return [Hash]
+    def search_result_json(record)
+      { id: record.id, name: search_result_label(record) }
+    end
+
+    def search_result_label(record)
+      return record.name if record.respond_to?(:name) && record.name.present?
+      return record.title if record.respond_to?(:title) && record.title.present?
+      record.to_s
+    end
+
     # Enforces the host's `config.authorize` hook. Nil hook = allowed
     # (authentication remains the gate). Falsy return = 403.
     #
@@ -222,12 +284,75 @@ module AdminSuite
     def filtered_collection
       return resource_class.all unless resource_config&.index_config
 
-      Admin::Base::FilterBuilder.new(resource_config, params).apply(resource_class.all)
+      scope = Admin::Base::FilterBuilder.new(resource_config, params).apply(resource_class.all)
+      apply_index_includes(scope)
+    end
+
+    # Applies the index's `includes:` DSL option (see
+    # `Admin::Base::Resource::IndexConfig#includes`) to the filtered scope.
+    # Only when the scope actually responds to `#includes` -- the PORO
+    # `Relation` test doubles used throughout this gem's own test suite
+    # don't, and a host's own non-AR scope object may not either -- so this
+    # skips silently rather than raising. `.includes` itself can raise for
+    # a bad/renamed/typo'd association name once the scope is a real AR
+    # relation; that must degrade the index to an unoptimized-but-working
+    # page, not 500 it, so it's logged and swallowed the same way the
+    # chart panel's bad `type:`/`data` values are (see
+    # `app/views/admin_suite/panels/_chart.html.erb`).
+    #
+    # @param scope [Object] the filtered collection
+    # @return [Object] the scope, with associations eager-loaded when possible
+    def apply_index_includes(scope)
+      includes_list = resource_config.index_config.includes_list
+      return scope if includes_list.blank?
+      return scope unless scope.respond_to?(:includes)
+
+      scope.includes(*includes_list)
+    rescue StandardError => e
+      Rails.logger&.warn(
+        "AdminSuite: #{resource_class}'s index `includes(#{includes_list.inspect})` raised " \
+        "#{e.class}: #{e.message}; rendering the index without eager loading."
+      )
+      scope
     end
 
+    # Max a request can push the index's per-page count to, regardless of
+    # what `per_page` the query string carries -- `per_page` is user-supplied
+    # (a plain query param), so this exists to stop `?per_page=999999` from
+    # turning the index into an unbounded query.
+    MAX_PER_PAGE = 100
+
     def paginate_collection(scope)
-      per_page = resource_config&.index_config&.per_page || 25
-      pagy(scope, items: per_page)
+      dsl_per_page = resource_config&.index_config&.per_page || 25
+      # Pagy 9.x's vars key is `limit:`, not `items:` -- the pre-existing
+      # `items:` call silently did nothing (pagy fell through to its own
+      # `DEFAULT[:limit]` of 20), so every resource's `paginate(n)` DSL
+      # value was already being ignored before this task. Fixed here since
+      # this task's clamp is meaningless without it.
+      pagy(scope, limit: clamped_per_page(dsl_per_page))
+    end
+
+    # Resolves the effective per-page count for the index from the
+    # `per_page` query param, clamped to `MAX_PER_PAGE` and falling back to
+    # the DSL's `paginate(n)` value (`dsl_per_page`) whenever the param is
+    # absent or not a usable positive integer.
+    #
+    # `per_page` is the most directly attacker-influenceable input this
+    # phase adds, so every shape it can arrive in is handled without
+    # raising: missing (nil), non-numeric ("abc"), zero, negative, an
+    # array (`per_page[]=1`, which Rails hands back as a plain Array, not
+    # a String -- `Integer(Array)` raises `TypeError`), and absurdly large
+    # (clamped, never passed through to the query).
+    #
+    # @param dsl_per_page [Integer] the resource's `paginate(n)` value
+    # @return [Integer]
+    def clamped_per_page(dsl_per_page)
+      value = Integer(params[:per_page])
+      return dsl_per_page if value <= 0
+
+      value.clamp(..MAX_PER_PAGE)
+    rescue ArgumentError, TypeError
+      dsl_per_page
     end
 
     def calculate_stats(scope)

data/app/helpers/admin_suite/base_helper.rb

@@ -141,7 +141,43 @@ module AdminSuite
       elsif column.content.is_a?(Proc)
         column.content.call(record)
       else
-        record.public_send(column.name) rescue "—"
+        value = record.public_send(column.name) rescue "—"
+        if active_record_base?(value)
+          render_association_value(value)
+        else
+          # `rescue "—"` above only fires on an exception; a genuinely nil
+          # attribute reaches here untouched and used to render as an empty
+          # cell. Every other surface in the gem (`format_table_cell`,
+          # `render_association_value`'s own rescues) already shows "—" for
+          # nil, so this closes the one place that didn't -- including a
+          # nil `belongs_to` value, which Task 3 deliberately left alone
+          # because this task owns it.
+          value.nil? ? "—" : value
+        end
+      end
+    end
+
+    # Maps a column's `align:` DSL option to a literal Tailwind class.
+    #
+    # `align` is resource-author-supplied, not end-user input, but it's
+    # still an arbitrary value handed to us from outside this method, so
+    # this follows the same precedent as the stat panel's `color` mapping
+    # (`app/views/admin_suite/panels/_stat.html.erb`) and the dashboard
+    # row's `span` clamp (`panels_helper.rb#render_panel`): a closed
+    # `case`/`else` over known values, never `"text-#{align}"` string
+    # interpolation. Dynamic Tailwind class names are invisible to the
+    # content scanner (unstyled in production) even when they happen to be
+    # spelled correctly, and an unrecognized or malformed `align:` here
+    # must degrade to no alignment class rather than emit a broken one.
+    #
+    # @param align [Symbol, String, nil]
+    # @return [String]
+    def column_align_class(align)
+      case align.respond_to?(:to_sym) ? align.to_sym : align
+      when :right then "text-right"
+      when :center then "text-center"
+      when :left then "text-left"
+      else ""
       end
     end
 
@@ -310,9 +346,7 @@ module AdminSuite
     def auto_admin_suite_path_for(item)
       return nil unless active_record_base?(item)
 
-      ensure_admin_resources_loaded_for!(item.class)
-
-      resource = Admin::Base::Resource.registered_resources.find { |r| r.model_class == item.class }
+      resource = admin_suite_resource_for(item.class)
       return nil unless resource&.portal_name && resource.respond_to?(:resource_name_plural)
 
       resource_path(portal: resource.portal_name, resource_name: resource.resource_name_plural, id: item.to_param)
@@ -320,6 +354,25 @@ module AdminSuite
       nil
     end
 
+    # Memoized per-request (the helper is mixed into a view instance created
+    # fresh per request) resource-class lookup. Before this, every rendered
+    # association value re-ran `ensure_admin_resources_loaded_for!`'s
+    # `registered_resources.any?` scan *plus* a `registered_resources.find`
+    # scan -- both full linear scans of the registry (28-38 resources in the
+    # real hosts) -- once per rendered row. Keying the memo on the model
+    # class (not the item's identity) means a page with N rows of the same
+    # class costs one lookup, not N.
+    #
+    # @param model_class [Class]
+    # @return [Class, nil] the registered `Admin::Base::Resource` subclass, if any
+    def admin_suite_resource_for(model_class)
+      @admin_suite_resource_for ||= {}
+      return @admin_suite_resource_for[model_class] if @admin_suite_resource_for.key?(model_class)
+
+      ensure_admin_resources_loaded_for!(model_class)
+      @admin_suite_resource_for[model_class] = Admin::Base::Resource.registered_resources.find { |r| r.model_class == model_class }
+    end
+
     def ensure_admin_resources_loaded_for!(model_class)
       already_loaded = Admin::Base::Resource.registered_resources.any? { |r| r.model_class == model_class }
       return if already_loaded
@@ -365,7 +418,11 @@ module AdminSuite
           elsif section.association.present?
             render_association_section(resource, section)
           elsif section.fields.any?
-            position == :sidebar ? render_sidebar_fields(resource, section.fields) : render_main_fields(resource, section.fields)
+            if position == :sidebar
+              render_sidebar_fields(resource, section.fields, hide_blank: section.hide_blank)
+            else
+              render_main_fields(resource, section.fields, hide_blank: section.hide_blank)
+            end
           else
             content_tag(:p, "No content", class: "text-slate-400 italic text-sm")
           end
@@ -373,11 +430,13 @@ module AdminSuite
       end
     end
 
-    def render_sidebar_fields(resource, fields)
+    def render_sidebar_fields(resource, fields, hide_blank: false)
       content_tag(:div, class: "space-y-3") do
         fields.each do |field_name|
           value = resource.public_send(field_name) rescue nil
-          if value.is_a?(ActiveStorage::Attached::One) || value.is_a?(ActiveStorage::Attached::Many)
+          next if hide_blank && show_value_blank?(value)
+
+          if attached_file_value?(value)
             concat(render_sidebar_attachment(value))
           else
             concat(content_tag(:div, class: "flex justify-between items-start gap-2") do
@@ -425,9 +484,18 @@ module AdminSuite
       end
     end
 
-    def render_main_fields(resource, fields)
+    def render_main_fields(resource, fields, hide_blank: false)
       content_tag(:dl, class: "space-y-6") do
         fields.each do |field_name|
+          # Only re-read the value (and only when `hide_blank` is actually
+          # on) so a plain `field :foo` row with no `hide_blank:` costs
+          # exactly what it cost before this option existed --
+          # `format_show_value` re-reads the value itself below regardless.
+          if hide_blank
+            value = resource.public_send(field_name) rescue nil
+            next if show_value_blank?(value)
+          end
+
           concat(content_tag(:div) do
             concat(content_tag(:dt, field_name.to_s.humanize, class: "text-sm font-medium text-slate-500 mb-2"))
             concat(content_tag(:dd, class: "text-sm text-slate-900") { format_show_value(resource, field_name) })
@@ -436,6 +504,38 @@ module AdminSuite
       end
     end
 
+    # Whether `resource.public_send(field_name)` should be omitted entirely
+    # from a `hide_blank: true` show panel.
+    #
+    # Deliberately not `value.blank?`: `false.blank?` is `true` in Ruby, and
+    # `false` renders as a real, meaningful grey "No" toggle icon today (see
+    # `ShowFormatterRegistry`'s `FalseClass` handler) -- hiding it would
+    # erase a real signal, not absence of one. Same reasoning for `0` and
+    # `0.0`: neither responds to `:empty?`, so both are kept. A
+    # whitespace-only string (`"   "`) is also kept -- `String#empty?`
+    # checks length, not content, and this option only claims to hide
+    # values with *zero* content, not "content a human would consider
+    # meaningless."
+    #
+    # @param value [Object]
+    # @return [Boolean]
+    def show_value_blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+    private :show_value_blank?
+
+    # True for an `ActiveStorage::Attached::One`/`::Many` proxy -- guarded
+    # with `defined?` because the host (and this gem's own dummy test app)
+    # may not load ActiveStorage at all.
+    #
+    # @param value [Object]
+    # @return [Boolean]
+    def attached_file_value?(value)
+      (defined?(ActiveStorage::Attached::One) && value.is_a?(ActiveStorage::Attached::One)) ||
+        (defined?(ActiveStorage::Attached::Many) && value.is_a?(ActiveStorage::Attached::Many))
+    end
+    private :attached_file_value?
+
     # ---- association rendering ----
     def render_association_section(resource, section)
       associated = resource.public_send(section.association) rescue nil
@@ -611,17 +711,56 @@ module AdminSuite
       when true, false then value ? "Yes" : "No"
       when Time, DateTime then value.strftime("%b %d, %H:%M")
       when Date then value.strftime("%b %d, %Y")
+      # Aligns with `format_show_value`'s Integer/Float/BigDecimal handling
+      # (see `AdminSuite::UI::ShowFormatterRegistry`) -- table cells used to
+      # render large numbers with no delimiter at all (via the `else`
+      # branch's plain `to_s`), inconsistent with the same value shown on
+      # the record's own show page.
+      when Integer, Float then number_with_delimiter(value)
+      # `.to_f` avoids number_with_delimiter rendering exponential notation
+      # for BigDecimal input, matching the show-value formatter's tradeoff.
+      when BigDecimal then number_with_delimiter(value.to_f)
       else
         # A `when ActiveRecord::Base` clause would evaluate that constant
         # reference unconditionally (crashing in a host without ActiveRecord
         # loaded), so this branch is checked explicitly via the predicate
         # instead of folded into the `case`.
-        return item_display_title(value) if active_record_base?(value)
+        return render_association_value(value) if active_record_base?(value)
 
         value.to_s.truncate(50)
       end
     end
 
+    # Renders a `belongs_to`-shaped association value (typically reached via
+    # `render_column_value`'s fallback branch or `format_table_cell`'s AR
+    # branch) as its display title, wrapped in a link to the record's own
+    # admin page when one resolves -- never the bare `#<Company:0x...>` that
+    # ERB's implicit `to_s` would otherwise produce for an AR object, and
+    # never the indigo-styled-but-unlinked plain text `format_table_cell`
+    # used to render on its own.
+    #
+    # `item_display_title` can raise on a host record whose `name`/`title`
+    # method blows up, and `auto_admin_suite_path_for` already swallows its
+    # own errors (unpersisted records, no registered resource, etc.) -- but
+    # this wraps the whole thing anyway so one bad row degrades to a plain
+    # dash instead of 500ing the entire index or show page.
+    #
+    # @param value [ActiveRecord::Base]
+    # @return [String, ActiveSupport::SafeBuffer]
+    def render_association_value(value)
+      title = begin
+        item_display_title(value).to_s
+      rescue StandardError
+        "—"
+      end
+
+      path = auto_admin_suite_path_for(value)
+      path ? link_to(title, path, class: "text-indigo-600 hover:underline") : title
+    rescue StandardError
+      "—"
+    end
+    private :render_association_value
+
     def item_display_title(item)
       return item.name if item.respond_to?(:name) && item.name.present?
       return item.title if item.respond_to?(:title) && item.title.present?
@@ -729,10 +868,48 @@ module AdminSuite
       end
     end
 
+    # Resolves the default search URL for a `searchable_select` field
+    # declared with `resource:` (e.g. `field :company_id,
+    # type: :searchable_select, resource: :companies`), so it can reach the
+    # gem's own search endpoint (`ResourcesController#search`) without the
+    # host wiring up a `collection:` URL by hand. A String `collection:`
+    # option always takes precedence over this -- see `render_searchable_select`.
+    #
+    # Looks up the resource by its plural (or singular) resource name among
+    # `Admin::Base::Resource.registered_resources`; returns nil (never raises)
+    # when the key is blank, unregistered, or has no `portal_name` to route
+    # through, so a typo'd `resource:` degrades to "no remote search" rather
+    # than a 500 on the very page meant to render a form.
+    #
+    # @param resource_key [Symbol, String, nil]
+    # @return [String, nil]
+    def admin_suite_search_url_for(resource_key)
+      return nil if resource_key.blank?
+
+      AdminSuite::DefinitionLoader.load!(:resources)
+      key = resource_key.to_s
+      target = Admin::Base::Resource.registered_resources.find do |r|
+        r.resource_name_plural == key || r.resource_name == key
+      end
+      return nil unless target&.portal_name
+
+      search_resources_path(portal: target.portal_name, resource_name: target.resource_name_plural)
+    rescue StandardError => e
+      Rails.logger&.warn(
+        "AdminSuite: resolving the search URL for `resource: #{resource_key.inspect}` raised " \
+        "#{e.class}: #{e.message}; rendering the field with no remote search."
+      )
+      nil
+    end
+
     def render_searchable_select(_f, field, resource)
       param_key = resource.class.model_name.param_key
       current_value = resource.public_send(field.name)
       collection = field.collection.is_a?(Proc) ? field.collection.call : field.collection
+      # A String `collection:` is an explicit search-URL override and always
+      # wins (unchanged host behavior); otherwise fall back to the field's
+      # `resource:` option resolved via `admin_suite_search_url_for`.
+      search_url = collection.is_a?(String) ? collection : admin_suite_search_url_for(field.resource).to_s
 
       options_json = if collection.is_a?(Array)
         collection.map { |opt| opt.is_a?(Array) ? { value: opt[1], label: opt[0] } : { value: opt, label: opt.to_s.humanize } }.to_json
@@ -762,7 +939,7 @@ module AdminSuite
           controller: "admin-suite--searchable-select",
           "admin-suite--searchable-select-options-value": options_json,
           "admin-suite--searchable-select-creatable-value": field.create_url.present?,
-          "admin-suite--searchable-select-search-url-value": collection.is_a?(String) ? collection : "",
+          "admin-suite--searchable-select-search-url-value": search_url,
           "admin-suite--searchable-select-create-url-value": field.create_url.to_s
         },
         class: "relative") do

data/app/javascript/admin_suite_application.js

@@ -42,3 +42,6 @@ application.register("admin-suite--flash", FlashController)
 
 import DependentSearchableSelectController from "controllers/admin_suite/dependent_searchable_select_controller"
 application.register("admin-suite--dependent-searchable-select", DependentSearchableSelectController)
+
+import ChartController from "controllers/admin_suite/chart_controller"
+application.register("admin-suite--chart", ChartController)

data/app/javascript/controllers/admin_suite/chart_controller.js

@@ -0,0 +1,173 @@
+import { Controller } from "@hotwired/stimulus"
+
+/**
+ * Chart Controller (Admin Suite)
+ *
+ * Upgrades a server-rendered CSS bar chart into a real Chart.js canvas.
+ * Chart.js is loaded from the engine's vendored asset (see app/assets/vendor)
+ * only on pages that render a chart panel with data.
+ *
+ * The server-rendered bar markup (this.element's existing children) is the
+ * no-JS degraded state. It stays on the page and visible until Chart.js is
+ * confirmed available and a canvas has actually been drawn — if Chart.js
+ * never loads, the bars are simply never hidden.
+ */
+
+// Bounded retry: ~50 attempts at 100ms each (~5s) before giving up. Guards
+// against an unbounded poll if the Chart.js asset fails to load (e.g. blocked
+// by a CSP, 404, or a page that never actually included it).
+const MAX_INIT_ATTEMPTS = 50
+const INIT_RETRY_DELAY_MS = 100
+
+const COLOR_HEX = {
+  amber: "#f59e0b",
+  green: "#22c55e",
+  red: "#ef4444",
+  cyan: "#06b6d4",
+  violet: "#8b5cf6",
+  indigo: "#6366f1",
+  slate: "#64748b",
+}
+
+const DOUGHNUT_PALETTE = [
+  "#6366f1", "#f59e0b", "#22c55e", "#ef4444",
+  "#06b6d4", "#8b5cf6", "#64748b", "#ec4899",
+]
+
+// Mirrors the ERB partial's own `chart_types` allowlist (see
+// _chart.html.erb). The ERB already normalizes an unknown `type:` down to
+// "bar" before it reaches the DOM, so this is a defensive second check, not
+// the primary one — it only matters if something other than the shipped
+// partial writes the type-value attribute (e.g. a host's `panel_chart`
+// override that skips the ERB's own validation).
+const KNOWN_TYPES = [ "bar", "line", "area", "doughnut" ]
+
+// Fallback height (px) if the server didn't send a height value for some
+// reason. Kept in sync with the ERB partial's own default.
+const DEFAULT_HEIGHT_PX = 192
+
+export default class extends Controller {
+  static values = {
+    series: Array,
+    type: String,
+    color: String,
+    height: Number,
+  }
+
+  connect() {
+    this.initAttempts = 0
+    this.chart = null
+    this.canvasWrapper = null
+    this.initChart()
+  }
+
+  initChart() {
+    if (typeof window.Chart === "undefined") {
+      this.initAttempts += 1
+      if (this.initAttempts >= MAX_INIT_ATTEMPTS) {
+        console.warn(
+          "admin-suite--chart: Chart.js failed to load after " +
+            MAX_INIT_ATTEMPTS +
+            " attempts; leaving the server-rendered bar chart in place."
+        )
+        return
+      }
+
+      this.retryTimeout = setTimeout(() => this.initChart(), INIT_RETRY_DELAY_MS)
+      return
+    }
+
+    // Idempotence guard: never build a second chart on top of an existing one.
+    if (this.chart) return
+
+    const series = this.hasSeriesValue ? this.seriesValue : []
+    if (series.length === 0) return
+
+    let type = this.hasTypeValue && this.typeValue ? this.typeValue : "bar"
+    if (!KNOWN_TYPES.includes(type)) {
+      console.warn(
+        "admin-suite--chart: unknown chart type " + JSON.stringify(type) + "; falling back to \"bar\"."
+      )
+      type = "bar"
+    }
+    const color = COLOR_HEX[this.colorValue] || COLOR_HEX.indigo
+    const height = this.hasHeightValue && this.heightValue > 0 ? this.heightValue : DEFAULT_HEIGHT_PX
+
+    // Chart.js's `responsive: true` / `maintainAspectRatio: false` combo
+    // requires the canvas's parent to have an explicit, non-content-derived
+    // height — otherwise there is no reference box to size against, and the
+    // canvas can render at 0px or grow unboundedly. The wrapper's height
+    // matches the server-rendered bars' height exactly (same data value), so
+    // there's no layout shift when the canvas replaces them.
+    const wrapper = document.createElement("div")
+    wrapper.style.position = "relative"
+    wrapper.style.height = `${height}px`
+    wrapper.style.width = "100%"
+
+    const canvas = document.createElement("canvas")
+    canvas.setAttribute("role", "img")
+    canvas.setAttribute("aria-label", "Chart")
+    wrapper.appendChild(canvas)
+
+    // Attach to the document before constructing the Chart so Chart.js can
+    // actually measure the wrapper's box on first render.
+    this.element.appendChild(wrapper)
+
+    const labels = series.map((row) => row.label)
+    const values = series.map((row) => row.value)
+
+    const chartType = type === "area" ? "line" : type
+    const isDoughnut = chartType === "doughnut"
+
+    const dataset = {
+      data: values,
+      backgroundColor: isDoughnut ? DOUGHNUT_PALETTE : color,
+      borderColor: isDoughnut ? DOUGHNUT_PALETTE : color,
+      fill: type === "area",
+      tension: 0.3,
+    }
+
+    // Only hide the degraded bar markup once Chart.js has actually accepted
+    // the config and rendered — this is what keeps the CSS bars visible as
+    // the degraded state on any earlier failure path.
+    this.chart = new window.Chart(canvas.getContext("2d"), {
+      type: chartType,
+      data: { labels, datasets: [ dataset ] },
+      options: {
+        responsive: true,
+        maintainAspectRatio: false,
+        plugins: { legend: { display: isDoughnut } },
+        scales: isDoughnut ? {} : { y: { beginAtZero: true } },
+      },
+    })
+
+    this.canvasWrapper = wrapper
+
+    // Hide (not remove) the server-rendered bar markup so it can be restored
+    // by simply removing the canvas wrapper if the controller disconnects.
+    Array.from(this.element.children).forEach((child) => {
+      if (child !== wrapper) child.style.display = "none"
+    })
+  }
+
+  disconnect() {
+    if (this.retryTimeout) {
+      clearTimeout(this.retryTimeout)
+      this.retryTimeout = null
+    }
+
+    if (this.chart) {
+      this.chart.destroy()
+      this.chart = null
+    }
+
+    if (this.canvasWrapper) {
+      this.canvasWrapper.remove()
+      this.canvasWrapper = null
+    }
+
+    Array.from(this.element.children).forEach((child) => {
+      child.style.display = ""
+    })
+  }
+}