janela 0.11.0 → 0.13.0

data/app/models/janela/query.rb

@@ -18,7 +18,22 @@ module Janela
     # categories the same beside a legend that says they differ (ADR 046).
     SERIES = 8
 
-    attr_reader :definition, :measure, :dimension, :renderer, :limit, :filters, :fixed, :default, :snapshot
+    # The steps a chart's height may take (ADR 047). Pane::HEIGHTS is the same
+    # range for a stored row, and a test holds the two together.
+    HEIGHTS = (1..5).freeze
+
+    # The steps a single value's prominence may take (ADR 050).
+    PROMINENCES = (1..3).freeze
+
+    # Each companion column is a query of its own, so how many a pane may run
+    # is bounded, as what one query may ask for is (ADR 051, ADR 025).
+    MAX_COMPANIONS = 3
+
+    # A column beside a table's label: a measure's formatted numbers, or a
+    # dimension's shared fact, by label.
+    Companion = Struct.new(:name, :header, :fact, :cells, keyword_init: true)
+
+    attr_reader :definition, :measure, :dimension, :renderer, :limit, :height, :prominence, :companions, :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.
@@ -28,7 +43,7 @@ module Janela
       parts.compact.join("_")
     end
 
-    def initialize(definition:, measure:, dimension: nil, renderer: "table", granularity: nil, limit: nil, filters: {}, fixed: {}, default: {}, snapshot: nil, title: nil)
+    def initialize(definition:, measure:, dimension: nil, renderer: "table", granularity: nil, limit: nil, height: nil, prominence: nil, companions: nil, filters: {}, fixed: {}, default: {}, snapshot: nil, title: nil)
       @definition = definition
       @title = title
       @measure = measure
@@ -42,6 +57,9 @@ module Janela
       raise BadRequest, "unknown pane renderer #{renderer.inspect}" unless RENDERERS.include?(@renderer)
       @granularity = Dimension.granularity!(granularity) if granularity.present?
       @limit = definition.limit!(limit) if limit.present?
+      @height = height!(height) if height.present?
+      @prominence = prominence!(prominence) if prominence.present?
+      @companions = companions!(companions)
     end
 
     def model
@@ -82,6 +100,20 @@ module Janela
       !single_value? && CANVAS.include?(renderer)
     end
 
+    # A height means a box only where there is a canvas to fill it. A ring, a
+    # table and a single value ignore one, so switching a pane between
+    # renderers never invalidates it (ADR 047).
+    # Only a single value has a headline number to make more or less of. A
+    # table, a chart and a ring ignore one, so a pane switched between renderers
+    # keeps what it had (ADR 050).
+    def prominent?
+      single_value? && !prominence.nil?
+    end
+
+    def boxed?
+      chart? && !height.nil?
+    end
+
     def ring?
       !single_value? && RINGS.include?(renderer)
     end
@@ -188,9 +220,30 @@ module Janela
       # 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?
-      return time_result(on) if time?
+      primary = time? ? time_result(on) : definition.query(measure, by: dimension, where: applicable_filters, on: on, granularity: granularity, limit: limit)
+      @companion_columns = companions? ? fetch_companions(primary, on) : []
+      primary
+    end
+
+    # Only a table draws companion columns, and a stored pane is the record of
+    # a moment that holds none (ADR 051).
+    def companions?
+      renderer == "table" && !single_value? && !frozen? && companions.any?
+    end
+
+    # The columns beside the label, once a result has been read. Kept from the
+    # same read as the result, with the same scope and filters, the way a time
+    # pane keeps its buckets.
+    def companion_columns
+      @companion_columns || []
+    end
+
+    def dimension_header
+      dimension.to_s.humanize
+    end
 
-      definition.query(measure, by: dimension, where: applicable_filters, on: on, granularity: granularity, limit: limit)
+    def measure_header
+      measure.to_s.humanize
     end
 
     # The two filters a click on this label writes, for a time pane: the start
@@ -290,6 +343,65 @@ module Janela
         }.keys
       end
 
