cafe_car 0.2.1 → 0.3.0

data/app/views/application/_controls.html.haml

@@ -2,6 +2,12 @@
 - show    = options.delete(:show)    { false }
 - edit    = options.delete(:edit)    { true }
 - destroy = options.delete(:destroy) { true }
+-# Custom member actions (Policy#permitted_member_actions) render per record on
+-# the index; the show page lists them in its Actions card instead. Pass
+-# `actions: false` (or an explicit list of names) to override.
+- actions = options.delete(:actions) { action.index? }
+- actions = policy(object).attributes.actions.member if actions == true
+- actions = Array(actions.presence)
 - links   = link(object)
 
 -# TODO: Handle resources with missing routes
@@ -10,3 +16,5 @@
   = c.Link links.show    if show
   = c.Link links.edit    if edit
   = c.Link links.destroy if destroy
+  - actions.each do |name|
+    = c.Link links.action(name)

data/app/views/application/_enum_filter.html.haml

@@ -0,0 +1,5 @@
+-# Equality against one of the enum's declared values (`?status=archived`,
+-# the enum key — QueryBuilder casts it natively; see Filter::FieldInfo#choices).
+= Field do
+  = f.label info.method
+  = f.enum info.method, info.choices, include_blank: t(:any, scope: %i[helpers filter])

data/app/views/application/_filter.html.haml

@@ -0,0 +1,4 @@
+-# Generic fallback: a bare equality filter (`?<attr>=<value>`).
+= Field do
+  = f.label info.method
+  = f.text_field info.method, placeholder: info.placeholder

data/app/views/application/_filters.html.haml

@@ -1,8 +1,17 @@
 = Card :sticky do |card|
   = filter_form_for objects do |f|
     = card.Section do
-      - f.remaining_attributes.each do |attr|
-        = f.field attr
-
+      -# A GET form replaces the query string wholesale on submit, so the
+      -# composing control params (sort, view) ride along as hiddens; the keyword
+      -# search rides as its own visible field, one card with the filters.
+      - { sort: params[:sort], view: params[:view] }.compact_blank.each do |name, value|
+        = hidden_field_tag name, value, id: nil
+      = Field do
+        = f.label :q, t(:search, scope: %i[helpers filter])
+        = f.search_field :q, value: search_term, placeholder: t(:search, scope: %i[helpers filter])
+      - f.remaining_attributes.each do |attribute|
+        = f.filter attribute
+      - f.scopes.each do |scope|
+        = f.scope_toggle scope
     = card.Foot do
-      = f.submit "Filter", commit: false
+      = f.submit t(:submit, scope: %i[helpers filter]), name: nil

data/app/views/application/_has_many_filter.html.haml

@@ -0,0 +1,7 @@
+-# "Has any of these associated records" — submits `?<assoc>.id[]=<id>`, which the
+-# query DSL turns into a where_assoc_exists matching any of the chosen ids.
+= Field do
+  = f.label info.method
+  = f.collection_select info.method, info.collection, :id, -> { present(_1).title },
+    { selected: f.object.value(info.method, :id) },
+    { multiple: true, name: "#{f.field_name(info.method, :id)}[]", **f.searchable_select(info) }

data/app/views/application/_head.html.haml

@@ -14,4 +14,5 @@
 = yield :head
 
 = stylesheet_link_tag "application", "data-turbo-track": "dynamic"
+= theme_stylesheet_tag
 = javascript_importmap_tags

data/app/views/application/_index.html.haml

@@ -1,4 +1,6 @@
-= render "search"
+.IndexToolbar
+  - if view.to_s == "table" && bulk_actions?
+    = render "bulk_actions"
 
 = render(view).presence or render("empty")
 

data/app/views/application/_index_actions.html.haml

@@ -3,7 +3,16 @@
     = icon(:view_grid)
   = Button href: view_url(:table), tip: "Table View" do
     = icon(:table_rows)
-  = Button href: csv_url, tip: "Download CSV" do
-    = icon(:download)
+  = Button href: view_url(:chart), tip: "Chart View" do
+    = icon(:stats_report)
 
