janela 0.13.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76a888911baddb25729442ecf07cf8975467f05792eb1881d1a6c9ec1c3d05e9
-  data.tar.gz: e3718fafdaf889aed3fd4459b722e5ed0db5b39ecffb771cb4c5599c34c0bfb9
+  metadata.gz: 9b6b7c6d32876fc33b9c40e07278094bc901c548ac355d30f2d4cd2048f41cde
+  data.tar.gz: c60ff46e6023319430c63a53ee5bae675fbf98541e6639982b62c5d79cd0b76b
 SHA512:
-  metadata.gz: 3cb99e213c2afbf7e7a570fe4c02b34f1c07fb6d7dc70e0d0fad4753c50264a3466e6f7661c52fb545a4ffa6b50a8fb1b63a6eed5e3ecbd4dd6b7670f21ed9ec
-  data.tar.gz: d9fbcebdd34dd825aeb98c98dc449ce92be38b50b1839e83c838730c0c5e9c3258e42d8410d818702032642496688279c0a9e1c361621d228d50dd7e92b9ea6d
+  metadata.gz: a48f8cd95951b00dfd10bf9d3a4ee9476bf486cd3660618a83f561259e61c61e22289cbce2647fe75b8463d14d25aa710354d760ad549bbf51e25d5ae67cdecb
+  data.tar.gz: 92f1c1a0b289f523a81b4a00d6c7c63b50d480e199d0ac42ffb0db34dc98064d4b9b44b01e0dc65d5f485fcbd4e6eb6a9d897401ad197522c66ad7541cbf85a0

