janela 0.14.0 → 0.16.0

data/app/helpers/janela/frames_helper.rb

@@ -34,26 +34,36 @@ module Janela
     # 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, value_labels: nil, companions: nil, id: nil)
-      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit, height: height, prominence: prominence,
-                value_labels: (1 if value_labels), companions: companions.presence,
+    #
+    # cumulative: is a running total across a time pane's buckets, and series:
+    # a list of further measures drawn beside it (ADR 062). Both travel in the
+    # URL for the same reason; a set cumulative is also part of the frame's
+    # id, since a measure to date and per period are two different answers.
+    # ignore_unknown_filters: drops the reader's filters this pane's model cannot
+    # apply rather than refusing them, for a pane beside panes over another
+    # model (ADR 063).
+    def janela_pane(model, measure, by: nil, as: :table, granularity: nil, limit: nil, sort: nil, height: nil, prominence: nil, value_labels: nil, companions: nil, cumulative: nil, series: nil, ignore_unknown_filters: nil, id: nil)
+      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit, sort: sort, height: height, prominence: prominence,
+                value_labels: (1 if value_labels), companions: companions.presence, cumulative: janela_cumulative_param(cumulative), series: janela_series_params(series),
+                ignore_unknown_filters: (1 if ignore_unknown_filters),
                 where: @janela_fixed_filters.presence }.compact
       base = janela_routes.pane_path(model.model_name.route_key, measure, by, **query)
 
-      turbo_frame_tag id || Query.turbo_frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit),
+      turbo_frame_tag id || Query.turbo_frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit, sort: sort, cumulative: cumulative, series: series),
         src: janela_with_page_filters(base),
         loading: :lazy,
         data: { janela__frame_target: "pane", janela_src: base }
     end
 
     # 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, height: nil, prominence: nil, value_labels: nil, companions: nil)
-      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit, height: height,
-                prominence: prominence, value_labels: (1 if value_labels), companions: companions.presence }.compact
+    # not part of the live frame's filter state (ADR 009). A snapshot holds
+    # no series, as it holds no companions, so it takes none (ADR 062).
+    def janela_snapshot_pane(snapshot, model, measure, by: nil, as: :table, granularity: nil, limit: nil, sort: nil, height: nil, prominence: nil, value_labels: nil, companions: nil, cumulative: nil)
+      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit, sort: sort, height: height,
+                prominence: prominence, value_labels: (1 if value_labels), companions: companions.presence, cumulative: janela_cumulative_param(cumulative) }.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),
+      turbo_frame_tag Query.turbo_frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit, sort: sort, cumulative: cumulative, snapshot: snapshot),
         src: src, loading: :lazy
     end
 
@@ -74,6 +84,24 @@ module Janela
     end
 
     private
+      # Read the way the server reads the flag, so "0" and "false" are no in
+      # the URL and in the frame's id alike.
+      def janela_cumulative_param(cumulative)
+        1 if Query.flag!("cumulative", cumulative)
+      end
+
+      # Each series led by its measure, because Rack opens a new hash in
+      # series[][...] where a key repeats and otherwise adds to the last one,
+      # and to_query keeps the order it is given inside a [] (ADR 062).
+      def janela_series_params(series)
+        return if series.blank?
+
+        series.map do |each|
+          given = each.to_h.symbolize_keys
+          { measure: given[:measure] }.merge(given.except(:measure)).compact
+        end
+      end
+
       # Wired once per frame, so a host asks a pane to go to a different query
       # by dispatching an event from anywhere inside rather than by reaching
       # for the controller itself (ADR 030).

data/app/models/janela/pane.rb

@@ -14,6 +14,10 @@ module Janela
     # How prominent a single value is drawn (ADR 050).
     PROMINENCES = Query::PROMINENCES
     LIMITS = (1..1000).freeze
+
+    # How a category pane is ordered (ADR 055). Nil is the default, largest
+    # first by the measure.
+    SORTS = Definition::SORTS
     # 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.
     OFFERED_LIMITS = [ 5, 10, 20, 50, 100 ].freeze
@@ -38,10 +42,15 @@ module Janela
     validates :kind, inclusion: { in: KINDS }
     validates :span, inclusion: { in: SPANS }
     validates :limit, inclusion: { in: LIMITS }, allow_nil: true
