janela 0.14.0 → 0.16.0

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

@@ -25,25 +25,35 @@
            "janela--chart-title-value": query.title,
            "janela--chart-selected-value": query.selected_values.to_json,
            "janela--chart-labels-value": result.keys.to_json,
-           "janela--chart-values-value": result.values.map(&:to_f).to_json,
+           "janela--chart-values-value": result.values.map { |measured| measured&.to_f }.to_json,
            "janela--chart-formatted-value": result.values.map { |measured| query.format(measured) }.to_json,
            "janela--chart-tick-format-value": query.tick_format.to_json,
            "janela--chart-filters-value": query.filters_for(result.keys).to_json,
            "janela--chart-fixed-height-value": (true if query.boxed?),
-           "janela--chart-value-labels-value": (true if query.labelled?)
+           "janela--chart-value-labels-value": (true if query.labelled?),
+           # Only with further series, so a chart without them is handed
+           # exactly what it always was (ADR 062).
+           "janela--chart-label-value": (query.series_label if query.series?),
+           "janela--chart-series-value": (query.chart_series(result).to_json if query.series?),
+           "janela--chart-axes-value": query.axis_titles&.to_json
          }) %>
     <%= 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? %>
+    <%# A header row only when there are columns to name: two columns read
+        without one, and a table with none is what it always was (ADR 051).
+        A further series is a column after the measure's and before any
+        companion, which is also the table a chart falls back to (ADR 062). %>
+    <% if query.companion_columns.any? || query.drawn_series.any? %>
       <thead>
         <tr>
           <th scope="col"><%= query.dimension_header %></th>
           <th scope="col"><%= query.measure_header %></th>
+          <% query.drawn_series.each do |series| %>
+            <th scope="col"><%= query.series_label(series) %></th>
+          <% end %>
           <% query.companion_columns.each do |column| %>
             <%= tag.th column.header, scope: "col", class: ("janela-fact" if column.fact) %>
           <% end %>
@@ -63,6 +73,9 @@
             <% end %>
           </td>
           <td><%= query.format(measured) %></td>
+          <% query.drawn_series.each do |series| %>
+            <td><%= query.series_format(series, series.values[label]) %></td>
+          <% end %>
           <% query.companion_columns.each do |column| %>
             <%= tag.td column.cells[label], class: ("janela-fact" if column.fact) %>
           <% end %>

data/config/locales/en.yml

@@ -19,11 +19,15 @@ en:
         renderer: Renderer
         granularity: Granularity
         limit: Rows
+        sort: Order
         span: Width
         height: Height
         prominence: Prominence
         value_labels: Show each bar's value
         companions: Beside the label
+        cumulative: Running total
+        series: More series
+        ignore_unknown_filters: Ignore filters this model cannot apply
         title: Title
   janela:
     errors:
@@ -75,8 +79,29 @@ en:
       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.
+    ignore_unknown_filters:
+      hint: For a pane beside panes over another model. A click there names a dimension this model does not have, and this pane stays as it is instead of saying the request is not allowed. A filter nobody's model declares is still a mistake on every other pane.
     value_labels:
-      hint: Draws the value at the end of each bar of a bar chart, if every one fits. Other charts ignore it.
+      hint: Draws the value at the end of each bar of a bar chart, if every one fits, and a line's latest value at its end. A ring ignores it.
+    series:
+      to_date: "%{label} to date"
+      cumulative_hint: Adds the measure up across the buckets, so the pane reads as a total to date. Applies to a time dimension.
+      hint: Up to %{count} more measures over the same buckets, each a line or bars on the left axis or a right one. A table draws them as columns. A ring ignores them.
+      measure: Measure
+      by: Over
+      as: Drawn as
+      axis: Axis
+      none: None
+      same_as_pane: Same as the pane
+      axes:
+        left: Left
+        right: Right
+    sorts:
+      desc: Largest first
+      asc: Smallest first
+      label: By label, A to Z
+      label_desc: By label, Z to A
+      hint: Applies to a breakdown by a category. A time series is always in time order.
     prominences:
       automatic: Automatic
       "1": Footnote

data/db/migrate/20261013000001_add_sort_to_janela_panes.rb

@@ -0,0 +1,7 @@
+class AddSortToJanelaPanes < ActiveRecord::Migration[8.0]
+  def change
+    # How a category pane is ordered (ADR 055): desc, asc, label or label_desc.
+    # Null is what every existing pane is: unset, and ordered exactly as before.
+    add_column :janela_panes, :sort, :string
+  end
+end

