janela 0.2.0 → 0.3.0

data/app/assets/stylesheets/janela.css

@@ -0,0 +1,163 @@
+/* Janela's own styling, small on purpose and meant to be overridden
+   (ADR 016). A host includes it with stylesheet_link_tag "janela"; the engine
+   never injects it into a layout it does not own.
+
+   The names follow one rule, janela-{property}-{scale}, and the scale is
+   the integer stored on the record. An analyst's number chooses a rule that
+   is already written here rather than reaching CSS as a length, so there is
+   nothing to inject and nothing to escape. */
+
+:root {
+  /* Retheme the whole spacing scale by setting this one value. */
+  --janela-space: 0.25rem;
+  --janela-line: rgba(128, 128, 128, 0.3);
+  --janela-accent: rgb(54, 162, 235);
+}
+
+.janela-frame { display: grid; }
+
+/* A grid item that cannot shrink below its content overflows the column, and
+   a chart is exactly that. */
+.janela-frame > * { min-width: 0; }
+
+.janela-cols-1 { grid-template-columns: repeat(1, minmax(0, 1fr)); }
+.janela-cols-2 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+.janela-cols-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+.janela-cols-4 { grid-template-columns: repeat(4, minmax(0, 1fr)); }
+.janela-cols-5 { grid-template-columns: repeat(5, minmax(0, 1fr)); }
+.janela-cols-6 { grid-template-columns: repeat(6, minmax(0, 1fr)); }
+.janela-cols-7 { grid-template-columns: repeat(7, minmax(0, 1fr)); }
+.janela-cols-8 { grid-template-columns: repeat(8, minmax(0, 1fr)); }
+.janela-cols-9 { grid-template-columns: repeat(9, minmax(0, 1fr)); }
+.janela-cols-10 { grid-template-columns: repeat(10, minmax(0, 1fr)); }
+.janela-cols-11 { grid-template-columns: repeat(11, minmax(0, 1fr)); }
+.janela-cols-12 { grid-template-columns: repeat(12, minmax(0, 1fr)); }
+
+.janela-gap-0 { gap: calc(var(--janela-space) * 0); }
+.janela-gap-1 { gap: calc(var(--janela-space) * 1); }
+.janela-gap-2 { gap: calc(var(--janela-space) * 2); }
+.janela-gap-3 { gap: calc(var(--janela-space) * 3); }
+.janela-gap-4 { gap: calc(var(--janela-space) * 4); }
+.janela-gap-5 { gap: calc(var(--janela-space) * 5); }
+.janela-gap-6 { gap: calc(var(--janela-space) * 6); }
+.janela-gap-7 { gap: calc(var(--janela-space) * 7); }
+.janela-gap-8 { gap: calc(var(--janela-space) * 8); }
+
+.janela-span-1 { grid-column: span 1; }
+.janela-span-2 { grid-column: span 2; }
+.janela-span-3 { grid-column: span 3; }
+.janela-span-4 { grid-column: span 4; }
+.janela-span-5 { grid-column: span 5; }
+.janela-span-6 { grid-column: span 6; }
+.janela-span-7 { grid-column: span 7; }
+.janela-span-8 { grid-column: span 8; }
+.janela-span-9 { grid-column: span 9; }
+.janela-span-10 { grid-column: span 10; }
+.janela-span-11 { grid-column: span 11; }
+.janela-span-12 { grid-column: span 12; }
+
+/* A dashboard nobody can read on a phone is not a choice worth offering, so
+   the collapse is here rather than in the data (ADR 016). */
+@media (max-width: 40rem) {
+  .janela-frame { grid-template-columns: minmax(0, 1fr); }
+  .janela-frame > * { grid-column: span 1; }
+}
+
+/* Enough base styling that a pane is legible on install (#15). Without it a
+   table pane runs its label into its number. */
+.janela-value { margin: 0; display: flex; flex-direction: column; gap: calc(var(--janela-space) * 1); }
+.janela-value-label { font-size: 0.85rem; opacity: 0.7; }
+.janela-value-number { font-size: 2rem; font-weight: 600; font-variant-numeric: tabular-nums; }
+
+table.janela-pane { width: 100%; border-collapse: collapse; }
+table.janela-pane caption { text-align: left; font-weight: 600; margin-bottom: calc(var(--janela-space) * 2); }
+table.janela-pane td { padding: calc(var(--janela-space) * 1.5) 0; border-top: 1px solid var(--janela-line); }
+table.janela-pane td:last-child { text-align: right; font-variant-numeric: tabular-nums; }
+table.janela-pane button {
+  font: inherit;
+  color: inherit;
+  background: none;
+  border: 0;
+  padding: calc(var(--janela-space) * 0.5) calc(var(--janela-space) * 2);
+  border-radius: 999px;
+  cursor: pointer;
+}
+table.janela-pane button:hover { background: var(--janela-line); }
+table.janela-pane button[aria-pressed="true"] { background: var(--janela-accent); color: white; }
+
+canvas.janela-chart { width: 100% !important; max-height: 20rem; }
+
+/* Janela's own pages (ADR 013). Scoped to a class the engine's layout sets,
+   so including this stylesheet changes nothing about a host's own pages. */
+.janela-page {
+  max-width: 70rem;
+  margin: 0 auto;
+  padding: calc(var(--janela-space) * 6);
+  font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+}
+.janela-heading { margin: 0 0 calc(var(--janela-space) * 2); font-size: 1.5rem; }
+.janela-crumb { margin: 0 0 calc(var(--janela-space) * 6); font-size: 0.875rem; opacity: 0.7; }
+.janela-card {
+  display: flex;
+  flex-direction: column;
+  gap: var(--janela-space);
+  padding: calc(var(--janela-space) * 4);
+  border: 1px solid var(--janela-line);
+  border-radius: calc(var(--janela-space) * 2);
+  color: inherit;
+  text-decoration: none;
+}
+.janela-card:hover { border-color: var(--janela-accent); }
+.janela-card-name { font-weight: 600; }
+.janela-card-meta { font-size: 0.875rem; opacity: 0.7; }
+.janela-subheading { margin: calc(var(--janela-space) * 8) 0 calc(var(--janela-space) * 2); font-size: 1.125rem; }
+.janela-muted, .janela-hint { font-size: 0.875rem; opacity: 0.7; }
+.janela-flash {
+  margin: 0 0 calc(var(--janela-space) * 4);
+  padding: calc(var(--janela-space) * 3);
+  border-radius: calc(var(--janela-space) * 2);
+  background: var(--janela-line);
+}
+
+/* The analyst's editing surface. Plain HTML controls, because these pages run
+   no JavaScript (ADR 018): every form submits and every button is a button. */
+.janela-form { display: flex; flex-direction: column; gap: calc(var(--janela-space) * 4); max-width: 30rem; }
+.janela-field { display: flex; flex-direction: column; gap: var(--janela-space); }
+.janela-field label { font-size: 0.875rem; font-weight: 600; }
+.janela-field input, .janela-field select {
+  font: inherit;
+  padding: calc(var(--janela-space) * 2);
+  border: 1px solid var(--janela-line);
+  border-radius: calc(var(--janela-space) * 1.5);
+  background: transparent;
+  color: inherit;
+}
+.janela-actions { display: flex; flex-wrap: wrap; gap: calc(var(--janela-space) * 3); align-items: center; }
+.janela-actions form { display: inline; }
+.janela-button {
+  font: inherit;
+  padding: calc(var(--janela-space) * 2) calc(var(--janela-space) * 4);
+  border: 1px solid var(--janela-line);
+  border-radius: calc(var(--janela-space) * 1.5);
+  background: transparent;
+  color: inherit;
+  text-decoration: none;
+  cursor: pointer;
+}
+.janela-button:hover { border-color: var(--janela-accent); }
+.janela-button[disabled] { opacity: 0.4; cursor: default; }
+.janela-danger { color: #b3261e; }
+.janela-errors { margin: 0; padding-left: calc(var(--janela-space) * 5); color: #b3261e; }
+.janela-list { list-style: none; margin: 0; padding: 0; }
+.janela-list-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: calc(var(--janela-space) * 3);
+  align-items: center;
+  padding: calc(var(--janela-space) * 3) 0;
+  border-top: 1px solid var(--janela-line);
+}
+.janela-list-name { flex: 1 1 12rem; font-weight: 600; }
+
+.janela-empty { margin: 0; opacity: 0.7; }
+.janela-error { margin: 0; }

data/app/controllers/janela/application_controller.rb

@@ -1,11 +1,56 @@
 module Janela
   class ApplicationController < Janela.parent_controller.constantize
+    # A frame request needs no layout, since Turbo keeps only the matching
+    # frame. A direct request gets Janela's own minimal layout, because a host
+    # layout's route helpers cannot resolve inside an isolated engine (ADR 011).
+    layout -> { turbo_frame_request? ? false : "janela/application" }
+
+    rescue_from Janela::NotFound, with: :janela_not_found
+    # A frame or a pane row the host's scope cannot see is the same answer as a
+    # measure that does not exist, and inside a turbo frame it has to be said
+    # in the frame rather than by the host's error page.
+    rescue_from ActiveRecord::RecordNotFound, with: :janela_not_found
+    rescue_from Janela::BadRequest, with: :janela_bad_request
+
     private
+      def filters
+        q = params[:q]
+        q.is_a?(ActionController::Parameters) ? q.permit!.to_h : {}
+      end
+
       # Pundit defines policy_scope on the host's ApplicationController, which
       # this inherits from, so authorisation applies without Janela depending
       # on Pundit or being configured.
       def janela_scope(model)
         respond_to?(:policy_scope, true) ? policy_scope(model) : model.all
       end
+
+      # A host that scopes frames by owner would hide a frame created without
+      # one, so the analyst's new dashboard would vanish as it was saved.
+      # Janela cannot know what owns a frame, so the host says, the same way it
+      # says what the scope is: by defining a method. A host with no tenancy
+      # defines nothing and gets a nil owner, which is right for it (ADR 014).
+      def janela_frame_owner
+        super if defined?(super)
+      end
+
+      def janela_not_found(error)
+        janela_error(error, :not_found, "There is no such pane.")
+      end
+
+      def janela_bad_request(error)
+        janela_error(error, :bad_request, "That request is not allowed on this pane.")
+      end
+
+      # The detail names models and filter keys, so it goes to the log; the
+      # client sees a plain sentence. A Turbo Frame request gets its frame
+      # back so the dashboard shows the sentence where the pane would be.
+      def janela_error(error, status, message)
+        logger.warn("Janela: #{error.message}")
+        body = view_context.tag.p(message, class: "janela-pane janela-error")
+        frame = request.headers["Turbo-Frame"]
+        body = view_context.turbo_frame_tag(frame) { body } if frame.present?
+        render html: body, status: status, layout: frame.blank?
+      end
   end
 end

data/app/controllers/janela/frames_controller.rb

@@ -0,0 +1,57 @@
+module Janela
+  # Janela's own pages, so a host can install the gem and navigate the same
+  # day (ADR 013), and the analyst's editing surface, as conventional Rails
+  # CRUD rather than a canvas (ADR 012, ADR 014). Every action reads through
+  # the host's scope rather than Frame.find, so another tenant's frame is a
+  # 404 to edit as well as to read.
+  class FramesController < ApplicationController
+    before_action :set_frame, only: %i[show edit update destroy]
+
+    def index
+      @frames = janela_scope(Frame).includes(:panes).order(:name)
+    end
+
+    def show
+    end
+
+    def new
+      @frame = Frame.new
+    end
+
+    def edit
+    end
+
+    def create
+      @frame = Frame.new(frame_params)
+      @frame.owner = janela_frame_owner
+
+      if @frame.save
+        redirect_to edit_frame_path(@frame), notice: t("janela.frames.created")
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def update
+      if @frame.update(frame_params)
+        redirect_to frame_path(@frame), notice: t("janela.frames.updated")
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      @frame.destroy
+      redirect_to frames_path, notice: t("janela.frames.destroyed")
+    end
+
+    private
+      def set_frame
+        @frame = janela_scope(Frame).find(params.require(:id))
+      end
+
+      def frame_params
+        params.expect(frame: [ :name, :columns, :gap ])
+      end
+  end
+end

data/app/controllers/janela/panes_controller.rb

@@ -1,23 +1,76 @@
 module Janela
+  # One pane of a frame: rendered from its row so the row's own title reaches
+  # the response (ADR 014), and edited as a nested resource (ADR 012).
   class PanesController < ApplicationController
+    before_action :set_frame
+    before_action :set_pane, only: %i[show edit update destroy move_up move_down]
+
     def show
-      @pane = Pane.new(
-        definition: Janela.definition!(params.require(:model)),
-        measure: params.require(:measure).to_sym,
-        dimension: params[:dimension]&.to_sym,
-        renderer: params.fetch(:as, "table"),
-        granularity: params[:granularity],
-        limit: params[:limit],
-        filters: filters
-      )
+      @query = @pane.query(filters: filters)
+      @result = @query.result(on: janela_scope(@query.model))
+    end
+
+    # Two steps, because the engine's pages have no JavaScript to refresh one
+    # select from another: the first picks a model, the second offers exactly
+    # that model's measures and dimensions (ADR 018).
+    def new
+      @pane = @frame.panes.build(model: params[:model], renderer: "table", span: 1)
+      @definition = @pane.model.present? ? Janela.definition!(@pane.model) : nil
+    end
+
+    def edit
+      @definition = @pane.definition
+    end
 
-      @result = @pane.result(on: janela_scope(@pane.model))
+    def create
+      @pane = @frame.panes.build(pane_params)
+
+      if @pane.save
+        redirect_to edit_frame_path(@frame), notice: t("janela.panes.created")
+      else
+        @definition = @pane.model.present? ? Janela.definition!(@pane.model) : nil
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def update
+      if @pane.update(pane_params)
+        redirect_to edit_frame_path(@frame), notice: t("janela.panes.updated")
+      else
+        @definition = @pane.definition
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      @pane.destroy
+      @frame.resequence_panes!
+      redirect_to edit_frame_path(@frame), notice: t("janela.panes.destroyed")
+    end
+
+    def move_up
+      @pane.move_up
+      redirect_to edit_frame_path(@frame)
+    end
+
+    def move_down
+      @pane.move_down
+      redirect_to edit_frame_path(@frame)
     end
 
     private
-      def filters
-        q = params[:q]
-        q.is_a?(ActionController::Parameters) ? q.permit!.to_h : {}
+      # Through the host's scope rather than Pane.find, so a frame belonging to
+      # another tenant is a 404 for every action (ADR 014).
+      def set_frame
+        @frame = janela_scope(Frame).find(params.require(:frame_id))
+      end
+
+      def set_pane
+        @pane = @frame.panes.find(params.require(:id))
+      end
+
+      def pane_params
+        params.expect(pane: [ :model, :measure, :dimension, :renderer, :granularity, :limit, :span, :title ])
       end
   end
 end

data/app/controllers/janela/queries_controller.rb

@@ -0,0 +1,17 @@
+module Janela
+  class QueriesController < ApplicationController
+    def show
+      @query = Query.new(
+        definition: Janela.definition!(params.require(:model)),
+        measure: params.require(:measure).to_sym,
+        dimension: params[:dimension]&.to_sym,
+        renderer: params.fetch(:as, "table"),
+        granularity: params[:granularity],
+        limit: params[:limit],
+        filters: filters
+      )
+
+      @result = @query.result(on: janela_scope(@query.model))
+    end
+  end
+end

data/app/controllers/janela/{snapshot_panes_controller.rb → snapshot_queries_controller.rb}

@@ -1,10 +1,12 @@
 module Janela
   # A pane as it was when a snapshot was taken. Filters in the request are
   # ignored: they were fixed at taking (ADR 009).
-  class SnapshotPanesController < ApplicationController
+  class SnapshotQueriesController < ApplicationController
     def show
-      snapshot = Snapshot.find(params.require(:snapshot_id))
-      @pane = Pane.new(
+      # Through the host's scope, so a snapshot its policy hides is a 404
+      # rather than a stored result anyone who guesses an id can read (ADR 014).
+      snapshot = janela_scope(Snapshot).find(params.require(:snapshot_id))
+      @query = Query.new(
         definition: Janela.definition!(params.require(:model)),
         measure: params.require(:measure).to_sym,
         dimension: params[:dimension]&.to_sym,
@@ -14,8 +16,8 @@ module Janela
         snapshot: snapshot
       )
 
-      @result = @pane.result
-      render "janela/panes/show"
+      @result = @query.result
+      render "janela/queries/show"
     end
   end
 end

data/app/helpers/janela/{dashboard_helper.rb → frames_helper.rb}

@@ -1,9 +1,15 @@
 module Janela
-  module DashboardHelper
-    # The page URL carries the dashboard's filters as q[...] (ADR 008), so a
-    # shared link renders filtered before any JavaScript runs.
-    def janela_dashboard(&block)
-      tag.div(data: { controller: "janela--dashboard", janela__dashboard_filters_value: janela_page_filters.to_json }, &block)
+  module FramesHelper
+    # Two ways to supply the panes: a frame record renders itself from its
+    # rows (ADR 012), or a block composes janela_pane calls by hand. The page
+    # URL carries the filters as q[...] either way (ADR 008), so a shared link
+    # renders filtered before any JavaScript runs.
+    # charts: false renders a chart pane as its table, for a surface with no
+    # chart runtime. The engine's own pages are the case (ADR 018).
+    def janela_frame(frame = nil, charts: true, &block)
+      return render("janela/frames/frame", frame: frame, filters: janela_page_filters, charts: charts) if frame
+
+      tag.div(data: { controller: "janela--frame", janela__frame_filters_value: janela_page_filters.to_json }, &block)
     end
 
     def janela_pane(model, measure, by: nil, as: :table, granularity: nil, limit: nil)
@@ -11,23 +17,33 @@ module Janela
       base = janela_routes.pane_path(model.model_name.route_key, measure, by, **query)
       src = janela_page_filters.empty? ? base : janela_routes.pane_path(model.model_name.route_key, measure, by, **query, q: janela_page_filters)
 
-      turbo_frame_tag Pane.frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit),
+      turbo_frame_tag Query.turbo_frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit),
         src: src,
         loading: :lazy,
