janela 0.2.0 → 0.3.0

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

@@ -1,45 +1,4 @@
-<%= turbo_frame_tag @pane.frame_id do %>
-  <% if @pane.single_value? %>
-    <p class="janela-pane janela-value">
-      <span class="janela-value-label"><%= @pane.title %></span>
-      <strong class="janela-value-number"><%= number_with_delimiter(@result || 0) %></strong>
-    </p>
-  <% elsif @result.empty? %>
-    <p class="janela-pane janela-empty"><%= @pane.title %>: no data</p>
-  <% elsif @pane.chart? %>
-    <canvas class="janela-pane janela-chart"
-            data-controller="janela--chart"
-            data-action="janela--chart:toggle->janela--dashboard#toggle"
-            data-janela--chart-type-value="<%= @pane.renderer %>"
-            data-janela--chart-title-value="<%= @pane.title %>"
-            data-janela--chart-key-value="<%= @pane.filter_key %>"
-            data-janela--chart-selected-value="<%= @pane.selected_value %>"
-            data-janela--chart-labels-value="<%= @result.keys.to_json %>"
-            data-janela--chart-values-value="<%= @result.values.map(&:to_f).to_json %>"
-            role="img" aria-label="<%= @pane.title %>"></canvas>
-  <% else %>
-    <table class="janela-pane">
-      <caption><%= @pane.title %></caption>
-      <tbody>
-        <% @result.each do |value, measured| %>
-          <tr>
-            <td>
-              <% if @pane.clickable? %>
-                <button type="button"
-                        aria-pressed="<%= value.to_s == @pane.selected_value.to_s && @pane.selected_value.present? %>"
-                        data-action="janela--dashboard#toggle"
-                        data-janela--dashboard-key-param="<%= @pane.filter_key %>"
-                        data-janela--dashboard-value-param="<%= value %>">
-                  <%= value %>
-                </button>
-              <% else %>
-                <span><%= value %></span>
-              <% end %>
-            </td>
-            <td><%= number_with_delimiter(measured) %></td>
-          </tr>
-        <% end %>
-      </tbody>
-    </table>
-  <% end %>
+<% content_for :title, @query.title %>
+<%= turbo_frame_tag @pane.turbo_frame_id do %>
+  <%= render "janela/queries/query", query: @query, result: @result %>
 <% end %>

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

@@ -0,0 +1,47 @@
+<%# 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">
+    <span class="janela-value-label"><%= query.title %></span>
+    <strong class="janela-value-number"><%= query.format(result || 0) %></strong>
+  </p>
+<% 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_value %>"
+          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>
+<% else %>
+  <table class="janela-pane">
+    <caption><%= query.title %></caption>
+    <tbody>
+      <% result.each do |label, measured| %>
+        <% key, value = query.filter_params(label) %>
+        <tr>
+          <td>
+            <% if key %>
+              <button type="button"
+                      aria-pressed="<%= label.to_s == query.selected_value.to_s && query.selected_value.present? %>"
+                      data-action="janela--frame#toggle"
+                      data-janela--frame-key-param="<%= key %>"
+                      data-janela--frame-value-param="<%= value %>">
+                <%= label %>
+              </button>
+            <% else %>
+              <span><%= label %></span>
+            <% end %>
+          </td>
+          <td><%= query.format(measured) %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+<% end %>

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

@@ -0,0 +1,4 @@
+<% content_for :title, @query.title %>
+<%= turbo_frame_tag @query.turbo_frame_id do %>
+  <%= render "janela/queries/query", query: @query, result: @result %>
+<% end %>

data/app/views/janela/shared/_errors.html.erb

@@ -0,0 +1,7 @@
+<% if record.errors.any? %>
+  <ul class="janela-errors">
+    <% record.errors.full_messages.each do |message| %>
+      <li><%= message %></li>
+    <% end %>
+  </ul>
+<% end %>

data/app/views/layouts/janela/application.html.erb

