janela 0.8.0 → 0.9.0

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

@@ -1,6 +1,6 @@
 <li class="janela-list-row">
   <span class="janela-list-name"><%= pane.label %></span>
-  <span class="janela-card-meta"><%= t("janela.panes.summary", renderer: pane.renderer, span: pane.span) %></span>
+  <span class="janela-card-meta"><%= pane.query? ? t("janela.panes.summary", renderer: pane.renderer, span: pane.span) : t("janela.panes.content_summary", kind: pane.partial? ? pane.partial.humanize : t("janela.panes.text"), span: pane.span) %></span>
   <span class="janela-actions">
     <%= button_to t("janela.actions.move_up"), move_up_frame_pane_path(frame, pane), method: :patch,
           class: "janela-button", disabled: pane == frame.panes.first %>

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

@@ -2,4 +2,8 @@
 <h1 class="janela-heading"><%= @pane.label %></h1>
 <p class="janela-crumb"><%= link_to @frame.name, edit_frame_path(@frame) %></p>
 
-<%= render "form", frame: @frame, pane: @pane, definition: @definition %>
+<% if @pane.query? %>
+  <%= render "form", frame: @frame, pane: @pane, definition: @definition %>
+<% else %>
+  <%= render "content_form", frame: @frame, pane: @pane %>
+<% end %>

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

@@ -4,6 +4,8 @@
 
 <% if @definition %>
   <%= render "form", frame: @frame, pane: @pane, definition: @definition %>
+<% elsif !@pane.query? %>
+  <%= render "content_form", frame: @frame, pane: @pane %>
 <% else %>
   <%# Step one of two. The engine's pages run no JavaScript, so one select
       cannot refill another: picking the model first is what lets step two
@@ -11,7 +13,10 @@
   <%= form_with url: new_frame_pane_path(@frame), method: :get, class: "janela-form" do |form| %>
     <div class="janela-field">
       <%= form.label :model, Janela::Pane.human_attribute_name(:model) %>
-      <%= form.select :model, Janela.definitions.map { |definition| [ definition.model.model_name.human, definition.model.model_name.route_key ] } %>
+      <%= form.select :model, grouped_options_for_select(
+            t("janela.panes.numbers") => Janela.definitions.map { |definition| [ definition.model.model_name.human, definition.model.model_name.route_key ] },
+            t("janela.panes.words") => [ [ t("janela.panes.text"), "text" ] ] +
+              Janela::Pane.content_partials.map { |name| [ name.humanize, "partial:#{name}" ] }) %>
     </div>
 
     <div class="janela-actions">

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

@@ -8,17 +8,21 @@
 <% elsif result.empty? %>
   <p class="janela-pane janela-empty"><%= query.title %>: no data</p>
 <% elsif query.chart? %>
-  <canvas class="janela-pane janela-chart"
-          data-controller="janela--chart"
-          data-action="janela--chart:toggle->janela--frame#toggle"
-          data-janela--chart-type-value="<%= query.renderer %>"
-          data-janela--chart-title-value="<%= query.title %>"
-          data-janela--chart-selected-value="<%= query.selected_values.to_json %>"
-          data-janela--chart-labels-value="<%= result.keys.to_json %>"
-          data-janela--chart-values-value="<%= result.values.map(&:to_f).to_json %>"
-          data-janela--chart-formatted-value="<%= result.values.map { |measured| query.format(measured) }.to_json %>"
-          data-janela--chart-filters-value="<%= query.filters_for(result.keys).to_json %>"
-          role="img" aria-label="<%= query.title %>"></canvas>
+  <% title_id = "#{query.turbo_frame_id}-title" %>
+  <figure class="janela-pane">
+    <figcaption class="janela-chart-title" id="<%= title_id %>"><%= query.title %></figcaption>
+    <canvas class="janela-chart"
+            data-controller="janela--chart"
+            data-action="janela--chart:toggle->janela--frame#toggle"
+            data-janela--chart-type-value="<%= query.renderer %>"
+            data-janela--chart-title-value="<%= query.title %>"
+            data-janela--chart-selected-value="<%= query.selected_values.to_json %>"
+            data-janela--chart-labels-value="<%= result.keys.to_json %>"
+            data-janela--chart-values-value="<%= result.values.map(&:to_f).to_json %>"
+            data-janela--chart-formatted-value="<%= result.values.map { |measured| query.format(measured) }.to_json %>"
+            data-janela--chart-filters-value="<%= query.filters_for(result.keys).to_json %>"
+            role="img" aria-labelledby="<%= title_id %>"></canvas>
+  </figure>
 <% else %>
   <table class="janela-pane">
     <caption><%= query.title %></caption>

