janela 0.10.0 → 0.12.0

data/app/helpers/janela/frames_helper.rb

@@ -26,8 +26,15 @@ module Janela
     # so a host that changes the query in place (a renderer, granularity or
     # limit control) keeps one stable frame for Turbo to reconcile into
     # rather than a different id every time the query changes (ADR 029).
-    def janela_pane(model, measure, by: nil, as: :table, granularity: nil, limit: nil, id: nil)
-      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit,
+    #
+    # prominence: is one of three steps for a single value, and height: one of
+    # five for a chart. Both travel in the pane's URL for the same reason.
+    # height: is one of five steps, and travels in the pane's URL because the
+    # server draws the pane from it again on every cross-filter. It is not part
+    # of the frame's id: how tall a pane is does not say which query it is
+    # (ADR 047, ADR 029).
+    def janela_pane(model, measure, by: nil, as: :table, granularity: nil, limit: nil, height: nil, prominence: nil, companions: nil, id: nil)
+      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit, height: height, prominence: prominence, companions: companions.presence,
                 where: @janela_fixed_filters.presence }.compact
       base = janela_routes.pane_path(model.model_name.route_key, measure, by, **query)
 
@@ -39,8 +46,9 @@ module Janela
 
     # A pane as it was when the snapshot was taken: same shape as janela_pane,
     # not part of the live frame's filter state (ADR 009).
-    def janela_snapshot_pane(snapshot, model, measure, by: nil, as: :table, granularity: nil, limit: nil)
-      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit }.compact
+    def janela_snapshot_pane(snapshot, model, measure, by: nil, as: :table, granularity: nil, limit: nil, height: nil, prominence: nil, companions: nil)
+      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit, height: height,
+                prominence: prominence, companions: companions.presence }.compact
       src = janela_routes.snapshot_pane_path(snapshot, model.model_name.route_key, measure, by, **query)
 
       turbo_frame_tag Query.turbo_frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit, snapshot: snapshot),

data/app/models/janela/pane.rb

@@ -5,6 +5,14 @@ module Janela
   # invent a query or reach a model nobody exposed.
   class Pane < ActiveRecord::Base
     SPANS = (1..12).freeze
+
+    # How tall a bar or line chart is drawn, or nil for what it always was
+    # (ADR 047). Five steps rather than pixels: a stored integer selects a class
+    # that is already written (ADR 016).
+    HEIGHTS = Query::HEIGHTS
+
+    # How prominent a single value is drawn (ADR 050).
+    PROMINENCES = Query::PROMINENCES
     LIMITS = (1..1000).freeze
     # A form cannot offer a thousand options, and these are the row counts a
     # dashboard actually asks for. Any limit inside LIMITS is still valid.
@@ -30,6 +38,10 @@ module Janela
     validates :kind, inclusion: { in: KINDS }
     validates :span, inclusion: { in: SPANS }
     validates :limit, inclusion: { in: LIMITS }, allow_nil: true
+    validates :height, inclusion: { in: HEIGHTS }, allow_nil: true
+    validates :prominence, inclusion: { in: PROMINENCES }, allow_nil: true
+    before_validation :normalise_companions
+    validate :companions_are_declared
     validates :measure, presence: true, if: :query?
     validate :declared_by_a_janela_block, if: :query?
     validate :holds_no_query, unless: :query?
@@ -72,7 +84,7 @@ module Janela
     # instead (ADR 018).
     def query(filters: {}, fixed: {}, renderer: self.renderer)
       Query.new(definition: definition, measure: measure.to_sym, dimension: dimension.presence&.to_sym,
-                renderer: renderer, granularity: granularity, limit: limit, filters: filters, fixed: fixed,
+                renderer: renderer, granularity: granularity, limit: limit, height: height, prominence: prominence, companions: companions, filters: filters, fixed: fixed,
                 default: frame.default_for(definition.model), title: title)
     end
 