data/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.15.0] - 2026-10-13
+
+### Added
+
+- **A category pane can be sorted by its measure either way, or by its label.** `janela_pane Order, :revenue, by: :customer, limit: 5, sort: :asc` shows the bottom five, and `janela_pane Order, :revenue, by: :cycle, as: :bar, sort: :label` draws a chart in the dimension's own order. `sort` takes `desc` (the default, and what every pane did before), `asc`, `label` and `label_desc`, as a select on the pane form and in `Janela::Tools`, and travels in the pane URL as `?sort=asc`. The limit follows the order, so `asc` with a limit is the real smallest rows and not the largest turned round, which the view could not do. A label order is the database sorting the column, so a number is in numeric order, a date in date order and a string in the database's collation. The `(none)` group is last in every order, because SQLite and PostgreSQL disagree about where NULL sorts. A time pane is always in time order and ignores it. Stored panes need a migration; see `UPGRADING.md`. `Janela.sorts` lists the four for a page that offers them as controls (ADR 055, #75, #80).
+
+### Changed
+
+- **Groups tied on the measure now come out by label.** Two groups with the same value used to come out in whatever order the database produced, which with a `limit` decided which of them was shown at all. They are now in label order, ascending, in either direction. A pane with no ties draws exactly what it did. A set `sort` is part of the pane's frame id (`..._top5_asc`), and an unset one leaves every existing id as it was (ADR 055).
+
+## [0.14.0] - 2026-10-07
+
+### Added
+
+- **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 +299,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.15.0]: https://github.com/retail-tasker/janela/releases/tag/v0.15.0
+[0.14.0]: https://github.com/retail-tasker/janela/releases/tag/v0.14.0
 [0.13.0]: https://github.com/retail-tasker/janela/releases/tag/v0.13.0
 [0.12.0]: https://github.com/retail-tasker/janela/releases/tag/v0.12.0
 [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.15"
 ```
 
 ```ruby
@@ -224,7 +224,7 @@ Compose panes on any page. Each pane is a Turbo Frame; clicking a value in one r
 <% end %>
 ```
 
-A pane with no `by:` is the measure's single total, the KPI tile. `limit: 10` keeps the top ten rows or bars. `as:` is `:table` by default, `:bar` for a Chart.js bar chart, `:doughnut` or `:pie` for a part-to-whole split, or `:line`, which suits a time dimension: `janela_pane Order, :revenue, by: :placed_on, as: :line, granularity: :week`. A chart fills its container's width at Chart.js's default aspect ratio, so wrap it in an element with the width you want. Clicking a bar does exactly what clicking a table value does.
+A pane with no `by:` is the measure's single total, the KPI tile. `limit: 10` keeps the top ten rows or bars, and `sort:` changes which ten (see below). `as:` is `:table` by default, `:bar` for a Chart.js bar chart, `:doughnut` or `:pie` for a part-to-whole split, or `:line`, which suits a time dimension: `janela_pane Order, :revenue, by: :placed_on, as: :line, granularity: :week`. A chart fills its container's width at Chart.js's default aspect ratio, so wrap it in an element with the width you want. Clicking a bar does exactly what clicking a table value does.
 
 A doughnut or a pie is drawn on the server as SVG with a legend of buttons beside it, so it is in the page before any JavaScript runs and can be operated from the keyboard through the legend. Bars, doughnut slices and pie slices are drawn in a palette of eight colours by position, first to eighth, and every value after the eighth in one neutral, so a ring suits a handful of values: `limit: 8` keeps it readable. A ring cannot show a negative value, so a pane with one is drawn as a table and says so. The palette is `--janela-series-1` to `--janela-series-8` and `--janela-series-other` in [docs/theming.md](docs/theming.md) (ADR 046).
 
@@ -232,6 +232,10 @@ 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).
 
+**Sorting.** A breakdown by a category is largest first by default. `sort: :asc` puts the smallest first, so `limit: 5` is the bottom five, and `sort: :label` and `sort: :label_desc` order by the dimension's own value, which suits a label whose text is already the natural order, such as a period code (`janela_pane Order, :revenue, by: :cycle, as: :bar, sort: :label`). The limit follows the order. A number or a date column sorts as itself, and text sorts by your database's collation, which is not the same everywhere. The `(none)` group is always last. Groups that tie on the measure come out by label. It is a select on the pane form, `sort:` in `Janela::Tools`, and `?sort=` in the pane URL. A time series is always in time order and ignores it (ADR 055).
+
+**Value labels.** A bar chart shows a value only in its tooltip unless the pane asks for it on the bar: `value_labels: true` (`janela_pane Order, :expedited_rate, by: :channel, as: :bar, value_labels: true`), or the checkbox on the pane form. The label is the same string the tooltip shows, the measure's own format, drawn beyond the end of the bar: above a positive one and below a negative. It is all or none: if any label is wider than its bar's share of the chart, none is drawn, rather than some bars carrying a number and others not. Make the chart wider or `limit:` the bars. 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 +400,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 +565,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.15.0 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering with multi-selection, bar, line, doughnut and pie charts, pane URLs, shareable dashboard URLs, snapshots, database-backed frames found by owner and key, panes that hold words or a host partial as well as a query, a host-fixed filter no click can remove and a frame's own permanent one beside it, STI subclasses, the engine's own pages for reading and editing them, bar charts that read in their measure's format and can show each bar's value, category panes that can be ordered either way by their measure or by their label, tools an agent can use to read and arrange a dashboard, and the optional vitral theme work and are covered by unit and real-browser tests, with the classes a theme may target documented in [Theming Janela](docs/theming.md). Not yet built: a visual editor, and narrowing a time pane's own granularity by clicking one of its buckets (a click on a bucket does filter the others). [Vista](docs/roadmap.md), the roadmap, says what 1.0 means and which of these are in it; open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
 
 ## Development
 

data/UPGRADING.md

@@ -12,6 +12,53 @@ bin/rails janela:doctor
 
 It reads your application and lists what still needs changing.
 
+## 0.14.0 to 0.15.0
+
+One migration step, if you use stored frames.
+
+**Take the pane migration.**
+
+A category pane can now be sorted (ADR 055). `janela_panes` gains a nullable
+string `sort`:
+
+```bash
+bin/rails janela:install:migrations
+bin/rails db:migrate
+```
+
+Every existing pane keeps it nil and is ordered exactly as before, largest
+first. If you never use stored frames, there is nothing to do.
+`bin/rails janela:doctor` names the column if a stored-frames host skips the
+step.
+
+**If you carry a patch that orders panes,** it can go: `sort: :asc` and
+`sort: :label` are the options it was written to add. Groups that tie on the
+measure now come out in label order where they used to come out in the
+database's, so a pane that was relying on that has nothing to change and is
+now the same every time.
+
+## 0.13.0 to 0.14.0
+
+One migration step, if you use stored frames.
+
+**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, :sort, :height, :prominence, :value_labels, :span, :title,
                               :heading, :body, :link, :partial, { companions: [] } ])
       end
 

data/app/controllers/janela/queries_controller.rb

@@ -8,8 +8,10 @@ module Janela
         renderer: params.fetch(:as, "table"),
         granularity: params[:granularity],
         limit: params[:limit],
+        sort: params[:sort],
         height: params[:height],
         prominence: params[:prominence],
+        value_labels: params[:value_labels],
         companions: params[:companions],
         filters: filters,
         fixed: fixed_filters

data/app/controllers/janela/snapshot_queries_controller.rb

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

data/app/helpers/janela/frames_helper.rb

@@ -28,17 +28,19 @@ 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, sort: nil, height: nil, prominence: nil, value_labels: nil, companions: nil, id: nil)
+      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit, sort: sort, 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)
 
-      turbo_frame_tag id || Query.turbo_frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit),
+      turbo_frame_tag id || Query.turbo_frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit, sort: sort),
         src: janela_with_page_filters(base),
         loading: :lazy,
         data: { janela__frame_target: "pane", janela_src: base }
@@ -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)
-      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit, height: height,
-                prominence: prominence, companions: companions.presence }.compact
+    def janela_snapshot_pane(snapshot, model, measure, by: nil, as: :table, granularity: nil, limit: nil, sort: nil, height: nil, prominence: nil, value_labels: nil, companions: nil)
+      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit, sort: sort, height: height,
+                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),
+      turbo_frame_tag Query.turbo_frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit, sort: sort, 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

@@ -14,6 +14,10 @@ module Janela
     # How prominent a single value is drawn (ADR 050).
     PROMINENCES = Query::PROMINENCES
     LIMITS = (1..1000).freeze
+
+    # How a category pane is ordered (ADR 055). Nil is the default, largest
+    # first by the measure.
+    SORTS = Definition::SORTS
     # A form cannot offer a thousand options, and these are the row counts a
     # dashboard actually asks for. Any limit inside LIMITS is still valid.
     OFFERED_LIMITS = [ 5, 10, 20, 50, 100 ].freeze
@@ -38,8 +42,11 @@ module Janela
     validates :kind, inclusion: { in: KINDS }
     validates :span, inclusion: { in: SPANS }
     validates :limit, inclusion: { in: LIMITS }, allow_nil: true
+    validates :sort, inclusion: { in: SORTS }, allow_nil: true
     validates :height, inclusion: { in: HEIGHTS }, allow_nil: true
     validates :prominence, inclusion: { in: PROMINENCES }, allow_nil: true
+    # A form sends an empty string for "Largest first", which is unset.
+    normalizes :sort, with: ->(value) { value.presence }
     before_validation :normalise_companions
     validate :companions_are_declared
     validates :measure, presence: true, if: :query?
@@ -84,7 +91,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, sort: sort, 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,17 +33,18 @@ 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, :sort, :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.
-    def self.turbo_frame_id(model:, measure:, by: nil, as: :table, granularity: nil, limit: nil, snapshot: nil)
+    def self.turbo_frame_id(model:, measure:, by: nil, as: :table, granularity: nil, limit: nil, sort: nil, snapshot: nil)
       parts = [ "janela", ("snapshot_#{snapshot.id}" if snapshot), model.model_name.route_key, measure, by,
-                (granularity if by), (as unless by.nil?), ("top#{limit}" if by && limit) ]
+                (granularity if by), (as unless by.nil?), ("top#{limit}" if by && limit),
+                (sort if by && sort.present? && sort.to_s != "desc") ]
       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, sort: nil, height: nil, prominence: nil, value_labels: nil, companions: nil, filters: {}, fixed: {}, default: {}, snapshot: nil, title: nil)
       @definition = definition
       @title = title
       @measure = measure
@@ -57,8 +58,13 @@ module Janela
       raise BadRequest, "unknown pane renderer #{renderer.inspect}" unless RENDERERS.include?(@renderer)
       @granularity = Dimension.granularity!(granularity) if granularity.present?
       @limit = definition.limit!(limit) if limit.present?
+      # Unset and desc are the same pane, and stay the same id and the same
+      # snapshot key (ADR 055).
+      chosen = definition.sort!(sort)
+      @sort = chosen unless chosen == "desc"
       @height = height!(height) if height.present?
       @prominence = prominence!(prominence) if prominence.present?
+      @value_labels = value_labels!(value_labels)
       @companions = companions!(companions)
     end
 
@@ -73,6 +79,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 +126,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
@@ -188,7 +211,7 @@ module Janela
 
     def turbo_frame_id
       self.class.turbo_frame_id(model: model, measure: measure, by: dimension, as: renderer,
-                          granularity: @granularity, limit: limit, snapshot: snapshot)
+                          granularity: @granularity, limit: limit, sort: sort, snapshot: snapshot)
     end
 
     # A pane row may carry its own title, which is the first analyst authored
@@ -208,7 +231,7 @@ module Janela
     # What identifies this pane's data inside a snapshot.
     def lookup_key
       { "model" => model.model_name.route_key, "measure" => measure.to_s, "dimension" => dimension&.to_s,
-        "granularity" => granularity&.to_s, "limit" => limit }
+        "granularity" => granularity&.to_s, "limit" => limit }.tap { |key| key["sort"] = sort if sort }
     end
 
     def result(on: nil)
@@ -220,7 +243,7 @@ module Janela
       # selection, which this pane shows the alternatives to (ADR 040, 043).
       on = definition.narrow(on || model.all, default) if default.present?
       on = definition.narrow(on || model.all, fixed) if fixed.present?
-      primary = time? ? time_result(on) : definition.query(measure, by: dimension, where: applicable_filters, on: on, granularity: granularity, limit: limit)
+      primary = time? ? time_result(on) : definition.query(measure, by: dimension, where: applicable_filters, on: on, granularity: granularity, limit: limit, sort: sort)
       @companion_columns = companions? ? fetch_companions(primary, on) : []
       primary
     end
@@ -388,6 +411,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/models/janela/snapshot.rb

@@ -40,9 +40,9 @@ module Janela
         @panes = []
       end
 
-      def pane(model, measure, by: nil, granularity: nil, limit: nil, on: nil)
+      def pane(model, measure, by: nil, granularity: nil, limit: nil, sort: nil, on: nil)
         query = Query.new(definition: model.janela, measure: measure, dimension: by,
-                          granularity: granularity, limit: limit, filters: filters)
+                          granularity: granularity, limit: limit, sort: sort, filters: filters)
         panes << query.lookup_key.merge("result" => plain(query.result(on: on)))
       end
 

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

@@ -41,6 +41,13 @@
     <%= form.select :limit, Janela::Pane::OFFERED_LIMITS, include_blank: t("janela.panes.no_limit") %>
   </div>
 
+  <%# Blank is largest first, so desc is not offered a second time. %>
+  <div class="janela-field">
+    <%= form.label :sort %>
+    <%= form.select :sort, (Janela.sorts - %w[desc]).map { |value| [ t("janela.sorts.#{value}"), value ] }, include_blank: t("janela.sorts.desc") %>
+    <span class="janela-hint"><%= t("janela.sorts.hint") %></span>
+  </div>
+
   <%# What may sit beside the label: this model's other measures and its
       categorical dimensions. The pane's own choices are left out when they are
       already made (ADR 051). %>
@@ -66,6 +73,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

@@ -19,12 +19,17 @@ en:
         renderer: Renderer
         granularity: Granularity
         limit: Rows
+        sort: Order
         span: Width
         height: Height
         prominence: Prominence
+        value_labels: Show each bar's value
         companions: Beside the label
         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 +76,14 @@ 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.
+    sorts:
+      desc: Largest first
+      asc: Smallest first
+      label: By label, A to Z
+      label_desc: By label, Z to A
+      hint: Applies to a breakdown by a category. A time series is always in time order.
     prominences:
       automatic: Automatic
       "1": Footnote

data/db/migrate/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/db/migrate/20261013000001_add_sort_to_janela_panes.rb

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