janela 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76a888911baddb25729442ecf07cf8975467f05792eb1881d1a6c9ec1c3d05e9
-  data.tar.gz: e3718fafdaf889aed3fd4459b722e5ed0db5b39ecffb771cb4c5599c34c0bfb9
+  metadata.gz: 69f4c0147424e4d9350bcee373b832e922f54b1686acce5c80fa776432a288c6
+  data.tar.gz: ec2f91ec4c87dcfeb49154b54e0cda105f293e8b56580fb774750011fb9277df
 SHA512:
-  metadata.gz: 3cb99e213c2afbf7e7a570fe4c02b34f1c07fb6d7dc70e0d0fad4753c50264a3466e6f7661c52fb545a4ffa6b50a8fb1b63a6eed5e3ecbd4dd6b7670f21ed9ec
-  data.tar.gz: d9fbcebdd34dd825aeb98c98dc449ce92be38b50b1839e83c838730c0c5e9c3258e42d8410d818702032642496688279c0a9e1c361621d228d50dd7e92b9ea6d
+  metadata.gz: 38e32300abc75aa9b738d63b2d7f638dff0d9f153e19aa32f1cb5cbd422702c4e236bc93b87e7c4474836bbd3bfddfad4f83fbaa95d523efee8e6b82b6246b12
+  data.tar.gz: fe82fff29b230ecab68eb8c14e162d214ee9c1666ead178145c73ffe776e635b8acd59fa8cc1df1011a9f091b2d50e9d9fe299e67142657ed59e69fa1d70d120

data/CHANGELOG.md

@@ -5,6 +5,22 @@ 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
@@ -273,6 +289,7 @@ 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

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.13"
+gem "janela", "~> 0.14"
 ```
 
 ```ruby
@@ -232,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.
@@ -396,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| %>
@@ -561,7 +563,7 @@ Deliberately out of scope: natural-language query, a separate data warehouse, a
 
 ## Status
 
-**v0.13.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, 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.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
 

data/UPGRADING.md

@@ -12,6 +12,28 @@ 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.

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/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 %>

data/app/views/janela/panes/_form.html.erb

@@ -66,6 +66,12 @@
     <%= form.select :prominence, Janela::Pane::PROMINENCES.map { |step| [ t("janela.prominences.#{step}"), step ] }, include_blank: t("janela.prominences.automatic") %>
   </div>
 
+  <div class="janela-field">
+    <%= form.check_box :value_labels %>
+    <%= form.label :value_labels %>
+    <span class="janela-hint"><%= t("janela.value_labels.hint") %></span>
+  </div>
+
   <div class="janela-field">
     <%= form.label :span %>
     <%= form.select :span, Janela::Pane::SPANS.to_a %>

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

@@ -27,8 +27,10 @@
            "janela--chart-labels-value": result.keys.to_json,
            "janela--chart-values-value": result.values.map(&: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-fixed-height-value": (true if query.boxed?),
+           "janela--chart-value-labels-value": (true if query.labelled?)
          }) %>
     <%= query.boxed? ? tag.div(canvas, class: "janela-chart-box janela-h-#{query.height}") : canvas %>
   </figure>

data/config/locales/en.yml

@@ -22,9 +22,13 @@ en:
         span: Width
         height: Height
         prominence: Prominence
+        value_labels: Show each bar's value
         companions: Beside the label
         title: Title
   janela:
+    errors:
+      not_found: There is no such pane.
+      bad_request: That request is not allowed on this pane.
     actions:
       add_pane: "Add a %{name}"
       cancel: Cancel
@@ -71,6 +75,8 @@ 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.
+    value_labels:
+      hint: Draws the value at the end of each bar of a bar chart, if every one fits. Other charts ignore it.
     prominences:
       automatic: Automatic
       "1": Footnote

data/db/migrate/20261006000001_add_value_labels_to_janela_panes.rb

@@ -0,0 +1,7 @@
+class AddValueLabelsToJanelaPanes < ActiveRecord::Migration[8.0]
+  def change
+    # Whether a bar chart draws each bar's value on the bar (ADR 054). Null is
+    # what every existing pane is: unset, and drawn exactly as before.
+    add_column :janela_panes, :value_labels, :boolean
+  end
+end

