janela 0.10.0 → 0.11.0

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/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/044-a-categorical-dimension-can-say-what-it-excludes.md

@@ -0,0 +1,140 @@
+---
+Date: 2026-09-29
+Status: Accepted
+Related: ADR 024, ADR 025, ADR 028, ADR 040, ADR 043
+Triggers:
+  - adding not_eq or not_in to a dimension's allowed predicates
+  - a frame's default filter, a host's fixed filter or a reader's q[...]
+    needing to say "not this value" rather than listing every other one
+  - widening CATEGORICAL_PREDICATES or TIME_PREDICATES
+  - reasoning about which dashboard question justifies a new predicate
+Topics: security, ransack, dsl, frames, cross-filtering
+---
+
+# ADR 044: A Categorical Dimension Can Say What It Excludes, Not Only What It Includes
+
+## Context
+
+#64: a categorical dimension's allowed predicates (ADR 025, corrected by
+ADR 028) are `eq`, `in`, `null` and `not_null`. There is no way to say
+"not this one." Reproduced against the demo:
+
+```ruby
+Order.janela.narrow(Order.all, "status_not_eq" => "refunded")
+# => Janela::BadRequest: Order does not allow status_not_eq. This
+#    dimension allows status_eq, status_in, status_null, status_not_null.
+```
+
+`Definition#narrow`/`#filter` is the single choke point every filter
+source goes through (ADR 025), so a reader's `q[...]`, a host's `where:`
+(ADR 040) and a frame's `default_where` (ADR 043) all hit the same wall.
+
+**The question is not whether the list is wrong, the way ADR 028 found
+it.** ADR 028 restored `not_null` because it was already shipped, tested
+behaviour that a first-principles list had missed. `not_eq`/`not_in` are
+not already shipped anywhere; nothing measured today shows them working.
+This is a request for new capability, and ADR 028 already set the bar for
+that: *"a predicate belongs there if a dashboard produces it, or if it is
+a boolean test of presence rather than a way to phrase a match."*
+`not_eq`/`not_in` fail both readings as ADR 028 wrote them: ADR 024 says
+a click only ever writes `eq`/`in`, and excluding a value is not a
+presence test the way `not_null` is.
+
+**But a dashboard question that needs it already exists, and it is the
+one that motivated #63.** ADR 043 built a frame's permanent
+`default_where` for exactly this sentence: "this queue never counts an
+archived row." That sentence can be typed today only as `status_in` with
+every value except `archived`, and #64's own point stands: that
+inclusion list silently stops covering the dashboard the day a new
+status value is added, which is the same quiet wrongness ADR 024, ADR
+032 and ADR 034 all already refuse elsewhere. An exclusion degrades
+differently from an inclusion when the data shape changes under it, and
+"never" is a more honest word for what `default_where` is for than a
+list that has to be kept in sync with every value a column might hold.
+
+### What was considered
+
+**Leave it, and require `_in` naming every value but the excluded one.**
+Rejected for the reason above: it is not equivalent, it is a
+maintenance trap that looks correct until a new value appears.
+
+**Allow `not_eq`/`not_in` only through `where:`/`default_where`, not
+through the reader's `q[...]`.** Considered, because the motivating case
+is a frame's own permanent filter, not something a reader asks for.
+Rejected: `narrow` is deliberately the one choke point every caller
+shares (ADR 025), and splitting it into a predicate list parameterised
+by which caller is asking is new configurability of exactly the kind
+ADR 021 and ADR 023's test rejects, to protect nothing. ADR 040 already
+says a fixed filter is a view filter, not an authorisation boundary: a
+reader who can edit a pane URL can already ask for anything the
+dimension allows, so refusing the reader `not_eq` while allowing a host
+the same predicate on the same attribute buys no security, only a
+second thing to explain.
+
+**A fourth verb in the DSL, "exclude," alongside ADR 025's "select" and
+"range" groupings.** Rejected. Nothing about `not_eq`/`not_in` needs a
+name Ransack does not already give it; the project keeps the DSL a thin
+layer over Ransack rather than a query language of its own (CLAUDE.md's
+forkability vision), and "select"/"range" were never a formal surface,
+only informal shorthand for reading ADR 025. Two more entries in the
+existing list cost nothing that a new grouping would justify.
+
+**Time dimensions get their own decision about whether they need it.**
+Considered, and rejected as unnecessary work: no dashboard question
+measured here or in #63 asks to exclude a single instant from a time
+range, so nothing argues for building it. But `TIME_PREDICATES` is
+`CATEGORICAL_PREDICATES + %w[gteq gt lteq lt]` (`lib/janela/dimension.rb`),
+the same way it already inherits `not_null` without a time-specific
+argument for that either. Carving `not_eq`/`not_in` out of the inherited
+half would be a special case with nothing behind it. It stays inherited.
+
+## Decision
+
+**A categorical dimension's allowed predicates gain `not_eq` and
+`not_in`, for the same reason `not_null` is already there: a real
+dashboard question, already built on top of this list (ADR 043),
+cannot be phrased any other way that survives a new value being added.**
+
+```ruby
+# lib/janela/dimension.rb
+CATEGORICAL_PREDICATES = %w[eq in not_eq not_in null not_null].freeze
+```
+
+`TIME_PREDICATES` inherits both, unchanged in its own definition. No new
+DSL vocabulary is introduced: `not_eq` and `not_in` are exactly Ransack's
+own predicate names, entries in the same flat list every other allowed
+predicate already sits in.
+
+This predicate is reachable through `where:` (ADR 040), `default_where`
+(ADR 043) and a hand-built or shared `q[...]` link, the same as every
+other allowed predicate. It is not reachable through a click: ADR 024
+writes only `eq`/`in`, and toggling a value never produces an exclusion.
+Worth saying plainly wherever this is documented, so nobody goes looking
+in the frame UI for a gesture that was never built.
+
+## Consequences
+
+- #63's motivating sentence, "this queue never counts an archived row,"
+  becomes expressible as `default_where: { "status_not_eq" => "archived" }`
+  and stays true when a new status value is added, which the `_in`
+  workaround could not.
+- **Additive, not breaking.** Nothing that worked before is refused now;
+  the list only widens. No `UPGRADING.md` entry is needed on that
+  account (ADR 015), though the release notes should say the predicate
+  exists, the same way a new capability is always announced.
+- The README and any documentation listing a dimension's allowed
+  predicates needs the two new entries alongside the existing four, kept
+  in sync with `CATEGORICAL_PREDICATES` rather than restated by hand.
+- `reject_oversized_filters!` (ADR 025) already bounds any predicate
+  whose `Ransack::Predicate#wants_array` is true, which includes
+  `not_in`, so the 1000 value ceiling applies to it without a code
+  change.
+- Test coverage belongs in `definition_query_test.rb` (the choke point
+  itself), `fixed_filter_test.rb` and `frame_default_filter_test.rb` (the
+  two callers ADR 040 and ADR 043 built), so all three layers are proven
+  rather than only the one that motivated this. Not built here.
+- What would change this decision: a host with a measured need to
+  exclude a specific instant from a time dimension, which nothing today
+  shows evidence of. The answer then is the same rule ADR 025 already
+  set: add it to the list in an ADR that names the dashboard question,
+  not by making the list configurable.