+    validates :sort, inclusion: { in: SORTS }, allow_nil: true
     validates :height, inclusion: { in: HEIGHTS }, allow_nil: true
     validates :prominence, inclusion: { in: PROMINENCES }, allow_nil: true
+    # A form sends an empty string for "Largest first", which is unset.
+    normalizes :sort, with: ->(value) { value.presence }
     before_validation :normalise_companions
     validate :companions_are_declared
+    before_validation :normalise_series
+    validate :series_are_declared
     validates :measure, presence: true, if: :query?
     validate :declared_by_a_janela_block, if: :query?
     validate :holds_no_query, unless: :query?
@@ -84,7 +93,8 @@ 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, height: height, prominence: prominence, value_labels: value_labels, companions: companions, filters: filters, fixed: fixed,
+                renderer: renderer, granularity: granularity, limit: limit, sort: sort, height: height, prominence: prominence, value_labels: value_labels, companions: companions,
+                cumulative: cumulative, series: series, ignore_unknown_filters: ignore_unknown_filters, filters: filters, fixed: fixed,
                 default: frame.default_for(definition.model), title: title)
     end
 
@@ -138,6 +148,27 @@ module Janela
         nil # an unknown model is reported by its own validation
       end
 
+      # The form sends a blank slot beyond the series it holds, and a series
+      # with no measure is no series. An empty list is nothing rather than [].
+      def normalise_series
+        self.series = Array(series).map { |each| each.to_h.stringify_keys.transform_values(&:to_s).reject { |_, value| value.blank? } }
+                                   .reject { |each| each["measure"].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 062). A running total on a pane
+      # that is not over time is refused the same way, by the query.
+      def series_are_declared
+        return if (series.blank? && !cumulative) || !query? || measure.blank? || Query::RENDERERS.exclude?(renderer.to_s)
+
+        Query.new(definition: definition, measure: measure.to_sym, dimension: dimension.presence&.to_sym,
+                  renderer: renderer, cumulative: cumulative, series: series)
+      rescue Janela::BadRequest => error
+        errors.add(error.message.start_with?("cumulative") ? :cumulative : :series, error.message)
+      rescue Janela::Error
+        nil # an unknown model or dimension is reported by its own validation
+      end
+
       def panes_above
         frame.panes.where(position: ...position).order(:position)
       end
@@ -168,7 +199,7 @@ module Janela
       # A row is one thing or the other, so the database never holds half a
       # query that nothing will run.
       def holds_no_query
-        %i[model measure dimension granularity].each do |column|
+        %i[model measure dimension granularity cumulative series].each do |column|
           errors.add(column, "belongs to a query pane, not a #{kind} one") if self[column].present?
         end
       end

data/app/models/janela/query.rb

@@ -33,17 +33,64 @@ module Janela
     # 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, :value_labels, :companions, :filters, :fixed, :default, :snapshot
+    # A time pane may carry up to three more series, each a measure over a
+    # time dimension of the same model, drawn as a line or bars on the left
+    # axis or a right one (ADR 062). Bounded as companions are, since each is
+    # a query. The keys are the words janela_pane takes, so a series reads the
+    # same in a row, in the helper and in the URL.
+    MAX_SERIES = 3
+    AXES = %w[left right].freeze
+    SERIES_KEYS = %w[measure by cumulative as axis title].freeze
+    # A series is joined to the pane's buckets one step at a time, so a column
+    # with a stray year 1900 would otherwise build a hundred thousand of them.
+    MAX_BUCKETS = 10_000
+    Series = Struct.new(:measure, :dimension, :cumulative, :renderer, :axis, :title, :values, keyword_init: true)
+
+    attr_reader :definition, :measure, :dimension, :renderer, :limit, :sort, :height, :prominence, :value_labels, :companions, :cumulative, :series, :ignore_unknown_filters, :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.
-    def self.turbo_frame_id(model:, measure:, by: nil, as: :table, granularity: nil, limit: nil, snapshot: nil)
+    # A measure to date and the same measure per period are two answers that
+    # may share a page, so a set cumulative is part of the id (ADR 062, as a
+    # sort is in ADR 055). Two panes that differ only in their series are two
+    # frames too, and a series is a hash, so it joins the id as a short digest
+    # of what was given.
+    def self.turbo_frame_id(model:, measure:, by: nil, as: :table, granularity: nil, limit: nil, sort: nil, cumulative: nil, series: nil, snapshot: nil)
       parts = [ "janela", ("snapshot_#{snapshot.id}" if snapshot), model.model_name.route_key, measure, by,
-                (granularity if by), (as unless by.nil?), ("top#{limit}" if by && limit) ]
+                (granularity if by), (as unless by.nil?), ("top#{limit}" if by && limit),
+                (sort if by && sort.present? && sort.to_s != "desc"), ("cumulative" if by && flag!("cumulative", cumulative)),
+                (series_digest(series) if by) ]
       parts.compact.join("_")
     end
 
