janela 0.11.0 → 0.12.0

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

@@ -1,10 +1,10 @@
 <%# One pane's content, without its turbo frame: the same markup whether the
     pane came from a URL, a row, or a frame rendered inline. %>
 <% if query.single_value? %>
-  <p class="janela-pane janela-value">
+  <%= tag.p class: [ "janela-pane", "janela-value", ("janela-prominence-#{query.prominence}" if query.prominent?) ] do %>
     <span class="janela-value-label"><%= query.title %></span>
     <strong class="janela-value-number"><%= query.format(result || 0) %></strong>
-  </p>
+  <% end %>
 <% elsif result.empty? %>
   <p class="janela-pane janela-empty"><%= query.title %>: no data</p>
 <% elsif query.ring? && query.ringable?(result) %>
@@ -13,6 +13,9 @@
   <% title_id = "#{query.turbo_frame_id}-title" %>
   <figure class="janela-pane">
     <figcaption class="janela-chart-title" id="<%= title_id %>"><%= query.title %></figcaption>
+    <%# A height puts the canvas in a box of fixed size for the chart to fill;
+        with none there is no box and the chart is what it always was (ADR 047). %>
+    <% canvas = capture do %>
     <canvas class="janela-chart"
             data-controller="janela--chart"
             data-action="janela--chart:toggle->janela--frame#toggle"
@@ -24,11 +27,27 @@
             data-janela--chart-formatted-value="<%= result.values.map { |measured| query.format(measured) }.to_json %>"
             data-janela--chart-filters-value="<%= query.filters_for(result.keys).to_json %>"
             <%= tag.attributes(aria: { description: (t("janela.time.click_hint") if query.time? && query.clickable?) }) %>
+            <%= "data-janela--chart-fixed-height-value=true".html_safe if query.boxed? %>
             role="img" aria-labelledby="<%= title_id %>"></canvas>
+    <% end %>
+    <%= query.boxed? ? tag.div(canvas, class: "janela-chart-box janela-h-#{query.height}") : canvas %>
   </figure>
 <% else %>
   <%= tag.table class: "janela-pane", aria: { description: (t("janela.time.click_hint") if query.time? && query.clickable?) } do %>
     <caption><%= query.title %></caption>
+    <%# A header row only when there are companions to name: two columns read
+        without one, and a table with none is what it always was (ADR 051). %>
+    <% if query.companion_columns.any? %>
+      <thead>
+        <tr>
+          <th scope="col"><%= query.dimension_header %></th>
+          <th scope="col"><%= query.measure_header %></th>
+          <% query.companion_columns.each do |column| %>
+            <%= tag.th column.header, scope: "col", class: ("janela-fact" if column.fact) %>
+          <% end %>
+        </tr>
+      </thead>
+    <% end %>
     <tbody>
       <% result.each do |label, measured| %>
         <% click = query.click_data(label) if query.clickable? %>
@@ -42,6 +61,9 @@
             <% end %>
           </td>
           <td><%= query.format(measured) %></td>
+          <% query.companion_columns.each do |column| %>
+            <%= tag.td column.cells[label], class: ("janela-fact" if column.fact) %>
+          <% end %>
         </tr>
       <% end %>
     </tbody>

data/config/locales/en.yml

@@ -20,6 +20,9 @@ en:
         granularity: Granularity
         limit: Rows
         span: Width
+        height: Height
+        prominence: Prominence
+        companions: Beside the label
         title: Title
   janela:
     actions:
@@ -64,6 +67,22 @@ en:
       text: Text
       link_hint: "A path on this site, such as /orders. Makes the heading a link."
       title_placeholder: Janela writes one if you leave this blank
+    companions:
+      measures: Measures
+      dimensions: Dimensions
+      hint: Up to three, drawn as columns in a table. A dimension shows a value only where every row of its group shares one.
+    prominences:
+      automatic: Automatic
+      "1": Footnote
+      "2": Normal
+      "3": Hero
+    heights:
+      automatic: Automatic
+      "1": Very short
+      "2": Short
+      "3": Medium
+      "4": Tall
+      "5": Very tall
     renderers:
       bar: Bar chart
       doughnut: Doughnut chart