data/docs/decisions/045-clicking-a-time-bucket-filters-the-frame-to-its-range.md

@@ -0,0 +1,206 @@
+---
+Date: 2026-09-29
+Status: Accepted
+Related: ADR 003, ADR 005, ADR 006, ADR 008, ADR 018, ADR 024, ADR 025, ADR 037, ADR 040
+Triggers:
+  - making a line chart, or a time table row, a click source
+  - a click that has to write more than one filter condition
+  - deciding what a time pane does with a range filter on its own dimension
+  - writing a time range into the page URL or a pane src
+  - drill-down, or narrowing a time pane's granularity by clicking a bucket
+Topics: time, cross-filtering, urls, ransack, accessibility, roadmap
+---
+
+# ADR 045: Clicking a Time Bucket Filters the Frame to Its Range
+
+## Context
+
+A time pane re-scopes when any other pane is clicked, but clicking a
+bucket in it does nothing (#18). ADR 006 left that out deliberately:
+"Clicking a category adds one Ransack condition, `status_eq=paid`.
+Clicking a month means two, `placed_on_gteq` and `placed_on_lt`, and the
+dashboard's filter model is a single key and value per toggle." It said
+drill-down was the natural next decision and would get its own ADR. This
+is that ADR, and it comes now rather than after 1.0 because of what ADR
+037 says 1.0 is: the pane URL shape and the dashboard filter parameters
+stop moving. A range is a new shape in exactly that grammar, and adding
+it after the freeze is a breaking change to the surface rather than an
+addition to it. Nobody reading a dashboard would call a line chart that
+ignores clicks finished, either. It is the first pane a person tries to
+click.
+
+Four things were measured against the dummy before deciding anything.
+
+**Two conditions work as a range, and the end is exclusive.** Against the
+`placed_on` date column, `placed_on_gteq=2026-09-01` with
+`placed_on_lt=2026-09-02` returns the one order on that day, of four in
+all. The month equivalent returns all four. `_gteq` and `_lt` are
+already on a time dimension's allowed list (ADR 025), so the guard needs
+nothing added. Using `_lteq` for the end would make the end of one bucket
+also the start of the next, which is why the pair is half open.
+
+**A bucket's label cannot be turned back into a range.** Groupdate's keys
+are labelled after the query (ADR 006): a day is `2026-09-01`, a week is
+its Monday `2026-08-31`, but a month is `Sep 2026`, a quarter is
+`Q3 2026` and a year is `2026`. The chart looks its filter up by label
+(`filters_for`), so the range has to be computed on the server from the
+bucket before the key is turned into a label, not parsed out of the label
+afterwards.
+
+**A time pane collapses to the bucket that was clicked.** `Query
+#applicable_filters` drops a categorical pane's own dimension from its
+filters, so the pane still shows the alternatives to what was picked, but
+returns every filter for a time pane. With a range on `placed_on`, the
+time pane's own query returns `{"2026-09-01" => 1}`: one point on a line.
+That is the whole difficulty. If the click wrote the range and nothing
+else changed, the pane you clicked would become a single dot, and so
+would every other time pane over the same dimension.
+
+**A time zone offset is accepted on a date column.** `2026-09-01T00:00:00Z`
+and `2026-09-01T00:00:00+10:00` both filter the date column to the right
+day, in UTC and under `Australia/Brisbane`. Not measured, because the
+dummy has no time dimension on a timestamp column and `created_at` is not
+ransackable there: the same pair against a datetime column with
+non-UTC `Time.zone`. Whoever builds this checks it first (see
+Consequences).
+
+### What was considered
+
+**Write one key, a range string.** `placed_on_between=2026-09-01..2026-09-02`
+would keep the frame's one key and value per toggle. Rejected. Ransack
+has no such predicate, so it would be a grammar Janela invents on top of
+ADR 005's, which is built on `q[...]` a person can read and a host can
+already write by hand (ADR 025). ADR 002 and CLAUDE.md are both against a
+second query language, and ADR 006 already tells hosts they can pass
+`placed_on_gteq` and `placed_on_lt` today.
+
+**Have the click write keys of its own, so it never meets the host's.**
+A `placed_on_clicked_from` pair, say, that a time pane ignores while it
+keeps applying `_gteq` and `_lt`. Rejected as a second vocabulary for one
+idea. The reader's own selection and a host's range are different
+*sources*, and ADR 040 and ADR 043 already sort by source: a host's fixed
+and default filters apply on a pane's own dimension, the reader's do not.
+Time panes should follow that rule like every other pane, not carry a
+private one.
+
+**Narrow, the way a BI tool drills.** Clicking `Sep 2026` changes that
+pane's granularity to weeks within September (#18's second option).
+Rejected here, and deferred, not refused. It changes what one pane shows
+rather than what the frame is filtered to, so it is a separate gesture
+with its own question: how to get back out, and whether it belongs in the
+URL (ADR 008). The filter is useful alone, and drill-down can be added
+on top of it without changing anything decided below.
+
+**Select more than one bucket.** Ctrl-click to add a second day, as ADR
+024 does for values. Rejected. Two `_gteq`/`_lt` pairs on one attribute
+are not two ranges. Ransack ANDs its conditions, so two different days
+return no rows at all, silently, which is the failure ADR 024 measured for
+`_null` with `_in`. Ransack's `g[]` grouping could express an OR and is
+rejected for the reason ADR 024 gave: it makes the URL unreadable.
+Adjacent buckets could be merged into one longer range, but that is a
+different gesture with a different rule about gaps, and nothing here asks
+for it.
+
+## Decision
+
+**Clicking a bucket on a time pane filters the frame to that bucket's
+half-open range, written as the dimension's `_gteq` and `_lt`. A time
+pane shows the alternatives to its own selection, like every other pane,
+and highlights the buckets inside it.**
+
+**The range is the bucket's start and the next bucket's start.** The
+server computes both from the bucket Groupdate returned, at the pane's
+granularity and with the week starting on `Date.beginning_of_week`, and
+hands the chart a pair per label. A click on `Sep 2026` writes:
+
+```
+q[placed_on_gteq]=2026-09-01&q[placed_on_lt]=2026-10-01
+```
+
+For a date column the values are dates. For a timestamp they are the
+start in `Time.zone`, ISO 8601 with its offset, so the bucket a person
+clicked is the bucket the filter selects. The URL stays readable and
+editable, and a range a host passes by hand behaves identically.
+
+**The toggle carries a selection, and a selection can be more than one
+condition.** A value click is a selection of one condition, as it is
+today. A bucket click is a selection of two. The frame controller treats
+either as one thing to add, replace or clear, so `clearDimension` clears
+the dimension's `gteq`, `gt`, `lteq` and `lt` as well as `in`, `null` and
+`eq`. Clicking the selected bucket clears it, the same as a value.
+
+**A modifier click is a plain click on a time pane.** A range is not a
+set, for the reason above, so Ctrl and Cmd change nothing here. This is
+the one place ADR 024's gesture does not apply, and the pane says so in
+its accessible description rather than leaving it to be discovered.
+
+**A time pane ignores the reader's range on its own dimension, and
+highlights the buckets that fall inside it.** This reverses what
+`applicable_filters` does for time panes today and follows the rule ADR
+040 and ADR 043 already set: a host's fixed and default filters narrow a
+pane on its own dimension, the reader's selection does not. A bucket is
+selected when its whole range lies within the filter's, so clicking a
+month highlights every day of that month on a day chart. Panes over the
+same dimension at different granularities agree that way without knowing
+about each other.
+
+**Granularity does not change.** Drill-down stays open (#18's second
+option), to be decided on top of this rather than folded into it.
+
+**Keyboard follows ADR 018.** A time table's rows render their labels as
+buttons, as a categorical table's do, and Enter is the click. A line
+chart stays a mouse surface, as ADR 024 accepts for bars, and the table
+that renders the same data is the operable one.
+
+**A stored pane is still not clickable** (ADR 009). It is the record of a
+moment.
+
+## Consequences
+
+- A dashboard can answer "what happened in March?" by clicking March,
+  and every other pane re-scopes. That is the first thing anyone tries on
+  a line chart and it now works.
+- **Breaking, narrowly.** A reader-supplied `placed_on_gteq` or `_lt` in a
+  URL used to narrow a time pane's own series. It now scopes every other
+  pane and leaves that one showing the whole series with the range
+  highlighted. A host's `where:` and `default_where` still narrow it, so
+  the supported way to fix a range is unchanged. It needs an
+  `UPGRADING.md` entry naming both routes, and the release carrying it is
+  a minor one (ADR 015). The doctor cannot see this from source, because
+  the filter arrives at runtime.
+- `Query#clickable?` stops excluding time panes, `filter_params` and
+  `filters_for` return a pair for one, and `selected_values` for a time
+  pane becomes a question about ranges. `Definition#query` has to keep the
+  bucket start until after the labelling step, since the label is
+  lossy. These are the parts a forker is most likely to touch, and the
+  reason they are named here.
+- The frame controller's toggle grows from one key and value to a
+  selection. A host that dispatches `janela--frame:toggle` itself keeps
+  working, because a single key and value is still a selection.
+- The case measured in Context as unmeasured was measured in the build.
+  On SQLite under `Australia/Brisbane`, a timestamp at 14:30 UTC on 1
+  September was bucketed into 2 September, a `_gteq`/`_lt` pair written as
+  ISO 8601 with `+10:00` for 2 September returned it and the pair for 1
+  September returned nothing, and date-only strings gave the same answers.
+  Groupdate honoured the zone on SQLite there, which ADR 006 said it does
+  not, so that line of ADR 006 is out of date. Not measured on PostgreSQL
+  or MySQL, whose zone handling is the database's own.
+- **The demo proves it.** Until a line pane on the home page's "This one
+  is live" frame filters the other panes when a day is clicked, and a
+  system test does the same, this ADR has been read but not shown to work.
+  The build includes both, and the home page's copy changes from "three
+  panes" to match.
+- **This moves #18 into 1.0.** ADR 037 sorted #18 after 1.0 on the ground
+  that it "needs an ADR of its own before any code", and that ADR now
+  exists. What moves it is the ground ADR 037 itself argues: a range is a
+  new shape in the URL grammar the freeze covers. The milestone gains a
+  ninth issue, `docs/roadmap.md` (and the count in its illustration) is
+  updated with it, and ADR 037 is left as written. The sort in it was
+  right at the time, and an ADR records what was decided then.
+- ADR 006's paragraph "Time panes are not yet click sources" is
+  superseded by this one. The rest of ADR 006 stands.
+- What would change this decision: a real dashboard that needs two
+  separate periods selected at once, which would have to be an OR and
+  would have to justify the URL cost ADR 024 refused; or drill-down
+  turning out to be the gesture people expect from a click, in which case
+  the follow-up ADR may swap which one a plain click does.

