janela 0.14.0 → 0.16.0

data/lib/janela/definition.rb

@@ -4,6 +4,11 @@ module Janela
     # applied when a host asks for none, and as the bound on one filter's values.
     MAXIMUM = 1000
 
+    # How a category pane is ordered (ADR 055): by its measure, largest or
+    # smallest first, or by the dimension's own value, ascending or descending.
+    # The first is what a pane did before there was a choice.
+    SORTS = %w[desc asc label label_desc].freeze
+
     attr_reader :model, :measures, :dimensions
 
     # The class whose janela block this is, which a subclass shares with the
@@ -44,8 +49,9 @@ module Janela
     # keys: narrows a categorical grouping to the labels a companion column is
     # being fetched for (ADR 051), so it is the primary's rows and not the
     # companion's own top 1000.
-    def query(measure_name, by: nil, where: {}, on: nil, granularity: nil, limit: nil, keys: nil)
+    def query(measure_name, by: nil, where: {}, on: nil, granularity: nil, limit: nil, keys: nil, sort: nil)
       measure = measure!(measure_name)
+      sort = sort!(sort)
       relation = filter(on || model.all, where)
       return measure.apply(relation) if by.nil?
 
@@ -57,7 +63,7 @@ module Janela
         bucketed(measure, dimension, relation, granularity).transform_keys { |bucket| dimension.label(bucket, granularity) }
       else
         relation = within_keys(relation, dimension, keys) if keys
-        grouped = relation.group(dimension.attribute).order(Arel.sql("#{measure.order_by} DESC"))
+        grouped = relation.group(dimension.attribute).order(Arel.sql(ordering(measure, dimension, sort)))
         grouped = grouped.limit(limit ? limit!(limit) : MAXIMUM)
         measure.apply(grouped).transform_keys { |value| value.nil? ? Dimension::NONE : value }
       end
@@ -124,6 +130,15 @@ module Janela
       nil # no database to ask yet; a query will raise on its own if it cannot run
     end
 
+    # nil is the default, so a caller that never heard of a sort is unchanged.
+    def sort!(value)
+      return "desc" if value.blank?
+
+      value = value.to_s
+      raise BadRequest, "sort must be one of #{SORTS.join(', ')}, got #{value.inspect}" unless SORTS.include?(value)
+      value
+    end
+
     def limit!(value)
       limit = Integer(value, exception: false)
       raise BadRequest, "limit must be a whole number from 1 to #{MAXIMUM}, got #{value.inspect}" unless limit&.between?(1, MAXIMUM)
@@ -138,6 +153,20 @@ module Janela
       dimensions.values.filter_map(&:through).map(&:to_s).uniq
     end
 
+    # The keys of these params Ransack would apply to this model, read by the
+    # same helper reject_dropped_filters! uses so the two cannot disagree about
+    # which keys are the model's. A pane that ignores unknown filters keeps
+    # these, and also a key on a dimension the model declares with a predicate
+    # Ransack does not know (path_inn), which is a misuse of a real key and is
+    # left for the filter to refuse (ADR 025, ADR 063). Only a key whose
+    # attribute the model does not declare at all is dropped.
+    def applicable(params)
+      return params if params.empty?
+
+      dropped = unapplied_keys(model.ransack(params.to_h), params)
+      params.reject { |key, _| dropped.include?(key) && !misspelt_declared_key?(key) }
+    end
+
     # A filter the host fixed for a render (ADR 040), applied as its own
     # condition before the reader's, so the reader's can only narrow inside
     # it. The same bounds as any filter: declared dimensions, ADR 025's
@@ -147,6 +176,24 @@ module Janela
     end
 
     private
