janela 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a28af383164e7bc1176c8b41bcff4d4ee384bbdaac7313b66a781c5c047a4fb8
-  data.tar.gz: 7611b5e28e04d9dc3cf45a940eba1aae33e2b80beb708f3a24b7ecc12a650819
+  metadata.gz: e1dbbea1c971d06f91daeb2e1bbd3ecc0a9d056363efd0e61664bf9cac51da9b
+  data.tar.gz: 50e76f042113f5e5e071f20d242c62176672aba367ab676448f6e722f1df9f2d
 SHA512:
-  metadata.gz: 8b32263ebc50a9d33ca95a9629bde4a58937370ea70df0fe17c58d651a0f87953aeb668dc363933c0aaa5e36a2b4bd663ffbdf4ea670cf5eec3dd5e3f7ee380d
-  data.tar.gz: 7651430b673d289b5bfa1a650c66351d580714c542cba06ec046cac4236dde21079c5debeddc9d27439442596b8a317aa60adccda1d1c3c9f1216b60a0d73f54
+  metadata.gz: 2a96c9be9933a2c7f4e33109bd5bd63f8fe6a0003047e66a3ab28f306bf33aa5d8be3f8be860ce306d4a994775749dcd410ca64998d8c856916caa048e3ab1c2
+  data.tar.gz: b9d548a0042e569e3cd9ceaae714af366b852a1a81ec95966bbd0a1b7b21f1978d352f560192fad01b87acc14d65d0dddb652ec443702eda5ffabeb61507d32f

data/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.9.0] - 2026-09-28
+
+### Added
+
+- `Janela::Frame.for(owner, key)`, so your code finds a frame it keeps for one of its pages: `Janela::Frame.for(account, :overview)`, `Janela::Frame.for(queue, :analytics)`. Finding by owner alone worked while an owner had one frame, and a tenant has several, so `find_by(owner: account)` returned the first frame the tenant ever made rather than the one the page was for. A frame now carries a nullable `key`, unique per owner in the database, which you set and nothing else reads: never in a URL or the engine's forms, so an analyst can rename a keyed frame without detaching it. The frame is created on first use, named after its key unless the block you pass says otherwise. Not the slug ADR 013 turned down, and the ADR says why. Needs a migration; see `UPGRADING.md` (ADR 041, #59).
+- **A pane can hold words.** A stored frame rendered its panes and nothing else, and a pane had to name a measure, so the analyst who owns a frame could choose every number on it and label none of them. A pane now has a `kind`: `query`, today's pane and the default, `text`, a heading, a body and a link the analyst writes, and `partial`, a partial you wrote under `app/views/janela_content/` that the analyst places by name and hands the same three strings, together with `pane`, `frame` and `where`, the filter fixed for the render, so a partial showing a figure scopes it from the frame rather than from whichever page it is on (#60). The reader's `q[...]` is not passed, since a content pane is not refreshed on a click. What an analyst writes is escaped, a link must be a path on your own site, and no HTML, Markdown or template is ever stored in a row, so the promise of ADR 012 still holds: an analyst arranges and writes words, and only code writes markup. Rendered as `div.janela-pane.janela-content`, with `janela-content-heading` on a text pane's heading, both added to the theming contract. Needs a migration; see `UPGRADING.md` (ADR 039, #58).
+- `janela_frame` takes `where:`, a filter the host fixes for one render: `janela_frame @frame, where: { queue_id_eq: @queue.id }`, or the same on the block form. It is for one frame shown on every record's page, narrowed to that record. Until now the only way was the page URL's `q[...]`, and that is the reader's: Clear filters, Escape, and a click on the same dimension all removed it, and the page then showed every record the reader could see under one record's heading. `where:` travels in each pane's URL as `where[...]`, which nothing the reader does touches, is applied before the reader's own filters so theirs can only narrow inside it, and is bounded exactly as `q[...]` is. A pane repointed with `janela--frame:repoint` keeps it. It is a view filter and not a permission: keep rows out of a reader's reach in `policy_scope` (ADR 040, #57).
+
+### Changed
+
+- The roadmap is called **Vista**, and the half of it beyond 1.0 is **Horizonte**. `docs/roadmap.md` keeps its path and its URL, so every link into it still resolves; what changed is the page's title, the demo's navigation, and `docs/naming.md`, which now carries both words in the table with the rest of the window's vocabulary. Janela is a window, so the document saying where the project is going is the view through it, and the far half of that view is the horizon. The table is where a forker looks to see whether a name was reasoned about or reached for, which is the only reason a rename like this is worth writing down. The page also gains a drawing of what it describes: two receding bands under an empty sky, eight marks on the near one for the issues in 1.0 and three on the far one for the work past it, drawn in `currentColor` so it reads in a light or a dark theme without knowing which it is in (ADR 037).
+- **Breaking.** A chart pane's title is a visible `<figcaption>` inside a `<figure>` wrapping the canvas, not only an `aria-label`. A table's caption and a single value's label were both visible text; a chart's was announced to a screen reader and shown to nobody, which #26's own investigation had already found and left standing. `janela-pane` moves from the `<canvas>` to the `<figure>`; `janela-chart` stays on the canvas, so anything that selected it alone is unaffected. The canvas's accessible name is now `aria-labelledby`, pointing at the figcaption, rather than a second copy of the string in `aria-label`. `janela-own-headings` hides the new figcaption the same way it already hides a table's caption and a value's label. `janela-chart-title` joins the theming contract; see `UPGRADING.md` (ADR 042, #61).
+
 ## [0.8.0] - 2026-09-23
 
 ### Added