data/db/migrate/20260930000001_add_height_to_janela_panes.rb

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

data/db/migrate/20260930000002_add_prominence_to_janela_panes.rb

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

data/db/migrate/20260930000003_add_companions_to_janela_panes.rb

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

data/docs/decisions/024-selecting-more-than-one-value.md

@@ -1,6 +1,6 @@
 ---
 Date: 2026-09-16
-Status: Accepted
+Status: Accepted (the exclusive null group paragraph is superseded by ADR 049)
 Related: ADR 003, ADR 005, ADR 008, ADR 009, ADR 018
 Triggers:
   - changing what a click on a value does

data/docs/decisions/038-a-ratio-is-a-measure-of-its-own.md

@@ -1,6 +1,6 @@
 ---
 Date: 2026-09-24
-Status: Proposed
+Status: Accepted
 Related: ADR 001, ADR 002, ADR 007, ADR 020, ADR 025
 Triggers:
   - adding a measure kind, or a sixth aggregate to the DSL

data/docs/decisions/047-a-charts-height-is-one-of-five-steps.md

@@ -0,0 +1,169 @@
+---
+Date: 2026-09-30
+Status: Accepted
+Related: ADR 005, ADR 012, ADR 016, ADR 029, ADR 036, ADR 037, ADR 042, ADR 046
+Triggers:
+  - giving a chart pane a height, an aspect ratio or any size of its own
+  - adding a parameter to the pane URL, or a column to janela_panes
+  - adding a class to the scale in janela.css, or a wrapper inside a chart pane
+  - a chart that is too tall, too short or squashed in a stored frame
+  - deciding what a renderer does with a setting that is not meant for it
+Topics: charts, css, layout, styling, public-api, panes, frames, urls
+---
+
+# ADR 047: A Chart's Height Is One of Five Steps, and Unset Changes Nothing
+
+## Context
+
+#24: a chart draws with Chart.js's defaults, `responsive` and
+`maintainAspectRatio: true` at 2:1, and a host cannot correct it from
+outside. A second report widened it: a stored frame has no height
+vocabulary at all. Its layout is width only, `columns`, `gap` and `span`
+(ADR 012), so an analyst with a three-row frame of charts could make it
+shorter only by swapping the charts for tables, which changes what the
+dashboard says to change how tall it is.
+
+Measured in a browser against the demo before deciding, and two things the
+issue assumed turned out to be wrong.
+
+**A chart is not enormous today.** A full width line in a 1020px column
+renders 1020 by 320 and a bar in one column of three renders 301 by 150.
+`canvas.janela-chart { max-height: 20rem }` already caps it at 320px, and
+the canvas bitmap and its CSS size agree.
+
+**A host can lower a chart from outside and cannot set one.** A host's
+`max-height: 120px !important` took the line to 1020 by 120, redrawn
+rather than squashed, so it does not "fight the resize loop". But
+`height: 240px !important` on the bar is ignored (still 150, because the
+height is derived from the width), and `min-height: 240px` stretches the
+bitmap: the box is 240 and the chart inside it is 150, so it is drawn
+distorted. Exactly N tall, or taller than 2:1, cannot be said from outside.
+
+**What works is a box of fixed height around the canvas.** Built fresh with
+`maintainAspectRatio: false` inside a `position: relative` box, a chart
+takes the box's height exactly, redraws when the box is resized, and does
+the same in a 300px column. (Patching the option onto a chart that was
+built with the aspect ratio on gave unreliable readings, so a height has
+to be known when the chart is made.) Five heights derived from the spacing
+unit, `--janela-space` at its default of 0.25rem, measured at 96, 160, 224,
+320 and 448 pixels and each came out exactly. The fifth is squashed to 320
+by the existing `max-height: 20rem` unless that rule is lifted inside the
+box.
+
+### What was considered
+
+**Pixels, `height: 240`, as the issue proposed.** Works for the helper and
+not for a row. ADR 016 keeps an analyst's number out of CSS: a stored
+integer selects a class that is already written, and a pane row taking
+pixels would be the first place an analyst's number reaches a style. A
+scale is the vocabulary `span`, `columns` and `gap` already speak.
+
+**`aspect:` instead of, or beside, `height`.** An aspect ratio means the
+height still follows the width, so it does not help a stored frame whose
+panes sit in different columns, and it would be a second way to say what a
+height says. Not needed, and the issue itself said one of the two was
+probably enough.
+
+**A frame-level maximum.** It sizes every pane at once but is a second way
+to say what per pane heights already say, and it cannot make one chart
+shorter than its neighbours. Not needed once panes have a height.
+
+**`rows`, a grid row span.** A different thing: a tall pane beside two
+short ones. It is worth having and is kept apart, since folding it into a
+chart height would make one field mean two things.
+
+**Lift the 20rem cap for everyone.** Changes every existing chart. Unset
+must change nothing.
+
+## Decision
+
+**A pane may carry a `height` of 1 to 5, drawn as a box of that fixed
+height around a bar or line chart. Unset is exactly what it is today.**
+
+| height | box | default size |
+| --- | --- | --- |
+| 1 | `calc(var(--janela-space) * 24)` | 96px |
+| 2 | `calc(var(--janela-space) * 40)` | 160px |
+| 3 | `calc(var(--janela-space) * 56)` | 224px |
+| 4 | `calc(var(--janela-space) * 80)` | 320px |
+| 5 | `calc(var(--janela-space) * 112)` | 448px |
+
+Multiples of the base unit, so a theme that sets `--janela-space` moves the
+whole scale with the rest (ADR 016), and step 4 is today's cap exactly, so
+"tall" means what a chart already is at full width. The class names follow
+ADR 016's `janela-{property}-{scale}`: `janela-h-1` to `janela-h-5`, on a
+`div.janela-chart-box` that wraps the canvas inside the figure, between the
+`figcaption` and the canvas, so ADR 042's structure otherwise stands.
+A host that wants an exact pixel value sets it against the class in its own
+CSS. Inside the box the canvas takes the box's height and the 20rem cap
+does not apply to it; the chart controller builds the chart with
+`maintainAspectRatio: false` when the pane carries a height.
+
+**With no height there is no box.** The markup, the classes, the cap and
+the 2:1 rule are unchanged, so nothing that renders today renders
+differently and `//figure[...]/canvas` still finds a canvas.
+
+**One vocabulary in three places.**
+
+```erb
+<%= janela_pane Order, :revenue, by: :placed_on, as: :line, height: 2 %>
+```
+
+- `Janela::Pane#height`, an integer column that is null when unset,
+  validated to `1..5` the way `span` is to `1..12`, and offered as a
+  select on the pane form (blank is "Automatic").
+- `janela_pane` and `janela_snapshot_pane` take `height:`.
+- The pane URL carries it as `?height=2`, because the pane's content is
+  rendered by the server from that URL, lazily and again on every
+  cross-filter, and a height left out of the URL would be lost on the first
+  refresh. A stored pane already refreshes from its row, which supplies it.
+
+**Height is not part of the pane's identity.** ADR 029 identifies a frame
+by who it is and not what it shows, and a height is a matter of drawing, not
+of which query this is. It stays out of `Query.turbo_frame_id`, which is
+also what lets a host change a pane's height in place without Turbo
+reconciling into a different frame. Two helper panes over an identical query
+that differ only in height still need an `id:`, exactly as two identical
+panes do now.
+
+**A height on a renderer that does not draw a canvas is ignored, not an
+error.** A ring is SVG that scales to its width to a maximum of 16rem
+(ADR 046), a table and a single value have no chart, and a snapshot pane
+draws as its own renderer says. A pane whose renderer is switched from bar
+to doughnut and back keeps the height it had, and a row is not made invalid
+by a setting that is meaningless for what it now shows. What a ring's size
+should be is left open.
+
+## Consequences
+
+- An analyst can shorten or lengthen a chart in a stored frame without
+  changing what it says, and a host can do the same in the helper, from one
+  vocabulary. Nothing about pixels reaches CSS.
+- **A migration for stored frames.** `janela_panes` gains a nullable
+  `height`, additive, so every existing pane is unset and unchanged. A
+  host that uses stored frames runs `bin/rails janela:install:migrations`
+  and `db:migrate`, in `UPGRADING.md` and the post install message
+  (ADR 015). A host that does not use stored frames has nothing to do.
+- **The pane URL grammar grows by one optional query parameter,** which
+  ADR 037 counts as public surface, so it belongs before 1.0 and not after.
+  `docs/theming.md` gains `janela-h-1` to `janela-h-5` and
+  `janela-chart-box` (ADR 036), and the README documents `height:`.
+- The chart controller reads one new value, which says whether a height was
+  set. A height changes when the chart is *built*, so `repoint` to a URL
+  with a different height replaces the pane content and the chart is made
+  again, which Turbo already does on every replacement.
+- A pane can now look too small to read: step 1 is 96px, tall enough for
+  a sparkline and not for a chart with a legend and axis labels. That is the
+  analyst's choice and the scale's lowest rung is deliberately that small.
+- Vitral, the optional theme, does not touch heights: it has no rule for
+  chart sizing and does not set `--janela-space`, so the scale reads the
+  same under it. Sizing is structure and belongs to `janela.css` (ADR 023),
+  and because the classes join the published contract a theme may override
+  them; none has to.
+- Not covered: rings, `rows`, a frame level maximum, and the gallery's
+  configuration form, which offers renderer, granularity and limit and can
+  offer height in a later change without a decision.
+- What would change this decision: a real need for a height between two
+  steps, which is an argument for a sixth step or for a host's own class
+  and not for pixels; or a need for the height to follow a container rather
+  than be fixed, which is a different feature.