-= link(model.build).new(class: ui.Button(:primary).class_name, params: dot_params) { icon(:plus) + _1}
+= Button href: csv_url, tip: "Download CSV" do
+  = icon(:download)
+
+-# Custom collection actions (Policy#permitted_collection_actions — the policy
+-# is the source of truth): one POST button per action, labeled + styled from
+-# the locale (see Controller#collection_action).
+- collection_actions.each do |name|
+  = collection_action name
+
+= link(model.build).new(class: ui.Button(:primary).class_name, params: filter_params) { icon(:plus) + _1}

data/app/views/application/_navigation.html.haml

@@ -1,4 +1,9 @@
 = Navigation tag: :nav do |nav|
+  - if href = navigation.dashboard_href
+    = nav.Link(href:) do
+      = Icon t(:dashboard, scope: "navigation.icon").to_sym
+      Dashboard
+
   = render "navigation_links", nav:
 
   - if try(:authenticated?)

data/app/views/application/_nested_field.html.haml

@@ -1,7 +1,7 @@
 - reflection = field.info.reflection
 - if reflection&.collection?
   - new_object    = reflection.klass.new
-  - nested_opts   = field.form.model.nested_attributes_options[field.method] || {}
+  - nested_opts   = field.form.model.nested_attributes_options[reflection.name] || {}
   - allow_destroy = nested_opts[:allow_destroy]
   - plural        = reflection.klass.model_name.plural
   - item_partial  = partial?("#{plural}/fields") ? "#{plural}/fields" : "fields"

data/app/views/application/_range_filter.html.haml

@@ -0,0 +1,8 @@
+-# Bounded range via the `.min`/`.max` dot-ops (`?price.min=10&price.max=50`).
+-# Dates parse through Chronic on the query side, so a bare `2026-01-01` works.
+- step = :any if info.type.in? %i[decimal float]
+= Field do
+  = f.label info.method, for: "#{info.method}_min"
+  = Group do
+    = f.public_send info.input, info.method, name: f.field_name(info.method, :min), id: "#{info.method}_min", value: f.object.value(info.method, :min), placeholder: t(:min, scope: %i[helpers filter]), step: step
+    = f.public_send info.input, info.method, name: f.field_name(info.method, :max), id: "#{info.method}_max", value: f.object.value(info.method, :max), placeholder: t(:max, scope: %i[helpers filter]), step: step

data/app/views/application/_scope_filter.html.haml

@@ -0,0 +1,5 @@
+-# Toggle for a policy-permitted model scope (`?published=true`).
+= Field do
+  = f.label scope do
+    = f.check_box scope, { name: f.field_name(scope) }, "true", nil
+    = t(scope, scope: [ :helpers, :filter, :scopes, f.model.model_name.i18n_key ], default: scope.to_s.humanize)

data/app/views/application/_string_filter.html.haml

@@ -0,0 +1,4 @@
+-# Substring match — submits the `~` (contains) dot-op, e.g. `?name~=acme`.
+= Field do
+  = f.label info.method
+  = f.text_field "#{info.method}~", id: info.method, placeholder: info.placeholder || t(:contains, scope: %i[helpers filter])

data/app/views/application/_table.html.haml

@@ -1,6 +1,8 @@
-= table_for objects do |t|
-  = t.logo
-  = t.title
-  = t.remaining
-  = t.timestamps
-  = t.controls
+= bulk_form do
+  = table_for objects do |t|
+    = t.select
+    = t.logo
+    = t.title
+    = t.remaining
+    = t.timestamps
+    = t.controls

data/app/views/application/_text_filter.html.haml

@@ -0,0 +1 @@
+= render "string_filter", f:, info:

data/app/views/cafe_car/application/index.html.haml

@@ -1,13 +1,16 @@
 - title = title model_name.human(count: :all)
 - actions = render "index_actions"
 - body = render("index")
+- filterable = policy(model.new).then { _1.attributes.filterable.any? or _1.permitted_scopes.any? }
 
 = Page title:, actions: do |page|
-  -# = page.Aside do
-  -#   = render "filters"
+  - if filterable
+    = page.Aside do
+      = render "filters"
 
   = page.Body do
     = render "alerts"
+    = render "active_filters"
     = body
     = render "debug" if debug?
 

data/app/views/cafe_car/dashboard/_chart.html.haml