@@ -192,6 +205,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.9.0]: https://github.com/retail-tasker/janela/releases/tag/v0.9.0
 [0.8.0]: https://github.com/retail-tasker/janela/releases/tag/v0.8.0
 [0.7.0]: https://github.com/retail-tasker/janela/releases/tag/v0.7.0
 [0.6.0]: https://github.com/retail-tasker/janela/releases/tag/v0.6.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.8"
+gem "janela", "~> 0.9"
 ```
 
 ```ruby
@@ -255,6 +255,37 @@ A frame renders each pane inline on the first response, so the page is a correct
 
 A frame may belong to an owner, `belongs_to :owner, polymorphic: true, optional: true`. Janela sets nothing there and reads nothing from it: it exists so a multi tenant host's Pundit `Scope` has a column to filter on. Set it to whatever your tenant is, and leave it null if you have one tenant.
 
+**A frame your code keeps for one of its pages.** Find it by owner and key, and it is created the first time it is asked for (ADR 041):
+
+```ruby
+@frame = Janela::Frame.for(Current.account, :overview)
+@frame = Janela::Frame.for(queue, :analytics) { |frame| frame.name = "#{queue.name} analytics" }
+```
+
+An owner can have any number of frames, one per key, beside every frame an analyst made from the engine's pages, which have no key. The key is yours: it is never in a URL or a form, so an analyst can rename, regrid and recompose the frame without detaching it from the page that finds it. The block runs only when the frame is created. Deleted from the engine's pages, it comes back empty on the next visit, because the page asks for it. If the owner is one of your records rather than your tenant, your policy scope has to see frames owned by those records; the [multi tenancy guide](docs/multi-tenancy.md) shows how.
+
+**Words beside the numbers.** A pane can hold a heading, a paragraph and a link instead of a query, so an analyst can label the frame they own without a deploy (ADR 039):
+
+```ruby
+frame.panes.create!(kind: "text", heading: "Refunds are excluded",
+                    body: "Figures are in the store's own currency.", link: "/orders", span: 3)
+frame.panes.create!(kind: "partial", partial: "overview_heading", heading: "Project overview", span: 3)
+```
+
+What an analyst writes is escaped, never rendered as markup, and a `link` must be a path on your own site. Anything that needs markup, an icon, an image, a layout, is a partial you write under `app/views/janela_content/`; the analyst places it by name and it receives `heading`, `body` and `link` as locals, and `pane`, `frame` and `where`, the filter you fixed for the render (`{}` when none), so a partial showing a figure can scope it from the frame's owner rather than from the page it is on. The reader's own selection is deliberately not passed: a content pane is not refreshed when they click, so a figure scoped by it would go stale. A partial that computes a figure scopes its own query, through your `policy_scope`, as any of your code does. The directory is the allowlist: a row cannot name any other template. It sits outside `app/views/janela/` on purpose, since a view of yours at an engine's path would replace the engine's own. The engine's pages offer both kinds when adding a pane. A content pane takes no part in cross-filtering and is not in a snapshot, because it has no query.
+
+**A frame narrowed to the record whose page it is on.** Pass `where:` and every pane of the frame is filtered by it before anything the reader selects:
+
+```erb
+<%= janela_frame @frame, where: { queue_id_eq: @queue.id } %>
+
+<%= janela_frame where: { queue_id_eq: @queue.id } do %>
+  <%= janela_pane Ticket, :count, by: :status %>
+<% end %>
+```
+
+It travels in each pane's URL as `where[...]`, apart from the reader's `q[...]`, so Clear filters, Escape and a click on the same dimension cannot take it off, and the reader's selection can only narrow inside it. It is bounded like any filter: declared dimensions only, and the predicates ADR 025 allows. It is a view filter, not a permission: it is visible in the pane URL, and a reader who edits it out sees only what your `policy_scope` already allows them to. Keep a record out of reach in the scope, not here. Putting the same filter in the page URL's `q[...]` instead does not hold, because `q[...]` is the reader's to clear (ADR 040).
+
 ### Janela's own pages
 
 The engine serves an index and a page per frame at the mount root, so you can install the gem and navigate the same day:
