janela 0.9.0 → 0.11.0

data/app/models/janela/query.rb

@@ -5,9 +5,20 @@ 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, :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
+
+    attr_reader :definition, :measure, :dimension, :renderer, :limit, :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 +28,7 @@ module Janela
       parts.compact.join("_")
     end
 
-    def initialize(definition:, measure:, dimension: nil, renderer: "table", granularity: nil, limit: nil, filters: {}, fixed: {}, snapshot: nil, title: nil)
+    def initialize(definition:, measure:, dimension: nil, renderer: "table", granularity: nil, limit: nil, filters: {}, fixed: {}, default: {}, snapshot: nil, title: nil)
       @definition = definition
       @title = title
       @measure = measure
@@ -25,6 +36,7 @@ module Janela
       @renderer = renderer.to_s
       @filters = filters
       @fixed = fixed
+      @default = default
       @snapshot = snapshot
 
       raise BadRequest, "unknown pane renderer #{renderer.inspect}" unless RENDERERS.include?(@renderer)
@@ -59,15 +71,87 @@ 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
+
+    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
@@ -98,13 +182,35 @@ module Janela
     def result(on: nil)
       return snapshot.stored_result(self) if frozen?
 
-      # The fixed filter applies even on this pane's own dimension, unlike the
-      # reader's: it is the host saying which rows the frame is about, not a
-      # selection this pane should show the alternatives to (ADR 040).
+      # Default, then fixed, then the reader's: a frame's own permanent
+      # filter narrows first, a host's per-record filter narrows again, and
+      # both apply even on this pane's own dimension, unlike the reader's
+      # 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?
+      return time_result(on) if time?
+
       definition.query(measure, by: dimension, where: applicable_filters, on: on, granularity: granularity, limit: limit)
     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
     # group filters with the null predicate, not an empty string (ADR 009 has
     # no say here; see issue #21).
@@ -113,7 +219,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 ]
@@ -123,6 +229,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
@@ -134,6 +241,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)
@@ -158,8 +266,32 @@ 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 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/queries/_query.html.erb

@@ -7,6 +7,8 @@
   </p>
 <% 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">
@@ -21,24 +23,20 @@
             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?) }) %>
             role="img" aria-labelledby="<%= title_id %>"></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>
     <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 %>
@@ -47,5 +45,10 @@
         </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

@@ -66,5 +66,11 @@ en:
       title_placeholder: Janela writes one if you leave this blank
     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/20260928000001_add_default_filter_to_janela_frames.rb

@@ -0,0 +1,10 @@
+class AddDefaultFilterToJanelaFrames < ActiveRecord::Migration[8.0]
+  def change
+    # A frame's own permanent filter (ADR 043): only a pane over
+    # default_model takes it, so a frame that holds panes from more than one
+    # model is never narrowed by a condition that is not about it. Present
+    # or absent together; every existing frame has neither.
+    add_column :janela_frames, :default_model, :string
+    add_column :janela_frames, :default_where, :json
+  end
+end

data/docs/composing.md

@@ -93,6 +93,25 @@ pane the reader can click: any value but the fixed one returns nothing.
 A figure you compute yourself for the same page, such as the progress
 bar below, takes the same condition in its own `where:`.
 
+## A frame's own permanent filter
+
+Some conditions are not about which record's page this is, they are
+true every time: "this queue never counts an archived row." `where:` is
+code, written into a view, run again on every render. A frame's own
+default filter is data instead, so an analyst changes it without a
+deploy (ADR 043):
+
+```ruby
+frame.update!(default_model: "orders", default_where: { status_in: %w[paid pending] })
+```
+
+`default_model` says which model the condition is about, so a frame
+holding panes from more than one model is never narrowed by a condition
+that was never about the pane reading it. It is validated when you save
+it, against that model's declared dimensions, rather than only
+discovered wrong the next time a pane renders. Set both columns
+together; either alone is a validation error.
+
 ## Components
 
 Each of these is plain HTML. The class names that start `janela-` are

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

data/docs/decisions/043-a-frames-default-filter-names-the-model-it-narrows.md