@@ -0,0 +1,11 @@
+-# A dashboard chart tile: title + inline SVG, no filter controls. Rendered by the
+-# `chart` helper. The x column is host-supplied but still runs through
+-# ChartBuilder's date-column allowlist, so a bad column can never reach SQL raw.
+- chart = chart_for(objects, column: x.to_s, bucket: by)
+
+.Dashboard-tile.Dashboard-chart
+  %h4.Dashboard-chartTitle= title
+  - if chart.columns.include?(chart.column)
+    = chart
+  - else
+    .center= t("cafe_car.dashboard.no_date_column", default: "No date column to chart.")

data/app/views/cafe_car/dashboard/_metric.html.haml

@@ -0,0 +1,4 @@
+-# A dashboard metric tile: a label over a value. Rendered by the `metric` helper.
+.Dashboard-tile.Metric
+  .Metric-value= value
+  .Metric-label= label

data/config/brakeman.ignore

@@ -1,29 +1,5 @@
 {
   "ignored_warnings": [
-    {
-      "warning_type": "Dangerous Eval",
-      "warning_code": 13,
-      "fingerprint": "9f7c27406a84219ad1d93b07b8c1acd435ad75921861a85a647e32f3d07d1289",
-      "check_name": "Evaluation",
-      "message": "Dynamic string evaluated as code",
-      "file": "lib/cafe_car/auto_resolver.rb",
-      "line": 16,
-      "link": "https://brakemanscanner.org/docs/warning_types/dangerous_eval/",
-      "code": "TOPLEVEL_BINDING.eval(\"class #{mod.name}::#{name} < CafeCar[:ApplicationController]\\n  include CafeCar::Controller\\n  cafe_car\\n  self\\nend\\n\", \"lib/cafe_car/auto_resolver.rb\", 16)",
-      "render_path": null,
-      "location": {
-        "type": "method",
-        "class": "CafeCar::AutoResolver",
-        "method": "define"
-      },
-      "user_input": null,
-      "confidence": "Weak",
-      "cwe_id": [
-        913,
-        95
-      ],
-      "note": ""
-    },
     {
       "warning_type": "Dangerous Eval",
       "warning_code": 13,
@@ -47,30 +23,6 @@
         95
       ],
       "note": ""
-    },
-    {
-      "warning_type": "Dangerous Eval",
-      "warning_code": 13,
-      "fingerprint": "f14f192898bdd59525b84317d91ecbbdc952f71e28dbeca457caf4c11bee0bc7",
-      "check_name": "Evaluation",
-      "message": "Dynamic string evaluated as code",
-      "file": "lib/cafe_car/auto_resolver.rb",
-      "line": 24,
-      "link": "https://brakemanscanner.org/docs/warning_types/dangerous_eval/",
-      "code": "TOPLEVEL_BINDING.eval(\"class #{mod.name}::#{name} < CafeCar[:ApplicationPolicy]\\n  def admin? = Rails.env.development?\\n\\n  def index?   = admin?\\n  def show?    = admin?\\n  def create?  = admin?\\n  def update?  = admin?\\n  def destroy? = admin?\\n\\n  def permitted_attributes\\n    model.info.fields.names.then do |names|\\n      [*model.primary_key].reverse.map(&:to_sym) & names | names\\n    end\\n  end\\n\\n  class Scope < Scope\\n    def resolve = scope.all\\n  end\\n  self\\nend\\n\", \"lib/cafe_car/auto_resolver.rb\", 24)",
-      "render_path": null,
-      "location": {
-        "type": "method",
-        "class": "CafeCar::AutoResolver",
-        "method": "define"
-      },
-      "user_input": null,
-      "confidence": "Weak",
-      "cwe_id": [
-        913,
-        95
-      ],
-      "note": ""
     }
   ],
   "brakeman_version": "8.0.4"

data/config/importmap.rb

@@ -4,6 +4,7 @@ pin "cafe_car"
 pin "@hotwired/turbo-rails", to: "turbo.min.js"
 pin "@rails/actiontext", to: "actiontext.esm.js"
 pin "trix"
+pin "tom-select", to: "tom-select.complete.min.js" # searchable association selects
 
 # pin "@hotwired/stimulus", to: "stimulus.min.js"
 # pin "@hotwired/stimulus-loading", to: "stimulus-loading.js"

data/config/locales/en.yml

@@ -10,12 +10,68 @@ en:
   navigation:
     icon:
       new_session: log-in
+      dashboard: dashboard
       sessions: log-in
       attachments: media-image-list
       blobs: media-image-folder
       passwords: key
       versions: multiple-pages
 
