janela 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7fbc539879d1f11c15536c9305299ab9a754add8e26bb443cb582ea236823be
-  data.tar.gz: 150f1292e5c2789cb378e6438c91fd94b766e10088f4daa4aea445ba63341a1b
+  metadata.gz: 00b7cab2c2ce57d7d9457affeb3d5f647b177f37d4f78349d4a12fe3fe298bd6
+  data.tar.gz: 5092f072ec8c4e282f09321fdff541e9eac613f557ae2f9697de830468c52778
 SHA512:
-  metadata.gz: a6d3e5390adf6ac5882d621abc014986f0da17cadad2bca3ba3404d9d2f0d4c744130d7163be7271ddfc70c1404250d1a9a3aa09f274d88a44be57c93c1ac8d4
-  data.tar.gz: 3d7d77e7022225e40c4c13f150818cfd646b0383400bbc59590014caa877b61894f6a1d0b4f056b4d438a1738b6c1489ead2d4ca60bb58caa9fa7554a15b8637
+  metadata.gz: 1bfea2cbc91408fa6c8879f2cd64b3c7cd51cc53b075da9268553ff9125716054afa68b8abc6f714e7b25c70a63f7a295f1c16353d5f31779a76ca326affbf6a
+  data.tar.gz: d9303b22989d5951d847bd56b3337f4576aa352c5887a2cc73b82d15e77d9967230a2984cd06bb2c428abed4f08065cd612461687abe7c91548cab4e88857669

