janela 0.6.0 → 0.8.0

data/docs/multi-tenancy.md

@@ -6,15 +6,22 @@ engine asks your application two questions and does what it is told.
 
 | Question | How your application answers | If it says nothing |
 | --- | --- | --- |
-| What may this request read? | `policy_scope(model)` on the controller Janela inherits | Everything: `model.all` |
+| What may this request read? | `policy_scope(model)` on the controller Janela inherits | Nothing: it raises `Janela::Unscoped` |
 | What owns a frame being created? | `janela_frame_owner` on the same controller | Nothing: a nil owner |
+| What owns a snapshot being taken? | `owner:`, an argument to `Snapshot.take` | Nothing: a nil owner |
+| What rows does a scheduled snapshot freeze? | `scope:` on `SnapshotJob`, or `scope_for` in a subclass of it | Nothing: it raises `Janela::Unscoped` |
 
-Both are ordinary methods on your `ApplicationController`, found by
-duck typing. Pundit defines the first for you. Anything else, you
-define in about five lines. ADR 019 has the reasoning for asking
+The first two are ordinary methods on your `ApplicationController`,
+found by duck typing. Pundit defines the first for you. Anything else,
+you define in about five lines. ADR 019 has the reasoning for asking
 rather than being configured: ownership is per-request state, and a
 setting cannot hold it.
 
+The third is an argument rather than a method for the reason ADR 033
+gives: a snapshot is never taken in a request. It is taken in a job, a
+task or a console, where there is no controller to ask and no current
+tenant to ask about, so the caller passes what it already knows.
+
 ## What goes through your scope
 
 Everything. There is no path through the engine that reads a record
@@ -104,9 +111,28 @@ class and returns a relation is the whole contract.
 
 ## With one tenant
 
-Define nothing. `policy_scope` is absent, every query runs over
-`model.all`, and a frame is created with a nil owner because nothing
-is filtering on one.
+Write the answer anyway, once:
+
+```ruby
+class ApplicationController < ActionController::Base
+  private
+    def policy_scope(model) = model.all
+end
+```
+
+Janela will not guess this one. Every other question here takes silence
+as an answer, because the silent answer is the narrow one: no owner, no
+theme, no tenancy. This question's permissive answer is the widest thing
+a library can assume, so it is the one you have to say out loud (ADR
+032).
+
+The line is not ceremony either. It asserts that everyone who can reach
+a dashboard may read every row behind it, and "one tenant" and "no rows
+worth hiding from staff" are not the same claim. If the second is not
+true here, return something narrower.
+
+A frame is still created with a nil owner, because nothing is filtering
+on one.
 
 ## What owns a frame
 
@@ -123,20 +149,63 @@ save failed silently. `bin/rails janela:doctor` reports this for you:
 it asks your policy for a scope over frames and looks for an owner in
 what comes back.
 
-## Snapshots are the rough edge
+## Snapshots
+
+A snapshot carries the same polymorphic owner a frame does, so your
+policy has the same column to filter on. You pass it when you take one:
+
+```ruby
+Janela::Snapshot.take(name: "September 2026", owner: ActsAsTenant.current_tenant) do |take|
+  take.pane Order, :revenue, on: policy_scope(Order)
+end
+```
+
+```ruby
+def policy_scope(model)
+  case model.name
+  when "Janela::Frame", "Janela::Snapshot" then model.where(owner: ActsAsTenant.current_tenant)
+  else model.all
+  end
+end
+```
+
+`Janela::SnapshotJob` takes `owner:` as well, since ActiveJob carries a
+record across the queue through its GlobalID.
+
+## What a scheduled snapshot freezes
+
+The owner says who a snapshot belongs to. What the numbers inside it
+cover is a separate question, and the job asks you rather than guessing.
 
-`janela_snapshots` has no owner column. A snapshot is a name, an
-instant, the filters it was taken under and the results. So a multi
-tenant application has to scope it by something else:
+A model's default scope is already your tenant's rows if your tenancy is
+enforced on the models, through acts_as_tenant, a `default_scope`, a
+connection or a schema. Say so:
+
+```ruby
+Janela::SnapshotJob.perform_later(name: "September 2026", owner: tenant,
+                                  scope: :model_default, panes: [ ... ])
+```
+
+If your scoping lives in your policies, `model.all` is every row, and no
+symbol can carry the relation you want across a queue. Answer in Ruby.
+Subclass the job, override its one question, and schedule yours:
+
+```ruby
+class TenantSnapshotJob < Janela::SnapshotJob
+  private def scope_for(model) = model.where(account: owner)
+end
+```
 
-- Keep snapshots to one tenant, or to whoever publishes.
-- Add your own column with a migration on `janela_snapshots` and scope
-  on that.
-- Encode the tenant in the filters a snapshot is taken under, and
-  scope on the stored name.
+`name`, `owner` and `filters` are readable inside `scope_for`, so a
+subclass never has to override `perform` or read ActiveJob's arguments.
+Override `scope_for` and the `scope:` argument is not consulted: the
+method that reads it is the one you replaced.
 