@@ -99,7 +111,7 @@ module Janela
     end
 
     def chart?
-      Query::RENDERERS.include?(renderer.to_s) && renderer.to_s != "table"
+      Query::CANVAS.include?(renderer.to_s)
     end
 
     def definition
@@ -107,6 +119,25 @@ module Janela
     end
 
     private
+      # A multiple select sends an empty string beside its choices, and an empty
+      # selection is nothing rather than an empty list.
+      def normalise_companions
+        self.companions = Array(companions).map(&:to_s).reject(&:blank?).presence
+      end
+
+      # The same rules a URL is held to, from the same place, so a row cannot
+      # name what a request could not (ADR 051).
+      def companions_are_declared
+        return if companions.blank? || !query? || measure.blank? || Query::RENDERERS.exclude?(renderer.to_s)
+
+        Query.new(definition: definition, measure: measure.to_sym, dimension: dimension.presence&.to_sym,
+                  renderer: renderer, companions: companions)
+      rescue Janela::BadRequest => error
+        errors.add(:companions, error.message)
+      rescue Janela::Error
+        nil # an unknown model is reported by its own validation
+      end
+
       def panes_above
         frame.panes.where(position: ...position).order(:position)
       end

data/app/models/janela/query.rb

@@ -5,9 +5,35 @@ module Janela
   # rather than collapsing this one to the value clicked. A query read from a
   # snapshot shows stored results and cannot be clicked at all.
   class Query
-    RENDERERS = %w[table bar line].freeze
+    RENDERERS = %w[table bar line doughnut pie].freeze
 
-    attr_reader :definition, :measure, :dimension, :renderer, :limit, :filters, :fixed, :default, :snapshot
+    # Drawn by Chart.js on a canvas, and so blank without a chart runtime.
+    CANVAS = %w[bar line].freeze
+
+    # Drawn on the server as SVG instead (ADR 046).
+    RINGS = %w[doughnut pie].freeze
+
+    # Palette slots before the neutral. Colour is chosen by position and never
+    # cycled: a ninth category drawn in the first colour would be two
+    # categories the same beside a legend that says they differ (ADR 046).
+    SERIES = 8
+
+    # The steps a chart's height may take (ADR 047). Pane::HEIGHTS is the same
+    # range for a stored row, and a test holds the two together.
+    HEIGHTS = (1..5).freeze
+
+    # The steps a single value's prominence may take (ADR 050).
+    PROMINENCES = (1..3).freeze
+
+    # Each companion column is a query of its own, so how many a pane may run
+    # is bounded, as what one query may ask for is (ADR 051, ADR 025).
+    MAX_COMPANIONS = 3
+
+    # A column beside a table's label: a measure's formatted numbers, or a
+    # dimension's shared fact, by label.
+    Companion = Struct.new(:name, :header, :fact, :cells, keyword_init: true)
+
+    attr_reader :definition, :measure, :dimension, :renderer, :limit, :height, :prominence, :companions, :filters, :fixed, :default, :snapshot
 
     # The helper renders the turbo frame and the controller renders its
     # replacement, so both derive the id the same way from the same parameters.
@@ -17,7 +43,7 @@ module Janela
       parts.compact.join("_")
     end
 
-    def initialize(definition:, measure:, dimension: nil, renderer: "table", granularity: nil, limit: nil, filters: {}, fixed: {}, default: {}, snapshot: nil, title: nil)
+    def initialize(definition:, measure:, dimension: nil, renderer: "table", granularity: nil, limit: nil, height: nil, prominence: nil, companions: nil, filters: {}, fixed: {}, default: {}, snapshot: nil, title: nil)
       @definition = definition
       @title = title
       @measure = measure
@@ -31,6 +57,9 @@ module Janela
       raise BadRequest, "unknown pane renderer #{renderer.inspect}" unless RENDERERS.include?(@renderer)
       @granularity = Dimension.granularity!(granularity) if granularity.present?
       @limit = definition.limit!(limit) if limit.present?