data/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] - 2026-09-17
+
+### Fixed
+
+- `Janela::HostRoutes.forwarded` could return an empty set. Route loading is lazy, so calling it before anything had drawn the host's routes, such as from a host's own initializer, silently forwarded nothing rather than raising. It now draws the routes first if they are not already loaded (#37).
+
 ## [0.4.0] - 2026-09-17
 
 ### Added
@@ -122,6 +128,7 @@ First alpha, installed from GitHub for testing in a single host application.
 - Only models that declare a `janela` block are addressable over HTTP.
 - ADRs 001 to 004 in `docs/decisions/`, shipped inside the gem.
 
+[0.4.1]: https://github.com/retail-tasker/janela/releases/tag/v0.4.1
 [0.4.0]: https://github.com/retail-tasker/janela/releases/tag/v0.4.0
 [0.3.0]: https://github.com/retail-tasker/janela/releases/tag/v0.3.0
 [0.2.1]: https://github.com/retail-tasker/janela/releases/tag/v0.2.1

data/README.md

@@ -435,7 +435,7 @@ Deliberately out of scope: natural-language query, a separate data warehouse, a
 
 ## Status
 
-**v0.4.0 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering with multi-selection, bar and line charts, pane URLs, shareable dashboard URLs, snapshots, database-backed frames, the engine's own pages for reading and editing them and the optional vitral theme work and are covered by unit and real-browser tests. Not yet built: a visual editor, drill-down on time panes, other chart types. Open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
+**v0.4.1 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering with multi-selection, bar and line charts, pane URLs, shareable dashboard URLs, snapshots, database-backed frames, the engine's own pages for reading and editing them and the optional vitral theme work and are covered by unit and real-browser tests. Not yet built: a visual editor, drill-down on time panes, other chart types. Open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
 
 ## Development
 

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

@@ -3,6 +3,7 @@ Date: 2026-09-15
 Status: Accepted
 Related: ADR 001, ADR 005, ADR 009, ADR 012, ADR 014
 Superseded in part by: ADR 012
+Not implemented: the host skill, the install task and the agent definition
 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

data/docs/decisions/025-janela-bounds-what-a-filter-can-ask-for.md

@@ -0,0 +1,131 @@
+---
+Date: 2026-09-17
+Status: Accepted
+Related: ADR 002, ADR 005, ADR 006, ADR 007, ADR 008, ADR 015, ADR 024
+Triggers:
+  - a filter reaching Ransack from a URL
+  - adding a predicate, or widening what a filter may contain
+  - a query with no LIMIT, or a grouped query over a high cardinality dimension
+  - deciding whether a bound belongs to Janela or to the host
+Topics: security, ransack, urls, performance, cross-filtering
+---
+
+# ADR 025: Janela Bounds What a Filter Can Ask For
+
+## Context
+
+ADR 002 chose Ransack so that a host's filters are the Ransack params a
+Rails developer already reads, and made a dimension declaration the
+allowlist of attributes. That part holds. What it left open is which
+*predicates* may be used on an allowed attribute, and issue #8 asked the
+question.
+
+Measured against the demo before writing this:
+
+| Filter passed | Result today |
+| --- | --- |
+| `status_eq: "paid"` | 300.0 |
+| `status_cont: "pai"` | 300.0 |
+| `status_start: "p"` | 325.0 |
+| `status_matches: "%aid"` | 300.0 |
+| `customer_name_cont: "cm"` | 150.0 |
+| `amount_gt: 60` | `BadRequest`, `amount` is not a dimension |
+| `status_frobnicate: "x"` | `BadRequest`, no such predicate |
+
+So the attribute allowlist works, and every predicate Ransack knows is
+reachable on an allowed attribute, including through an association.
+`Ransack::Predicate.names` has 62 entries. The sharpest is `_matches`,
+which takes an arbitrary `LIKE` pattern, so a leading wildcard scan of an
+indexed column is one URL edit away, in a page a host has already
+authorised someone to read.
+
+Two other bounds are missing. A grouped query with no `limit` carries no
+`LIMIT` in SQL at all, so a breakdown by a high cardinality dimension
+returns a row per value. And a single filter can carry any number of
+values: `status_in` with 5001 of them was answered rather than refused,
+which matters more since ADR 024 made `_in` the shape a click writes.
+
+**The question worth deciding is whose job this is.** ADR 002
+deliberately spent Ransack's familiarity on the host, and the obvious
+objection to bounding anything here is that a host can restrict filtering
+itself by defining `ransackable_attributes`. That objection is false, and
+the measurement above is why: `ransackable_attributes` allows *columns*,
+and Ransack has no per-attribute predicate allowlist. Once a host allows
+a column for equality, it has allowed `_matches` on that column too.
+There is nowhere else for this bound to live.
+
+Options considered and rejected:
+
+- **Leave it, and document it.** A dashboard is often the first page a
+  company exposes to people it would not give SQL to, and the library
+  hands them a pattern scan. Documenting a sharp edge is not the same as
+  not having one.
+- **Restrict to `_eq` and `_in`,** as issue #8 proposed. It would delete
+  documented behaviour: ADR 006 allows `placed_on_gteq` and
+  `placed_on_lt` so a host can narrow a time range, and the README says
+  so. A range filter on a time dimension is a dashboard's ordinary
+  question, not an escape hatch.
+- **A setting listing the allowed predicates.** Rejected on the test
+  ADR 021 and ADR 023 set: a setting earns itself when the judgement is
+  made once about the whole application and cannot be inferred. This one
+  can be inferred, from what kind of dimension is being filtered.
+
+## Decision
+
+**Janela allows only the predicates a dashboard asks in, bounds what a
+grouped query returns, and bounds how many values one filter may carry.**
+
+**Predicates are allowed by the kind of dimension.** A categorical
+dimension takes `eq`, `in` and `null`, which is exactly what a click
+produces (ADR 024). A time dimension additionally takes `gteq`, `gt`,
+`lteq` and `lt`, because narrowing a range is how a time dimension is
+filtered (ADR 006). Anything else raises `Janela::BadRequest` naming the
+attribute and the predicates that are allowed, the way a disallowed
+attribute already does.
+
+The check belongs beside the existing one in `Definition#filter`, which
+already raises for a filter Ransack silently dropped. `Ransack::Predicate
+.detect_from_string` splits a key into attribute and predicate, so this
+is a comparison, not a parser.
+
+**One ceiling, 1000, in both places.** A grouped query with no `limit`
+gets `LIMIT 1000`, and a single filter may carry at most 1000 values.
+1000 is not a new number: ADR 007 already fixed it as the maximum a host
+may ask for, so the ceiling is the existing maximum applied by default
+rather than a second constant to reason about. A pane that hits the
+ceiling is unreadable long before it is reached, so this is a bound on
+harm, not on usefulness.
+
+**Time panes keep their exemption.** ADR 007 exempted them from `limit`
+because a time series shows its whole range, and gap filled buckets are
+generated rather than returned by the database. The ceiling does not
+apply to them. A host that wants fewer buckets narrows the range or
+coarsens the granularity, which ADR 006 already allows.
+
+**No setting is added.** A host that genuinely needs a pattern search
+already has the documented way in: pass a pre-filtered relation through
+`on:`, where it writes the condition itself in its own code, under its
+own authorisation, rather than accepting one from a URL.
+
+## Consequences
+
+- The reachable filter surface goes from 62 predicates to three on a
+  categorical dimension and seven on a time dimension. That is the point.
+- **Breaking for a host that passes anything else.** A `_cont` or
+  `_matches` filter that works today raises `BadRequest` after this. It
+  needs an `UPGRADING.md` entry naming the allowed predicates and the
+  `on:` alternative, and the release carrying it is minor (ADR 015).
+  The doctor cannot find this one by reading source, because the filter
+  is usually built at runtime; the upgrade note is the whole mitigation.
+- A stored snapshot holds the filters it was taken under (ADR 009). One
+  taken with a now disallowed predicate would raise when read. Whether to
+  refuse those at read time or leave stored results alone is not decided
+  here and should be settled while building this.
+- The default ceiling changes a number a host can see: a breakdown over
+  more than 1000 values silently showed all of them and will now show
+  1000. It is ordered by the measure, so what is cut is the smallest, and
+  a host that wants a different cut passes `limit`.
+- What would change this: a host with a real need for a predicate not on
+  the list. The answer is to add that predicate to the list for that kind
+  of dimension, in an ADR that says which dashboard question needed it,
+  not to make the list configurable.

data/docs/decisions/INDEX.md

@@ -21,23 +21,24 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | Topic | ADRs |
 |-------|------|
 | **Vision, scope, forkability** | 001, 010, 012 |
-| **Open-source & host-decoupling** | 001 |
-| **DSL & query layer** | 002, 006, 007 |
-| **Dependencies** | 002, 003, 004, 006, 017 |
-| **Authorisation** | 002, 003, 004, 009, 017, 019 |
-| **Performance & storage** | 007, 017 |
-| **Cross-filtering & Hotwire** | 003, 004, 005, 008 |
-| **Layouts & views** | 011, 012, 016, 018 |
-| **CSS & styling** | 016, 018 |
+| **Open-source & host-decoupling** | 001, 022 |
+| **DSL & query layer** | 002, 006, 007, 020, 025 |
+| **Dependencies** | 002, 003, 004, 006, 017, 025 |
+| **Authorisation** | 002, 003, 004, 009, 017, 019, 022 |
+| **Performance & storage** | 007, 017, 025 |
+| **Cross-filtering & Hotwire** | 003, 004, 005, 008, 024, 025 |
+| **Layouts & views** | 011, 012, 016, 018, 020 |
+| **CSS & styling** | 016, 018, 023 |
 | **Frames, panes & persistence** | 012, 013, 014, 019 |
-| **Naming rule** | 014 |
+| **Naming rule** | 014, 023 |
 | **JavaScript delivery & charts** | 004, 006 |
-| **Time dimensions** | 006 |
-| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013 |
-| **Snapshots & publishing** | 009 |
-| **AI agents & guidance** | 010, 015 |
-| **Releases & upgrades** | 015 |
-| **Security** | 003 |
+| **Time dimensions** | 006, 025 |
+| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025 |
+| **Snapshots & publishing** | 009, 020 |
+| **AI agents & guidance** | 010, 015, 021 |
+| **Releases & upgrades** | 015, 021 |
+| **Accessibility & keyboard** | 024 |
+| **Security** | 003, 025 |
 | **Testing** | 003 |
 
 ## Chronological
@@ -68,7 +69,8 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 022 | A Host's Route Helpers Work Inside the Engine | 2026-09-16 | Accepted |
 | 023 | Vitral Is a Theme, Not the Stylesheet | 2026-09-16 | Accepted |
 | 024 | Selecting More Than One Value | 2026-09-16 | Accepted |
+| 025 | Janela Bounds What a Filter Can Ask For | 2026-09-17 | Accepted |
 
 ## Next number
 
-Next ADR: 025
+Next ADR: 026

data/lib/janela/host_routes.rb

@@ -25,6 +25,12 @@ module Janela
     end
 
     def self.forwarded(host: Rails.application.routes, engine: Janela::Engine.routes)
+      # Route loading is lazy, so a call before anything else has drawn the
+      # host's routes would otherwise see an empty set rather than an error
+      # (issue #37). This does not recurse: define! runs from
+      # after_routes_loaded, by which point the reloader has already marked
+      # itself loaded.
+      Rails.application.reload_routes_unless_loaded
       host.named_routes.helper_names - engine.named_routes.helper_names
     end
   end

data/lib/janela/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: janela
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Jay Killeen
@@ -160,6 +160,7 @@ files:
 - docs/decisions/022-host-route-helpers-work-inside-the-engine.md
 - docs/decisions/023-vitral-is-a-theme-not-the-stylesheet.md
 - docs/decisions/024-selecting-more-than-one-value.md
+- docs/decisions/025-janela-bounds-what-a-filter-can-ask-for.md
 - docs/decisions/INDEX.md
 - docs/multi-tenancy.md
 - docs/naming.md
@@ -182,15 +183,6 @@ metadata:
   changelog_uri: https://github.com/retail-tasker/janela/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/retail-tasker/janela/issues
   rubygems_mfa_required: 'true'
-post_install_message: |
-  Janela 0.4.0 selects more than one value in a dimension. Most applications
-  need do nothing. You need to act only if you override a pane view, where
-  selected_value is now selected_values, or if something of yours reads
-  Janela's URLs, where a click now writes q[field_in][] rather than
-  q[field_eq]. Links already shared keep working.
-
-  Steps: UPGRADING.md in this gem, or
-  https://github.com/retail-tasker/janela/blob/main/UPGRADING.md
 rdoc_options: []
 require_paths:
 - lib