@@ -503,7 +534,7 @@ Deliberately out of scope: natural-language query, a separate data warehouse, a
 
 ## Status
 
-**v0.8.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, with the classes a theme may target documented in [Theming Janela](docs/theming.md). Not yet built: a visual editor, drill-down on time panes, other chart types. [Where Janela Is Going](docs/roadmap.md) says what 1.0 means and which of these are in it; open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
+**v0.9.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 found by owner and key, panes that hold words or a host partial as well as a query, a host-fixed frame filter no click can remove, 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, with the classes a theme may target documented in [Theming Janela](docs/theming.md). Not yet built: a visual editor, drill-down on time panes, other chart types. [Vista](docs/roadmap.md), the roadmap, says what 1.0 means and which of these are in it; open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
 
 ## Development
 

data/UPGRADING.md

@@ -12,6 +12,54 @@ bin/rails janela:doctor
 
 It reads your application and lists what still needs changing.
 
+## 0.8.0 to 0.9.0
+
+Two migrations, if you use stored frames. Both are taken by the same
+command, so run it once.
+
+**1. Take the content pane migration.**
+
+A pane can now hold words instead of a query (ADR 039). `janela_panes`
+gains `kind`, `heading`, `body`, `link` and `partial`, and `model` and
+`measure` become nullable:
+
+```bash
+bin/rails janela:install:migrations
+bin/rails db:migrate
+```
+
+Every existing pane becomes `kind: "query"` and renders as it did.
+Nothing else changes unless you add a content pane. If you want
+analysts to place markup of your own, write it as partials under
+`app/views/janela_content/`; each one is offered by name.
+
+**2. The frame key migration comes with it.**
+
+`janela_frames` gains a nullable `key` and a unique index on owner and
+key (ADR 041). Existing frames keep a nil key and are unaffected. If you
+keep a column in your own tables pointing at a frame, you can drop it
+and find the frame with `Janela::Frame.for(record, :some_key)` instead.
+
+**3. Check any CSS or JavaScript you wrote against a chart pane's canvas.**
+
+A bar or line pane now renders its title as a visible `<figcaption>`
+inside a `<figure>`, rather than only as the canvas's `aria-label`
+(ADR 042). No migration; a markup change to check your own code against:
+
+```
+Before: <canvas class="janela-pane janela-chart" role="img" aria-label="Revenue by Status">
+After:  <figure class="janela-pane">
+          <figcaption class="janela-chart-title">Revenue by Status</figcaption>
+          <canvas class="janela-chart" role="img" aria-labelledby="...">
+        </figure>
+```
+
+`canvas.janela-chart` still selects the canvas. If you selected
+`.janela-pane.janela-chart` as one element, or read a chart's title from
+its `aria-label`, both need updating: `.janela-pane` is now the
+`<figure>`, and the title is the figcaption's text, referenced by
+`aria-labelledby`.
+
 ## 0.7.0 to 0.8.0
 
 Two steps, each only if it applies to you: one if you name a parent

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

@@ -121,6 +121,7 @@ export default class extends Controller {
     const pane = this.paneTargets.find((each) => each.contains(event.target))
     const query = new URL(event.detail.url, window.location.origin)
     this.stripFilters(query)
+    this.keepFixedFilters(query, pane)
 
     // 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.
@@ -208,6 +209,20 @@ export default class extends Controller {
     }
   }
 