+      def companions!(value)
+        return [] if value.blank?
+        raise BadRequest, "companions must be a list of measure and dimension names, got #{value.class}" unless value.is_a?(Array) && value.all? { |each| each.is_a?(String) || each.is_a?(Symbol) }
+
+        names = value.map(&:to_sym)
+        raise BadRequest, "a pane may carry at most #{MAX_COMPANIONS} companions, got #{names.size}" if names.size > MAX_COMPANIONS
+        raise BadRequest, "companions must each be named once, got #{names.map(&:inspect).join(', ')}" unless names == names.uniq
+
+        names.each { |name| companion!(name) }
+      end
+
+      # Only what the model declared, by the name it declared it under: no
+      # column, no expression, nothing that becomes SQL (ADR 025, ADR 051).
+      def companion!(name)
+        declared = definition.measures.keys + definition.dimensions.keys
+        raise BadRequest, "#{name.inspect} is not a declared measure or dimension of #{model}. Declared: #{declared.join(', ')}" unless declared.include?(name)
+        raise BadRequest, "#{name.inspect} is this pane's own #{name == measure ? 'measure' : 'dimension'}" if name == measure || name == dimension
+        return if definition.measures.key?(name)
+
+        fact = definition.dimensions.fetch(name)
+        raise BadRequest, "#{name.inspect} is a time dimension, and a bucket is not a fact about a label" if fact.time?
+        raise BadRequest, "#{name.inspect} is a dimension, which a time pane has no shared fact to show" if dimension && definition.dimension!(dimension).time?
+      end
+
+      # Ordering and the limit belong to the primary measure. The companions are
+      # fetched for the labels it chose, one grouped query for each measure and
+      # one for all the dimensions (ADR 051).
+      def fetch_companions(primary, on)
+        keys = time? ? nil : primary.keys
+        facts = companions.reject { |name| definition.measures.key?(name) }
+        shared = facts.any? ? definition.facts(facts, by: dimension, where: applicable_filters, on: on, keys: keys) : {}
+
+        companions.map do |name|
+          if definition.measures.key?(name)
+            values = definition.query(name, by: dimension, where: applicable_filters, on: on, granularity: granularity, keys: keys)
+            formatted = definition.measure!(name)
+            Companion.new(name: name, header: name.to_s.humanize, fact: false,
+                          cells: primary.keys.to_h { |label| [ label, formatted.format(values[label]) ] })
+          else
+            Companion.new(name: name, header: name.to_s.humanize, fact: true,
+                          cells: primary.keys.to_h { |label| [ label, shared.dig(label, name).to_s ] })
+          end
+        end
+      end
+
+      def prominence!(value)
+        step = Integer(value.to_s, exception: false)
+        raise BadRequest, "prominence must be a whole number from #{PROMINENCES.first} to #{PROMINENCES.last}, got #{value.inspect}" unless PROMINENCES.cover?(step)
+
+        step
+      end
+
+      def height!(value)
+        step = Integer(value.to_s, exception: false)
+        raise BadRequest, "height must be a whole number from #{HEIGHTS.first} to #{HEIGHTS.last}, got #{value.inspect}" unless HEIGHTS.cover?(step)
+
+        step
+      end
+
       def applicable_filters
         return filters if single_value?
 

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

@@ -41,6 +41,31 @@
     <%= form.select :limit, Janela::Pane::OFFERED_LIMITS, include_blank: t("janela.panes.no_limit") %>
   </div>
 
+  <%# What may sit beside the label: this model's other measures and its
+      categorical dimensions. The pane's own choices are left out when they are
+      already made (ADR 051). %>
+  <%
+    companion_choices = {
+      t("janela.companions.measures") => definition.measures.keys.reject { |name| name.to_s == pane.measure }.map { |name| [ name.to_s.humanize, name ] },
+      t("janela.companions.dimensions") => definition.dimensions.values.reject { |each| each.time? || each.name.to_s == pane.dimension }.map { |each| [ each.name.to_s.humanize, each.name ] }
+    }
+  %>
+  <div class="janela-field">
+    <%= form.label :companions %>
+    <%= form.select :companions, companion_choices, {}, multiple: true %>
+    <span class="janela-hint"><%= t("janela.companions.hint") %></span>
+  </div>
+
+  <div class="janela-field">
+    <%= form.label :height %>
+    <%= form.select :height, Janela::Pane::HEIGHTS.map { |step| [ t("janela.heights.#{step}"), step ] }, include_blank: t("janela.heights.automatic") %>
+  </div>
+
+  <div class="janela-field">
+    <%= form.label :prominence %>
+    <%= form.select :prominence, Janela::Pane::PROMINENCES.map { |step| [ t("janela.prominences.#{step}"), step ] }, include_blank: t("janela.prominences.automatic") %>
+  </div>
+
   <div class="janela-field">
     <%= form.label :span %>
     <%= form.select :span, Janela::Pane::SPANS.to_a %>

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