+      @height = height!(height) if height.present?
+      @prominence = prominence!(prominence) if prominence.present?
+      @companions = companions!(companions)
     end
 
     def model
@@ -60,15 +89,101 @@ module Janela
       @granularity || (dimension_definition.granularity if time?)
     end
 
-    # Clicking a category adds one Ransack condition; clicking a time bucket
-    # would need two, and the dashboard toggles one key at a time (ADR 006).
     # A stored pane is the record of a moment and is not clickable (ADR 009).
+    # A time pane is: a bucket writes the pair of conditions for its range
+    # (ADR 045).
     def clickable?
-      !single_value? && !time? && !frozen?
+      !single_value? && !frozen?
     end
 
     def chart?
-      !single_value? && renderer != "table"
+      !single_value? && CANVAS.include?(renderer)
+    end
+
+    # A height means a box only where there is a canvas to fill it. A ring, a
+    # table and a single value ignore one, so switching a pane between
+    # renderers never invalidates it (ADR 047).
+    # Only a single value has a headline number to make more or less of. A
+    # table, a chart and a ring ignore one, so a pane switched between renderers
+    # keeps what it had (ADR 050).
+    def prominent?
+      single_value? && !prominence.nil?
+    end
+
+    def boxed?
+      chart? && !height.nil?
+    end
+
+    def ring?
+      !single_value? && RINGS.include?(renderer)
+    end
+
+    # A part of a whole cannot be negative, and a ring of nothing draws
+    # nothing. Either way the pane is a table that says why, not a wrong
+    # picture (ADR 046).
+    def hole?
+      renderer == "doughnut"
+    end
+
+    def ringable?(result)
+      values = result.values.map(&:to_f)
+      values.none?(&:negative?) && values.sum.positive?
+    end
+
+    # The custom property a category at this position is drawn with.
+    def series_property(index)
+      index < SERIES ? "--janela-series-#{index + 1}" : "--janela-series-other"
+    end
+
+    # One entry per label, in result order, with the arc it covers. A zero is
+    # kept for the legend and has no arc. The filter is the one a click on
+    # that label toggles, so the slice and its legend row cannot disagree.
+    CENTRE = 50.0
+    OUTER = 48.0
+    INNER = 27.0
+
+    Slice = Struct.new(:label, :formatted, :property, :click, :selected, :fraction, :from, keyword_init: true) do
+      # The SVG path of this slice on a 100 by 100 canvas, from twelve o'clock
+      # clockwise, or nil when it covers nothing. One slice covering the whole
+      # circle is two half arcs, since an arc from a point to itself is not
+      # drawn. A doughnut's hole is a second sub-path, cut out by the
+      # stylesheet's even-odd fill rule.
+      def path(hole:)
+        return unless fraction.positive?
+        return whole(hole) if fraction >= 0.9999
+
+        large = fraction > 0.5 ? 1 : 0
+        outer_from, outer_to = point(OUTER, from), point(OUTER, from + fraction)
+        if hole
+          inner_from, inner_to = point(INNER, from), point(INNER, from + fraction)
+          "M #{outer_from} A #{OUTER} #{OUTER} 0 #{large} 1 #{outer_to} L #{inner_to} A #{INNER} #{INNER} 0 #{large} 0 #{inner_from} Z"
+        else
+          "M #{CENTRE} #{CENTRE} L #{outer_from} A #{OUTER} #{OUTER} 0 #{large} 1 #{outer_to} Z"
+        end
+      end
+
+      private
+        def whole(hole)
+          circle = ->(radius) { "M #{CENTRE} #{CENTRE - radius} A #{radius} #{radius} 0 1 1 #{CENTRE} #{CENTRE + radius} A #{radius} #{radius} 0 1 1 #{CENTRE} #{CENTRE - radius} Z" }
+          hole ? "#{circle.(OUTER)} #{circle.(INNER)}" : circle.(OUTER)
+        end
+
+        def point(radius, turns)
+          angle = turns * 2 * Math::PI - Math::PI / 2
+          format("%.3f %.3f", CENTRE + radius * Math.cos(angle), CENTRE + radius * Math.sin(angle))
+        end
+    end
+
+    def slices(result)
+      total = result.values.sum(&:to_f)
+      from = 0.0
+      result.each_with_index.map do |(label, measured), index|
+        fraction = measured.to_f / total
+        slice = Slice.new(label: label.to_s, formatted: format(measured), property: series_property(index),
+                          click: (click_data(label) if clickable?), selected: selected?(label), fraction: fraction, from: from)
+        from += fraction
+        slice
+      end
     end
 
     def turbo_frame_id
