janela 0.15.0 → 0.16.0

data/app/models/janela/pane.rb

@@ -49,6 +49,8 @@ module Janela
     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?
@@ -91,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, sort: sort, 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
 
@@ -145,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
@@ -175,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,18 +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, :sort, :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, sort: 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),
-                (sort if by && sort.present? && sort.to_s != "desc") ]
+                (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, sort: 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
@@ -64,8 +110,11 @@ module Janela
       @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
@@ -126,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?
@@ -211,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, sort: sort, 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
@@ -222,12 +271,70 @@ 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,
@@ -235,7 +342,10 @@ module Janela
     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
@@ -266,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
@@ -344,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
@@ -413,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)
@@ -435,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/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

@@ -63,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") %>
@@ -79,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 %>

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

@@ -25,25 +25,35 @@
            "janela--chart-title-value": query.title,
            "janela--chart-selected-value": query.selected_values.to_json,
            "janela--chart-labels-value": result.keys.to_json,
-           "janela--chart-values-value": result.values.map(&:to_f).to_json,
+           "janela--chart-values-value": result.values.map { |measured| measured&.to_f }.to_json,
            "janela--chart-formatted-value": result.values.map { |measured| query.format(measured) }.to_json,
            "janela--chart-tick-format-value": query.tick_format.to_json,
            "janela--chart-filters-value": query.filters_for(result.keys).to_json,
            "janela--chart-fixed-height-value": (true if query.boxed?),
-           "janela--chart-value-labels-value": (true if query.labelled?)
+           "janela--chart-value-labels-value": (true if query.labelled?),
+           # Only with further series, so a chart without them is handed
+           # exactly what it always was (ADR 062).
+           "janela--chart-label-value": (query.series_label if query.series?),
+           "janela--chart-series-value": (query.chart_series(result).to_json if query.series?),
+           "janela--chart-axes-value": query.axis_titles&.to_json
          }) %>
     <%= query.boxed? ? tag.div(canvas, class: "janela-chart-box janela-h-#{query.height}") : canvas %>
   </figure>
 <% else %>
   <%= 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? %>
+    <%# A header row only when there are columns to name: two columns read
+        without one, and a table with none is what it always was (ADR 051).
+        A further series is a column after the measure's and before any
+        companion, which is also the table a chart falls back to (ADR 062). %>
+    <% if query.companion_columns.any? || query.drawn_series.any? %>
       <thead>
         <tr>
           <th scope="col"><%= query.dimension_header %></th>
           <th scope="col"><%= query.measure_header %></th>
+          <% query.drawn_series.each do |series| %>
+            <th scope="col"><%= query.series_label(series) %></th>
+          <% end %>
           <% query.companion_columns.each do |column| %>
             <%= tag.th column.header, scope: "col", class: ("janela-fact" if column.fact) %>
           <% end %>
@@ -63,6 +73,9 @@
             <% end %>
           </td>
           <td><%= query.format(measured) %></td>
+          <% query.drawn_series.each do |series| %>
+            <td><%= query.series_format(series, series.values[label]) %></td>
+          <% end %>
           <% query.companion_columns.each do |column| %>
             <%= tag.td column.cells[label], class: ("janela-fact" if column.fact) %>
           <% end %>

data/config/locales/en.yml

@@ -25,6 +25,9 @@ en:
         prominence: Prominence
         value_labels: Show each bar's value
         companions: Beside the label
+        cumulative: Running total
+        series: More series
+        ignore_unknown_filters: Ignore filters this model cannot apply
         title: Title
   janela:
     errors:
@@ -76,8 +79,23 @@ en:
       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.
+    ignore_unknown_filters:
+      hint: For a pane beside panes over another model. A click there names a dimension this model does not have, and this pane stays as it is instead of saying the request is not allowed. A filter nobody's model declares is still a mistake on every other pane.
     value_labels:
-      hint: Draws the value at the end of each bar of a bar chart, if every one fits. Other charts ignore it.
+      hint: Draws the value at the end of each bar of a bar chart, if every one fits, and a line's latest value at its end. A ring ignores it.
+    series:
+      to_date: "%{label} to date"
+      cumulative_hint: Adds the measure up across the buckets, so the pane reads as a total to date. Applies to a time dimension.
+      hint: Up to %{count} more measures over the same buckets, each a line or bars on the left axis or a right one. A table draws them as columns. A ring ignores them.
+      measure: Measure
+      by: Over
+      as: Drawn as
+      axis: Axis
+      none: None
+      same_as_pane: Same as the pane
+      axes:
+        left: Left
+        right: Right
     sorts:
       desc: Largest first
       asc: Smallest first