-None of those is as clean as a frame's owner. Giving a snapshot the
-same polymorphic owner is [issue #32](https://github.com/retail-tasker/janela/issues/32).
+Answer neither way and the job raises `Janela::Unscoped` instead of
+freezing a scope nobody chose. That matters more here than on a live
+page: a wrong pane is wrong once, on a screen, to somebody already
+signed in, while a wrong snapshot is frozen into a row, labelled with an
+owner and served at an address (ADR 034).
 
 ## Proving your wiring
 

data/docs/roadmap.md

@@ -0,0 +1,97 @@
+---
+Topics: roadmap, releases, scope, planning
+---
+
+# Where Janela Is Going
+
+Janela is alpha. It works, it is tested against a real Rails application
+in a real browser, and its public surface has changed in three of the
+last four releases. This page says what has to be true before that stops,
+what is in the next release, and what is deliberately not coming. The
+reasoning behind it is ADR 037.
+
+## What 1.0 means
+
+Not that Janela is finished. ADR 001 commits the project to the
+load-bearing 5% of a BI tool and to staying small enough to fork, so a
+1.0 measured against what a commercial tool ships would never arrive.
+
+1.0 is three claims you can check.
+
+**The public surface stops moving.** Everything listed as the contract in
+[Theming Janela](theming), the measures and dimensions DSL, `janela_pane`
+and `janela_frame`, the pane URL shape and the dashboard filter
+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.
+
+**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.
+
+## In 1.0
+
+| 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 |
+
+Progress is tracked on the
+[1.0 milestone](https://github.com/retail-tasker/janela/milestone/2).
+
+## After 1.0
+
+Wanted, not blocking a stable release. 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
+  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.
+- **A scroll drift on the gallery page** ([#45](https://github.com/retail-tasker/janela/issues/45)).
+  Cosmetic, demo only, and possibly not worth fixing.
+
+## Not coming
+
+Janela is meant to be small enough that forking it and adding your own
+piece is a normal way to use it. These are the things you would be
+adding yourself, and each is left out because something you already run
+does it better.
+
+Natural-language query. A separate data warehouse. A row-level-security
+subsystem, because your application already has Pundit or CanCanCan and
+Janela reads through it. A refresh-scheduling interface, because you
+already have a scheduler and snapshots are an ActiveJob. An embedding
+SDK. A mobile application. Print and paginated reports. A drag-and-drop
+visual dashboard designer, though frames and panes are database records,
+so an application can build its own editor on top of them.
+
+Whether Janela should help arrange panes on a page is genuinely open
+([#29](https://github.com/retail-tasker/janela/issues/29)). The default
+answer is that layout belongs to your application, and changing it would
+need a decision record first.
+
+## How this page stays honest
+
+It is updated when a release lands, not on a schedule, and it carries no
+dates. A roadmap with dates on a project this size would be wrong within
+a fortnight and would train you to ignore it. If something here has been
+true for a long time and nothing has moved, that is worth reading as the
+signal it is.

data/docs/theming.md

@@ -0,0 +1,177 @@
+---
+Topics: styling, theming, css, host-integration
+---
+
+# Theming Janela
+
+Janela publishes the hooks; a theme supplies the taste. This page is the
+contract: the class names and custom properties the engine renders, which
+your own stylesheet or somebody else's theme may target, and which will
+not change without an entry in `UPGRADING.md` (ADR 036).
+
+Two stylesheets ship in the gem.
+
+```erb
+<%= stylesheet_link_tag "janela" %>   <%# the hooks, and enough style to be legible %>
+<%= stylesheet_link_tag "vitral" %>   <%# optional: one theme, stained glass %>
+```
+
+`janela.css` is not a look. It is the grid, the pane's own markup and
+enough base styling that a table does not run its label into its number.
+Everything decorative is a theme's, and vitral is one theme rather than
+the theme.
+
+## The contract
+
+### Custom properties
+
+Three, and setting them moves everything that depends on them.
+
+| 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. |
+
+```css
+:root {
+  --janela-space: 0.3rem;
+  --janela-accent: #7c3aed;
+}
+```
+
+### The grid
+
+A frame's stored integers choose these. Nothing an analyst types reaches
+CSS as a length: the number selects a rule that is already written
+(ADR 016).
+
+| Class | Range |
+| --- | --- |
+| `janela-frame` | the grid container itself |
+| `janela-cols-N` | 1 to 12 |
+| `janela-gap-N` | 0 to 8, multiplied by `--janela-space` |
+| `janela-span-N` | 1 to 12, on a pane |
+
+Below `40rem` the grid collapses to one column. That is in the
+stylesheet rather than in the data, because a dashboard nobody can read
+on a phone is not a choice worth offering.
+
+### The pane
+
+What `janela_pane` and `janela_frame` put in your own pages. These are
+the names a theme spends most of its time on.
+
+| Class | On | Rendered when |
+| --- | --- | --- |
+| `janela-pane` | `<table>`, `<p>` or `<canvas>` | every pane, whatever the renderer |
+| `janela-value` | `<p>` | a single value pane |
+| `janela-value-label` | `<span>` | its caption |
+| `janela-value-number` | `<strong>` | the number itself |
+| `janela-chart` | `<canvas>` | a bar or line pane |
+| `janela-empty` | `<p>` | a pane whose query returned nothing |
+| `janela-error` | `<p>` | a pane that could not be read |
+
+A table pane also renders a `<caption>`, its accessible name, and a
+chart pane carries the same string as `aria-label`.
+
+### Hiding a heading you already wrote
+
+Put `janela-own-headings` on any ancestor and a pane's caption and a
+single value's label are hidden from sight while staying in the
+accessibility tree.
+
+```erb
+<div class="janela-own-headings">
+  <h3>Revenue by status</h3>
+  <%= janela_pane Order, :revenue, by: :status %>
+</div>
+```
+
+Use it when your own markup already says what the pane is, so the text
+is not on screen twice. It hides rather than removes on purpose: a table
+with no caption has no accessible name, so a screen reader lands on a
+grid of numbers with nothing to say what they measure. `display: none`
+would do that, which is why this rule ships here rather than being left
+for each host to write.
+
+A chart pane needs nothing: its title is only ever an `aria-label` and
+was never drawn.
+
+## What is not the contract
+
+`janela.css` also styles Janela's own pages, the frame index and the
+editing forms: `janela-page`, `janela-card`, `janela-button`,
+`janela-form`, `janela-field`, `janela-list`, `janela-crumb`,
+`janela-flash` and the rest. They are scoped under `janela-page`, which
+only the engine's own layout sets, so they cannot touch your pages.
+
+**Those names may change in any release.** They are the engine's own
+chrome rather than an interface. Restyle them if you want Janela's
+pages to match your application, and expect to revisit it after an
+upgrade; or point `Janela.theme` at a stylesheet of your own, below.
+
+## Writing a theme
+
+A theme is any stylesheet, named once:
+
+```ruby
+# config/initializers/janela.rb
+Janela.theme = "midnight"
+```
+
+The name is resolved against your own asset paths, so `midnight.css` in
+your application works exactly as the gem's own `vitral` does. A name
+that resolves to nothing raises rather than quietly rendering an
+unthemed page.
+
+That setting links the theme into **Janela's own pages**. Your pages load
+whatever your layout says, so if you want the same look around a pane you
+have embedded yourself, link the stylesheet there too. The asymmetry is
+deliberate: Janela is an isolated engine and does not write your layout
+(ADR 011).
+
+A theme targets the contract above and nothing else. If it cannot be
+written that way, the contract is missing something, which is worth an
+issue rather than a workaround.
+
+## Vitral
+
+The theme the gem ships. A *vitral* is a stained glass window: each pane
+holds one of five colours, dark leading runs between them, and the light
+comes from behind.
+
+```erb
+<%= stylesheet_link_tag "vitral" %>
+<body class="vitral">
+```
+
+Nothing is repainted until that class is present, so linking the
+stylesheet can never be the thing that broke a page.
+
+**Its own public classes**, so the page around a dashboard can be made of
+the same window: `vitral-pane`, `vitral-panes`, `vitral-button`,
+`vitral-button-primary`, `vitral-lattice`.
+
+**Retheme it from its custom properties** rather than by forking it. The
+light is `--vitral-light-cobalt`, `-teal`, `-amber`, `-rose`, `-violet`;
+the glass is `--vitral-pane-1` through `-5`; the leading is
+`--vitral-came`; and `--vitral-ink`, `--vitral-muted`, `--vitral-ground`,
+`--vitral-radius`, `--vitral-shadow` and `--vitral-blur` do what they
+say.
+
+```css
+:root {
+  --vitral-pane-1: rgba(120, 60, 200, 0.3);
+  --vitral-came: #1b1b1b;
+}
+```
+
+**It works without JavaScript.** Janela's own pages load none (ADR 011),
+so the stained glass is CSS and the lattice that leans toward the pointer
+is a separate optional controller. Reduced motion, reduced transparency
+and increased contrast each fall back to a still, solid window, and so
+does a browser without `backdrop-filter`.
+
+`test/dummy` has a live page at `/vitral` showing all of it against real
+panes.

data/lib/janela/definition.rb

@@ -6,8 +6,15 @@ module Janela
 
     attr_reader :model, :measures, :dimensions
 
+    # The class whose janela block this is, which a subclass shares with the
+    # parent it inherited from. A subclass gets a definition of its own, so
+    # anything reporting on a declaration rather than on a model groups by
+    # this or says the same thing once per class in an STI family (ADR 035).
+    attr_accessor :declared_by
+
     def initialize(model, &block)
       @model = model
+      @declared_by = model
       @measures = {}
       @dimensions = {}
       @block = block
@@ -19,7 +26,7 @@ module Janela
     # the queries they run are its own, because ActiveRecord adds the type
     # condition to a relation on the subclass (ADR 031).
     def for(model)
-      self.class.new(model, &@block)
+      self.class.new(model, &@block).tap { |inherited| inherited.declared_by = declared_by }
     end
 
     def measure(name, **aggregate)