+  // A host's fixed filter is on a pane's base URL as where[...] (ADR 040), and
+  // a caller repointing the pane says nothing about it, the same as for the
+  // reader's filters. It carries over from the URL being replaced, so a
+  // repointed pane cannot drop out of the rows the host narrowed the frame to.
+  keepFixedFilters(url, pane) {
+    for (const key of [ ...url.searchParams.keys() ]) {
+      if (key.startsWith("where[")) url.searchParams.delete(key)
+    }
+    const previous = new URL(pane.dataset.janelaSrc, window.location.origin)
+    for (const [ key, value ] of previous.searchParams) {
+      if (key.startsWith("where[")) url.searchParams.append(key, value)
+    }
+  }
+
   // 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/assets/stylesheets/janela.css

@@ -69,6 +69,12 @@
 .janela-value-label { font-size: 0.85rem; opacity: 0.7; }
 .janela-value-number { font-size: 2rem; font-weight: 600; font-variant-numeric: tabular-nums; }
 
+/* Words in a stored frame (ADR 039). A heading and paragraphs, spaced by the
+   same unit as everything else and otherwise left to the page. */
+.janela-content > :first-child { margin-top: 0; }
+.janela-content > :last-child { margin-bottom: 0; }
+.janela-content-heading { font-size: 1.1rem; margin: 0 0 calc(var(--janela-space) * 2); }
+
 table.janela-pane { width: 100%; border-collapse: collapse; }
 table.janela-pane caption { text-align: left; font-weight: 600; margin-bottom: calc(var(--janela-space) * 2); }
 table.janela-pane td { padding: calc(var(--janela-space) * 1.5) 0; border-top: 1px solid var(--janela-line); }
