janela 0.15.0 → 0.16.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +29 -0
  3. data/README.md +23 -7
  4. data/UPGRADING.md +34 -0
  5. data/app/assets/javascripts/janela/chart_controller.js +148 -42
  6. data/app/assets/stylesheets/janela.css +7 -0
  7. data/app/controllers/janela/panes_controller.rb +2 -2
  8. data/app/controllers/janela/queries_controller.rb +11 -0
  9. data/app/controllers/janela/snapshot_queries_controller.rb +1 -0
  10. data/app/helpers/janela/frames_helper.rb +35 -7
  11. data/app/models/janela/pane.rb +26 -2
  12. data/app/models/janela/query.rb +245 -25
  13. data/app/views/janela/frames/show.html.erb +2 -2
  14. data/app/views/janela/panes/_form.html.erb +46 -0
  15. data/app/views/janela/queries/_query.html.erb +18 -5
  16. data/config/locales/en.yml +19 -1
  17. data/db/migrate/20261029000001_add_series_to_janela_panes.rb +9 -0
  18. data/db/migrate/20261029000003_add_ignore_unknown_filters_to_janela_panes.rb +8 -0
  19. data/docs/agents.md +33 -2
  20. data/docs/charts.md +148 -0
  21. data/docs/decisions/018-a-table-is-the-universal-renderer.md +1 -0
  22. data/docs/decisions/053-an-agent-reaches-janela-through-tools-the-host-scopes.md +1 -0
  23. data/docs/decisions/054-a-chart-reads-numbers-the-way-its-measure-formats-them.md +1 -1
  24. data/docs/decisions/056-the-demo-counts-its-own-visits-and-an-agent-arranges-the-dashboard.md +51 -0
  25. data/docs/decisions/057-a-host-is-told-about-the-agent-tools-and-a-generator-sets-them-up.md +197 -0
  26. data/docs/decisions/058-the-deployed-demo-is-reached-over-ssh-and-its-visits-frame-survives-a-reset.md +94 -0
  27. data/docs/decisions/059-a-host-can-tell-janelas-own-pages-that-its-layout-draws-charts.md +91 -0
  28. data/docs/decisions/060-the-demo-tells-search-engines-what-it-is-and-shows-its-own-adoption.md +79 -0
  29. data/docs/decisions/061-the-demo-speaks-brazilian-portuguese-under-a-prefix-and-the-gem-stays-english.md +118 -0
  30. data/docs/decisions/062-a-time-pane-can-accumulate-and-carry-more-series-on-two-axes.md +282 -0
  31. data/docs/decisions/063-a-pane-can-ignore-a-filter-its-model-cannot-apply.md +147 -0
  32. data/docs/decisions/INDEX.md +23 -15
  33. data/docs/roadmap.md +6 -4
  34. data/lib/generators/janela/mcp/mcp_generator.rb +51 -0
  35. data/lib/generators/janela/mcp/templates/janela-mcp.tt +50 -0
  36. data/lib/janela/definition.rb +38 -2
  37. data/lib/janela/dimension.rb +9 -1
  38. data/lib/janela/doctor.rb +10 -1
  39. data/lib/janela/measure.rb +8 -0
  40. data/lib/janela/tools.rb +33 -2
  41. data/lib/janela/version.rb +1 -1
  42. data/lib/janela.rb +8 -0
  43. metadata +14 -16