@@ -105,7 +220,48 @@ module Janela
       # selection, which this pane shows the alternatives to (ADR 040, 043).
       on = definition.narrow(on || model.all, default) if default.present?
       on = definition.narrow(on || model.all, fixed) if fixed.present?
-      definition.query(measure, by: dimension, where: applicable_filters, on: on, granularity: granularity, limit: limit)
+      primary = time? ? time_result(on) : definition.query(measure, by: dimension, where: applicable_filters, on: on, granularity: granularity, limit: limit)
+      @companion_columns = companions? ? fetch_companions(primary, on) : []
+      primary
+    end
+
+    # Only a table draws companion columns, and a stored pane is the record of
+    # a moment that holds none (ADR 051).
+    def companions?
+      renderer == "table" && !single_value? && !frozen? && companions.any?
+    end
+
+    # The columns beside the label, once a result has been read. Kept from the
+    # same read as the result, with the same scope and filters, the way a time
+    # pane keeps its buckets.
+    def companion_columns
+      @companion_columns || []
+    end
+
+    def dimension_header
+      dimension.to_s.humanize
+    end
+
+    def measure_header
+      measure.to_s.humanize
+    end
+
+    # The two filters a click on this label writes, for a time pane: the start
+    # of its bucket and the start of the next (ADR 045).
+    def range_for(label)
+      from, to = dimension_definition.bounds(@buckets.fetch(label.to_s), granularity)
+      { "#{ransack_name}_gteq" => from, "#{ransack_name}_lt" => to }
+    end
+
+    # The data attributes a table button or legend row carries: one key and
+    # value for a category, the pair of conditions for a bucket.
+    def click_data(label)
+      if time?
+        { janela__frame_filters_param: range_for(label).to_json }
+      else
+        key, value = filter_params(label)
+        key ? { janela__frame_key_param: key, janela__frame_value_param: value } : nil
+      end
     end
 
     # The Ransack key and value a click on this label should toggle. A null
@@ -116,7 +272,7 @@ module Janela
     # _eq link is still read, since a URL somebody already sent should not stop
     # working to suit us (ADR 024).
     def filter_params(label)
-      return [ nil, nil ] unless clickable?
+      return [ nil, nil ] unless clickable? && !time?
       return [ "#{ransack_name}_null", "1" ] if label.to_s == Dimension::NONE
 
       [ "#{ransack_name}_in", label.to_s ]
@@ -126,6 +282,7 @@ module Janela
     # to look up by label when a bar is clicked.
     def filters_for(labels)
       return {} unless clickable?
+      return labels.to_h { |label| [ label.to_s, range_for(label) ] } if time?
 
       labels.to_h { |label| [ label.to_s, filter_params(label) ] }
     end
@@ -137,6 +294,7 @@ module Janela
     # like any other label.
     def selected_values
       return [] unless clickable?
+      return selected_buckets if time?
 
       values = Array(filter("#{ransack_name}_in")) + Array(filter("#{ransack_name}_eq"))
       values = values.map(&:to_s)
@@ -161,8 +319,91 @@ module Janela
         dimension_definition.ransack_name
       end
 
