cafe_car 0.2.1 → 0.3.0

data/lib/cafe_car/filter_builder.rb

@@ -13,8 +13,21 @@ module CafeCar
     def persisted? = false
     def errors     = Hash.new([])
 
+    # Rails' select/check_box read the current value off the object by the field
+    # name (`object.status`); a nested control's name is a dot-path
+    # (`client.status`), so split it to dig the nested param — the same segment
+    # walk as #value.
     def method_missing(name, *, &)
-      @params.dig("", name)
+      @params.dig("", *name.to_s.split("."))
+    end
+
+    # Current value of a (possibly nested) filter param — `value(:price, :min)`
+    # reads `?price.min=`, and `value("client.owner_id")` digs the nested
+    # `?client.owner_id=` a nested control posts (a dotted key splits into its
+    # segments). Nil-safe against shapes a control can't express (a hand-typed
+    # `?price=10..20` parses to a Range, not a Hash).
+    def value(*keys)
+      keys.flat_map { _1.to_s.split(".") }.reduce(@params[""]) { |v, key| v[key] if v.is_a?(Hash) }
     end
   end
 end

data/lib/cafe_car/form_builder.rb

@@ -13,17 +13,66 @@ module CafeCar
     def policy    = @template.policy(@object)
     def show(...) = ui.Input { @template.present(@object).show(...) }
 
-    def association(method, collection: nil, **options)
+    def association(method, collection: nil, multiple: false, **options)
       info = info(method)
 
       return show(info.input_key) if info.polymorphic? and object.persisted?
       return hidden(*info.polymorphic_methods) if info.polymorphic?
 
-      collection              ||= info.collection
-      # options[:prompt]      ||= info.prompt
+      collection ||= with_selected(info)
+      # A multi-select filters by a set (`author_id[]`), so no blank "any" option —
+      # an empty selection already means "any". A single select keeps its prompt.
+      options[:include_blank] ||= info.prompt unless multiple
+
+      html = searchable_select(info)
+      html[:multiple] = true if multiple
+
+      collection_select(info.input_key, collection, :id,
+                        -> { @template.present(_1).title }, options, html)
+    end
+
+    # HTML options that flag an association <select> for Tom Select enhancement
+    # (see cafe_car.js). When the associated model exposes an `options` typeahead
+    # feed, its URL rides along so keystroke search can reach records past
+    # `max_collection_options`; without it the field degrades to a plain select.
+    def searchable_select(info)
+      data = { "searchable-select": "" }
+      url  = options_url(info.reflection&.klass)
+      data["searchable-select-url"] = url if url
+      { data: }
+    end
+
+    # URL of the associated model's typeahead feed in the current namespace, or nil
+    # when no such route exists. e.g. `belongs_to :owner` -> `options_admin_users_path`.
+    def options_url(klass)
+      return unless klass
+      helper = [ :options, *@template.namespace, klass.model_name.route_key, :path ].join("_")
+      @template.public_send(helper) if @template.respond_to?(helper)
+    end
+
+    # The capped option collection, guaranteeing the currently-associated record is
+    # among the options even when it sorts past the cap — otherwise editing a record
+    # whose association is beyond `max_collection_options` would silently drop the value.
+    def with_selected(info)
+      collection = info.collection
+      return collection unless info.reflection&.belongs_to?
+
+      selected = object.try(info.reflection.name)
+      return collection unless selected
+
+      records = collection.to_a
+      records.include?(selected) ? records : [ selected, *records ]
+    end
+
+    # An ActiveRecord enum renders as a plain <select> of its declared values,
+    # read straight off `defined_enums` (see FieldInfo#values).
+    def enum(method, choices = nil, **options)
+      info = info(method)
+
+      choices                 ||= info.values
       options[:include_blank] ||= info.prompt
 
-      input(info.input_key, collection, :id, -> { @template.present(_1).title }, as: :collection_select, **options)
+      select(method, choices, options)
     end
 
     def hidden(*methods, **, &)