@@ -85,18 +91,20 @@ table.janela-pane button {
 table.janela-pane button:hover { background: var(--janela-line); }
 table.janela-pane button[aria-pressed="true"] { background: var(--janela-accent); color: white; }
 
+.janela-chart-title { font-weight: 600; margin-bottom: calc(var(--janela-space) * 2); }
 canvas.janela-chart { width: 100% !important; max-height: 20rem; }
 
 /* A host whose own markup already says what a pane is puts this on any
-   ancestor, and the caption and the single value's label stop being drawn
-   without leaving the accessibility tree. Hidden rather than removed on
-   purpose: a caption is the table's accessible name, so display: none would
-   land a screen reader on a grid of numbers with nothing to say what they
-   measure. The rule ships here because that is easy to get wrong and every
-   host would otherwise write it (ADR 036, #26). A chart pane needs nothing:
-   its title was only ever an aria-label. */
+   ancestor, and the caption, the value's label and the chart's title stop
+   being drawn without leaving the accessibility tree. Hidden rather than
+   removed on purpose: each is its pane's accessible name (a chart's by
+   aria-labelledby since ADR 042), so display: none would land a screen
+   reader on a grid of numbers with nothing to say what they measure. The
+   rule ships here because that is easy to get wrong and every host would
+   otherwise write it (ADR 036, #26). */
 .janela-own-headings table.janela-pane caption,
-.janela-own-headings .janela-value-label {
+.janela-own-headings .janela-value-label,
+.janela-own-headings .janela-chart-title {
   position: absolute;
   width: 1px;
   height: 1px;

data/app/controllers/janela/application_controller.rb

@@ -25,6 +25,13 @@ module Janela
         q.is_a?(ActionController::Parameters) ? q.permit!.to_h : {}
       end
 
+      # The host's fixed filter (ADR 040). Its own key, so nothing that writes
+      # the reader's q[...] can reach it.
+      def fixed_filters
+        where = params[:where]
+        where.is_a?(ActionController::Parameters) ? where.permit!.to_h : {}
+      end
+
       # Pundit defines policy_scope on the host's ApplicationController, which
       # this inherits from, so authorisation applies without Janela depending
       # on Pundit or being configured. A host that defines nothing is refused

data/app/controllers/janela/panes_controller.rb

@@ -5,21 +5,27 @@ module Janela
     before_action :set_frame
     before_action :set_pane, only: %i[show edit update destroy move_up move_down]
 
+    # A content pane has no query, so it has no URL to be fetched from.
     def show
-      @query = @pane.query(filters: filters)
+      raise NotFound, "pane #{@pane.id} holds content, not a query" unless @pane.query?
+
+      @query = @pane.query(filters: filters, fixed: fixed_filters)
       @result = @query.result(on: janela_scope(@query.model))
     end
 
     # Two steps, because the engine's pages have no JavaScript to refresh one
     # select from another: the first picks a model, the second offers exactly
     # that model's measures and dimensions (ADR 018).
+    # Step one also offers words, and each partial the host wrote for them
+    # (ADR 039), in the same list as the models, since each is a choice of
+    # what the pane holds.
     def new
-      @pane = @frame.panes.build(model: params[:model], renderer: "table", span: 1)
-      @definition = @pane.model.present? ? Janela.definition!(@pane.model) : nil
+      @pane = build_pane(params[:model])
+      @definition = @pane.query? && @pane.model.present? ? Janela.definition!(@pane.model) : nil
     end
 
     def edit
-      @definition = @pane.definition
+      @definition = @pane.definition if @pane.query?
     end
 
     def create
@@ -28,7 +34,7 @@ module Janela
       if @pane.save
         redirect_to edit_frame_path(@frame), notice: t("janela.panes.created")
       else
-        @definition = @pane.model.present? ? Janela.definition!(@pane.model) : nil
+        @definition = @pane.query? && @pane.model.present? ? Janela.definition!(@pane.model) : nil
         render :new, status: :unprocessable_entity
       end
     end
@@ -37,7 +43,7 @@ module Janela
       if @pane.update(pane_params)
         redirect_to edit_frame_path(@frame), notice: t("janela.panes.updated")
       else
-        @definition = @pane.definition
+        @definition = @pane.definition if @pane.query?
         render :edit, status: :unprocessable_entity
       end
     end
@@ -70,7 +76,16 @@ module Janela
       end
 
       def pane_params
-        params.expect(pane: [ :model, :measure, :dimension, :renderer, :granularity, :limit, :span, :title ])
+        params.expect(pane: [ :kind, :model, :measure, :dimension, :renderer, :granularity, :limit, :span, :title,
+                              :heading, :body, :link, :partial ])
+      end
+
+      def build_pane(choice)
+        case choice.to_s
+        when "text" then @frame.panes.build(kind: "text", span: 1)
+        when /\Apartial:(.+)\z/ then @frame.panes.build(kind: "partial", partial: $1, span: 1)
+        else @frame.panes.build(model: choice, renderer: "table", span: 1)
+        end
       end
   end
 end

data/app/controllers/janela/queries_controller.rb

@@ -8,7 +8,8 @@ module Janela
         renderer: params.fetch(:as, "table"),
         granularity: params[:granularity],
         limit: params[:limit],
-        filters: filters
+        filters: filters,
+        fixed: fixed_filters
       )
 
       @result = @query.result(on: janela_scope(@query.model))

data/app/helpers/janela/frames_helper.rb

@@ -6,11 +6,20 @@ module Janela
     # renders filtered before any JavaScript runs.
     # charts: false renders a chart pane as its table, for a surface with no
     # chart runtime. The engine's own pages are the case (ADR 018).
-    def janela_frame(frame = nil, charts: true, &block)
-      return render("janela/frames/frame", frame: frame, filters: janela_page_filters, charts: charts) if frame
+    # where: is a filter the host fixes for this render, such as the record
+    # whose page this is. It goes into every pane's base URL rather than the
+    # frame's filters, so nothing the reader clicks can take it off (ADR 040).
+    def janela_frame(frame = nil, where: {}, charts: true, &block)
+      fixed = where.to_h.stringify_keys.sort.to_h
+      return render("janela/frames/frame", frame: frame, filters: janela_page_filters, fixed: fixed, charts: charts) if frame
 
-      tag.div(data: { controller: "janela--frame", action: janela_frame_actions,
-                      janela__frame_filters_value: janela_page_filters.to_json }, &block)
+      begin
+        outer, @janela_fixed_filters = @janela_fixed_filters, fixed
+        tag.div(data: { controller: "janela--frame", action: janela_frame_actions,
+                        janela__frame_filters_value: janela_page_filters.to_json }, &block)
+      ensure
+        @janela_fixed_filters = outer
+      end
     end
 
     # id: names the pane's frame instead of fingerprinting it from the query,
@@ -18,12 +27,12 @@ module Janela
     # 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
+      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit,
+                where: @janela_fixed_filters.presence }.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 id || Query.turbo_frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit),
-        src: src,
+        src: janela_with_page_filters(base),
         loading: :lazy,
         data: { janela__frame_target: "pane", janela_src: base }
     end