+  helpers:
+    bulk_confirm: "Apply “%{action}” to the selected rows?"
+    # A collection-action button's label — the action plus its reach (how many
+    # records the current filtered view holds), e.g. "Publish all 21". A
+    # count-keyed one/other hash so a host can reword either form; both default
+    # to the same "%{action} %{count}".
+    collection_action:
+      one: "%{action} %{count}"
+      other: "%{action} %{count}"
+    collection_confirm:
+      one: "Apply “%{action}” to %{count} %{models}?"
+      other: "Apply “%{action}” to %{count} %{models}?"
+
+    # The index filter panel (_filters + the _*_filter partials). Per-field
+    # copy nests per model under label/placeholder/hint (see
+    # Filter::FieldInfo#i18n) and scope toggles under scopes.<model>.<scope>.
+    filter:
+      title: Filters
+      search: Search
+      submit: Filter
+      any: Any
+      contains: Contains
+      min: Min
+      max: Max
+      # The active-filter chips (_active_filters): the row's accessible name, the
+      # per-chip remove control's label, and the clear-all link.
+      active: Active filters
+      remove: "Remove %{filter} filter"
+      clear: Clear all
+
+  # Button style (a Button component flag) per bulk action — a shipped default a
+  # host can extend/override. Unlisted actions fall back to the neutral style.
+  bulk_actions:
+    styles:
+      destroy: danger
+
+  # Button style per custom (member or collection) action — the same convention
+  # as bulk_actions.styles.
+  actions:
+    styles:
+      destroy: danger
+
+  dashboard:
+    no_date_column: No date column to chart.
+
+  # Index "chart" view controls. The y-metric labels interpolate the chartable
+  # column's own attribute name (e.g. "Sum of Total").
+  chart:
+    no_columns: No date columns to chart.
+    update: Update
+    metric:
+      count: Count
+      sum: "Sum of %{attribute}"
+      avg: "Average %{attribute}"
+
   list_html:
     zero: "(none)"
     one: "%{list}"
@@ -51,6 +107,10 @@ en:
     create_html: "%{Model} created."
     update_html: "%{Model} updated."
     destroy_html: "%{Model} deleted."
+    # Custom-action notices: %{action} is the action's label (en.<name>),
+    # e.g. "Publish article" / "Publish all articles".
+    member_action: "%{action} %{model}"
+    collection_action: "%{action} %{models}"
 
   activerecord:
     models:

data/config/routes.rb

@@ -1,9 +1,22 @@
 CafeCar::Engine.routes.draw do
-  scope module: :cafe_car, as: :cafe_car do
-    get "components", to: "examples#index"
+  # The `components` gallery is an unauthenticated UI demo, mounted for development
+  # only so a host app never inherits a public, policy-skipping route in production.
+  if Rails.env.development?
+    scope module: :cafe_car, as: :cafe_car do
+      get "components", to: "examples#index"
+    end
   end
 
   # Opt-in login/logout. Singular resource so the form posts to /session and
   # request_authentication can redirect to new_session_path.
   resource :session, only: %i[new create destroy], controller: "cafe_car/sessions"
+
+  # The dashboard overview is opt-in via a host template, not config: the route
+  # always mounts, but the controller 404s unless the host has written
+  # `app/views/cafe_car/dashboard/show.html.haml`. So a CRUD-only host that never
+  # writes the template sees no dashboard (404 on direct hit, no nav link), while
+  # opt-in stays a matter of "drop a view" — the same convention as every other
+  # CafeCar surface. (Routes are drawn at boot, before any view context, so the
+  # template check can't gate the mount itself.)
+  get "dashboard", to: "cafe_car/dashboards#show", as: :dashboard
 end

data/lib/cafe_car/attributes.rb

@@ -1,23 +1,51 @@
+# The policy's attribute sets — the single surface for "which attributes does
+# this policy expose, and how." Mirrors the nested Scope: a policy builds one
+# (`policy.attributes`) and reads `.listable`, `.displayable`, `.editable`,
+# `.filterable`, and `.actions` through it. Every reader derives from the
+# policy's host-overridable declarations (`permitted_attributes`,
+# `permitted_filters`, `permitted_*_actions`), so a host override of any of
+# those flows through unchanged.
 class CafeCar::Attributes