@@ -0,0 +1,163 @@
+---
+Date: 2026-09-28
+Status: Accepted
+Related: ADR 012, ADR 014, ADR 020, ADR 025, ADR 040
+Triggers:
+  - a frame that should always exclude some rows, regardless of who renders it
+  - adding a column to Janela::Frame or Janela::Pane
+  - a host copying the same where: condition into every view that renders one frame
+  - validating a stored Ransack condition at save time rather than at render
+Topics: frames, filters, cross-filtering, persistence, ransack
+---
+
+# ADR 043: A Frame's Default Filter Names the Model It Narrows
+
+## Context
+
+#63, found while dogfooding: ADR 040 gives a host a way to narrow a
+frame to the current record, `where: { project_id_eq: @project.id }`,
+code, per request, correctly not data because the value is inherently
+per-record. It does not give a frame a way to say something that is
+true on every render, forever: "this queue never counts an archived
+row." That is not per-record narrowing, it is a permanent property of
+what the dashboard means, and today it can only be expressed by typing
+the same Ransack condition into every view that renders the frame.
+
+ADR 012's own argument is that composition moved out of ERB because
+the analyst, not the developer, owns a dashboard, and a decision typed
+into a view is "a file held by the wrong owner." A permanent filter is
+exactly that file, with nowhere on the data side to move to: `Frame`
+and `Pane` have no column that could hold one.
+
+### What breaks the obvious shape
+
+The obvious answer, a `default_where` column on `Frame` applied to
+every pane in it, runs into a fact ADR 020 already used to reject the
+frame as the layer for a different per-pane setting: a frame can hold
+panes from more than one model. Measured against the demo, reusing the
+existing bound check rather than assuming it:
+
+```ruby
+Order.janela.narrow(Order.all, "expedited_eq" => "false")
+# => Janela::BadRequest: Order does not allow filtering on expedited_eq.
+#    Declare a janela dimension, or add it to ransackable_attributes.
+```
+
+`expedited` is a real column on `Order`, not a declared dimension. A
+condition applied uniformly to every pane in a frame raises for any
+pane whose model, or whose declared dimension set, does not carry the
+attribute the condition names. ADR 020's own case was a format string
+being "right for the currency and wrong for the count sitting next to
+it"; a stored Ransack condition is at least as specific to one model.
+
+### What was considered for where the mismatch goes
+
+**Raise for every pane whose model does not match.** Rejected: the
+frame breaks the moment an analyst adds a pane over a second model, or
+the moment a declared dimension is removed from the first, and the
+failure is frame-wide rather than local to the pane that changed.
+
+**Skip the condition quietly for a pane it does not apply to.** Rejected
+outright. ADR 024, ADR 032 and ADR 034 all refuse the same shape of
+quiet: a filter that means one thing for one pane and nothing for
+another, on the same frame, with nothing on the page saying so.
+
+**Restrict a frame with a default to panes over one model.** Considered
+and rejected as an unnecessary restriction on `Pane`, which already
+allows any model with a `janela` block. The mismatch is the default's
+problem to solve, not a new constraint on what a frame may hold.
+
+## Decision
+
+**A frame's default filter names the one model it narrows, and only a
+pane over that model takes it.** `Janela::Frame` gains two columns,
+`default_model` and `default_where`, both nullable and present or
+absent together:
+
+```ruby
+frame.update!(default_model: "orders", default_where: { "status_not_eq" => "archived" })
+```
+
+**`default_model` is validated the same way `Pane#model` already is**:
+blank, or a route key naming a model with a `janela` block, checked
+through `Janela.definition!` and rescued the same way
+`declared_by_a_janela_block` does. It does not have to match any pane
+the frame currently holds. A frame can carry a default before its first
+matching pane exists, and a pane over a different model is simply never
+narrowed by it, no error, because the condition was never claimed to be
+about it.
+
+**`default_where` is validated against that one model's `Definition` at
+save time**, not only discovered wrong at render. `Definition#narrow`
+already runs `Ransack#ransack` and the three checks ADR 025 built
+(dropped filters, disallowed predicates, oversized value lists); a new
+validation calls it against `default_model`'s definition and turns a
+raised `Janela::BadRequest` into a validation error on `default_where`,
+the same sentence a request would have raised, read at the point an
+analyst can still fix it. This is new ground: nothing today validates a
+persisted, arbitrary Ransack condition at save time, only `fixed` and
+the reader's `q[...]`, which are validated fresh on every render because
+neither is ever stored.
+
+**It composes as a third layer, ahead of the two ADR 040 already
+built.** `Pane#query` asks its frame for the default that applies to its
+own model and passes it to `Query`, which narrows with it before `fixed`
+narrows again, before the reader's own filters:
+
+```ruby
+# Janela::Frame
+def default_for(model)
+  default_model == model.model_name.route_key ? default_where.to_h : {}
+end
+
+# Janela::Query#result
+on = definition.narrow(on || model.all, default) if default.present?  # frame, permanent
+on = definition.narrow(on, fixed) if fixed.present?                   # host, per-record (ADR 040)
+definition.query(measure, by: dimension, where: applicable_filters, on: on, ...) # reader
+```
+
+Applied even on a pane's own dimension, the same as `fixed`: the point
+of "this queue never counts an archived row" is that no pane on it ever
+shows archived as one of its own bars either. Nothing the reader does
+in `q[...]` can remove it, for the same reason nothing the reader does
+can remove a host's fixed filter.
+
+**Only a stored frame can have one.** A hand composed `janela_frame do
+... end` block has no `Frame` row for a default to live on; a host
+composing a page in ERB already writes its own permanent conditions in
+its own code, in one place, which is what ADR 012 left unchanged for
+that path. This is additive to the data-driven half only.
+
+**Vocabulary, so the three layers stay distinct.** *Default* is the
+frame's own, permanent, data. *Fixed* stays ADR 040's word for the
+host's own, per-record, code. *Filters*, or `q[...]`, stays the
+reader's. Three words, three owners, and none of them is allowed to
+mean another.
+
+## Consequences
+
+- An analyst declares "this queue never counts an archived row" once,
+  as a row, and it holds across every page that ever renders the frame,
+  including one that does not exist yet.
+- **A stale default is a frame-wide failure, not a pane-wide one.**
+  If `default_model`'s `janela` block later drops the dimension
+  `default_where` names, every pane over that model in the frame raises
+  at render, the same "missing pane" treatment `declared_by_a_janela_block`
+  already gives a stale measure or dimension, just wider: one condition
+  now speaks for every pane that shares its model rather than for one
+  row. Worth a line in the engine's own edit form once built.
+- `janela_frames` gains `default_model` and `default_where`, both
+  nullable. Existing frames are unaffected either way; needs a migration
+  and an `UPGRADING.md` entry (ADR 015).
+- **Not decided here: a frame with panes over two models, each wanting
+  its own permanent default.** One `(model, where)` pair per frame is
+  what is built. A second model needing one of its own is the trigger to
+  revisit this as a has-many rather than a second pair of columns, the
+  same way ADR 040 left a signed filter for the day a host's need for
+  one is real rather than guessed at.
+- The engine's own frame form needs a way to set both columns together,
+  and to clear both together; not built here.
+- What would change this decision: a host needing a permanent filter
+  that is not one model's own condition, such as one spanning an
+  association two different pane models both reach through. Nothing
+  proposes that today.