@@ -58,6 +67,16 @@ module Janela
         Janela.scope(controller, model)
       end
 
+      # The reader's filters appended after everything else in the base URL,
+      # which is how the frame controller builds the same URL. Rails sorts
+      # query parameters, which would put q before where, and a src spelled
+      # differently from the controller's is refetched as stale (#33).
+      def janela_with_page_filters(base)
+        return base if janela_page_filters.empty?
+
+        "#{base}#{base.include?("?") ? "&" : "?"}#{{ q: janela_page_filters }.to_query}"
+      end
+
       def janela_page_filters
         @janela_page_filters ||= begin
           q = request.query_parameters["q"]

data/app/models/janela/frame.rb

@@ -15,6 +15,26 @@ module Janela
     validates :name, presence: true
     validates :columns, inclusion: { in: COLUMNS }
     validates :gap, inclusion: { in: GAPS }
+    # The shape of the symbol a host passes, so nothing that reads like a
+    # name or a path gets in (ADR 041).
+    validates :key, format: { with: /\A[a-z0-9_]+\z/ }, uniqueness: { scope: %i[owner_type owner_id] }, allow_nil: true
+
+    # The host's frame for this owner and key, created on first use (ADR 041).
+    # The block runs only when the frame is created, to set what a new frame
+    # starts as. Two requests creating it at once end with one row: the unique
+    # index refuses the second insert, and the find is asked again.
+    #
+    #   Janela::Frame.for(account, :overview)
+    #   Janela::Frame.for(queue, :analytics) { |frame| frame.name = "#{queue.name} analytics" }
+    def self.for(owner, key, &block)
+      key = key.to_s
+      find_or_create_by!(owner: owner, key: key) do |frame|
+        frame.name = key.humanize
+        block&.call(frame)
+      end
+    rescue ActiveRecord::RecordNotUnique
+      find_by!(owner: owner, key: key)
+    end
 
     # Positions are kept contiguous so that moving a pane has no gap to fall
     # into and a new pane's position is never a hole. Called after a pane is

data/app/models/janela/pane.rb

@@ -10,15 +10,55 @@ module Janela
     # dashboard actually asks for. Any limit inside LIMITS is still valid.
     OFFERED_LIMITS = [ 5, 10, 20, 50, 100 ].freeze
 
+    # What a pane holds (ADR 039). A query is today's pane. Text is words an
+    # analyst writes, escaped. A partial is markup a host wrote in code, which
+    # an analyst places by name and hands the same words to.
+    KINDS = %w[query text partial].freeze
+    # Outside app/views/janela/ on purpose: a host view at an engine's path
+    # replaces the engine's own, and janela/panes/ holds the engine's forms.
+    CONTENT_PARTIALS = "janela_content"
+    PARTIAL_NAME = /\A[a-z0-9_]+\z/
+    # A path on this site: one slash, then not a second. A scheme or a
+    # protocol relative // would send a reader anywhere under the host's name.
+    SITE_PATH = %r{\A/(?!/)}
+
     belongs_to :frame
 
     before_validation :assign_position, on: :create
 
     validates :position, presence: true
-    validates :measure, presence: true
+    validates :kind, inclusion: { in: KINDS }
     validates :span, inclusion: { in: SPANS }
     validates :limit, inclusion: { in: LIMITS }, allow_nil: true
-    validate :declared_by_a_janela_block
+    validates :measure, presence: true, if: :query?
+    validate :declared_by_a_janela_block, if: :query?
+    validate :holds_no_query, unless: :query?
+    validates :heading, presence: true, if: -> { text? && body.blank? }
+    validates :link, format: { with: SITE_PATH, message: "must be a path on this site, starting with /" }, allow_blank: true
+    validate :names_a_content_partial, if: :partial?
+
+    # The partials a host has written for analysts to place, by name.
+    def self.content_partials
+      ActionController::Base.view_paths.flat_map do |path|
+        Dir.glob(File.join(path.to_s, CONTENT_PARTIALS, "_*.html.erb")).map { |file| File.basename(file, ".html.erb").delete_prefix("_") }
+      end.select { |name| name.match?(PARTIAL_NAME) }.uniq.sort
+    end
+
+    def query?
+      kind == "query"
+    end
+
+    def text?
+      kind == "text"
+    end
+
+    def partial?
+      kind == "partial"
+    end
+
+    def partial_path
+      "#{CONTENT_PARTIALS}/#{partial}"
+    end
 
     # 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