@@ -0,0 +1,26 @@
+<%# Janela's own pages and a pane opened directly, outside a Turbo Frame.
+    Deliberately minimal: the engine cannot know the host's asset names or
+    bundler, and a host layout's route helpers do not resolve inside an
+    isolated engine (ADR 011). It loads Janela's own stylesheet, which the gem
+    ships and can therefore name, and no JavaScript: Turbo and Stimulus come
+    from the host, so these pages are static dashboards rather than broken
+    ones. A host can override this file, or point the controller at its own
+    layout. %>
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= yield(:title).presence || "Janela" %></title>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+    <%= stylesheet_link_tag "janela" %>
+    <%= yield :head %>
+  </head>
+  <body class="janela-page">
+    <% flash.each do |_kind, message| %>
+      <p class="janela-flash"><%= message %></p>
+    <% end %>
+    <%= yield %>
+  </body>
+</html>

data/config/importmap.rb

@@ -1,4 +1,4 @@
-pin "janela/dashboard_controller", to: "janela/dashboard_controller.js"
+pin "janela/frame_controller", to: "janela/frame_controller.js"
 pin "janela/chart_controller", to: "janela/chart_controller.js"
 
 # Hosts that already pin their own Chart.js keep it.

data/config/locales/en.yml

@@ -0,0 +1,64 @@
+en:
+  activerecord:
+    models:
+      janela/frame:
+        one: Frame
+        other: Frames
+      janela/pane:
+        one: Pane
+        other: Panes
+    attributes:
+      janela/frame:
+        name: Name
+        columns: Columns
+        gap: Gap
+      janela/pane:
+        model: Model
+        measure: Measure
+        dimension: Dimension
+        renderer: Renderer
+        granularity: Granularity
+        limit: Rows
+        span: Width
+        title: Title
+  janela:
+    actions:
+      add_pane: "Add a %{name}"
+      cancel: Cancel
+      continue: Continue
+      delete: Remove
+      delete_frame: "Delete this %{name}"
+      edit: Edit
+      move_down: Down
+      move_up: Up
+      new_frame: "New %{name}"
+      save: Save
+      view: View
+    frames:
+      created: Created.
+      destroyed: Deleted.
+      updated: Saved.
+      index:
+        blank: "No %{name} yet."
+      edit:
+        blank: "No %{name} yet."
+      frame:
+        panes:
+          zero: no panes
+          one: 1 pane
+          other: "%{count} panes"
+        changed: "changed %{time} ago"
+    panes:
+      created: Added.
+      destroyed: Removed.
+      updated: Saved.
+      declared_granularity: As the model declares it
+      granularity_hint: "Applies to %{dimensions} only."
+      no_dimension: "No breakdown, one number"
+      no_limit: Every row
+      summary: "%{renderer}, %{span} wide"
+      title_placeholder: Janela writes one if you leave this blank
+    renderers:
+      bar: Bar chart
+      line: Line chart
+      table: Table

data/config/routes.rb

@@ -1,9 +1,22 @@
 Janela::Engine.routes.draw do
   segment = /[a-z0-9_]+/
 
-  get "snapshots/:snapshot_id/:model/:measure(/:dimension)", to: "snapshot_panes#show", as: :snapshot_pane,
+  # Frames sit at the mount root and are drawn before the pane grammar, with a
+  # numeric constraint: no model's route key is all digits, so /3 is a frame
+  # and /orders/revenue is a pane, with nothing to disambiguate (ADR 014).
+  resources :frames, path: "", constraints: { id: /\d+/ } do
+    # No index: a frame's own edit page is the list of its panes.
+    resources :panes, except: :index, constraints: { id: /\d+/, frame_id: /\d+/ } do
+      member do
+        patch :move_up
+        patch :move_down
+      end
+    end
+  end
+
+  get "snapshots/:snapshot_id/:model/:measure(/:dimension)", to: "snapshot_queries#show", as: :snapshot_pane,
     constraints: { snapshot_id: /\d+/, model: segment, measure: segment, dimension: segment }
 
-  get ":model/:measure(/:dimension)", to: "panes#show", as: :pane,
+  get ":model/:measure(/:dimension)", to: "queries#show", as: :pane,
     constraints: { model: segment, measure: segment, dimension: segment }
 end

data/db/migrate/20260916000001_create_janela_frames.rb

@@ -0,0 +1,13 @@
+class CreateJanelaFrames < ActiveRecord::Migration[8.0]
+  def change
+    create_table :janela_frames do |t|
+      t.string :name, null: false
+      t.integer :columns, null: false, default: 3
+      t.integer :gap, null: false, default: 4
+      # Janela never reads the owner. It is here so a host's Pundit Scope has
+      # something to filter a frame on (ADR 014).
+      t.references :owner, polymorphic: true, null: true
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260916000002_create_janela_panes.rb