-        data: { janela__dashboard_target: "pane", janela_src: base }
+        data: { janela__frame_target: "pane", janela_src: base }
     end
 
     # A pane as it was when the snapshot was taken: same shape as janela_pane,
-    # not part of the live dashboard's filter state (ADR 009).
+    # not part of the live frame's filter state (ADR 009).
     def janela_snapshot_pane(snapshot, model, measure, by: nil, as: :table, granularity: nil, limit: nil)
       query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit }.compact
       src = janela_routes.snapshot_pane_path(snapshot, model.model_name.route_key, measure, by, **query)
 
-      turbo_frame_tag Pane.frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit, snapshot: snapshot),
+      turbo_frame_tag Query.turbo_frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit, snapshot: snapshot),
         src: src, loading: :lazy
     end
 
     private
+      def janela_frame_classes(frame)
+        [ "janela-frame", "janela-cols-#{frame.columns}", "janela-gap-#{frame.gap}" ]
+      end
+
+      # A frame rendered inline runs its queries in the host's own request, so
+      # the same Pundit scope the engine's controllers apply is applied here.
+      def janela_scope(model)
+        respond_to?(:policy_scope, true) ? policy_scope(model) : model.all
+      end
+
       def janela_page_filters
         @janela_page_filters ||= begin
           q = request.query_parameters["q"]

data/app/models/janela/frame.rb

@@ -0,0 +1,28 @@
+module Janela
+  # A dashboard, as data: a name, a grid, and the panes it holds (ADR 012).
+  # A frame is created at runtime by a host, a script or an agent, so nothing
+  # about a dashboard has to be deployed.
+  class Frame < ActiveRecord::Base
+    COLUMNS = (1..12).freeze
+    GAPS = (0..8).freeze
+
+    # Janela sets nothing here and reads nothing from it. The column exists so
+    # a multi tenant host's Pundit Scope has something to filter on (ADR 014).
+    belongs_to :owner, polymorphic: true, optional: true
+
+    has_many :panes, -> { order(:position) }, dependent: :destroy, inverse_of: :frame
+
+    validates :name, presence: true
+    validates :columns, inclusion: { in: COLUMNS }
+    validates :gap, inclusion: { in: GAPS }
+
+    # Positions are kept contiguous so that moving a pane has no gap to fall
+    # into and a new pane's position is never a hole. Called after a pane is
+    # removed rather than on read, because reading a frame is the common case.
+    def resequence_panes!
+      panes.order(:position).each_with_index do |pane, index|
+        pane.update_columns(position: index + 1) unless pane.position == index + 1
+      end
+    end
+  end
+end