@@ -30,15 +70,17 @@ module Janela
     # renderer: overrides what the row asked for, because a renderer is a
     # viewing choice and a surface without a chart runtime shows a table
     # instead (ADR 018).
-    def query(filters: {}, renderer: self.renderer)
+    def query(filters: {}, fixed: {}, renderer: self.renderer)
       Query.new(definition: definition, measure: measure.to_sym, dimension: dimension.presence&.to_sym,
-                renderer: renderer, granularity: granularity, limit: limit, filters: filters, title: title)
+                renderer: renderer, granularity: granularity, limit: limit, filters: filters, fixed: fixed,
+                title: title)
     end
 
     # The row's own words, for a list or a heading. Built from the columns
     # rather than from a query, because an editing page has to render even if
     # a janela block has since lost the dimension this row names.
     def label
+      return content_label unless query?
       return title if title.present?
 
       dimension.present? ? "#{measure.humanize} by #{dimension.humanize}" : measure.to_s.humanize
@@ -85,6 +127,27 @@ module Janela
         true
       end
 
+      def content_label
+        return heading if heading.present?
+        return partial.humanize if partial?
+
+        body.to_s.truncate(40)
+      end
+
+      # A row is one thing or the other, so the database never holds half a
+      # query that nothing will run.
+      def holds_no_query
+        %i[model measure dimension granularity].each do |column|
+          errors.add(column, "belongs to a query pane, not a #{kind} one") if self[column].present?
+        end
+      end
+
+      def names_a_content_partial
+        return if partial.to_s.match?(PARTIAL_NAME) && self.class.content_partials.include?(partial)
+
+        errors.add(:partial, "must name a partial in app/views/#{CONTENT_PARTIALS}/")
+      end
+
       def assign_position
         self.position ||= (frame&.panes&.maximum(:position) || 0) + 1
       end

data/app/models/janela/query.rb

@@ -7,7 +7,7 @@ module Janela
   class Query
     RENDERERS = %w[table bar line].freeze
 
-    attr_reader :definition, :measure, :dimension, :renderer, :limit, :filters, :snapshot
+    attr_reader :definition, :measure, :dimension, :renderer, :limit, :filters, :fixed, :snapshot
 
     # The helper renders the turbo frame and the controller renders its
     # replacement, so both derive the id the same way from the same parameters.
@@ -17,13 +17,14 @@ module Janela
       parts.compact.join("_")
     end
 
-    def initialize(definition:, measure:, dimension: nil, renderer: "table", granularity: nil, limit: nil, filters: {}, snapshot: nil, title: nil)
+    def initialize(definition:, measure:, dimension: nil, renderer: "table", granularity: nil, limit: nil, filters: {}, fixed: {}, snapshot: nil, title: nil)
       @definition = definition
       @title = title
       @measure = measure
       @dimension = dimension
       @renderer = renderer.to_s
       @filters = filters
+      @fixed = fixed
       @snapshot = snapshot
 
       raise BadRequest, "unknown pane renderer #{renderer.inspect}" unless RENDERERS.include?(@renderer)
@@ -97,6 +98,10 @@ module Janela
     def result(on: nil)
       return snapshot.stored_result(self) if frozen?
 
+      # The fixed filter applies even on this pane's own dimension, unlike the
+      # reader's: it is the host saying which rows the frame is about, not a
+      # selection this pane should show the alternatives to (ADR 040).
+      on = definition.narrow(on || model.all, fixed) if fixed.present?
       definition.query(measure, by: dimension, where: applicable_filters, on: on, granularity: granularity, limit: limit)
     end
 

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