@@ -52,8 +101,14 @@ module CafeCar
 
       options[:placeholder]  = info.placeholder  unless options.key?(:placeholder)
       options[:autocomplete] = info.autocomplete unless options.key?(:autocomplete)
+      options[:multiple]     = true if as == :file_field && info.multiple? && !options.key?(:multiple)
+
+      # Field-typed inputs render through their component object; explicit `as:`
+      # overrides the family doesn't own (e.g. `hidden_field`) fall through to the
+      # helper directly, preserving `#input`'s "render via any form helper" contract.
+      return public_send(as, method, *args, **options) unless Inputs::BaseInput.classes.key?(as)
 
-      public_send(as, method, *args, **options)
+      Inputs::BaseInput.build(as, form: self, method:, template: @template, args:, **options).to_html
     end
 
     def hint(method, text = info(method).hint, **)
@@ -94,7 +149,7 @@ module CafeCar
       end
     end
 
-    def remaining_attributes = policy.editable_attributes - @fields.keys
+    def remaining_attributes = policy.attributes.editable - @fields.keys
 
     def remaining_fields(**, &block)
       block  ||= proc { field(_1, **) }

data/lib/cafe_car/helpers.rb

@@ -33,6 +33,14 @@ module CafeCar
 
     def body_classes = [ *controller_path.split(?/), action_name, *@body_class ]
 
+    # Stylesheet <link> for the active bundled theme (`CafeCar.theme`), injected
+    # into every CafeCar page's <head>. Each theme is self-contained — its light
+    # tokens plus a `prefers-color-scheme: dark` block — so dark mode needs no
+    # separate tag. Emitted after `application.css` so its `:root` tokens win.
+    def theme_stylesheet_tag
+      stylesheet_link_tag "cafe_car/themes/#{CafeCar.theme}", "data-turbo-track": "reload"
+    end
+
     def title(object)
       present(object).title.presence.tap do |title|
         content_for(:title, title)
@@ -81,6 +89,81 @@ module CafeCar
     # the export matches the view. Pagination is dropped (CSV exports the full set).
     def csv_url = url_for(request.params.except("page", "per").merge(format: :csv))
 