data/config/locales/en.yml

@@ -58,6 +58,11 @@ en:
       no_dimension: "No breakdown, one number"
       no_limit: Every row
       summary: "%{renderer}, %{span} wide"
+      content_summary: "%{kind}, %{span} wide"
+      numbers: Numbers
+      words: Words
+      text: Text
+      link_hint: "A path on this site, such as /orders. Makes the heading a link."
       title_placeholder: Janela writes one if you leave this blank
     renderers:
       bar: Bar chart

data/db/migrate/20260924000001_add_content_to_janela_panes.rb

@@ -0,0 +1,16 @@
+class AddContentToJanelaPanes < ActiveRecord::Migration[8.0]
+  def change
+    # A pane can hold words instead of a query (ADR 039). Every existing row
+    # is a query, which is the default.
+    add_column :janela_panes, :kind, :string, null: false, default: "query"
+    add_column :janela_panes, :heading, :string
+    add_column :janela_panes, :body, :text
+    add_column :janela_panes, :link, :string
+    add_column :janela_panes, :partial, :string
+
+    # A content pane has no query, so these are required by kind in the
+    # model rather than by the column.
+    change_column_null :janela_panes, :model, true
+    change_column_null :janela_panes, :measure, true
+  end
+end

data/db/migrate/20260924000002_add_key_to_janela_frames.rb

@@ -0,0 +1,10 @@
+class AddKeyToJanelaFrames < ActiveRecord::Migration[8.0]
+  def change
+    # The host's own name for a frame, so it finds one of an owner's several
+    # from code (ADR 041). Janela reads it only in Frame.for.
+    add_column :janela_frames, :key, :string
+    # One frame per owner and key. Frames without a key, every one an analyst
+    # makes, are not constrained: a null is never equal to another.
+    add_index :janela_frames, [ :owner_type, :owner_id, :key ], unique: true
+  end
+end

data/docs/composing.md