+      # The label comes second in a measure order so that groups tied on the
+      # measure come out the same way every time, and a limit between them
+      # always shows the same one. IS NULL puts the (none) group last wherever
+      # the database would put it: SQLite sorts NULL first in an ascending
+      # order and PostgreSQL last, and a label order would otherwise differ by
+      # host (ADR 055). The database sorts the column as its own type, so a
+      # number is in numeric order and a date in date order.
+      def ordering(measure, dimension, sort)
+        label = dimension.quoted_column
+        by_label = "#{label} IS NULL, #{label}"
+        case sort
+        when "asc" then "#{measure.order_by} ASC, #{by_label} ASC"
+        when "label" then "#{by_label} ASC"
+        when "label_desc" then "#{by_label} DESC"
+        else "#{measure.order_by} DESC, #{by_label} ASC"
+        end
+      end
+
       def within_keys(relation, dimension, keys)
         labels = keys - [ Dimension::NONE ]
         condition = dimension.attribute.in(labels)
@@ -203,14 +250,36 @@ module Janela
       # Ransack silently discards conditions an allowlist does not permit,
       # which would quietly return unfiltered numbers.
       def reject_dropped_filters!(search, params)
-        applied = search.conditions.flat_map { |condition| condition.attributes.map(&:name) }
-        dropped = params.keys.reject { |key| applied.any? { |name| key.to_s.start_with?(name) } }
+        dropped = unapplied_keys(search, params)
         return if dropped.empty?
 
         raise BadRequest, "#{model} does not allow filtering on #{dropped.join(', ')}. " \
                      "Declare a janela dimension, or add it to ransackable_attributes."
       end
 
+      # The keys Ransack did not apply: those that are not exactly an attribute
+      # it applied followed by a predicate it knows. Exact, so status_code_in
+      # is not taken for status because it starts with it.
+      def unapplied_keys(search, params)
+        applied = search.conditions.flat_map { |condition| condition.attributes.map(&:name) }
+        params.keys.reject { |key| applied.any? { |name| predicate_of?(key, name) } }
+      end
+
+      def predicate_of?(key, name)
+        prefix = "#{name}_"
+        key.to_s.start_with?(prefix) && Ransack.predicates.has_key?(key.to_s.delete_prefix(prefix))
+      end
+
+      # A key Ransack did not apply that is a declared dimension and a suffix
+      # that is not another attribute with a known predicate on it: path_inn is
+      # path with a typo, status_code_in is a different attribute entirely.
+      def misspelt_declared_key?(key)
+        dimensions.values.reject(&:through).any? do |dimension|
+          rest = key.to_s.delete_prefix("#{dimension.ransack_name}_")
+          rest != key.to_s && Ransack.predicates.keys.none? { |predicate| rest.end_with?("_#{predicate}") }
+        end
+      end
+
       # An allowed attribute still reaches every predicate Ransack knows,
       # including _matches, an arbitrary LIKE pattern (ADR 025). A dashboard
       # asks in only the predicates its kind of dimension needs.

data/lib/janela/dimension.rb

@@ -26,11 +26,19 @@ module Janela
       "hour" => ->(t) { t.strftime("%Y-%m-%d %H:00") },
       "day" => ->(t) { t.strftime("%Y-%m-%d") },
       "week" => ->(t) { t.strftime("%Y-%m-%d") },
-      "month" => ->(t) { t.strftime("%b %Y") },
+      "month" => ->(t) { month_label(t) },
       "quarter" => ->(t) { "Q#{(t.month - 1) / 3 + 1} #{t.year}" },
       "year" => ->(t) { t.strftime("%Y") }
     }.freeze
 
+    # The month in the reader's language when the host has that language's month
+    # names, and in English when it has not: strftime is English only, and a host
+    # that never set a locale must see what it always did (ADR 061).
+    def self.month_label(time)
+      names = I18n.t("date.abbr_month_names", default: nil)
+      names.is_a?(Array) && names[time.month] ? "#{names[time.month]} #{time.year}" : time.strftime("%b %Y")
+    end
+
     attr_reader :name, :model, :through, :column, :granularity
 
     # A dimension is named for what it means on the dashboard and reads a

data/lib/janela/doctor.rb

@@ -38,6 +38,7 @@ module Janela
     }.freeze
 
     SEARCHED = %w[app config lib].freeze
+    AGENT_SERVER = "bin/janela-mcp".freeze
     READABLE = %w[.rb .erb .js .erb.html .html.erb .haml .slim .yml].freeze
 
     def initialize(root)