+    # The active-filter chips above the index: one per leaf in the policy-gated
+    # filter set (permitted_filter_params), each carrying its human label, display
+    # value, and the URL that removes just that one filter — the current params
+    # minus its single key, so every OTHER filter plus q/sort/view survive.
+    # Reflecting the gated set (not raw request params) means a stray or
+    # non-permitted param never grows a chip.
+    def active_filters(klass = model)
+      flatten_filters(permitted_filter_params).map do |key, value|
+        { key:, label: filter_label(klass, key), value: filter_value(klass, key, value),
+          remove_url: url_for(request.params.except(key, "page")) }
+      end
+    end
+
+    # "Clear all" target: the current params minus every active filter key (and
+    # the now-stale page), keeping the control params — q, sort, view, per.
+    def clear_filters_url
+      url_for(request.params.except(*flatten_filters(permitted_filter_params).keys, "page"))
+    end
+
+    # Flattens the nested gated filter params back to the flat dot-keyed params
+    # request.params carries: every nested hash — an operator group (`{min:}`) or
+    # an association hop (`{client: {status:}}`) — recurses, joining segments with
+    # ".", so a leaf's key is exactly the one url_for drops to remove it. Non-hash
+    # leaves (a scalar, an id set, a parsed Range) end the walk.
+    def flatten_filters(params, prefix = "")
+      params.each_with_object({}) do |(key, value), flat|
+        path = "#{prefix}#{key}"
+        value.is_a?(Hash) ? flat.merge!(flatten_filters(value, "#{path}.")) : flat[path] = value
+      end
+    end
+
+    # The human label for a filter key, from the same Filter::FieldInfo the panel
+    # controls read (policy/locale-driven, with a humanized-attribute fallback) —
+    # never the raw column/operator key.
+    def filter_label(klass, key)
+      CafeCar["Filter::FieldInfo"].new(model: klass, method: filter_method(key)).label
+    end
+
+    # A filter key reduced to the attribute path its label reads: the trailing
+    # operator char (`name~`) and a trailing word-operator segment (`price.min`)
+    # drop off; a nested association path (`client.status`) keeps its dots.
+    def filter_method(key)
+      segments = key.to_s.sub(/\W+$/, "").split(".")
+      segments.pop if segments.size > 1 && CafeCar::QueryBuilder::OPS.key?(segments.last)
+      segments.join(".")
+    end
+
+    # A filter value as chip text. An association filter — a belongs_to foreign-key
+    # set (`owner_id[]`) or a has_many/has_one membership set (`line_items.id[]`) —
+    # shows each referenced record's TITLE (the same title the filter's typeahead
+    # lists), so a chip reads "Owner: Jane Doe" not "Owner: 42". The whole set is
+    # resolved in ONE query, and an id that no longer resolves falls back to its raw
+    # value. Every other filter (enum/string/range/boolean) prints its value(s) as-is.
+    def filter_value(klass, key, value)
+      ids   = Array.wrap(value)
+      assoc = filter_association(klass, key)
+      return ids.join(", ") unless assoc
+
+      titles = assoc.where(id: ids).index_by { _1.id.to_s }
+      ids.map { |id| titles[id.to_s]&.then { present(_1).title } || id }.join(", ")
+    end
+
+    # The model whose records an association filter's values are ids of, or nil for
+    # a non-association filter. A foreign-key set resolves through the terminal
+    # belongs_to; a membership set (`<assoc>.id[]`) through the association named
+    # just before the `.id`. Reflects through the same Filter::FieldInfo the panel
+    # controls read, so titling never diverges from what the control's select shows.
+    def filter_association(klass, key)
+      method          = filter_method(key)
+      parent, _, leaf = method.rpartition(".")
+      method          = parent if leaf == "id" && parent.present?
+      field           = CafeCar["Filter::FieldInfo"].new(model: klass, method:)
+      field.reflection&.klass if field.type.in?(%i[belongs_to has_many has_one])
+    end
+
     def context(name = nil, &)
       @context ||= []
 
@@ -143,6 +226,119 @@ module CafeCar
       CafeCar[:TableBuilder].new(self, objects:, **options, &block)
     end
 
