janela 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2416bb876bf67b3cda96853cc4cee216fd8c153a0ec4930d8243512be5c8c163
-  data.tar.gz: 1b4a35484a9d04d696771376389ab35dc17b76469ce772de54e48ed7017f5cc5
+  metadata.gz: 69f4c0147424e4d9350bcee373b832e922f54b1686acce5c80fa776432a288c6
+  data.tar.gz: ec2f91ec4c87dcfeb49154b54e0cda105f293e8b56580fb774750011fb9277df
 SHA512:
-  metadata.gz: 6f20d48d6dfcb473861d0e20b9116e135498d6879a79f9c5720a184b35a66be4189d7e74bc51431d116f4955c73b458af59ff428062e237ee0a2421564436ad0
-  data.tar.gz: 5b9c28323e356a9c6833ea25d0c0e3ef8c92225848ef7611fb4c3aeafb95bd75e7c0087d9b3957d819c161fedd1bfacd915b3731382ae78cf6874dca94202645
+  metadata.gz: 38e32300abc75aa9b738d63b2d7f638dff0d9f153e19aa32f1cb5cbd422702c4e236bc93b87e7c4474836bbd3bfddfad4f83fbaa95d523efee8e6b82b6246b12
+  data.tar.gz: fe82fff29b230ecab68eb8c14e162d214ee9c1666ead178145c73ffe776e635b8acd59fa8cc1df1011a9f091b2d50e9d9fe299e67142657ed59e69fa1d70d120