@@ -66,6 +67,14 @@ module Janela
       # Said out loud every run, because a silence nobody remembers is how a
       # real finding goes unread.
       out.puts "Silenced: #{silenced.map(&:code).uniq.join(', ')}." if silenced.any?
+
+      # Not a finding: it is optional, so it is never counted, silenced or
+      # allowed to change the result. It says what it saw, which is a missing
+      # file, and is printed on a clean run too (ADR 057).
+      unless @root.join(AGENT_SERVER).exist?
+        out.puts
+        out.puts "Optional: let an agent arrange dashboards. bin/rails generate janela:mcp (docs/agents.md)."
+      end
       findings.none? { |finding| finding.severity == :error }
     end
 
@@ -148,7 +157,7 @@ module Janela
       # the same thing twice.
       ADDED_COLUMNS = {
         "Janela::Frame" => %w[key default_model default_where],
-        "Janela::Pane" => %w[kind heading body link partial height prominence companions value_labels],
+        "Janela::Pane" => %w[kind heading body link partial height prominence companions value_labels sort cumulative series ignore_unknown_filters],
         "Janela::Snapshot" => %w[owner_type owner_id]
       }.freeze
 

data/lib/janela/measure.rb

@@ -46,6 +46,14 @@ module Janela
       aggregate == :ratio
     end
 
+    # A count or a sum adds up across buckets: a running total of it means
+    # something, and a bucket with no rows is zero. An average, a minimum, a
+    # maximum or a ratio does not, and a bucket with no rows has no value
+    # (ADR 062).
+    def additive?
+      %i[count sum].include?(aggregate)
+    end
+
     def apply(relation)
       return relation.average(ratio_expression) if ratio?
 

data/lib/janela/tools.rb

@@ -17,11 +17,14 @@ module Janela
 
     # The attributes of a pane a caller may set: the ones the README names. The
     # frame, the position and the timestamps are not an agent's to write.
-    PANE_ATTRIBUTES = %w[kind model measure dimension renderer granularity limit span title height prominence
-                         value_labels companions heading body link partial].freeze
+    PANE_ATTRIBUTES = %w[kind model measure dimension renderer granularity limit sort span title height prominence
+                         value_labels companions cumulative series ignore_unknown_filters heading body link partial].freeze
+    # A frame's grid is the only part of a frame an agent may change (ADR 057).
+    # Its name, key and owner are the host's to say (ADR 033, ADR 041).
+    FRAME_ATTRIBUTES = %w[columns gap].freeze
     DIRECTIONS = %w[up down].freeze
     READS = %w[describe_vocabulary list_frames get_frame read_pane].freeze
-    WRITES = %w[add_pane update_pane remove_pane move_pane].freeze
+    WRITES = %w[add_pane update_pane remove_pane move_pane update_frame].freeze
 
     def initialize(scope: nil, write: false)
       unless scope.respond_to?(:call)
@@ -64,7 +67,8 @@ module Janela
         { models: Janela.definitions.map { |definition| model_hash(definition) },
           renderers: Janela.renderers.map(&:to_s),
           granularities: Janela.granularities.map(&:to_s),
-          limits: Pane::OFFERED_LIMITS }
+          limits: Pane::OFFERED_LIMITS,
+          sorts: Janela.sorts }
       end
 
       def list_frames
@@ -88,6 +92,12 @@ module Janela
         reading.merge(values: result.transform_values(&:to_f), formatted: result.transform_values { |value| query.format(value) })
       end
 
+      def update_frame(frame_id:, **attributes)
+        frame = frame_in_scope(frame_id)
+        frame.update(frame_attributes(attributes)) || refuse(frame)
+        frame_hash(frame)
+      end
+
       def add_pane(frame_id:, **attributes)
         frame = frame_in_scope(frame_id)
         pane = frame.panes.build(pane_attributes(attributes))
@@ -143,6 +153,13 @@ module Janela
         attributes.transform_keys(&:to_s)
       end
 