+    def chart_for(objects, **options)
+      CafeCar[:ChartBuilder].new(self, objects:,
+        column: params[:chart_x], bucket: params[:chart_by], metric: params[:chart_y], **options)
+    end
+
+    # The bulk actions offered on this model's index table — the model policy's
+    # `permitted_bulk_actions` list is the source of truth. This only decides which
+    # buttons show; each selected row is still authorized one-by-one in the
+    # controller, so a shown action never bulk-bypasses a per-record denial.
+    def bulk_actions(klass = model)
+      policy(klass.new).attributes.actions.bulk
+    end
+
+    def bulk_actions? = bulk_actions.any?
+
+    # A single bulk-action submit button, wired to the table's BulkForm from the
+    # toolbar (`form: "BulkForm"`). The label comes from the locale (`en.destroy`),
+    # never a hardcoded string, and the button style from the locale too — a shipped
+    # default maps `destroy` to `:danger` (see `bulk_actions.styles`). The default
+    # `_bulk_actions` partial loops `bulk_actions` calling this; a host overriding
+    # the partial can call it directly for a bespoke set.
+    def bulk_action(name, style = bulk_action_style(name))
+      label   = t(name, default: name.to_s.humanize)
+      confirm = t(:bulk_confirm, scope: :helpers, action: label)
+      Button(*style, tag: :button, type: :submit, form: "BulkForm",
+        name: :bulk_action, value: name, data: { turbo_confirm: confirm }) { label }
+    end
+
+    # The button style (a Button flag like `:danger`) for a bulk action, from the
+    # locale under `bulk_actions.styles`, or nil for the default style.
+    def bulk_action_style(name)
+      t("bulk_actions.styles.#{name}", default: nil)&.to_sym
+    end
+
+    # The custom collection actions offered in this model's index toolbar — the
+    # model policy's `permitted_collection_actions` list is the source of truth,
+    # like #bulk_actions. This only decides which buttons show; the controller
+    # re-authorizes the POST (see Controller#collection_action).
+    def collection_actions(klass = model)
+      policy(klass.new).attributes.actions.collection
+    end
+
+    # A collection-action button for the index toolbar: POSTs the named action
+    # to the generic collection route (Controller#collection_action), carrying the
+    # active filters + search so the action runs over exactly the viewed set. The
+    # label appends that set's count (localized `helpers.collection_action` — e.g.
+    # "Publish all 21"); style and confirm come from the locale like #bulk_action.
+    def collection_action(name, style = action_style(name))
+      count   = filtered_scope.count
+      action  = t(name, default: name.to_s.humanize)
+      label   = t(:collection_action, scope: :helpers, action:, count:)
+      confirm = t(:collection_confirm, scope: :helpers, action:, count:,
+                  models: model.model_name.human(count:).downcase)
+      filters = search_term ? filter_params.merge(q: search_term) : filter_params
+      url     = url_for(filters.merge(action: :collection_action, collection_action: name))
+      button_to label, url, class: ui.Button(*style).class_name, data: { turbo_confirm: confirm }
+    end
+
+    # The button style for a custom (member or collection) action, from the
+    # locale under `actions.styles` — the same convention as #bulk_action_style.
+    def action_style(name)
+      t("actions.styles.#{name}", default: nil)&.to_sym
+    end
+
+    # A dashboard metric tile: a label over the value captured from the block. The
+    # block is host-authored (a real view), evaluated at render.
+    def metric(label, &block)
+      render "cafe_car/dashboard/metric", label:, value: capture(&block)
+    end
+
+    # A dashboard chart tile: a title over the dependency-free inline-SVG bar chart,
+    # built from `model`'s records bucketed over the `x` date column at `by`
+    # granularity. `x` runs through ChartBuilder's date-column allowlist unchanged,
+    # so a column name can never reach SQL raw.
+    def chart(title, model:, x:, by: nil)
+      render "cafe_car/dashboard/chart", title:, objects: model.all, x:, by:
+    end
+
+    # The policy-driven metric tiles for `model`: one count tile per name in the
+    # model policy's `permitted_metrics` (`:all` = the whole relation). This is the
+    # default dashboard behavior — a host template overrides by calling `metric`
+    # directly instead.
+    def metrics(model)
+      policy = policy(model.new)
+      safe_join(policy.permitted_metrics.map { metric_for(model, _1) })
+    end
+
+    def metric_for(model, name)
+      scope = name.to_sym == :all ? model.all : model.public_send(name)
+      metric(metric_label(model, name)) { scope.count }
+    end
+
+    # A metric tile's label, from the locale: the pluralized model name for the
+    # whole-relation `:all` metric, else `metrics.<name>` (defaulting to the
+    # humanized scope name).
+    def metric_label(model, name)
+      return model.model_name.human(count: 2) if name.to_sym == :all
+      t("metrics.#{name}", default: name.to_s.humanize)
+    end
+
+    # Wraps the index table in the form that submits the selected row ids and the
+    # chosen bulk action. With no bulk actions available, the table renders as-is.
+    # The action bar itself lives up in the index toolbar (next to the search box);
+    # its buttons reach back into this form by id via their `form="BulkForm"`.
+    def bulk_form(&block)
+      content = capture(&block)
+      return content unless bulk_actions?
+
+      form_tag(url_for(action: :batch), method: :post, class: "BulkForm", id: "BulkForm") do
+        content
+      end
+    end
+
     def debug?   = params.key?(:debug)
     def console? = params.key?(:console)
 

