janela 0.2.1 → 0.4.0

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,16 @@
 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", action: "keydown.esc->janela--frame#clear",
+                      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 +18,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

data/app/models/janela/pane.rb

@@ -1,137 +1,140 @@
 module Janela
-  # One pane of a dashboard: a measure, optionally grouped by a dimension,
-  # rendered as a single value, a table or a chart. A pane ignores filters on
-  # its own dimension so that clicking a value re-scopes the other panes
-  # rather than collapsing this one to the value clicked. A pane read from a
-  # snapshot shows stored results and cannot be clicked at all.
-  class Pane
-    RENDERERS = %w[table bar line].freeze
-
-    attr_reader :definition, :measure, :dimension, :renderer, :limit, :filters, :snapshot
-
-    # The helper renders the frame and the controller renders its replacement,
-    # so both derive the id the same way from the same parameters.
-    def self.frame_id(model:, measure:, by: nil, as: :table, granularity: nil, limit: nil, snapshot: nil)
-      parts = [ "janela", ("snapshot_#{snapshot.id}" if snapshot), model.model_name.route_key, measure, by,
-                (granularity if by), (as unless by.nil?), ("top#{limit}" if by && limit) ]
-      parts.compact.join("_")
-    end
+  # One pane of a frame, as data: where it sits, how wide it is, and what it
+  # shows (ADR 012). A row may only name a measure and a dimension the model's
+  # janela block declares, so an analyst arranges what is shown and cannot
+  # invent a query or reach a model nobody exposed.
+  class Pane < ActiveRecord::Base
+    SPANS = (1..12).freeze
+    LIMITS = (1..1000).freeze
+    # A form cannot offer a thousand options, and these are the row counts a
+    # dashboard actually asks for. Any limit inside LIMITS is still valid.
+    OFFERED_LIMITS = [ 5, 10, 20, 50, 100 ].freeze
 
-    def initialize(definition:, measure:, dimension: nil, renderer: "table", granularity: nil, limit: nil, filters: {}, snapshot: nil)
-      @definition = definition
-      @measure = measure
-      @dimension = dimension
-      @renderer = renderer.to_s
-      @filters = filters
-      @snapshot = snapshot
-
-      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?
-    end
+    belongs_to :frame
 
-    def model
-      definition.model
-    end
+    before_validation :assign_position, on: :create
 
-    def single_value?
-      dimension.nil?
+    validates :position, presence: true
+    validates :measure, presence: true
+    validates :span, inclusion: { in: SPANS }
+    validates :limit, inclusion: { in: LIMITS }, allow_nil: true
+    validate :declared_by_a_janela_block
+
+    # The DOM id is the row, not the query it runs: two rows in one frame may
+    # show the same measure by the same dimension, and a fingerprint of the
+    # query would give them the same turbo frame for Turbo to replace (ADR 014).
+    def turbo_frame_id
+      "janela_pane_#{id}"
     end
 
-    def time?
-      !single_value? && dimension_definition.time?
+    # renderer: overrides what the row asked for, because a renderer is a
+    # viewing choice and a surface without a chart runtime shows a table
+    # instead (ADR 018).
+    def query(filters: {}, renderer: self.renderer)
+      Query.new(definition: definition, measure: measure.to_sym, dimension: dimension.presence&.to_sym,
+                renderer: renderer, granularity: granularity, limit: limit, filters: filters, title: title)
     end
 
-    def frozen?
-      !snapshot.nil?
+    # The row's own words, for a list or a heading. Built from the columns
+    # rather than from a query, because an editing page has to render even if
+    # a janela block has since lost the dimension this row names.
+    def label
+      return title if title.present?
+
+      dimension.present? ? "#{measure.humanize} by #{dimension.humanize}" : measure.to_s.humanize
     end
 
-    def granularity
-      @granularity || (dimension_definition.granularity if time?)
+    # Arranging the window is the point of the editing surface, and a number
+    # field is not arranging, so a pane swaps places with its neighbour.
+    # Written without validations: the swap passes through a moment where two
+    # panes share a position, and neither row's own data is being changed.
+    def move_up
+      swap_with(panes_above.last)
     end
 
-    # Clicking a category adds one Ransack condition; clicking a time bucket
-    # would need two, and the dashboard toggles one key at a time (ADR 006).
-    # A stored pane is the record of a moment and is not clickable (ADR 009).
-    def clickable?
-      !single_value? && !time? && !frozen?
+    def move_down
+      swap_with(panes_below.first)
     end
 
     def chart?
-      !single_value? && renderer != "table"
+      Query::RENDERERS.include?(renderer.to_s) && renderer.to_s != "table"
     end
 