-    def initialize(definition:, measure:, dimension: nil, renderer: "table", granularity: nil, limit: nil, height: nil, prominence: nil, value_labels: nil, companions: nil, filters: {}, fixed: {}, default: {}, snapshot: nil, title: nil)
+    # The same words in any spelling a host, a URL or a row gives them: symbol
+    # or string keys, true or "1", a blank left out. Nil when there are none,
+    # so a pane without series keeps the id it always had.
+    def self.series_digest(series)
+      given = Array(series).filter_map do |each|
+        next unless each.respond_to?(:to_h)
+
+        words = each.to_h.to_h { |key, value| [ key.to_s, value.to_s ] }.reject { |_, value| value.blank? }
+        words["cumulative"] = "1" if words.key?("cumulative") && flag!("cumulative", words["cumulative"])
+        words.delete("cumulative") unless words["cumulative"] == "1"
+        words.sort.to_h
+      end
+      return if given.empty?
+
+      "s#{Digest::SHA1.hexdigest(given.to_json)[0, 8]}"
+    end
+
+    # A yes or a no from a URL or a form, with unset the same as no. Anything
+    # else is refused rather than read as one of them.
+    def self.flag!(name, value)
+      case value.to_s
+      when "", "0", "false" then false
+      when "1", "true" then true
+      else raise BadRequest, "#{name} must be 1 or 0, got #{value.inspect}"
+      end
+    end
+
+    def initialize(definition:, measure:, dimension: nil, renderer: "table", granularity: nil, limit: nil, sort: nil, height: nil, prominence: nil, value_labels: nil, companions: nil, cumulative: nil, series: nil, ignore_unknown_filters: nil, filters: {}, fixed: {}, default: {}, snapshot: nil, title: nil)
       @definition = definition
       @title = title
       @measure = measure
@@ -57,10 +104,17 @@ 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?
+      # Unset and desc are the same pane, and stay the same id and the same
+      # snapshot key (ADR 055).
+      chosen = definition.sort!(sort)
+      @sort = chosen unless chosen == "desc"
       @height = height!(height) if height.present?
       @prominence = prominence!(prominence) if prominence.present?
-      @value_labels = value_labels!(value_labels)
+      @value_labels = flag!("value_labels", value_labels)
+      @ignore_unknown_filters = flag!("ignore_unknown_filters", ignore_unknown_filters)
       @companions = companions!(companions)
+      @cumulative = cumulative!(cumulative)
+      @series = series!(series)
     end
 
     def model
@@ -121,11 +175,11 @@ module Janela
       single_value? && !prominence.nil?
     end
 
-    # Only a bar has a bar to put a value on. A line, a ring, a table and a
-    # single value ignore the flag, so a pane switched between renderers keeps
-    # it (ADR 054).
+    # A bar has a bar to put a value on, and a line has an end to write its
+    # latest value at (ADR 054, ADR 062). A ring, a table and a single value
+    # ignore the flag, so a pane switched between renderers keeps it.
     def labelled?
-      value_labels && chart? && renderer == "bar"
+      value_labels && chart?
     end
 
     def boxed?
@@ -206,7 +260,7 @@ module Janela
 
     def turbo_frame_id
       self.class.turbo_frame_id(model: model, measure: measure, by: dimension, as: renderer,
-                          granularity: @granularity, limit: limit, snapshot: snapshot)
+                          granularity: @granularity, limit: limit, sort: sort, cumulative: cumulative, series: @series_given, snapshot: snapshot)
     end
 
     # A pane row may carry its own title, which is the first analyst authored