data/lib/cafe_car/inputs/association_input.rb

@@ -0,0 +1,11 @@
+module CafeCar
+  module Inputs
+    # A `<select>` over an association's records (belongs_to / has_many). Delegates
+    # to the form builder's `association`, which caps the collection, guarantees the
+    # currently-associated record is present, and flags the select for typeahead
+    # enhancement when the associated model exposes an options feed.
+    class AssociationInput < BaseInput
+      def helper = :association
+    end
+  end
+end

data/lib/cafe_car/inputs/base_input.rb

@@ -1,19 +1,68 @@
 module CafeCar
   module Inputs
+    # Renders one bound form input for a field.
+    #
+    # Each field type is a small subclass that names the form-builder helper it emits
+    # through (and any per-type options). `.build` maps a field's resolved input key
+    # (what `FieldInfo#input` returns) to the right subclass, so *which* input a field
+    # gets stays single-sourced on the field metadata — these objects only render it.
+    #
+    # Styling rides the shared `ui/Input.css` (native input/select/textarea), and copy
+    # (placeholder, prompt, hint) comes from the field's locale via `FieldInfo` — no
+    # hardcoded strings, no styles outside components.
     class BaseInput
-      attr_accessor :options
+      # Maps a resolved input key (`FieldInfo#input`) to its component class. Kept
+      # lazy so the subclass constants resolve through Zeitwerk at call time.
+      def self.classes
+        {
+          text_field:     StringInput,
+          text_area:      TextAreaInput,
+          number_field:   NumberInput,
+          check_box:      BooleanInput,
+          date_field:     DateInput,
+          datetime_field: DatetimeInput,
+          password_field: PasswordInput,
+          file_field:     FileInput,
+          rich_text_area: RichTextInput,
+          enum:           SelectInput,
+          association:    AssociationInput,
+          fields_for:     NestedInput
+        }
+      end
+
+      def self.build(key, **, &)
+        klass = classes[key] or raise ArgumentError, "No input component for #{key.inspect}"
+        klass.new(**, &)
+      end
 
-      def initialize(template:, **options)
+      attr_reader :form, :method, :template, :args, :options
+
+      def initialize(form:, method:, template:, args: [], **options, &block)
+        @form     = form
+        @method   = method
         @template = template
+        @args     = args
         @options  = options
+        @block    = block
       end
 
-      def tag  = :input
-      def type = :text
+      def info = form.info(method)
 
-      def to_html
-        @template.Input(tag:, type:, **options)
-      end
+      # The form-builder helper this input renders through. Subclasses override.
+      def helper = :text_field
+
+      # Per-type option defaults, filled only where the caller left them unset.
+      def defaults = {}
+
+      # Locale-driven copy for free-text inputs — never a hardcoded string.
+      def text_hints = { placeholder: info.placeholder, autocomplete: info.autocomplete }.compact
+
+      def render_options = defaults.merge(options)
+
+      def to_html = form.public_send(helper, method, *args, **render_options, &@block)
+
+      def to_s       = to_html.to_s
+      def html_safe? = true
     end
   end
 end

data/lib/cafe_car/inputs/boolean_input.rb

@@ -0,0 +1,9 @@
+module CafeCar
+  module Inputs
+    # A native `<input type="checkbox">` (with Rails' companion hidden field) for
+    # boolean columns, themed as a CafeCar control by `ui/Input.css`.
+    class BooleanInput < BaseInput
+      def helper = :check_box
+    end
+  end
+end

data/lib/cafe_car/inputs/date_input.rb

@@ -0,0 +1,8 @@
+module CafeCar
+  module Inputs
+    # A native date picker `<input type="date">` for date columns.
+    class DateInput < BaseInput
+      def helper = :date_field
+    end
+  end
+end