@@ -0,0 +1,79 @@
1
+ ---
2
+ Date: 2026-10-14
3
+ Status: Proposed
4
+ Related: ADR 010, ADR 052, ADR 056
5
+ Triggers:
6
+ - changing what the demo tells a search engine or a link preview
7
+ - adding a call from the demo to a service outside it
8
+ - showing a number in the demo that the demo did not count itself
9
+ - adding a page to the demo that should or should not be indexed
10
+ Topics: demo, seo, marketing, privacy, dependencies, dogfooding
11
+ ---
12
+
13
+ # ADR 060: The Demo Tells Search Engines What It Is, and Shows Its Own Adoption
14
+
15
+ ## Context
16
+
17
+ The demo is Janela's front door, and a search for it is how most hosts will meet
18
+ the gem. The maintainer wants to measure how well it is found, and the first
19
+ thing that measuring needs is that there is something to find.
20
+
21
+ ### Measured
22
+
23
+ Against the live demo, 2026-10-14.
24
+
25
+ | Thing | State |
26
+ | --- | --- |
27
+ | `/robots.txt`, `/sitemap.xml` | both 404 |
28
+ | meta description, canonical link, Open Graph tags | none on any page |
29
+ | `lang` on the `html` element | absent |
30
+ | `<h1>` on `/name` | none |
31
+ | titles | one per page, though `Gallery` and `Vitral` say nothing a search result could use |
32
+ | RubyGems | the gem answers `api/v1/gems/janela.json`: 8,315 downloads, 147 on the current version |
33
+ | GitHub | the repository answers `api.github.com/repos/...`: 1 star |
34
+
35
+ The Dashboards, snapshot and frame pages are the engine's own, and they take any
36
+ filter as a query string, so a crawler that follows their links meets an
37
+ unbounded number of URLs that all show the same page.
38
+
39
+ ## Decision
40
+
41
+ **The demo says what each page is, in the head of the page, and keeps crawlers
42
+ off the pages that are only filters.**
43
+
44
+ - Every page has a `lang`, a title, a meta description, a canonical link to its
45
+ own path with no query string, and Open Graph and Twitter tags. A page with
46
+ nothing of its own to say gets the site's description rather than none.
47
+ - A documentation page's description is its first paragraph, read from the
48
+ document, so it cannot drift from what ships in the gem (ADR 010).
49
+ - `robots.txt` names the sitemap and disallows `/dashboards`, `/snapshots` and
50
+ `/frames`, the pages that are one dashboard under unbounded filters.
51
+ `sitemap.xml` lists the pages worth finding: the home page, the guides, the
52
+ decisions, the gallery, the name, the example and the visits page. One
53
+ mechanism for keeping a page out, and it is the robots file.
54
+
55
+ **The footer shows RubyGems downloads and GitHub stars, fetched by the server
56
+ and cached for an hour.** They link to the gem's page and the repository. A
57
+ failed fetch shows the plain links as before and is not retried for five
58
+ minutes, so a service being down costs the page nothing and the demo does not
59
+ hammer it. The numbers are fetched, not stored: Janela owns no data store, and a
60
+ count that is only ever read from its source cannot disagree with it.
61
+
62
+ **Nothing is fetched in the test suite.** The footer is on every page, so a call
63
+ from it would put the network in every test. It is switched on in development
64
+ and production, and a test that wants it says so.
65
+
66
+ ## Consequences
67
+
68
+ - **The demo makes two outbound calls**, at most one pair an hour. They carry no
69
+ information about a visitor, because the server makes them and not the
70
+ browser, so no visitor's address reaches either service.
71
+ - **A visitor's first view after the cache expires waits for the fetch**, up to
72
+ the timeout. That is accepted for a demo, and the stale-while-refresh answer
73
+ is for when it is not.
74
+ - **This is the baseline, not the measuring.** Search Console and page speed
75
+ data, a referrer on the visits recorder and the adoption numbers as stored
76
+ history are separate decisions, and the first of them needs `PageView` to
77
+ change, which ADR 056 keeps cookie free.
78
+ - **What would change this decision:** the counts being wanted as history, which
79
+ is the day they stop being fetched and become rows.
@@ -0,0 +1,118 @@
1
+ ---
2
+ Date: 2026-10-14
3
+ Status: Proposed
4
+ Related: ADR 023, ADR 036, ADR 054, ADR 056, ADR 060
5
+ Triggers:
6
+ - adding a language to the demo, or a page that is translated
7
+ - generating a route helper for a page under the /pt-BR prefix
8
+ - deciding whether the gem should ship a second language
9
+ - mounting the engine inside a scope with a dynamic segment
10
+ - writing a month, a number or a date label in a chart
11
+ Topics: i18n, demo, routing, seo, engines, host-integration, dogfooding
12
+ ---
13
+
14
+ # ADR 061: The Demo Speaks Brazilian Portuguese Under a Prefix, and the Gem Stays English
15
+
16
+ ## Context
17
+
18
+ Janela is the Portuguese word for window, and the demo has never said so in
19
+ Portuguese. The maintainer wants a language picker and Brazilian Portuguese
20
+ (`pt-BR`) as a homage to the name. Two questions decide the shape: whether the
21
+ gem or only the demo carries the language, and where the language lives in the
22
+ address.
23
+
24
+ The README already tells a host to override Janela's words in its own locale
25
+ file, and every string the gem shows is one `en.yml` of 63 keys under `janela.*`.
26
+
27
+ ### Measured
28
+
29
+ Against the demo, 2026-10-14.
30
+
31
+ **The language can be a prefix, including for the mounted engine.** With the
32
+ whole demo inside `scope "(:locale)", locale: /pt-BR/` and the engine mounted
33
+ inside it, `/pt-BR/dashboards` serves the engine's index, its frame page and its
34
+ editor. Every `href`, `action`, `data-` URL and Turbo Frame `src` on those pages
35
+ carries `/pt-BR/`, so cross-filtering stays in the language. `/fr/orders` is a
36
+ 404, because the constraint admits only the language we have.
37
+
38
+ **A positional route argument fills the locale slot.** With an optional leading
39
+ segment, `doc_path("agents")` generated `locale: "agents"` and then failed for
40
+ want of a slug, on every English page, until the controller's
41
+ `default_url_options` always carried a `locale` key, nil for English. The same
42
+ call in a test outside a request has no controller, so the route set carries
43
+ `locale: nil`, which an integration test merges, and the system tests' base class
44
+ says it for their own helper object.
45
+
46
+ **The engine repeated the language as a query parameter.** Its own links came out
47
+ as `/pt-BR/dashboards/684?locale=pt-BR`: the mount point already carries the
48
+ language in its path, so a `locale` option has nowhere to go but the query
49
+ string. `_routes` inside `url_options` says which route set is being generated
50
+ for, so the host drops `locale` for the engine's routes and keeps it for its own.
51
+
52
+ **A month label was English only.** `Dimension::LABELS["month"]` used
53
+ `strftime("%b %Y")`, which does not read a locale. A clicked label maps back to
54
+ its bucket through a lookup built from the labels (`Query`), not by parsing the
55
+ text, so a translated label cannot break a time click.
56
+
57
+ **Numbers already follow the locale.** The measure reads `number.format` for its
58
+ delimiter and `number_to_rounded` for the separator, so with Rails' own Portuguese
59
+ data `$375.00` reads `$375,00`.
60
+
61
+ ### What was considered
62
+
63
+ **The gem ships `pt-BR`.** Rejected for now, by the maintainer. A second language
64
+ in the gem is upkeep for every release, and the demo adding it in its own locale
65
+ file is the worked example of how any host does.
66
+
67
+ **A cookie or the `Accept-Language` header.** Rejected. Neither is in the
68
+ address, so a link cannot carry the language, a search engine cannot see the
69
+ second page, and the visits page promises no cookie.
70
+
71
+ **A subdomain.** Rejected. It is a second site to certify and deploy for one
72
+ language.
73
+
74
+ **Translating every page.** Rejected as a first step. The guides and decisions are
75
+ the gem's own markdown, rendered as they ship (ADR 010), and are English.
76
+
77
+ ## Decision
78
+
79
+ **English is the root and Brazilian Portuguese is under `/pt-BR`, one address per
80
+ language. The gem ships English only, and the demo adds Portuguese in its own
81
+ locale files.**
82
+
83
+ - The pages translated are the home page, the orders dashboard, the visits page,
84
+ the menu, the footer and every string Janela's own pages show. A page that is
85
+ not translated is still reachable under `/pt-BR`, says so at the top, and
86
+ names the English page as its canonical address, so there is never a second
87
+ copy of English text competing with the first.
88
+ - A translated page carries `hreflang` alternates for both languages and
89
+ `x-default`. The sitemap lists the translated pages in both. `robots.txt`
90
+ keeps the Portuguese dashboards out as it does the English ones (ADR 060).
91
+ - The picker is a link in the menu, named in its own language, that goes to the
92
+ same page in the other language and keeps its filter.
93
+ - Brazilian Portuguese for Rails' own words (month names, number formats) is the
94
+ `rails-i18n` gem, in the demo's Gemfile and not the gem's.
95
+ - **The gem's month label reads the locale** when the host has month names for it,
96
+ and falls back to English when it has not, so a host that never set a locale
97
+ sees exactly what it did. This is the one change to the gem.
98
+ - A frame is `quadro` and a pane is `painel`, the words a Brazilian reader of a
99
+ dashboard already uses, and not the window words (`esquadria`, `vidraça`) that
100
+ are prettier and mean nothing to someone looking for a chart.
101
+
102
+ ## Consequences
103
+
104
+ - **The Portuguese is written by an assistant and has not been read by a native
105
+ speaker.** It should be before this is shown to people. It is a draft to be
106
+ corrected, and the copy is in two files, so correcting it is an edit.
107
+ - **Every `Rails.application.routes` helper in the demo is under an optional
108
+ segment.** A new helper called with a positional argument outside a controller
109
+ needs `locale: nil` or a named argument. The route set and the system test
110
+ base class carry the former.
111
+ - **A missing key fails a test.** Test runs raise on a missing translation, and a
112
+ test compares the Portuguese files with the English ones, because fallbacks
113
+ would otherwise hide a gap behind English text.
114
+ - **The visits dashboard records Portuguese pages at their own path**, so the
115
+ language a visitor read is visible in the data the demo already shows.
116
+ - **What would change this decision:** a host asking for Portuguese from the
117
+ gem, which is the day `config/locales/pt-BR.yml` moves from the demo into the
118
+ gem and `janela.pt-BR.yml` here is deleted.
@@ -0,0 +1,282 @@
1
+ ---
2
+ Date: 2026-10-29
3
+ Status: Proposed
4
+ Related: ADR 002, ADR 005, ADR 006, ADR 007, ADR 009, ADR 018, ADR 020, ADR 029, ADR 037, ADR 045, ADR 046, ADR 047, ADR 051, ADR 054, ADR 055
5
+ Triggers:
6
+ - a running total, a cumulative line, a to-date figure over time
7
+ - drawing two measures on one chart, or a bar beside a line
8
+ - a second value axis, a right axis, or two scales on one plot
9
+ - a series bucketed by a different date column than the pane's
10
+ - adding a column to janela_panes, or a parameter to the pane URL
11
+ - choosing the colour of a series rather than of a category
12
+ - a chart legend, or a title on an axis
13
+ Topics: charts, time, dsl, query layer, panes, urls, public-api, frames, styling
14
+ ---
15
+
16
+ # ADR 062: A Time Pane Can Accumulate, and Carry More Series on Two Axes
17
+
18
+ ## Context
19
+
20
+ #90, raised from a real install building an adoption chart: sign-ups to
21
+ date and activations to date as two lines on the left axis, new sign-ups
22
+ per week as bars on a right axis, one chart, filtered by the panes around
23
+ it. The host built it as a partial pane (ADR 039) holding its own Chart.js
24
+ controller and its own query. It draws, and it is wrong in three ways that
25
+ matter: it does not change when the reader clicks another pane, it is not a
26
+ row an analyst can edit, and it is a second chart implementation the host
27
+ has to keep in step with the gem's.
28
+
29
+ Four gaps stand between a pane and that chart, measured against `main`
30
+ before deciding.
31
+
32
+ **Nothing accumulates.** `Definition#series` returns one value per bucket
33
+ and `Query#result` hands it on. A chart of orders per month cannot be a
34
+ chart of orders to date without a column on the model that stores the
35
+ running count, which is presentation in the schema.
36
+
37
+ **One measure, one dimension.** `Query` holds exactly one of each. The
38
+ chart partial hands the controller one `labels` and one `values` array,
39
+ and `chart_controller.js` builds one dataset over one `y` scale. Two
40
+ measures over the same weeks are two panes, which cannot share an axis.
41
+
42
+ **The renderer is the pane's.** A pane is bars or a line, never both.
43
+
44
+ **A second value axis does not exist.** A count of five beside a total of
45
+ five hundred is a line on the floor.
46
+
47
+ Three facts shape the answer.
48
+
49
+ **Groupdate's keys differ by column type.** A date column's week buckets
50
+ come back as `Date` (`Mon, 31 Aug 2026`), a timestamp's as `Time` in the
51
+ zone. Two series over two columns can only share an x axis if their keys
52
+ are made the same kind first; `in_time_zone` gives the same instant for
53
+ both, and `Dimension#span` already reads a bucket that way.
54
+
55
+ **A list of hashes survives a URL if each starts with the same key.**
56
+ Rack's nested query parser opens a new hash in `series[][...]` when a key
57
+ repeats and otherwise adds to the last one, so `a[][x]=1&a[][y]=4&a[][x]=3`
58
+ gives the first hash the `y` meant for the second. Rails' `to_query`
59
+ leaves keys in their given order inside a `[]` namespace rather than
60
+ sorting them, measured: `{ series: [{ measure: "m", by: "d" }, { measure:
61
+ "n", as: "bar" }] }` writes `measure` first in each and parses back whole.
62
+ A series led by its measure is unambiguous; one that is not may not be.
63
+
64
+ **Chart.js draws a mixed chart from a type per dataset** and a second
65
+ scale from a second entry in `scales`, so the canvas needs nothing new
66
+ shipped (ADR 004).
67
+
68
+ ### What was considered
69
+
70
+ **A stored column for the running total.** The host's workaround today.
71
+ Rejected: ADR 051 refused presentation in the schema for companions, and
72
+ a running total is the measure's own numbers added up, which is one line
73
+ of Ruby after the read.
74
+
75
+ **A `combo` renderer.** A fifth renderer whose dataset shape is its own.
76
+ Rejected: it would be a renderer that means "several of the other two",
77
+ and a table could not be its fallback without learning the same shape
78
+ anyway (ADR 018). The series are what is new; which of two existing
79
+ renderers each one uses is one word on it.
80
+
81
+ **A second pane that is told to share an axis with the first.** Two
82
+ panes, two queries, one canvas somehow. Rejected: a pane is one turbo
83
+ frame with one URL (ADR 005, ADR 029), and two of them cannot be one
84
+ `<figure>`.
85
+
86
+ **Series on a categorical pane.** Revenue and orders by status as grouped
87
+ bars. Not built, and not refused for ever: a categorical pane colours by
88
+ position in the result (ADR 046), a series needs colour by series, and
89
+ which rule wins is a decision of its own. The one host that needs this
90
+ needs it over time.
91
+
92
+ **A series with its own granularity.** Rejected: the point of a series is
93
+ that it shares the pane's buckets, and a week beside a month is two x
94
+ axes.
95
+
96
+ **Colour by category on a multi-series bar.** ADR 046 draws a bar in the
97
+ colour of its position. Rejected for a pane with series: a bar series over
98
+ thirty weeks in eight colours and a grey, beside a legend that names one
99
+ series, is a wrong picture. A pane with series colours by series.
100
+
101
+ **Formatted labels on every point of a line.** ADR 054 refused this and
102
+ the refusal stands. What a running total wants is its latest value, once,
103
+ at the end of the line.
104
+
105
+ **A per-series `title` left out, naming by measure alone.** Considered,
106
+ because a measure is already named for what it means on the dashboard
107
+ (ADR 002) and a host can declare `measure :sign_ups, count: true` beside
108
+ `measure :activations, count: true` for the same aggregate. Not enough on
109
+ its own: the same measure over the same dimension, once to date and once
110
+ per week, is the first chart anyone draws with this, and two legend
111
+ entries reading `Orders` is a wrong picture. A series may carry a title,
112
+ and the one Janela writes says what it is.
113
+
114
+ ## Decision
115
+
116
+ **A time pane may carry `cumulative`, a running total of its measure
117
+ across its buckets, and `series`, up to three more measures of the same
118
+ model over the same buckets, each drawn as a line or as bars, each on the
119
+ left axis or a right one. Unset is exactly what a pane is today.**
120
+
121
+ ```erb
122
+ <%= janela_pane Order, :orders, by: :placed_on, as: :line, granularity: :month,
123
+ cumulative: true,
124
+ series: [
125
+ { measure: :orders, by: :shipped_on, cumulative: true, title: "Orders shipped to date" },
126
+ { measure: :orders, as: :bar, axis: :right, title: "Orders per month" }
127
+ ] %>
128
+ ```
129
+
130
+ **`cumulative` is a yes or a no, and a time pane's.** The running total
131
+ is summed in Ruby after the read, so the SQL, the buckets, the filters and
132
+ the click on a bucket are what they always were (ADR 045). A stored
133
+ snapshot keeps per-bucket numbers and a cumulative view of it is summed
134
+ the same way on read, so nothing about what is stored changes (ADR 009).
135
+ Only a measure that adds up accumulates, a count or a sum: an average, a
136
+ minimum, a maximum or a ratio is refused with its reason, as is a series
137
+ with `cumulative` over one, because their sum is a number that means
138
+ nothing. On a categorical pane or a single value it is refused with its reason,
139
+ not ignored: a running total over categories sorted by their measure is a
140
+ different chart that nobody has asked for, and a row whose dimension is
141
+ changed to a category is told so on the form rather than quietly drawing
142
+ something else.
143
+
144
+ **A series is a hash of up to six words, and the first is `measure`.**
145
+
146
+ | key | takes | unset means |
147
+ | --- | --- | --- |
148
+ | `measure` | a measure the model declares | required |
149
+ | `by` | a time dimension the model declares | the pane's own dimension |
150
+ | `cumulative` | `1` or `0` | `0` |
151
+ | `as` | `line` or `bar` | the pane's renderer when it is one of those, else `line` |
152
+ | `axis` | `left` or `right` | `left` |
153
+ | `title` | words for the legend and the table header | Janela writes one |
154
+
155
+ Only what the model declared, by the name it declared it under, as
156
+ companions are bounded (ADR 025, ADR 051). A series by a different time
157
+ dimension shares the pane's granularity: its buckets are read with the
158
+ same `week_start`, every series' buckets are joined into one sorted set
159
+ through `in_time_zone`, and a bucket a series has no row in is zero for a count or a sum, so
160
+ `Orders shipped to date` is flat across a month nothing shipped rather
161
+ than absent, and a gap for an average, minimum, maximum or ratio, which
162
+ have no value in an empty bucket. Joined buckets beyond 10,000 are a
163
+ refusal, so a stray year in a column cannot build a hundred thousand. Two series that name the same measure, dimension and
164
+ `cumulative` are refused as one series drawn twice. Four series are a
165
+ refusal that says three.
166
+
167
+ **The title Janela writes** is the measure's name, then `by` and the
168
+ dimension's name when the series is over a dimension other than the
169
+ pane's, then `to date` when it is cumulative: `Orders`, `Orders by
170
+ Shipped on to date`. The same rule names the pane's own series, so a
171
+ cumulative pane's legend and table header read `Orders to date`. A
172
+ `title` replaces all of it and is escaped like any other string.
173
+
174
+ **The pane's own measure is the first series, and it is the left axis.**
175
+ The pane's measure, dimension, renderer and `cumulative` are what they
176
+ were. What a click writes is the pane's dimension's range (ADR 045), and
177
+ the x axis is the pane's buckets. Filters are applied to every series the
178
+ same way: the reader's selection on the pane's own dimension is set aside
179
+ for all of them, because the pane shows the alternatives to it, and a
180
+ selection on any other dimension, including a series' own, narrows that
181
+ series as it narrows every pane.
182
+
183
+ **A bar and a line draw the series as datasets. A table draws them as
184
+ columns. A ring and a single value ignore them,** as a ring ignores a
185
+ height (ADR 047) and every renderer but a table ignores companions (ADR
186
+ 051), so a pane switched between renderers keeps them. The table is the
187
+ fallback on a surface with no chart runtime (ADR 018), with a header row
188
+ as a table with companions has, the series' columns after the measure's
189
+ and before any companions. A stored snapshot holds no series, as it holds
190
+ no companions, so a snapshot pane with them shows the base table.
191
+
192
+ **With series, the chart shows a legend and colours by series.** The
193
+ pane's own series is `--janela-series-1`, the next `--janela-series-2`,
194
+ and so on, in the order given (ADR 046's palette, by series rather than by
195
+ category). Bars are drawn behind lines. A selected bucket is solid and the
196
+ rest faded, in every dataset, as a single series is today. Without series
197
+ nothing about a chart's colour, legend or interaction changes.
198
+
199
+ **A right axis exists when a series asks for it, and then both axes are
200
+ titled.** A right axis draws no grid lines across the plot, so the left
201
+ axis's grid is the only one. Each axis's title is the titles of the
202
+ series on it, in order, because an untitled second scale is the way two
203
+ scales mislead. When every series on the right axis is bars, that axis is
204
+ scaled so the tallest bar reaches about a third of the plot, so bars sit
205
+ under the lines rather than fighting them. A line on the right axis is
206
+ scaled to its own data like any line.
207
+
208
+ **`value_labels` on a line writes its latest value at the end of the
209
+ line, in text ink.** One label, not one per point, which is what ADR 054
210
+ refused. It applies to every line series on a pane that asks for it. Bars
211
+ on a pane with series draw no labels: their slots are shared and the all
212
+ or none rule of ADR 054 would almost always say none. A single-series bar
213
+ chart is unchanged. This supersedes the sentence in ADR 054 that a line
214
+ ignores the flag, and nothing else in it.
215
+
216
+ **One vocabulary in three places,** as height and companions are:
217
+
218
+ - `Janela::Pane#cumulative`, a nullable boolean, and `Janela::Pane#series`,
219
+ a nullable JSON array of hashes, validated on save against the model's
220
+ declared measures and dimensions through the same `Query` that would
221
+ refuse the request. The pane form offers a checkbox and one blank
222
+ series slot beyond those filled, each a group of plain selects since
223
+ the engine's pages have no JavaScript (ADR 018), wherever it offers a
224
+ granularity: on a pane over a time dimension, or one with no dimension
225
+ chosen yet.
226
+ - `janela_pane` and `janela_snapshot_pane` take `cumulative:` and
227
+ `series:`.
228
+ - The pane URL carries `?cumulative=1` and `series[][measure]=orders&
229
+ series[][by]=shipped_on&series[][cumulative]=1`, each series led by its
230
+ measure, because the server draws the pane again from that URL on every
231
+ cross-filter.
232
+
233
+ **`cumulative` and `series` are part of the pane's identity when set.**
234
+ A measure to date and the same measure per period are two answers that
235
+ may share a page, as top five and bottom five are (ADR 055), so a set
236
+ `cumulative` joins `Query.turbo_frame_id` and an unset one leaves every
237
+ existing id alone. Two panes that differ only in their series draw
238
+ different charts, so a set `series` joins it as a short digest of the
239
+ words given, however they were spelled; none leaves the id as it was.
240
+ `cumulative` is read from the flag the way the server reads it, so `"0"`
241
+ is no in the URL and in the id alike.
242
+
243
+ ## Consequences
244
+
245
+ - The adoption chart is a row, or one `janela_pane`, and it cross-filters,
246
+ falls back to a table, and is edited on the pane form like any other.
247
+ - **A migration for stored frames.** `janela_panes` gains a nullable
248
+ boolean `cumulative` and a nullable JSON `series`, additive, in one
249
+ migration. A host using stored frames runs `bin/rails
250
+ janela:install:migrations` and `db:migrate`, written in `UPGRADING.md`.
251
+ The doctor's `unmigrated-columns` check is taught both.
252
+ - **`Janela::Tools` learns both attributes** in the same change, with the
253
+ series' keys in its schema (ADR 053).
254
+ - **The pane URL grammar grows by one parameter and one array of hashes.**
255
+ ADR 037 counts that as public surface. The array of hashes is the first
256
+ structured parameter in the grammar, and it is readable because each
257
+ hash is a short sentence led by its measure.
258
+ - **A chart with series carries three more data attributes** (`series`,
259
+ `label`, `axes`), and `labels`, `values` and `formatted` keep meaning
260
+ the pane's own series, so a host that subclasses the controller and
261
+ reads `datasets[0]` sees what it saw.
262
+ - The running total is summed from the buckets Groupdate returned, so it
263
+ starts at the first bucket with a row, not at the beginning of time. A
264
+ host that fixes the frame's range with `where:` starts the count there.
265
+ That is the right answer for a filtered dashboard and the surprising one
266
+ for a chart meant to begin at zero on launch day; a `where:` from the
267
+ launch date is the way to say so.
268
+ - A series by a different time dimension counts rows where that column
269
+ falls in the bucket, so a null is not counted anywhere. That is what
270
+ makes `Orders by Shipped on` the orders that shipped, with no filter.
271
+ - Up to three more queries per pane, bounded as companions are (ADR 051).
272
+ - Text labels on a canvas are not available to a screen reader, which is
273
+ as true of the lines themselves (ADR 042) and is why the table is
274
+ always there.
275
+ - Not decided here: series on a categorical pane; a series with its own
276
+ granularity or its own filter; stacking; a legend a keyboard can
277
+ operate; a second axis for a single series. Each starts from the table
278
+ above.
279
+ - What would change this decision: a host that needs a grouped bar over
280
+ categories, which reopens the colour rule and is the first thing to
281
+ revisit; or a dashboard whose series come from two models, which is an
282
+ argument about what a pane is and not about this.
@@ -0,0 +1,147 @@
1
+ ---
2
+ Date: 2026-10-29
3
+ Status: Proposed
4
+ Related: ADR 003, ADR 005, ADR 008, ADR 012, ADR 025, ADR 035, ADR 037, ADR 040, ADR 043, ADR 053
5
+ Triggers:
6
+ - a frame holding panes over more than one model
7
+ - a pane showing "That request is not allowed on this pane" after a click on another pane
8
+ - deciding what a pane does with a filter key its model does not declare
9
+ - adding a boolean to a pane, a column to janela_panes, or a parameter to the pane URL
10
+ - a setting that could live on the frame or on the pane
11
+ Topics: cross-filtering, ransack, panes, frames, urls, public-api, security
12
+ ---
13
+
14
+ # ADR 063: A Pane Can Ignore a Filter Its Model Cannot Apply
15
+
16
+ ## Context
17
+
18
+ #92, found trialling a frame that holds panes over two models: the demo's
19
+ orders, with a status, a region and a date, and the demo's page views,
20
+ with a page and a date. Clicking `paid` on an orders pane writes
21
+ `q[status_in][]=paid` to the frame (ADR 003, ADR 008), the frame hands
22
+ it to every pane, and the page views pane answers with "That request is
23
+ not allowed on this pane" where its number was.
24
+
25
+ Measured against the demo before deciding. `Query#applicable_filters`
26
+ drops only the pane's own dimension, which is the cross-filtering rule:
27
+ the pane you clicked shows the alternatives to what you picked. Every
28
+ other key goes to `Definition#filter`, where `reject_dropped_filters!`
29
+ compares what Ransack applied with what was asked and raises
30
+ `BadRequest` for the difference: `PageView does not allow filtering on
31
+ status_in`. Ransack itself, asked for `status_in` and `viewed_on_gteq`
32
+ on page views, applied `viewed_on` and dropped `status` without a word.
33
+
34
+ That refusal is deliberate and right (ADR 025). Ransack discards a
35
+ condition its allowlist does not permit, so a typo in a hand written
36
+ `q[...]` would quietly show an unfiltered number, which is the worst
37
+ thing this library can do. Nothing about that changes here. What is
38
+ wrong is only its reach: a key another pane's model declares is not a
39
+ mistake, it is a click the reader made on a pane beside this one, and
40
+ the honest answer is for this pane to stay as it is.
41
+
42
+ A key both models declare under the same name, such as a date, or one
43
+ reached through an association, already works, because it matches a
44
+ declared dimension on the second model too.
45
+
46
+ ### What was considered
47
+
48
+ **Drop undeclared keys on every pane.** The smallest change and the
49
+ wrong one: it removes the loud failure ADR 025 chose, for every host,
50
+ to suit the one frame that mixes models.
51
+
52
+ **A setting on the frame.** A frame is where the mixing happens, so a
53
+ frame that says "my panes ignore what they cannot apply" reads well.
54
+ Rejected, for how a pane is drawn. A pane is fetched on its own URL in
55
+ its own request (ADR 005), lazily and again on every cross-filter, and
56
+ a hand written `janela_frame do` block has no record at all, so the
57
+ setting would have to travel on each pane's URL anyway to reach the
58
+ request that draws it. A frame column would then be a fourth place to
59
+ say a per-pane thing, beside the row, the helper and the URL that every
60
+ other option already uses, and it could not reach a hand written frame.
61
+
62
+ **Derive it: drop a key that another pane in the same frame declares.**
63
+ The most precise rule, since a key no pane can apply is still a typo.
64
+ Rejected, because only a stored pane fetched through its frame knows
65
+ what the other panes are; a `janela_pane` on its own URL does not, and
66
+ the two shapes would behave differently for the same click.
67
+
68
+ **Have the frame controller send each pane only the keys its model
69
+ declares.** The browser does not know the models' dimensions, and
70
+ teaching it would put the allowlist in the page (ADR 025 keeps it on
71
+ the server).
72
+
73
+ ## Decision
74
+
75
+ **A pane may carry `ignore_unknown_filters`, a yes or a no. When set,
76
+ the reader's filters whose keys Ransack would not apply to the pane's
77
+ model are dropped before the query, and the pane draws as if they were
78
+ never written. Unset is exactly what a pane is today: a key the model
79
+ does not declare is refused with its reason.**
80
+
81
+ ```erb
82
+ <%= janela_frame do %>
83
+ <%= janela_pane Order, :revenue, by: :status, as: :bar %>
84
+ <%= janela_pane PageView, :views, by: :page, ignore_unknown_filters: true %>
85
+ <% end %>
86
+ ```
87
+
88
+ **Only the reader's filters are dropped.** A host's fixed `where:`
89
+ (ADR 040) and a frame's `default_where` (ADR 043) are the host's and the
90
+ analyst's own words about this pane and stay refused when wrong, as they
91
+ are validated today. A key the model does declare but with a predicate
92
+ its dimension does not allow, such as `status_matches`, is still refused:
93
+ that is a misuse of a real key, not another model's key.
94
+
95
+ **What is dropped is what Ransack would drop,** read the same way
96
+ `reject_dropped_filters!` reads it, so the two cannot disagree about
97
+ which keys belong to the model. A key that survives is applied exactly
98
+ as it would be on any pane.
99
+
100
+ **It is opt in, per pane, because the pane is what knows.** A pane is
101
+ the unit that is fetched, refused and drawn, and the analyst placing a
102
+ page views pane on an orders frame is the one who knows it will be
103
+ clicked past. A pane that never meets another model keeps the loud
104
+ failure, and a typo on it is still a typo.
105
+
106
+ **One vocabulary in three places,** as `value_labels` is (ADR 054):
107
+
108
+ - `Janela::Pane#ignore_unknown_filters`, a nullable boolean offered on
109
+ the pane form as a checkbox.
110
+ - `janela_pane` takes `ignore_unknown_filters:`.
111
+ - The pane URL carries `?ignore_unknown_filters=1`, because the server
112
+ draws the pane again from that URL on every cross-filter.
113
+
114
+ `janela_snapshot_pane` does not take it: a snapshot's filters were
115
+ fixed when it was taken and the request's are ignored (ADR 009).
116
+
117
+ **It is not part of the pane's identity** (ADR 029). What a pane does
118
+ with a stray key does not say which query it is.
119
+
120
+ ## Consequences
121
+
122
+ - A frame can hold panes over two models and a click on either side
123
+ leaves the other side standing. That is the first thing a host
124
+ building a page over events and the records they belong to tries.
125
+ - **A migration for stored frames.** `janela_panes` gains a nullable
126
+ boolean, additive, so every existing pane is unset and refused as
127
+ before. A host using stored frames runs `bin/rails
128
+ janela:install:migrations` and `db:migrate`, in `UPGRADING.md`. The
129
+ doctor's `unmigrated-columns` check is taught the column.
130
+ - **`Janela::Tools` learns the attribute** in the same change (ADR 053).
131
+ - **The pane URL grammar grows by one optional parameter,** which ADR
132
+ 037 counts as public surface.
133
+ - A pane that ignores a key is silently unfiltered by it, which is the
134
+ very thing ADR 025 refuses by default. It is accepted here because the
135
+ analyst asked for it on that pane, and because the alternative is a
136
+ pane that cannot share a frame with another model at all. The log
137
+ says nothing when a key is dropped: a dropped key is the normal case
138
+ on such a pane, not a finding.
139
+ - A dimension reached through an association is addressed by the host
140
+ as `<association>_<column>`, so two models can share a click only when
141
+ they spell the key the same. A way for a host to alias that name is a
142
+ separate question, not decided here.
143
+ - What would change this decision: a frame that needs the derived rule,
144
+ a key dropped only when another pane in the frame declares it, which
145
+ would need the pane URL to carry the frame's vocabulary and is an
146
+ argument about what a pane URL says; or a host that wants the drop
147
+ logged, which is a setting that would have to earn itself.