@@ -217,20 +271,81 @@ module Janela
       base = if single_value?
         measure.to_s.humanize
       else
-        by = "#{measure.to_s.humanize} by #{dimension.to_s.humanize}"
+        by = "#{series_label} by #{dimension.to_s.humanize}"
         time? ? "#{by} per #{granularity}" : by
       end
       frozen? ? "#{base} as of #{snapshot.taken_at.strftime('%-d %b %Y')}" : base
     end
 
+    # What a series is called in a legend and at the head of its column: its
+    # title if it has one, else the measure's name, then the dimension's when
+    # it is not the pane's own, then "to date" when it is a running total. The
+    # pane's own series is named by the same rule, so the same measure to date
+    # and per period never read the same (ADR 062).
+    def series_label(each = nil)
+      return each.title if each&.title.present?
+
+      label = (each ? each.measure : measure).to_s.humanize
+      label = "#{label} by #{each.dimension.to_s.humanize}" if each && each.dimension != dimension
+      (each ? each.cumulative : cumulative) ? I18n.t("janela.series.to_date", label: label) : label
+    end
+
+    # Series are drawn by a bar, a line and a table. A ring ignores them, as it
+    # ignores a height, and a stored pane holds none (ADR 062, ADR 051).
+    def series?
+      series.any? && !frozen? && !ring?
+    end
+
+    # The series after the pane's own, once a result has been read, each with
+    # its values by label over the same buckets.
+    def drawn_series
+      series? ? series : []
+    end
+
+    # A series' numbers read the way its own measure formats them (ADR 020).
+    def series_format(each, value)
+      definition.measure!(each.measure).format(value)
+    end
+
+    def series_tick_format(each)
+      declared = definition.measure!(each.measure)
+      { prefix: declared.prefix.to_s, suffix: declared.suffix.to_s, ratio: declared.ratio? }
+    end
+
+    # What the chart controller needs for each further series: the values and
+    # the formatted strings in the primary's label order, and how to draw it.
+    def chart_series(result)
+      drawn_series.map do |each|
+        { label: series_label(each), type: each.renderer, axis: each.axis,
+          values: result.keys.map { |label| each.values[label]&.to_f },
+          tick_format: series_tick_format(each),
+          formatted: result.keys.map { |label| series_format(each, each.values[label]) } }
+      end
+    end
+
+    # A right axis exists when a series asks for it, and then both are titled
+    # with the names of the series on them: an untitled second scale is how
+    # two scales mislead (ADR 062). Nil without one, so a chart with every
+    # series on the left is drawn as it always was.
+    def axis_titles
+      right = drawn_series.select { |each| each.axis == "right" }
+      return if right.empty?
+
+      left = [ series_label ] + drawn_series.reject { |each| each.axis == "right" }.map { |each| series_label(each) }
+      { left: left.join(", "), right: right.map { |each| series_label(each) }.join(", ") }
+    end
+
     # What identifies this pane's data inside a snapshot.
     def lookup_key
       { "model" => model.model_name.route_key, "measure" => measure.to_s, "dimension" => dimension&.to_s,
-        "granularity" => granularity&.to_s, "limit" => limit }
+        "granularity" => granularity&.to_s, "limit" => limit }.tap { |key| key["sort"] = sort if sort }
     end
 
     def result(on: nil)
-      return snapshot.stored_result(self) if frozen?
+      # A snapshot keeps per-bucket numbers, and a running total of them is
+      # summed on read as a live one is, so what is stored does not change
+      # (ADR 062, ADR 009).
+      return accumulated(snapshot.stored_result(self), cumulative) if frozen?
 
       # Default, then fixed, then the reader's: a frame's own permanent
       # filter narrows first, a host's per-record filter narrows again, and
@@ -238,7 +353,7 @@ 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?
-      primary = time? ? time_result(on) : 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, sort: sort)
       @companion_columns = companions? ? fetch_companions(primary, on) : []
       primary
     end
@@ -261,7 +376,7 @@ module Janela
     end
 
     def measure_header
-      measure.to_s.humanize
+      series_label
     end
 
     # The two filters a click on this label writes, for a time pane: the start
@@ -339,10 +454,62 @@ module Janela
 
       # 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.
