janela 0.8.0 → 0.10.0

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, :default, :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,15 @@ 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: {}, default: {}, snapshot: nil, title: nil)
       @definition = definition
       @title = title
       @measure = measure
       @dimension = dimension
       @renderer = renderer.to_s
       @filters = filters
+      @fixed = fixed
+      @default = default
       @snapshot = snapshot
 
       raise BadRequest, "unknown pane renderer #{renderer.inspect}" unless RENDERERS.include?(@renderer)
@@ -97,6 +99,12 @@ module Janela
     def result(on: nil)
       return snapshot.stored_result(self) if frozen?
 
+      # Default, then fixed, then the reader's: a frame's own permanent
+      # filter narrows first, a host's per-record filter narrows again, and
+      # both apply even on this pane's own dimension, unlike the reader's
+      # selection, which this pane shows the alternatives to (ADR 040, 043).
+      on = definition.narrow(on || model.all, default) if default.present?
+      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 %>

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/db/migrate/20260928000001_add_default_filter_to_janela_frames.rb

@@ -0,0 +1,10 @@
+class AddDefaultFilterToJanelaFrames < ActiveRecord::Migration[8.0]
+  def change
+    # A frame's own permanent filter (ADR 043): only a pane over
+    # default_model takes it, so a frame that holds panes from more than one
+    # model is never narrowed by a condition that is not about it. Present
+    # or absent together; every existing frame has neither.
+    add_column :janela_frames, :default_model, :string
+    add_column :janela_frames, :default_where, :json
+  end
+end

data/docs/composing.md

@@ -0,0 +1,288 @@
+---
+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:`.
+
+## A frame's own permanent filter
+
+Some conditions are not about which record's page this is, they are
+true every time: "this queue never counts an archived row." `where:` is
+code, written into a view, run again on every render. A frame's own
+default filter is data instead, so an analyst changes it without a
+deploy (ADR 043):
+
+```ruby
+frame.update!(default_model: "orders", default_where: { status_in: %w[paid pending] })
+```
+
+`default_model` says which model the condition is about, so a frame
+holding panes from more than one model is never narrowed by a condition
+that was never about the pane reading it. It is validated when you save
+it, against that model's declared dimensions, rather than only
+discovered wrong the next time a pane renders. Set both columns
+together; either alone is a validation error.
+
+## 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.