data/db/migrate/20261029000001_add_series_to_janela_panes.rb

@@ -0,0 +1,9 @@
+class AddSeriesToJanelaPanes < ActiveRecord::Migration[8.0]
+  def change
+    # A running total of a time pane's measure, and up to three more series
+    # drawn beside it (ADR 062). Null is what every existing pane is: unset,
+    # and drawn exactly as before.
+    add_column :janela_panes, :cumulative, :boolean
+    add_column :janela_panes, :series, :json
+  end
+end

data/db/migrate/20261029000003_add_ignore_unknown_filters_to_janela_panes.rb

@@ -0,0 +1,8 @@
+class AddIgnoreUnknownFiltersToJanelaPanes < ActiveRecord::Migration[8.0]
+  def change
+    # Whether a pane drops a reader's filter its model cannot apply rather
+    # than refusing the request (ADR 063). Null is what every existing pane
+    # is: unset, and refused exactly as before.
+    add_column :janela_panes, :ignore_unknown_filters, :boolean
+  end
+end

data/docs/agents.md

@@ -15,6 +15,29 @@ them with whatever MCP library your application already runs. Janela
 registers nothing, detects nothing and serves nothing, because it cannot
 know who is asking and your application can.
 
+## Setting it up
+
+```
+bin/rails generate janela:mcp
+```
+
+This writes `bin/janela-mcp`, a stdio server built on the official Ruby SDK, and
+adds a `janela` entry to `.mcp.json`, which Claude Code and other MCP clients
+read to find it. Both are yours from then on. It leaves an existing server or
+entry alone, and it does not touch your Gemfile: if `mcp` is not in your bundle
+it says which line to add (`gem "mcp"`).
+
+Open `bin/janela-mcp` and write the scope. It is the one thing the generator
+cannot know: who the agent acts for, and what that caller may read. It cannot be
+your controller's `policy_scope`, which needs a request, and called without one
+it does not fail but answers a different question and reads the wrong rows
+(ADR 057). Until you write it, every tool refuses to read and says so. The file
+also refuses to run outside development, so an agent never reaches real data
+until you decide it should.
+
+The rest of this page explains what is in that file, for a host that would
+rather write it by hand or register the tools with another library.
+
 ## Building the tools
 
 ```ruby
@@ -43,6 +66,7 @@ tool is called. They are cheap to construct.
 | `update_pane` | Change a pane. An invalid change leaves it as it was. | yes |
 | `remove_pane` | Remove a pane and close the gap. | yes |
 | `move_pane` | Move a pane one place up or down. | yes |
+| `update_frame` | Change a frame's `columns` and `gap`. Its name, key and owner are not an agent's to change. | yes |
 
 The write tools are off unless you build the tools with `write: true`. Their
 inputs are the pane's own attributes, the ones the README
@@ -50,8 +74,8 @@ names, and nothing else: an attribute that is not a pane's is refused rather
 than dropped. A pane Janela would refuse is refused with its own reason, for
 example `Measure "nonsense" is not a measure of Order`.
 
-There is no tool to create a frame or take a snapshot. Your code finds or makes
-a frame with `Janela::Frame.for` (ADR 041), and a snapshot needs an owner and a
+There is no tool to create a frame or take a snapshot, and none to change who owns
+one. Your code finds or makes a frame with `Janela::Frame.for` (ADR 041), and a snapshot needs an owner and a
 scope you have named (ADR 033, ADR 034).
 
 ## Registering them
@@ -88,6 +112,13 @@ end
 `mcp` is not a dependency of Janela, and a host using another library writes the
 same few lines against it.
 
+## What an agent cannot reach
+
+A server run with `bin/janela-mcp` reads and changes the database of the
+environment it starts in, which is development. It cannot reach a dashboard on a
+deployed host: that needs an authenticated path only your application can give,
+because Janela serves no endpoint and does not know who is calling (ADR 053).
+
 ## What Janela does not do
 
 It does not serve MCP, detect a server, edit your configuration or install