+      # Further series are read the same way, each by its own dimension, and
+      # every bucket any of them has becomes one shared x axis, zero where a
+      # series has no row (ADR 062).
       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) }
+        read = definition.series(measure, by: dimension, where: applicable_filters, on: on, granularity: granularity)
+        if series?
+          extra = series.map { |each| [ each, definition.series(each.measure, by: each.dimension, where: applicable_filters, on: on, granularity: granularity) ] }
+          buckets = spanning((read.keys + extra.flat_map { |_, result| result.keys }).map(&:in_time_zone))
+          read = aligned(read, buckets, measure)
+          extra.each { |each, result| each.values = labelled(accumulated(aligned(result, buckets, each.measure), each.cumulative)) }
+        end
+        @buckets = read.keys.to_h { |bucket| [ dimension_definition.label(bucket, granularity), bucket ] }
+        labelled(accumulated(read, cumulative))
+      end
+
+      def labelled(result)
+        result.transform_keys { |bucket| dimension_definition.label(bucket, granularity) }
+      end
+
+      # Every bucket from the first any series has to the last, one step
+      # apart. Groupdate fills the gaps inside each series' own range, and two
+      # series whose ranges do not meet would otherwise leave a hole between
+      # them on the shared axis.
+      def spanning(instants)
+        return [] if instants.empty?
+
+        step = Dimension::STEPS.fetch(granularity)
+        buckets = []
+        bucket = instants.min
+        last = instants.max
+        while bucket <= last
+          raise BadRequest, "these series span more than #{MAX_BUCKETS} #{granularity} buckets, so they cannot share one axis" if buckets.size >= MAX_BUCKETS
+
+          buckets << bucket
+          bucket += step
+        end
+        buckets
+      end
+
+      # Groupdate keys a date column's buckets as Date and a timestamp's as
+      # Time, so two series are joined through the instant each bucket starts.
+      # A bucket with no row is zero for a count or a sum and a gap for an
+      # average, a minimum, a maximum or a ratio, which have no value there.
+      def aligned(result, buckets, name)
+        by_instant = result.transform_keys(&:in_time_zone)
+        empty = definition.measure!(name).additive? ? 0 : nil
+        buckets.to_h { |bucket| [ bucket, by_instant.fetch(bucket, empty) ] }
+      end
+
+      # A running total, summed after the read so the query, the buckets and
+      # the click are what they always were (ADR 062).
+      def accumulated(result, running)
+        return result unless running
+
+        total = 0
+        result.transform_values { |value| total += (value || 0) }
       end
 
       # The buckets that lie wholly inside the range the filters name. Janela
@@ -408,12 +575,65 @@ module Janela
 
       # A yes or a no from a URL or a form, with unset the same as no. Anything
       # else is refused rather than read as one of them.