data/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.14.0] - 2026-10-07
+
+### Added
+
+- **A bar chart can draw each bar's value on the bar.** `janela_pane Order, :expedited_rate, by: :channel, as: :bar, value_labels: true`, or the checkbox on a stored pane's form, writes the measure's own formatted string, the one the tooltip shows, beyond the end of each bar: above a positive one and below a negative, with the value axis given a tenth of headroom so the tallest bar's label is not clipped. A chart whose labels would not all fit in their bars' share of the width draws none, rather than labelling some bars and not others. Until now a reader had to hover every bar to read a number, so a report wanting `53.0%` written on each bar could not be built. With none set nothing changes, and a line, a ring, a table and a single value ignore it. It travels in the pane URL as `?value_labels=1`, and `Janela::Tools` can set it on a pane. Stored panes need a migration; see `UPGRADING.md` (ADR 054, #76).
+
+- **`Janela.heights`, `Janela.prominences` and `Janela.max_companions`**, for a page that offers a pane's options as controls. They answer the steps a pane's `height:` and `prominence:` take and how many companion columns a table may carry, so such a page does not read `Janela::Pane::HEIGHTS` or `Janela::Query::MAX_COMPANIONS` directly, as `Janela.renderers` already spares it for the renderers. The demo's gallery is built from them: beside each pane is a control for every option it takes, shown only where the renderer chosen is one it changes, with the declaration rewriting itself so it can be copied. No action needed (ADR 027).
+
+### Changed
+
+- **A chart's value axis reads in the measure's own format.** A bar or line chart drew Chart.js's raw numbers down its side, so a ratio read `0, 0.2 ... 1` beside tooltips saying `50.0%`, and revenue read `50,000` beside `$469,097.85`. The ticks now carry the measure's `prefix` and `suffix`, and a ratio's read as percentages, whole where the spacing is whole (`20%`, `40%`) and fractional only where the ticks really are (`0.5%`, `1%`). A measure with no prefix, suffix or ratio draws what it always did, and the number plotted is unchanged. A host that has copied `chart_controller.js` will not get this and has nothing to break. No action needed (ADR 054, #72).
+
+### Fixed
+
+- **One stored pane Janela will not draw no longer takes the whole host page down.** A frame rendered inline runs its panes' queries in the host's own request, with no controller of Janela's above them, so a pane that was refused raised out of the template and the host answered with a server error. That happened to a pane left on a model that no longer declares the dimension it names, as when a frame is moved between models, and to any pane when a filter named a dimension its model does not declare. The refusal is right and stays, because Ransack would otherwise drop the filter and show an unfiltered number (ADR 025); what changes is its reach. The pane shows the same plain sentence the engine's own pane page shows and the rest of the page draws. The detail, which names models and filter keys, goes to the log. A host that has not scoped is still an error, since that is a misconfiguration and not a pane that cannot be drawn (ADR 032). No action needed, and a host that deleted such panes as a workaround can stop (#83).
+
+## [0.13.0] - 2026-10-02
+
+### Changed
+
+- **The vitral theme draws charts in its own colours.** Bars, doughnut slices and pie slices were the stained glass accent for the first and Janela's neutral set for the other seven; vitral now sets all eight, as soft glass tones: a muted blue, sage, lavender, plum, clay, teal, ochre and dusty rose, with the grey of lead came for anything past the eighth. A first version in saturated jewel tones was rejected by eye as a rainbow against the pale tiles, so these sit at about half the chroma and lean on differences in lightness. They were chosen as an ordered set and checked together, with adjacent colour-vision separation of 12.4 (the target is 8) and adjacent normal-vision separation of 15.8 (the floor is 15). Slot 1 is a softer blue of vitral's own; `--janela-accent` stays the stronger blue for what is selected. A host that uses vitral and has set its own `--janela-series-N` keeps them. No action needed (ADR 026, #67).
+
+### Fixed
+
+- **The engine's own chart partial compiles through Herb.** Rails 8.2 renders HTML templates through Herb, which refuses ERB that writes an attribute's name or sits in attribute position, and `janela/queries/_query.html.erb` did both for the chart's canvas. It is now one `tag.canvas` call that renders the same attributes, so a host on the 8.2 defaults is not broken by Janela's own template. A host that has copied that partial keeps its copy, which Herb will reject if it still has ERB in an attribute position: `bin/rails app:herb:check` on Rails 8.2 lists any. No action needed otherwise.
+- **The doctor no longer calls `Janela::PanesController` a stale name.** It reported an error that the name "is now `Janela::QueriesController`", true from 0.7 until 0.12 added a `Janela::PanesController` back as the stored-pane form's controller, which owns `pane_params`. A host patching that form was told to move the patch to a controller with no `pane_params`, which would have silently stopped its extra pane param saving, and the error failed `janela:doctor` until the check was silenced. It is now a warning that says what the name means today. The check is still silenced by `stale-identifiers`, and `Janela::SnapshotPanesController` is unchanged (#74).
+
+### Added
+
+- **Tools for an agent: `Janela::Tools`.** An agent in a host had no way to read or arrange a dashboard except by writing `Janela::Frame` and `Janela::Pane` rows from a console. `Janela::Tools.new(scope:)` is plain Ruby with a name, a description and a JSON schema for each of `describe_vocabulary`, `list_frames`, `get_frame` and `read_pane`, and with `write: true`, `add_pane`, `update_pane`, `remove_pane` and `move_pane`. `scope:` is required and takes a model class and returns a relation, the answer `policy_scope` gives, so a read or a change reaches only what the caller may see; leaving it out raises `Janela::Unscoped` when the tools are built. Janela registers nothing, serves nothing and depends on no MCP library: [docs/agents.md](docs/agents.md) shows the adapter for the official Ruby SDK, which Janela's own tests run. No action needed (ADR 053, #73).
+
+- **The doctor notices a skipped migration, not only a missing table.** `bin/rails janela:doctor` reported a missing `janela_panes` and said nothing when the table was there but a release had added a column to it, so a host that upgraded and did not run `db:migrate` was told all was well, and met an error the first time a pane form or a stored pane read `height`, `prominence` or `companions`. A new `unmigrated-columns` check lists the missing columns by table and names the two commands. It can be silenced by that name like any other (ADR 021, ADR 035).
+
 ## [0.12.0] - 2026-10-01
 
 ### Added
@@ -40,7 +73,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - **A range in the URL no longer narrows the time pane it names.** `q[placed_on_gteq]` and `q[placed_on_lt]` from a reader now scope every other pane and leave a time pane on that dimension showing its whole series with the range marked, where before it narrowed that pane's own series. A range a host fixes with `where:` or `default_where` still narrows it. See `UPGRADING.md` (ADR 045).
-- **A bar chart's bars are no longer all one colour.** Each bar is now drawn in the palette colour for its position, so a host that has seen every bar in `--janela-accent` will see the first bar in the accent and the rest in new colours. A line chart is unchanged. To keep the old look, set `--janela-series-2` to `--janela-series-8` to your accent; see `UPGRADING.md` (ADR 046).
+- **A bar chart's bars are no longer all one colour.** Each bar is now drawn in the palette colour for its position, so a host that has seen every bar in `--janela-accent` will see the first bar in the accent and the rest in new colours. A line chart is unchanged. To keep the old look, set `--janela-series-2` to `--janela-series-8`, and `--janela-series-other`, to your accent; see `UPGRADING.md` (ADR 046).
 
 ### Fixed
 
@@ -256,6 +289,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.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
 [0.11.0]: https://github.com/retail-tasker/janela/releases/tag/v0.11.0
 [0.10.0]: https://github.com/retail-tasker/janela/releases/tag/v0.10.0

data/README.md

@@ -6,7 +6,7 @@ PowerBI-style dashboards and cross-filtering slicers, native to Rails and Active
 
 ## First principle
 
-Janela is a PowerBI-style library built on Ruby and Stimulus, meant to drop onto any Ruby on Rails application. No JS framework, no build step of its own, no separate frontend app. Just a gem you add to an existing Rails app's Gemfile and two Stimulus controllers that ship with it.
+Janela is a PowerBI-style library built on Ruby and Stimulus, meant to drop onto any Ruby on Rails application. No JS framework, no build step of its own, no separate frontend app. Just a gem you add to an existing Rails app's Gemfile and two Stimulus controllers that ship with it, plus an optional third for the theme.
 
 ## Why
 
@@ -14,7 +14,7 @@ Every Rails BI option today is one of:
 
 - **SQL-first** (Blazer). Powerful, but the query is a black box to your models and associations.
 - **Admin-panel-first** (RailsAdmin, ActiveAdmin, Motor Admin, Avo). Association-aware filtering, but built for CRUD, not for composing multiple charts that filter each other.
-- **A dead end for cross-filtering**. None of the above let clicking one chart re-scope every other chart on the page. That's the actual PowerBI/Tableau slicer experience, and nothing in the Rails ecosystem does it as a first-class citizen.
+- **A dead end for cross-filtering**. None of the above are built around clicking one chart to re-scope every other chart on the page. That's the PowerBI/Tableau slicer experience, and it's what Janela is for.
 
 Janela's bet: the same dashboard definition should serve two audiences without being two systems.
 
@@ -23,11 +23,11 @@ Janela's bet: the same dashboard definition should serve two audiences without b
 
 ## Installation
 
-Janela is an alpha on [rubygems.org](https://rubygems.org/gems/janela). It has two halves, a gem and an npm package:
+Janela is an alpha on [rubygems.org](https://rubygems.org/gems/janela). It is a gem, plus a JavaScript package installed from GitHub if your app bundles its JavaScript. An app on importmap-rails needs only the gem. It needs Rails 8.0+ and Ruby 3.3+ (see Requirements below).
 
 ```ruby
 # Gemfile
-gem "janela", "~> 0.12"
+gem "janela", "~> 0.14"
 ```
 
 ```ruby
@@ -35,6 +35,15 @@ gem "janela", "~> 0.12"
 mount Janela::Engine => "/dashboards"   # or /reports, or wherever you like
 ```
 
+Janela reads nothing until your `ApplicationController` says what a visitor may see, so the first visit to `/dashboards` raises `Janela::Unscoped` without it. An app with nothing to hide answers once:
+
+```ruby
+# app/controllers/application_controller.rb
+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.
+
 Then register the two Stimulus controllers. How depends on how your app ships JavaScript.
 
 **With jsbundling (esbuild, bun, webpack):**
@@ -223,6 +232,8 @@ 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).
+
 **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).
 
 **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.
@@ -322,7 +333,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 draws nothing; put a frame on your own page, where your JavaScript is, for the interactive version.
+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`.
 
 The noun in the headings is `Janela::Frame.model_name.human`, so rename it in your own locale file rather than in a setting:
 
@@ -387,7 +398,7 @@ The model is its route key (`orders`, `sales_orders`), then the measure, then op
 
 ### What Janela can draw
 
-`Janela.renderers`, `Janela.granularities` and `Janela.offered_limits` answer what a pane can be drawn as, without reaching into `Janela::Query::RENDERERS`, `Janela::Dimension::GRANULARITIES` or `Janela::Pane::OFFERED_LIMITS`. `Janela.definitions` answers the other half: every model that declares a `janela` block, with its own measures and dimensions. A gallery of every renderer, live against your own data, is a page you build from those four calls and `janela_pane`, not one the engine serves (ADR 026, ADR 027):
+`Janela.renderers`, `Janela.granularities` and `Janela.offered_limits` answer what a pane can be drawn as, without reaching into `Janela::Query::RENDERERS`, `Janela::Dimension::GRANULARITIES` or `Janela::Pane::OFFERED_LIMITS`. `Janela.heights`, `Janela.prominences` and `Janela.max_companions` answer the steps a pane's `height:` and `prominence:` take and how many companion columns a table may carry, for a page that offers them as controls. `Janela.definitions` answers the other half: every model that declares a `janela` block, with its own measures and dimensions. A gallery of every renderer, live against your own data, is a page you build from those calls and `janela_pane`, not one the engine serves (ADR 026, ADR 027):
 
 ```erb
 <% Janela.definitions.each do |definition| %>
@@ -418,7 +429,7 @@ Render a stored pane the same way you render a live one:
 <%= janela_snapshot_pane @snapshot, Order, :revenue, by: :status, as: :bar %>
 ```
 
-Inside a dashboard a pane is a Turbo Frame and carries no layout at all. Opened directly it renders in Janela's own minimal layout, which deliberately loads no assets, because the gem cannot know your asset names or whether you bundle. A direct pane link therefore shows its numbers unstyled, and a chart pane shows nothing, since the chart needs Stimulus.
+Inside a dashboard a pane is a Turbo Frame and carries no layout at all. Opened directly it renders in Janela's own minimal layout, which loads the gem's stylesheet and none of your JavaScript, because the gem cannot know your asset names or whether you bundle. A direct pane link therefore shows its numbers styled, and a bar or line chart draws nothing, since the chart needs Stimulus. A table and a ring (which is drawn as SVG on the server) still show.
 
 To make direct pane links styled and chart-capable, give Janela a small layout of your own that loads your assets and nothing else:
 
@@ -487,25 +498,19 @@ Scoping is automatic when you use Pundit: `Janela::ApplicationController` calls
 
 **Multi tenancy** has its own guide: [docs/multi-tenancy.md](docs/multi-tenancy.md). It covers what goes through your scope, worked wiring for Pundit, acts_as_tenant and CanCanCan, what owns a frame the analyst creates, and what rows a scheduled snapshot freezes.
 
-### The pages Janela serves
+### Giving an agent access
 
-Mounting the engine gives you an index of frames and a page per frame with no
-work at all, which is enough to navigate on the day you install it:
+Frames and panes are rows, so an agent can arrange a dashboard if it has tools. Janela gives you the tool definitions as plain Ruby and leaves the registering to you, because your application knows who is asking and Janela does not (ADR 053):
 
-```
-/insights      every frame your policy scope returns
-/insights/3    one frame
-```
+```ruby
+tools = Janela::Tools.new(scope: ->(model) { policy_scope(model) })   # read only
+tools = Janela::Tools.new(scope: ->(model) { policy_scope(model) }, write: true)
 
-Both go through your `policy_scope`, so a frame another tenant owns is a 404. Each page carries a link back to your application's root, so they are not a dead end; rename it in your own locale file under `janela.actions.home`, or override the engine's layout if you want your whole navigation there.
+Janela::Tools.all          # name, description, input_schema, read_only
+tools.call("read_pane", pane_id: 4)
+```
 
-These pages load Janela's own stylesheet and nothing of yours, because the gem
-cannot know your asset names or bundler. Two consequences worth knowing. They
-do not cross-filter, since that needs Stimulus. And a pane whose row asks for a
-chart renders as its **table** here, because there is no chart runtime on the
-page and a table needs nothing: the same frame rendered in your own page with
-`janela_frame(@frame)` draws the chart. A renderer is a viewing choice, not part
-of the pane (ADR 018).
+`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.
 
 ### Checking an installation
 
@@ -558,11 +563,11 @@ Deliberately out of scope: natural-language query, a separate data warehouse, a
 
 ## Status
 
-**v0.12.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 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, drill-down on time panes, other chart types. [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.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).
 
 ## Development
 
-Janela is a Rails engine. It ships with a minimal host application in `test/dummy` that mounts the engine at `/janela`, so the gem is always developed and tested against a real Rails app with a real (SQLite) database.
+Janela is a Rails engine. It ships with a minimal host application in `test/dummy` that mounts the engine at `/dashboards`, so the gem is always developed and tested against a real Rails app with a real (SQLite) database.
 
 After checking out the repo, run `bin/setup` to install dependencies. Then:
 
@@ -575,13 +580,13 @@ bin/rails console     # console inside the dummy app, engine loaded
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/retail-tasker/janela. Pull requests are reviewed on the merits of the diff, whether a person or an agent wrote them. [CONTRIBUTING.md](CONTRIBUTING.md) says how to run the tests, when a change needs a decision record first, and what to write down for the people who upgrade. Contributors are expected to adhere to the [code of conduct](https://github.com/retail-tasker/janela/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/retail-tasker/janela. Pull requests are reviewed on the merits of the diff, whether a person or an agent wrote them. [CONTRIBUTING.md](https://github.com/retail-tasker/janela/blob/main/CONTRIBUTING.md) says how to run the tests, when a change needs a decision record first, and what to write down for the people who upgrade. Contributors are expected to adhere to the [code of conduct](https://github.com/retail-tasker/janela/blob/main/CODE_OF_CONDUCT.md).
 
 ## Support and security
 
 Janela is pre-1.0 and its public surface can still move between releases, with an upgrade note each time. Issues and pull requests are read when the maintainers can get to them; there is no support contract and no promised response time.
 
-To report a vulnerability, use the private form described in [SECURITY.md](SECURITY.md) and not a public issue. Releases are cut by the two maintainers and published from a protected workflow; the steps are in [RELEASING.md](RELEASING.md).
+To report a vulnerability, use the private form described in [SECURITY.md](https://github.com/retail-tasker/janela/blob/main/SECURITY.md) and not a public issue. Releases are cut by the two maintainers and published from a protected workflow; the steps are in [RELEASING.md](https://github.com/retail-tasker/janela/blob/main/RELEASING.md).
 
 ## License
 

data/UPGRADING.md

@@ -12,6 +12,60 @@ bin/rails janela:doctor
 
 It reads your application and lists what still needs changing.
 
+## 0.13.0 to 0.14.0
+
+One migration step, if you use stored frames.
+
+**Take the pane migration.**
+
+A bar chart pane can now draw each bar's value on the bar (ADR 054).
+`janela_panes` gains a nullable boolean `value_labels`:
+
+```bash
+bin/rails janela:install:migrations
+bin/rails db:migrate
+```
+
+Every existing pane keeps it nil and is drawn exactly as before. 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.
+
+**Chart axes now read in the measure's format.** Nothing to change: a revenue
+chart's ticks gain their `$` and a ratio chart's read as percentages. A host
+that screenshots or asserts on a chart's tick labels will see the new text.
+
+## 0.12.0 to 0.13.0
+
+No migration, and nothing you must change. Two things you may see.
+
+**The doctor treats `Janela::PanesController` as a warning.**
+
+0.7 renamed it to `Janela::QueriesController`, and 0.12 added a
+`Janela::PanesController` back as the stored-pane form's controller, which owns
+`pane_params`. The doctor used to call every mention of the name an error. It now
+warns, and says what the name means today. If you patch the form's
+`pane_params`, leave it where it is. If you patched how a query renders, that
+patch belongs on `Janela::QueriesController`.
+
+**A host that copied `janela/queries/_query.html.erb` should check it.**
+
+Rails 8.2 renders HTML templates through Herb, which refuses ERB that writes an
+attribute's name or sits in attribute position. Janela's own copy of the partial
+no longer does either, so it compiles. A copy of yours keeps the old markup,
+which Herb will reject if it has ERB in an attribute position. On Rails 8.2:
+
+```bash
+bin/rails herb:check
+```
+
+lists what it rejects. On earlier Rails there is nothing to do.
+
+**Optional: tools for an agent.**
+
+`Janela::Tools` gives an agent the tools to read and arrange a dashboard. It is
+not on unless you build it, and nothing registers itself. See
+[docs/agents.md](docs/agents.md).
+
 ## 0.11.0 to 0.12.0
 
 One migration step, if you use stored frames.
@@ -63,7 +117,7 @@ in `--janela-series-2` to `--janela-series-8`, and every bar after the
 eighth in `--janela-series-other`. Until now every bar was the accent.
 Line charts are unchanged.
 
-If you want the old look, set the seven to your accent:
+If you want the old look, set the other eight to your accent:
 
 ```css
 :root {
@@ -549,6 +603,11 @@ Most applications do not.
 `Janela::Pane` is reserved for a database record in a later release,
 which is why the runtime object had to give the name up.
 
+`Janela::PanesController` was renamed in this table, and 0.12 added a
+`Janela::PanesController` back: the stored-pane form's controller, which owns
+`pane_params`. The doctor warns about the name without calling it an error,
+because only you know which one your code means.
+
 If you override Janela's view, move your copy from
 `app/views/janela/panes/` to `app/views/janela/queries/`.
 

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

@@ -1,5 +1,5 @@
 import { Controller } from "@hotwired/stimulus"
-import { Chart, registerables } from "chart.js"
+import { Chart, Ticks, registerables } from "chart.js"
 
 Chart.register(...registerables)
 
@@ -9,11 +9,15 @@ Chart.register(...registerables)
 // chart is destroyed on disconnect and rebuilt on connect.
 export default class extends Controller {
   static values = { type: String, labels: Array, values: Array, filters: Object, title: String,
-                    selected: Array, formatted: Array, fixedHeight: Boolean }
+                    selected: Array, formatted: Array, tickFormat: Object, fixedHeight: Boolean, valueLabels: Boolean }
 
   connect() {
+    const controller = this
     this.chart = new Chart(this.element, {
       type: this.typeValue,
+      // A plugin cannot be added to a chart once it is built, so it is handed
+      // over here, as the aspect ratio is for a height (ADR 047, ADR 054).
+      plugins: this.valueLabelsValue ? [ { id: "janelaValueLabels", afterDatasetsDraw: (chart) => this.drawValueLabels(chart) } ] : [],
       data: {
         labels: this.labelsValue,
         datasets: [{
@@ -31,7 +35,14 @@ 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,
-        scales: { y: { beginAtZero: true } },
+        // 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) } }
+        } },
         // 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).
@@ -62,6 +73,46 @@ 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).
+  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
+    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.restore()
+  }
+
+  // Chart.js's own numeric formatter, so the decimals follow the spacing
+  // between ticks: 20%, 40%, and 0.5%, 1% only where the ticks really are half
+  // a percent apart. A ratio is stored as a fraction and read as a percentage
+  // (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.
+  tickLabel(scale, value, index, ticks) {
+    const { prefix = "", suffix = "", ratio = false } = this.tickFormatValue
+    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) })))
+    return `${prefix}${number}${ratio ? "%" : suffix}`
+  }
+
   // 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

data/app/assets/stylesheets/vitral.css

@@ -69,6 +69,27 @@
      janela.css draws agree with the parts this one does. */
   --janela-line: var(--vitral-came-soft);
   --janela-accent: rgb(40, 110, 205);
+
+  /* The colours a bar, a doughnut slice or a pie slice is drawn in, by
+     position (ADR 046, ADR 026). Soft glass rather than bright: a first
+     version in saturated jewel tones read as a rainbow against the pale tiles,
+     so these sit at about half the chroma and lean on differences in lightness
+     to keep neighbours apart (the plum and the dusty rose are the darker ones).
+     Chosen as an ordered set and run through the palette checker: adjacent
+     colour vision separation 12.4 (target 8) and adjacent normal vision
+     separation 15.8 (floor 15). The order is what keeps neighbours apart, so a
+     reorder has to be re-checked. Slot 1 is a softer blue of its own and not
+     the accent, which stays the stronger blue for what is selected. The neutral
+     past the eighth is the grey of lead came. */
+  --janela-series-1: #608fcb;
+  --janela-series-2: #56ab81;
+  --janela-series-3: #a492da;
+  --janela-series-4: #91507d;
+  --janela-series-5: #be774e;
+  --janela-series-6: #159da9;
+  --janela-series-7: #c29e51;
+  --janela-series-8: #994b59;
+  --janela-series-other: #8794a6;
 }
 
 /* Opt in, because a theme that repaints a host's <body> uninvited is not a

data/app/controllers/janela/application_controller.rb

@@ -50,11 +50,11 @@ module Janela
       end
 
       def janela_not_found(error)
-        janela_error(error, :not_found, "There is no such pane.")
+        janela_error(error, :not_found, I18n.t("janela.errors.not_found"))
       end
 
       def janela_bad_request(error)
-        janela_error(error, :bad_request, "That request is not allowed on this pane.")
+        janela_error(error, :bad_request, I18n.t("janela.errors.bad_request"))
       end
 
       # The detail names models and filter keys, so it goes to the log; the

data/app/controllers/janela/panes_controller.rb

@@ -76,7 +76,7 @@ module Janela
       end
 
       def pane_params
-        params.expect(pane: [ :kind, :model, :measure, :dimension, :renderer, :granularity, :limit, :height, :prominence, :span, :title,
+        params.expect(pane: [ :kind, :model, :measure, :dimension, :renderer, :granularity, :limit, :height, :prominence, :value_labels, :span, :title,
                               :heading, :body, :link, :partial, { companions: [] } ])
       end
 

data/app/controllers/janela/queries_controller.rb

@@ -10,6 +10,7 @@ module Janela
         limit: params[:limit],
         height: params[:height],
         prominence: params[:prominence],
+        value_labels: params[:value_labels],
         companions: params[:companions],
         filters: filters,
         fixed: fixed_filters

data/app/controllers/janela/snapshot_queries_controller.rb

@@ -15,6 +15,7 @@ module Janela
         limit: params[:limit],
         height: params[:height],
         prominence: params[:prominence],
+        value_labels: params[:value_labels],
         companions: params[:companions],
         snapshot: snapshot
       )

data/app/helpers/janela/frames_helper.rb

@@ -28,13 +28,15 @@ module Janela
     # rather than a different id every time the query changes (ADR 029).
     #
     # prominence: is one of three steps for a single value, and height: one of
-    # five for a chart. Both travel in the pane's URL for the same reason.
+    # five for a chart. Both travel in the pane's URL for the same reason, and
+    # so does value_labels:, which puts each bar's value on a bar chart (ADR 054).
     # height: is one of five steps, and travels in the pane's URL because the
     # server draws the pane from it again on every cross-filter. It is not part
     # of the frame's id: how tall a pane is does not say which query it is
     # (ADR 047, ADR 029).
-    def janela_pane(model, measure, by: nil, as: :table, granularity: nil, limit: nil, height: nil, prominence: nil, companions: nil, id: nil)
-      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit, height: height, prominence: prominence, companions: companions.presence,
+    def janela_pane(model, measure, by: nil, as: :table, granularity: nil, limit: nil, height: nil, prominence: nil, value_labels: nil, companions: nil, id: nil)
+      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit, height: height, prominence: prominence,
+                value_labels: (1 if value_labels), companions: companions.presence,
                 where: @janela_fixed_filters.presence }.compact
       base = janela_routes.pane_path(model.model_name.route_key, measure, by, **query)
 
@@ -46,15 +48,31 @@ module Janela
 
     # A pane as it was when the snapshot was taken: same shape as janela_pane,
     # not part of the live frame's filter state (ADR 009).
-    def janela_snapshot_pane(snapshot, model, measure, by: nil, as: :table, granularity: nil, limit: nil, height: nil, prominence: nil, companions: nil)
+    def janela_snapshot_pane(snapshot, model, measure, by: nil, as: :table, granularity: nil, limit: nil, height: nil, prominence: nil, value_labels: nil, companions: nil)
       query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit, height: height,
-                prominence: prominence, companions: companions.presence }.compact
+                prominence: prominence, value_labels: (1 if value_labels), companions: companions.presence }.compact
       src = janela_routes.snapshot_pane_path(snapshot, model.model_name.route_key, measure, by, **query)
 
       turbo_frame_tag Query.turbo_frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit, snapshot: snapshot),
         src: src, loading: :lazy
     end
 
+    # What a stored pane draws, inline in the host's own request. The engine's
+    # pane page rescues a refused request in its controller; there is none above
+    # this, so a refusal would be a server error for the whole host page. A
+    # filter a model does not declare is still refused (ADR 025), only now by
+    # the one pane that cannot honour it. The detail names models and filter
+    # keys, so it goes to the log and the reader sees the plain sentence. A
+    # missing scope is deliberately not rescued: that is a host to be told, not
+    # a pane that cannot be drawn (ADR 032, #83).
+    def janela_pane_body(pane, filters:, fixed:, charts:)
+      query = pane.query(filters: filters, fixed: fixed, renderer: pane.chart? && !charts ? "table" : pane.renderer)
+      render "janela/queries/query", query: query, result: query.result(on: janela_scope(query.model))
+    rescue Janela::BadRequest, Janela::NotFound => error
+      Rails.logger.warn("Janela: pane #{pane.id}: #{error.message}")
+      tag.p(t(error.is_a?(Janela::NotFound) ? "janela.errors.not_found" : "janela.errors.bad_request"), class: "janela-pane janela-error")
+    end
+
     private
       # Wired once per frame, so a host asks a pane to go to a different query
       # by dispatching an event from anywhere inside rather than by reaching

data/app/models/janela/pane.rb

@@ -84,7 +84,7 @@ module Janela
     # instead (ADR 018).
     def query(filters: {}, fixed: {}, renderer: self.renderer)
       Query.new(definition: definition, measure: measure.to_sym, dimension: dimension.presence&.to_sym,
-                renderer: renderer, granularity: granularity, limit: limit, height: height, prominence: prominence, companions: companions, filters: filters, fixed: fixed,
+                renderer: renderer, granularity: granularity, limit: limit, height: height, prominence: prominence, value_labels: value_labels, companions: companions, filters: filters, fixed: fixed,
                 default: frame.default_for(definition.model), title: title)
     end
 

data/app/models/janela/query.rb

@@ -33,7 +33,7 @@ module Janela
     # dimension's shared fact, by label.
     Companion = Struct.new(:name, :header, :fact, :cells, keyword_init: true)
 
-    attr_reader :definition, :measure, :dimension, :renderer, :limit, :height, :prominence, :companions, :filters, :fixed, :default, :snapshot
+    attr_reader :definition, :measure, :dimension, :renderer, :limit, :height, :prominence, :value_labels, :companions, :filters, :fixed, :default, :snapshot
 
     # The helper renders the turbo frame and the controller renders its
     # replacement, so both derive the id the same way from the same parameters.
@@ -43,7 +43,7 @@ module Janela
       parts.compact.join("_")
     end
 
-    def initialize(definition:, measure:, dimension: nil, renderer: "table", granularity: nil, limit: nil, height: nil, prominence: nil, companions: nil, filters: {}, fixed: {}, default: {}, snapshot: nil, title: nil)
+    def initialize(definition:, measure:, dimension: nil, renderer: "table", granularity: nil, limit: nil, height: nil, prominence: nil, value_labels: nil, companions: nil, filters: {}, fixed: {}, default: {}, snapshot: nil, title: nil)
       @definition = definition
       @title = title
       @measure = measure
@@ -59,6 +59,7 @@ module Janela
       @limit = definition.limit!(limit) if limit.present?
       @height = height!(height) if height.present?
       @prominence = prominence!(prominence) if prominence.present?
+      @value_labels = value_labels!(value_labels)
       @companions = companions!(companions)
     end
 
@@ -73,6 +74,16 @@ module Janela
       definition.measure!(measure).format(value)
     end
 
+    # What a chart's value axis needs to read like the measure's own numbers
+    # (ADR 054). The ticks are chosen in the browser and so cannot be formatted
+    # here; this is the part of the format a tick can use. Precision is left out
+    # because a tick's decimals follow the spacing between ticks, not what one
+    # value means.
+    def tick_format
+      declared = definition.measure!(measure)
+      { prefix: declared.prefix.to_s, suffix: declared.suffix.to_s, ratio: declared.ratio? }
+    end
+
     def single_value?
       dimension.nil?
     end
@@ -110,6 +121,13 @@ module Janela
       single_value? && !prominence.nil?
     end
 
+    # Only a bar has a bar to put a value on. A line, a ring, a table and a
+    # single value ignore the flag, so a pane switched between renderers keeps
+    # it (ADR 054).
+    def labelled?
+      value_labels && chart? && renderer == "bar"
+    end
+
     def boxed?
       chart? && !height.nil?
     end
@@ -388,6 +406,16 @@ module Janela
         end
       end
 
+      # A yes or a no from a URL or a form, with unset the same as no. Anything
+      # else is refused rather than read as one of them.
+      def value_labels!(value)
+        case value.to_s
+        when "", "0", "false" then false
+        when "1", "true" then true
+        else raise BadRequest, "value_labels must be 1 or 0, got #{value.inspect}"
+        end
+      end
+
       def prominence!(value)
         step = Integer(value.to_s, exception: false)
         raise BadRequest, "prominence must be a whole number from #{PROMINENCES.first} to #{PROMINENCES.last}, got #{value.inspect}" unless PROMINENCES.cover?(step)

data/app/views/janela/frames/_pane.html.erb

@@ -5,8 +5,9 @@
     change, which is what makes cross-filtering work from here. %>
 <%# A table needs no JavaScript, so it is what a surface with no chart runtime
     shows in place of an empty canvas (ADR 018). %>
-<% query = pane.query(filters: filters, fixed: fixed, renderer: pane.chart? && !charts ? "table" : pane.renderer) %>
+<%# A pane Janela will not draw is that pane's sentence and not the page's
+    error, as it is on the engine's own pane page (#83). %>
 <%= turbo_frame_tag pane.turbo_frame_id, class: "janela-span-#{pane.span}",
       data: { janela__frame_target: "pane", janela_src: janela_routes.frame_pane_path(pane.frame_id, pane, where: fixed.presence) } do %>
-  <%= render "janela/queries/query", query: query, result: query.result(on: janela_scope(query.model)) %>
+  <%= janela_pane_body(pane, filters: filters, fixed: fixed, charts: charts) %>
 <% end %>