data/lib/cafe_car/inputs/datetime_input.rb

@@ -0,0 +1,8 @@
+module CafeCar
+  module Inputs
+    # A native `<input type="datetime-local">` for datetime columns.
+    class DatetimeInput < BaseInput
+      def helper = :datetime_field
+    end
+  end
+end

data/lib/cafe_car/inputs/file_input.rb

@@ -0,0 +1,11 @@
+module CafeCar
+  module Inputs
+    # A file picker `<input type="file">` for Active Storage attachments. A
+    # `has_many_attached` field renders a multiple picker so several files upload
+    # at once.
+    class FileInput < BaseInput
+      def helper   = :file_field
+      def defaults = info.multiple? ? { multiple: true } : {}
+    end
+  end
+end

data/lib/cafe_car/inputs/nested_input.rb

@@ -0,0 +1,10 @@
+module CafeCar
+  module Inputs
+    # The `fields_for` sub-form for a `accepts_nested_attributes_for` association.
+    # Delegates to the form builder's `fields_for`, which renders each child record's
+    # remaining fields (or the caller's block).
+    class NestedInput < BaseInput
+      def helper = :fields_for
+    end
+  end
+end

data/lib/cafe_car/inputs/number_input.rb

@@ -0,0 +1,9 @@
+module CafeCar
+  module Inputs
+    # A numeric `<input type="number">` for integer columns.
+    class NumberInput < BaseInput
+      def helper   = :number_field
+      def defaults = text_hints
+    end
+  end
+end

data/lib/cafe_car/inputs/password_input.rb

@@ -1,7 +1,9 @@
 module CafeCar
   module Inputs
-    class StringInput < BaseInput
-      def tag = :input
+    # A masked `<input type="password">` for `has_secure_password` digests.
+    class PasswordInput < BaseInput
+      def helper   = :password_field
+      def defaults = text_hints
     end
   end
 end

data/lib/cafe_car/inputs/rich_text_input.rb

@@ -0,0 +1,9 @@
+module CafeCar
+  module Inputs
+    # An Action Text `<trix-editor>` (with its hidden input) for `has_rich_text`
+    # associations.
+    class RichTextInput < BaseInput
+      def helper = :rich_text_area
+    end
+  end
+end

data/lib/cafe_car/inputs/select_input.rb

@@ -0,0 +1,10 @@
+module CafeCar
+  module Inputs
+    # A `<select>` of an ActiveRecord enum's declared values. Delegates to the form
+    # builder's `enum`, which reads the choices off `defined_enums` and prepends the
+    # locale prompt as the blank option.
+    class SelectInput < BaseInput
+      def helper = :enum
+    end
+  end
+end

data/lib/cafe_car/inputs/string_input.rb

@@ -1,7 +1,9 @@
 module CafeCar
   module Inputs
+    # A free-text `<input type="text">` — the default for string/decimal columns.
     class StringInput < BaseInput
-      def type = :text
+      def helper   = :text_field
+      def defaults = text_hints
     end
   end
 end

data/lib/cafe_car/inputs/text_area_input.rb

@@ -0,0 +1,9 @@
+module CafeCar
+  module Inputs
+    # A multi-line `<textarea>` for text/json columns.
+    class TextAreaInput < BaseInput
+      def helper   = :text_area
+      def defaults = text_hints
+    end
+  end
+end

data/lib/cafe_car/link_builder.rb

@@ -45,6 +45,17 @@ module CafeCar
       end
     end
 