data/docs/decisions/046-a-ring-is-server-drawn-svg-and-a-palette-is-eight-fixed-colours.md

@@ -0,0 +1,199 @@
+---
+Date: 2026-09-29
+Status: Accepted
+Related: ADR 016, ADR 018, ADR 024, ADR 026, ADR 036, ADR 037, ADR 042
+Triggers:
+  - adding a renderer, or a colour a renderer draws with
+  - adding a custom property to janela.css or documenting one in docs/theming.md
+  - drawing a part-to-whole split, a doughnut or a pie
+  - deciding what a chart does with more categories than it has colours
+  - a chart pane that must be readable, printable or operable without JavaScript
+Topics: rendering, styling, theming, charts, accessibility, roadmap
+---
+
+# ADR 046: A Ring Is Server Drawn SVG, and a Palette Is Eight Fixed Colours
+
+## Context
+
+#30, raised from a real install: a two-category split has to be drawn as
+two bars, and a ring reads better for a part-to-whole. It asks for
+`doughnut` and `pie` renderers, a categorical palette to make them
+readable, and two smaller fixes to the chart controller. It assumes
+Chart.js, because the controller already hands its type straight to
+it. ADR 037 puts it in 1.0 and #30 is the only item there that adds to
+what a pane can be drawn as.
+
+Measured against the demo before deciding:
+
+- `renderer: "doughnut"` raises `Janela::BadRequest` today. The whitelist
+  is `Janela::Query::RENDERERS` (`%w[table bar line]`). The issue says
+  `Pane::RENDERERS`, which does not exist. The pane form, `Janela.renderers`,
+  the `janela.renderers.*` locale keys, the gallery and stored pane rows
+  all read that one constant.
+- Chart.js is vendored with its doughnut and pie controllers, so the
+  canvas route needs no dependency.
+- Switching a live bar chart's config to `doughnut` with the controller's
+  own options gives a ring in one colour: `backgroundColor` holds one
+  distinct value across four segments, so the boundaries are hairlines.
+  The unconditional `y` scale is configured on it too. Both complaints in
+  the issue are real.
+- `--janela-accent` is the only colour Janela publishes
+  (`docs/theming.md`). Vitral's `--vitral-pane-1..5` are translucent glass
+  tints for backgrounds, not colours to draw data in.
+- The demo's dimensions have four, two and three values (one of them the
+  `(none)` group). A categorical dimension is bounded only by 1000
+  (ADR 025), so a palette will meet more categories than it has colours.
+- The dataviz palette validator (a fixed-order eight colour categorical
+  set) passes on adjacent pairs in light mode with the accent as slot 1:
+  worst adjacent colour vision separation 9.1, normal vision 19.6, against
+  targets of 8 and 15. It warns that four slots (accent, aqua, yellow,
+  pink) fall under 3:1 contrast against a light surface, which obliges
+  visible labels or a table view. The same eight hues stepped for a dark
+  surface pass too (8.4, 19.3, contrast all 3:1 or better).
+
+### What was considered
+
+**Chart.js `doughnut` and `pie`, as the issue proposes.** The smallest
+change: a whitelist entry, a palette, and conditionals around the scale
+and legend. Rejected. ADR 026 makes server rendered HTML and CSS the
+default, a library earning its place by doing what the document cannot,
+and a ring is inline SVG arcs, which the document can do. A canvas is
+blank without JavaScript, does not print as text, has nothing focusable
+behind it (ADR 024 already says as much of bars) and puts the labels
+inside a bitmap. It would also leave the issue's two "smaller things" as
+work: the scale and legend switches exist only because the canvas has to
+be told what it is.
+
+**A CSS `conic-gradient` ring.** Also HTML and CSS, and shorter than SVG.
+Rejected. A gradient is one element, so a slice has no hit target, no
+native tooltip and no way to take a gap or a dimmed state of its own.
+Every one of those would have to be rebuilt from the legend alone.
+
+**Cycle the palette.** #30 says "N distinct colours cycling". Rejected.
+The 9th slice reusing the 1st colour draws two different categories the
+same, next to a legend that says they are different. The rule is fixed
+order and a neutral past the last slot.
+
+**Leave bars on the one accent.** The recommendation put to the
+maintainer, to avoid changing panes people have already themed.
+Overridden: the palette applies to bars as well. See Consequences for
+what that changes and what a host does.
+
+## Decision
+
+**`doughnut` and `pie` are renderers drawn on the server as inline SVG
+with a legend that is a table of buttons, and Janela publishes a
+categorical palette of eight fixed colours that bars, doughnuts and pies
+draw with.**
+
+**The ring is SVG, and its legend is the control.** Each slice is a `path`
+carrying the same `janela--frame#toggle` action a table button does, a
+`<title>` child so a hover names it, and a gap between slices so no
+boundary depends on colour alone. A doughnut is a pie with a hole. The
+pane is a `figure` with a `figcaption` title (ADR 042), the SVG points to
+it, and beside the ring is a legend of real buttons, each with a swatch,
+the label and the measure's formatted value (ADR 020). The legend is what a
+keyboard, a screen reader and a touch user operate, and it is the visible
+labelling the palette's contrast warning obliges. Ctrl and Cmd add and
+remove as in ADR 024, because they are the same buttons. It works,
+printed and unstyled, with no JavaScript, and the engine's own frame page
+draws it (ADR 026, rule 3).
+
+**A ring draws only what a ring can.** A slice with a zero value is left
+out of the ring and stays in the legend. A pane with a negative value is
+drawn as the table renderer's markup instead, since a part of a whole
+cannot be negative, and the pane says so in words rather than drawing
+something wrong. Nothing raises.
+
+**The palette is eight ordered custom properties and a neutral.**
+
+```css
+:root {
+  --janela-series-1: var(--janela-accent);
+  --janela-series-2: #eb6834;
+  --janela-series-3: #1baf7a;
+  --janela-series-4: #eda100;
+  --janela-series-5: #e87ba4;
+  --janela-series-6: #008300;
+  --janela-series-7: #4a3aa7;
+  --janela-series-8: #e34948;
+  --janela-series-other: #8c8c8c;
+}
+```
+
+Slot 1 is the accent, so a host that has set `--janela-accent` still has
+its own colour on the first bar. The set is the reference instance of the
+validated palette with the accent standing in for its blue, and it was
+run through the validator in that form. A colour is chosen by a
+category's position in the result, first to eighth, and every category
+past the eighth takes `--janela-series-other`. Never cycled. A host
+that wants a longer pane says `limit: 8` (ADR 007), which is the honest
+answer for a ring anyway, and the documentation says a ring suits few
+slices. Lines are one series and keep the accent.
+
+**The selected state is the existing one, over each slice's own colour.**
+With nothing selected every slice and bar is solid. With a selection the
+unselected ones dim to the same reduced opacity a bar already uses
+(`colours()` in `chart_controller.js`) and the selected ones stay solid.
+A dimmed set of eight colours stays distinguishable because opacity is
+applied to the slice, not the palette.
+
+**Published, and therefore frozen at 1.0.** `--janela-series-1..8`,
+`--janela-series-other` and the ring's and legend's class names join the
+contract in `docs/theming.md` in the same change (ADR 036). The class
+names are chosen in the build and documented there, not here. The dark
+values that passed the validator are recorded in `docs/theming.md` for a
+theme to use. `janela.css` ships no dark scheme today (ADR 023 leaves that
+to a theme), and adding one is not this decision.
+
+**The chart controller changes only for bars.** It draws bar and line, so
+the two conditionals in the issue (`beginAtZero` on an axis-less chart and
+the hidden legend) do not arise and are not added. Bars read their
+per-bar colours from the palette on the element, the way `accentColour`
+already reads `--janela-accent`.
+
+## Consequences
+
+- A part-to-whole split has a renderer, and it is a table to a screen
+  reader, a picture to everyone else, and a link on a slice to anyone with
+  a mouse.
+- `Query::RENDERERS` becomes `table bar line doughnut pie`. `Janela
+  .renderers`, the pane form, the locale keys (`janela.renderers.doughnut`
+  and `.pie`), the gallery and its tests follow from that one constant and
+  need entries. A model with no suitable dimension shows the renderer as
+  unavailable, as the gallery does for any other. Additive.
+- **Bars change appearance, in a minor release.** Every existing bar pane
+  goes from one accent colour to one colour per bar. A host that themed
+  bars through `--janela-accent` keeps that colour on the first bar and
+  the accent for selection and hover, and gets new colours on the rest.
+  A host that wants the old look sets `--janela-series-2` to
+  `--janela-series-8` to the accent. It needs an `UPGRADING.md` entry
+  saying exactly that, in the release that carries it (ADR 015). The
+  doctor cannot see this from source.
+- **Colour follows position, not the category.** A filter on another
+  pane can reorder this pane's categories, and a colour then moves with
+  its rank. The dataviz rule that colour follows the entity, so a filter
+  never repaints the survivors, is not met, because Janela has no registry
+  of what a category is. The label is always beside the colour (legend or
+  axis), which is the reason this is acceptable, and the cost is real. What
+  would change it: a host declaring a colour for a dimension value,
+  which is a new piece of DSL and its own ADR.
+- Four slots fall under 3:1 contrast on a light surface. The legend is the
+  visible labelling the validator asks for, and a bar has its axis.
+  Adjacent colour vision separation is 9.1 and above, but only the first
+  three slots pass when every pair is compared, and a ring with a fifth
+  slice puts colours side by side that are not adjacent in the palette.
+  That is why the gap and the legend exist and why the documentation
+  recommends few slices.
+- A slice's hit target is small when it is a small share. The legend row
+  is always the full target.
+- The demo proves it. The home page's "This one is live" frame gains a
+  doughnut pane (revenue by status), the gallery shows both new renderers
+  through `Janela.renderers`, and a system test clicks a slice and a legend
+  button and sees the other panes re-scope. The copy that says how many
+  panes there are changes with it, once, together with the time pane from
+  ADR 045.
+- What would change this decision: a chart that needs what SVG cannot do,
+  such as animation or many thousands of marks, is the case ADR 026 keeps
+  the library for, and this one does not fit it. A host that needs a
+  category to keep its colour across filters is the case above.