-      def value_labels!(value)
-        case value.to_s
-        when "", "0", "false" then false
-        when "1", "true" then true
-        else raise BadRequest, "value_labels must be 1 or 0, got #{value.inspect}"
-        end
+      def flag!(name, value)
+        self.class.flag!(name, value)
+      end
+
+      # A running total is across buckets, so only a time pane has one. On a
+      # category pane or a single value it is refused with its reason rather
+      # than ignored: a row whose dimension is changed to a category is told on
+      # the form, not left drawing something else (ADR 062).
+      def cumulative!(value)
+        running = flag!("cumulative", value)
+        raise BadRequest, "cumulative applies to a time dimension, and this pane is not over one" if running && !time?
+        raise BadRequest, unsummable(measure) if running && !definition.measure!(measure).additive?
+
+        running
+      end
+
+      def unsummable(name)
+        "cumulative applies to a measure that adds up, a count or a sum, and #{name.inspect} is " \
+          "#{definition.measure!(name.to_sym).aggregate == :ratio ? 'a ratio' : "an #{definition.measure!(name.to_sym).aggregate}"}"
+      end
+
+      def series!(value)
+        @series_given = value
+        return [] if value.blank?
+        raise BadRequest, "series must be a list of hashes, got #{value.class}" unless value.is_a?(Array) && value.all?(Hash)
+        raise BadRequest, "series apply to a time dimension, and this pane is not over one" unless time?
+        raise BadRequest, "a pane may carry at most #{MAX_SERIES} series, got #{value.size}" if value.size > MAX_SERIES
+
+        built = value.map { |each| series_from(each.stringify_keys) }
+        named = built.map { |each| [ each.measure, each.dimension, each.cumulative ] }
+        raise BadRequest, "a series is given twice: the same measure, dimension and cumulative" unless named == named.uniq
+
+        built
+      end
+
+      # Only what the model declared, by the name it declared it under, as a
+      # companion is (ADR 025, ADR 051). What is left unsaid is the pane's own.
+      def series_from(given)
+        unknown = given.keys - SERIES_KEYS
+        raise BadRequest, "a series takes #{SERIES_KEYS.join(', ')}, not #{unknown.join(', ')}" if unknown.any?
+
+        name = given["measure"].to_s
+        raise BadRequest, "a series needs a measure" if name.blank?
+        raise BadRequest, "#{name.inspect} is not a measure of #{model}. Declared: #{definition.measures.keys.join(', ')}" unless definition.measures.key?(name.to_sym)
+
+        by = given["by"].present? ? given["by"].to_s.to_sym : dimension
+        declared = definition.dimensions.fetch(by) { raise BadRequest, "#{by.inspect} is not a dimension of #{model}" }
+        raise BadRequest, "#{by.inspect} is not a time dimension, and a series shares the pane's buckets" unless declared.time?
+
+        drawn = given["as"].present? ? given["as"].to_s : (CANVAS.include?(renderer) ? renderer : "line")
+        raise BadRequest, "a series is drawn as #{CANVAS.join(' or ')}, not #{drawn.inspect}" unless CANVAS.include?(drawn)
+        axis = given["axis"].present? ? given["axis"].to_s : "left"
+        raise BadRequest, "a series' axis is #{AXES.join(' or ')}, not #{axis.inspect}" unless AXES.include?(axis)
+
+        running = flag!("cumulative", given["cumulative"])
+        raise BadRequest, unsummable(name) if running && !definition.measures.fetch(name.to_sym).additive?
+
+        Series.new(measure: name.to_sym, dimension: by, cumulative: running,
+                   renderer: drawn, axis: axis, title: given["title"].presence&.to_s)
       end
 
       def prominence!(value)
@@ -430,10 +650,15 @@ module Janela
         step
       end
 
+      # The reader's filters this pane applies: every one but its own
+      # dimension's, which is the cross-filtering rule, and when the pane asks
+      # for it, only those its model can apply (ADR 063). A host's fixed and a
+      # frame's default filter are not read here and are refused when wrong.
       def applicable_filters
-        return filters if single_value?
-
-        filters.reject { |key, _| key.to_s.start_with?(ransack_name) }
+        @applicable_filters ||= begin
+          given = ignore_unknown_filters ? definition.applicable(filters) : filters
+          single_value? ? given : given.reject { |key, _| key.to_s.start_with?(ransack_name) }
+        end
       end
   end
 end

data/app/models/janela/snapshot.rb

@@ -40,9 +40,9 @@ module Janela
         @panes = []
       end
 
-      def pane(model, measure, by: nil, granularity: nil, limit: nil, on: nil)
+      def pane(model, measure, by: nil, granularity: nil, limit: nil, sort: nil, on: nil)
         query = Query.new(definition: model.janela, measure: measure, dimension: by,
-                          granularity: granularity, limit: limit, filters: filters)
+                          granularity: granularity, limit: limit, sort: sort, filters: filters)
         panes << query.lookup_key.merge("result" => plain(query.result(on: on)))
       end
 

data/app/views/janela/frames/show.html.erb

@@ -5,5 +5,5 @@
   <%= link_to t("janela.actions.edit"), edit_frame_path(@frame) %>
 </p>
 
-<%# charts: false because this page loads no chart runtime (ADR 018). %>
-<%= janela_frame @frame, charts: false %>
+<%# A table unless the host has said its layout draws charts, because this page cannot see that (ADR 018, ADR 059). %>
+<%= janela_frame @frame, charts: Janela.charts_on_own_pages %>

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

@@ -41,6 +41,13 @@
     <%= form.select :limit, Janela::Pane::OFFERED_LIMITS, include_blank: t("janela.panes.no_limit") %>
   </div>
 
