janela 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69f4c0147424e4d9350bcee373b832e922f54b1686acce5c80fa776432a288c6
-  data.tar.gz: ec2f91ec4c87dcfeb49154b54e0cda105f293e8b56580fb774750011fb9277df
+  metadata.gz: 83aee3a06740005fd9bf9e81ddc12c6de350ea4b8f6fce34899a94869e0f2615
+  data.tar.gz: cd6d59364454c17e80302de50377a5ca2ca3f2db2ceb2bd58be8ca6a29d6b878
 SHA512:
-  metadata.gz: 38e32300abc75aa9b738d63b2d7f638dff0d9f153e19aa32f1cb5cbd422702c4e236bc93b87e7c4474836bbd3bfddfad4f83fbaa95d523efee8e6b82b6246b12
-  data.tar.gz: fe82fff29b230ecab68eb8c14e162d214ee9c1666ead178145c73ffe776e635b8acd59fa8cc1df1011a9f091b2d50e9d9fe299e67142657ed59e69fa1d70d120
+  metadata.gz: 670dcac643875f4723159a3f8ecc4429d9feb115dcf58c7336fc823f8290eff4bb3c25316893dc382958753d43e689c4572416d9371b7fa36e0e23447640052c
+  data.tar.gz: 6c423db2685c60bb12a6f3878ea956fe926dfde507a9a373d71be3f42092322a22a6958ecf6cc54aee68e6535fd8690e9d4320a0a55da2aa6eed4e40074b0734