@@ -0,0 +1,22 @@
+class CreateJanelaPanes < ActiveRecord::Migration[8.0]
+  def change
+    create_table :janela_panes do |t|
+      # The composite index below is the one a frame's panes are read by, so
+      # references adds none of its own.
+      t.references :frame, null: false, index: false, foreign_key: { to_table: :janela_frames }
+      t.integer :position, null: false
+      t.integer :span, null: false, default: 1
+      # A model's route key, the same identifier a pane URL carries (ADR 005).
+      t.string :model, null: false
+      t.string :measure, null: false
+      t.string :dimension
+      t.string :renderer, null: false, default: "table"
+      t.string :granularity
+      t.integer :limit
+      t.string :title
+      t.timestamps
+    end
+
+    add_index :janela_panes, [ :frame_id, :position ]
+  end
+end

data/docs/decisions/001-built-to-be-forked.md

@@ -71,3 +71,7 @@ Janela is designed to be forked, not just configured.
   special-casing Janela itself.
 - Future scope decisions (what's in the 5%, what isn't) should cite
   this ADR rather than re-litigate the philosophy each time.
+- The exclusion of a report designer was partly superseded by ADR 012:
+  composition became data, because this ADR assumed the developer
+  authored dashboards and the author is the analyst. The reasoning
+  still holds for the query vocabulary, which stays in code.

data/docs/decisions/005-pane-urls-and-mount-path.md

@@ -1,7 +1,7 @@
 ---
 Date: 2026-09-15
 Status: Accepted
-Related: ADR 001, ADR 002, ADR 003, ADR 004
+Related: ADR 001, ADR 002, ADR 003, ADR 004, ADR 011
 Triggers:
   - changing the URL of a pane or how a dashboard frame addresses one
   - mounting the engine anywhere other than the default, or with as:
@@ -134,3 +134,6 @@ author reached for unprompted.
 - Looking up the mount in the host's route table means the helper
   finds the first mount of the engine. Mounting Janela twice is
   unsupported and not a goal.
+- The claim above that a directly opened pane renders "inside the
+  host's layout" was wrong and is superseded by ADR 011: a host
+  layout's route helpers cannot resolve inside an isolated engine.

data/docs/decisions/009-snapshots.md

@@ -1,7 +1,8 @@
 ---
 Date: 2026-09-15
 Status: Accepted
-Related: ADR 001, ADR 002, ADR 005, ADR 008
+Related: ADR 001, ADR 002, ADR 005, ADR 008, ADR 012
+Superseded in part by: ADR 012
 Triggers:
   - publishing a dashboard or pane for an audience that must not see live data or slicers
   - adding a database table, migration or model to the engine
@@ -53,7 +54,9 @@ several panes frozen at the same instant under the same filters, so a
 `Janela::Snapshot` row holds a name, `taken_at`, the filters, and an
 array of pane results. There is no Dashboard model and no dashboard
 DSL: the host's page is the dashboard, and the host names the panes to