+      def frame_attributes(attributes)
+        unknown = attributes.keys.map(&:to_s) - FRAME_ATTRIBUTES
+        raise BadRequest, "not a frame attribute an agent may change: #{unknown.join(', ')}. A frame's #{FRAME_ATTRIBUTES.join(' and ')} can be changed." if unknown.any?
+
+        attributes.transform_keys(&:to_s)
+      end
+
       def refuse(record)
         raise BadRequest, record.errors.full_messages.to_sentence
       end
@@ -186,6 +203,11 @@ module Janela
             "remove_pane" => tool("remove_pane", required: %w[pane_id],
               description: "Remove a pane and close the gap it leaves.",
               properties: { pane_id: { type: "integer" } }),
+            "update_frame" => tool("update_frame", required: %w[frame_id],
+              description: "Change a frame's grid: how many columns it has and the gap between panes. Nothing else of a frame can be changed.",
+              properties: { frame_id: { type: "integer" },
+                            columns: { type: "integer", minimum: Frame::COLUMNS.min, maximum: Frame::COLUMNS.max },
+                            gap: { type: "integer", minimum: Frame::GAPS.min, maximum: Frame::GAPS.max } }),
             "move_pane" => tool("move_pane", required: %w[pane_id direction],
               description: "Move a pane one place up or down its frame.",
               properties: { pane_id: { type: "integer" }, direction: { type: "string", enum: DIRECTIONS } })
@@ -205,12 +227,23 @@ module Janela
             renderer: { type: "string", enum: Janela.renderers.map(&:to_s) },
             granularity: { type: "string", enum: Janela.granularities.map(&:to_s) },
             limit: { type: "integer", minimum: Pane::LIMITS.min, maximum: Pane::LIMITS.max },
+            sort: { type: "string", enum: Janela.sorts },
             span: { type: "integer", minimum: Pane::SPANS.min, maximum: Pane::SPANS.max },
             title: { type: "string" },
             height: { type: "integer", enum: Pane::HEIGHTS.to_a },
             prominence: { type: "integer", enum: Pane::PROMINENCES.to_a },
             value_labels: { type: "boolean", description: "Draw each bar's value on a bar chart; other renderers ignore it" },
             companions: { type: "array", items: { type: "string" } },
+            cumulative: { type: "boolean", description: "A running total of the measure across a time pane's buckets" },
+            series: { type: "array", description: "Up to #{Query::MAX_SERIES} more series on a time pane, each a measure over a time dimension of the same model",
+                      items: { type: "object", required: %w[measure], additionalProperties: false,
+                               properties: { measure: { type: "string" },
+                                             by: { type: "string", description: "A time dimension; the pane's own when left out" },
+                                             cumulative: { type: "boolean" },
+                                             as: { type: "string", enum: Query::CANVAS },
+                                             axis: { type: "string", enum: Query::AXES },
+                                             title: { type: "string" } } } },
+            ignore_unknown_filters: { type: "boolean", description: "Drop the reader's filters this pane's model cannot apply rather than refusing them, for a pane beside panes over another model" },
             heading: { type: "string" },
             body: { type: "string" },
             link: { type: "string", description: "A path on this site, starting with /" },

data/lib/janela/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Janela
-  VERSION = "0.14.0"
+  VERSION = "0.16.0"
 end

data/lib/janela.rb

@@ -70,6 +70,14 @@ module Janela
   # whatever that host's layout says (ADR 023).
   mattr_accessor :theme, default: nil
 
+  # Whether the engine's own frame page draws a bar or line pane as a chart.
+  # False is a table, because the engine's minimal layout loads no chart
+  # runtime and cannot know whether a host's layout does (ADR 018). A host that
+  # has given Janela's own pages a layout that registers the Stimulus
+  # controllers and loads Chart.js says so here (ADR 059). A host that sets it
+  # without the runtime gets an empty hole where the table was.
+  mattr_accessor :charts_on_own_pages, default: false
+
   # Checks janela:doctor should not report, by the name it prints beside each
   # finding. A check that is a false alarm for one application stays a false
   # alarm, and that is a judgement made once at boot, which is what a setting