data/docs/decisions/048-a-frame-can-be-told-to-refresh-and-janela-never-decides-when.md

@@ -0,0 +1,154 @@
+---
+Date: 2026-09-30
+Status: Proposed
+Related: ADR 003, ADR 009, ADR 025, ADR 029, ADR 030, ADR 032, ADR 034, ADR 037, ADR 039
+Triggers:
+  - a dashboard that should update on a timer, on a push, or when a record changes
+  - a host reaching for Turbo Streams, ActionCable or a broadcast to update a pane
+  - adding an action or an event to the frame controller
+  - a request for a refresh interval, a polling option or a stream_from helper
+  - reloading a pane's turbo frame from a host's own JavaScript
+Topics: cross-filtering, frames, javascript, hotwire, performance, authorisation, public-api
+---
+
+# ADR 048: A Frame Can Be Told to Refresh, and Janela Never Decides When
+
+## Context
+
+The question: should a frame be able to refresh itself every few seconds,
+or stream from something, so a dashboard on a wall stays current? Janela
+has nothing for it. ADR 003 chose Turbo Frames for cross-filtering on the
+ground that a dashboard needs no streams, sockets or client state, and the
+roadmap lists a refresh-scheduling interface among the things that are not
+coming, on the reasoning that a host already has a scheduler and snapshots
+are an ActiveJob. That reasoning was about *snapshots*. Refreshing what a
+reader is looking at, in their browser, is a different request and is not
+answered by it.
+
+Three things were established before deciding.
+
+**Pushing rendered content cannot work, and would leak if it did.** A
+pane's numbers depend on who is asking. `QueriesController#show` renders
+through `janela_scope`, which calls the *request's own controller* for
+`policy_scope` (ADR 032), and the reader's filters live in their browser as
+`q[...]` (ADR 008). A Turbo Stream broadcast renders once, outside any
+request, with no reader whose scope or filters exist, and sends the same
+HTML to every subscriber. Where it rendered at all it would show one
+person's scope to everyone else, which is the failure ADR 032 and ADR 034
+exist to prevent. So the server can never usefully push a pane's content.
+
+**What can be pushed is a nudge, and the refetch belongs to each browser.**
+"Something changed" carries no data. Each browser then re-fetches its own
+panes with its own filters, through the same scoped request it always made,
+so a viewer only ever gets numbers they were entitled to.
+
+**A host can already do the refetch, and it already behaves.** Measured in
+a browser against the demo, with all nine panes of the orders dashboard
+loaded and one value selected:
+
+- Calling `reload()` on every pane, as a timer would, refetched each at the
+  address Janela last asked for, with the filters. None of it was
+  unfiltered.
+- With a click and a timer tick landing in the same instant, so that every
+  pane was reloaded while the click's own refetch was in flight, all seven
+  text panes ended on the filtered numbers, matching the server's answer for
+  each. The supersede rule in the frame controller (#33) already drops a
+  request for an address that is no longer what was asked, so a tick cannot
+  put stale numbers back. One run, not a proof, but the mechanism is the one
+  #33 built for exactly this.
+- Before the panes had scrolled into view, a reload of all nine made seven
+  requests, consistent with a lazy pane that has not loaded not being
+  fetched by a reload.
+
+So the mechanism is not missing. What is missing is a name for it that a
+host can rely on. ADR 030 says a host talks to the frame and does not write
+a pane's `src`, and `reload()` on each frame is the host reaching past the
+frame controller into Turbo, with no promise about what it does for a
+pane that holds words and has no `src` (ADR 039), for a pane whose request
+is already in flight, or for a snapshot pane that is never live (ADR 009).
+
+### What was considered
+
+**A `refresh_every:` option on a frame or a pane.** Rejected. Every tick is
+one query per pane per viewer, so an interval is a decision about load, and
+ADR 025 bounds what one query may ask for and says nothing about how often
+a page asks. Somebody has to own that number, and it is the host, who knows
+its database, its audience and whether the wall display is one browser or
+two hundred. A setting would also put a polling interval where an analyst
+can edit it, which ADR 016 keeps numbers out of. If the numbers are
+expensive, snapshots are the answer, not a faster poll.
+
+**A `stream_from` helper, or broadcasting the rendered pane.** Rejected for
+the scope reason above. A helper that only sent the nudge would be a thin
+wrapper over `turbo_stream_from` and a custom action, which the host writes
+in a line, and Janela would then own a transport it has no view of.
+
+**Doing nothing, and telling hosts to call `reload()`.** Rejected, because
+the unsupported parts above are exactly where it goes wrong quietly: a
+content pane, a snapshot pane, a lazy pane forced to load early, or a pane
+restarted for no reason while it is already fetching the newest thing.
+
+## Decision
+
+**The frame controller gains one action, `refresh`, which re-fetches the
+panes that are live and loaded at what was last asked, and Janela provides
+no timer, interval, transport or stream.**
+
+```html
+<button data-action="janela--frame#refresh">Refresh</button>
+```
+
+```js
+// a timer the host owns, paused while the tab is hidden
+setInterval(() => { if (!document.hidden) frame.dispatchEvent(new CustomEvent("janela--frame:refresh")) }, 3000)
+
+// or a nudge from ActionCable, a Turbo Stream custom action, anything
+```
+
+It is also an event the frame listens for, `janela--frame:refresh`, wired
+the way `repoint` is (ADR 030), so code outside the frame can ask without
+holding a reference to the controller.
+
+**What refresh does.** For each pane the frame controller manages, it
+re-fetches the address last asked for, with the reader's filters and any
+host-fixed `where` (ADR 040), through the same supersede rules a click uses.
+It leaves alone:
+
+- a pane with no live address: a pane that holds words or a host partial
+  (ADR 039), and a snapshot pane (ADR 009);
+- a pane that has not loaded yet, so a lazy pane still loads when it scrolls
+  into view and a refresh does not pull the whole page forward;
+- a pane whose request for the current address is already in flight, since
+  it is about to show the newest thing.
+
+**It is a nudge in the other direction too.** Refresh reads no data and
+sends none, so it cannot show anyone anything they could not already see:
+every fetch it causes is the ordinary scoped request (ADR 032).
+
+**Where the timer and the transport live.** In the host's code, documented
+as recipes with the cost stated: a tick is one query per pane per viewer,
+so pause it while the tab is hidden and choose an interval the database can
+carry. The README gains a short section, and `docs/composing.md` may carry
+the longer recipes.
+
+## Consequences
+
+- A wall dashboard is a `setInterval` and one line, a "refresh" button is
+  one attribute, and a push from a background job is an ActionCable channel
+  and one line of JavaScript. Janela owns none of the three, and none of
+  them can leak across readers.
+- **Additive, so it does not need to land before 1.0.** A new action and a
+  new event are additions to the frame controller's surface, which ADR 037
+  freezes for changes and not for additions. That is why this is filed for
+  after 1.0. The name is worth choosing well (`refresh` and
+  `janela--frame:refresh` sit beside `clear` and `repoint`).
+- The supersede rule (#33) becomes load bearing for something new: a tick
+  arriving during a click's fetch. Build must test that deliberately, by
+  holding a response in flight, rather than rely on the single run above.
+- A host that polls carries the load of it. This ADR states that; it does
+  not bound it.
+- Nothing changes for a host that does not use it.
+- What would change this decision: a measured case where a host cannot
+  reasonably own the timer, which would be an argument for a helper that
+  only wires a host-supplied interval, never one that chooses it; or a
+  way to broadcast that renders per reader, which Turbo does not offer.

data/docs/decisions/049-the-null-group-is-one-more-value-in-a-selection.md

@@ -0,0 +1,143 @@
+---
+Date: 2026-09-30
+Status: Accepted
+Related: ADR 008, ADR 024, ADR 025, ADR 028, ADR 037, ADR 040, ADR 043
+Triggers:
+  - selecting the (none) group together with a value
+  - a filter that carries both _in and _null for one dimension
+  - changing what a pair of filter parameters means, or how they combine
+  - the frame controller's handling of the null group in toggle
+  - a host's where: or default_where naming a value and the null group
+Topics: cross-filtering, ransack, urls, dsl, accessibility, roadmap
+---
+
+# ADR 049: The Null Group Is One More Value in a Selection
+
+## Context
+
+#69: with a chart of A, B and (none) you can select A and B together but not
+A and (none). This is ADR 024 working as written. It made the null group
+exclusive within its dimension, because a click writes `channel_in[]=web` for
+a value and `channel_null=1` for the group, Ransack ANDs its conditions, and
+the pair asks for rows whose channel is both null and web. That returns zero
+rows without saying so, and the ADR chose to refuse the combination over
+rendering an empty dashboard. What it could not offer was a way to say "web
+or none", and a reader now wants exactly that.
+
+Measured against the demo (channel is nil on one row, `phone` on one and
+`web` on two), through Janela's own filter path:
+
+| Filter | Rows |
+| --- | --- |
+| `channel_in: [web]` and `channel_null: 1` | 0 |
+| `channel_in: [web, nil]` | 2 (Ransack drops the nil: no null rows) |
+| `channel_in: [web, ""]` | 2 (same) |
+| `channel_eq_any: [web, nil]` | refused, not an allowed predicate (ADR 025) |
+| `g[]` with `m: or` | refused, and ADR 024 rejected it for an unreadable URL |
+| `channel_not_in: [phone]` | 2 (SQL drops the null rows) |
+
+So nothing Ransack offers through Janela's allowed predicates says "A or none".
+
+**But Ransack can say it if Janela asks for it.** Given Ransack's own
+grouping, built by Janela and never appearing in a URL:
+
+- `g: [{ m: "or", channel_in: ["web"], channel_null: "1" }]` returns 3, as
+  `WHERE channel IN ('web') OR channel IS NULL`.
+- Merged with another filter it combines as AND:
+  `status IN ('paid') AND (channel IN ('web') OR channel IS NULL)`, 2 rows.
+- Through an association it keeps the join:
+  `LEFT OUTER JOIN customers ... WHERE (customers.region IN ('APAC') OR
+  customers.region IS NULL)`.
+
+So the union is expressible without a new predicate, a new grammar, or
+anything in the URL a person has to learn.
+
+### What was considered
+
+**A new predicate, `in_or_null`.** `q[channel_in_or_null][]=web`. Rejected.
+It is a second way to spell a selection that Janela already spells with two
+keys it already reads, it would be a new entry in ADR 025's list for a
+question that list already answers, and the frame controller would have to
+translate between the two forms when a value is added to a selection that
+held the null group.
+
+**The null inside the `_in` list, as a token such as `(none)`.** Rejected.
+It collides with a real value that is spelled `(none)`, and Ransack drops the
+nil it would have to become.
+
+**`g[]` grouping in the URL.** Still rejected, for ADR 024's reason: the URL
+is one a person reads and edits (ADR 008). Using the grouping *inside* Janela
+is a different thing; nothing in the URL changes.
+
+**Leave it exclusive.** The present state. It costs a question a dashboard
+plainly has ("web or unknown") that can be answered by no gesture.
+
+## Decision
+
+**The null group is one more member of a selection. A dimension that carries
+`_in` (or `_eq`) and `_null` means the union, and the frame controller adds
+and removes the null group like any other value.**
+
+**At the server.** `Definition#filter`, the one choke point every filter
+passes through (ADR 025), validates the parameters exactly as it does now:
+declared dimensions, the allowed predicates, the value ceiling. It then builds
+the result with each such pair for one dimension taken out of the AND and
+applied as an OR of the two, merged back with everything else. The URL is
+what it was:
+
+```
+q[channel_in][]=web&q[channel_null]=1
+```
+
+This applies to a reader's `q[...]`, a host's `where:` (ADR 040) and a
+frame's `default_where` (ADR 043) alike, because they share the choke point.
+Today that pair returns zero rows, so no working link or stored filter depends
+on it.
+
+**It is the inclusions that union, and the exclusions stay an intersection.**
+"A or none" is two ways of being selected, so they OR. `not_in` with
+`not_null` is two ways of being ruled out ("anything but A, and not none"),
+so they AND, as they do now. `_null` with `_not_null` remains a contradiction
+and returns nothing.
+
+**At the frame controller.** `toggle` stops treating the null key as
+exclusive. The gestures are ADR 024's, unchanged:
+
+| Gesture | Result |
+| --- | --- |
+| Click (none) | (none) alone is selected |
+| Click a value while (none) is selected | that value alone replaces it |
+| Ctrl or Cmd click (none) | (none) is added to, or removed from, the selection |
+| Ctrl or Cmd click a value while (none) is selected | the value is added, (none) stays |
+
+`clearDimension` still clears the dimension's keys when a plain click replaces
+the selection. The highlight needs nothing: a pane already marks `(none)`
+among the selected values (`Query#selected_values`).
+
+## Consequences
+
+- A dashboard can answer "A or none", which nothing could before, and a
+  selection of A, B and (none) is three ordinary members of one set.
+- **ADR 024's exclusivity paragraph is superseded.** Its measurement of the
+  AND stands and is why the union is built explicitly. The rest of 024, the
+  gestures, `_in`, the keyboard, stands. ADR 024's status line says so.
+- **The meaning of a documented pair of parameters changes**, which ADR 037
+  counts as public surface, and is why this belongs before 1.0. It is
+  narrowly breaking: the pair returned no rows before, so the only thing that
+  could depend on it is a link or a stored filter that always showed an empty
+  pane. `CHANGELOG.md` says so under Changed, and no `UPGRADING.md` entry is
+  needed because there is nothing to change.
+- The chart and the table need no change of their own: the null group is
+  already a label with a filter, and the selection highlight already includes
+  it.
+- A snapshot taken under the pair stores its filters as it does any others
+  (ADR 009), and a snapshot taken before this holds the zero rows it always
+  did. Stored results are never re-run.
+- Build must test the choke point for `_in` and `_eq` each with `_null`,
+  through an association, alongside a filter on another dimension, with the
+  value ceiling still enforced, with `not_in` and `not_null` still
+  intersecting, and the frame controller in a browser for the four gestures
+  above.
+- What would change this decision: a host needing the union for a *range* on
+  a time dimension, which is an OR of two ranges and a different feature
+  (ADR 045), or a dimension where "none" is not a value at all but an error.