@@ -0,0 +1,26 @@
+<%# Words an analyst wrote, escaped like any other string, or a partial the
+    host wrote that is handed the same words (ADR 039). Nothing a row holds
+    reaches the page as markup. The same shape as a query pane, a grid cell
+    holding the pane, so a theme that draws the cell as glass draws this too. %>
+<%= tag.div class: "janela-span-#{pane.span}", id: "janela_pane_#{pane.id}" do %>
+<%= tag.div class: [ "janela-pane", "janela-content" ] do %>
+  <% if pane.partial? %>
+    <%# The analyst's words, and what the partial is about: its row, its frame,
+        so the frame's owner and key, and the filter the host fixed for this
+        render (#60). Not the reader's q[...]: this pane is not refreshed when
+        they click, so a figure scoped by it would be stale after the first. %>
+    <%= render pane.partial_path, heading: pane.heading, body: pane.body, link: pane.link,
+               pane: pane, frame: frame, where: fixed %>
+  <% else %>
+    <% if pane.heading.present? %>
+      <h2 class="janela-content-heading"><%= pane.link.present? ? link_to(pane.heading, pane.link) : pane.heading %></h2>
+    <% end %>
+    <% pane.body.to_s.split(/\n\s*\n/).map(&:strip).reject(&:empty?).each do |paragraph| %>
+      <p><%= paragraph %></p>
+    <% end %>
+    <% if pane.link.present? && pane.heading.blank? %>
+      <p><%= link_to pane.link, pane.link %></p>
+    <% end %>
+  <% end %>
+<% end %>
+<% end %>

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

@@ -1,5 +1,13 @@
 <%= tag.div class: janela_frame_classes(frame),
             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 } %>
+  <% frame.panes.each do |pane| %>
+    <%# A content pane has no query, so it is not a turbo frame and the frame
+        controller has nothing of it to refresh (ADR 039). %>
+    <% if pane.query? %>
+      <%= render "janela/frames/pane", pane: pane, filters: filters, fixed: fixed, charts: charts %>
+    <% else %>
+      <%= render "janela/frames/content", pane: pane, frame: frame, fixed: fixed %>
+    <% end %>
+  <% end %>
 <% end %>

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

@@ -5,8 +5,8 @@
     change, which is what makes cross-filtering work from here. %>
 <%# A table needs no JavaScript, so it is what a surface with no chart runtime
     shows in place of an empty canvas (ADR 018). %>
-<% query = pane.query(filters: filters, renderer: pane.chart? && !charts ? "table" : pane.renderer) %>
+<% query = pane.query(filters: filters, fixed: fixed, renderer: pane.chart? && !charts ? "table" : pane.renderer) %>
 <%= turbo_frame_tag pane.turbo_frame_id, class: "janela-span-#{pane.span}",
-      data: { janela__frame_target: "pane", janela_src: janela_routes.frame_pane_path(pane.frame_id, pane) } do %>
+      data: { janela__frame_target: "pane", janela_src: janela_routes.frame_pane_path(pane.frame_id, pane, where: fixed.presence) } do %>
   <%= render "janela/queries/query", query: query, result: query.result(on: janela_scope(query.model)) %>
 <% end %>

data/app/views/janela/panes/_content_form.html.erb

@@ -0,0 +1,33 @@
+<%# Words for a content pane (ADR 039). Plain fields, because what is typed
+    here is shown as text: there is no markup to write. %>
+<%= form_with model: pane, url: pane.persisted? ? frame_pane_path(frame, pane) : frame_panes_path(frame), class: "janela-form" do |form| %>
+  <%= render "janela/shared/errors", record: pane %>
+  <%= form.hidden_field :kind %>
+  <%= form.hidden_field :partial if pane.partial? %>
+
+  <div class="janela-field">
+    <%= form.label :heading %>
+    <%= form.text_field :heading %>
+  </div>
+
+  <div class="janela-field">
+    <%= form.label :body %>
+    <%= form.text_area :body, rows: 5 %>
+  </div>
+
+  <div class="janela-field">
+    <%= form.label :link %>
+    <%= form.text_field :link %>
+    <span class="janela-hint"><%= t("janela.panes.link_hint") %></span>
+  </div>
+
+  <div class="janela-field">
+    <%= form.label :span %>
+    <%= form.select :span, Janela::Pane::SPANS.to_a %>
+  </div>
+
+  <div class="janela-actions">
+    <%= form.submit t("janela.actions.save"), class: "janela-button" %>
+    <%= link_to t("janela.actions.cancel"), edit_frame_path(frame) %>
+  </div>
+<% end %>