data/docs/decisions/INDEX.md

@@ -22,27 +22,27 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 |-------|------|
 | **Vision, scope, forkability** | 001, 010, 012, 037 |
 | **Open-source & host-decoupling** | 001, 022, 036, 041 |
-| **DSL & query layer** | 002, 006, 007, 020, 025, 038 |
+| **DSL & query layer** | 002, 006, 007, 020, 025, 038, 044 |
 | **Dependencies** | 002, 003, 004, 006, 017, 025 |
 | **Authorisation** | 002, 003, 004, 009, 017, 019, 022, 032, 033, 034, 035, 039, 040 |
 | **Performance & storage** | 007, 017, 025 |
 | **Ordering & formatting** | 007, 020, 038 |
-| **Cross-filtering & Hotwire** | 003, 004, 005, 008, 024, 025, 040, 043 |
+| **Cross-filtering & Hotwire** | 003, 004, 005, 008, 024, 025, 040, 043, 044, 045 |
 | **Layouts & views** | 011, 012, 016, 018, 020, 027, 039 |
-| **CSS & styling** | 016, 018, 023, 026, 027, 036, 042 |
-| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030, 033, 039, 040, 041, 043 |
+| **CSS & styling** | 016, 018, 023, 026, 027, 036, 042, 046 |
+| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030, 033, 039, 040, 041, 043, 044 |
 | **Naming rule** | 014, 023, 036 |
