janela 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b37ede25ec758841e03748b59d6ebce1044ffeacc50fa38eea78a95a57f731be
-  data.tar.gz: beae0fa4879019dfd161a5196bff0420b2053bccd6d7243a272bd3b173b77ce7
+  metadata.gz: 86e2bcbf47fdcf475b8e34b2b1897d308a6c9f478e7b3f0903979cd3fa6bb8e2
+  data.tar.gz: 9116c50f2f6e92a69489827acf9e9d580954c21bbe068887c3605b96d0531019
 SHA512:
-  metadata.gz: fb70200d571c6ba005f868336d05e4fbe40d7acc720ecd73895c328b92429b2606fd806b9e8a42fe68ca8fb6f47423f57cb1af9fba3424d5c2d1561a299a56d6
-  data.tar.gz: 0d78429d0dfdde06f0b77bdec85704d1f7d1a13e29046926937d9fb99346097d86f4420c74cea5035b48e22950813b11a53d8b4e5064e122eb7b128788803844
+  metadata.gz: a132498d5553317cd888139ba00559b5c7844c3878bdfe4c0c595783e14e3e4a082ec6fbe0a844d9f07a985a586daf4a4104164ff9dd452ed8ddf4390bdfe630
+  data.tar.gz: 5f35f6d28fe84c469e3502f97f8c0ec13b7e1c703f04c5aa21360ef7ad6e14b4cc9c8e8d174e5ac1af9207adcc221d3ed430e2851059ef41f08eb5833637712b

data/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-09-15
+
+Fixes found by dogfooding 0.2.0 in a second application. 0.2.0 is unusable in any host whose layout contains a route helper, which is most of them.
+
+### Fixed
+
+- Panes rendered in the host's application layout, so any route helper in it raised `NameError` inside the isolated engine and every pane 500'd. A pane in a Turbo Frame now carries no layout; opened directly it uses Janela's own minimal layout (ADR 011, #19).
+- `average:` or `sum:` over a boolean column returned `true` instead of a ratio, because ActiveRecord casts an aggregate back through the column's type. Declaring one now raises and points at `dimension` instead (#20).
+- A group whose dimension is null rendered as a blank label and filtered on an empty string. It is now labelled `(none)` and toggles Ransack's null predicate (#21).
+- The README claimed time buckets follow `Time.zone`; on SQLite they are UTC, which silently shifts daily buckets by the host's offset (#22).
+
+### Changed
+
+- A request for a model, measure, dimension or stored pane that does not exist is a 404; a renderer, granularity, limit or filter the request may not use is a 400. The response is a plain sentence, inside the requesting Turbo Frame when there is one, and the detail goes to the log instead of the client. `Janela::NotFound` and `Janela::BadRequest` subclass `Janela::Error`.
+
+## [0.2.0] - 2026-09-15
+
+Breaking. Renames and a new URL scheme while the only installation is the author's own (ADR 005).
+
+### Changed
+
+- `janela_visual` is now `janela_pane`; `Janela::Visual` is `Janela::Pane`; CSS hooks are `janela-pane`, `janela-chart`, `janela-value`, `janela-empty`.
+- A pane's URL is `/<mount>/<model route key>/<measure>[/<dimension>]?as=bar&q[...]` instead of `/<mount>/visual?model=...`. Frame ids follow the same shape.
+- The gem no longer ships its Rakefile, which referenced the unshipped dummy application.
+- The helper finds the engine's mount in the host's routes, so `mount Janela::Engine => "/reports", as: :reports` works. Documentation and the dummy application mount at `/dashboards`.
+
+### Added
+
+- A pane with no dimension renders the measure's single total.
+- Time dimensions: `dimension :placed_on, granularity: :month` buckets with Groupdate (`hour` to `year`), gap-filled, labelled in Ruby. Override per pane with `?granularity=week` or `janela_pane ..., granularity: :week`. Time panes re-scope with the dashboard but are not yet click sources (ADR 006).
+- `as: :line` renderer for time series.
+- Groupdate is a runtime dependency.
+- Published to rubygems.org through trusted publishing; a public demo of `test/dummy` deploys from `main`.
+- Snapshots: `Janela::Snapshot.take` freezes several panes' results at one instant under one set of filters; `janela_snapshot_pane` renders a stored pane, static by nature, at `/snapshots/:id/<model>/<measure>[/<dimension>]`. `Janela::SnapshotJob` for scheduling. First migration: `rails janela:install:migrations` (ADR 009).
+- Dashboard filters live in the page URL as `q[...]`; a reload keeps them and a filtered dashboard is shareable. The server renders the initial state from `params[:q]` (ADR 008).
+- Category panes are ordered by their measure, largest first, in SQL. `?limit=N` / `janela_pane ..., limit: N` keeps the top N (ADR 007).
+- `dimension :customer, through: :customer, column: :name` names a dimension for its meaning while reading another column.
+
+
 ## [0.1.0] - 2026-09-15
 
 First alpha, installed from GitHub for testing in a single host application.
