janela 0.9.0 → 0.11.0

data/docs/roadmap.md

@@ -8,7 +8,7 @@ Topics: roadmap, releases, scope, planning
 
 <svg viewBox="0 0 680 360" width="100%" role="img" aria-labelledby="vista-title vista-desc" class="vista-art" style="display: block; margin: 1.75rem 0; border-radius: 10px;">
   <title id="vista-title">Vista</title>
-  <desc id="vista-desc">Sea and sky with a horizon across them. Eight lights burn on the near water, one for each issue in 1.0, and three sit far off at the horizon for the work still in sight past it. A low sun rises and sets on the horizon as the pointer moves up and down, and never climbs higher: the sky above is empty, because what is not coming is not in view.</desc>
+  <desc id="vista-desc">Sea and sky with a horizon across them. Six lights burn on the near water, one for each issue in 1.0, and three sit far off at the horizon for the work still in sight past it. A low sun rises and sets on the horizon as the pointer moves up and down, and never climbs higher: the sky above is empty, because what is not coming is not in view.</desc>
 
   <style>
     .vista-art .v-far { transform: translate3d(calc(var(--vitral-shift-x, 0) * 13px), calc(var(--vitral-shift-y, 0) * 7px), 0); transition: transform .45s cubic-bezier(.2,.7,.3,1); }
@@ -99,10 +99,6 @@ Topics: roadmap, releases, scope, planning
       <path d="M427 234 h10" stroke-width="1" stroke-opacity="0.2"/>
     </g>
     <g class="v-near">
-      <circle cx="74" cy="330" r="22" fill="url(#vLamp)" opacity="0.4"/>
-      <circle cx="74" cy="330" r="4.3" fill="#FFF6E2" opacity="0.88"/>
-      <circle cx="154" cy="302" r="20" fill="url(#vLamp)" opacity="0.4"/>
-      <circle cx="154" cy="302" r="4.0" fill="#FFF6E2" opacity="0.88"/>
       <circle cx="238" cy="340" r="21" fill="url(#vLamp)" opacity="0.4"/>
       <circle cx="238" cy="340" r="4.2" fill="#FFF6E2" opacity="0.88"/>
       <circle cx="312" cy="283" r="18" fill="url(#vLamp)" opacity="0.4"/>
@@ -143,30 +139,29 @@ parameters change only on a major version after 1.0. Until then they can
 change in any release, and every change of that kind carries an entry in
 `UPGRADING.md`.
 
-**A pane can be read.** Janela draws tables, bars and lines. A
-part-to-whole split currently has to be drawn as bars, a table row cannot
-carry context beside its label, and a chart takes Chart.js's default
-proportions whether or not they suit the page. Those are not extra
-features. They are the 5% not finished, and most of them were found by
-people installing the gem rather than reading it.
+**A pane can be read.** Janela draws tables, bars, lines, doughnuts and
+pies. A table row still cannot carry context beside its label, a single
+number has no way to say how prominent it is, and a chart takes whatever
+height its width gives it whether or not that suits the page. Those are
+not extra features. They are the 5% not finished, and most of them were
+found by people installing the gem rather than reading it.
 
 **The doctor can be trusted.** `rails janela:doctor` checks an
 installation for the mistakes that produce a dashboard showing numbers
-nobody should see. Two of its checks have no test that makes them fire.
-A check nobody can prove is working is a check nobody should rely on.
+nobody should see. Every one of its checks now has a test that makes it
+fire and one that leaves it quiet, because a check nobody can prove is
+working is a check nobody should rely on.
 
 ## In 1.0
 
