janela 0.2.1 → 0.4.0

data/docs/decisions/022-host-route-helpers-work-inside-the-engine.md

@@ -0,0 +1,104 @@
+---
+Date: 2026-09-16
+Status: Accepted
+Related: ADR 004, ADR 005, ADR 011, ADR 019
+Triggers:
+  - a route helper raising inside Janela's controllers
+  - host code inherited from ApplicationController running in the engine
+  - authentication redirects
+  - anything that would make the engine less isolated
+Topics: host-integration, routing, engine-isolation, authentication
+---
+
+# ADR 022: A Host's Route Helpers Work Inside the Engine
+
+## Context
+
+`isolate_namespace Janela` points every route helper evaluated inside
+Janela's controllers at the engine's own route set. That is the right
+default for the engine's own code. It is the wrong answer for the
+host's, and the host's runs there constantly, because
+`Janela::ApplicationController` inherits the host's
+`ApplicationController` on purpose (ADR 004).
+
+Three reports, one cause, and each host found it separately:
+
+1. A host's application layout calling `root_path` in its nav, which
+   made every pane 500. Solved another way in 0.2.1 by not rendering
+   panes in the host's layout (ADR 011).
+2. A host authenticating per controller, whose `before_action`
+   redirected to `new_session_path`.
+3. A host authenticating globally, whose `Authentication` concern
+   redirected to `new_session_path` from inside the engine and raised
+   `ActionController::UrlGenerationError`. An unauthenticated visitor
+   got a 500 instead of a sign-in page.
+
+Case 3 is the one that shows the shape of the problem. The README had
+framed the fix as something to do "if your app authenticates per
+controller", which is not the trigger at all. The trigger is that a
+URL is generated by host code while it is inside the engine. A
+`rescue_from` that redirects, an `after_action`, a flash partial and an
+audit callback all qualify. Each host discovers it on its own, in
+production, as a 500.
+
+`main_app.new_session_path` is the documented fix and it works. It
+also asks every host to know that Janela is an isolated engine, and to
+remember it in code that has nothing to do with Janela. That is the
+opposite of what installing this gem is supposed to feel like.
+
+The option of including the host's `url_helpers` wholesale was
+considered and rejected. Both sets of helpers would then be present,
+and a name in both would resolve by module order, so `frames_path`
+inside Janela's own view could silently become the host's `/frames`.
+Trading a loud `UrlGenerationError` for a quietly wrong link is a bad
+trade.
+
+## Decision
+
+**Janela forwards to the host exactly those route helpers the engine
+does not define, and no others.**
+
+The set is computed when routes are loaded, as the host's helper names
+minus the engine's, and each one is defined to call `main_app`. It is
+rebuilt whenever routes reload, so a name that goes away goes away
+here too.
+
+```ruby
+# In a host's ApplicationController, running inside Janela:
+redirect_to new_session_path   # works, forwarded to the host
+frames_path                    # Janela's, never the host's /frames
+main_app.frames_path           # the host's, said unambiguously
+```
+
+Two properties matter more than the convenience:
+
+**The engine's own routes can never be shadowed.** A name is forwarded
+only when Janela does not define it, so no host route can change what
+one of Janela's own views means. Precedence is decided by
+construction, not by the order modules happened to be included.
+
+**`main_app` still means what it means.** Nothing is taken away. A
+host that prefers to be explicit, or that needs a name Janela also
+uses, says `main_app.` and is unambiguous.
+
+**This covers named helpers only.** `url_for(record)` and
+`redirect_to @record` resolve polymorphically at call time, so there
+is no name to forward and they still need `main_app.`. That boundary
+is documented rather than papered over.
+
+## Consequences
+
+- A host's authentication redirect works inside Janela with no
+  configuration, no reopened class and no knowledge that an engine is
+  involved. That was the whole complaint in three reports.
+- Janela is slightly less isolated than a textbook engine, in one
+  direction only: host names in, never Janela names out. ADR 005's
+  mount independence is untouched, since the engine still generates
+  every one of its own URLs through its own routes.
+- A host route helper shares a name with one of Janela's and the host
+  loses the bare name inside the engine. Janela's route names are few
+  and dull, which makes this rare, and `main_app.` remains.
+- The README's explanation was wrong about the cause and is corrected
+  here and there.
+- Polymorphic routing is a known gap. If it bites someone the answer
+  is another ADR, not a quiet widening of this one.