@@ -170,6 +178,10 @@ module Janela
   # The steps a pane's height and prominence take, and how many companion
   # columns a table may carry, for a page that offers them as controls
   # (ADR 027, ADR 047, ADR 050, ADR 051).
+  def self.sorts
+    Definition::SORTS
+  end
+
   def self.heights
     Pane::HEIGHTS.to_a
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: janela
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Jay Killeen
@@ -147,6 +147,9 @@ files:
 - db/migrate/20260930000002_add_prominence_to_janela_panes.rb
 - db/migrate/20260930000003_add_companions_to_janela_panes.rb
 - db/migrate/20261006000001_add_value_labels_to_janela_panes.rb
+- db/migrate/20261013000001_add_sort_to_janela_panes.rb
+- db/migrate/20261029000001_add_series_to_janela_panes.rb
+- db/migrate/20261029000003_add_ignore_unknown_filters_to_janela_panes.rb
 - docs/agents.md
 - docs/composing.md
 - docs/decisions/001-built-to-be-forked.md
@@ -203,11 +206,22 @@ files:
 - docs/decisions/052-how-the-project-is-run.md
 - docs/decisions/053-an-agent-reaches-janela-through-tools-the-host-scopes.md
 - docs/decisions/054-a-chart-reads-numbers-the-way-its-measure-formats-them.md
+- docs/decisions/055-a-category-pane-can-be-sorted-by-its-measure-either-way-or-by-its-label.md
+- docs/decisions/056-the-demo-counts-its-own-visits-and-an-agent-arranges-the-dashboard.md
+- docs/decisions/057-a-host-is-told-about-the-agent-tools-and-a-generator-sets-them-up.md
+- docs/decisions/058-the-deployed-demo-is-reached-over-ssh-and-its-visits-frame-survives-a-reset.md
+- docs/decisions/059-a-host-can-tell-janelas-own-pages-that-its-layout-draws-charts.md
+- docs/decisions/060-the-demo-tells-search-engines-what-it-is-and-shows-its-own-adoption.md
+- docs/decisions/061-the-demo-speaks-brazilian-portuguese-under-a-prefix-and-the-gem-stays-english.md
+- docs/decisions/062-a-time-pane-can-accumulate-and-carry-more-series-on-two-axes.md
+- docs/decisions/063-a-pane-can-ignore-a-filter-its-model-cannot-apply.md
 - docs/decisions/INDEX.md
 - docs/multi-tenancy.md
 - docs/naming.md
 - docs/roadmap.md
 - docs/theming.md
+- lib/generators/janela/mcp/mcp_generator.rb
+- lib/generators/janela/mcp/templates/janela-mcp.tt
 - lib/janela.rb
 - lib/janela/definition.rb
 - lib/janela/dimension.rb
@@ -229,17 +243,17 @@ metadata:
   bug_tracker_uri: https://github.com/retail-tasker/janela/issues
   rubygems_mfa_required: 'true'
 post_install_message: |
-  Janela 0.14.0: one migration, if you use stored frames.
+  Janela 0.16.0: one migration, if you use stored frames.
 
-  A pane can now draw each bar's value on a bar chart (ADR 054), which
-  adds a nullable value_labels column to janela_panes. Run
+  A time pane can now be a running total and carry more series on two
+  axes (ADR 062), and a pane can ignore a filter its model cannot apply
+  (ADR 063). That adds nullable cumulative, series and
+  ignore_unknown_filters columns to janela_panes. Run
   bin/rails janela:install:migrations and then bin/rails db:migrate. If
   you never use stored frames there is nothing to do.
 
-  Also: a chart's axis now reads in the measure's own format, so a
-  currency chart gains its prefix and a ratio reads as percentages. A
-  pane Janela will not draw is now that pane's own sentence and no
-  longer an error for the whole host page.
+  Also: a line chart with value_labels now writes its latest value at
+  its end.
 
   Steps: UPGRADING.md in this gem, or
   https://github.com/retail-tasker/janela/blob/main/UPGRADING.md