+      # A time pane's series is read as buckets, not labels, and the buckets
+      # are kept: the labels alone cannot say what range a click covers.
+      def time_result(on)
+        series = definition.series(measure, by: dimension, where: applicable_filters, on: on, granularity: granularity)
+        @buckets = series.keys.to_h { |bucket| [ dimension_definition.label(bucket, granularity), bucket ] }
+        series.transform_keys { |bucket| dimension_definition.label(bucket, granularity) }
+      end
+
+      # The buckets that lie wholly inside the range the filters name. Janela
+      # writes both ends, so a range with one is somebody else's and selects
+      # nothing here. Read before the first result there are no buckets yet.
+      def selected_buckets
+        from, to = filter("#{ransack_name}_gteq"), filter("#{ransack_name}_lt")
+        return [] if from.blank? || to.blank? || @buckets.nil?
+
+        from, to = Time.zone.parse(from.to_s), Time.zone.parse(to.to_s)
+        return [] if from.nil? || to.nil?
+
+        @buckets.select { |_, bucket|
+          start, finish = dimension_definition.span(bucket, granularity)
+          start >= from && finish <= to
+        }.keys
+      end
+
+      def companions!(value)
+        return [] if value.blank?
+        raise BadRequest, "companions must be a list of measure and dimension names, got #{value.class}" unless value.is_a?(Array) && value.all? { |each| each.is_a?(String) || each.is_a?(Symbol) }
+
+        names = value.map(&:to_sym)
+        raise BadRequest, "a pane may carry at most #{MAX_COMPANIONS} companions, got #{names.size}" if names.size > MAX_COMPANIONS
+        raise BadRequest, "companions must each be named once, got #{names.map(&:inspect).join(', ')}" unless names == names.uniq
+
+        names.each { |name| companion!(name) }
+      end
+
+      # Only what the model declared, by the name it declared it under: no
+      # column, no expression, nothing that becomes SQL (ADR 025, ADR 051).
+      def companion!(name)
+        declared = definition.measures.keys + definition.dimensions.keys
+        raise BadRequest, "#{name.inspect} is not a declared measure or dimension of #{model}. Declared: #{declared.join(', ')}" unless declared.include?(name)
+        raise BadRequest, "#{name.inspect} is this pane's own #{name == measure ? 'measure' : 'dimension'}" if name == measure || name == dimension
+        return if definition.measures.key?(name)
+
+        fact = definition.dimensions.fetch(name)
+        raise BadRequest, "#{name.inspect} is a time dimension, and a bucket is not a fact about a label" if fact.time?
+        raise BadRequest, "#{name.inspect} is a dimension, which a time pane has no shared fact to show" if dimension && definition.dimension!(dimension).time?
+      end
+
+      # Ordering and the limit belong to the primary measure. The companions are
+      # fetched for the labels it chose, one grouped query for each measure and
+      # one for all the dimensions (ADR 051).
+      def fetch_companions(primary, on)
+        keys = time? ? nil : primary.keys
+        facts = companions.reject { |name| definition.measures.key?(name) }
+        shared = facts.any? ? definition.facts(facts, by: dimension, where: applicable_filters, on: on, keys: keys) : {}
+
+        companions.map do |name|
+          if definition.measures.key?(name)
+            values = definition.query(name, by: dimension, where: applicable_filters, on: on, granularity: granularity, keys: keys)
+            formatted = definition.measure!(name)
+            Companion.new(name: name, header: name.to_s.humanize, fact: false,
+                          cells: primary.keys.to_h { |label| [ label, formatted.format(values[label]) ] })
+          else
+            Companion.new(name: name, header: name.to_s.humanize, fact: true,
+                          cells: primary.keys.to_h { |label| [ label, shared.dig(label, name).to_s ] })
+          end
+        end
+      end
+
+      def prominence!(value)
+        step = Integer(value.to_s, exception: false)
+        raise BadRequest, "prominence must be a whole number from #{PROMINENCES.first} to #{PROMINENCES.last}, got #{value.inspect}" unless PROMINENCES.cover?(step)
+
+        step
+      end
+
+      def height!(value)
+        step = Integer(value.to_s, exception: false)
+        raise BadRequest, "height must be a whole number from #{HEIGHTS.first} to #{HEIGHTS.last}, got #{value.inspect}" unless HEIGHTS.cover?(step)
+
+        step
+      end
+
       def applicable_filters