data/docs/decisions/023-vitral-is-a-theme-not-the-stylesheet.md

@@ -0,0 +1,86 @@
+---
+Date: 2026-09-16
+Status: Accepted
+Related: ADR 011, ADR 016, ADR 021
+Triggers:
+  - changing how Janela looks
+  - adding a stylesheet, a class or a custom property
+  - adding a Stimulus controller to the gem
+  - adding a setting
+Topics: styling, host-integration, configuration, naming
+---
+
+# ADR 023: Vitral Is a Theme, Not the Stylesheet
+
+## Context
+
+ADR 016 gave Janela one stylesheet, deliberately plain: the grid classes
+an analyst's numbers choose from, and just enough style that a pane is
+legible on install. That was right, and it left an obvious gap. A host
+that wants a dashboard to look like something has to write all of it,
+and the first thing anyone does with a new library is judge how it
+looks.
+
+The temptation is to make `janela.css` prettier. That would be a
+mistake. Structure and taste have different lifetimes: the grid classes
+are load bearing and must not change, while taste is the first thing a
+host will want to replace and the first thing we will want to revise.
+Putting both in one file means every visual revision risks the layout,
+and every host that dislikes the look has to fight rules it also needs.
+
+## Decision
+
+**A second stylesheet, `vitral.css`, optional and separate.**
+
+A *vitral* is a stained glass window. Janela is a window, its parts are
+frames and panes, and this is what the glass looks like. The name
+follows the same rule as the rest: an uncommon but conceivable word, so
+it never collides with the vocabulary a host already uses for its own
+things.
+
+```erb
+<%= stylesheet_link_tag "janela" %>
+<%= stylesheet_link_tag "vitral" %>
+```
+
+Four rules hold it in place.
+
+**Nothing is repainted until asked.** The light and the leading hang off
+a `vitral` class. A host that links the stylesheet and adds no class
+gets nothing, which means linking it can never be the thing that broke
+a page.
+
+**It is a small library, not a private skin.** `vitral-pane`,
+`vitral-panes` and `vitral-button` are public, so the page around a
+dashboard can be made of the same window. Everything else is a custom
+property, so a host rethemes from its own stylesheet rather than by
+forking this one.
+
+**The theme must be complete without JavaScript.** Janela's own pages
+load none at all (ADR 011), so the stained glass is CSS, and the part
+that answers the pointer is a separate optional controller. The
+stylesheet carries a static lattice for everyone who never loads it.
+
+**Janela's own pages wear it by name.** `Janela.theme = "vitral"` is the
+third setting this gem has, and it earns that the same way the second
+did: which theme, if any, is a judgement made once about the whole
+application, and that is what configuration is for (ADR 021). A host
+that leaves it unset gets the structural stylesheet, exactly as before.
+
+## Consequences
+
+- Janela looks like something out of the box, and a host that hates it
+  removes one line rather than overriding a hundred rules.
+- `janela.css` can stay frozen and boring while the theme moves. A
+  revision to the look is not a revision to the grid.
+- The lattice is an inline SVG data URI rather than an image, because a
+  stylesheet shipped in a gem cannot rely on a host's asset pipeline to
+  resolve a `url()`.
+- Accessibility is the theme's problem, not the host's: reduced motion,
+  reduced transparency and increased contrast each fall back to a
+  still, solid window, and so does a browser without `backdrop-filter`.
+- A visual change to vitral is visible to every host that opted in, so
+  it belongs in the changelog like any other change a host can see
+  (ADR 015). It is not a breaking change, because nothing depends on it.
+- A third stylesheet is a third thing for a Sprockets host to declare
+  for precompilation. The engine declares both itself.

data/docs/decisions/024-selecting-more-than-one-value.md