@@ -1,10 +1,10 @@
 <%# One pane's content, without its turbo frame: the same markup whether the
     pane came from a URL, a row, or a frame rendered inline. %>
 <% if query.single_value? %>
-  <p class="janela-pane janela-value">
+  <%= tag.p class: [ "janela-pane", "janela-value", ("janela-prominence-#{query.prominence}" if query.prominent?) ] do %>
     <span class="janela-value-label"><%= query.title %></span>
     <strong class="janela-value-number"><%= query.format(result || 0) %></strong>
-  </p>
+  <% end %>
 <% elsif result.empty? %>
   <p class="janela-pane janela-empty"><%= query.title %>: no data</p>
 <% elsif query.ring? && query.ringable?(result) %>
@@ -13,22 +13,41 @@
   <% 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 %>"
-            <%= tag.attributes(aria: { description: (t("janela.time.click_hint") if query.time? && query.clickable?) }) %>
-            role="img" aria-labelledby="<%= title_id %>"></canvas>
+    <%# A height puts the canvas in a box of fixed size for the chart to fill;
+        with none there is no box and the chart is what it always was (ADR 047). %>
+    <% canvas = tag.canvas(
+         class: "janela-chart", role: "img",
+         aria: { labelledby: title_id, description: (t("janela.time.click_hint") if query.time? && query.clickable?) },
+         data: {
+           controller: "janela--chart",
+           action: "janela--chart:toggle->janela--frame#toggle",
+           "janela--chart-type-value": query.renderer,
+           "janela--chart-title-value": query.title,
+           "janela--chart-selected-value": query.selected_values.to_json,
+           "janela--chart-labels-value": result.keys.to_json,
+           "janela--chart-values-value": result.values.map(&:to_f).to_json,
+           "janela--chart-formatted-value": result.values.map { |measured| query.format(measured) }.to_json,
+           "janela--chart-filters-value": query.filters_for(result.keys).to_json,
+           "janela--chart-fixed-height-value": (true if query.boxed?)
+         }) %>
+    <%= query.boxed? ? tag.div(canvas, class: "janela-chart-box janela-h-#{query.height}") : canvas %>
   </figure>
 <% else %>
   <%= tag.table class: "janela-pane", aria: { description: (t("janela.time.click_hint") if query.time? && query.clickable?) } do %>
     <caption><%= query.title %></caption>
+    <%# A header row only when there are companions to name: two columns read
+        without one, and a table with none is what it always was (ADR 051). %>
+    <% if query.companion_columns.any? %>
+      <thead>
+        <tr>
+          <th scope="col"><%= query.dimension_header %></th>
+          <th scope="col"><%= query.measure_header %></th>
+          <% query.companion_columns.each do |column| %>
+            <%= tag.th column.header, scope: "col", class: ("janela-fact" if column.fact) %>
+          <% end %>
+        </tr>
+      </thead>
+    <% end %>
     <tbody>
       <% result.each do |label, measured| %>
         <% click = query.click_data(label) if query.clickable? %>
@@ -42,6 +61,9 @@
             <% end %>
           </td>
           <td><%= query.format(measured) %></td>
+          <% query.companion_columns.each do |column| %>
+            <%= tag.td column.cells[label], class: ("janela-fact" if column.fact) %>
+          <% end %>
         </tr>
       <% end %>
     </tbody>

data/config/locales/en.yml

@@ -20,6 +20,9 @@ en:
         granularity: Granularity
         limit: Rows
         span: Width