-    def frame_id
-      self.class.frame_id(model: model, measure: measure, by: dimension, as: renderer,
-                          granularity: @granularity, limit: limit, snapshot: snapshot)
+    def definition
+      Janela.definition!(model)
     end
 
-    def title
-      base = if single_value?
-        measure.to_s.humanize
-      else
-        by = "#{measure.to_s.humanize} by #{dimension.to_s.humanize}"
-        time? ? "#{by} per #{granularity}" : by
+    private
+      def panes_above
+        frame.panes.where(position: ...position).order(:position)
       end
-      frozen? ? "#{base} as of #{snapshot.taken_at.strftime('%-d %b %Y')}" : base
-    end
-
-    # What identifies this pane's data inside a snapshot.
-    def lookup_key
-      { "model" => model.model_name.route_key, "measure" => measure.to_s, "dimension" => dimension&.to_s,
-        "granularity" => granularity&.to_s, "limit" => limit }
-    end
 
-    def result(on: nil)
-      return snapshot.stored_result(self) if frozen?
+      def panes_below
+        frame.panes.where(position: (position + 1)..).order(:position)
+      end
 
-      definition.query(measure, by: dimension, where: applicable_filters, on: on, granularity: granularity, limit: limit)
-    end
+      def swap_with(other)
+        return false if other.nil?
 
-    # The Ransack key and value a click on this label should toggle. A null
-    # group filters with the null predicate, not an empty string (ADR 009 has
-    # no say here; see issue #21).
-    def filter_params(label)
-      return [ nil, nil ] unless clickable?
-      return [ "#{ransack_name}_null", "1" ] if label.to_s == Dimension::NONE
+        transaction do
+          mine = position
+          update_columns(position: other.position, updated_at: Time.current)
+          other.update_columns(position: mine, updated_at: Time.current)
+          frame.touch
+        end
+        true
+      end
 
-      [ "#{ransack_name}_eq", label.to_s ]
-    end
+      def assign_position
+        self.position ||= (frame&.panes&.maximum(:position) || 0) + 1
+      end
 
-    # Every label in this pane paired with the filter it toggles, for a chart
-    # to look up by label when a bar is clicked.
-    def filters_for(labels)
-      return {} unless clickable?
+      # A janela block can lose a measure or a dimension long after a row named
+      # it, and the pane would then fail at render as a missing pane rather
+      # than a bad row. Checked on save, and as errors rather than raising, so
+      # the row is rejected with something a person can read (ADR 014).
+      def declared_by_a_janela_block
+        return errors.add(:model, "must be a model with a janela block") if model.blank?
+
+        declaration = definition
+        validate_measure(declaration) if measure.present?
+        dimension_declaration = validate_dimension(declaration)
+        validate_renderer
+        validate_granularity(dimension_declaration)
+      rescue Janela::Error
+        errors.add(:model, "#{model.inspect} is not a janela model")
+      end
 
-      labels.to_h { |label| [ label.to_s, filter_params(label) ] }
-    end
+      def validate_measure(declaration)
+        return if declaration.measures.key?(measure.to_s.to_sym)
 
-    # The filter on this pane's own dimension is not applied to its query, but
-    # it is what the user clicked here, so the view highlights it.
-    def selected_value
-      return unless clickable?
-      return Dimension::NONE if filter("#{ransack_name}_null").present?
+        errors.add(:measure, "#{measure.inspect} is not a measure of #{declaration.model}")
+      end
 
-      filter("#{ransack_name}_eq")
-    end
+      def validate_dimension(declaration)
+        return if dimension.blank?
 
-    private
-      def filter(key)
-        filters[key] || filters[key.to_sym]
+        declaration.dimensions.fetch(dimension.to_sym) do
+          errors.add(:dimension, "#{dimension.inspect} is not a dimension of #{declaration.model}")
+          nil
+        end
       end
 
-      def dimension_definition
-        definition.dimension!(dimension)
-      end
+      def validate_renderer
+        return if Query::RENDERERS.include?(renderer.to_s)
 
-      def ransack_name
-        dimension_definition.ransack_name
+        errors.add(:renderer, "must be one of #{Query::RENDERERS.join(', ')}")
       end
 
-      def applicable_filters
-        return filters if single_value? || time?
+      def validate_granularity(dimension_declaration)
+        return if granularity.blank?
+
+        unless Dimension::GRANULARITIES.include?(granularity)
+          return errors.add(:granularity, "must be one of #{Dimension::GRANULARITIES.join(', ')}")
+        end
+        return if dimension_declaration.nil? || dimension_declaration.time?
 
-        filters.reject { |key, _| key.to_s.start_with?(ransack_name) }
+        errors.add(:granularity, "only applies to a time dimension, and #{dimension} is not one")
       end
   end
 end