data/db/migrate/20261029000001_add_series_to_janela_panes.rb

@@ -0,0 +1,9 @@
+class AddSeriesToJanelaPanes < ActiveRecord::Migration[8.0]
+  def change
+    # A running total of a time pane's measure, and up to three more series
+    # drawn beside it (ADR 062). Null is what every existing pane is: unset,
+    # and drawn exactly as before.
+    add_column :janela_panes, :cumulative, :boolean
+    add_column :janela_panes, :series, :json
+  end
+end

data/db/migrate/20261029000003_add_ignore_unknown_filters_to_janela_panes.rb

@@ -0,0 +1,8 @@
+class AddIgnoreUnknownFiltersToJanelaPanes < ActiveRecord::Migration[8.0]
+  def change
+    # Whether a pane drops a reader's filter its model cannot apply rather
+    # than refusing the request (ADR 063). Null is what every existing pane
+    # is: unset, and refused exactly as before.
+    add_column :janela_panes, :ignore_unknown_filters, :boolean
+  end
+end

data/docs/agents.md

@@ -15,6 +15,29 @@ them with whatever MCP library your application already runs. Janela
 registers nothing, detects nothing and serves nothing, because it cannot
 know who is asking and your application can.
 
+## Setting it up
+
+```
+bin/rails generate janela:mcp
+```
+
+This writes `bin/janela-mcp`, a stdio server built on the official Ruby SDK, and
+adds a `janela` entry to `.mcp.json`, which Claude Code and other MCP clients
+read to find it. Both are yours from then on. It leaves an existing server or
+entry alone, and it does not touch your Gemfile: if `mcp` is not in your bundle
+it says which line to add (`gem "mcp"`).
+
+Open `bin/janela-mcp` and write the scope. It is the one thing the generator
+cannot know: who the agent acts for, and what that caller may read. It cannot be
+your controller's `policy_scope`, which needs a request, and called without one
+it does not fail but answers a different question and reads the wrong rows
+(ADR 057). Until you write it, every tool refuses to read and says so. The file
+also refuses to run outside development, so an agent never reaches real data
+until you decide it should.
+
+The rest of this page explains what is in that file, for a host that would
+rather write it by hand or register the tools with another library.
+
 ## Building the tools
 
 ```ruby
@@ -43,6 +66,7 @@ tool is called. They are cheap to construct.
 | `update_pane` | Change a pane. An invalid change leaves it as it was. | yes |
 | `remove_pane` | Remove a pane and close the gap. | yes |
 | `move_pane` | Move a pane one place up or down. | yes |
+| `update_frame` | Change a frame's `columns` and `gap`. Its name, key and owner are not an agent's to change. | yes |
 
 The write tools are off unless you build the tools with `write: true`. Their
 inputs are the pane's own attributes, the ones the README
@@ -50,8 +74,8 @@ names, and nothing else: an attribute that is not a pane's is refused rather
 than dropped. A pane Janela would refuse is refused with its own reason, for
 example `Measure "nonsense" is not a measure of Order`.
 
-There is no tool to create a frame or take a snapshot. Your code finds or makes
-a frame with `Janela::Frame.for` (ADR 041), and a snapshot needs an owner and a
+There is no tool to create a frame or take a snapshot, and none to change who owns
+one. Your code finds or makes a frame with `Janela::Frame.for` (ADR 041), and a snapshot needs an owner and a
 scope you have named (ADR 033, ADR 034).
 
 ## Registering them
@@ -88,6 +112,13 @@ end
 `mcp` is not a dependency of Janela, and a host using another library writes the
 same few lines against it.
 
+## What an agent cannot reach
+
+A server run with `bin/janela-mcp` reads and changes the database of the
+environment it starts in, which is development. It cannot reach a dashboard on a
+deployed host: that needs an authenticated path only your application can give,
+because Janela serves no endpoint and does not know who is calling (ADR 053).
+
 ## What Janela does not do
 
 It does not serve MCP, detect a server, edit your configuration or install

data/docs/decisions/018-a-table-is-the-universal-renderer.md

@@ -1,6 +1,7 @@
 ---
 Date: 2026-09-16
 Status: Accepted
+Superseded in part by: ADR 059
 Related: ADR 009, ADR 011, ADR 013, ADR 016
 Triggers:
   - rendering a pane where the chart runtime may be absent

data/docs/decisions/053-an-agent-reaches-janela-through-tools-the-host-scopes.md

@@ -1,6 +1,7 @@
 ---
 Date: 2026-10-02
 Status: Accepted
+Superseded in part by: ADR 057
 Related: ADR 001, ADR 010, ADR 012, ADR 014, ADR 017, ADR 019, ADR 025, ADR 032, ADR 033, ADR 034, ADR 037, ADR 041
 Triggers:
   - proposing an MCP server, an agent tool or any machine facing surface for Janela

data/docs/decisions/054-a-chart-reads-numbers-the-way-its-measure-formats-them.md

@@ -1,6 +1,6 @@
 ---
 Date: 2026-10-06
-Status: Accepted
+Status: Accepted (the sentence that a line ignores value_labels is superseded by ADR 062)
 Related: ADR 004, ADR 020, ADR 029, ADR 037, ADR 038, ADR 046, ADR 047, ADR 050, ADR 053
 Triggers:
   - a chart's axis showing a number the tooltip shows differently

data/docs/decisions/055-a-category-pane-can-be-sorted-by-its-measure-either-way-or-by-its-label.md

@@ -0,0 +1,204 @@
+---
+Date: 2026-10-13
+Status: Accepted
+Related: ADR 005, ADR 006, ADR 007, ADR 020, ADR 037, ADR 046, ADR 047, ADR 049, ADR 050, ADR 053, ADR 054
+Triggers:
+  - adding a sort direction, or sorting a pane by something other than its measure
+  - asking for the bottom N, the lowest values, or a chart in label order
+  - a dimension whose labels are the natural order, such as a period code
+  - adding a parameter to the pane URL, or a column to janela_panes
+  - deciding where the NULL group sits in a pane's order
+Topics: ordering, limit, panes, urls, query-layer, public-api, frames
+---
+
+# ADR 055: A Category Pane Can Be Sorted by Its Measure Either Way, or by Its Label
+
+## Context
+
+ADR 007 ordered every category pane by its measure, largest first, with no
+way to turn that off, and named what it left for later: "an 'other' bucket
+that sums what the limit cut off, ascending order, sorting by label, and
+paging. Each is plausible; none is needed by the first host." Two hosts
+have now needed one each.
+
+#75: a pane with a `limit` shows the top N and cannot show the bottom N, the
+lowest scores rather than the highest. Reversing the result in the view
+does not help, because the limit is applied in SQL before the host sees any
+rows, so a reversed top ten is still the top ten. The host that raised it
+carries a patch that gives each pane an ascending or descending order, and
+that patch broke across releases because it copied method bodies.
+
+#80: a chart of a measure by a dimension whose labels are the natural order,
+such as `202603 March Grocery Independents`, where the leading `YYYYMM` makes
+alphabetical order chronological, comes out largest first and not oldest
+first, so a trend is unreadable. The host worked round it with a database
+column that holds the month as a time dimension, because a time dimension is
+the one exemption ADR 007 makes. That costs a column, and it merges any two
+cycles that fall in the same month.
+
+These are one decision. Both are "which end of which ordering does the pane
+start from", they share every open question below, and building either alone
+risks making the other's shape wrong.
+
+### What was measured
+
+Against the demo, on SQLite, before deciding.
+
+**The ordering is one line.** `Definition#query` groups by the dimension and
+orders by `measure.order_by` descending, then limits. Reversing the
+direction and ordering by the dimension's own column both work with a
+change to that line, and the limit follows the order: ascending by measure
+with a limit of two returned the two smallest groups.
+
+**A database sorts a column by the column's type.** Ordering in SQL puts a
+numeric column in numeric order and a date column in date order, and sorts a
+text column as text. A text label such as `202603 ...` sorts correctly
+because its prefix is fixed width, and a text column holding `10` and `9`
+sorts `10` before `9`, as any text sort does. The question #80 left open,
+whether label sorting compares as text or follows the column's type, is
+answered by letting the database do it: it follows the column's type,
+because the column is what is being sorted.
+
+**Text order is the database's collation, and it differs.** On SQLite
+`B` sorts before `a`. Other databases sort case insensitively by default.
+Janela does not read the collation and does not try to make them agree.
+
+**The NULL group is placed differently by different databases.** SQLite sorts
+NULL first in an ascending order. PostgreSQL, from its documentation and
+not measured here, sorts it last. Left alone, a label ordered pane would
+show `(none)` at the top on one host and at the bottom on another.
+`ORDER BY column IS NULL, column` puts it last everywhere, and measured on
+SQLite it did: `10, 202603 x, 9, B, a, b, (none)`.
+
+**Ties have no order today.** Two groups with the same measure come out in
+whatever order the database produces, and with a limit the choice between
+them decides which one is shown at all. That is harmless for a top ten of
+distinct sums and arbitrary for a bottom five of counts, where ties are the
+norm.
+
+### What was considered
+
+**Order on the measure.** ADR 020 put formatting there, and the reasoning
+does not carry over. Formatting is a fact about the number, true wherever it
+is shown. Order is a choice about one view of it: the same revenue measure is
+sensibly largest first in one pane, smallest first in another and in label
+order in a third on the same page. A measure that carries an order would
+force two measures for one number, which is the workaround ADR 002 offers
+for variation and the wrong one here. The limit is already on the pane for
+the same reason (ADR 007), and order and limit are read together.
+
+**Two settings, a field and a direction** (`sort: :label, dir: :desc`). Two
+columns and two URL parameters to say one of four things, with combinations
+that mean nothing for a time pane. One setting with four values is the
+vocabulary `height` and `prominence` already speak (ADR 047, ADR 050).
+
+**Sorting in Ruby after the fetch.** Cannot work. The limit is applied in
+SQL, so a Ruby sort of ten rows sorts the wrong ten.
+
+**A natural or numeric aware text sort.** Not portable across databases and
+a second query language to document. A host whose labels need it can sort by
+a column that holds the sortable form, which is what the one host already
+does, and which the label order now makes unnecessary for the common case.
+
+**An "other" bucket and paging.** Still not needed by anyone. Left where
+ADR 007 left them.
+
+## Decision
+
+**A category pane may carry a `sort`, one of four values, and unset is
+exactly what a pane does today.**
+
+| sort | order | reads as |
+| --- | --- | --- |
+| `desc` (default) | measure, largest first | top N |
+| `asc` | measure, smallest first | bottom N |
+| `label` | the dimension's own value, ascending | alphabetical, oldest first |
+| `label_desc` | the dimension's own value, descending | newest first |
+
+```erb
+<%= janela_pane Order, :revenue, by: :customer, limit: 5, sort: :asc %>
+<%= janela_pane Order, :revenue, by: :cycle, as: :bar, sort: :label %>
+```
+
+**It is the pane's, in the three places the pane's other options are.**
+
+- `Janela::Pane#sort`, a nullable string column validated to the four
+  values and offered as a select on the pane form (blank is "Largest
+  first").
+- `janela_pane` and `janela_snapshot_pane` take `sort:`.
+- The pane URL carries it as `?sort=asc`, so the server-rendered content
+  keeps it on every cross-filter and lazy load, the same reasoning as
+  `height` (ADR 047).
+
+The column is named `sort` and not `order`, which is a reserved word in SQL
+and the name of a relation method, and not `order_by`, which already means
+the SQL expression on a measure.
+
+**The database does the work, and the limit comes after.** For `label` and
+`label_desc` the query orders by the dimension's column, so a number, a date
+and a string each sort as themselves, and the limit then cuts that order:
+`sort: :label, limit: 10` is the first ten labels. For `asc` it orders by the
+measure ascending, so `limit: 5` is the bottom five.
+
+**The `(none)` group is always last,** in all four orders, by ordering on
+`column IS NULL` first. It is a group like any other for the measure orders,
+and where its measure falls it falls. For the label orders it has no
+position in the label's own order, so it goes to the end in a way that is
+the same on every database.
+
+**Ties are broken by the label, ascending,** in every order, so the same
+data always draws the same pane and a limit between tied groups always
+shows the same one. Unset panes were arbitrary in ties and are now fixed,
+which changes nothing anyone could have relied on.
+
+**A time pane ignores `sort`.** A time series is ordered by time and shows
+its whole range (ADR 007), and that stands. A `sort` on one is ignored and
+not an error, as a height is on a ring, so a row whose dimension is changed
+to a time dimension is not made invalid and keeps its value if it is changed
+back. Newest first on a time pane is a different question, left open below.
+
+**A ring and a table take it unchanged.** Both draw the result in order: a
+ring's slices and its legend follow it, a table's rows follow it. Nothing
+special is built for either. A ring of the bottom five by `asc` is the caller's
+choice, as a ring of the top five already is, and ADR 046's remark that a
+ring suits few slices stands.
+
+**It is part of the pane's identity when set,** the way `limit` is (ADR 007),
+because "top five" and "bottom five" of one breakdown are two different
+answers and may share a page. It is added to `Query.turbo_frame_id` only when
+it is not the default, so every existing frame id is unchanged. This differs
+from `height`, which is drawing and not identity (ADR 047).
+
+## Consequences
+
+- **A migration for stored frames.** `janela_panes` gains a nullable `sort`,
+  additive, so every existing pane is unset and unchanged. A host that uses
+  stored frames runs `bin/rails janela:install:migrations` and `db:migrate`,
+  written in `UPGRADING.md` and the post install message (ADR 015). The
+  doctor's `unmigrated-columns` check (ADR 035) is taught the column.
+- **`Janela::Tools` has to learn the attribute,** in the same change as the
+  column, or an agent could arrange every part of a pane except how it is
+  ordered (ADR 053). Its vocabulary names the four values.
+- **The pane URL grammar grows by one optional parameter,** which ADR 037
+  counts as public surface and is why this belongs before 1.0. ADR 005's
+  naming table gains a row: *bottom N* is `?sort=asc&limit=N`.
+- **Snapshots record it.** A snapshot's lookup key includes the sort, as it
+  includes the limit, so a frozen "bottom five" is not found for a request
+  for "top five" (ADR 009).
+- **Text labels sort by the host database's collation.** Documented, not
+  smoothed over. A host that needs a different text order sorts on a column
+  that holds it.
+- Companion columns follow the primary measure's order and limit, as they do
+  today (ADR 051).
+- The demo's playground gets a control for it, shown only for a category
+  pane, with the declaration rewriting itself as for the others (ADR 027).
+- A pane ordered by label no longer puts the largest value first, so a chart
+  in label order can bury the biggest bar. That is the analyst's choice and
+  the reason for asking.
+- Not decided here: newest first on a time pane; an "other" bucket; paging;
+  a host's own ordering by an arbitrary column. Each starts from this
+  table.
+- What would change this decision: a need for an ordering by something that
+  is neither the measure nor the label, such as a second measure, which is an
+  argument for companion columns driving an order (ADR 051) and not for more
+  values here; or a database where `column IS NULL` is not portable.

data/docs/decisions/056-the-demo-counts-its-own-visits-and-an-agent-arranges-the-dashboard.md

@@ -0,0 +1,51 @@
+---
+Date: 2026-10-13
+Status: Accepted
+Related: ADR 001, ADR 012, ADR 032, ADR 053
+Triggers:
+  - changing what the demo records about a visitor
+  - adding a model to the demo that Janela reads
+  - arranging a demo frame by hand rather than through the tools
+  - the demo reset or its seeds
+Topics: demo, dogfooding, privacy, agents, mcp, frames
+---
+
+# ADR 056: The Demo Counts Its Own Visits, and an Agent Arranges the Dashboard
+
+## Context
+
+The demo's data is a year of invented orders. A dashboard over real traffic
+is a better proof that Janela works on rows nobody planted, and it is the
+first thing here that an agent can arrange through `Janela::Tools` (ADR 053)
+against a model that was not written for the tools. A real application had
+just done the same for its own pages, with a `PageView` model, a concern and
+a seeded frame, and that shape is small enough to copy unchanged.
+
+## Decision
+
+**One `PageView` row per full HTML page opened.** `page` is
+`controller#action`, `path` is the URL without its query string, and
+`viewed_on` is a stored date. Nothing says who the visitor was: no cookie,
+no address, no user agent. A Turbo Frame request (every pane), a prefetch,
+a robot, a non-HTML response, a redirect and a non-GET are not page views,
+and a failure to record is reported and never breaks the page.
+
+**The frame is rows, and an agent arranges it.** `test/dummy/bin/janela-mcp`
+registers the tools with the official SDK, writes enabled, scoped as the
+demo's own `policy_scope` is, and refuses to run outside development. The
+repository's `.mcp.json` points at it. The frame itself is made by the host,
+since there is no `create_frame` tool, and the panes are added with
+`add_pane`. The result is frozen as rows in `db/seeds.rb`, because the hourly
+reset deletes every frame and seeds are what bring one back.
+
+**`PageView` is not reset.** `demo:reset` puts the invented orders and the
+frames back and leaves the visits alone, so the numbers stay real.
+
+## Consequences
+
+- The dashboard starts empty on a fresh deploy and fills as people use the
+  site. That is honest, and is not seeded with invented history.
+- Counting a visit costs one insert per page. Fine for a demo on SQLite, and
+  not a pattern to take to a busy host.
+- A change to the dashboard is made through the tools and copied into the
+  seeds. If the two drift, the seeds win after the next reset.