-        return filters if single_value? || time?
+        return filters if single_value?
 
         filters.reject { |key, _| key.to_s.start_with?(ransack_name) }
       end

data/app/views/janela/panes/_form.html.erb

@@ -41,6 +41,31 @@
     <%= form.select :limit, Janela::Pane::OFFERED_LIMITS, include_blank: t("janela.panes.no_limit") %>
   </div>
 
+  <%# What may sit beside the label: this model's other measures and its
+      categorical dimensions. The pane's own choices are left out when they are
+      already made (ADR 051). %>
+  <%
+    companion_choices = {
+      t("janela.companions.measures") => definition.measures.keys.reject { |name| name.to_s == pane.measure }.map { |name| [ name.to_s.humanize, name ] },
+      t("janela.companions.dimensions") => definition.dimensions.values.reject { |each| each.time? || each.name.to_s == pane.dimension }.map { |each| [ each.name.to_s.humanize, each.name ] }
+    }
+  %>
+  <div class="janela-field">
+    <%= form.label :companions %>
+    <%= form.select :companions, companion_choices, {}, multiple: true %>
+    <span class="janela-hint"><%= t("janela.companions.hint") %></span>
+  </div>
+
+  <div class="janela-field">
+    <%= form.label :height %>
+    <%= form.select :height, Janela::Pane::HEIGHTS.map { |step| [ t("janela.heights.#{step}"), step ] }, include_blank: t("janela.heights.automatic") %>
+  </div>
+
+  <div class="janela-field">
+    <%= form.label :prominence %>
+    <%= form.select :prominence, Janela::Pane::PROMINENCES.map { |step| [ t("janela.prominences.#{step}"), step ] }, include_blank: t("janela.prominences.automatic") %>
+  </div>
+
   <div class="janela-field">
     <%= form.label :span %>
     <%= form.select :span, Janela::Pane::SPANS.to_a %>

data/app/views/janela/queries/_query.html.erb

@@ -1,16 +1,21 @@
 <%# One pane's content, without its turbo frame: the same markup whether the
     pane came from a URL, a row, or a frame rendered inline. %>
 <% if query.single_value? %>
-  <p class="janela-pane janela-value">
+  <%= tag.p class: [ "janela-pane", "janela-value", ("janela-prominence-#{query.prominence}" if query.prominent?) ] do %>
     <span class="janela-value-label"><%= query.title %></span>
     <strong class="janela-value-number"><%= query.format(result || 0) %></strong>
-  </p>
+  <% end %>
 <% elsif result.empty? %>
   <p class="janela-pane janela-empty"><%= query.title %>: no data</p>
+<% elsif query.ring? && query.ringable?(result) %>
+  <%= render "janela/queries/ring", query: query, result: result %>
 <% elsif query.chart? %>
   <% title_id = "#{query.turbo_frame_id}-title" %>
   <figure class="janela-pane">
     <figcaption class="janela-chart-title" id="<%= title_id %>"><%= query.title %></figcaption>
+    <%# A height puts the canvas in a box of fixed size for the chart to fill;
+        with none there is no box and the chart is what it always was (ADR 047). %>
+    <% canvas = capture do %>
     <canvas class="janela-chart"
             data-controller="janela--chart"
             data-action="janela--chart:toggle->janela--frame#toggle"