+  <%# Blank is largest first, so desc is not offered a second time. %>
+  <div class="janela-field">
+    <%= form.label :sort %>
+    <%= form.select :sort, (Janela.sorts - %w[desc]).map { |value| [ t("janela.sorts.#{value}"), value ] }, include_blank: t("janela.sorts.desc") %>
+    <span class="janela-hint"><%= t("janela.sorts.hint") %></span>
+  </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). %>
@@ -56,6 +63,46 @@
     <span class="janela-hint"><%= t("janela.companions.hint") %></span>
   </div>
 
+  <%# A running total and further series apply to a time pane (ADR 062). The
+      series slots are plain selects, one blank beyond those the row holds, up
+      to the most a pane may carry, since these pages have no JavaScript to
+      add a row on demand (ADR 018). Each slot leads with its measure, which
+      is how the browser's params keep one slot's fields together. %>
+  <% if granularity_applies %>
+    <div class="janela-field">
+      <%= form.check_box :cumulative %>
+      <%= form.label :cumulative %>
+      <span class="janela-hint"><%= t("janela.series.cumulative_hint") %></span>
+    </div>
+
+    <%
+      slots = Array(pane.series).first(Janela::Query::MAX_SERIES)
+      slots << {} if slots.size < Janela::Query::MAX_SERIES
+      time_choices = definition.dimensions.values.select(&:time?).map { |dimension| [ dimension.name.to_s.humanize, dimension.name ] }
+    %>
+    <fieldset class="janela-field janela-series">
+      <legend><%= Janela::Pane.human_attribute_name(:series) %></legend>
+      <span class="janela-hint"><%= t("janela.series.hint", count: Janela::Query::MAX_SERIES) %></span>
+      <% slots.each_with_index do |slot, index| %>
+        <% slot = slot.to_h.stringify_keys %>
+        <div class="janela-series-slot">
+          <%= label_tag "pane_series_#{index}_measure", t("janela.series.measure") %>
+          <%= select_tag "pane[series][][measure]", options_for_select(measures, slot["measure"]), include_blank: t("janela.series.none"), id: "pane_series_#{index}_measure" %>
+          <%= label_tag "pane_series_#{index}_by", t("janela.series.by") %>
+          <%= select_tag "pane[series][][by]", options_for_select(time_choices, slot["by"]), include_blank: t("janela.series.same_as_pane"), id: "pane_series_#{index}_by" %>
+          <%= check_box_tag "pane[series][][cumulative]", "1", ActiveModel::Type::Boolean.new.cast(slot["cumulative"]), id: "pane_series_#{index}_cumulative" %>
+          <%= label_tag "pane_series_#{index}_cumulative", Janela::Pane.human_attribute_name(:cumulative) %>
+          <%= label_tag "pane_series_#{index}_as", t("janela.series.as") %>
+          <%= select_tag "pane[series][][as]", options_for_select(Janela::Query::CANVAS.map { |each| [ t("janela.renderers.#{each}"), each ] }, slot["as"]), include_blank: t("janela.series.same_as_pane"), id: "pane_series_#{index}_as" %>
+          <%= label_tag "pane_series_#{index}_axis", t("janela.series.axis") %>
+          <%= select_tag "pane[series][][axis]", options_for_select(Janela::Query::AXES.map { |each| [ t("janela.series.axes.#{each}"), each ] }, slot["axis"]), id: "pane_series_#{index}_axis" %>
+          <%= label_tag "pane_series_#{index}_title", Janela::Pane.human_attribute_name(:title) %>
+          <%= text_field_tag "pane[series][][title]", slot["title"], id: "pane_series_#{index}_title", placeholder: t("janela.panes.title_placeholder") %>
+        </div>
+      <% end %>
+    </fieldset>
+  <% end %>
+
   <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") %>
@@ -72,6 +119,12 @@
     <span class="janela-hint"><%= t("janela.value_labels.hint") %></span>
   </div>
 
+  <div class="janela-field">
+    <%= form.check_box :ignore_unknown_filters %>
+    <%= form.label :ignore_unknown_filters %>
+    <span class="janela-hint"><%= t("janela.ignore_unknown_filters.hint") %></span>
+  </div>
+
   <div class="janela-field">
     <%= form.label :span %>
     <%= form.select :span, Janela::Pane::SPANS.to_a %>