janela 0.7.0 → 0.8.0

data/docs/decisions/037-what-1-0-means.md

@@ -0,0 +1,172 @@
+---
+Date: 2026-09-23
+Status: Accepted
+Related: ADR 001, ADR 010, ADR 015, ADR 021
+Triggers:
+  - deciding whether an open issue belongs in the next release
+  - proposing a feature, or arguing that one is out of scope
+  - cutting a release and choosing the version number
+  - deciding whether a breaking change is still affordable
+  - wondering whether the project is drifting
+Topics: vision, scope, forkability, releases, roadmap, planning
+---
+
+# ADR 037: 1.0 Means the Surface Stops Moving, Not That Janela Is Finished
+
+## Context
+
+Janela has a vision and a backlog and nothing in between. ADR 001 says
+what the project is, the load-bearing 5% of a BI tool, and the README's
+Design section lists what it will never be: natural-language query, a
+warehouse, a row-level-security subsystem, a scheduling UI, an embedding
+SDK, a mobile app, paginated reports. That is a stronger statement of
+scope than most libraries manage. What neither says is what order things
+happen in, or what has to be true before a host can build on this
+without expecting the ground to move.
+
+The gap shows up in three measurements taken today.
+
+**The surface moves every release.** Counting entries marked breaking in
+`CHANGELOG.md`: 0.5.0 carried one, 0.7.0 carried two, and the unreleased
+section carries two more. Five breaking changes across four releases in
+five days, every one of them correct and every one of them announced the
+way ADR 015 requires. This is what alpha is for and there is nothing to
+apologise for in it. It also means nobody outside this repository can
+build anything on Janela yet, because the DSL, the helpers, the pane
+URLs and the class names a theme targets have all changed underneath a
+host at least once.
+
+**The declared horizon ran out.** The `Before public release` milestone
+stands at ten closed and one open. It worked, it is nearly spent, and
+nothing replaced it. Thirteen of the fourteen open issues carry no
+milestone at all.
+
+**The issue list cannot rank itself.** Eight of those issues are
+enhancements, four of them raised from a real install, and none has been
+picked up while the last four releases went to hardening. That looked
+like drift and is worth being precise about, because it was not. ADRs
+025, 032, 034 and 035 are one argument made four times: Janela refuses
+rather than guesses about scope. Bounded predicates, a refused unscoped
+read, a refused unnamed snapshot scope, and a doctor that reports what it
+actually saw. That is the most coherent stretch of work in the project.
+The problem is that the theme was never declared, so it was invisible
+while it was happening, and now that it is finished there is nothing
+declared to follow it. A flat list of fourteen issues is what a project
+looks like between themes when it has no way of saying so.
+
+Three options were considered.
+
+**A roadmap with dates or quarters** was rejected. This project's
+throughput is not predictable enough to commit to a calendar, and a
+published roadmap that slips teaches people to stop reading it. The cost
+is ongoing and lands every release; the benefit is mostly the appearance
+of planning.
+
+**Leaving it to the issue list** was rejected because that is the current
+state, and the current state is what prompted the question. Labels
+describe what an issue is. Nothing describes what it is for.
+
+**Declaring 1.0 feature-complete** against what a commercial BI tool ships
+was rejected for contradicting ADR 001 outright. Janela is not trying to
+reach parity with anything. A 1.0 defined as "the features are all there"
+has no end, because the list it is measured against is somebody else's.
+
+## Decision
+
+**1.0 means the public surface stops moving, the 5% can be read, and the
+doctor can be trusted. It does not mean Janela is finished, and it is not
+a feature count.**
+
+Three claims, each of which can be checked rather than argued about.
+
+**The public surface stops moving.** After 1.0, everything
+`docs/theming.md` lists as the contract, 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. Before 1.0 they may
+change in any release, with the upgrade note ADR 015 requires. This is
+the load-bearing claim and the other two exist to serve it: a surface is
+only worth freezing once it is the right shape, which is why the feature
+work below sits inside 1.0 rather than after it. Freezing an API that is
+missing a limb only guarantees the limb arrives as a breaking change
+later.
+
+**The 5% can be read.** Janela draws three renderers, `table`, `bar` and
+`line`. A part-to-whole split has to be drawn as two bars. A table pane
+carries exactly two cells per row, so a label that needs context to be
+understood cannot have any. A chart takes Chart.js's 2:1 default and a
+host cannot correct it from outside. None of these is a feature beyond
+the 5%; each is the 5% not finished, and the distinguishing test is that
+four of them were raised by someone trying to use the gem rather than by
+someone reading its source. The theme that follows "Janela refuses rather
+than guesses" is legibility: a pane a person can actually read.
+
+**The doctor can be trusted.** ADR 021 holds that a check people stop
+trusting has stopped working. Every check in `CHECKS` bar two now has a
+test that makes it fire and one that leaves it quiet.
+
+The open issues sort as follows, and this sort is the substance of the
+decision rather than an illustration of it.
+
+In 1.0: #14 (a Sprockets host serves the engine's JavaScript or is told
+it cannot), #53 (the last two untested checks), #27 (a ratio measure, so
+the refusal in #20 offers somewhere to go), #30 (doughnut and pie, and
+the categorical palette that makes them readable), #31 (a pane says how
+prominent it is), #34 (a table carries an attribute column beside its
+label), #24 (a chart's height is the host's to set), and #6 (how
+contributions are accepted, who cuts a release, where to report a
+vulnerability privately).
+
+After 1.0: #18 (drill-down on time panes, which ADR 006 excluded
+deliberately and which needs an ADR of its own before any code), #41 (a
+command palette, which the issue itself argues belongs to the demo and
+not the gem), and #45 (a cosmetic scroll drift on one demo page, where
+the issue already allows that deciding not to fix it is a legitimate
+answer).
+
+Neither, and tracked as itself: #5 is an upstream pin on ActiveSupport
+and is removed when ActiveSupport is fixed. #56 is a one-in-160 test
+flake deliberately recorded rather than chased, and is evidence, not
+work.
+
+Needing a decision rather than a place: #29 asks Janela to help arrange
+panes on a page. ADR 011 has panes not rendering in the host's layout and
+ADR 001 prefers a fork to a configuration surface, so the default answer
+is that arrangement belongs to the host and the issue closes into the
+README's out-of-scope list. That is a scope decision and gets argued on
+its own rather than settled here by omission.
+
+**The roadmap is published rather than kept in the issue tracker.**
+`docs/roadmap.md` ships in the gem and renders on the demo at
+`/docs/roadmap`, because the demo reads the gem's own markdown rather
+than restating it (ADR 010). One file is therefore the public statement,
+the page a visitor reads and the copy in the installed gem at once. The
+GitHub milestone remains the working tracker and the progress bar; it
+says which issues, while the document says what the release is for. A
+reader who has to open an issue tracker to find out where a library is
+going has been told to do the maintainer's filing.
+
+## Consequences
+
+- A breaking change is cheap now and expensive after 1.0. Anything that
+  wants to change the DSL, the helpers or the published class names
+  should be argued for before 1.0 rather than after, and the sort above
+  is deliberately biased that way.
+- An issue outside 1.0 is not rejected. It is not blocking a release,
+  which is a different and weaker statement, and the roadmap says so in
+  those words so that nobody reads the list as a refusal.
+- The eight issues in 1.0 are a commitment made in public. That is the
+  point of publishing it and also its only real cost: a roadmap on the
+  website can be held against the project in a way a milestone cannot.
+- The current release is 0.8.0 and not 1.0, which this ADR answers
+  without further argument, because it carries two breaking changes.
+- `docs/roadmap.md` has to be updated when a release lands, or it becomes
+  the stale artifact this ADR rejected dated roadmaps for being. It is
+  named in `/jan-release` for that reason.
+- The README's Design section currently says snapshots are "not built
+  yet" and they shipped in 0.7.0. Publishing a roadmap beside a stale
+  status line makes the staleness worse, so that sentence is corrected in
+  the same change.
+- What would change this decision: a real install blocked by something in
+  the after-1.0 list. The sort is a judgement about what a host needs to
+  read a dashboard, and a host saying otherwise is better evidence than
+  the judgement.

