janela 0.16.0 → 0.16.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83aee3a06740005fd9bf9e81ddc12c6de350ea4b8f6fce34899a94869e0f2615
-  data.tar.gz: cd6d59364454c17e80302de50377a5ca2ca3f2db2ceb2bd58be8ca6a29d6b878
+  metadata.gz: 720d124c207d9183b7450a7be6597adc0593b3addb26cc548cd2e445b828f250
+  data.tar.gz: db09ec1528a8b2b75c2369ae1e8d537b515e314416f01cd0e2463cdafab9d64b
 SHA512:
-  metadata.gz: 670dcac643875f4723159a3f8ecc4429d9feb115dcf58c7336fc823f8290eff4bb3c25316893dc382958753d43e689c4572416d9371b7fa36e0e23447640052c
-  data.tar.gz: 6c423db2685c60bb12a6f3878ea956fe926dfde507a9a373d71be3f42092322a22a6958ecf6cc54aee68e6535fd8690e9d4320a0a55da2aa6eed4e40074b0734
+  metadata.gz: 9497ce5bb01d59a4e43006bca8c3243ce162c0b5ea760011c58921791acf43df2932785c89d5bc99a7eb62c113b4a53e5fce3a7c983395ac410571fd439e26db
+  data.tar.gz: 9f7bcad7c5cbbed3523960fc0f0db1c045fabd8b02e41e1f2bed357a9dad000a6dfaeae9eee02c716acd7e5b65018dff14bfba257e19e5450ee3d302e1b20ac6

data/CHANGELOG.md

@@ -5,6 +5,12 @@ 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.16.1] - 2026-11-02
+
+### Added
+
+- **A Charts guide, `docs/charts.md`.** The pane options were documented only in the README, so the demo's Documentation page had nowhere to say how to choose a renderer or how to build a chart with a running total and more series on two axes. The guide covers the renderers, the options that shape one chart, `cumulative:` and `series:` with the combined chart as a worked example, and the colours. It ships in the gem and is listed under Documentation on the demo (ADR 062).
+
 ## [0.16.0] - 2026-10-29
 
 ### Added
@@ -320,6 +326,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.16.1]: https://github.com/retail-tasker/janela/releases/tag/v0.16.1
 [0.16.0]: https://github.com/retail-tasker/janela/releases/tag/v0.16.0
 [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

data/README.md

@@ -581,7 +581,7 @@ Deliberately out of scope: natural-language query, a separate data warehouse, a
 
 ## Status
 
-**v0.16.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).
+**v0.16.1 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/docs/charts.md

