janela 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e79c9733a355bce01c020c4dd98b34599167b88aa86ecbd20ffe8fdd2ea8842b
-  data.tar.gz: da0d442d1607b6347e5851ba136984da8009eac44ac8e453e2f8024a927016e0
+  metadata.gz: 2fd31f19d1b100c312826e8077aefc291873c0cc153410aa9c53199dcdf5ba18
+  data.tar.gz: ec551cd6c640de00e6ba13266ae2920945f68ad4a576c344e157830c9442563d
 SHA512:
-  metadata.gz: 5ac5148b2676651bfdf2fabc046b960c475c3abd93ee4797b80cb869c733575933ce863360c455511cd12fb4b64c0a524ac5c21578ef271a34b4070e1df6ce21
-  data.tar.gz: 4898a621a1ed7312b8a13f5d42908bfd0e8ec10360984318f090b0b7c12258a390bd9025c2112f7a16d9dfe033d0c403225c4e6659cdf18548a413a03663328d
+  metadata.gz: 692add30c86d3633d3144b6fe1fbb138246762e974f618430db2f290f1980a91bb55441104b2a1d183e67e6e16ca3ffd75aaab8d8e0156d77444950bc388dc21
+  data.tar.gz: 794ac1f1352ee3e30357d8ef2ff7bd2d0692895f932b3aec5d3acc5df55ab21e592397f111df855a120c547eea271273807e870d988a602a49c6575987ddaa9a