@@ -21,31 +26,51 @@
             data-janela--chart-values-value="<%= result.values.map(&:to_f).to_json %>"
             data-janela--chart-formatted-value="<%= result.values.map { |measured| query.format(measured) }.to_json %>"
             data-janela--chart-filters-value="<%= query.filters_for(result.keys).to_json %>"
+            <%= tag.attributes(aria: { description: (t("janela.time.click_hint") if query.time? && query.clickable?) }) %>
+            <%= "data-janela--chart-fixed-height-value=true".html_safe if query.boxed? %>
             role="img" aria-labelledby="<%= title_id %>"></canvas>
+    <% end %>
+    <%= query.boxed? ? tag.div(canvas, class: "janela-chart-box janela-h-#{query.height}") : canvas %>
   </figure>
 <% else %>
-  <table class="janela-pane">
+  <%= tag.table class: "janela-pane", aria: { description: (t("janela.time.click_hint") if query.time? && query.clickable?) } do %>
     <caption><%= query.title %></caption>
+    <%# A header row only when there are companions to name: two columns read
+        without one, and a table with none is what it always was (ADR 051). %>
+    <% if query.companion_columns.any? %>
+      <thead>
+        <tr>
+          <th scope="col"><%= query.dimension_header %></th>
+          <th scope="col"><%= query.measure_header %></th>
+          <% query.companion_columns.each do |column| %>
+            <%= tag.th column.header, scope: "col", class: ("janela-fact" if column.fact) %>
+          <% end %>
+        </tr>
+      </thead>
+    <% end %>
     <tbody>
       <% result.each do |label, measured| %>
-        <% key, value = query.filter_params(label) %>
+        <% click = query.click_data(label) if query.clickable? %>
         <tr>
           <td>
-            <% if key %>
-              <button type="button"
-                      aria-pressed="<%= query.selected?(label) %>"
-                      data-action="janela--frame#toggle"
-                      data-janela--frame-key-param="<%= key %>"
-                      data-janela--frame-value-param="<%= value %>">
-                <%= label %>
-              </button>
+            <% if click %>
+              <%= tag.button label, type: "button", aria: { pressed: query.selected?(label) },
+                    data: { action: "janela--frame#toggle" }.merge(click) %>
             <% else %>
               <span><%= label %></span>
             <% end %>
           </td>
           <td><%= query.format(measured) %></td>
+          <% query.companion_columns.each do |column| %>
+            <%= tag.td column.cells[label], class: ("janela-fact" if column.fact) %>
+          <% end %>
         </tr>
       <% end %>
     </tbody>
-  </table>
+  <% end %>
+  <%# A ring cannot draw a negative part or a total of nothing, so it says it
+      is a table rather than drawing something wrong (ADR 046). %>
+  <% if query.ring? %>
+    <p class="janela-muted"><%= t("janela.rings.not_drawable") %></p>
+  <% end %>
 <% end %>

data/app/views/janela/queries/_ring.html.erb

@@ -0,0 +1,41 @@
+<%# A doughnut or a pie, drawn here rather than on a canvas so it is in the
+    HTML before any JavaScript runs, prints, and can be read and operated by
+    a keyboard through the legend (ADR 046, ADR 026). A slice and its legend
+    row toggle the same filter, and the legend is the control a keyboard and a
+    screen reader use, so the slices are not offered to them twice. %>
+<% title_id = "#{query.turbo_frame_id}-title" %>
+<% slices = query.slices(result) %>
+<% selecting = slices.any?(&:selected) %>
+<figure class="janela-pane janela-ring">
+  <figcaption class="janela-chart-title" id="<%= title_id %>"><%= query.title %></figcaption>
+  <svg class="janela-ring-svg" viewBox="0 0 100 100" role="img" aria-labelledby="<%= title_id %>"
+       data-hole="<%= query.hole? %>">
+    <% slices.each do |slice| %>
+      <% path = slice.path(hole: query.hole?) %>
+      <% next unless path %>
+      <%= tag.path d: path, class: [ "janela-ring-slice", ("janela-dim" if selecting && !slice.selected) ],
+            style: "fill: var(#{slice.property})",
+            data: (slice.click ? { action: "click->janela--frame#toggle" }.merge(slice.click) : {}) do %>
+        <title><%= slice.label %>: <%= slice.formatted %></title>
+      <% end %>
+    <% end %>
+  </svg>
+  <table class="janela-legend">
+    <tbody>
+      <% slices.each do |slice| %>
+        <tr>
+          <td>
+            <span class="janela-swatch" style="background: var(<%= slice.property %>)" aria-hidden="true"></span>
+            <% if slice.click %>
+              <%= tag.button slice.label, type: "button", aria: { pressed: slice.selected },
+                    data: { action: "janela--frame#toggle" }.merge(slice.click) %>
+            <% else %>
+              <span><%= slice.label %></span>
+            <% end %>
+          </td>
+          <td><%= slice.formatted %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</figure>