+        height: Height
+        prominence: Prominence
+        companions: Beside the label
         title: Title
   janela:
     actions:
@@ -64,6 +67,22 @@ en:
       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
+    companions:
+      measures: Measures
+      dimensions: Dimensions
+      hint: Up to three, drawn as columns in a table. A dimension shows a value only where every row of its group shares one.
+    prominences:
+      automatic: Automatic
+      "1": Footnote
+      "2": Normal
+      "3": Hero
+    heights:
+      automatic: Automatic
+      "1": Very short
+      "2": Short
+      "3": Medium
+      "4": Tall
+      "5": Very tall
     renderers:
       bar: Bar chart
       doughnut: Doughnut chart

data/db/migrate/20260930000001_add_height_to_janela_panes.rb

@@ -0,0 +1,7 @@
+class AddHeightToJanelaPanes < ActiveRecord::Migration[8.0]
+  def change
+    # How tall a bar or line chart is drawn, one of five steps (ADR 047). Null
+    # is what every existing pane is: unset, and drawn exactly as before.
+    add_column :janela_panes, :height, :integer
+  end
+end

data/db/migrate/20260930000002_add_prominence_to_janela_panes.rb

@@ -0,0 +1,7 @@
+class AddProminenceToJanelaPanes < ActiveRecord::Migration[8.0]
+  def change
+    # How prominent a single value is drawn, one of three steps (ADR 050).
+    # Null is what every existing pane is: unset, and drawn exactly as before.
+    add_column :janela_panes, :prominence, :integer
+  end
+end

data/db/migrate/20260930000003_add_companions_to_janela_panes.rb

@@ -0,0 +1,8 @@
+class AddCompanionsToJanelaPanes < ActiveRecord::Migration[8.0]
+  def change
+    # Measures and dimensions a table pane draws as columns beside its label
+    # (ADR 051), by the names the model declared them under. Null is what
+    # every existing pane is: none, and drawn exactly as before.
+    add_column :janela_panes, :companions, :json
+  end
+end

data/docs/agents.md

