janela 0.13.0 → 0.15.0

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/055-a-category-pane-can-be-sorted-by-its-measure-either-way-or-by-its-label.md

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

data/docs/decisions/INDEX.md

@@ -22,20 +22,20 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 |-------|------|
 | **Vision, scope, forkability** | 001, 010, 012, 037, 052 |
 | **Open-source & host-decoupling** | 001, 022, 036, 041, 052 |
-| **DSL & query layer** | 002, 006, 007, 020, 025, 038, 044, 049, 051 |
+| **DSL & query layer** | 002, 006, 007, 020, 025, 038, 044, 049, 051, 055 |
 | **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, 055 |
 | **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, 055 |
 | **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 |
-| **Snapshots & publishing** | 009, 020, 028, 033, 034, 051 |
+| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025, 040, 041, 045, 047, 050, 051, 054, 055 |
+| **Snapshots & publishing** | 009, 020, 028, 033, 034, 051, 055 |
 | **AI agents & guidance** | 010, 015, 021, 053 |
 | **The doctor & checks** | 021, 025, 032, 033, 035 |
 | **Releases & upgrades** | 015, 021, 032, 034, 035, 036, 037, 042, 052 |
@@ -101,7 +101,9 @@ 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 |
+| 055 | A Category Pane Can Be Sorted by Its Measure Either Way, or by Its Label | 2026-10-13 | Accepted |
 
 ## Next number
 
-Next ADR: 054
+Next ADR: 056

data/docs/roadmap.md

@@ -133,7 +133,9 @@ 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, a bar can show its value, and a category pane can
+be put in the order that reads. 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 +149,15 @@ 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). 0.15.0 followed that: a category
+pane can be sorted by its measure either way or by its label, so a bottom five
+and a chart in date order can be drawn (ADR 055). All three came from a real
+install, and the last two add a pane option and a URL parameter, so the soak
+starts again from 0.15.0. What 1.0 waits
+on now is a week of real installs of 0.15.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 +180,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/definition.rb

@@ -4,6 +4,11 @@ module Janela
     # applied when a host asks for none, and as the bound on one filter's values.
     MAXIMUM = 1000
 
+    # How a category pane is ordered (ADR 055): by its measure, largest or
+    # smallest first, or by the dimension's own value, ascending or descending.
+    # The first is what a pane did before there was a choice.
+    SORTS = %w[desc asc label label_desc].freeze
+
     attr_reader :model, :measures, :dimensions
 
     # The class whose janela block this is, which a subclass shares with the
@@ -44,8 +49,9 @@ module Janela
     # keys: narrows a categorical grouping to the labels a companion column is
     # being fetched for (ADR 051), so it is the primary's rows and not the
     # companion's own top 1000.
-    def query(measure_name, by: nil, where: {}, on: nil, granularity: nil, limit: nil, keys: nil)
+    def query(measure_name, by: nil, where: {}, on: nil, granularity: nil, limit: nil, keys: nil, sort: nil)
       measure = measure!(measure_name)
+      sort = sort!(sort)
       relation = filter(on || model.all, where)
       return measure.apply(relation) if by.nil?
 
@@ -57,7 +63,7 @@ module Janela
         bucketed(measure, dimension, relation, granularity).transform_keys { |bucket| dimension.label(bucket, granularity) }
       else
         relation = within_keys(relation, dimension, keys) if keys
-        grouped = relation.group(dimension.attribute).order(Arel.sql("#{measure.order_by} DESC"))
+        grouped = relation.group(dimension.attribute).order(Arel.sql(ordering(measure, dimension, sort)))
         grouped = grouped.limit(limit ? limit!(limit) : MAXIMUM)
         measure.apply(grouped).transform_keys { |value| value.nil? ? Dimension::NONE : value }
       end
@@ -124,6 +130,15 @@ module Janela
       nil # no database to ask yet; a query will raise on its own if it cannot run
     end
 
+    # nil is the default, so a caller that never heard of a sort is unchanged.
+    def sort!(value)
+      return "desc" if value.blank?
+
+      value = value.to_s
+      raise BadRequest, "sort must be one of #{SORTS.join(', ')}, got #{value.inspect}" unless SORTS.include?(value)
+      value
+    end
+
     def limit!(value)
       limit = Integer(value, exception: false)
       raise BadRequest, "limit must be a whole number from 1 to #{MAXIMUM}, got #{value.inspect}" unless limit&.between?(1, MAXIMUM)
@@ -147,6 +162,24 @@ module Janela
     end
 
     private
+      # The label comes second in a measure order so that groups tied on the
+      # measure come out the same way every time, and a limit between them
+      # always shows the same one. IS NULL puts the (none) group last wherever
+      # the database would put it: SQLite sorts NULL first in an ascending
+      # order and PostgreSQL last, and a label order would otherwise differ by
+      # host (ADR 055). The database sorts the column as its own type, so a
+      # number is in numeric order and a date in date order.
+      def ordering(measure, dimension, sort)
+        label = dimension.quoted_column
+        by_label = "#{label} IS NULL, #{label}"
+        case sort
+        when "asc" then "#{measure.order_by} ASC, #{by_label} ASC"
+        when "label" then "#{by_label} ASC"
+        when "label_desc" then "#{by_label} DESC"
+        else "#{measure.order_by} DESC, #{by_label} ASC"
+        end
+      end
+
       def within_keys(relation, dimension, keys)
         labels = keys - [ Dimension::NONE ]
         condition = dimension.attribute.in(labels)

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 sort],
         "Janela::Snapshot" => %w[owner_type owner_id]
       }.freeze
 

data/lib/janela/tools.rb

@@ -17,8 +17,8 @@ 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
+    PANE_ATTRIBUTES = %w[kind model measure dimension renderer granularity limit sort span title height prominence
+                         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
@@ -64,7 +64,8 @@ module Janela
         { models: Janela.definitions.map { |definition| model_hash(definition) },
           renderers: Janela.renderers.map(&:to_s),
           granularities: Janela.granularities.map(&:to_s),
-          limits: Pane::OFFERED_LIMITS }
+          limits: Pane::OFFERED_LIMITS,
+          sorts: Janela.sorts }
       end
 
       def list_frames
@@ -205,10 +206,12 @@ module Janela
             renderer: { type: "string", enum: Janela.renderers.map(&:to_s) },
             granularity: { type: "string", enum: Janela.granularities.map(&:to_s) },
             limit: { type: "integer", minimum: Pane::LIMITS.min, maximum: Pane::LIMITS.max },
+            sort: { type: "string", enum: Janela.sorts },
             span: { type: "integer", minimum: Pane::SPANS.min, maximum: Pane::SPANS.max },
             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.15.0"
 end