@@ -23,4 +62,6 @@ 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.2.1]: https://github.com/retail-tasker/janela/releases/tag/v0.2.1
+[0.2.0]: https://github.com/retail-tasker/janela/releases/tag/v0.2.0
 [0.1.0]: https://github.com/retail-tasker/janela/releases/tag/v0.1.0

data/README.md

@@ -21,16 +21,16 @@ Janela's bet: the same dashboard definition should serve two audiences without b
 
 ## Installation
 
-Janela is pre-release and installed from GitHub. It has two halves, a gem and an npm package, installed the same way:
+Janela is an alpha on [rubygems.org](https://rubygems.org/gems/janela). It has two halves, a gem and an npm package:
 
 ```ruby
 # Gemfile
-gem "janela", github: "retail-tasker/janela"
+gem "janela", "~> 0.2"
 ```
 
 ```ruby
 # config/routes.rb
-mount Janela::Engine => "/janela"
+mount Janela::Engine => "/dashboards"   # or /reports, or wherever you like
 ```
 
 Then register the two Stimulus controllers. How depends on how your app ships JavaScript.
@@ -79,16 +79,22 @@ class Order < ApplicationRecord
 
     dimension :status
     dimension :region, through: :customer
+    dimension :placed_on, granularity: :month
   end
 end
 ```
 
+A dimension with a `granularity` is a time dimension. Groupdate buckets it (`hour`, `day`, `week`, `month`, `quarter`, `year`), fills empty buckets with zero, and uses your app's `Time.zone` and week start. **On SQLite, buckets are UTC**, because SQLite cannot convert time zones: with a non-UTC `Time.zone` a daily bucket is shifted by your offset, and an early-morning row lands in the previous day. Coarser granularities blunt the shift without removing it. If you need local-day buckets on SQLite, store a local date column and use it as a plain dimension.
+
 Then query them:
 
 ```ruby
 Order.janela.query(:revenue)                  # => 375
 Order.janela.query(:revenue, by: :status)     # => { "paid" => 300, "refunded" => 50, "pending" => 25 }
 Order.janela.query(:revenue, by: :region)     # => { "APAC" => 150, "EU" => 225 }
+Order.janela.query(:revenue, by: :placed_on)  # => { "Sep 2026" => 375 }
+Order.janela.query(:revenue, by: :placed_on, granularity: :day)
+                                              # => { "2026-09-01" => 100, "2026-09-02" => 50, ... }
 ```
 
 Filters are [Ransack](https://github.com/activerecord-hackery/ransack) params, so a slicer built with `search_form_for` can pass `params[:q]` straight through:
@@ -114,21 +120,68 @@ end
 
 ### Dashboards
 
-Compose visuals on any page. Each visual is a Turbo Frame; clicking a value in one re-scopes the others:
+Compose panes on any page. Each pane is a Turbo Frame; clicking a value in one re-scopes the others:
 
 ```erb
 <%= janela_dashboard do %>
   <button type="button" data-action="janela--dashboard#clear">Clear filters</button>
 
-  <%= janela_visual Order, :revenue, by: :status, as: :bar %>
-  <%= janela_visual Order, :revenue, by: :region %>
-  <%= janela_visual Order, :orders,  by: :region %>
+  <%= janela_pane Order, :revenue %>
+  <%= janela_pane Order, :revenue, by: :status, as: :bar %>
+  <%= janela_pane Order, :revenue, by: :region %>
+  <%= janela_pane Order, :orders,  by: :region %>
 <% end %>
 ```
 
-`as:` is `:table` by default or `:bar` for a Chart.js bar chart. 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. `as:` is `:table` by default, `:bar` for a Chart.js bar chart, 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.
+
+The dashboard's filters live in the page URL as the same `q[...]` parameters, so a reload keeps them and a filtered dashboard is a link you can send: `/reports/orders?q[status_eq]=paid` renders filtered before any JavaScript runs. A pane ignores filters on its own dimension, so clicking a value re-scopes the rest of the dashboard rather than collapsing the pane you clicked. Time panes re-scope with the others but are not click sources yet; drill-down is the next decision. The selected value is marked `aria-pressed="true"` on tables and drawn solid against faded siblings on charts, so it can be styled and read. A pane with no matching rows renders a `.janela-empty` paragraph. A group whose dimension is null is labelled `(none)` and filters with Ransack's null predicate rather than an empty string. Only models that declare a `janela` block can be requested over HTTP.
+
+### Pane URLs
+
+Every pane has its own URL under the mount, and a Turbo Frame in a dashboard loads exactly the same URL a person can open directly:
+
+```
+/dashboards/orders/revenue                      orders revenue
+/dashboards/orders/revenue/status               orders revenue by status
+/dashboards/orders/revenue/status?as=bar        ... as a bar chart
+/dashboards/orders/revenue/region?q[status_eq]=paid
+                                                orders revenue by region where status is paid
+/dashboards/orders/revenue/placed_on?granularity=week&as=line
+                                                orders revenue by placed_on, per week, as a line
+```
+
+The model is its route key (`orders`, `sales_orders`), then the measure, then optionally the dimension. Where an analyst would say *by*, the URL has a `/`; *where* is a `q` filter; *as a bar chart* is `?as=bar`; *top ten* is `?limit=10`; *as of* a snapshot is `/snapshots/:id/` in front. Category panes are always ordered by the measure, largest first; time panes are chronological. A pane opened on its own renders inside your application layout with its filters applied, so a filtered pane is a link you can send someone. ADR 005 has the reasoning.
+
+### Snapshots
+
+A snapshot freezes the results of several panes at one instant, under one set of filters, so an audience sees exactly what was signed off while the live dashboard stays editable. Results are stored, not HTML; a stored pane can still be drawn as a table or a chart.
+
+```bash
+bin/rails janela:install:migrations && bin/rails db:migrate
+```
+
+```ruby
+Janela::Snapshot.take(name: "September 2026", filters: { status_eq: "paid" }) do |take|
+  take.pane Order, :revenue,                                on: policy_scope(Order)
+  take.pane Order, :revenue, by: :status,                   on: policy_scope(Order)
+  take.pane Order, :revenue, by: :placed_on, granularity: :week
+end
+```
+
+Render a stored pane the same way you render a live one:
+
+```erb
+<%= janela_snapshot_pane @snapshot, Order, :revenue, by: :status, as: :bar %>
+```
+
+Panes render in Janela's own minimal layout when opened directly, so a shared pane link shows its numbers but no host styling and no charts; set `Janela::ApplicationController.layout "application"` in an initializer to use your own layout, which must not call a bare host route helper (inside an engine those need a `main_app.` prefix). Inside a dashboard, panes are Turbo Frames and carry no layout at all.
+
+Stored panes are static by nature: no filter buttons, charts ignore clicks, and the URL says *as of*: `/dashboards/snapshots/42/orders/revenue/status`. Request filters are ignored because the snapshot's were fixed when it was taken.
+
+`Janela::SnapshotJob.perform_later(name:, panes: [{ "model" => "orders", "measure" => "revenue", "by" => "status" }])` takes one from serialisable arguments so you can schedule it with whatever runs your jobs. The job uses each model's default scope; if you scope by tenant, write your own job around `Snapshot.take` and pass `on:`.
 
-A visual ignores filters on its own dimension, so clicking a value re-scopes the rest of the dashboard rather than collapsing the visual you clicked. The selected value is marked `aria-pressed="true"` on tables and drawn solid against faded siblings on charts, so it can be styled and read. A visual with no matching rows renders a `.janela-empty` paragraph. Only models that declare a `janela` block can be requested over HTTP.
+Who may see a snapshot is your decision. Stored panes go through the same controllers as live ones, so your authentication applies; an external audience gets a page you build over `janela_snapshot_pane` behind whatever share tokens you already trust. ADR 009 has the reasoning.
 
 ### Securing dashboards
 
@@ -153,7 +206,7 @@ Janela ships the load-bearing core of a BI tool and nothing else. The reasoning
 
 - **Measures and dimensions are a Ruby DSL on the model**, config-as-code like `routes.rb`. No drag-and-drop designer.
 - **Querying rides on [Ransack](https://github.com/activerecord-hackery/ransack)'s association-path traversal.** Janela does not invent a query language.
-- **Cross-filtering is a Stimulus controller plus Turbo Frames.** Click a value in one visual, shared filter state updates, every other frame on the page re-renders.
+- **Cross-filtering is a Stimulus controller plus Turbo Frames.** Click a value in one pane, shared filter state updates, every other frame on the page re-renders.
 - **Charts are [Chart.js](https://www.chartjs.org)**, driven by one small Stimulus controller from the same values the tables show. Not a charting engine.
 - **Publishing creates a Snapshot.** An ActiveJob freezes the result set into a new record; the live dashboard stays editable and the published view is a point-in-time fork, not a toggle on the same record. Not built yet.
 
@@ -161,7 +214,7 @@ Deliberately out of scope: report designer UI, natural-language query, a separat
 
 ## Status
 
-**v0.1.0 alpha.** The measures/dimensions DSL, cross-filtering, and bar charts work and are covered by unit and real-browser tests. Not yet built: time-granularity dimensions, other chart types, filter state in the page URL, published snapshots. Open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
+**v0.2.1 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering, bar and line charts, pane URLs, shareable dashboard URLs and snapshots work and are covered by unit and real-browser tests. Not yet built: drill-down on time panes, other chart types. Open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
 
 ## Development
 

data/app/assets/javascripts/janela/chart_controller.js

@@ -3,27 +3,34 @@ import { Chart, registerables } from "chart.js"
 
 Chart.register(...registerables)
 
-// Renders one visual as a chart and turns a click on a bar into the same
+// Renders one pane as a chart and turns a click on a bar into the same
 // toggle event a table button emits, so the dashboard controller cannot tell
 // the difference. Turbo replaces the frame on every cross-filter, so the chart
 // is destroyed on disconnect and rebuilt on connect.
 export default class extends Controller {
-  static values = { type: String, labels: Array, values: Array, key: String, title: String, selected: String }
+  static values = { type: String, labels: Array, values: Array, filters: Object, title: String, selected: String }
 
   connect() {
     this.chart = new Chart(this.element, {
       type: this.typeValue,
       data: {
         labels: this.labelsValue,
-        datasets: [{ label: this.titleValue, data: this.valuesValue, backgroundColor: this.colours() }]
+        datasets: [{
+          label: this.titleValue,
+          data: this.valuesValue,
+          backgroundColor: this.colours(),
+          borderColor: "rgba(54, 162, 235, 0.9)"
+        }]
       },
       options: {
         animation: false,
+        scales: { y: { beginAtZero: true } },
         plugins: { legend: { display: false } },
         onClick: (_event, elements) => {
           if (elements.length === 0) return
-          const value = this.labelsValue[elements[0].index]
-          this.dispatch("toggle", { detail: { key: this.keyValue, value } })
+          const label = this.labelsValue[elements[0].index]
+          const [key, value] = this.filtersValue[String(label)] || []
+          if (key) this.dispatch("toggle", { detail: { key, value } })
         }
       }
     })

data/app/assets/javascripts/janela/dashboard_controller.js

@@ -1,10 +1,10 @@
 import { Controller } from "@hotwired/stimulus"
 
-// Shared filter state for every visual on the page. Clicking a value rewrites
+// Shared filter state for every pane on the page. Clicking a value rewrites
 // each frame's src, and Turbo reloads a frame whenever its src changes, so
 // cross-filtering needs no streams, no sockets and no state library.
 export default class extends Controller {
-  static targets = ["visual"]
+  static targets = ["pane"]
   static values = { filters: Object }
 
   // Table buttons send key/value as Stimulus action params; charts dispatch a
@@ -27,14 +27,32 @@ export default class extends Controller {
   }
 
   filtersValueChanged() {
-    this.visualTargets.forEach((visual) => {
-      const url = new URL(visual.dataset.janelaSrc, window.location.origin)
+    this.paneTargets.forEach((pane) => {
+      const url = new URL(pane.dataset.janelaSrc, window.location.origin)
+      this.writeFilters(url)
+      if (pane.src !== url.href) pane.src = url.href
+    })
 
-      for (const [key, value] of Object.entries(this.filtersValue)) {
-        url.searchParams.set(`q[${key}]`, value)
-      }
+    this.syncPageUrl()
+  }
 
-      if (visual.src !== url.href) visual.src = url.href
-    })
+  // The page URL carries the same q[...] the panes do, so a reload or a
+  // pasted link opens the dashboard filtered (ADR 008). Replaced rather than
+  // pushed: a click is not a place the back button should return to.
+  syncPageUrl() {
+    const url = new URL(window.location.href)
+    for (const key of [...url.searchParams.keys()]) {
+      if (key.startsWith("q[")) url.searchParams.delete(key)
+    }
+    this.writeFilters(url)
+    if (url.href !== window.location.href) history.replaceState(history.state, "", url)
+  }
+
+  // Sorted so the browser serialises filters the same way the server does and
+  // an unchanged src is never reloaded.
+  writeFilters(url) {
+    for (const key of Object.keys(this.filtersValue).sort()) {
+      url.searchParams.set(`q[${key}]`, this.filtersValue[key])
+    }
   }
 }

data/app/controllers/janela/application_controller.rb

@@ -1,5 +1,13 @@
 module Janela
   class ApplicationController < Janela.parent_controller.constantize
+    # A frame request needs no layout, since Turbo keeps only the matching
+    # frame. A direct request gets Janela's own minimal layout, because a host
+    # layout's route helpers cannot resolve inside an isolated engine (ADR 011).
+    layout -> { turbo_frame_request? ? false : "janela/application" }
+
+    rescue_from Janela::NotFound, with: :janela_not_found
+    rescue_from Janela::BadRequest, with: :janela_bad_request
+
     private
       # Pundit defines policy_scope on the host's ApplicationController, which
       # this inherits from, so authorisation applies without Janela depending
@@ -7,5 +15,24 @@ module Janela
       def janela_scope(model)
         respond_to?(:policy_scope, true) ? policy_scope(model) : model.all
       end
+
+      def janela_not_found(error)
+        janela_error(error, :not_found, "There is no such pane.")
+      end
+
+      def janela_bad_request(error)
+        janela_error(error, :bad_request, "That request is not allowed on this pane.")
+      end
+
+      # The detail names models and filter keys, so it goes to the log; the
+      # client sees a plain sentence. A Turbo Frame request gets its frame
+      # back so the dashboard shows the sentence where the pane would be.
+      def janela_error(error, status, message)
+        logger.warn("Janela: #{error.message}")
+        body = view_context.tag.p(message, class: "janela-pane janela-error")
+        frame = request.headers["Turbo-Frame"]
+        body = view_context.turbo_frame_tag(frame) { body } if frame.present?
+        render html: body, status: status, layout: frame.blank?
+      end
   end
 end

data/app/controllers/janela/{visuals_controller.rb → panes_controller.rb}

@@ -1,15 +1,17 @@
 module Janela
-  class VisualsController < ApplicationController
+  class PanesController < ApplicationController
     def show
-      @visual = Visual.new(
+      @pane = Pane.new(
         definition: Janela.definition!(params.require(:model)),
         measure: params.require(:measure).to_sym,
-        dimension: params.require(:by).to_sym,
+        dimension: params[:dimension]&.to_sym,
         renderer: params.fetch(:as, "table"),
+        granularity: params[:granularity],
+        limit: params[:limit],
         filters: filters
       )
 
-      @result = @visual.result(on: janela_scope(@visual.model))
+      @result = @pane.result(on: janela_scope(@pane.model))
     end
 
     private

data/app/controllers/janela/snapshot_panes_controller.rb

@@ -0,0 +1,21 @@
+module Janela
+  # A pane as it was when a snapshot was taken. Filters in the request are
+  # ignored: they were fixed at taking (ADR 009).
+  class SnapshotPanesController < ApplicationController
+    def show
+      snapshot = Snapshot.find(params.require(:snapshot_id))
+      @pane = Pane.new(
+        definition: Janela.definition!(params.require(:model)),
+        measure: params.require(:measure).to_sym,
+        dimension: params[:dimension]&.to_sym,
+        renderer: params.fetch(:as, "table"),
+        granularity: params[:granularity],
+        limit: params[:limit],
+        snapshot: snapshot
+      )
+
+      @result = @pane.result
+      render "janela/panes/show"
+    end
+  end
+end

data/app/helpers/janela/dashboard_helper.rb

@@ -1,16 +1,49 @@
 module Janela
   module DashboardHelper
+    # The page URL carries the dashboard's filters as q[...] (ADR 008), so a
+    # shared link renders filtered before any JavaScript runs.
     def janela_dashboard(&block)
-      tag.div(data: { controller: "janela--dashboard" }, &block)
+      tag.div(data: { controller: "janela--dashboard", janela__dashboard_filters_value: janela_page_filters.to_json }, &block)
     end
 
-    def janela_visual(model, measure, by:, as: :table)
-      src = janela.visual_path(model: model.name, measure: measure, by: by, as: as)
+    def janela_pane(model, measure, by: nil, as: :table, granularity: nil, limit: nil)
+      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit }.compact
+      base = janela_routes.pane_path(model.model_name.route_key, measure, by, **query)
+      src = janela_page_filters.empty? ? base : janela_routes.pane_path(model.model_name.route_key, measure, by, **query, q: janela_page_filters)
 
-      turbo_frame_tag Visual.frame_id(model: model.name, measure: measure, by: by, as: as),
+      turbo_frame_tag Pane.frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit),
         src: src,
         loading: :lazy,
-        data: { janela__dashboard_target: "visual", janela_src: src }
+        data: { janela__dashboard_target: "pane", janela_src: base }
     end
+
+    # A pane as it was when the snapshot was taken: same shape as janela_pane,
+    # not part of the live dashboard's filter state (ADR 009).
+    def janela_snapshot_pane(snapshot, model, measure, by: nil, as: :table, granularity: nil, limit: nil)
+      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit }.compact
+      src = janela_routes.snapshot_pane_path(snapshot, model.model_name.route_key, measure, by, **query)
+
+      turbo_frame_tag Pane.frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit, snapshot: snapshot),
+        src: src, loading: :lazy
+    end
+
+    private
+      def janela_page_filters
+        @janela_page_filters ||= begin
+          q = request.query_parameters["q"]
+          q.is_a?(Hash) ? q.sort.to_h : {}
+        end
+      end
+
+      # The host chooses where and under what name the engine is mounted, so
+      # the route proxy is looked up rather than assumed to be `janela`.
+      def janela_routes
+        @janela_routes ||= begin
+          mount = Rails.application.routes.routes.find { |route| route.app.respond_to?(:app) && route.app.app == Janela::Engine }
+          raise Error, "Janela::Engine is not mounted in the host application's routes" unless mount
+
+          public_send(mount.name)
+        end
+      end
   end
 end

data/app/jobs/janela/snapshot_job.rb

@@ -0,0 +1,18 @@
+module Janela
+  # Takes a snapshot from serialisable arguments so a host can schedule it
+  # with whatever runs its jobs. Each pane uses its model's default scope; a
+  # host that scopes by tenant writes its own job around Snapshot.take and
+  # passes on: (ADR 009).
+  class SnapshotJob < ActiveJob::Base
+    def perform(name:, panes:, filters: {})
+      Snapshot.take(name: name, filters: filters) do |take|
+        panes.each do |pane|
+          pane = pane.to_h.stringify_keys
+          model = Janela.definition!(pane.fetch("model")).model
+          take.pane(model, pane.fetch("measure").to_sym,
+                    by: pane["by"]&.to_sym, granularity: pane["granularity"], limit: pane["limit"])
+        end
+      end
+    end
+  end
+end

data/app/models/janela/pane.rb

@@ -0,0 +1,137 @@
+module Janela
+  # One pane of a dashboard: a measure, optionally grouped by a dimension,
+  # rendered as a single value, a table or a chart. A pane ignores filters on
+  # its own dimension so that clicking a value re-scopes the other panes
+  # rather than collapsing this one to the value clicked. A pane read from a
+  # snapshot shows stored results and cannot be clicked at all.
+  class Pane
+    RENDERERS = %w[table bar line].freeze
+
+    attr_reader :definition, :measure, :dimension, :renderer, :limit, :filters, :snapshot
+
+    # The helper renders the frame and the controller renders its replacement,
+    # so both derive the id the same way from the same parameters.
+    def self.frame_id(model:, measure:, by: nil, as: :table, granularity: nil, limit: 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) ]
+      parts.compact.join("_")
+    end
+
+    def initialize(definition:, measure:, dimension: nil, renderer: "table", granularity: nil, limit: nil, filters: {}, snapshot: nil)
+      @definition = definition
+      @measure = measure
+      @dimension = dimension
+      @renderer = renderer.to_s
+      @filters = filters
+      @snapshot = snapshot
+
+      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?
+    end
+
+    def model
+      definition.model
+    end
+
+    def single_value?
+      dimension.nil?
+    end
+
+    def time?
+      !single_value? && dimension_definition.time?
+    end
+
+    def frozen?
+      !snapshot.nil?
+    end
+
+    def granularity
+      @granularity || (dimension_definition.granularity if time?)
+    end
+
+    # Clicking a category adds one Ransack condition; clicking a time bucket
+    # would need two, and the dashboard toggles one key at a time (ADR 006).
+    # A stored pane is the record of a moment and is not clickable (ADR 009).
+    def clickable?
+      !single_value? && !time? && !frozen?
+    end
+
+    def chart?
+      !single_value? && renderer != "table"
+    end
+
+    def frame_id
+      self.class.frame_id(model: model, measure: measure, by: dimension, as: renderer,
+                          granularity: @granularity, limit: limit, snapshot: snapshot)
+    end
+
+    def title
+      base = if single_value?
+        measure.to_s.humanize
+      else
+        by = "#{measure.to_s.humanize} by #{dimension.to_s.humanize}"
+        time? ? "#{by} per #{granularity}" : by
+      end
+      frozen? ? "#{base} as of #{snapshot.taken_at.strftime('%-d %b %Y')}" : base
+    end
+
+    # 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 }
+    end
+
+    def result(on: nil)
+      return snapshot.stored_result(self) if frozen?
+
+      definition.query(measure, by: dimension, where: applicable_filters, on: on, granularity: granularity, limit: limit)
+    end
+
+    # The Ransack key and value a click on this label should toggle. A null
+    # group filters with the null predicate, not an empty string (ADR 009 has
+    # no say here; see issue #21).
+    def filter_params(label)
+      return [ nil, nil ] unless clickable?
+      return [ "#{ransack_name}_null", "1" ] if label.to_s == Dimension::NONE
+
+      [ "#{ransack_name}_eq", label.to_s ]
+    end
+
+    # Every label in this pane paired with the filter it toggles, for a chart
+    # to look up by label when a bar is clicked.
+    def filters_for(labels)
+      return {} unless clickable?
+
+      labels.to_h { |label| [ label.to_s, filter_params(label) ] }
+    end
+
+    # The filter on this pane's own dimension is not applied to its query, but
+    # it is what the user clicked here, so the view highlights it.
+    def selected_value
+      return unless clickable?
+      return Dimension::NONE if filter("#{ransack_name}_null").present?
+
+      filter("#{ransack_name}_eq")
+    end
+
+    private
+      def filter(key)
+        filters[key] || filters[key.to_sym]
+      end
+
+      def dimension_definition
+        definition.dimension!(dimension)
+      end
+
+      def ransack_name
+        dimension_definition.ransack_name
+      end
+
+      def applicable_filters
+        return filters if single_value? || time?
+
+        filters.reject { |key, _| key.to_s.start_with?(ransack_name) }
+      end
+  end
+end

data/app/models/janela/snapshot.rb

@@ -0,0 +1,51 @@
+module Janela
+  # A snapshot freezes the results of several panes at one instant under one
+  # set of filters, so an audience sees exactly what was signed off while the
+  # live dashboard stays editable (ADR 009). Results are stored, not HTML; the
+  # renderer is chosen by whoever shows a stored pane.
+  class Snapshot < ActiveRecord::Base
+    attribute :filters, default: -> { {} }
+    attribute :panes, default: -> { [] }
+
+    validates :name, :taken_at, presence: true
+
+    def self.take(name:, filters: {}, taken_at: Time.current)
+      taking = Taking.new(filters.to_h.stringify_keys)
+      yield taking
+      create!(name: name, taken_at: taken_at, filters: taking.filters, panes: taking.panes)
+    end
+
+    def stored_result(pane)
+      key = pane.lookup_key
+      entry = panes.find { |stored| stored.slice(*key.keys) == key }
+      raise NotFound, "snapshot #{id} has no pane #{key.compact.values.join(' ')}" unless entry
+
+      entry["result"]
+    end
+
+    class Taking
+      attr_reader :filters, :panes
+
+      def initialize(filters)
+        @filters = filters
+        @panes = []
+      end
+
+      def pane(model, measure, by: nil, granularity: nil, limit: nil, on: nil)
+        pane = Pane.new(definition: model.janela, measure: measure, dimension: by,
+                        granularity: granularity, limit: limit, filters: filters)
+        panes << pane.lookup_key.merge("result" => plain(pane.result(on: on)))
+      end
+
+      private
+        # BigDecimal would otherwise be encoded as a JSON string.
+        def plain(result)
+          case result
+          when Hash then result.transform_values { |v| plain(v) }
+          when BigDecimal then result.to_f
+          else result
+          end
+        end
+    end
+  end
+end