@@ -0,0 +1,97 @@
+---
+Topics: agents, mcp, tools, authorisation, host-integration
+---
+
+# Giving an Agent Access to Janela
+
+Frames and panes are rows (ADR 012), so an agent could always arrange a
+dashboard by writing them from a console. This page is for giving it tools
+instead: read a frame, read a pane's values, and, if you choose, add, change,
+remove and move panes. The reasoning is in ADR 053.
+
+The short version: Janela gives you the tool definitions as plain Ruby. You
+build them with the answer to "what may this caller read", and you register
+them with whatever MCP library your application already runs. Janela
+registers nothing, detects nothing and serves nothing, because it cannot
+know who is asking and your application can.
+
+## Building the tools
+
+```ruby
+tools = Janela::Tools.new(scope: ->(model) { policy_scope(model) })
+```
+
+`scope:` is required. It takes a model class and returns a relation: the same
+answer your `policy_scope` gives a Janela controller (ADR 032). Leave it out
+and `Janela::Unscoped` is raised when the tools are built, because a tool with
+no scope would read every row of every model. Every read the tools make passes
+that relation, and frames and panes are found through it too, so a caller can
+change only what it can see.
+
+Build the tools where you know who is asking, which for an MCP server is when a
+tool is called. They are cheap to construct.
+
+## What they do
+
+| Tool | Does | Needs `write: true` |
+| --- | --- | --- |
+| `describe_vocabulary` | The models, measures, dimensions, renderers and granularities the `janela` blocks declare. An agent should offer nothing else. | no |
+| `list_frames` | The frames the scope returns: id, name, owner, pane count. | no |
+| `get_frame` | One frame with its panes in position order. | no |
+| `read_pane` | A pane's values, through the scope. Filters are Ransack predicates on declared dimensions, bounded as a reader's are (ADR 025). | no |
+| `add_pane` | Add a pane to the end of a frame. | yes |
+| `update_pane` | Change a pane. An invalid change leaves it as it was. | yes |
+| `remove_pane` | Remove a pane and close the gap. | yes |
+| `move_pane` | Move a pane one place up or down. | yes |
+
+The write tools are off unless you build the tools with `write: true`. Their
+inputs are the pane's own attributes, the ones the README
+names, and nothing else: an attribute that is not a pane's is refused rather
+than dropped. A pane Janela would refuse is refused with its own reason, for
+example `Measure "nonsense" is not a measure of Order`.
+
+There is no tool to create a frame or take a snapshot. Your code finds or makes
+a frame with `Janela::Frame.for` (ADR 041), and a snapshot needs an owner and a
+scope you have named (ADR 033, ADR 034).
+
+## Registering them
+
+`Janela::Tools.all` is the list of definitions, and needs no scope: each has a
+`name`, a `description`, an `input_schema` (JSON Schema) and `read_only`.
+`tools.call(name, arguments)` runs one and returns a Hash, or raises a
+`Janela::Error` (`NotFound`, `BadRequest` or `Unscoped`) that an adapter reports
+to the agent as the tool's own error.
+
+For the official Ruby SDK, the `mcp` gem, an adapter looks like this. It is run
+by Janela's own tests, so it cannot drift from the code. `server_context` is
+whatever your server was built with, and is where you keep the caller; the
+scope is built from it at the moment of the call.
+
+```ruby
+def janela_server(write: false)
+  tools = Janela::Tools.all(write: write).map do |tool|
+    MCP::Tool.define(name: tool.name, description: tool.description, input_schema: tool.input_schema,
+                     annotations: { read_only_hint: tool.read_only }) do |server_context:, **arguments|
+      # The scope is built per call, because who is asking is known only now.
+      scope = ->(model) { server_context[:scope].call(model) }
+      result = Janela::Tools.new(scope: scope, write: write).call(tool.name, arguments)
+      MCP::Tool::Response.new([ { type: "text", text: result.to_json } ])
+    rescue Janela::Error => error
+      MCP::Tool::Response.new([ { type: "text", text: error.message } ], error: true)
+    end
+  end
+
+  MCP::Server.new(name: "janela", tools: tools, server_context: { scope: yield })
+end
+```
+
+`mcp` is not a dependency of Janela, and a host using another library writes the
+same few lines against it.
+
+## What Janela does not do
+
+It does not serve MCP, detect a server, edit your configuration or install
+anything. It holds no credentials and has no idea who your agent is. Whether an
+agent may reach your MCP server at all is your server's authentication, which
+Janela never sees. Everything it adds is the question it already asks: what may
+this caller read?

data/docs/composing.md

@@ -23,12 +23,12 @@ with your own classes plus the hooks in [Theming Janela](theming).
 | `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.
+A stored frame renders panes, and a pane is either a query, a few words
+the analyst writes (a heading, a sentence, a link), or a partial you
+wrote and they place by name (ADR 039). What an analyst writes is
+escaped, never markup, so a row cannot put arbitrary content on the page
+(ADR 012). Anything richer than that, an icon, an image, a layout of your
+own, goes in the page around the frame, or use the block form.
 
 ```erb
 <h2>Orders</h2>
@@ -58,9 +58,9 @@ same classes a stored frame gets from its integers:
 
 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:
+`janela_pane` takes no class of its own, and will not: arranging panes
+beyond the shipped grid is the host's (see the roadmap). So wrap a pane
+to span it:
 
 ```erb
 <div class="janela-span-2"><%= janela_pane Order, :revenue, by: :status, as: :bar %></div>
@@ -195,11 +195,11 @@ 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 done out of total figure over a yes or no column is one pane: a
+`ratio:` measure is the share of rows where a boolean is true (ADR 038).
+When the condition is not a column, 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 progress bar
 

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

@@ -1,6 +1,6 @@
 ---
 Date: 2026-09-16
-Status: Accepted
+Status: Accepted (the exclusive null group paragraph is superseded by ADR 049)
 Related: ADR 003, ADR 005, ADR 008, ADR 009, ADR 018
 Triggers:
   - changing what a click on a value does

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

@@ -1,6 +1,6 @@
 ---
 Date: 2026-09-24
-Status: Proposed
+Status: Accepted
 Related: ADR 001, ADR 002, ADR 007, ADR 020, ADR 025
 Triggers:
   - adding a measure kind, or a sixth aggregate to the DSL