data/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.16.0] - 2026-10-29
+
+### Added
+
+- **A time pane can read as a running total, and carry more series on two axes.** `janela_pane Order, :orders, by: :placed_on, as: :line, granularity: :month, cumulative: true` draws orders to date rather than orders per month, summed after the read so the buckets, the filters and a click on a bucket are unchanged. The same pane takes `series:`, up to three more measures of the same model over the same buckets, each optionally by a different time dimension (`by: :shipped_on`), each a running total or not, each drawn as a line or as bars (`as:`), each on the left axis or a right one (`axis:`), with a `title` for the legend or one Janela writes (`Orders by Shipped on to date`). Every series' buckets are joined into one axis and a series with no row in a bucket reads zero there (a gap, for a measure that does not add up). A chart with series shows a legend, colours by series rather than by category, draws bars behind lines, and when a series is on the right both axes are titled; a right axis holding only bars is scaled so the tallest reaches about a third of the plot. A table draws them as columns, which is the fallback with no chart runtime; a ring ignores them; a snapshot holds none. `cumulative` is refused on a category pane or a single value, and on an average, minimum, maximum or ratio, which do not add up; a set one joins the pane's frame id, and so does a digest of the series. A bucket an average, minimum, maximum or ratio series has no row in is a gap rather than a zero, and series that would span more than 10,000 buckets are refused. Both are a checkbox and plain selects on the pane form, attributes in `Janela::Tools`, and `?cumulative=1` and `series[][measure]=...` in the pane URL, each series led by its measure. Until now the chart a host wanted, sign-ups to date and activations to date as lines with new sign-ups per week as bars, was a partial pane with its own Chart.js that did not cross-filter and was not a row. Stored panes need a migration; see `UPGRADING.md` (ADR 062, #90).
+- **A pane can ignore a filter its model cannot apply.** On a frame holding panes over two models, a click on one side wrote a key the other side's model does not declare, and that pane answered "That request is not allowed on this pane" where its number was. `janela_pane PageView, :views, by: :page, ignore_unknown_filters: true`, the checkbox on the pane form, `ignore_unknown_filters` in `Janela::Tools` or `?ignore_unknown_filters=1` in the pane URL drops the reader's keys Ransack would not apply to the pane's model before the query, so the pane draws as if they were never written. A key the model declares is applied as before, a declared key with a disallowed predicate is still refused, and a host's `where:` and a frame's `default_where` are still refused when wrong. Unset, nothing changes: a key nobody declares is still refused with its reason (ADR 025). Stored panes need a migration; see `UPGRADING.md` (ADR 063, #92).
+
+- **A time pane's month label is written in the reader's language.** `Oct 2026` used `strftime`, which does not read a locale, so a host that set one still drew English months. It now uses the locale's abbreviated month names when the host has them (`out 2026` with Rails' Portuguese data, from the `rails-i18n` gem), and falls back to the English it always drew when it has not, so a host that never set a locale sees no change. A clicked label still maps back to its bucket through a lookup, not by reading the text, so a time click is unaffected (ADR 061).
+
+- **`bin/rails generate janela:mcp` writes the server an agent reaches the tools through.** It creates `bin/janela-mcp`, a stdio server on the official Ruby SDK, and a `janela` entry in `.mcp.json` so Claude Code and other clients find it. Both are yours once written. The file is the adapter from `docs/agents.md` with the scope left for you to write, and until you write it every tool refuses to read with a message saying so. It refuses to run outside development. The generator leaves an existing server or entry alone, and tells you to add `gem "mcp"` rather than editing your Gemfile. The scope cannot be your controller's `policy_scope`, because outside a request that method answers a different question and reads the wrong rows (ADR 057).
+
+- **`janela:doctor` tells a host the agent tools exist.** When `bin/janela-mcp` is missing it ends with one line, `Optional: let an agent arrange dashboards. bin/rails generate janela:mcp (docs/agents.md).` It is not a finding, so it is never counted, cannot be silenced and does not change whether the task passes. It is printed on a clean run too (ADR 057).
+
+- **`Janela.charts_on_own_pages`, so Janela's own frame page can draw its charts.** That page showed every bar and line pane as its table, because its minimal layout loads no chart runtime and the engine cannot see whether a host's layout does (ADR 018). A host that has given those pages a layout registering the two Stimulus controllers and loading Chart.js can now say so, once, and the page draws and cross-filters like its own. It defaults to `false`, so a host that sets nothing sees exactly what it did. A host that sets it without the runtime gets an empty hole where the table was. The pane page opened directly is unchanged (ADR 059).
+
+- **`update_frame`, a write tool that changes a frame's columns and gap.** An agent arranging a dashboard could add and move panes but not widen the grid they sit in. It takes `frame_id`, `columns` and `gap`, finds the frame through your scope like every other tool, and refuses a value Janela does not draw with the frame's own reason. A frame's name, key and owner are still yours to set, and any other attribute is refused. Off unless you build the tools with `write: true` (ADR 057).
+
+### Changed
+
+- **`value_labels` on a line chart now writes the line's latest value at its end.** A line ignored the flag (ADR 054); it now draws one label, the last point's formatted value, in the same text colour a bar's labels use. A line that never set the flag is unchanged, and a bar chart's labels are what they were (ADR 062).
+
+## [0.15.0] - 2026-10-13
+
+### Added
+
+- **A category pane can be sorted by its measure either way, or by its label.** `janela_pane Order, :revenue, by: :customer, limit: 5, sort: :asc` shows the bottom five, and `janela_pane Order, :revenue, by: :cycle, as: :bar, sort: :label` draws a chart in the dimension's own order. `sort` takes `desc` (the default, and what every pane did before), `asc`, `label` and `label_desc`, as a select on the pane form and in `Janela::Tools`, and travels in the pane URL as `?sort=asc`. The limit follows the order, so `asc` with a limit is the real smallest rows and not the largest turned round, which the view could not do. A label order is the database sorting the column, so a number is in numeric order, a date in date order and a string in the database's collation. The `(none)` group is last in every order, because SQLite and PostgreSQL disagree about where NULL sorts. A time pane is always in time order and ignores it. Stored panes need a migration; see `UPGRADING.md`. `Janela.sorts` lists the four for a page that offers them as controls (ADR 055, #75, #80).
+
+### Changed
+
+- **Groups tied on the measure now come out by label.** Two groups with the same value used to come out in whatever order the database produced, which with a `limit` decided which of them was shown at all. They are now in label order, ascending, in either direction. A pane with no ties draws exactly what it did. A set `sort` is part of the pane's frame id (`..._top5_asc`), and an unset one leaves every existing id as it was (ADR 055).
+
 ## [0.14.0] - 2026-10-07
 
 ### Added
@@ -289,6 +320,8 @@ First alpha, installed from GitHub for testing in a single host application.
 - Only models that declare a `janela` block are addressable over HTTP.
 - ADRs 001 to 004 in `docs/decisions/`, shipped inside the gem.
 
+[0.16.0]: https://github.com/retail-tasker/janela/releases/tag/v0.16.0
+[0.15.0]: https://github.com/retail-tasker/janela/releases/tag/v0.15.0
 [0.14.0]: https://github.com/retail-tasker/janela/releases/tag/v0.14.0
 [0.13.0]: https://github.com/retail-tasker/janela/releases/tag/v0.13.0
 [0.12.0]: https://github.com/retail-tasker/janela/releases/tag/v0.12.0

data/README.md

@@ -27,7 +27,7 @@ Janela is an alpha on [rubygems.org](https://rubygems.org/gems/janela). It is a
 
 ```ruby
 # Gemfile
-gem "janela", "~> 0.14"
+gem "janela", "~> 0.16"
 ```
 
 ```ruby
@@ -42,7 +42,7 @@ Janela reads nothing until your `ApplicationController` says what a visitor may
 private def policy_scope(model) = model.all
 ```
 
-If you use stored frames or snapshots, run `bin/rails janela:install:migrations && bin/rails db:migrate` (see Frames below), and finish with `bin/rails janela:doctor`, which checks the install and says what to fix. The rest of this section is the JavaScript.
+If you use stored frames or snapshots, run `bin/rails janela:install:migrations && bin/rails db:migrate` (see Frames below), and finish with `bin/rails janela:doctor`, which checks the install and says what to fix. If you want an agent to arrange dashboards for you, `bin/rails generate janela:mcp` sets that up (see Giving an agent access below). The rest of this section is the JavaScript.
 
 Then register the two Stimulus controllers. How depends on how your app ships JavaScript.
 
@@ -163,7 +163,7 @@ measure :pass_rate, average: :score, precision: 1, suffix: "%"   # 66.7%
 measure :orders, count: true                                     # 1,234
 ```
 
-Precision defaults to what the schema already says. Counting rows has no decimal places, a `decimal(10, 2)` column reads to the cent, and summing an integer column stays whole. Declare `precision:` where the schema has nothing to say, such as averaging an integer, or where you want something else. Thousands are delimited with your app's locale.
+Precision defaults to what the schema already says. Counting rows has no decimal places, a `decimal(10, 2)` column reads to the cent, and summing an integer column stays whole. Declare `precision:` where the schema has nothing to say, such as averaging an integer, or where you want something else. Thousands are delimited with your app's locale, and a month on a time pane is written with its month names.
 
 Formatting is rendering, never rounding. The number itself reaches a snapshot and an order clause at full precision, so a snapshot taken last month reads back under a format you declare today.
 
@@ -224,7 +224,7 @@ Compose panes on any page. Each pane is a Turbo Frame; clicking a value in one r
 <% end %>
 ```
 
-A pane with no `by:` is the measure's single total, the KPI tile. `limit: 10` keeps the top ten rows or bars. `as:` is `:table` by default, `:bar` for a Chart.js bar chart, `:doughnut` or `:pie` for a part-to-whole split, or `:line`, which suits a time dimension: `janela_pane Order, :revenue, by: :placed_on, as: :line, granularity: :week`. A chart fills its container's width at Chart.js's default aspect ratio, so wrap it in an element with the width you want. Clicking a bar does exactly what clicking a table value does.
+A pane with no `by:` is the measure's single total, the KPI tile. `limit: 10` keeps the top ten rows or bars, and `sort:` changes which ten (see below). `as:` is `:table` by default, `:bar` for a Chart.js bar chart, `:doughnut` or `:pie` for a part-to-whole split, or `:line`, which suits a time dimension: `janela_pane Order, :revenue, by: :placed_on, as: :line, granularity: :week`. A chart fills its container's width at Chart.js's default aspect ratio, so wrap it in an element with the width you want. Clicking a bar does exactly what clicking a table value does.
 
 A doughnut or a pie is drawn on the server as SVG with a legend of buttons beside it, so it is in the page before any JavaScript runs and can be operated from the keyboard through the legend. Bars, doughnut slices and pie slices are drawn in a palette of eight colours by position, first to eighth, and every value after the eighth in one neutral, so a ring suits a handful of values: `limit: 8` keeps it readable. A ring cannot show a negative value, so a pane with one is drawn as a table and says so. The palette is `--janela-series-1` to `--janela-series-8` and `--janela-series-other` in [docs/theming.md](docs/theming.md) (ADR 046).
 
@@ -232,10 +232,24 @@ A doughnut or a pie is drawn on the server as SVG with a legend of buttons besid
 
 **Prominence.** A single value is `2rem` unless the pane says how much it matters: `prominence: 1` is a footnote at `1.25rem`, `2` is what it already is, and `3` is the hero number at `3.5rem` (`janela_pane Order, :orders, prominence: 3`). Three steps rather than a length, the same as `span` and `height`, so a stored pane takes it too, from the pane form. The label stays small at every step. With none set nothing changes, and a table, a chart and a ring ignore one (ADR 050).
 
-**Value labels.** A bar chart shows a value only in its tooltip unless the pane asks for it on the bar: `value_labels: true` (`janela_pane Order, :expedited_rate, by: :channel, as: :bar, value_labels: true`), or the checkbox on the pane form. The label is the same string the tooltip shows, the measure's own format, drawn beyond the end of the bar: above a positive one and below a negative. It is all or none: if any label is wider than its bar's share of the chart, none is drawn, rather than some bars carrying a number and others not. Make the chart wider or `limit:` the bars. With none set nothing changes, and a line, a ring, a table and a single value ignore it (ADR 054).
+**Sorting.** A breakdown by a category is largest first by default. `sort: :asc` puts the smallest first, so `limit: 5` is the bottom five, and `sort: :label` and `sort: :label_desc` order by the dimension's own value, which suits a label whose text is already the natural order, such as a period code (`janela_pane Order, :revenue, by: :cycle, as: :bar, sort: :label`). The limit follows the order. A number or a date column sorts as itself, and text sorts by your database's collation, which is not the same everywhere. The `(none)` group is always last. Groups that tie on the measure come out by label. It is a select on the pane form, `sort:` in `Janela::Tools`, and `?sort=` in the pane URL. A time series is always in time order and ignores it (ADR 055).
+
+**Value labels.** A bar chart shows a value only in its tooltip unless the pane asks for it on the bar: `value_labels: true` (`janela_pane Order, :expedited_rate, by: :channel, as: :bar, value_labels: true`), or the checkbox on the pane form. The label is the same string the tooltip shows, the measure's own format, drawn beyond the end of the bar: above a positive one and below a negative. It is all or none: if any label is wider than its bar's share of the chart, none is drawn, rather than some bars carrying a number and others not. Make the chart wider or `limit:` the bars. On a line it writes the line's latest value, once, at the end of the line, which is what a running total wants (ADR 062). With none set nothing changes, and a ring, a table and a single value ignore it (ADR 054).
 
 **Companion columns.** A table can carry up to three more columns beside its label, each a measure or a dimension the model declares: `janela_pane Order, :expedited_rate, by: :customer, companions: [:orders, :region]` reads as customer, expedited rate, orders and region, under a header row. A measure companion is its own number, formatted as it declares, so a rate can sit beside the count behind it: 75% of four and 75% of forty are different things to act on. A dimension companion shows a value only where every row of that label's group shares one, and is blank where they differ, since grouping by it would show a label twice and picking one would show an arbitrary value as fact. Order, limit, filters and clicking a label are the primary measure's and are unchanged. Only a table draws companions, a stored snapshot shows the base table, and a time pane may carry measures but not dimensions. Each companion is one more query, which is why it is three at most (ADR 051).
 
+**Running totals and more series.** A time pane can read as a total to date rather than a figure per period: `cumulative: true` (`janela_pane Order, :orders, by: :placed_on, as: :line, granularity: :month, cumulative: true`), or the checkbox on the pane form. The running total is summed after the read, so the buckets, the filters and a click on a bucket are what they were, and it is refused on a category pane or a single value, or on a measure that does not add up (an average, minimum, maximum or ratio), rather than drawing something else. A set `cumulative` is part of the pane's frame id, since a measure to date and per period are two different answers that may share a page. The same pane can carry up to three more series over the same buckets, each a measure the model declares, optionally over a different time dimension of the same model, each drawn as a line or as bars, on the left axis or a right one:
+
+```erb
+<%= janela_pane Order, :orders, by: :placed_on, as: :line, granularity: :month, cumulative: true,
+      series: [
+        { measure: :orders, by: :shipped_on, cumulative: true, title: "Orders shipped to date" },
+        { measure: :orders, as: :bar, axis: :right, title: "Orders per month" }
+      ] %>
+```
+
+A series takes `measure`, `by` (a time dimension; the pane's own when left out), `cumulative`, `as` (`line` or `bar`; the pane's renderer when it is one of those, else `line`), `axis` (`left` or `right`) and `title`. Every series' buckets are joined into one axis, from the first bucket any of them has to the last, and a series with no row in a bucket reads zero there (a gap for an average, minimum, maximum or ratio, which have no value in an empty bucket), so `Orders shipped to date` is flat across a month nothing shipped. A series by another time dimension counts rows where that column falls in the bucket, so a null is not counted anywhere. The title Janela writes when you leave it out is the measure's name, then `by` and the dimension's when it is not the pane's, then `to date` when it accumulates. A chart with series shows a legend and colours by series, `--janela-series-1` for the pane's own and the rest in order, bars behind lines; a right axis exists only when a series asks for it, and then both axes are titled with the series on them, and a right axis that holds only bars is scaled so the tallest reaches about a third of the plot. A table draws the series as columns after the measure's, which is also what a surface with no chart runtime shows; a ring ignores them and a stored snapshot holds none. On a chart with series, `value_labels` writes each line's latest value at the end of the line and labels no bar. Filters narrow every series the same way, and a click on the chart writes the pane's own dimension's range. It is rows on the pane form, `cumulative:` and `series:` in `Janela::Tools`, and `?cumulative=1` and `series[][measure]=orders&series[][by]=shipped_on` in the pane URL, each series led by its measure (ADR 062).
+
 **Reconfiguring a pane in place**, a renderer toggle, a granularity switcher, a "show top 20" control, takes two things: name the pane with `id:`, then ask the frame to repoint it.
 
 ```erb
@@ -333,7 +347,7 @@ The engine serves an index and a page per frame at the mount root, so you can in
 
 No model's route key is all digits, so a frame id and a pane URL cannot be confused. Both pages read through `policy_scope(Janela::Frame)`, so a frame your scope does not return is a 404 rather than a page, and so is a pane row under it.
 
-These pages render in Janela's own minimal layout, which loads the gem's stylesheet and nothing else. It does not load Turbo or Stimulus, because those come from your bundler and the engine cannot name them. So Janela's own pages are correct, styled, **static** dashboards: every pane is rendered inline and the numbers are right, filters in the URL apply, and nothing cross-filters when you click. A chart pane needs Chart.js, so on these pages it renders as its table (ADR 018); put a frame on your own page, where your JavaScript is, for the interactive version. Each page links back to your application's root, which you can rename in your own locale file under `janela.actions.home`.
+These pages render in Janela's own minimal layout, which loads the gem's stylesheet and nothing else. It does not load Turbo or Stimulus, because those come from your bundler and the engine cannot name them. So Janela's own pages are correct, styled, **static** dashboards: every pane is rendered inline and the numbers are right, filters in the URL apply, and nothing cross-filters when you click. A chart pane needs Chart.js, so on these pages it renders as its table (ADR 018); put a frame on your own page, where your JavaScript is, for the interactive version. If you have given these pages a layout of your own that registers the two Stimulus controllers and loads Chart.js, say so with `Janela.charts_on_own_pages = true` in `config/initializers/janela.rb`, and the frame page draws its charts and cross-filters too (ADR 059). Leave it off otherwise: the engine cannot see what your layout loads, and a chart with no runtime is an empty hole. Each page links back to your application's root, which you can rename in your own locale file under `janela.actions.home`.
 
 The noun in the headings is `Janela::Frame.model_name.human`, so rename it in your own locale file rather than in a setting:
 
@@ -376,6 +390,8 @@ A host with no tenancy defines nothing, gets a nil owner, and is correct: nothin
 
 The dashboard's filters live in the page URL as the same `q[...]` parameters, so a reload keeps them and a filtered dashboard is a link you can send: `/reports/orders?q[status_in][]=paid` renders filtered before any JavaScript runs. A pane ignores filters on its own dimension, so clicking a value re-scopes the rest of the dashboard rather than collapsing the pane you clicked. Clicking a bucket on a time pane filters the others to the range it covers. Every selected value is marked `aria-pressed="true"` on tables and drawn solid against faded siblings on charts, so it can be styled and read.
 
+**A frame over two models.** Every pane is handed the frame's filters, and a pane refuses a key its model does not declare, because Ransack would otherwise drop it and show an unfiltered number (ADR 025). On a frame that holds panes over two models that refusal reaches a click it should not: `paid` clicked on an orders pane is `q[status_in][]=paid` to a page views pane, which has no status and would answer "That request is not allowed on this pane" where its number was. A pane can say it ignores what it cannot apply: `janela_pane PageView, :views, by: :page, ignore_unknown_filters: true`, or the checkbox on the pane form, or `?ignore_unknown_filters=1` in the pane URL. The keys Ransack would drop are dropped before the query, a key the model does declare is applied as on any pane, a declared key with a predicate the dimension does not allow is still refused, and a host's `where:` and a frame's `default_where` are still refused when wrong. Unset, a pane is what it always was, so a typo on a pane that never meets another model still fails loudly. Two models share a click only when they spell the key the same, which for a dimension reached through an association is `<association>_<column>` (ADR 063).
+
 **Selecting more than one.** Ctrl or Cmd click adds a value to the selection and takes it out again, leaving the rest alone, which is how every list in every operating system already behaves. A plain click selects one value and replaces whatever was selected, or clears the dimension if that value was the only one. It works the same on a chart. The (none) group, the rows that have nothing there, is a member of the selection like any value: Ctrl or Cmd click it beside a value and the panes show the rows that have that value or nothing (`q[channel_in][]=web&q[channel_null]=1`), where `not_in` and `not_null` together still mean neither (ADR 049). All of it works from the keyboard too: a value is a real `<button>`, so Enter is a click and Ctrl or Cmd with Enter adds. `Escape` clears the frame's filters, and those are the only two keys Janela binds, both only while focus is inside the frame, because a single letter belongs to your application and to any text field on the page (ADR 024). A pane with no matching rows renders a `.janela-empty` paragraph. A group whose dimension is null is labelled `(none)` and filters with Ransack's null predicate rather than an empty string. Only models that declare a `janela` block can be requested over HTTP.
 
 ### Pane URLs
@@ -390,6 +406,8 @@ Every pane has its own URL under the mount, and a Turbo Frame in a dashboard loa
                                                 orders revenue by region where status is paid
 /dashboards/orders/revenue/placed_on?granularity=week&as=line
                                                 orders revenue by placed_on, per week, as a line
+/dashboards/orders/orders/placed_on?cumulative=1&series[][measure]=orders&series[][by]=shipped_on&series[][cumulative]=1
+                                                orders to date by placed_on, with orders by shipped_on to date beside it
 ```
 
 The model is its route key (`orders`, `sales_orders`), then the measure, then optionally the dimension. Where an analyst would say *by*, the URL has a `/`; *where* is a `q` filter; *as a bar chart* is `?as=bar`; *top ten* is `?limit=10`; *as of* a snapshot is `/snapshots/:id/` in front. Category panes are always ordered by the measure, largest first; time panes are chronological. A pane opened on its own renders with its filters applied, so a filtered pane is a link you can send someone. ADR 005 has the grammar, ADR 011 the layout it renders in.
@@ -510,7 +528,7 @@ Janela::Tools.all          # name, description, input_schema, read_only
 tools.call("read_pane", pane_id: 4)
 ```
 
-`scope:` is required and is the same answer your `policy_scope` gives, so an agent reads and changes only what the person it acts for can. The read tools list the vocabulary and frames and read a pane's values. The write tools add, change, remove and move panes, and are off unless asked for. Janela serves no MCP endpoint, edits no configuration and depends on no MCP library; [docs/agents.md](docs/agents.md) shows the few lines that register them with the official Ruby SDK.
+`scope:` is required and is the same answer your `policy_scope` gives, so an agent reads and changes only what the person it acts for can. The read tools list the vocabulary and frames and read a pane's values. The write tools add, change, remove and move panes and change a frame's columns and gap, and are off unless asked for. `bin/rails generate janela:mcp` writes the server file and the `.mcp.json` entry so an agent can reach them, and you write the scope in it. Janela serves no MCP endpoint, edits nothing it did not create and depends on no MCP library; [docs/agents.md](docs/agents.md) has the rest.
 
 ### Checking an installation
 
@@ -563,7 +581,7 @@ Deliberately out of scope: natural-language query, a separate data warehouse, a
 
 ## Status
 
-**v0.14.0 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering with multi-selection, bar, line, doughnut and pie charts, pane URLs, shareable dashboard URLs, snapshots, database-backed frames found by owner and key, panes that hold words or a host partial as well as a query, a host-fixed filter no click can remove and a frame's own permanent one beside it, STI subclasses, the engine's own pages for reading and editing them, bar charts that read in their measure's format and can show each bar's value, tools an agent can use to read and arrange a dashboard, and the optional vitral theme work and are covered by unit and real-browser tests, with the classes a theme may target documented in [Theming Janela](docs/theming.md). Not yet built: a visual editor, and narrowing a time pane's own granularity by clicking one of its buckets (a click on a bucket does filter the others). [Vista](docs/roadmap.md), the roadmap, says what 1.0 means and which of these are in it; open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
+**v0.16.0 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering with multi-selection, bar, line, doughnut and pie charts, pane URLs, shareable dashboard URLs, snapshots, database-backed frames found by owner and key, panes that hold words or a host partial as well as a query, a host-fixed filter no click can remove and a frame's own permanent one beside it, STI subclasses, the engine's own pages for reading and editing them, bar charts that read in their measure's format and can show each bar's value, category panes that can be ordered either way by their measure or by their label, tools an agent can use to read and arrange a dashboard, and the optional vitral theme work and are covered by unit and real-browser tests, with the classes a theme may target documented in [Theming Janela](docs/theming.md). Not yet built: a visual editor, and narrowing a time pane's own granularity by clicking one of its buckets (a click on a bucket does filter the others). [Vista](docs/roadmap.md), the roadmap, says what 1.0 means and which of these are in it; open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
 
 ## Development
 

data/UPGRADING.md

@@ -12,6 +12,65 @@ bin/rails janela:doctor
 
 It reads your application and lists what still needs changing.
 
+## 0.15.0 to 0.16.0
+
+One migration step, if you use stored frames.
+
+**Take the pane migration.**
+
+A time pane can now be a running total and carry further series (ADR 062),
+and a pane can ignore a filter its model cannot apply (ADR 063).
+`janela_panes` gains a nullable boolean `cumulative`, a nullable JSON
+`series` and a nullable boolean `ignore_unknown_filters`:
+
+```bash
+bin/rails janela:install:migrations
+bin/rails db:migrate
+```
+
+Every existing pane keeps all three nil and is drawn exactly as before. If you
+never use stored frames, there is nothing to do. `bin/rails janela:doctor`
+names the columns if a stored-frames host skips the step.
+
+**A line chart with `value_labels` gains one label.** Nothing to change: a
+line that asked for value labels and got none now has its latest value
+written at its end. A host that screenshots such a chart will see the new
+text.
+
+**If you built a combined chart as a partial pane,** with its own Chart.js
+controller, it can become a query pane: `cumulative: true` and `series:` on
+`janela_pane`, or the same on the pane form. The partial keeps working as it
+is; it just never cross-filtered.
+
+**A pane that ignores filters still refuses a misused real key.** Nothing to
+change: `ignore_unknown_filters: true` drops only keys the pane's model does
+not declare.
+
+## 0.14.0 to 0.15.0
+
+One migration step, if you use stored frames.
+
+**Take the pane migration.**
+
+A category pane can now be sorted (ADR 055). `janela_panes` gains a nullable
+string `sort`:
+
+```bash
+bin/rails janela:install:migrations
+bin/rails db:migrate
+```
+
+Every existing pane keeps it nil and is ordered exactly as before, largest
+first. If you never use stored frames, there is nothing to do.
+`bin/rails janela:doctor` names the column if a stored-frames host skips the
+step.
+
+**If you carry a patch that orders panes,** it can go: `sort: :asc` and
+`sort: :label` are the options it was written to add. Groups that tie on the
+measure now come out in label order where they used to come out in the
+database's, so a pane that was relying on that has nothing to change and is
+now the same every time.
+
 ## 0.13.0 to 0.14.0
 
 One migration step, if you use stored frames.

data/app/assets/javascripts/janela/chart_controller.js

@@ -7,9 +7,15 @@ Chart.register(...registerables)
 // toggle event a table button emits, so the frame controller cannot tell the
 // difference. Turbo replaces the turbo frame on every cross-filter, so the
 // chart is destroyed on disconnect and rebuilt on connect.
+//
+// labels, values and formatted are the pane's own series. A time pane may
+// carry further series, each a dataset of its own on the left axis or a
+// right one, and then the chart has a legend and both axes are titled
+// (ADR 062). Without them nothing here is different from before.
 export default class extends Controller {
   static values = { type: String, labels: Array, values: Array, filters: Object, title: String,
-                    selected: Array, formatted: Array, tickFormat: Object, fixedHeight: Boolean, valueLabels: Boolean }
+                    selected: Array, formatted: Array, tickFormat: Object, fixedHeight: Boolean, valueLabels: Boolean,
+                    label: String, series: Array, axes: Object }
 
   connect() {
     const controller = this
@@ -20,13 +26,7 @@ export default class extends Controller {
       plugins: this.valueLabelsValue ? [ { id: "janelaValueLabels", afterDatasetsDraw: (chart) => this.drawValueLabels(chart) } ] : [],
       data: {
         labels: this.labelsValue,
-        datasets: [{
-          label: this.titleValue,
-          data: this.valuesValue,
-          backgroundColor: this.colours(),
-          borderColor: this.typeValue === "bar" ? this.colours(0.9) : this.accentColour(0.9),
-          ...this.pointStyle()
-        }]
+        datasets: [ this.primaryDataset(), ...this.seriesValue.map((series, index) => this.seriesDataset(series, index + 1)) ]
       },
       options: {
         animation: false,
@@ -35,24 +35,18 @@ export default class extends Controller {
         // is decided here, when the chart is made: patched onto a chart built
         // with it on, it draws at the wrong size.
         maintainAspectRatio: !this.fixedHeightValue,
-        // Chart.js picks the ticks, so the server cannot format them; each is
-        // formatted here with what the measure declares (ADR 054).
-        scales: { y: {
-          beginAtZero: true,
-          // Room above the tallest bar, and below the lowest, for its label (ADR 054).
-          grace: this.valueLabelsValue ? "10%" : undefined,
-          ticks: { callback(value, index, ticks) { return controller.tickLabel(this, value, index, ticks) } }
-        } },
+        scales: this.scales(),
         // A line is clicked anywhere along its x position rather than on
         // the exact pixel of a point, which on a dense series is a few
-        // pixels wide (ADR 045).
-        interaction: this.typeValue === "line" ? { mode: "nearest", axis: "x", intersect: false } : undefined,
+        // pixels wide (ADR 045). With several series a bucket is read across
+        // all of them at once.
+        interaction: this.interaction(),
         plugins: {
-          legend: { display: false },
+          legend: { display: this.hasSeries() },
           // The server formatted every number for the table, so the tooltip
           // reads the same string rather than formatting a second time here
           // and disagreeing with the cell beside it.
-          tooltip: { callbacks: { label: (item) => this.formattedValue[item.dataIndex] ?? item.formattedValue } }
+          tooltip: { callbacks: { label: (item) => this.formattedFor(item.datasetIndex)[item.dataIndex] ?? item.formattedValue } }
         },
         onClick: (event, elements) => {
           if (elements.length === 0) return
@@ -73,30 +67,133 @@ export default class extends Controller {
     })
   }
 
-  // The same string the tooltip shows, at the end of each bar: above a positive
-  // one and below a negative, where the bar is not. All of them or none: a
-  // label wider than its bar's slot would overlap its neighbour, and hiding only
-  // the ones that collide would label some bars and not others for a reason a
-  // reader cannot see (ADR 054).
+  hasSeries() {
+    return this.seriesValue.length > 0
+  }
+
+  // The pane's own series. Alone it is what it always was: bars coloured by
+  // position and a line in the accent. Beside further series it is the first
+  // colour of the palette, and the others follow in order (ADR 062).
+  primaryDataset() {
+    const property = this.hasSeries() ? this.seriesProperty(0) : null
+    return {
+      label: this.hasSeries() ? this.labelValue : this.titleValue,
+      data: this.valuesValue,
+      type: this.typeValue,
+      yAxisID: "y",
+      order: this.typeValue === "bar" ? 2 : 1,
+      backgroundColor: this.colours(0.25, property, this.typeValue === "bar" && property ? 0.55 : 0.9),
+      borderColor: this.typeValue === "bar" ? this.colours(0.9, property, property ? 0.55 : 0.9) : (property ? this.colour(property, 0.9) : this.accentColour(0.9)),
+      ...this.pointStyle(this.typeValue, property)
+    }
+  }
+
+  // Bars are drawn behind lines and quieter than them, so a line stays the
+  // story over the bars under it.
+  seriesDataset(series, position) {
+    const property = this.seriesProperty(position)
+    return {
+      label: series.label,
+      data: series.values,
+      type: series.type,
+      yAxisID: series.axis === "right" ? "y1" : "y",
+      order: series.type === "bar" ? 2 : 1,
+      backgroundColor: series.type === "bar" ? this.colours(0.2, property, 0.55) : this.colours(0.25, property),
+      borderColor: series.type === "bar" ? this.colours(0.2, property, 0.55) : this.colour(property, 0.9),
+      ...this.pointStyle(series.type, property)
+    }
+  }
+
+  formattedFor(datasetIndex) {
+    return datasetIndex === 0 ? this.formattedValue : (this.seriesValue[datasetIndex - 1]?.formatted ?? [])
+  }
+
+  interaction() {
+    if (this.hasSeries()) return { mode: "index", intersect: false }
+    return this.typeValue === "line" ? { mode: "nearest", axis: "x", intersect: false } : undefined
+  }
+
+  // Chart.js picks the ticks, so the server cannot format them; each is
+  // formatted here with what the measure declares (ADR 054). A right axis
+  // exists only when a series asks for it, draws no grid across the plot,
+  // and both axes are then titled with the series on them. When every series
+  // on the right is bars, that axis is scaled so the tallest bar reaches
+  // about a third of the plot, so bars sit under the lines (ADR 062).
+  scales() {
+    const controller = this
+    const ticks = { callback(value, index, ticks) { return controller.tickLabel(this, value, index, ticks) } }
+    const scales = { y: {
+      beginAtZero: true,
+      // Room above the tallest bar, and below the lowest, for its label (ADR 054).
+      grace: this.valueLabelsValue ? "10%" : undefined,
+      title: this.axisTitle(this.axesValue.left),
+      ticks
+    } }
+
+    const right = this.seriesValue.filter((series) => series.axis === "right")
+    if (right.length > 0) {
+      const barsOnly = right.every((series) => series.type === "bar")
+      const tallest = Math.max(0, ...right.flatMap((series) => series.values))
+      scales.y1 = {
+        position: "right",
+        beginAtZero: true,
+        suggestedMax: barsOnly && tallest > 0 ? tallest * 3 : undefined,
+        grid: { drawOnChartArea: false },
+        title: this.axisTitle(this.axesValue.right),
+        ticks
+      }
+    }
+    return scales
+  }
+
+  axisTitle(text) {
+    return text ? { display: true, text } : undefined
+  }
+
+  // With value labels asked for: on a lone bar chart the same string the
+  // tooltip shows at the end of each bar, above a positive one and below a
+  // negative, all of them or none, since a label wider than its bar's slot
+  // would overlap its neighbour and hiding only the ones that collide would
+  // label some bars for a reason a reader cannot see (ADR 054). On a line its
+  // latest value, once, at the end of the line, which is what a running total
+  // wants (ADR 062). Bars beside other series draw none: their slots are
+  // shared, and all or none would almost always say none.
   drawValueLabels(chart) {
-    const bars = chart.getDatasetMeta(0).data
-    const values = chart.data.datasets[0].data
     const { ctx } = chart
     const { size, family } = Chart.defaults.font
-    const slot = chart.chartArea.width / bars.length
-
     ctx.save()
     ctx.font = `${size}px ${family}`
-    if (this.formattedValue.some((text) => ctx.measureText(text).width > slot)) return ctx.restore()
-
     ctx.fillStyle = Chart.defaults.color
+
+    chart.data.datasets.forEach((dataset, index) => {
+      // A dataset hidden from the legend draws nothing, labels included.
+      if (!chart.isDatasetVisible(index)) return
+      const formatted = this.formattedFor(index)
+      const points = chart.getDatasetMeta(index).data
+      if (dataset.type === "line") {
+        const last = points.at(-1)
+        if (!last || formatted.length === 0) return
+        ctx.textAlign = "right"
+        ctx.textBaseline = "bottom"
+        ctx.fillText(formatted.at(-1), last.x, last.y - 6)
+      } else if (!this.hasSeries()) {
+        this.drawBarLabels(chart, points, dataset.data, formatted)
+      }
+    })
+    ctx.restore()
+  }
+
+  drawBarLabels(chart, bars, values, formatted) {
+    const { ctx } = chart
+    const slot = chart.chartArea.width / bars.length
+    if (formatted.some((text) => ctx.measureText(text).width > slot)) return
+
     ctx.textAlign = "center"
     bars.forEach((bar, index) => {
       const negative = values[index] < 0
       ctx.textBaseline = negative ? "top" : "bottom"
-      ctx.fillText(this.formattedValue[index], bar.x, negative ? bar.y + 4 : bar.y - 4)
+      ctx.fillText(formatted[index], bar.x, negative ? bar.y + 4 : bar.y - 4)
     })
-    ctx.restore()
   }
 
   // Chart.js's own numeric formatter, so the decimals follow the spacing
@@ -105,8 +202,15 @@ export default class extends Controller {
   // (ADR 038), so its ticks are scaled by 100, rounded first because 0.035 * 100
   // is 3.5000000000000004. The measure's precision is not used: it says what one
   // value means, and would print 20.0% at every tick.
+  // The right axis reads in the format of the series on it, so it agrees with
+  // the tooltip. Where several series share it, the first one speaks.
+  tickFormatFor(scale) {
+    if (scale.id !== "y1") return this.tickFormatValue
+    return this.seriesValue.find((series) => series.axis === "right")?.tick_format ?? this.tickFormatValue
+  }
+
   tickLabel(scale, value, index, ticks) {
-    const { prefix = "", suffix = "", ratio = false } = this.tickFormatValue
+    const { prefix = "", suffix = "", ratio = false } = this.tickFormatFor(scale)
     const factor = ratio ? 100 : 1
     const scaled = (number) => Number((number * factor).toPrecision(12))
     const number = Ticks.formatters.numeric.call(scale, scaled(value), index, ticks.map((tick) => ({ ...tick, value: scaled(tick.value) })))
@@ -116,27 +220,29 @@ export default class extends Controller {
   // With nothing selected every bar is solid; with a selection only the
   // selected ones are, and there can be more than one of them. A bar takes
   // the colour for its position in the palette (ADR 046); a line is one
-  // series and keeps the accent.
-  colours(unselected = 0.25) {
+  // series and keeps the accent. A dataset beside other series is given its
+  // own property instead and every bucket takes that one colour, and a bar
+  // there is quieter than a line (ADR 062).
+  colours(unselected = 0.25, property = null, solidAlpha = 0.9) {
     const selected = this.selectedValue.map(String)
     return this.labelsValue.map((label, index) => {
       const solid = selected.length === 0 || selected.includes(String(label))
-      const property = this.typeValue === "bar" ? this.seriesProperty(index) : "--janela-accent"
-      return this.colour(property, solid ? 0.9 : unselected)
+      const chosen = property || (this.typeValue === "bar" ? this.seriesProperty(index) : "--janela-accent")
+      return this.colour(chosen, solid ? solidAlpha : unselected)
     })
   }
 
   // A line shows its selection on its points: the buckets inside the range
   // are solid and larger, the rest faded. A dense series draws no points
   // until one is hovered, so it stays a line (ADR 045).
-  pointStyle() {
-    if (this.typeValue !== "line") return {}
+  pointStyle(type = this.typeValue, property = null) {
+    if (type !== "line") return {}
 
     const selected = this.selectedValue.map(String)
     const dense = this.labelsValue.length > 60
     return {
-      pointBackgroundColor: this.colours(),
-      pointBorderColor: this.colours(),
+      pointBackgroundColor: this.colours(0.25, property),
+      pointBorderColor: this.colours(0.25, property),
       pointRadius: this.labelsValue.map((label) => selected.includes(String(label)) ? 5 : (dense ? 0 : 3)),
       pointHoverRadius: 6
     }

data/app/assets/stylesheets/janela.css

@@ -225,6 +225,13 @@ table.janela-legend button[aria-pressed="true"] { background: var(--janela-accen
   background: transparent;
   color: inherit;
 }
+/* One further series per row on the pane form (ADR 062): its measure first,
+   then what is left unsaid about it, each a plain control. */
+.janela-series { border: 1px solid var(--janela-line); border-radius: calc(var(--janela-space) * 1.5); padding: calc(var(--janela-space) * 3); }
+.janela-series legend { font-size: 0.875rem; font-weight: 600; padding: 0 calc(var(--janela-space) * 1); }
+.janela-series-slot { display: flex; flex-wrap: wrap; align-items: center; gap: calc(var(--janela-space) * 2); padding-top: calc(var(--janela-space) * 3); }
+.janela-series-slot label { font-weight: 400; }
+.janela-series-slot input[type="text"] { flex: 1 1 10rem; }
 .janela-actions { display: flex; flex-wrap: wrap; gap: calc(var(--janela-space) * 3); align-items: center; }
 .janela-actions form { display: inline; }
 .janela-button {

data/app/controllers/janela/panes_controller.rb

@@ -76,8 +76,8 @@ module Janela
       end
 
       def pane_params
-        params.expect(pane: [ :kind, :model, :measure, :dimension, :renderer, :granularity, :limit, :height, :prominence, :value_labels, :span, :title,
-                              :heading, :body, :link, :partial, { companions: [] } ])
+        params.expect(pane: [ :kind, :model, :measure, :dimension, :renderer, :granularity, :limit, :sort, :height, :prominence, :value_labels, :cumulative, :ignore_unknown_filters, :span, :title,
+                              :heading, :body, :link, :partial, { companions: [], series: [ Janela::Query::SERIES_KEYS.map(&:to_sym) ] } ])
       end
 
       def build_pane(choice)

data/app/controllers/janela/queries_controller.rb

@@ -8,15 +8,27 @@ module Janela
         renderer: params.fetch(:as, "table"),
         granularity: params[:granularity],
         limit: params[:limit],
+        sort: params[:sort],
         height: params[:height],
         prominence: params[:prominence],
         value_labels: params[:value_labels],
         companions: params[:companions],
+        cumulative: params[:cumulative],
+        series: series_params,
+        ignore_unknown_filters: params[:ignore_unknown_filters],
         filters: filters,
         fixed: fixed_filters
       )
 
       @result = @query.result(on: janela_scope(@query.model))
     end
+
+    private
+      # A list of hashes, each led by its measure (ADR 062). Anything else in
+      # the parameter is handed to the query to be refused with its reason.
+      def series_params
+        given = params[:series]
+        given.is_a?(Array) ? given.map { |each| each.respond_to?(:permit!) ? each.permit!.to_h : each } : given
+      end
   end
 end

data/app/controllers/janela/snapshot_queries_controller.rb

@@ -13,10 +13,12 @@ module Janela
         renderer: params.fetch(:as, "table"),
         granularity: params[:granularity],
         limit: params[:limit],
+        sort: params[:sort],
         height: params[:height],
         prominence: params[:prominence],
         value_labels: params[:value_labels],
         companions: params[:companions],
+        cumulative: params[:cumulative],
         snapshot: snapshot
       )