@@ -0,0 +1,148 @@
+---
+Topics: charts, renderers, panes, time, series, cumulative
+---
+
+# Charts and Their Options
+
+A pane is a measure, sometimes over a dimension, drawn one way. This page
+is the reference for the drawing: which renderer suits which question, the
+options that change how it reads, and how to put more than one measure on
+a chart. Each option is written the same three ways, in `janela_pane`, as a
+column on a stored pane, and in the pane's URL, so a hand written page, an
+analyst's row and a link all say the same thing.
+
+The short version: pick the renderer from the shape of the question, pass
+the option you need, and let the others stay unset. Every option is off
+until a pane asks for it, and a pane that sets none is drawn as it always
+was.
+
+## Choosing a renderer
+
+`as:` is `:table` unless the pane says otherwise.
+
+| Renderer | The question it answers | Needs |
+| --- | --- | --- |
+| `:table` | what are the exact numbers | anything |
+| `:bar` | how do the values of a category compare | a category dimension |
+| `:line` | how does a measure move over time | a time dimension |
+| `:doughnut`, `:pie` | how is a whole split between a handful of values | a category dimension, no negatives |
+| none, with no `by:` | what is the single figure | a measure alone |
+
+```erb
+<%= janela_pane Order, :revenue %>
+<%= janela_pane Order, :revenue, by: :status, as: :bar %>
+<%= janela_pane Order, :revenue, by: :placed_on, as: :line, granularity: :week %>
+<%= janela_pane Order, :orders, by: :region, as: :doughnut, limit: 8 %>
+```
+
+A table is also what any chart becomes where there is no chart runtime, so
+the numbers are always readable. Bars and lines are drawn in the browser
+with Chart.js. 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. A ring cannot show a negative
+value, so a pane with one is drawn as a table and says so.
+
+Clicking a bar, a slice or a table value narrows the other panes on the
+frame. A click on a line's bucket narrows them to that range.
+
+## Shaping one chart
+
+These options apply to a single measure over a single dimension.
+
+| Option | Does | Applies to |
+| --- | --- | --- |
+| `limit:` | keeps the top rows or bars | table, bar, ring |
+| `sort:` | `:asc`, `:label`, `:label_desc`; the default is largest first | a category pane |
+| `granularity:` | `:hour` to `:year`; the bucket size | a time pane |
+| `height:` | `1` to `5`, from about 96px to about 448px | bar, line |
+| `prominence:` | `1` to `3`, the size of a single figure | a single value |
+| `value_labels:` | writes the value on the chart | bar, line |
+| `companions:` | up to three more columns | table |
+
+A bar or line chart is drawn at twice its width, up to 20rem, unless it
+is given a height. Heights and prominences are steps rather than lengths,
+so a stored pane takes them from its form. `value_labels` on a bar is all
+or none: if any label is wider than its bar's share of the chart, none is
+drawn. The README has the detail of each; ADRs 046, 047, 050, 051, 054
+and 055 have the reasons.
+
+## A running total
+
+A time pane reads per period by default: orders placed each month.
+`cumulative: true` reads the same buckets as a total to date.
+
+```erb
+<%= janela_pane Order, :orders, by: :placed_on, as: :line, granularity: :month, cumulative: true %>
+```
+
+The total is summed after the read, so the buckets, the filters and a
+click on a bucket are exactly what they were. It is refused, with its
+reason, on a category pane, on a single value, and on a measure that does
+not add up: an average, a minimum, a maximum or a ratio. A running sum of
+averages would be a number, but not the average to date. Per period and to
+date are two different answers that can share a page, so a pane that sets
+`cumulative` has its own frame id.
+
+## More than one series
+
+A time pane can carry up to three more measures over the same buckets.
+Each is a hash led by its measure.
+
+```erb
+<%= janela_pane Order, :orders, by: :placed_on, as: :line, granularity: :month, cumulative: true,
+      series: [
+        { measure: :orders, by: :shipped_on, cumulative: true, title: "Orders shipped to date" },
+        { measure: :orders, as: :bar, axis: :right, title: "Orders per month" }
+      ] %>
+```
+
+That is orders placed and orders shipped, both to date, as two lines on
+the left axis, with orders per month as bars on a right one.
+
+| Key | Means | Left out |
+| --- | --- | --- |
+| `measure` | a measure the model declares | required |
+| `by` | a time dimension of the same model | the pane's own |
+| `cumulative` | a running total | per period |
+| `as` | `line` or `bar` | the pane's renderer if it is one of those, else `line` |
+| `axis` | `left` or `right` | `left` |
+| `title` | the legend's name for it | one Janela writes, such as `Orders shipped to date` |
+
+**What the chart does.** Every series' buckets are joined into one axis,
+from the first bucket any series has to the last. A series with no row in
+a bucket reads zero there, so a total to date is flat across a month
+nothing shipped. For a measure that has no value in an empty bucket (an
+average, a minimum, a maximum or a ratio) the bucket is a gap instead. A
+chart with series shows a legend and colours by series rather than by
+category: `--janela-series-1` for the pane's own, the rest in order. Bars
+are drawn behind lines. A right axis exists only when a series asks for
+one, and then both axes are titled with the series on them. A right axis
+that holds only bars is scaled so the tallest reaches about a third of the
+plot, which keeps them from covering the lines.
+
+**What it does not do.** Series belong to a time pane. A category pane,
+a ring and a single value refuse them or ignore them, and a stored
+snapshot holds none. A series cannot have its own granularity or filter,
+or come from another model, and nothing stacks. With `value_labels`, each
+line writes its latest value at its end and a bar writes nothing.
+
+**Where to set it.** The same keys are rows on the pane form, `cumulative`
+and `series` in `Janela::Tools`, and `?cumulative=1&series[][measure]=orders&series[][by]=shipped_on`
+in the pane URL. Put `measure` first in a series in a URL, because that is
+what starts a new one. A table draws each series as a column after the
+measure's, which is also what a page with no chart runtime shows.
+
+## Colours
+
+Bars, slices and series are drawn from eight colours by position, and every
+position after the eighth in one neutral. They are `--janela-series-1` to
+`--janela-series-8` and `--janela-series-other`, and [Theming
+Janela](theming) says how to change them.
+
+## What this page is not
+
+It is not the list of what can be asked of a model; that is the model's
+own `janela` block, and `Janela::Definition` answers it. It is not the
+layout around a pane either, which is [Composing a Page Around
+Panes](composing). The decisions behind the options are the ADRs: 062 for
+running totals and series, and the README for the rest.

data/lib/janela/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: janela
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.16.1
 platform: ruby
 authors:
 - Jay Killeen
@@ -151,6 +151,7 @@ files:
 - db/migrate/20261029000001_add_series_to_janela_panes.rb
 - db/migrate/20261029000003_add_ignore_unknown_filters_to_janela_panes.rb
 - docs/agents.md
+- docs/charts.md
 - docs/composing.md
 - docs/decisions/001-built-to-be-forked.md
 - docs/decisions/002-measures-and-dimensions-over-ransack.md
@@ -242,23 +243,6 @@ metadata:
   changelog_uri: https://github.com/retail-tasker/janela/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/retail-tasker/janela/issues
   rubygems_mfa_required: 'true'
-post_install_message: |
-  Janela 0.16.0: one migration, if you use stored frames.
-
-  A time pane can now be a running total and carry more series on two
-  axes (ADR 062), and a pane can ignore a filter its model cannot apply
-  (ADR 063). That adds nullable cumulative, series and
-  ignore_unknown_filters columns 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 line chart with value_labels now writes its latest value at
-  its end.
-
-  Steps: UPGRADING.md in this gem, or
-  https://github.com/retail-tasker/janela/blob/main/UPGRADING.md
-
-  Then run: bin/rails janela:doctor
 rdoc_options: []
 require_paths:
 - lib