data/config/locales/en.yml

@@ -20,6 +20,9 @@ en:
         granularity: Granularity
         limit: Rows
         span: Width
+        height: Height
+        prominence: Prominence
+        companions: Beside the label
         title: Title
   janela:
     actions:
@@ -64,7 +67,29 @@ en:
       text: Text
       link_hint: "A path on this site, such as /orders. Makes the heading a link."
       title_placeholder: Janela writes one if you leave this blank
+    companions:
+      measures: Measures
+      dimensions: Dimensions
+      hint: Up to three, drawn as columns in a table. A dimension shows a value only where every row of its group shares one.
+    prominences:
+      automatic: Automatic
+      "1": Footnote
+      "2": Normal
+      "3": Hero
+    heights:
+      automatic: Automatic
+      "1": Very short
+      "2": Short
+      "3": Medium
+      "4": Tall
+      "5": Very tall
     renderers:
       bar: Bar chart
+      doughnut: Doughnut chart
       line: Line chart
+      pie: Pie chart
       table: Table
+    time:
+      click_hint: Choose a period to filter the other panes to it. Ctrl or Cmd does not add a second period.
+    rings:
+      not_drawable: A ring cannot show a negative value or a total of nothing, so this is drawn as a table.

data/db/migrate/20260930000001_add_height_to_janela_panes.rb

@@ -0,0 +1,7 @@
+class AddHeightToJanelaPanes < ActiveRecord::Migration[8.0]
+  def change
+    # How tall a bar or line chart is drawn, one of five steps (ADR 047). Null
+    # is what every existing pane is: unset, and drawn exactly as before.
+    add_column :janela_panes, :height, :integer
+  end
+end

data/db/migrate/20260930000002_add_prominence_to_janela_panes.rb

@@ -0,0 +1,7 @@
+class AddProminenceToJanelaPanes < ActiveRecord::Migration[8.0]
+  def change
+    # How prominent a single value is drawn, one of three steps (ADR 050).
+    # Null is what every existing pane is: unset, and drawn exactly as before.
+    add_column :janela_panes, :prominence, :integer
+  end
+end

data/db/migrate/20260930000003_add_companions_to_janela_panes.rb

@@ -0,0 +1,8 @@
+class AddCompanionsToJanelaPanes < ActiveRecord::Migration[8.0]
+  def change
+    # Measures and dimensions a table pane draws as columns beside its label
+    # (ADR 051), by the names the model declared them under. Null is what
+    # every existing pane is: none, and drawn exactly as before.
+    add_column :janela_panes, :companions, :json
+  end
+end

data/docs/decisions/006-time-dimensions-with-groupdate.md

@@ -1,6 +1,6 @@
 ---
 Date: 2026-09-15
-Status: Accepted
+Status: Accepted (the click source paragraph is superseded by ADR 045)
 Related: ADR 002, ADR 005
 Triggers:
   - grouping a measure by a date or time column