data/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-09-20
+
+### Added
+
+- `janela_pane` takes an optional `id:`, naming the pane's frame instead of fingerprinting it from the query. A host that reconfigures a pane in place, a renderer toggle, a granularity switcher, a "show top 20" link, keeps one stable frame for Turbo to reconcile into rather than a different id every time the query changes. Without `id:`, nothing changes.
+- A `janela--frame:repoint` event, dispatched on a pane or anything inside one with `detail: { url }`, sends that pane to a different query. `janela_frame` listens for it, so nothing has to be wired up and nothing has to reach for the controller. This is how a host changes what a pane shows: a pane's `src` belongs to Turbo, which writes it back whenever a response lands, so Janela keeps its own record of what was asked for and cancels anything else, a host's `src` write included. The event says the query and nothing about filters, because the frame reapplies whatever it is currently filtered to. `data-janela-asked` and `data-janela-src` are how the frame remembers, not an interface, and a host reading or writing them is relying on something that may change (ADR 030, #43).
+- A subclass inherits the dashboard its parent declared and is addressable on its own route key, with nothing to declare: `class WholesaleOrder < Order; end` answers at `/dashboards/wholesale_orders/revenue` and totals its own rows, because the query runs on the subclass and ActiveRecord adds the type condition itself. This is a change of posture, since only a model that declared a `janela` block was addressable before, and it is one of URL surface rather than data surface: an STI subclass is a subset of rows its parent already totals, read through the same scope as everything else. A subclass that wants a different dashboard declares its own block, which replaces its parent's. The cost is noise: a family of a dozen STI types is a dozen entries in `Janela.definitions` and in the form that offers a choice of model, where a host expected one (ADR 031, #11).
+
+### Fixed
+
+- A subclass came out half declared: it inherited the Ransack allowlist, because Janela defined that as singleton methods on the parent and singleton methods inherit, while `.janela` returned nil and nothing was registered. A host calling `WholesaleOrder.ransack(...)` in its own code was filtering on dimensions no definition behind that class declared. The allowlist Janela generates is now the allowlist of the definition a class reports, whichever class declared it, and a subclass declaring its own block no longer replaces an allowlist the host wrote on a parent (ADR 031, #11).
+- Pointing a pane's turbo frame at a URL differing only in `limit`, `granularity` or `as` left the frame stale with no error. The response was fingerprinted from the query, so it wore an id the frame never had and Turbo had nothing to reconcile it against. A pane rendered into a turbo frame request now answers to the frame that asked, using the id Turbo already sends in its `Turbo-Frame` header, rather than deriving one again from the query. A pane rendered any other way keeps deriving its own id as before. The demo's gallery config controller no longer fetches and swaps a pane's frame by hand: it names each configurable pane and asks the frame to repoint it, which is 22 lines shorter than where it started (ADR 029, #42).
+- Reconfiguring a pane while the frame was filtered refetched that pane unfiltered, so it showed numbers for a filter state nobody was in while every pane beside it stayed filtered, and nothing on the page said so. Reapplying the frame's current filters is part of repointing now rather than something a caller has to remember, which is what the demo's gallery control got wrong: change a pane's granularity there with a value selected and it went back to showing the year (ADR 003, ADR 030, #43).
+
 ## [0.5.0] - 2026-09-18
 
 ### Added
@@ -138,6 +152,7 @@ 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.6.0]: https://github.com/retail-tasker/janela/releases/tag/v0.6.0
 [0.5.0]: https://github.com/retail-tasker/janela/releases/tag/v0.5.0
 [0.4.1]: https://github.com/retail-tasker/janela/releases/tag/v0.4.1
 [0.4.0]: https://github.com/retail-tasker/janela/releases/tag/v0.4.0

data/README.md

@@ -27,7 +27,7 @@ Janela is an alpha on [rubygems.org](https://rubygems.org/gems/janela). It has t
 
 ```ruby
 # Gemfile
-gem "janela", "~> 0.5"
+gem "janela", "~> 0.6"
 ```
 
 ```ruby
@@ -129,6 +129,21 @@ 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.
 
+### A subclass inherits
+
+Declaring is what a family of classes does once. A subclass of a model with a `janela` block has the same measures and dimensions and its own pane URLs, with nothing to declare:
+
+```ruby
+class WholesaleOrder < Order
+end
+```
+
+`/dashboards/wholesale_orders/revenue` totals the wholesale orders and `/dashboards/orders/revenue` totals all of them. Janela knows nothing about single table inheritance: the query runs on the subclass and ActiveRecord adds the type condition itself. A subclass is read through your scope like any other model, so if you authorise per class, the subclass needs an answer of its own.
+
+A subclass that wants a different dashboard declares its own `janela` block, which replaces its parent's rather than adding to it. Either way, the Ransack allowlist Janela generates is the allowlist of the definition that class reports, so the two cannot disagree.
+
+Every subclass is a definition, so a model with a dozen STI types offers a dozen of them wherever Janela lists what it can draw, such as the form for adding a pane (ADR 031).
+
 ### How numbers read
 
 A measure says what its own number means, and every renderer asks it, so a table cell, a single value and a chart tooltip cannot disagree (ADR 020):
@@ -194,6 +209,23 @@ Compose panes on any page. Each pane is a Turbo Frame; clicking a value in one r
 
 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.
 
+**Reconfiguring a pane in place**, a renderer toggle, a granularity switcher, a "show top 20" control, takes two things: name the pane with `id:`, then ask the frame to repoint it.
+
+```erb
+<%= janela_pane Order, :revenue, by: :status, as: :bar, id: "revenue-by-status" %>
+```
+
+```js
+const pane = document.getElementById("revenue-by-status")
+pane.dispatchEvent(new CustomEvent("janela--frame:repoint", {
+  bubbles: true, detail: { url: "/dashboards/orders/revenue/status?limit=20" }
+}))
+```
+
+`id:` gives the frame a name you chose rather than a fingerprint of its own query, which would move every time that query changed and leave Turbo nothing to reconcile into. That is necessary and it is not enough on its own: a pane's `src` belongs to Turbo, which writes it back whenever a response lands, so writing `src` yourself has the request cancelled and the pane put back where it was, with no error and the old numbers still on screen. The event is how you say what you want instead. `janela_frame` listens for it, so anything inside a frame can dispatch it, from a Stimulus controller (`this.dispatch("repoint", { prefix: "janela--frame", target: pane, detail: { url } })`) or from plain JavaScript as above.
+
+Say the query and nothing about filters: the frame reapplies whatever it is currently filtered to, so a repointed pane still agrees with the panes beside it, and any `q[...]` on the URL you pass is dropped in favour of them (ADR 029, ADR 030).
+
 ### Frames
 
 A dashboard does not have to be written in ERB. A frame is a record, so the person who decides which panes a dashboard has and how wide each one is does not need a deploy to change it (ADR 012):
@@ -296,6 +328,8 @@ Every pane has its own URL under the mount, and a Turbo Frame in a dashboard loa
 
 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 with its filters applied, so a filtered pane is a link you can send someone. ADR 005 has the grammar, ADR 011 the layout it renders in.
 
+**Sending an existing pane to one of these URLs takes both halves of Reconfiguring a pane in place, above: name it with `id:`, and repoint it through the frame.** Without the `id:` the response wears an id the frame never had and Turbo has nothing to reconcile, so the pane keeps its old numbers with no error at all. Without the event, `src` is not yours to write and the request is cancelled, with the same silence (ADR 029, ADR 030).
+
 ### What Janela can draw
 
 `Janela.renderers`, `Janela.granularities` and `Janela.offered_limits` answer what a pane can be drawn as, without reaching into `Janela::Query::RENDERERS`, `Janela::Dimension::GRANULARITIES` or `Janela::Pane::OFFERED_LIMITS`. `Janela.definitions` answers the other half: every model that declares a `janela` block, with its own measures and dimensions. A gallery of every renderer, live against your own data, is a page you build from those four calls and `janela_pane`, not one the engine serves (ADR 026, ADR 027):
@@ -450,7 +484,7 @@ Deliberately out of scope: natural-language query, a separate data warehouse, a
 
 ## Status
 
-**v0.5.0 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering with multi-selection, bar and line charts, pane URLs, shareable dashboard URLs, snapshots, database-backed frames, the engine's own pages for reading and editing them and the optional vitral theme work and are covered by unit and real-browser tests. Not yet built: a visual editor, drill-down on time panes, other chart types. Open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
+**v0.6.0 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering with multi-selection, bar and line charts, pane URLs, shareable dashboard URLs, snapshots, database-backed frames, STI subclasses, the engine's own pages for reading and editing them and the optional vitral theme work and are covered by unit and real-browser tests. Not yet built: a visual editor, drill-down on time panes, other chart types. Open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
 
 ## Development
 

data/UPGRADING.md

@@ -12,6 +12,60 @@ bin/rails janela:doctor
 
 It reads your application and lists what still needs changing.
 
+## 0.5.0 to 0.6.0
+
+How single table inheritance is handled changed (ADR 031). Nothing here
+applies unless your application has STI subclasses under a model that
+declares a `janela` block. If it does not, upgrade and read no further.
+
+**1. A named subclass is now registered and addressable.**
+
+Before, only a class with its own `janela` block answered at a URL. Now
+every named subclass of one does, on its own route key:
+
+```
+  /insights/orders/revenue              as before
++ /insights/wholesale_orders/revenue    new in 0.6.0
+```
+
+The numbers are the subclass's own rows, because the query runs on the
+subclass and ActiveRecord adds the type condition itself. There is
+nothing to declare and nothing to register.
+
+Scoping is unchanged: a subclass reads through `janela_scope` like every
+other model, so an application authorising with `policy_scope` already
+covers the new addresses. One that instead gates on the request path now
+has paths it has not listed, and should list them.
+
+**2. `Janela.definitions` returns one entry per subclass.**
+
+A family of a dozen STI types is a dozen entries, where a form offering a
+choice of model previously showed one. If you want only the classes that
+declared a dashboard:
+
+```ruby
+- Janela.definitions
++ Janela.definitions.select { |definition| definition.model.base_class == definition.model }
+```
+
+**3. A subclass's Ransack allowlist now matches the dashboard it reports.**
+
+This was wrong before rather than merely different. A subclass inherited
+the allowlist Janela generated on its parent, because those are singleton
+methods and singleton methods inherit, while `.janela` returned nil and
+nothing was registered. So `WholesaleOrder.ransack(...)` in your own code
+filtered on dimensions no definition behind that class had declared. The
+allowlist is now the allowlist of the definition a class reports,
+whichever class declared it.
+
+Janela also no longer replaces an allowlist you wrote yourself on a
+parent class when a subclass declares its own block.
+
+**What did not change.** A model that declares its own `janela` block, an
+application with no STI, every `janela_frame` and `janela_pane` call you
+have already written, and every filter already in a URL. An anonymous
+subclass is still not registered, having no route key to be addressed by.
+
 ## 0.4.1 to 0.5.0
 
 A filter is now bound to what kind of dimension it names (ADR 025). Most

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

@@ -102,6 +102,34 @@ export default class extends Controller {
     if (Object.keys(this.filtersValue).length) this.filtersValue = {}
   }
 
+  // A host changes what a pane shows by asking here, and never by writing
+  // src or one of the dataset records below. Turbo writes src back onto a
+  // frame when a response lands, so src does not say what was asked for and
+  // this controller keeps its own record instead (#33); a host writing that
+  // record by hand has to write two attributes in the right order and
+  // reapply the frame's filters itself, and only this controller knows what
+  // those filters are. Getting it wrong is silent: the pane shows numbers
+  // for a filter state nobody is in, beside panes that are still filtered
+  // (ADR 003, ADR 030, #43).
+  //
+  // Dispatched on the pane, or on anything inside it, with the query to go
+  // to. Filters are the frame's, so a caller says nothing about them:
+  //
+  //   pane.dispatchEvent(new CustomEvent("janela--frame:repoint",
+  //     { bubbles: true, detail: { url: "/dashboards/orders/revenue/status?limit=5" } }))
+  repoint(event) {
+    const pane = this.paneTargets.find((each) => each.contains(event.target))
+    const query = new URL(event.detail.url, window.location.origin)
+    this.stripFilters(query)
+
+    // The query without filters first, since it is what this pane's URL is
+    // rebuilt from on the next click as well as on the line below.
+    pane.dataset.janelaSrc = query.pathname + query.search
+    const url = this.urlFor(pane)
+    pane.dataset.janelaAsked = url.href
+    pane.src = url.href
+  }
+
   // Whatever is selected for one key, as a set of strings. A filter arrives as
   // an array from a click and as a string from a hand written _eq link.
   valuesFor(filters, key) {
@@ -160,9 +188,7 @@ export default class extends Controller {
   // 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.stripFilters(url)
     this.writeFilters(url)
     if (url.href !== window.location.href) history.replaceState(history.state, "", url)
   }
@@ -173,6 +199,15 @@ export default class extends Controller {
     return url
   }
 
+  // The filters on a URL are Janela's to write, so whatever is already there
+  // comes off before the current selection goes on: a page URL carrying the
+  // filters a page was opened with, or a query a host handed to repoint.
+  stripFilters(url) {
+    for (const key of [ ...url.searchParams.keys() ]) {
+      if (key.startsWith("q[")) url.searchParams.delete(key)
+    }
+  }
+
   // Sorted, keys and values both, so the browser serialises a selection the
   // same way every time and an unchanged src is never reloaded.
   writeFilters(url) {

data/app/helpers/janela/frames_helper.rb

@@ -9,16 +9,20 @@ module Janela
     def janela_frame(frame = nil, charts: true, &block)
       return render("janela/frames/frame", frame: frame, filters: janela_page_filters, charts: charts) if frame
 
-      tag.div(data: { controller: "janela--frame", action: "keydown.esc->janela--frame#clear",
+      tag.div(data: { controller: "janela--frame", action: janela_frame_actions,
                       janela__frame_filters_value: janela_page_filters.to_json }, &block)
     end
 
-    def janela_pane(model, measure, by: nil, as: :table, granularity: nil, limit: nil)
+    # id: names the pane's frame instead of fingerprinting it from the query,
+    # so a host that changes the query in place (a renderer, granularity or
+    # limit control) keeps one stable frame for Turbo to reconcile into
+    # rather than a different id every time the query changes (ADR 029).
+    def janela_pane(model, measure, by: nil, as: :table, granularity: nil, limit: nil, id: 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 Query.turbo_frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit),
+      turbo_frame_tag id || Query.turbo_frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit),
         src: src,
         loading: :lazy,
         data: { janela__frame_target: "pane", janela_src: base }
@@ -35,6 +39,13 @@ module Janela
     end
 
     private
+      # Wired once per frame, so a host asks a pane to go to a different query
+      # by dispatching an event from anywhere inside rather than by reaching
+      # for the controller itself (ADR 030).
+      def janela_frame_actions
+        "keydown.esc->janela--frame#clear janela--frame:repoint->janela--frame#repoint"
+      end
+
       def janela_frame_classes(frame)
         [ "janela-frame", "janela-cols-#{frame.columns}", "janela-gap-#{frame.gap}" ]
       end

data/app/views/janela/frames/_frame.html.erb

@@ -1,5 +1,5 @@
 <%= tag.div class: janela_frame_classes(frame),
-            data: { controller: "janela--frame", action: "keydown.esc->janela--frame#clear",
+            data: { controller: "janela--frame", action: janela_frame_actions,
                     janela__frame_filters_value: filters.to_json } do %>
   <%= render partial: "janela/frames/pane", collection: frame.panes, as: :pane, locals: { filters: filters, charts: charts } %>
 <% end %>

data/app/views/janela/queries/show.html.erb

@@ -1,4 +1,9 @@
+<%# A pane rendered into a turbo frame request answers to the frame that
+    asked, using the id Turbo already sends in its Turbo-Frame header,
+    rather than fingerprinting the id again from a query that may have just
+    changed underneath it (ADR 029). Rendered any other way, it still
+    derives its own id. %>
 <% content_for :title, @query.title %>
-<%= turbo_frame_tag @query.turbo_frame_id do %>
+<%= turbo_frame_tag turbo_frame_request_id.presence || @query.turbo_frame_id do %>
   <%= render "janela/queries/query", query: @query, result: @result %>
 <% end %>

data/docs/decisions/029-a-panes-frame-is-identified-by-who-it-is.md

@@ -0,0 +1,112 @@
+---
+Date: 2026-09-18
+Status: Accepted
+Related: ADR 003, ADR 005, ADR 012, ADR 014, ADR 024
+Superseded in part by: ADR 030
+Triggers:
+  - changing how a pane's turbo frame is identified
+  - adding a parameter to a pane URL
+  - a host wanting a control over a pane's own settings
+  - a frame that does not update when it should
+Topics: cross-filtering, panes, urls, host-integration
+---
+
+# ADR 029: A Pane's Frame Is Identified by Who It Is, Not by What It Shows
+
+## Context
+
+Issue #42 found that pointing a pane's turbo frame at a URL differing only
+in `limit`, `granularity` or `as` makes Turbo fetch the response and then
+silently do nothing: no render, no `frame-missing`, no console error, the
+frame left showing the old numbers forever. Measured in a browser, not
+inferred.
+
+The cause is that `Query.turbo_frame_id` builds the id out of the query
+itself, renderer, granularity and limit included, so the response comes
+back wearing a different id from the frame that asked for it. Turbo has
+nothing to reconcile and gives up quietly.
+
+**The project has already solved this once, in the half that does not have
+the bug.** A pane that is a record uses `Pane#turbo_frame_id`, which is
+`janela_pane_#{id}`, and the comment on it says exactly why:
+
+> The DOM id is the row, not the query it runs: two rows in one frame may
+> show the same measure by the same dimension, and a fingerprint of the
+> query would give them the same turbo frame for Turbo to replace.
+
+That is ADR 014's reasoning, and it is right. A record-backed pane can
+change its renderer, its granularity and its limit all day and its frame
+id never moves, because the id says who the pane is rather than what it
+is currently showing.
+
+The helper path has no row to point at, so it fingerprints the query
+instead. The fingerprint is not arbitrary: without it, two `janela_pane`
+calls for the same measure by the same dimension would collide, and one
+would replace the other. So the fingerprint solves a real problem and
+creates this one.
+
+The reason this has not bitten the library itself is worth stating: a
+click changes filters, and filters are deliberately not in the id, so
+every navigation Janela performs keeps the id stable. It is only a host
+reaching for the URL's other documented parameters that falls in, and
+what it gets is stale numbers with no error, which is the worst failure
+this library has (ADR 003).
+
+## Decision
+
+**`janela_pane` accepts an `id:`, and a pane given one is identified by
+it rather than by a fingerprint of its query.**
+
+1. The fingerprint stays the default. It is correct for the common case,
+   a page of unlike panes with no controls over them, and it is what
+   keeps two alike panes apart.
+2. A host that wants to change a pane's settings in place names that
+   frame itself. The id is then stable by construction, because it comes
+   from the host rather than from the query, and Turbo reconciles
+   normally. This is the same move ADR 012 made for a record-backed pane,
+   made available to a pane that is not a record.
+3. The response wears the id the frame asked for rather than one derived
+   again from the query. This needs no new surface at all: Turbo already
+   sends the requesting frame's id in the `Turbo-Frame` header, and
+   turbo-rails exposes it as `turbo_frame_request_id`. So a pane rendered
+   into a frame request answers to the frame that asked, and a pane
+   rendered any other way keeps deriving its own id as it does now. The
+   pane URL does not grow a parameter, which was the first thing this
+   decision reached for and did not need.
+4. The failure is documented rather than left to be discovered. A host
+   that changes a pane's URL without naming its frame gets the silent
+   staleness described above, and the README says so where it describes
+   the pane URL's parameters.
+
+## What this turns down
+
+**Taking renderer, granularity and limit out of the fingerprint.** It
+would fix #42 and reintroduce the collision ADR 014 avoided: the gallery
+renders the same measure by the same dimension as a bar and as a line on
+one page, and those two must not share a frame. The fingerprint is doing
+real work.
+
+**Leaving it to every host to fetch and swap the frame themselves**, which
+is what the demo's gallery does today and what proved the diagnosis. It
+works, and it asks each host to write the same Stimulus controller and to
+know a thing about Turbo's id matching that nothing told them. ADR 001
+says ship the load-bearing 5%: a frame that updates when its URL changes
+is inside that, and a host reimplementing frame reconciliation is not.
+(Superseded in part by ADR 030: a frame does not update when its URL
+changes, because `src` is not a channel a host can speak through. What is
+inside the 5% is a pane that goes where it is asked to, which is the same
+thing said correctly.)
+
+## Consequences
+
+`janela_pane` grows one optional keyword argument, and a host that never
+passes it sees no change at all. The demo's gallery control becomes
+smaller, since the frame can be navigated rather than swapped by hand,
+and that is the check on whether this decision is right: if the control
+does not get simpler, the decision was wrong.
+
+Two alike panes given the same `id` by a host would collide, which the
+fingerprint prevented automatically. That is the cost of letting a host
+name things, it is the same cost a host already carries for every DOM id
+it writes, and the doctor is the place to notice it if it turns out to
+happen.

data/docs/decisions/030-a-panes-src-belongs-to-turbo.md

@@ -0,0 +1,93 @@
+---
+Date: 2026-09-18
+Status: Accepted
+Related: ADR 003, ADR 005, ADR 024, ADR 029
+Supersedes: part of ADR 029
+Triggers:
+  - a host changing what a pane shows from JavaScript
+  - writing to a turbo frame's src from anything but Turbo
+  - adding a data attribute the frame controller reads
+  - anything that would reintroduce reading intent out of the DOM
+Topics: cross-filtering, panes, host-integration, javascript
+---
+
+# ADR 030: A Pane's src Belongs to Turbo, So a Host Talks to the Frame
+
+## Context
+
+ADR 029 gave a host a way to name a pane's frame so it could be
+reconfigured in place, and said that "a frame that updates when its URL
+changes is inside" the load-bearing core. Building it showed that is not
+true, and the reason is a decision this project already made.
+
+#33 established that a frame's `src` does not describe what that frame
+is showing. Turbo writes `src` back onto a frame when a response lands,
+including a late one for a request that has since been superseded. So
+`janela--frame` keeps its own record of what was asked for and reverts
+anything that does not match it:
+
+> The request for what Janela last asked for wins, and any other is
+> reverted. What was asked for is the only honest rule (#33).
+
+That rule is right, and its consequence was not drawn at the time: if
+the controller's own record is the only trustworthy statement of intent,
+then `src` is no longer a channel a host can speak through. A host that
+follows ADR 029, names a pane and writes `frame.src`, has its request
+aborted and the frame put back, with no error and the old numbers still
+on screen. That is the failure #42 was about, reached by following the
+instructions written to fix #42.
+
+There is no way to tell a host's `src` write from Turbo's. Any attempt,
+a mutation observer, a flag, a heuristic on the attribute, re-infers
+intent from the DOM, which is exactly what #33 removed because it
+produced wrong numbers.
+
+And the record is not one attribute. A pane also carries the base URL
+the controller rebuilds from on the next click, so a host writing the
+record by hand has to write two attributes in the right order, and
+reapply the frame's current filters itself. Only the frame controller
+knows those filters. The demo's own gallery control got that wrong:
+reconfigure a pane while a filter is active and it refetches unfiltered
+while every pane beside it stays filtered (#43).
+
+## Decision
+
+**A host changes what a pane shows by asking `janela--frame`, and never
+by writing `src` or a data attribute.**
+
+The controller already does this for itself when the frame's filters
+change. Making that reachable is extraction rather than new surface: one
+way to ask a pane to go to a different query, which records what was
+asked, reapplies the frame's filters and sets `src` in the order the
+guard expects.
+
+Three things follow.
+
+1. **The data attributes are private.** `janelaAsked` and `janelaSrc` are
+   how the controller remembers, not an interface. A host that writes
+   them is relying on something that may change.
+2. **A reconfigured pane stays cross-filtered.** Reapplying the frame's
+   current filters is part of repointing, not something a caller
+   remembers, because forgetting it shows numbers for the wrong filter
+   state and says nothing (ADR 003).
+3. **`id:` is still necessary.** ADR 029 stands: without a stable frame
+   id there is nothing to repoint. It is necessary and it was not
+   sufficient, which is what this records.
+
+## Consequences
+
+ADR 029's claim that a frame updates when its URL changes is untrue as
+written, and this supersedes that sentence rather than the decision. The
+`id:` keyword and answering a frame request with the id Turbo sent are
+both correct and stay.
+
+A host reconfiguring a pane writes one call instead of three writes it
+was never told about, and gets the filter behaviour right by default
+rather than by knowing to. The demo's gallery control is the check, the
+same way it was for ADR 029: it should get smaller again, and its filter
+bug should disappear rather than be fixed separately.
+
+The cost is one public method on a Stimulus controller, which is a
+surface this project did not have before. It earns itself by removing a
+class of silent wrongness rather than by adding capability, which is the
+kind of addition ADR 001 leaves room for.

data/docs/decisions/031-a-subclass-inherits-the-dashboard.md

@@ -0,0 +1,110 @@
+---
+Date: 2026-09-19
+Status: Accepted
+Related: ADR 002, ADR 013, ADR 014, ADR 025, ADR 028
+Triggers:
+  - subclassing a model that declares a janela block
+  - changing what is addressable over HTTP
+  - changing how the registry is populated
+  - adding to the Ransack allowlist a model gets from Janela
+Topics: configuration, urls, security, scope
+---
+
+# ADR 031: A Subclass Inherits the Dashboard Its Parent Declared
+
+## Context
+
+`janela` stores its definition in a plain class instance variable, so a
+subclass of a model that declares one gets `nil` from `.janela` and is
+not in the registry (#11).
+
+Reproducing it found something the issue did not say. The subclass does
+inherit the Ransack allowlist, because
+`define_janela_ransack_allowlist` defines singleton methods on the
+parent and singleton methods inherit down the singleton class chain:
+
+```
+subclass .janela:      nil
+subclass ransackable:  ["status", "channel", "placed_on"]
+```
+
+So a subclass is already half declared: filterable on the parent's
+dimensions, with no definition behind it saying what those dimensions
+are. Neither half was decided. One was written and the other happened.
+
+The instinct is to walk the ancestors in `janela`, which fixes `.janela`
+and does not fix the bug. What a host wants from an STI subclass is a
+dashboard of it, and that needs the subclass registered:
+
+```ruby
+janela_pane PaidOrder, :revenue   # src is /paid_orders/revenue
+```
+
+An inherited definition with no registration renders that pane and then
+404s it. That is worse than today, because today the failure is loud at
+the call site and that one is a dead pane on a page.
+
+So the question is not whether the definition inherits. It is whether
+being a subclass makes a model addressable, and `lib/janela.rb` states
+the current answer plainly:
+
+> Only models that declare a janela block are addressable over HTTP
+
+## Decision
+
+**A subclass inherits its parent's definition and is addressable on its
+own route key. Declaring is what a family of classes does once.**
+
+The argument that settles it is about data rather than URLs. An STI
+subclass is a subset of its parent's rows. If the parent is addressable,
+the subclass reveals no row the parent does not already total, and it is
+read through the same host scope as everything else (ADR 014). So this
+adds URL surface and no data surface, which is a much smaller thing than
+the rule above makes it sound.
+
+Three things follow.
+
+1. **The halves agree.** The definition inherits, the registration
+   inherits, and the Ransack allowlist keeps inheriting as it already
+   does. A subclass is either a Janela model or it is not, rather than
+   being one in the part nobody chose.
+2. **STI scoping is ActiveRecord's, not Janela's.** A definition whose
+   model is the subclass runs its query on that class and ActiveRecord
+   adds the `type` condition itself. Janela learns nothing about STI,
+   which is the right amount for it to know.
+3. **A subclass may still declare its own block**, and then it has its
+   own definition rather than its parent's, which is how a subclass says
+   its dashboard is different.
+
+Registration cannot happen where declaration happens, because the
+subclass does not exist when the parent declares. It happens when the
+subclass is created.
+
+## What this turns down
+
+**Inheriting nothing, and documenting that each subclass declares its
+own.** It is the most conservative reading and it asks a host with five
+STI types to retype the same measures and dimensions five times. ADR 002
+spent Ransack's familiarity on the host deliberately; spending their
+typing on a class hierarchy Rails already models is a worse trade.
+
+**Inheriting the definition without registering.** Rejected above: a
+helper that renders a pane which cannot load.
+
+## Consequences
+
+The honest cost is not security, it is noise. `Janela.definitions` feeds
+the form that offers a choice of model when an analyst adds a pane
+(ADR 012), and a host with a dozen STI types will see a dozen entries
+where it expected one. That is a real cost and it is the thing to watch:
+if it becomes the complaint, the answer is a way for a family to say
+which of its classes are worth offering, and that is a later decision
+rather than a setting invented now.
+
+The check on whether this decision is right is what a host writes. If
+adding a dashboard for an STI subclass still takes anything beyond
+creating the class, the decision did not deliver.
+
+The demo has no STI model, so proving this takes one: a `type` column on
+a table and a subclass in the dummy. That is a fixture, and adding it is
+part of the work rather than a reason to avoid it.

data/docs/decisions/INDEX.md

@@ -29,7 +29,7 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | **Cross-filtering & Hotwire** | 003, 004, 005, 008, 024, 025 |
 | **Layouts & views** | 011, 012, 016, 018, 020, 027 |
 | **CSS & styling** | 016, 018, 023, 026, 027 |
-| **Frames, panes & persistence** | 012, 013, 014, 019 |
+| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030 |
 | **Naming rule** | 014, 023 |
 | **JavaScript delivery & charts** | 004, 006, 026 |
 | **Time dimensions** | 006, 025 |
@@ -38,7 +38,7 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | **AI agents & guidance** | 010, 015, 021 |
 | **Releases & upgrades** | 015, 021 |
 | **Accessibility & keyboard** | 024 |
-| **Security** | 003, 025, 028 |
+| **Security** | 003, 025, 028, 031 |
 | **Testing** | 003 |
 
 ## Chronological
@@ -73,7 +73,10 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 026 | A Renderer Is the Seam, and HTML Comes First | 2026-09-18 | Accepted |
 | 027 | The Gallery Is a Host Page, Built from the Gem's Helpers | 2026-09-18 | Accepted |
 | 028 | The Predicate List ADR 025 Named Was Not Quite Right | 2026-09-18 | Accepted |
+| 029 | A Pane's Frame Is Identified by Who It Is, Not by What It Shows | 2026-09-18 | Accepted |
+| 030 | A Pane's src Belongs to Turbo, So a Host Talks to the Frame | 2026-09-18 | Accepted |
+| 031 | A Subclass Inherits the Dashboard Its Parent Declared | 2026-09-19 | Accepted |
 
 ## Next number
 
-Next ADR: 029
+Next ADR: 032

data/lib/janela/definition.rb

@@ -6,10 +6,20 @@ module Janela
 
     attr_reader :model, :measures, :dimensions
 
-    def initialize(model)
+    def initialize(model, &block)
       @model = model
       @measures = {}
       @dimensions = {}
+      @block = block
+      instance_eval(&block) if block
+    end
+
+    # The same declaration read against another model, which is how a subclass
+    # inherits a dashboard: its measures and dimensions are its parent's, and
+    # 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)
     end
 
     def measure(name, **aggregate)

data/lib/janela/model.rb

@@ -1,25 +1,61 @@
 module Janela
   module Model
+    # Dimensions are the only things Janela filters on, so they are the
+    # Ransack allowlist. This asks for the definition when it is called rather
+    # than closing over one, so a subclass answers with the definition it
+    # reports, whether that is its parent's or one it declared itself. The two
+    # halves cannot then disagree, which is what they did before ADR 031: a
+    # subclass inherited this list and reported no definition behind it.
+    module RansackAllowlist
+      def ransackable_attributes(_auth_object = nil)
+        janela.ransackable_attributes
+      end
+
+      def ransackable_associations(_auth_object = nil)
+        janela.ransackable_associations
+      end
+    end
+
     def janela(&block)
-      return @janela_definition unless block
+      return @janela_definition ||= inherited_janela_definition unless block
 
-      @janela_definition = Definition.new(self)
-      @janela_definition.instance_eval(&block)
+      @janela_definition = Definition.new(self, &block)
       define_janela_ransack_allowlist
       Janela.register(self)
       @janela_definition
     end
 
+    # A subclass cannot be registered where its parent declares, because it
+    # does not exist yet, so it registers as it is created (ADR 031). An
+    # anonymous class has no route key to be addressed by; naming it is the
+    # host's move and declaring on it is the host's other one.
+    def inherited(subclass)
+      super
+      Janela.register_subclass(subclass) if subclass.name && janela
+    end
+
     private
-      # Dimensions are the only things Janela filters on, so they are the
-      # Ransack allowlist. A model that already declares its own allowlist
-      # keeps it.
+      # What a subclass inherits is the declaration, not the definition
+      # object. A definition holds the model it queries, so a subclass handed
+      # its parent's would report the right dashboard and then total the
+      # parent's rows behind it.
+      def inherited_janela_definition
+        superclass.janela&.for(self) if superclass.respond_to?(:janela)
+      end
+
+      # A model that already answers for itself keeps its answer, whether it
+      # said so here or on a class above. Ransack's own default lives on
+      # ActiveRecord::Base, so anything nearer than that was somebody's
+      # decision and is not ours to replace.
       def define_janela_ransack_allowlist
-        return if singleton_class.method_defined?(:ransackable_attributes, false)
+        return if janela_ransack_allowlist_answered?
+
+        extend RansackAllowlist
+      end
 
-        definition = @janela_definition
-        define_singleton_method(:ransackable_attributes) { |_auth_object = nil| definition.ransackable_attributes }
-        define_singleton_method(:ransackable_associations) { |_auth_object = nil| definition.ransackable_associations }
+      def janela_ransack_allowlist_answered?
+        owner = singleton_class.instance_method(:ransackable_attributes).owner
+        !ActiveRecord::Base.singleton_class.ancestors.include?(owner)
       end
   end
 end

data/lib/janela/version.rb

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

data/lib/janela.rb

@@ -37,9 +37,10 @@ module Janela
   # is for (ADR 021).
   mattr_accessor :silenced_checks, default: []
 
-  # Only models that declare a janela block are addressable over HTTP, keyed by
-  # the route key that appears in pane URLs (orders, sales_orders). Names are
-  # stored rather than classes so a reloaded model leaves nothing stale behind.
+  # A model that declares a janela block is addressable over HTTP, and so is a
+  # subclass of one, keyed by the route key that appears in pane URLs (orders,
+  # sales_orders). Names are stored rather than classes so a reloaded model
+  # leaves nothing stale behind.
   def self.registry
     @registry ||= {}
   end
@@ -48,6 +49,18 @@ module Janela
     registry[model.model_name.route_key] = model.name
   end
 
+  # A subclass registers itself as it is created (ADR 031), so unlike a
+  # declaration it is not a host writing a line of code. It never takes a
+  # route key another class already holds: a host that gives a subclass its
+  # parent's model_name, so the two share a route and a form, would otherwise
+  # find the parent's URL answering with a subset of its rows.
+  def self.register_subclass(model)
+    route_key = model.model_name.route_key
+    return if registry.key?(route_key) && registry[route_key] != model.name
+
+    register(model)
+  end
+
   # Every model that declares a janela block, for a form that offers a choice
   # of them. Eager loading first, because a model nobody has referenced yet has
   # not registered. A name that no longer resolves is left out rather than

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: janela
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Jay Killeen
@@ -164,6 +164,9 @@ files:
 - docs/decisions/026-a-renderer-is-the-seam-and-html-comes-first.md
 - docs/decisions/027-the-gallery-is-a-host-page.md
 - docs/decisions/028-the-predicate-list-adr-025-named.md
+- docs/decisions/029-a-panes-frame-is-identified-by-who-it-is.md
+- docs/decisions/030-a-panes-src-belongs-to-turbo.md
+- docs/decisions/031-a-subclass-inherits-the-dashboard.md
 - docs/decisions/INDEX.md
 - docs/multi-tenancy.md
 - docs/naming.md
@@ -187,12 +190,14 @@ metadata:
   bug_tracker_uri: https://github.com/retail-tasker/janela/issues
   rubygems_mfa_required: 'true'
 post_install_message: |
-  Janela 0.5.0 bounds what a filter predicate can ask for (ADR 025). Most
-  applications need do nothing: a click already writes eq or in, both still
-  allowed. You need to act only if you pass a filter yourself using _cont,
-  _matches, _start, _end or another predicate outside a dimension's
-  allowlist, which now raises Janela::BadRequest instead of being quietly
-  answered.
+  Janela 0.6.0 changes how single table inheritance is handled (ADR 031).
+  You need to act only if your application has STI subclasses under a model
+  that declares a janela block. Every named subclass of one is now
+  registered and addressable on its own route key, and Janela.definitions
+  returns one entry per subclass where a form offering a choice of model
+  previously showed one.
+
+  Everyone else: nothing to do.
 
   Steps: UPGRADING.md in this gem, or
   https://github.com/retail-tasker/janela/blob/main/UPGRADING.md