data/docs/decisions/INDEX.md

@@ -20,26 +20,28 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 
 | Topic | ADRs |
 |-------|------|
-| **Vision, scope, forkability** | 001, 010, 012 |
-| **Open-source & host-decoupling** | 001, 022 |
+| **Vision, scope, forkability** | 001, 010, 012, 037 |
+| **Open-source & host-decoupling** | 001, 022, 036 |
 | **DSL & query layer** | 002, 006, 007, 020, 025 |
 | **Dependencies** | 002, 003, 004, 006, 017, 025 |
-| **Authorisation** | 002, 003, 004, 009, 017, 019, 022, 032, 033, 034 |
+| **Authorisation** | 002, 003, 004, 009, 017, 019, 022, 032, 033, 034, 035 |
 | **Performance & storage** | 007, 017, 025 |
 | **Cross-filtering & Hotwire** | 003, 004, 005, 008, 024, 025 |
 | **Layouts & views** | 011, 012, 016, 018, 020, 027 |
-| **CSS & styling** | 016, 018, 023, 026, 027 |
+| **CSS & styling** | 016, 018, 023, 026, 027, 036 |
 | **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030, 033 |
-| **Naming rule** | 014, 023 |
+| **Naming rule** | 014, 023, 036 |
 | **JavaScript delivery & charts** | 004, 006, 026 |
 | **Time dimensions** | 006, 025 |
 | **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025 |
 | **Snapshots & publishing** | 009, 020, 028, 033, 034 |
 | **AI agents & guidance** | 010, 015, 021 |
-| **Releases & upgrades** | 015, 021, 032, 034 |
+| **The doctor & checks** | 021, 025, 032, 033, 035 |
+| **Releases & upgrades** | 015, 021, 032, 034, 035, 036, 037 |
 | **Accessibility & keyboard** | 024 |
-| **Security** | 003, 025, 028, 031, 032, 034 |
+| **Security** | 003, 025, 028, 031, 032, 034, 035 |
 | **Testing** | 003 |
+| **Roadmap & planning** | 001, 037 |
 
 ## Chronological
 
@@ -79,7 +81,10 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 032 | Janela Will Not Read a Model It Cannot Scope | 2026-09-20 | Accepted |
 | 033 | A Snapshot Is Told Who Owns It | 2026-09-21 | Accepted |
 | 034 | Janela Will Not Freeze a Scope the Host Has Not Named | 2026-09-21 | Accepted |
+| 035 | A Check Does What Janela Does, or It Says What It Saw | 2026-09-22 | Accepted |
+| 036 | Janela Publishes What a Theme May Target, and Vitral Is Only One | 2026-09-22 | Accepted |
+| 037 | 1.0 Means the Surface Stops Moving, Not That Janela Is Finished | 2026-09-23 | Accepted |
 
 ## Next number
 
-Next ADR: 035
+Next ADR: 038

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)