+    # A custom member action (Policy#permitted_member_actions) as a POST link —
+    # label, i18n and disable state (the `name?` predicate, via #cant?) all
+    # derive from the action name, like #destroy. The `params` override the
+    # route action: the href hits the generic member-action endpoint
+    # (Controller#member_action), which re-authorizes and forwards to the
+    # record's `name!`.
+    def action(name, *, **opts, &)
+      link(name, @object, *, method: :post,
+        params: { action: :member_action, member_action: name }, **opts, &)
+    end
+
     def show(*, **, &)    = link(:show, @object, *, data: { turbo_stream:  nil }, **, &)
     def edit(...)         = link(:edit, @object, ...)
     def destroy(*, **, &) = link(:destroy, @object, *, method: :delete, confirm: confirm(:destroy), **, &)

data/lib/cafe_car/model.rb

@@ -4,20 +4,49 @@ module CafeCar::Model
   include CafeCar::Queryable
   include CafeCar::Informable
 
+  # A validated sort term: an Arel/hash `order` argument plus the association to
+  # `left_outer_joins` (nil for a plain column) so the qualified ORDER BY resolves.
+  SortKey = Data.define(:order, :join)
+
   class_methods do
     def sorted(*args)
-      return all if args.compact_blank!.empty?
-      args = args.flat_map { normalize_sort_key(_1) }
-      reorder(*args)
+      keys = args.join(",").split(",").filter_map { normalize_sort_key(_1) }
+      return all if keys.empty?
+      scope = reorder(*keys.map(&:order))
+      joins = keys.filter_map(&:join).uniq
+      joins.any? ? scope.left_outer_joins(*joins) : scope
     end
 
+    # Turn one requested sort key into a safe SortKey, or nil to drop it. Honors a
+    # leading "-" for descending. Every key is validated against the model's real
+    # columns/associations before it can reach `reorder` — a client-supplied
+    # `?sort=` (e.g. `item.`, `bogus.col`, or a raw SQL fragment) can never pass
+    # through as SQL, where it would trip Rails' dangerous-query guard into an
+    # unauthenticated 500.
     def normalize_sort_key(key)
-      case key
-      when /,/
-        key.split(",").map { normalize_sort_key _1 }
-      when /^-(.+)$/ then { $1 => :desc }
-      else key
+      desc      = key.to_s.start_with?("-")
+      name      = key.to_s.delete_prefix("-").strip
+      direction = desc ? :desc : :asc
+
+      if name.include?(".")
+        association_sort_key(name, direction)
+      elsif column_names.include?(name)
+        SortKey.new(order: { name => direction }, join: nil)
       end
     end
+
+    # A `<belongs_to>.<column>` header-sort key (LabelBuilder only emits these for
+    # belongs_to). Qualifies the ORDER BY to the *reflected* table so custom table
+    # names/aliases work, and joins the association in so the column resolves.
+    # Strict: an unknown/polymorphic association or unknown column returns nil.
+    def association_sort_key(name, direction)
+      assoc, column = name.split(".", 2)
+      reflection    = reflect_on_association(assoc.to_sym)
+      return unless reflection&.belongs_to? && !reflection.polymorphic?
+      return unless reflection.klass.column_names.include?(column)
+
+      order = reflection.klass.arel_table[column].public_send(direction)
+      SortKey.new(order:, join: reflection.name)
+    end
   end
 end

data/lib/cafe_car/navigation.rb

@@ -43,6 +43,16 @@ module CafeCar
 
     def router = Rails.application.routes.router
     def named_routes = Rails.application.routes.named_routes.to_h.values.map { Route.new(_1, template: @template) }
+
+    # Path to the opt-in dashboard overview, or nil until a host writes the
+    # dashboard template (`app/views/cafe_car/dashboard/show.html.haml`) — its
+    # existence is the opt-in. The dashboard route lives in the engine (not the
+    # host's routes), so it's resolved through the engine's own url helpers — that
+    # works from any host controller regardless of where CafeCar is mounted.
+    def dashboard_href
+      return unless @template.lookup_context.exists?("show", %w[cafe_car/dashboard], false)
+      CafeCar::Engine.routes.url_helpers.dashboard_path
+    end
     def index_routes = named_routes.select(&:index?)
     def groups = routes.group_by(&:group)