@@ -0,0 +1,127 @@
+---
+Date: 2026-09-16
+Status: Accepted
+Related: ADR 003, ADR 005, ADR 008, ADR 009, ADR 018
+Triggers:
+  - changing what a click on a value does
+  - adding a filter predicate or changing the URL grammar
+  - adding a keyboard shortcut
+  - anything a mouse can do that a keyboard cannot
+Topics: cross-filtering, urls, accessibility, ransack
+---
+
+# ADR 024: Selecting More Than One Value
+
+## Context
+
+A click on a value writes one Ransack condition, `q[status_eq]=paid`,
+and clicking the same value again removes it. One value per dimension.
+Every real dashboard eventually needs two: paid and pending, APAC and
+EU. A commercial tool does this with a modifier click, and everyone
+already knows the gesture.
+
+The gesture is the easy part. `toggle(event)` already receives the
+event, so `ctrlKey || metaKey` is there for a table button, and
+Chart.js hands its own click handler the native event. What needs
+deciding is what the URL says, what happens to the null group, and
+what someone without a mouse does instead, because a modifier click is
+invisible, absent on touch and unreachable from a keyboard. Deciding
+the gesture without deciding that last part would build a feature only
+some people can use (#35, #36).
+
+Three things were measured against the dummy before writing this,
+rather than assumed:
+
+- `status_in: [paid, pending]` passes Janela's allowlist guard and
+  returns the sum of both. A dimension's allowlist is per attribute, so
+  the predicate needs nothing added.
+- `status_eq: paid` still works, so an existing link keeps working
+  whatever a new click writes.
+- `channel_null: 1` together with `channel_in: [web]` **returns zero**.
+  Ransack ANDs its conditions, so that combination asks for rows whose
+  channel is both null and web.
+
+That last one is the whole difficulty. It does not raise. It renders
+an empty dashboard, which reads as a bug in Janela rather than as an
+impossible question.
+
+## Decision
+
+**A click selects, a modifier click adds, and the selection is a set.**
+
+Following the convention every list in every operating system already
+uses, so that nothing has to be learned:
+
+| Gesture | Result |
+| --- | --- |
+| Click an unselected value | That value alone is selected |
+| Click the only selected value | The dimension is cleared |
+| Click a value while others are selected | That value replaces them |
+| Ctrl or Cmd click | That value is added or removed, the rest stay |
+
+**Janela writes `_in`, and keeps reading `_eq`.** A click always
+produces `q[status_in][]=paid`, one value or five, so there is one
+shape in the controller, one in the view and one in a stored snapshot.
+A hand written or previously shared `_eq` link keeps working, because
+Ransack accepts it and because a URL somebody already sent should not
+stop working to suit us (ADR 005).
+
+**The null group is exclusive within its dimension.** Selecting
+`(none)` clears the other values of that dimension, and selecting a
+value clears `(none)`. The combination is unanswerable, and the honest
+options are to refuse it or to render nothing and let it look broken.
+
+Ransack can express the OR through its `g[]` grouping, and that is
+rejected. It would make the URL unreadable, and ADR 005's grammar is
+built on a URL a person can read and edit. It would also have to be
+understood by every stored snapshot and every hand written link
+forever, to serve a question almost nobody asks.
+
+**The keyboard gets the same two gestures, not a different feature.**
+A value is already a real `<button>` (ADR 018), so Enter is a click
+and **Ctrl or Cmd with Enter is a modifier click**, using the same
+flags on the same event. Nothing new is invented, and nothing has to
+be learned twice.
+
+**Janela binds exactly two keys, and only inside the frame.**
+
+- `Escape` clears the frame's filters.
+- `Enter` and `Space` act on the focused value, as they already do.
+
+No single letter keys. A single letter belongs to the host
+application, to its own shortcuts, and to any text field on the page.
+Janela is a guest in someone else's application and will not take a
+key that could mean something there. A host that wants `c` for clear
+binds its own control to `janela--frame#clear`, which is how the clear
+button already works.
+
+**A chart stays a mouse surface, and the table is the accessible one.**
+A bar is painted pixels with nothing focusable behind it. Rather than
+build a parallel focus model inside a canvas, Janela says plainly that
+the table renders the same data and is operable by keyboard, which is
+what ADR 018 made a table the universal renderer for. A chart
+highlights every selected value rather than one.
+
+## Consequences
+
+- A dashboard can answer "paid and pending", which is the ordinary
+  question this could not previously express.
+- `Query#selected_value` becomes `selected_values` and returns an
+  array. A host that overrode a pane view touches it, so this is a
+  breaking change, and it goes in UPGRADING.md with the version that
+  carries it (ADR 015).
+- A shared link's shape changes from `q[status_eq]=paid` to
+  `q[status_in][]=paid`. Older links keep working, so nothing that was
+  sent stops working.
+- The page URL and every pane `src` now carry repeated parameters. The
+  controller sorts filters so an unchanged `src` is never reloaded, and
+  it must sort the values inside a dimension too or a set will
+  serialise two ways and refetch every pane for nothing.
+- Touch has no modifier key, so a touch user gets replace-only
+  selection. That is a real gap and this ADR does not close it. The
+  answer, when someone needs it, is a control the host can render that
+  makes the next clicks additive, with the modifier as its accelerator
+  rather than the only path. Not built, because the simple thing has
+  not yet failed.
+- Snapshots store filters as JSON, so an array needs nothing new, and
+  a snapshot taken under `_eq` still reads.

data/docs/decisions/INDEX.md

@@ -20,18 +20,23 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 
 | Topic | ADRs |
 |-------|------|
-| **Vision, scope, forkability** | 001, 010 |
+| **Vision, scope, forkability** | 001, 010, 012 |
 | **Open-source & host-decoupling** | 001 |
 | **DSL & query layer** | 002, 006, 007 |
-| **Dependencies** | 002, 003, 004, 006 |
-| **Authorisation** | 002, 003, 004, 009 |
+| **Dependencies** | 002, 003, 004, 006, 017 |
+| **Authorisation** | 002, 003, 004, 009, 017, 019 |
+| **Performance & storage** | 007, 017 |
 | **Cross-filtering & Hotwire** | 003, 004, 005, 008 |
-| **Layouts & views** | 011 |
+| **Layouts & views** | 011, 012, 016, 018 |
+| **CSS & styling** | 016, 018 |
+| **Frames, panes & persistence** | 012, 013, 014, 019 |
+| **Naming rule** | 014 |
 | **JavaScript delivery & charts** | 004, 006 |
 | **Time dimensions** | 006 |
-| **Routes, URLs & naming** | 005, 007, 008, 009, 011 |
+| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013 |
 | **Snapshots & publishing** | 009 |
-| **AI agents & guidance** | 010 |
+| **AI agents & guidance** | 010, 015 |
+| **Releases & upgrades** | 015 |
 | **Security** | 003 |
 | **Testing** | 003 |
 
@@ -50,7 +55,20 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 009 | Snapshots | 2026-09-15 | Accepted |
 | 010 | Agent Guidance Ships, the Agent Waits | 2026-09-15 | Accepted |
 | 011 | Panes Do Not Render in the Host Layout | 2026-09-15 | Accepted |
+| 012 | Frames and Panes Are Data | 2026-09-15 | Accepted |
+| 013 | Naming and Addressing Frames | 2026-09-15 | Accepted |
+| 014 | Corrections Before Frames Are Built | 2026-09-15 | Accepted |
+| 015 | How Breaking Change Is Communicated | 2026-09-16 | Accepted |
+| 016 | The Styling Vocabulary | 2026-09-16 | Accepted |
+| 017 | Janela Owns No Data Store | 2026-09-16 | Accepted |
+| 018 | A Table Is the Universal Renderer | 2026-09-16 | Accepted |
+| 019 | A Created Frame Asks the Host Who Owns It | 2026-09-16 | Accepted |
+| 020 | Formatting Belongs to the Measure | 2026-09-16 | Accepted |
+| 021 | A Check Has a Name, and a Host Can Silence It | 2026-09-16 | Accepted |
+| 022 | A Host's Route Helpers Work Inside the Engine | 2026-09-16 | Accepted |
+| 023 | Vitral Is a Theme, Not the Stylesheet | 2026-09-16 | Accepted |
+| 024 | Selecting More Than One Value | 2026-09-16 | Accepted |
 
 ## Next number
 
-Next ADR: 012
+Next ADR: 025

data/docs/multi-tenancy.md

@@ -0,0 +1,175 @@
+# Fitting Janela into a multi tenant application
+
+Janela holds no tenancy of its own. There is no tenant setting, no
+default scope of ours on your models, and nothing to configure. The
+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 owns a frame being created? | `janela_frame_owner` on the same controller | Nothing: a nil owner |
+
+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
+rather than being configured: ownership is per-request state, and a
+setting cannot hold it.
+
+## What goes through your scope
+
+Everything. There is no path through the engine that reads a record
+without asking first:
+
+- The index of frames, and each frame page.
+- Every editing action on a frame or a pane, so another tenant's frame
+  is a 404 to rename or delete as much as to read.
+- Every pane's own query, on Janela's pages and inline in yours. The
+  measure is calculated over `policy_scope(Order)`, not over `Order`.
+- An ad hoc pane URL, which is the same query by another route.
+- A snapshot, read through `policy_scope(Janela::Snapshot)`.
+
+A pane rendered inline in your own page runs in your request, so the
+same scope applies there as in the engine's controllers. Nothing is
+calculated in a background context where the current tenant would have
+gone missing.
+
+## With Pundit
+
+Write a policy for Janela's own record. The class name is namespaced,
+because the model is:
+
+```ruby
+# app/policies/janela/frame_policy.rb
+module Janela
+  class FramePolicy < ApplicationPolicy
+    class Scope < ApplicationPolicy::Scope
+      def resolve
+        scope.where(owner: Current.account)
+      end
+    end
+  end
+end
+```
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Pundit::Authorization
+
+  private
+    def janela_frame_owner
+      Current.account
+    end
+end
+```
+
+Your own models keep the policies they already have. Janela calls
+`policy_scope(Order)` and gets whatever `OrderPolicy::Scope` returns.
+
+## With acts_as_tenant
+
+Your own models are already scoped, so the only thing Janela needs
+told about is its own tables. Define `policy_scope` as the adapter:
+
+```ruby
+class ApplicationController < ActionController::Base
+  set_current_tenant_through_filter
+  before_action :set_tenant
+
+  private
+    def policy_scope(model)
+      case model.name
+      when "Janela::Frame" then model.where(owner: ActsAsTenant.current_tenant)
+      else model.all # acts_as_tenant has already scoped your own models
+      end
+    end
+
+    def janela_frame_owner
+      ActsAsTenant.current_tenant
+    end
+end
+```
+
+## With CanCanCan, or with your own
+
+The same adapter, pointed at whatever you use:
+
+```ruby
+def policy_scope(model)
+  model.accessible_by(current_ability)
+end
+```
+
+Janela never asks how the answer was arrived at. A method that takes a
+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.
+
+## What owns a frame
+
+`Janela::Frame belongs_to :owner, polymorphic: true, optional: true`.
+It can point at an account, a team, a user or anything else you scope
+by, and Janela reads nothing from it. It exists so your scope has a
+column.
+
+Return the tenant from `janela_frame_owner` and the engine assigns it
+to a frame it creates. Skip that method while your scope filters by
+owner and the analyst's new dashboard is saved with no owner, then
+hidden by your own policy the instant it is saved. It looks like the
+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
+
+`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:
+
+- 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.
+
+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).
+
+## Proving your wiring
+
+Run the doctor first. It reads your application and reports the traps
+that are visible from outside a request:
+
+```bash
+bin/rails janela:doctor
+```
+
+Then write the test that matters, which is the one that fails if a
+scope is ever loosened. Create a frame as one tenant and ask for it as
+another:
+
+```ruby
+test "another tenant's frame is a 404" do
+  frame = Janela::Frame.create!(name: "Theirs", owner: accounts(:acme))
+
+  sign_in users(:globex_analyst)
+  get janela.frame_path(frame)
+
+  assert_response :not_found
+end
+```
+
+This repository's dummy application is a worked example of all of the
+above, in
+[test/dummy/app/controllers/application_controller.rb](https://github.com/retail-tasker/janela/blob/main/test/dummy/app/controllers/application_controller.rb),
+scoped by a `?tenant=` parameter standing in for a session.
+
+## What Janela will never do
+
+Add a tenant filter of its own. Your scope is the only one, so there
+is nothing to double filter and nothing that looks enforced while
+being unenforceable. Janela can be handed any relation through `on:`,
+so a guarantee made here would be a guarantee it cannot keep.