-  attr_reader :user, :object, :permitted
-
-  def initialize(user, object, permitted_attributes)
-    @user      = user
-    @object    = object
-    @permitted = [ *permitted_attributes ]
-    process_attributes!
+  def initialize(policy)
+    @policy = policy
   end
 
-  def info(method) = CafeCar[:FieldInfo].new(object:, method:)
+  # Columns an index table shows by default — the model's listable fields.
+  def listable = model.info.fields.listable.map(&:method)
+
+  # Columns/associations shown on a record and the default filter set: the
+  # permitted attribute keys unioned with the model's own columns, each foreign
+  # key resolved to its association, parameter-filtered keys (password/token)
+  # and `id` dropped.
+  def displayable
+    permitted_attribute_keys
+      .union(model.columns.map(&:name).map(&:to_sym))
+      .map    { association_for_attribute(_1) || _1 }
+      .reject { filtered_attribute? _1 } - %i[id]
+  end
 
+  # Form input keys for the permitted attributes, minus keys a richer input
+  # abrogates (a file field replaces its `*_cache`, a nested field its ids).
   def editable
-    @editable ||= @permitted.map()
+    permitted_fields.map(&:input_key) - permitted_fields.flat_map(&:abrogated_keys)
   end
 
+  # The attributes an index may be filtered by — the policy's `permitted_filters`
+  # (which defaults to #displayable). Host-overridable on the policy.
+  def filterable = @policy.permitted_filters
 
-  private
+  # The custom actions this policy declares, grouped by target.
+  def actions = Actions.new(@policy)
 
-  def process_attributes!
-    @editable = @permitted.clone
+  # Reads the policy's three host-overridable action lists through one object.
+  Actions = Struct.new(:policy) do
+    def member     = policy.permitted_member_actions
+    def collection = policy.permitted_collection_actions
+    def bulk       = policy.permitted_bulk_actions
   end
+
+  private
+
+  delegate :model, :permitted_attribute_keys, :permitted_fields,
+           :association_for_attribute, :filtered_attribute?, to: :@policy
 end

data/lib/cafe_car/chart_builder.rb