data/docs/decisions/020-formatting-belongs-to-the-measure.md

@@ -2,6 +2,7 @@
 Date: 2026-09-16
 Status: Accepted
 Related: ADR 002, ADR 009, ADR 012, ADR 018
+Superseded in part by: ADR 054
 Triggers:
   - a number rendering with more precision than it means
   - adding an option to a pane, a frame or a pane URL
@@ -74,7 +75,9 @@ back under a format declared today.
 and a chart tooltip all show the string the measure produced, and the
 chart is handed those strings rather than formatting a second time in
 JavaScript. The chart still plots raw numbers, because an axis is a
-scale and not a label.
+scale and not a label. (Superseded in part by
+ADR 054: the axis is formatted by the measure too. The chart still plots
+raw numbers.)
 
 ## Consequences
 

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

@@ -0,0 +1,221 @@
+---
+Date: 2026-10-06
+Status: Accepted
+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
+  - drawing text on a chart canvas, or adding a Chart.js plugin
+  - adding a boolean to a pane, a column to janela_panes, or a parameter to the pane URL
+  - a ratio, a currency or a percentage on a chart
+  - a chart too dense to label every bar
+Topics: charts, formatting, measures, public-api, panes, urls
+---
+
+# ADR 054: A Chart Reads Numbers the Way Its Measure Formats Them
+
+## Context
+
+#72 and #76, raised from a real install building a client report: a share
+of rows by category, drawn as bars, with the percentage on each bar. Two
+things stood in the way, and both are the same gap. A chart is the one
+place a number reaches a reader without the measure's format applied
+(ADR 020), except the tooltip, which a reader has to hover to see.
+
+Both were reproduced against the demo on `main` (Chart.js 4.5.1), with the
+chart built live and the drawn scale read from it.
+
+**The axis is raw.** A bar chart of a ratio drew ticks `0, 0.1 ... 1.0`
+beside tooltips reading `0.0%`. Revenue drew `0, 50,000 ... 500,000` beside
+tooltips reading `$469,097.85`. `chart_controller.js` sets
+`scales: { y: { beginAtZero: true } }` and formats only the tooltip.
+
+**#72 said this was never decided. It was.** ADR 020 closes its Decision
+with "The chart still plots raw numbers, because an axis is a scale and not
+a label." That sentence is wrong for a reader, who reads the axis as labels
+whatever it is to Chart.js. A ratio's axis at 0.5 against a tooltip at 50.0%
+reads as two different numbers (ADR 038 keeps the stored value a fraction
+for the data's sake, which is not a reason for the axis to show one). The
+rest of ADR 020 stands: the number is never rounded or transformed, and the
+measure is the layer that owns its format.
+
+**Tick precision does not need a rule of Janela's own.** The worry in #72
+was that ticks fall between data points, so the precision that suits a
+value (`25.0%`) is wrong for a tick (`25%`). Chart.js's own numeric tick
+formatter already derives its decimals from the spacing between ticks.
+Calling it with a ratio's ticks scaled by 100 and appending `%` gave, on the
+live chart:
+
+| ratio data up to | ticks |
+| --- | --- |
+| 0.53 | `0%, 10% ... 60%` |
+| 0.03 | `0%, 0.5%, 1% ... 3%` |
+| 1 | `0% ... 100%` |
+
+Whole percentages where the spacing is whole, half percentages only where
+the ticks really are half a percent apart. One catch: scaling by 100 leaves
+float noise (`3.5000000000000004%`), so the scaled value has to be rounded
+before it is formatted.
+
+**A bar label has to fit, and nothing guarantees it does.** Measured with a
+label drawn at each bar's end:
+
+- The tallest bar of a default chart touches the top of the plot area, so a
+  label above it is clipped. `scales.y.grace = "10%"` left 30px of
+  headroom in a 300px chart, and Chart.js 4.5.1 supports it.
+- A label inside the bar was never an option: the shortest bars are about
+  2px tall.
+- With 30 bars in a 600px chart a bar was 13px wide and a label such as
+  `$88,000.00` was 60px, so neighbouring labels overlap several deep.
+  Hiding only the ones that collide would label some bars and not others
+  for a reason a reader cannot see.
+- A negative bar ends below its base, so a label placed above the end would
+  sit on the bar.
+- A plugin cannot be added to a chart after it is built, so the drawing has
+  to be handed over when the controller constructs the chart, as
+  `maintainAspectRatio` is for a height (ADR 047).
+
+### What was considered
+
+**Formatted tick strings from the server.** The server formats a value
+(ADR 020), but the client chooses the ticks, where they fall depends on the
+chart's size and data, and the server cannot know them. It would have to
+format values it is never asked about.
+
+**A `precision` of the measure's own for ticks.** A measure's precision is
+what one value means. A scale spanning `$0` to `$500,000` in steps of
+50,000 does not want cents, and a ratio at one decimal place would print
+`20.0%` at every tick. It is the answer to a different question.
+
+**A host-supplied tick callback.** A setting, to do what one formatter
+already does for every measure. ADR 001 prefers one obvious way, and ADR 021
+and ADR 023 only allow a setting where a judgement is made once at boot.
+
+**`chartjs-plugin-datalabels` for the bar labels.** A dependency, and a
+second way to format a number on a chart. ADR 004 keeps Chart.js the one
+thing the engine ships, and an inline plugin that draws a string the server
+already produced is about twenty lines.
+
+**Labels on by default.** Changes every bar chart that exists, and a chart
+of thirty bars gains nothing from it. Unset must change nothing, as it does
+for height and prominence.
+
+**A setting for where the label sits, or whether it fits.** Outside the end
+is the only place that works for every bar, including the shortest and the
+negative, and a fit that is a judgement per chart is a decision a reader of
+the dashboard cannot see made.
+
+**Labels on a line, or on a ring.** A line has a point per bucket, often
+sixty or more, and a ring already prints every value beside it (ADR 046).
+Neither gains from it.
+
+## Decision
+
+**A chart's axis is formatted by the measure, always, and a bar chart can
+be asked to draw each bar's value as a label.** The first supersedes the one
+sentence in ADR 020 above and nothing else in it. The second is opt in.
+
+### The axis
+
+The server sends what a tick needs as one more data attribute on the canvas:
+the measure's `prefix`, its `suffix`, and whether it is a ratio.
+
+```erb
+data-janela--chart-tick-format-value='{"prefix":"$","suffix":"","ratio":false}'
+```
+
+The controller formats each tick with Chart.js's own numeric formatter and
+adds those. A ratio's ticks are scaled by 100, rounded to remove float
+noise, and given a `%`. The measure's `precision` is not used: the tick's
+decimals come from the spacing between ticks, which is what answers "25%,
+not 25.0%". It applies to a bar and a line, both of which have a value axis,
+and it is not a setting: it is what the axis always was, now correct.
+
+A measure with no prefix, suffix or ratio draws what it draws today.
+
+### The labels
+
+**A pane may carry `value_labels`, a boolean. Unset is exactly what it is
+today.** When set on a bar chart, each bar's formatted string, the same one
+the tooltip shows, is drawn beyond the end of the bar, above for a positive
+value and below for a negative one. The value axis is given 10% of grace so
+the tallest bar keeps its label in the plot.
+
+**All or none.** The labels are drawn only if every one of them fits within
+its category's slot, the chart area's width divided by the number of bars.
+If any does not, none is drawn and the chart is what it was without the flag.
+A chart never labels some bars and not others, and a host that wants the
+labels on a dense chart makes the chart wider or the pane a bar chart of
+fewer categories (`limit:`, ADR 007).
+
+**One vocabulary in three places,** as height and prominence do:
+
+```erb
+<%= janela_pane Order, :expedited_rate, by: :status, as: :bar, value_labels: true %>
+```
+
+- `Janela::Pane#value_labels`, a nullable boolean, offered on the pane form
+  as a checkbox.
+- `janela_pane` and `janela_snapshot_pane` take `value_labels:`.
+- The pane URL carries it as `?value_labels=1`, because the server draws the
+  pane again from that URL on every cross-filter.
+
+**The name avoids `labels`.** In this codebase a chart's labels are its
+categories: the controller's `labels` value is the x axis. `value_labels`
+says which labels, and `values` would collide the same way with the
+controller's `values`. It is the one name that reads the same at the helper,
+the column, the URL and the controller (ADR 037).
+
+**It is not part of the pane's identity.** ADR 029 identifies a frame by who
+it is, and whether its bars carry numbers does not say which query it is. It
+stays out of `Query.turbo_frame_id`.
+
+**On anything that is not a bar chart it is ignored, not an error.** A
+table, a single value, a line and a ring keep what they have, and a pane
+switched between renderers keeps the flag, as height does on a ring
+(ADR 047).
+
+## Consequences
+
+- **Every existing chart's axis can change.** A revenue chart gains a `$`
+  on its ticks and a ratio chart reads in percentages. Nothing else about it
+  moves, and a measure with no prefix, suffix or ratio is untouched. It is
+  in `CHANGELOG.md` under Changed as a visible correction, with no action for
+  a host; it is not an `UPGRADING.md` step (ADR 015), because nothing a host
+  wrote has to change. A host that overrode the tick callback on its own
+  chart is unaffected, since Janela does not set one for it.
+- A ratio chart is readable end to end: a percentage on the axis, in the
+  tooltip, and on the bars if asked.
+- **A migration for stored frames.** `janela_panes` gains a nullable
+  boolean `value_labels`, additive, so every existing pane is unset and
+  unchanged. A host using stored frames runs `bin/rails
+  janela:install:migrations` and `db:migrate`, as it did for `height`,
+  `prominence` and `companions`. The doctor's `unmigrated-columns` check
+  (ADR 035) is taught the new column, so a host that upgrades and skips the
+  migration is told rather than meeting an error on the pane form. A host that
+  does not use stored frames has nothing to do.
+- **`Janela::Tools` has to learn the attribute.** Its `PANE_ATTRIBUTES` is the
+  list of a pane's own attributes an agent may set (ADR 053), and an
+  attribute not on it is refused. `value_labels` joins it in the same change as
+  the column, or an agent could arrange every other part of a pane and not
+  this one.
+- **The pane URL grammar grows by one optional parameter.** ADR 037 counts
+  that as public surface, which is why this belongs before 1.0.
+- **Ticks use the browser's number locale, and the tooltip uses the host's
+  delimiter** (ADR 020). A host whose `number.format.delimiter` differs from
+  its readers' browsers would see two styles on one chart. This is from how
+  Chart.js formats and is not something measured here; if it turns up in
+  practice the answer is to pass the delimiter in the same attribute, not to
+  stop using Chart.js's formatter.
+- The all or none rule means the flag can do nothing on a dense chart, and
+  the pane form cannot say so. That is a real cost, accepted because the
+  alternative is a chart that labels bars selectively.
+- Drawn pixels are not available to a screen reader. That is as true of the
+  bars themselves, which ADR 042 answers with the figure's caption and the
+  table beside it, and this decision does not change it.
+- Tests read what the code produced: the drawn tick labels, and the position
+  and text of each drawn bar label, not the attribute that asked for them
+  (ADR 035).
+- What would change this decision: a need for a label on a line or a ring,
+  which is an argument about those renderers and not about this one; or a
+  host that needs the labels to survive on a dense chart, which would be a
+  case for a step in how they are thinned and not for a placement setting.

data/docs/decisions/INDEX.md

@@ -26,15 +26,15 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | **Dependencies** | 002, 003, 004, 006, 017, 025, 053 |
 | **Authorisation** | 002, 003, 004, 009, 017, 019, 022, 032, 033, 034, 035, 039, 040, 048, 053 |
 | **Performance & storage** | 007, 017, 025, 048, 051 |
-| **Ordering & formatting** | 007, 020, 038 |
+| **Ordering & formatting** | 007, 020, 038, 054 |
 | **Cross-filtering & Hotwire** | 003, 004, 005, 008, 024, 025, 040, 043, 044, 045, 048, 049 |
 | **Layouts & views** | 011, 012, 016, 018, 020, 027, 039, 047, 050 |
 | **CSS & styling** | 016, 018, 023, 026, 027, 036, 042, 046, 047, 050 |
-| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030, 033, 039, 040, 041, 043, 044, 047, 048, 050, 051, 053 |
+| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030, 033, 039, 040, 041, 043, 044, 047, 048, 050, 051, 053, 054 |
 | **Naming rule** | 014, 023, 036 |
-| **JavaScript delivery & charts** | 004, 006, 026, 042, 046, 047 |
+| **JavaScript delivery & charts** | 004, 006, 026, 042, 046, 047, 054 |
 | **Time dimensions** | 006, 025, 045 |
-| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025, 040, 041, 045, 047, 050, 051 |
+| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025, 040, 041, 045, 047, 050, 051, 054 |
 | **Snapshots & publishing** | 009, 020, 028, 033, 034, 051 |
 | **AI agents & guidance** | 010, 015, 021, 053 |
 | **The doctor & checks** | 021, 025, 032, 033, 035 |
@@ -101,7 +101,8 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 051 | A Table Can Carry Companion Columns, and a Fact Is Shown Only When It Is Shared | 2026-09-30 | Accepted |
 | 052 | Two People Cut Releases, Reports Go Private, and Support Is Best Effort | 2026-09-30 | Accepted |
 | 053 | An Agent Reaches Janela Through Tools the Host Scopes, and Janela Registers None | 2026-10-02 | Accepted |
+| 054 | A Chart Reads Numbers the Way Its Measure Formats Them | 2026-10-06 | Accepted |
 
 ## Next number
 
-Next ADR: 054
+Next ADR: 055

data/docs/roadmap.md

@@ -133,7 +133,8 @@ change in any release, and every change of that kind carries an entry in
 
 **A pane can be read.** Janela draws tables, bars, lines, doughnuts and
 pies. A table row can carry context beside its label, a single number says
-how prominent it is, and a chart has a height that suits the page. Those
+how prominent it is, a chart has a height that suits the page, its axis reads
+in the measure's own format, and a bar can show its value. Those
 were not extra features. They were the 5% not finished, and most of them
 were found by people installing the gem rather than reading it.
 
@@ -147,8 +148,12 @@ working is a check nobody should rely on.
 
 The near ground is clear. Every issue that was in 1.0 has shipped: chart
 height, a ratio measure, single value prominence, companion columns, Sprockets
-hosts, and how the project is run. 0.13.0 is out, and adds tools an agent
-can use (ADR 053). What 1.0 waits on now is a week of real installs ([#71](https://github.com/retail-tasker/janela/issues/71)),
+hosts, and how the project is run. 0.13.0 added tools an agent can use
+(ADR 053). 0.14.0 followed: a chart's axis reads in the measure's own format,
+so a ratio is a percentage down the side as well as in the tooltip, and a bar
+chart can show each bar's value (ADR 054). Both came from a real install, and
+the second adds a pane option, so it starts its own short soak. What 1.0 waits
+on now is a week of real installs of 0.14.0 ([#71](https://github.com/retail-tasker/janela/issues/71)),
 since much of that surface was added in the last days and has only met this
 repository. When nothing surprising comes back, the surface is frozen and 1.0
 is tagged. The agent tools are the one new piece of surface: the read tools are
@@ -171,9 +176,14 @@ release, and being on this list is not a refusal.
 - **Telling a frame to refresh** ([#68](https://github.com/retail-tasker/janela/issues/68)).
   One action a host's own timer or push can call, and no timer or stream of
   Janela's own (ADR 048). Additive, so it can land after 1.0.
-- **Vitral's own palette** ([#67](https://github.com/retail-tasker/janela/issues/67)).
-  The optional theme setting its own series colours instead of Janela's
-  neutral ones.
+- **A frame toolbar** ([#77](https://github.com/retail-tasker/janela/issues/77)).
+  A small strip of standard controls a host does not have to build, starting
+  with full screen. Additive, so it can land after 1.0, and it needs a decision
+  record first.
+- **A theme panel in the demo** ([#84](https://github.com/retail-tasker/janela/issues/84)).
+  Setting how every pane is presented, starting with colours, as a page of
+  controls over the properties a theme already publishes. The demo, not the
+  gem, and any property beyond colour needs a decision record first.
 - **A command palette for the demo** ([#41](https://github.com/retail-tasker/janela/issues/41)).
   The demo site, not the gem.
 - **A scroll drift on the gallery page** ([#45](https://github.com/retail-tasker/janela/issues/45)).

data/lib/janela/doctor.rb

@@ -148,7 +148,7 @@ module Janela
       # the same thing twice.
       ADDED_COLUMNS = {
         "Janela::Frame" => %w[key default_model default_where],
-        "Janela::Pane" => %w[kind heading body link partial height prominence companions],
+        "Janela::Pane" => %w[kind heading body link partial height prominence companions value_labels],
         "Janela::Snapshot" => %w[owner_type owner_id]
       }.freeze
 

data/lib/janela/tools.rb

@@ -18,7 +18,7 @@ module Janela
     # The attributes of a pane a caller may set: the ones the README names. The
     # frame, the position and the timestamps are not an agent's to write.
     PANE_ATTRIBUTES = %w[kind model measure dimension renderer granularity limit span title height prominence
-                         companions heading body link partial].freeze
+                         value_labels companions heading body link partial].freeze
     DIRECTIONS = %w[up down].freeze
     READS = %w[describe_vocabulary list_frames get_frame read_pane].freeze
     WRITES = %w[add_pane update_pane remove_pane move_pane].freeze
@@ -209,6 +209,7 @@ module Janela
             title: { type: "string" },
             height: { type: "integer", enum: Pane::HEIGHTS.to_a },
             prominence: { type: "integer", enum: Pane::PROMINENCES.to_a },
+            value_labels: { type: "boolean", description: "Draw each bar's value on a bar chart; other renderers ignore it" },
             companions: { type: "array", items: { type: "string" } },
             heading: { type: "string" },
             body: { type: "string" },

data/lib/janela/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Janela
-  VERSION = "0.13.0"
+  VERSION = "0.14.0"
 end

data/lib/janela.rb

@@ -166,4 +166,19 @@ module Janela
   def self.offered_limits
     Pane::OFFERED_LIMITS
   end
+
+  # 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
+  # (ADR 027, ADR 047, ADR 050, ADR 051).
+  def self.heights
+    Pane::HEIGHTS.to_a
+  end
+
+  def self.prominences
+    Pane::PROMINENCES.to_a
+  end
+
+  def self.max_companions
+    Query::MAX_COMPANIONS
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: janela
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Jay Killeen
@@ -146,6 +146,7 @@ files:
 - db/migrate/20260930000001_add_height_to_janela_panes.rb
 - db/migrate/20260930000002_add_prominence_to_janela_panes.rb
 - db/migrate/20260930000003_add_companions_to_janela_panes.rb
+- db/migrate/20261006000001_add_value_labels_to_janela_panes.rb
 - docs/agents.md
 - docs/composing.md
 - docs/decisions/001-built-to-be-forked.md
@@ -201,6 +202,7 @@ files:
 - docs/decisions/051-a-table-can-carry-companion-columns.md
 - docs/decisions/052-how-the-project-is-run.md
 - docs/decisions/053-an-agent-reaches-janela-through-tools-the-host-scopes.md
+- docs/decisions/054-a-chart-reads-numbers-the-way-its-measure-formats-them.md
 - docs/decisions/INDEX.md
 - docs/multi-tenancy.md
 - docs/naming.md
@@ -227,15 +229,17 @@ metadata:
   bug_tracker_uri: https://github.com/retail-tasker/janela/issues
   rubygems_mfa_required: 'true'
 post_install_message: |
-  Janela 0.13.0: nothing you have to do.
+  Janela 0.14.0: one migration, if you use stored frames.
 
-  New, and only if you want it: Janela::Tools gives an agent the
-  tools to read and arrange a dashboard, scoped by your own
-  policy_scope (ADR 053). Nothing registers itself. See docs/agents.md.
+  A pane can now draw each bar's value on a bar chart (ADR 054), which
+  adds a nullable value_labels column to janela_panes. Run
+  bin/rails janela:install:migrations and then bin/rails db:migrate. If
+  you never use stored frames there is nothing to do.
 
-  Two things you may see: the doctor now warns, rather than errors,
-  on Janela::PanesController, and a copy of
-  janela/queries/_query.html.erb may need checking on Rails 8.2.
+  Also: a chart's axis now reads in the measure's own format, so a
+  currency chart gains its prefix and a ratio reads as percentages. A
+  pane Janela will not draw is now that pane's own sentence and no
+  longer an error for the whole host page.
 
   Steps: UPGRADING.md in this gem, or
   https://github.com/retail-tasker/janela/blob/main/UPGRADING.md