@@ -0,0 +1,269 @@
+---
+Topics: composing, html, layout, host-integration, styling
+---
+
+# Composing a Page Around Panes
+
+A pane is a number, a table or a chart. Everything a dashboard has that
+is not a query result, the heading, the icon beside it, a sentence of
+explanation, a link to the full list, a progress bar, is ordinary HTML
+that your application writes. This page is the reference for writing it
+so that it sits properly beside Janela's own markup.
+
+The short version: compose with the block form of `janela_frame`, put
+your markup and the panes inside a `janela-frame` grid, and style both
+with your own classes plus the hooks in [Theming Janela](theming).
+
+## Where your markup can go
+
+`janela_frame` has two forms, and only one of them takes your HTML.
+
+| Form | Your own HTML | Use it when |
+| --- | --- | --- |
+| `janela_frame do ... end` | anywhere inside the block | the page needs a heading, text, links or a layout of its own |
+| `janela_frame @frame` | none | the dashboard is data an analyst edits without a deploy |
+
+A stored frame renders panes and nothing else. That is deliberate (ADR
+012): a row names a measure the model declared, so an analyst arranges
+what is shown and cannot put arbitrary content on the page. If a
+dashboard needs a heading and an explanation, write them in the page
+around the frame, or use the block form. Whether a stored frame should
+hold content of its own, such as text or an image, has not been decided.
+
+```erb
+<h2>Orders</h2>
+<p>Everything placed this financial year.</p>
+<%= janela_frame @frame %>
+```
+
+Inside the block form, anything goes. The block's own `<div>` carries
+the cross-filtering controller, so a button or a link inside it can
+clear or re-point the panes, and markup that has nothing to do with
+filtering is simply ignored by it.
+
+## The grid
+
+The block form's wrapper is not a grid. Write the grid yourself with the
+same classes a stored frame gets from its integers:
+
+```erb
+<%= janela_frame do %>
+  <div class="janela-frame janela-cols-3 janela-gap-4">
+    <%= janela_pane Order, :revenue %>
+    <%= janela_pane Order, :orders %>
+    <%= janela_pane Order, :average_order %>
+  </div>
+<% end %>
+```
+
+Every direct child is a grid item, your own elements included, so a
+heading can take a whole row and a text box can sit between two panes.
+`janela_pane` takes no class of its own yet
+([#29](https://github.com/retail-tasker/janela/issues/29)), so wrap a
+pane to span it:
+
+```erb
+<div class="janela-span-2"><%= janela_pane Order, :revenue, by: :status, as: :bar %></div>
+```
+
+Below `40rem` the grid is one column whatever you asked for.
+
+Under the vitral theme every direct child of `janela-frame` is drawn as a
+pane of glass, your heading and your notes included. That is usually
+what you want, since the page reads as one window. When it is not, put
+the element above the grid rather than in it.
+
+## A frame for one record
+
+One frame is often wanted on every record's page, each copy narrowed to
+its own record. Pass the condition as `where:` and every pane is
+filtered by it before anything the reader selects:
+
+```erb
+<%= janela_frame @frame, where: { queue_id_eq: @queue.id } %>
+```
+
+The block form takes the same argument. Do not carry the record in the
+page URL's `q[...]` instead: that is the reader's selection, and Clear
+filters or Escape takes it off. `where:` is a view filter, not a
+permission, so a record a reader must not see is kept out of reach by
+your `policy_scope` (ADR 040). Do not also offer the fixed dimension as a
+pane the reader can click: any value but the fixed one returns nothing.
+
+A figure you compute yourself for the same page, such as the progress
+bar below, takes the same condition in its own `where:`.
+
+## Components
+
+Each of these is plain HTML. The class names that start `janela-` are
+the contract and will not change without an entry in `UPGRADING.md`.
+The ones that do not are yours to name; the examples use a `card-`
+prefix only so they read clearly.
+
+### A heading with an icon
+
+A heading belongs to your page, not to a pane. Make it a full-width grid
+item so it sits above the panes it introduces.
+
+```erb
+<%= janela_frame do %>
+  <div class="janela-frame janela-cols-3 janela-gap-4">
+    <header class="janela-span-3 card-heading">
+      <svg aria-hidden="true" class="card-icon">...</svg>
+      <h2>Orders overview</h2>
+    </header>
+    <%= janela_pane Order, :revenue %>
+    ...
+  </div>
+<% end %>
+```
+
+Mark the icon `aria-hidden="true"`. The heading's text is its name, and
+an icon read aloud as "image" adds nothing.
+
+### A text box
+
+Explanation, a caveat, what the numbers exclude. A grid item like any
+other, so it can span the row or sit beside a pane.
+
+```erb
+<p class="janela-span-3 card-note">
+  Refunds are excluded. Figures are in the store's own currency.
+</p>
+```
+
+Write it in the page rather than in a pane's title. A title is the
+pane's accessible name and should say what it measures, not carry a
+paragraph.
+
+### A labelled number
+
+A single value pane already renders its own label and number
+(`janela-value-label`, `janela-value-number`). When your card already
+says what the number is, hide the pane's label with
+`janela-own-headings` so it is not on screen twice. It stays in the
+accessibility tree.
+
+```erb
+<div class="card janela-own-headings">
+  <p class="card-label">Revenue</p>
+  <%= janela_pane Order, :revenue %>
+</div>
+```
+
+### Several numbers in one card
+
+Two single value panes side by side read as one figure. Each is its own
+query, so each cross-filters on its own.
+
+```erb
+<div class="card janela-own-headings">
+  <p class="card-label">Revenue, from orders</p>
+  <div class="card-figure">
+    <%= janela_pane Order, :revenue %>
+    <span>from</span>
+    <%= janela_pane Order, :orders %>
+  </div>
+</div>
+```
+
+```css
+.card-figure { display: flex; align-items: baseline; gap: .5rem; }
+```
+
+A single value pane is a block of its own, a `<p>` holding its label
+and number, so the figure needs a `<div>` rather than a `<p>` around it,
+and a line of CSS to put the numbers side by side. Without it they
+stack.
+
+A done out of total figure cannot be two panes yet. A measure has no
+condition of its own, so there is no pane for the done half. Compute it
+as the progress bar below does. A measure that is itself the ratio is
+proposed in ADR 038
+([#27](https://github.com/retail-tasker/janela/issues/27)).
+
+### A progress bar
+
+There is no progress renderer. A bar is your own markup, from a value
+your controller computes through the same scope Janela uses.
+`where:` takes the same Ransack conditions a pane's filters do, on the
+dimensions the model declared:
+
+```ruby
+scope = policy_scope(Order)
+done = Order.janela.query(:orders, where: { status_eq: "paid" }, on: scope)
+total = Order.janela.query(:orders, on: scope)
+@percent = total.zero? ? 0 : (100.0 * done / total).round
+```
+
+```erb
+<div class="janela-span-3 card-progress">
+  <p><span>Paid</span> <span><%= @percent %>%</span></p>
+  <progress max="100" value="<%= @percent %>"><%= @percent %>%</progress>
+</div>
+```
+
+Use `<progress>` rather than two nested `<div>`s: it has a role and a
+value a screen reader can announce without any ARIA of your own. It is
+computed once, when the page renders, so it does not move when a click
+cross-filters the panes around it. Put it outside the frame, or say
+that it is the unfiltered figure, so nobody reads it as filtered.
+
+### A link or an action
+
+A link to the full list, or a button that clears the filters.
+
+```erb
+<%= link_to "View all", orders_path, class: "card-link" %>
+<button type="button" data-action="janela--frame#clear">Clear filters</button>
+```
+
+A button only reaches `janela--frame` from inside the block. Outside
+it, it has no frame to clear.
+
+## Putting it together
+
+An overview card: a heading with an icon and a link, two numbers and a
+note, then a progress bar under it.
+
+```erb
+<%= janela_frame do %>
+  <div class="janela-frame janela-cols-3 janela-gap-4">
+    <header class="janela-span-3 card-heading">
+      <svg aria-hidden="true" class="card-icon">...</svg>
+      <h2>Orders overview</h2>
+      <%= link_to "View all", orders_path, class: "card-link" %>
+    </header>
+
+    <div class="janela-span-2 card janela-own-headings">
+      <p class="card-label">Revenue, from orders</p>
+      <div class="card-figure">
+        <%= janela_pane Order, :revenue %>
+        <span>from</span>
+        <%= janela_pane Order, :orders %>
+      </div>
+    </div>
+
+    <p class="card-note">Refunds are excluded.</p>
+  </div>
+<% end %>
+
+<div class="card-progress">
+  <p><span>Paid, across every order</span> <span><%= @percent %>%</span></p>
+  <progress max="100" value="<%= @percent %>"><%= @percent %>%</progress>
+</div>
+```
+
+The progress bar sits below the frame, and its label says it covers
+every order, because it does not move when a click filters the panes
+above it.
+
+## What this page is not
+
+It is not a component library. Janela ships no `card` class and will
+not: a heading, a paragraph and a link already exist, and your
+application already has a way of drawing them. What Janela promises is
+the grid and the pane hooks, so that your markup and its markup can sit
+in one layout. If a component keeps needing something from a pane that
+the hooks cannot give it, that is worth an issue rather than a
+workaround.

data/docs/decisions/038-a-ratio-is-a-measure-of-its-own.md

@@ -0,0 +1,194 @@
+---
+Date: 2026-09-24
+Status: Proposed
+Related: ADR 001, ADR 002, ADR 007, ADR 020, ADR 025
+Triggers:
+  - adding a measure kind, or a sixth aggregate to the DSL
+  - deciding how a measure's value is scaled or formatted
+  - changing how a grouped pane is ordered
+  - a host wanting a rate or a percentage over a boolean column
+  - wondering whether a measure option belongs on the measure or on a pane
+Topics: DSL, query layer, measures, formatting, ordering
+---
+
+# ADR 038: A Ratio Is a Measure of Its Own, Stored as a Fraction and Read as a Percentage
+
+## Context
+
+A boolean column is how an application stores a yes or no fact, and
+averaging one is how a person asks what share of rows are yes. Janela
+refuses that today, correctly, and the refusal leaves nowhere to go
+(#20, #27).
+
+Four things were measured against the demo on `c6922da`, Rails 8.1.3.1
+and SQLite, with `orders.expedited` as a real boolean column.
+
+**The cast is total, not partial.** `Order.average(:expedited)` returns
+`true` where the true ratio is `0.333`, and returns `true` again where
+the true ratio is `0.0`, because Rails' boolean cast does not read a
+float `0.0` as false. There is no value of the ratio that renders as
+anything other than `true`. #20 described this as a cast losing
+information; it loses all of it.
+
+**The existing machinery already carries the fix.**
+`relation.average(Arel.sql("CASE WHEN ... THEN 1.0 ELSE 0.0 END"))`
+answers `0.3333333333333333` as a Float ungrouped, and grouped it
+answers a hash per bucket. Nothing new is needed for grouping,
+gap filling, cross filtering or snapshots, because the ratio goes
+through the same `Measure#apply` every other measure goes through.
+
+**Ordering breaks, which #27 did not mention.** `Definition` orders a
+grouped query with `order(Arel.sql("#{measure.sql_alias} DESC"))`, and
+`sql_alias` is `"#{aggregate}_#{column}"`, the alias ADR 007 names.
+There is no such alias for an expression: the string becomes
+`average_CASE WHEN orders.expedited THEN 1.0 ELSE 0.0 END DESC` and
+raises `ActiveRecord::StatementInvalid`. Ordering by the expression
+itself works and sorts correctly.
+
+**The null claim in #27 is backwards.** On one true, one false and one
+null row:
+
+| expression | result |
+| --- | --- |
+| `AVG(CASE WHEN f THEN 1.0 ELSE 0.0 END)`, null as false | 0.333 |
+| the same with a `WHEN f IS NULL THEN NULL` arm | 0.5 |
+| `AVG(f)`, plain | 0.5 |
+
+#27 says excluding null "differs from `AVG` in SQL". Excluding null is
+exactly what `AVG` does. The naive `CASE` is the form that differs, and
+it counts every unknown as a failure, which is this library's worst
+failure mode: a wrong number that looks like a right one.
+
+### Fraction or percentage, and where that choice lives
+
+The formatter does not scale. `format(0.6667)` with `suffix: "%"`
+renders `"0.7%"`, wrong by a hundred; `format(66.67)` renders
+`"66.7%"`. ADR 020's own example, `measure :pass_rate, average: :score,
+precision: 1, suffix: "%"`, only reads correctly if the value is
+already on a nought to a hundred scale.
+
+Three positions were considered.
+
+**Storing nought to a hundred** was rejected. ADR 020 holds that the
+number itself reaches a snapshot, an order clause and a comparison at
+full precision. Storing a presentation scale puts a display choice into
+a frozen snapshot and into an `ORDER BY`, where it is no longer a
+display choice at all. A ratio is a proportion, and a proportion is
+nought to one.
+
+**Leaving the scale to each pane** was rejected, and ADR 020 had
+already rejected it: `janela_panes` carries `model`, `measure`,
+`dimension`, `renderer`, `granularity`, `limit` and `position`, and no
+formatting columns, deliberately. Two panes of one measure could
+otherwise freeze different numbers into different snapshots and serve
+both as fact. ADR 020's consequences say per pane formatting, if it
+ever arrives, overrides the measure's format rather than replacing the
+idea, and calls that the reason to think twice.
+
+**A fraction with an opt in percentage**, such as `percent: true` or a
+remembered `suffix: "%"`, was considered and is the option this
+decision narrows rather than takes. A proportion shown to a person is a
+percentage; making that a flag means every host that declares a rate
+also remembers a second thing, and a host that forgets gets `0.31` on a
+dashboard where `31.2%` was meant. ADR 001 prefers one obvious way over
+a knob.
+
+## Decision
+
+**A ratio is a measure kind of its own. It computes a fraction, and it
+renders as a percentage.**
+
+```ruby
+janela do
+  measure :expedited_rate, ratio: :expedited   # a boolean column
+end
+```
+
+**The kind sits beside the five aggregates rather than inside them.**
+ADR 002 says a measure takes exactly one aggregate of `sum`, `count`,
+`average`, `minimum`, `maximum`. `ratio:` is a sixth option in that
+position and not a sixth aggregate, because it names a column and an
+intent rather than an SQL function. `Measure::AGGREGATES` is unchanged
+and the error a host already sees when it declares two of them is
+unchanged.
+
+**It requires a boolean column, which is the mirror of the refusal it
+answers.** `average:` rejects a boolean column and names `ratio:`;
+`ratio:` rejects anything that is not one. Both look the column up
+through `model.type_for_attribute`, so the expression is built from a
+column the model has confirmed, never from a string that arrived over
+HTTP. ADR 025 bounds what a filter may ask for; this is the same
+principle one layer down.
+
+**Null is excluded, so a ratio agrees with `AVG`.**
+
+```sql
+AVG(CASE WHEN col IS NULL THEN NULL WHEN col THEN 1.0 ELSE 0.0 END)
+```
+
+An unknown is not a failure. A host that wants unknowns counted as
+failures says so in its own schema with a `NOT NULL` default, which is
+a decision about the data rather than about the dashboard.
+
+**A condition form is not included.** `ratio: { status: "paid" }` was
+considered and rejected: it is a second query language growing inside
+the measure, it needs the same bounding ADR 025 gives filters, and the
+case it serves is already served. Where a column is not already a yes
+or no fact, the split is the honest answer and cross filters better,
+which is what #20's refusal says and what ADR 002 says to every other
+variation. The boolean case earns its own kind precisely because the
+split cannot answer it: "the share that passed, over time" is one
+series, and a dimension gives two.
+
+**The stored number is the fraction. The rendered string is the
+percentage.** The value that reaches a snapshot, an `ORDER BY`, a chart
+axis and a comparison is `0.3119`. The string a table cell, a single
+value and a chart tooltip show is `31.2%`. This follows ADR 020 rather
+than bending it: that decision forbids transforming the number, and a
+ratio's number is never transformed. Only the string is.
+
+Precision defaults to one decimal place for a ratio rather than ADR
+020's fallback of two, because a percentage carries two more significant
+figures than the fraction it came from and `31.19%` is noise. A measure
+may still declare its own.
+
+**Declaring `prefix:` or `suffix:` on a ratio raises.** The kind already
+says what unit it is, and a host that writes `suffix: "%"` out of habit
+would otherwise render `31.2%%`. Raising names the conflict rather than
+guessing which was meant, which is what this library does everywhere
+else it is given two answers.
+
+**A measure answers what it is ordered by, rather than what its column
+alias is.** `Measure#sql_alias` becomes `Measure#order_by`: for an
+aggregate it returns the alias ActiveRecord already gives, unchanged,
+and for a ratio it returns the `AVG(CASE ...)` expression. ADR 007's
+decision is untouched, since a category pane is still ordered by its
+measure, largest first, with no way to turn it off. Only the mechanism
+it named has to widen, because that ADR assumed every measure is an
+aggregate with an alias and a ratio is not.
+
+## Consequences
+
+- A host with a boolean column declares one line and gets a rate that
+  cross filters, gap fills, snapshots and orders like any other measure.
+- `rails janela:doctor` has nothing to add. The declaration either
+  raises at boot or is correct, so there is no silent state for a check
+  to find.
+- **A measure that wants the fraction rather than the percentage cannot
+  have it.** That is the cost of refusing the flag, and it is a real
+  one: a host wanting `0.31` on a dashboard has to use `average:` over
+  a numeric column of its own. If that turns up in practice, the answer
+  is a format on the measure, not on the pane, and ADR 020 already says
+  which layer that is.
+- `Measure#sql_alias` is gone. It is internal rather than documented
+  surface, with one call site in the gem, but a fork that reached for it
+  will not find it, so it needs a line in `CHANGELOG.md` under Changed
+  rather than an `UPGRADING.md` step (ADR 015): nothing a host declares
+  changes.
+- #20's error message names `ratio:`, which closes the loop the refusal
+  opened. That string is what a host actually meets, so it is part of
+  the work rather than a nicety.
+- What would change this decision: a host that needs a rate over
+  something that is not a boolean column and for which the split is
+  genuinely wrong. That is the case the condition form was rejected for,
+  and one real report of it is better evidence than the argument above.