@@ -0,0 +1,217 @@
+module CafeCar
+  # Aggregates an index collection into time buckets for the index "chart" view.
+  # Given a datetime/date column (the x-axis) and a granularity it GROUP BYs a
+  # DB-portable truncation of that column and COUNTs each bucket, then renders an
+  # inline SVG bar chart. The collection passed in is already policy-scoped and
+  # filtered (it is the same relation the table view renders), so the chart never
+  # counts rows the user can't see and always honors the active filters.
+  class ChartBuilder
+    # strftime patterns, shared by SQLite's `strftime` and Ruby's `Time#strftime`
+    # so a bucket label is identical whichever adapter produced the key.
+    FORMATS        = { day: "%Y-%m-%d", week: "%Y-%W", month: "%Y-%m" }.freeze
+    DEFAULT_BUCKET = :month
+
+    # The y-axis aggregations. `count` is a plain row count (no column); `sum`/`avg`
+    # aggregate a numeric column and map to the portable ActiveRecord calculation.
+    OPERATIONS      = { "sum" => :sum, "avg" => :average }.freeze
+    NUMERIC_TYPES   = %i[integer decimal float].freeze
+    DEFAULT_METRIC  = "count"
+    METRIC_DEFAULTS = { "sum" => "Sum of %{attribute}", "avg" => "Average %{attribute}" }.freeze
+
+    # SVG geometry (user units; the viewBox scales it to fit its container). WIDTH
+    # and HEIGHT are FIXED so the chart keeps one landscape shape at ANY bucket
+    # count. The CSS gives `.Chart` a full-width block with `height: auto`, so the
+    # rendered height follows the viewBox aspect ratio — a column-per-bucket layout
+    # made that viewBox near-square for a few buckets (rendered tall and narrow) and
+    # very wide for many (rendered flat and short). Distributing the bars across a
+    # fixed WIDTH instead holds a steady ~3.5:1 landscape that always fills the column.
+    WIDTH      = 1000
+    HEIGHT     = 280
+    PAD_TOP    = 14  # room for the value label above the tallest bar
+    PAD_BOTTOM = 22  # room for the x-axis (bucket) labels
+    MAX_BAR    = 72  # cap bar width so a handful of buckets don't balloon
+    BAR_RATIO  = 0.6 # bar width as a fraction of its slot
+
+    delegate :tag, :safe_join, :t, to: :@template
+
+    def initialize(template, objects:, column: nil, bucket: nil, metric: nil)
+      @template = template
+      @objects  = objects
+      @column   = pick_column(column)
+      @bucket   = FORMATS.key?(bucket.to_s.to_sym) ? bucket.to_s.to_sym : DEFAULT_BUCKET
+      @metric   = pick_metric(metric)
+    end
+
+    attr_reader :column, :bucket, :metric
+
+    # The date/datetime columns offered as x-axis choices: the model's displayable
+    # attributes (policy-respecting) whose type is a date. Column NAMES only reach
+    # the query through this allowlist — a `?chart_x=` param outside it is dropped
+    # by #pick_column, so a raw param can never be interpolated as a column name.
+    def columns
+      @columns ||= policy.attributes.displayable
+                         .map    { info(_1) }
+                         .select { _1.type.in?(%i[date datetime]) }
+                         .map    { _1.method.to_s }
+    end
+
+    # The numeric columns offered as y-axis aggregates: the model's displayable
+    # attributes (policy-respecting, the SAME source of truth as the x-axis) whose
+    # type is numeric. A `chart_y=sum:<col>` param's column is validated against
+    # this list by #pick_metric, so a raw param never becomes a column reference.
+    def value_columns
+      @value_columns ||= policy.attributes.displayable
+                               .map    { info(_1) }
+                               .select { _1.type.in?(NUMERIC_TYPES) }
+                               .map    { _1.method.to_s }
+    end
+
+    def column_options = columns.map { [ info(_1).label, _1 ] }
+    def bucket_options = FORMATS.keys.map { [ _1.to_s.capitalize, _1.to_s ] }
+
+    # Whether a y-metric selector is worth showing — only when there's a numeric
+    # column to aggregate (otherwise `count` is the only choice).
+    def metrics? = value_columns.any?
+
+    # `[label, encoding]` pairs for the y-metric select: a plain count plus a
+    # sum + average per numeric column. Labels come from the locale.
+    def metric_options
+      count = [ t("chart.metric.count", default: "Count"), DEFAULT_METRIC ]
+      aggs  = value_columns.flat_map do |col|
+        attribute = info(col).label
+        OPERATIONS.each_key.map { |op| [ metric_label(op, attribute), "#{op}:#{col}" ] }
+      end
+      [ count, *aggs ]
+    end
+
+    def metric_label(op, attribute)
+      t("chart.metric.#{op}", attribute:, default: METRIC_DEFAULTS.fetch(op) % { attribute: })
+    end
+
+    # Ordered `{ "2026-01" => count }` over the policy-scoped, filtered collection.
+    def data = @data ||= aggregate
+
+    def html_safe? = true
+    def to_s       = svg.to_s
+    def ~@         = @template.concat(to_s)
+
+    private
+
+    def aggregate
+      return {} unless @column
+      base.group(bucket_node).public_send(operation, *value_column)
+          .reject  { |bucket, _| bucket.nil? } # rows with a NULL x-axis value
+          .transform_keys   { label_for _1 }
+          .transform_values { value_for _1 }
+          .sort.to_h
+    end
+
+    # The ActiveRecord calculation for the chosen metric — `:count` (no column),
+    # else `:sum`/`:average` over #value_column. All three emit portable SQL
+    # (COUNT(*) / SUM(col) / AVG(col)) that runs on both Postgres and SQLite.
+    def operation  = OPERATIONS.fetch(@metric.split(":").first, :count)
+    def value_column = @metric.split(":", 2)[1]&.to_sym
+
+    # Normalize an aggregate for the label and bar scale: counts and integer sums
+    # stay Integer; a decimal sum or average collapses to Integer when whole
+    # (301.0 -> 301) and otherwise rounds to 2 places (avg 33.333 -> 33.33), so a
+    # BigDecimal never renders as "0.301e3".
+    def value_for(raw)
+      n = raw.is_a?(BigDecimal) ? raw.to_f : raw
+      return n unless n.is_a?(Float)
+      n == n.round ? n.round : n.round(2)
+    end
+
+    # The y-metric encoding: `count` (default), or `sum:<col>`/`avg:<col>` over a
+    # numeric column. The column half is validated against #value_columns — the
+    # same policy-driven allowlist as the x-axis — so a `?chart_y=` param can never
+    # put a raw column name into the aggregate. An unknown or non-numeric column
+    # (or a bare `count`) falls back to a plain record count.
+    def pick_metric(param)
+      op, col = param.to_s.split(":", 2)
+      return DEFAULT_METRIC unless OPERATIONS.key?(op) && value_columns.include?(col)
+      "#{op}:#{col}"
+    end
+
+    # The collection stripped of clauses that would corrupt a GROUP BY aggregate:
+    # pagination (else only the current page counts), ordering (a non-grouped ORDER
+    # BY column is invalid under GROUP BY on Postgres), and eager loading (its LEFT
+    # JOINs could multiply counts). The WHERE — filters + policy scope — is kept.
+    def base
+      @objects.except(:limit, :offset, :includes, :eager_load, :preload).reorder(nil)
+    end
+
+    # DB-portable date truncation as an Arel function (no raw SQL string, so no
+    # injection surface and Brakeman-clean). The granularity is a fixed keyword and
+    # the column is allowlisted, so neither is attacker-controlled.
+    def bucket_node
+      col = @objects.arel_table[@column]
+      if postgres?
+        Arel::Nodes::NamedFunction.new("date_trunc", [ Arel::Nodes.build_quoted(@bucket.to_s), col ])
+      else
+        Arel::Nodes::NamedFunction.new("strftime", [ Arel::Nodes.build_quoted(FORMATS[@bucket]), col ])
+      end
+    end
+
+    # SQLite's strftime already returns the formatted String; Postgres' date_trunc
+    # returns a Time we format the same way, so both adapters key by the same label.
+    def label_for(key) = key.is_a?(String) ? key : key.to_time.strftime(FORMATS[@bucket])
+
+    def postgres? = @objects.klass.connection_db_config.adapter.match?(/postg/i)
+
+    def pick_column(param)
+      param = param.to_s
+      return param if columns.include?(param)
+      columns.include?("created_at") ? "created_at" : columns.first
+    end
+
+    # Build the policy from a model instance, not the relation — the same way the
+    # rest of CafeCar does (`policy(model.new)`). A policy's `permitted_attributes`
+    # may inspect the record (e.g. `object.new_record?`), which a relation can't answer.
+    def policy     = @template.policy(@objects.klass.new)
+    def info(name) = @objects.info.field(name)
+
+    # --- SVG rendering ------------------------------------------------------
+
+    def svg
+      points = data
+      max    = points.values.max || 0
+      plot   = HEIGHT - PAD_TOP - PAD_BOTTOM
+      slot   = points.empty? ? WIDTH : WIDTH.to_f / points.size
+      bar_w  = [ slot * BAR_RATIO, MAX_BAR ].min
+
+      tag.svg(class: "Chart", role: "img", "aria-label": aria_label,
+              "viewBox": "0 0 #{WIDTH} #{HEIGHT}", preserveAspectRatio: "xMidYMid meet") do
+        safe_join [ baseline, *bars(points, max, plot, slot, bar_w) ]
+      end
+    end
+
+    def baseline
+      y = HEIGHT - PAD_BOTTOM
+      tag.line(class: "Chart-axis", x1: 0, y1: y, x2: WIDTH, y2: y,
+               stroke: "currentColor", "stroke-opacity": "0.25")
+    end
+
+    def bars(points, max, plot, slot, bar_w)
+      points.each_with_index.map do |(label, value), i|
+        cx = slot * (i + 0.5)
+        x  = cx - bar_w / 2
+        h  = max.zero? ? 0 : (value.to_f / max * plot).round
+        y  = HEIGHT - PAD_BOTTOM - h
+
+        tag.g(class: "Chart-bar", "data-bucket": label, "data-value": value) do
+          safe_join [
+            tag.title("#{label}: #{value}"),
+            tag.rect(x:, y:, width: bar_w, height: h, rx: 2, fill: "currentColor"),
+            tag.text(value, x: cx, y: y - 4, class: "Chart-value", "text-anchor": "middle"),
+            tag.text(label, x: cx, y: HEIGHT - PAD_BOTTOM + 15, class: "Chart-label", "text-anchor": "middle")
+          ]
+        end
+      end
+    end
+
+    def aria_label
+      "#{@objects.model_name.human(count: :all)} by #{info(@column).label}" if @column
+    end
+  end
+end