-| **JavaScript delivery & charts** | 004, 006, 026, 042 |
-| **Time dimensions** | 006, 025 |
-| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025, 040, 041 |
+| **JavaScript delivery & charts** | 004, 006, 026, 042, 046 |
+| **Time dimensions** | 006, 025, 045 |
+| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025, 040, 041, 045 |
 | **Snapshots & publishing** | 009, 020, 028, 033, 034 |
 | **AI agents & guidance** | 010, 015, 021 |
 | **The doctor & checks** | 021, 025, 032, 033, 035 |
 | **Releases & upgrades** | 015, 021, 032, 034, 035, 036, 037, 042 |
-| **Accessibility & keyboard** | 024, 042 |
-| **Security** | 003, 025, 028, 031, 032, 034, 035 |
+| **Accessibility & keyboard** | 024, 042, 045, 046 |
+| **Security** | 003, 025, 028, 031, 032, 034, 035, 044 |
 | **Testing** | 003 |
-| **Roadmap & planning** | 001, 037 |
+| **Roadmap & planning** | 001, 037, 045, 046 |
 
 ## Chronological
 
@@ -91,7 +91,10 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 041 | A Host Finds Its Frame by Owner and Key | 2026-09-24 | Accepted |
 | 042 | A Chart's Title Is a Figcaption, and the Canvas Points to It | 2026-09-28 | Accepted |
 | 043 | A Frame's Default Filter Names the Model It Narrows | 2026-09-28 | Accepted |
+| 044 | A Categorical Dimension Can Say What It Excludes, Not Only What It Includes | 2026-09-29 | Accepted |
+| 045 | Clicking a Time Bucket Filters the Frame to Its Range | 2026-09-29 | Accepted |
+| 046 | A Ring Is Server Drawn SVG, and a Palette Is Eight Fixed Colours | 2026-09-29 | Accepted |
 
 ## Next number
 
-Next ADR: 044
+Next ADR: 047