janela 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69f4c0147424e4d9350bcee373b832e922f54b1686acce5c80fa776432a288c6
-  data.tar.gz: ec2f91ec4c87dcfeb49154b54e0cda105f293e8b56580fb774750011fb9277df
+  metadata.gz: 9b6b7c6d32876fc33b9c40e07278094bc901c548ac355d30f2d4cd2048f41cde
+  data.tar.gz: c60ff46e6023319430c63a53ee5bae675fbf98541e6639982b62c5d79cd0b76b
 SHA512:
-  metadata.gz: 38e32300abc75aa9b738d63b2d7f638dff0d9f153e19aa32f1cb5cbd422702c4e236bc93b87e7c4474836bbd3bfddfad4f83fbaa95d523efee8e6b82b6246b12
-  data.tar.gz: fe82fff29b230ecab68eb8c14e162d214ee9c1666ead178145c73ffe776e635b8acd59fa8cc1df1011a9f091b2d50e9d9fe299e67142657ed59e69fa1d70d120
+  metadata.gz: a48f8cd95951b00dfd10bf9d3a4ee9476bf486cd3660618a83f561259e61c61e22289cbce2647fe75b8463d14d25aa710354d760ad549bbf51e25d5ae67cdecb
+  data.tar.gz: 92f1c1a0b289f523a81b4a00d6c7c63b50d480e199d0ac42ffb0db34dc98064d4b9b44b01e0dc65d5f485fcbd4e6eb6a9d897401ad197522c66ad7541cbf85a0

data/CHANGELOG.md

@@ -5,6 +5,16 @@ 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
@@ -289,6 +299,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.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

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.14"
+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,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).
 
+**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).
@@ -563,7 +565,7 @@ Deliberately out of scope: natural-language query, a separate data warehouse, a
 
 ## Status
 
-**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).
+**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,31 @@ 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.

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, :value_labels, :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,6 +8,7 @@ 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],

data/app/controllers/janela/snapshot_queries_controller.rb

@@ -13,6 +13,7 @@ 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],

data/app/helpers/janela/frames_helper.rb

@@ -34,13 +34,13 @@ module Janela
     # 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, value_labels: nil, companions: nil, id: nil)
-      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit, height: height, prominence: prominence,
+    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 }
@@ -48,12 +48,12 @@ 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, value_labels: nil, companions: nil)
-      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit, height: height,
+    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
 

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, value_labels: value_labels, 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, :value_labels, :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, value_labels: 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,6 +58,10 @@ 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)
@@ -206,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
@@ -226,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)
@@ -238,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

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

data/config/locales/en.yml

@@ -19,6 +19,7 @@ en:
         renderer: Renderer
         granularity: Granularity
         limit: Rows
+        sort: Order
         span: Width
         height: Height
         prominence: Prominence
@@ -77,6 +78,12 @@ en:
       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/20261013000001_add_sort_to_janela_panes.rb

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

data/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, 054 |
+| **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, 054 |
+| **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, 054 |
 | **Time dimensions** | 006, 025, 045 |
-| **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 |
+| **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 |
@@ -102,7 +102,8 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 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: 055
+Next ADR: 056

data/docs/roadmap.md

@@ -134,7 +134,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, 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
+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.
 
@@ -151,9 +152,12 @@ height, a ratio measure, single value prominence, companion columns, Sprockets
 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)),
+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

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 value_labels],
+        "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,7 +17,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
+    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
@@ -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,6 +206,7 @@ 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 },

data/lib/janela/version.rb

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

data/lib/janela.rb

@@ -170,6 +170,10 @@ module Janela
   # 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.sorts
+    Definition::SORTS
+  end
+
   def self.heights
     Pane::HEIGHTS.to_a
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: janela
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Jay Killeen
@@ -147,6 +147,7 @@ files:
 - 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
+- db/migrate/20261013000001_add_sort_to_janela_panes.rb
 - docs/agents.md
 - docs/composing.md
 - docs/decisions/001-built-to-be-forked.md
@@ -203,6 +204,7 @@ files:
 - 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/055-a-category-pane-can-be-sorted-by-its-measure-either-way-or-by-its-label.md
 - docs/decisions/INDEX.md
 - docs/multi-tenancy.md
 - docs/naming.md
@@ -229,17 +231,15 @@ metadata:
   bug_tracker_uri: https://github.com/retail-tasker/janela/issues
   rubygems_mfa_required: 'true'
 post_install_message: |
-  Janela 0.14.0: one migration, if you use stored frames.
+  Janela 0.15.0: one migration, if you use stored frames.
 
-  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
+  A category pane can now be sorted by its measure either way, or by its
+  label (ADR 055), which adds a nullable sort 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.
 
-  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.
+  Also: groups that tie on the measure now come out in label order, so
+  a pane with a limit shows the same rows every time.
 
   Steps: UPGRADING.md in this gem, or
   https://github.com/retail-tasker/janela/blob/main/UPGRADING.md