-The eight lights burning in the near ground.
+The six lights burning in the near ground.
 
 | Issue | What |
 | --- | --- |
 | [#24](https://github.com/retail-tasker/janela/issues/24) | A chart's height and aspect ratio are the host's to set |
 | [#27](https://github.com/retail-tasker/janela/issues/27) | A ratio measure, so refusing `average:` over a boolean offers somewhere to go |
-| [#30](https://github.com/retail-tasker/janela/issues/30) | Doughnut and pie, and a categorical palette that makes them readable |
 | [#31](https://github.com/retail-tasker/janela/issues/31) | A pane says how prominent it is |
 | [#34](https://github.com/retail-tasker/janela/issues/34) | A table pane carries an attribute column beside its label |
-| [#53](https://github.com/retail-tasker/janela/issues/53) | The last two doctor checks get tests |
 | [#14](https://github.com/retail-tasker/janela/issues/14) | A Sprockets host serves the engine's JavaScript, or is told it cannot |
 | [#6](https://github.com/retail-tasker/janela/issues/6) | How contributions are accepted, who cuts a release, where to report a vulnerability |
 
@@ -178,10 +173,10 @@ Progress is tracked on the
 The three lights far off at the horizon. Wanted, not blocking a stable
 release, and being on this list is not a refusal.
 
-- **Drill-down on time panes** ([#18](https://github.com/retail-tasker/janela/issues/18)).
-  Clicking a month could filter every other pane to it, or narrow that
-  pane to weeks within it. Both are reasonable, they need different
-  things from the URL, and ADR 006 left the question open on purpose. It
+- **Drilling down on time panes** ([#65](https://github.com/retail-tasker/janela/issues/65)).
+  Clicking a month now filters every other pane to it (#18). Narrowing
+  that pane itself to the weeks within it is a different gesture, with
+  its own questions about getting back out and about the URL, and it
   needs a decision record before any code.
 - **A command palette for the demo** ([#41](https://github.com/retail-tasker/janela/issues/41)).
   The demo site, not the gem.

data/docs/theming.md

@@ -25,13 +25,15 @@ the theme.
 
 ### Custom properties
 
-Three, and setting them moves everything that depends on them.
+Setting any of these moves everything that depends on it.
 
 | Property | Default | What it does |
 | --- | --- | --- |
 | `--janela-space` | `0.25rem` | The base unit of the whole spacing scale. Every gap and padding is a multiple of it. |
 | `--janela-line` | `rgba(128, 128, 128, 0.3)` | Rules between rows, borders on cards and fields. |
-| `--janela-accent` | `rgb(54, 162, 235)` | A selected value, a hovered card. |
+| `--janela-accent` | `rgb(54, 162, 235)` | A selected value, a hovered card, a line chart (#62), and the first colour of the palette below. |
+| `--janela-series-1` to `--janela-series-8` | the accent, then `#eb6834`, `#1baf7a`, `#eda100`, `#e87ba4`, `#008300`, `#4a3aa7`, `#e34948` | The colour a bar, a doughnut slice or a pie slice is drawn in, by its position in the pane, first to eighth (ADR 046). |
+| `--janela-series-other` | `#8c8c8c` | Every position after the eighth. The palette is never cycled, so the ninth value is not drawn like the first. |
 
 ```css
 :root {
@@ -70,11 +72,21 @@ the names a theme spends most of its time on.
 | `janela-value-number` | `<strong>` | the number itself |
 | `janela-chart` | `<canvas>` | a bar or line pane, inside its `<figure>` |
 | `janela-chart-title` | `<figcaption>` | its caption (ADR 042) |
+| `janela-ring` | `<figure>` | a doughnut or pie pane (ADR 046) |
+| `janela-ring-svg` | `<svg>` | its picture; `data-hole` is `true` for a doughnut |
+| `janela-ring-slice` | `<path>` | one slice; `janela-dim` is added to those not selected while something is |
+| `janela-legend` | `<table>` | its legend, one row of swatch, button and value per slice |
+| `janela-swatch` | `<span>` | the colour beside a legend label |
 | `janela-empty` | `<p>` | a pane whose query returned nothing |
 | `janela-error` | `<p>` | a pane that could not be read |
 | `janela-content` | `<div>` | a stored pane holding words or a host partial rather than a query (ADR 039) |
 | `janela-content-heading` | `<h2>` | a text pane's heading |
 
+The dark values that passed the palette check on a dark surface are
+`#3987e5`, `#d95926`, `#199e70`, `#c98500`, `#d55181`, `#008300`,
+`#9085e9` and `#e66767`. `janela.css` ships no dark scheme (ADR 023), so
+a dark theme sets the eight properties to them.
+
 A table pane renders a `<caption>` and a chart pane a `<figcaption>`,
 each its own accessible name; the chart's canvas points to its
 figcaption with `aria-labelledby` rather than repeating the string in

data/lib/janela/definition.rb

@@ -51,9 +51,7 @@ module Janela
 
       if dimension.time?
         granularity = Dimension.granularity!(granularity || dimension.granularity)
-        options = granularity == "week" ? { week_start: Date.beginning_of_week } : {}
-        buckets = relation.group_by_period(granularity, dimension.qualified_column, **options)
-        measure.apply(buckets).transform_keys { |bucket| dimension.label(bucket, granularity) }
+        bucketed(measure, dimension, relation, granularity).transform_keys { |bucket| dimension.label(bucket, granularity) }
       else
         grouped = relation.group(dimension.attribute).order(Arel.sql("#{measure.sql_alias} DESC"))
         grouped = grouped.limit(limit ? limit!(limit) : MAXIMUM)
@@ -61,6 +59,20 @@ module Janela
       end
     end
 
+    # The buckets of a time dimension keyed by the bucket itself, where query
+    # keys them by label. A label is lossy ("Sep 2026", "Q3 2026"), and a click
+    # on a bucket has to write the range it covers, which only the bucket can
+    # say (ADR 045).
+    def series(measure_name, by:, where: {}, on: nil, granularity: nil)
+      measure = measure!(measure_name)
+      dimension = dimension!(by)
+      raise Error, "#{by.inspect} is not a time dimension" unless dimension.time?
+
+      relation = filter(on || model.all, where)
+      relation = relation.left_joins(dimension.through) if dimension.through
+      bucketed(measure, dimension, relation, Dimension.granularity!(granularity || dimension.granularity))
+    end
+
     def dimension!(name)
       dimensions.fetch(name) { raise NotFound, "#{model} has no janela dimension #{name.inspect}" }
     end
@@ -106,6 +118,11 @@ module Janela
     end
 
     private
+      def bucketed(measure, dimension, relation, granularity)
+        options = granularity == "week" ? { week_start: Date.beginning_of_week } : {}
+        measure.apply(relation.group_by_period(granularity, dimension.qualified_column, **options))
+      end
+
       def filter(relation, params)
         return relation if params.empty?
 

data/lib/janela/dimension.rb

@@ -4,12 +4,20 @@ module Janela
 
     # What a click produces (ADR 024), plus not_null: excluding the null
     # group is documented, tested behaviour ADR 025 did not measure and would
-    # otherwise silently break.
-    CATEGORICAL_PREDICATES = %w[eq in null not_null].freeze
+    # otherwise silently break. not_eq and not_in (ADR 044) say what a
+    # dimension excludes, which an _in list naming every other value cannot
+    # do without rotting the day a new value appears.
+    CATEGORICAL_PREDICATES = %w[eq in not_eq not_in null not_null].freeze
 
     # A time dimension additionally narrows a range (ADR 006).
     TIME_PREDICATES = (CATEGORICAL_PREDICATES + %w[gteq gt lteq lt]).freeze
 
+    # How far a bucket reaches, so a click on it can name the range it covers
+    # (ADR 045). A quarter is three months, which is why it is not a step of
+    # its own.
+    STEPS = { "hour" => 1.hour, "day" => 1.day, "week" => 1.week, "month" => 1.month,
+              "quarter" => 3.months, "year" => 1.year }.freeze
+
     # A group of rows whose dimension is null. Labelled rather than blank, and
     # filtered with Ransack's null predicate rather than an empty string.
     NONE = "(none)".freeze
@@ -54,6 +62,27 @@ module Janela
       time? ? TIME_PREDICATES : CATEGORICAL_PREDICATES
     end
 
+    # The bucket's start and the next bucket's start, in the zone the bucket
+    # was made in. The end is exclusive, so one bucket's end is the next
+    # one's start and no row falls in both (ADR 045).
+    def span(bucket, granularity = self.granularity)
+      from = bucket.in_time_zone
+      [ from, from + STEPS.fetch(granularity.to_s) ]
+    end
+
+    # The same range as the two values a filter carries: dates for a date
+    # column, and for a timestamp the zone's ISO 8601 with its offset, which
+    # Ransack reads back in the same zone (measured against Brisbane).
+    def bounds(bucket, granularity = self.granularity)
+      span(bucket, granularity).map { |moment| date_column? ? moment.to_date.iso8601 : moment.iso8601 }
+    end
+
+    def date_column?
+      klass.type_for_attribute(column.to_s).type == :date
+    rescue ActiveRecord::ActiveRecordError
+      false
+    end
+
     def attribute
       klass.arel_table[column]
     end

data/lib/janela/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: janela
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Jay Killeen
@@ -129,6 +129,7 @@ files:
 - app/views/janela/panes/new.html.erb
 - app/views/janela/panes/show.html.erb
 - app/views/janela/queries/_query.html.erb
+- app/views/janela/queries/_ring.html.erb
 - app/views/janela/queries/show.html.erb
 - app/views/janela/shared/_errors.html.erb
 - app/views/layouts/janela/application.html.erb
@@ -141,6 +142,7 @@ files:
 - db/migrate/20260921000001_add_owner_to_janela_snapshots.rb
 - db/migrate/20260924000001_add_content_to_janela_panes.rb
 - db/migrate/20260924000002_add_key_to_janela_frames.rb
+- db/migrate/20260928000001_add_default_filter_to_janela_frames.rb
 - docs/composing.md
 - docs/decisions/001-built-to-be-forked.md
 - docs/decisions/002-measures-and-dimensions-over-ransack.md
@@ -184,6 +186,10 @@ files:
 - docs/decisions/040-a-host-can-fix-a-frames-filter.md
 - docs/decisions/041-a-host-finds-its-frame-by-owner-and-key.md
 - docs/decisions/042-a-charts-title-is-a-figcaption.md
+- docs/decisions/043-a-frames-default-filter-names-the-model-it-narrows.md
+- docs/decisions/044-a-categorical-dimension-can-say-what-it-excludes.md
+- docs/decisions/045-clicking-a-time-bucket-filters-the-frame-to-its-range.md
+- docs/decisions/046-a-ring-is-server-drawn-svg-and-a-palette-is-eight-fixed-colours.md
 - docs/decisions/INDEX.md
 - docs/multi-tenancy.md
 - docs/naming.md
@@ -209,22 +215,16 @@ metadata:
   bug_tracker_uri: https://github.com/retail-tasker/janela/issues
   rubygems_mfa_required: 'true'
 post_install_message: |
-  Janela 0.9.0: a migration if you use stored frames, and a markup
-  check if you wrote CSS or JavaScript against a chart pane.
+  Janela 0.11.0: no migration. Two things to look for, and if
+  neither describes you there is nothing to do.
 
-  1. If you use stored frames, take two migrations together:
-     bin/rails janela:install:migrations && bin/rails db:migrate
-     A pane can now hold words or a host partial instead of a query
-     (ADR 039), and Janela::Frame.for(owner, key) finds a frame kept
-     for one of your pages without a column of your own (ADR 041).
-     Existing frames and panes are unaffected either way.
+  Bar charts are drawn in a palette now, not all one colour (ADR 046).
+  If you want the old look, UPGRADING.md has the lines that restore it.
 
-  2. A chart pane's title is now a visible <figcaption> inside a
-     <figure> wrapping the canvas, not only the canvas's aria-label
-     (ADR 042). janela-pane moved from the <canvas> to the <figure>;
-     janela-chart stayed on the canvas. If you selected
-     .janela-pane.janela-chart as one element, or read a chart's
-     title from aria-label, both need updating.
+  A range a reader sends in q[...], such as q[placed_on_gteq], no
+  longer narrows the time pane it names, since clicking a time bucket
+  now writes exactly that (ADR 045). A range you fix yourself with
+  where: or default_where still does.
 
   Steps: UPGRADING.md in this gem, or
   https://github.com/retail-tasker/janela/blob/main/UPGRADING.md