-freeze. If the host renders its live page from the same list it passes
+freeze. (Superseded in part by ADR 012: a dashboard is now a record,
+`Janela::Frame`, and a snapshot of a frame rather than of a list is
+the obvious next shape. Nothing about what a snapshot stores changes.) If the host renders its live page from the same list it passes
 here, nothing is declared twice.
 
 ```ruby

data/docs/decisions/010-agent-guidance-ships-the-agent-waits.md

@@ -0,0 +1,134 @@
+---
+Date: 2026-09-15
+Status: Accepted
+Related: ADR 001, ADR 005, ADR 009, ADR 012, ADR 014
+Superseded in part by: ADR 012
+Triggers:
+  - writing or changing guidance for AI agents about using Janela
+  - proposing that Janela ship an agent, a skill or an MCP surface to hosts
+  - adding generators or introspection tasks
+  - changing the public API in a way the guidance describes
+  - deciding what a host application receives on install beyond the code
+Topics: ai, agents, jan, skills, documentation, install, dx, scope
+---
+
+# ADR 010: Agent Guidance Ships, the Agent Waits
+
+## Context
+
+ADR 001 decided the reasoning behind Janela ships inside the gem, as
+ADRs, so a developer or their agent understands why a piece exists
+before changing it. That covers the *why*. Nothing covers the *how*,
+and the first real installation showed the gap has a price: three
+traps bit within an hour, each a one line fix found only by debugging.
+Ransack's allowlist is per class, so a `through:` dimension needs the
+associated model to allow the attribute. A host that bundles with
+esbuild has no importmap, so none of Janela's JavaScript loads and
+nothing cross filters while everything looks right. Janela's
+controllers are exactly as authenticated as the host's
+`ApplicationController`, which in a host that authenticates per
+controller means not at all.
+
+None of that is derivable from reading the code, which is precisely
+the test ADR 001 sets for what belongs in the repository as prose.
+
+A second, larger idea came up alongside it: that Janela ship an agent
+of its own, named Jan, so installing the gem gives a host a briefed
+colleague rather than a briefing. Open source has always shipped code
+and documentation; it could now ship the person who knows how to use
+them. It is a genuinely novel idea and nobody is doing it.
+
+The two are not the same commitment, and this ADR separates them.
+
+## Decision
+
+**A skill ships with the gem and installs into the host.**
+`docs/skills/janela/SKILL.md` lives in the gem's `docs/` tree beside
+the ADRs. `rails janela:install:skill` copies it to the host's
+`.claude/skills/janela/` and prints the one line to add to an
+`AGENTS.md` or `CLAUDE.md` for tools that read those instead. Janela
+never edits a host's instruction files itself.
+
+The skill is knowledge, not instructions to a particular agent, which
+is why it survives whatever agent formats come and go.
+
+**What the skill covers, in this order:**
+
+1. The dashboard shape that works, and why: a row of single value
+   panes, a time series, then categorical breakdowns.
+2. Choosing measures and dimensions. Name them for what they mean and
+   alias through dimensions. Keep categories low cardinality or pass
+   `limit`. Declare time dimensions with the granularity people
+   actually ask about. A dimension declaration is a promise that
+   filtering on it is allowed.
+3. The naming table from ADR 005, so an analyst's sentence becomes a
+   pane URL and back.
+4. When to take a snapshot, and that a snapshot holds results, not
+   HTML.
+5. The three traps above, each with its one line fix.
+6. What Janela deliberately does not do, so an agent does not build
+   natural language query, row level security or a scheduler into the
+   host by accident. Composition is no longer on that list: ADR 012
+   made frames and panes records and ADR 014 sequenced the editing
+   surfaces, so the skill points an agent at those rather than telling
+   it to compose dashboards in ERB.
+
+**The skill describes the README's API and nothing else.** One API,
+one set of names. If the skill needs to say something the README does
+not, the README is incomplete and gets fixed first. No agent only
+vocabulary.
+
+**The demo application is the worked example.** `test/dummy` shows
+every construct on realistic data, deployed and clickable. The skill
+points at specific files rather than duplicating them.
+
+**Every code sample is executable.** Each sample in the skill and in
+`docs/guides/` is lifted from a file the test suite exercises, or is
+run by a test. A sample that cannot be run is written as a sentence,
+not a code block. This is the mechanism that stops the guidance
+drifting from the code.
+
+**Jan is not shipped to hosts yet.** An agent definition is added to
+this repository only, as the project's own collaborator, and is not
+copied into host applications by any install task. Three reasons:
+
+- Its method, read the models, declare dimensions, compose in the
+  standard shape, wire the install, verify in a browser, is what a
+  capable agent with the skill loaded already does. The marginal value
+  over the skill is a name to invoke and a guarantee the skill is
+  loaded. That is convenience, not capability, and convenience is not
+  worth a public surface.
+- Agent definition formats are unsettled. The skill's content is prose
+  about dashboards and survives any format; an agent definition is the
+  part most likely to be stale in six months.
+- A gem that writes a named agent into a host arrives with opinions
+  about how that team works, not only about what its code does. That
+  cuts against the posture in ADR 001, where the invitation is to read
+  the code and fork it.
+
+**What would change this.** Ship Jan to hosts when either is true:
+
+- Jan, used on this repository, demonstrably does something a skill
+  loaded agent does not. Name the thing in the ADR that supersedes
+  this one.
+- An MCP surface exists. An agent that can query dashboards and take
+  snapshots through tools has a job no skill can do, and at that point
+  a named agent stops being a wrapper and becomes a user.
+
+## Consequences
+
+- A host that installs Janela and runs one task gets an opinionated,
+  current briefing, including the three traps that cost real debugging
+  time. That is the concrete value of this layer and it lands now.
+- `docs/guides/` becomes a real directory shipping in the gem, so a
+  forker receives reasoning, rules and how to together.
+- Jan exists but only here. The agent that helps build the gem is the
+  agent that would one day help hosts, so drift between what Jan says
+  and what the code does surfaces in this repository first. That is
+  the trial period, and it is free.
+- Saying no to shipping Jan is recorded rather than remembered, with
+  the conditions that would reverse it. A future proposal cites this
+  ADR instead of relitigating the idea.
+- Introspection (`rails janela:describe Model`), generators and MCP
+  are each one ADR away. Each must be a wrapper over the existing API,
+  for the same reason the skill must describe only one.

data/docs/decisions/011-panes-do-not-render-in-the-host-layout.md

@@ -0,0 +1,81 @@
+---
+Date: 2026-09-15
+Status: Accepted
+Related: ADR 003, ADR 005
+Triggers:
+  - changing which layout a pane renders in
+  - a host reporting NameError from its own layout when a pane loads
+  - adding anything to the engine's own layout
+  - making the dummy application unrepresentative of a real host
+Topics: layouts, engines, panes, urls, install
+---
+
+# ADR 011: Panes Do Not Render in the Host Layout
+
+## Context
+
+ADR 005 promised that a pane opened directly "gets that pane alone
+inside the host's layout". Dogfooding 0.2.0 in a second application
+showed that promise is a bug. `Janela::ApplicationController` inherits
+the host's `ApplicationController` and therefore the host's layout,
+but the engine is `isolate_namespace`d, so a route helper written in
+that layout resolves against Janela's routes and raises `NameError`.
+Almost every real application layout has a nav, so almost every host
+is broken on install, and a whole dashboard of frames goes blank.
+
+The gem's own dummy application has no route helper in its layout,
+which is exactly why the suite, the demo and the first host install
+never saw it. The first host squeaked through because its only layout
+helpers were an Active Storage URL and a PWA manifest path rather
+than nav links.
+
+## Decision
+
+**A pane requested inside a Turbo Frame renders with no layout.**
+Turbo extracts the matching frame from the response and discards
+everything around it, so a layout was never doing any work there. This
+alone fixes every dashboard, which is how panes are almost always
+requested.
+
+**A pane requested directly renders in Janela's own layout.** A
+minimal layout in the engine, carrying only a charset, a viewport, the
+CSRF and CSP tags and a `yield`. It keeps ADR 005's shareable pane
+alive and cannot depend on anything the host has not got.
+
+```ruby
+layout -> { turbo_frame_request? ? false : "janela/application" }
+```
+
+**A directly opened pane is therefore unstyled, and that is
+documented.** Janela ships no CSS (issue #15), and the engine layout
+deliberately loads none of the host's assets, because it cannot know
+their names or whether the host bundles or uses importmap. A host that
+wants its own styling on direct pane URLs sets
+`Janela::ApplicationController.layout "application"` in an
+initializer, and is told the condition: that layout must not call a
+bare host route helper, since inside an engine those need a
+`main_app.` prefix.
+
+**The dummy application's layout gains a route helper.** The dummy is
+the gem's stand in for a real host, and a stand in that omits the most
+common thing a layout contains is not doing its job. A `link_to` to
+the dashboard makes the suite fail if a pane ever renders in the host
+layout again.
+
+## Consequences
+
+- ADR 005's sentence about the host layout is superseded by this ADR.
+  The rest of ADR 005, the URL grammar and the naming table, stands.
+- Direct pane URLs render a table but not a chart, because no
+  JavaScript is loaded. Shareable pane links are therefore honest for
+  data and plain for visuals until a host opts its own layout in.
+  Acceptable: the pane URL's job is to show a number to someone, and
+  the dashboard is where charts live.
+- The engine now owns a view that a host might want to override.
+  `app/views/layouts/janela/application.html.erb` is overridable by
+  the usual Rails precedence, which is the Rails answer and needs no
+  configuration of Janela's own.
+- The lesson generalises beyond layouts: the dummy application should
+  resemble a real host in the ways hosts actually vary. Each time a
+  host finds something the dummy could not, the dummy gains that
+  characteristic rather than the fix being verified only by hand.