janela 0.1.0 → 0.2.0

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

@@ -0,0 +1,136 @@
+---
+Date: 2026-09-15
+Status: Accepted
+Related: ADR 001, ADR 002, ADR 003, ADR 004
+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:
+  - renaming a model that has a janela block
+  - adding a renderer, a parameter or a response format to panes
+  - adding a second dimension, a sort or a limit to a pane
+  - anything that turns a pane into a shareable link
+Topics: routes, urls, mount, panes, naming, public-api
+---
+
+# ADR 005: Pane URLs and the Mount Path
+
+## Context
+
+A dashboard is a window onto a model, and each visual in it is one
+pane of that window. Until now a pane was addressed as
+`/janela/visual?model=Order&measure=revenue&by=status&as=bar`: the
+engine's own name in the path, and every identifying fact spelled out
+as a query parameter in whatever order the helper happened to emit
+them. That URL was an implementation detail that leaked, not a design.
+
+Two things were wrong with it. The path segment `janela` is the
+project's name, not a word a host application would choose for its
+own reports, and the documentation and dummy application made it look
+mandatory. And a pane had no address a person would want to bookmark,
+share, or open on its own, even though the controller already rendered
+one perfectly well when hit directly.
+
+A related bug: the `janela_visual` helper built its frame `src` through
+the `janela` route proxy, so mounting the engine with a different `as:`
+broke every dashboard (#13).
+
+## Decision
+
+**The mount path is the host's, chosen in `config/routes.rb`.**
+
+```ruby
+mount Janela::Engine => "/dashboards"
+```
+
+This is the one obvious way Rails engines are placed, it is what
+Blazer does, and a separate `Janela.configure` setting for the same
+fact would duplicate it. Documentation and the dummy application use
+`/dashboards`, and say plainly that the path is whatever the host
+wants. The helper finds the engine's mount by looking it up in the
+host's route table rather than assuming a proxy name, so `as:` works
+and #13 is closed.
+
+**A pane's URL is the sentence an analyst would say, with the small
+words replaced by URL syntax.**
+
+```
+/dashboards/orders/revenue                      orders revenue
+/dashboards/orders/revenue/status               orders revenue by status
+/dashboards/orders/revenue/status?as=bar        ... as a bar chart
+/dashboards/orders/revenue/region?q[status_eq]=paid
+                                                orders revenue by region where status is paid
+```
+
+Path: the model's route key, the measure, and optionally the
+dimension. Query: `as` for the renderer (default `table`), `q` for
+Ransack filters exactly as ADR 002 defined them. One route serves both
+uses: a Turbo Frame in a dashboard loads it, and a person opens it
+directly and gets that pane alone inside the host's layout.
+
+The naming convention, recorded so future URL decisions start from it:
+
+| An analyst says     | The URL says            |
+|---------------------|-------------------------|
+| *by*                | `/`                     |
+| *where*, *for*, *only* | `?q[...]`            |
+| *as a bar chart*    | `?as=bar`               |
+| nothing after the measure | no dimension segment: the total |
+
+There is no literal `by` segment. It carried nothing the router
+needed, since segment count and the model's declared dimensions
+already disambiguate, and it kept `/orders/revenue` from being a
+complete sentence. Rails paths are nouns without prepositions;
+`/posts/1/comments`, not `/posts/1/with/comments`.
+
+**A pane with no dimension is a single value.** `/orders/revenue` is
+the measure's total under the current filters, rendered as one number.
+It is the KPI tile every dashboard has, and it falls out of the
+grammar rather than being a separate feature. It is a pane like any
+other: it lives in a Turbo Frame, it re-scopes when other panes are
+clicked, and it has nothing of its own to click.
+
+The renderer is a query parameter rather than a format extension
+(`status.bar`) because Rails treats an extension as a MIME format and
+`bar` is not one; it would also spend the extension that a future
+`.json` response of the same pane's data should have.
+
+The model appears as its `model_name.route_key` (`orders`,
+`sales_orders`), the same identifier the host's own resource routes
+use. The registry from ADR 003 keys on route key instead of class
+name and remains the allowlist: a request for a key no model declared
+is refused before anything is constantized.
+
+**The concept is a pane, and the code says so.** `Janela::Visual`
+becomes `Janela::Pane`, `VisualsController` becomes `PanesController`,
+`janela_visual` becomes `janela_pane`, and the CSS hooks become
+`janela-pane`, `janela-chart`, `janela-value` and `janela-empty`.
+"Visual" was a placeholder borrowed from BI vendors; "pane" is the
+word that fits a project named for a window, and it is the word its
+author reached for unprompted.
+
+## Consequences
+
+- This breaks the 0.1.0 API: helper name, class names, frame ids, CSS
+  classes and the route. Acceptable now, while the only installation
+  is the author's own, and impossible to do cheaply later. Ships as
+  0.2.0 with the CHANGELOG saying exactly what to rename.
+- A model's route key becomes part of a public URL. Renaming the model
+  changes the URL, which is how every other Rails resource already
+  behaves.
+- A pane opened directly has no dashboard controller around it, so
+  clicking a value does nothing there. That is correct: the click
+  would only ever filter other panes, and there are none. Filters in
+  the query string still apply, so a filtered pane is a shareable
+  link. This delivers #1 for a single pane; a whole dashboard's
+  filter state in the URL remains open.
+- The grammar has one open slot: a second path segment after the
+  dimension. Whether that means a second dimension (a matrix), a sort,
+  or is refused is a decision for the ADR that adds it, and it should
+  start from the naming table above: an analyst would say "by status
+  *and* region", which suggests another `/`.
+- A time dimension with a granularity (#3) is still "by placed_on";
+  the granularity is a modifier, so it is a query parameter, not a new
+  word in the path.
+- 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.

data/docs/decisions/006-time-dimensions-with-groupdate.md

@@ -0,0 +1,93 @@
+---
+Date: 2026-09-15
+Status: Accepted
+Related: ADR 002, ADR 005
+Triggers:
+  - grouping a measure by a date or time column
+  - adding a granularity, a time zone rule or a week start
+  - making a time pane clickable or adding drill-down
+  - adding a dependency to the query path
+Topics: dsl, time, granularity, groupdate, dependencies, charts
+---
+
+# ADR 006: Time Dimensions with Groupdate
+
+## Context
+
+A dashboard without time is thin. "Revenue by status" answers one
+question; "revenue per month" answers the one people ask first. ADR 002
+built dimensions as columns grouped as they are, which is right for
+categories and wrong for dates: grouping by a raw `placed_on` yields one
+row per day with gaps wherever nothing happened, in whatever order the
+database returns them, in the database's time zone.
+
+Bucketing time correctly is harder than it looks. A month boundary
+depends on the viewer's time zone, a week depends on which day starts
+it, an empty bucket must still appear so a chart does not silently skip
+it, and every database spells `date_trunc` differently. ADR 002 named
+Groupdate as the conventional answer and deferred the decision until
+the work arrived.
+
+## Decision
+
+**A time dimension declares a default granularity.**
+
+```ruby
+dimension :placed_on, granularity: :month
+```
+
+Granularity is one of `hour`, `day`, `week`, `month`, `quarter`,
+`year`. A dimension with a granularity is a time dimension; one without
+is a category, exactly as before.
+
+**Granularity is a modifier, so it is a query parameter.** Following
+ADR 005's naming table, an analyst says "revenue by placed_on, per
+week": the dimension is the path segment, the granularity is
+`?granularity=week`. The dimension's declared value is the default.
+
+```
+/dashboards/orders/revenue/placed_on
+/dashboards/orders/revenue/placed_on?granularity=week&as=line
+```
+
+**Groupdate does the bucketing.** `group_by_period(granularity, column)`
+handles the time zone, the week start, gap filling with zeros and the
+database differences. Janela adds a runtime dependency on it rather
+than reimplementing any of that. The week starts on the host's
+`Date.beginning_of_week`, which is Monday unless the host says
+otherwise. Buckets are labelled in Ruby after the query
+(`2026-09-01`, `Sep 2026`, `Q3 2026`, `2026`) so labels do not depend
+on the database.
+
+**Charts gain a `line` renderer.** A time series wants a line; the
+renderer whitelist becomes `table`, `bar`, `line`. Nothing else about
+charts changes.
+
+**Time panes are not yet click sources.** Clicking a category value
+adds one Ransack condition, `status_eq=paid`. Clicking a month means
+two, `placed_on_gteq` and `placed_on_lt`, and the dashboard's filter
+model is a single key and value per toggle. Rather than half-build
+drill-down today, a time pane's values render as plain text and its
+chart ignores clicks. Time panes still re-scope when any other pane is
+clicked. Drill-down, narrowing granularity by clicking a bucket, is
+the natural next decision and gets its own ADR.
+
+## Consequences
+
+- Groupdate is a runtime dependency. It is the conventional Rails
+  answer, it is small, and reimplementing time-zone-correct bucketing
+  across three databases would be far more code than Janela should
+  carry.
+- Time buckets are gap-filled, so a chart over a quiet period shows
+  the quiet rather than compressing it away. A table over a long range
+  gets long; the ordering and limit decision (planned next) applies to
+  time panes as to any other.
+- Time zone follows `Time.zone`, which is what a Rails host already
+  configured. SQLite does not support time zone conversion, so a host
+  on SQLite gets UTC buckets; the dummy application runs in UTC.
+- A declared `placed_on` dimension is Ransack-allowlisted like any
+  other, so hosts can pass `placed_on_gteq` and `placed_on_lt` as
+  filters today even though clicking does not generate them yet.
+- The naming table in ADR 005 predicted this shape (granularity as a
+  modifier, not a path word) before the feature existed, which is the
+  point of having recorded it.

data/docs/decisions/007-ordering-and-limits.md

@@ -0,0 +1,74 @@
+---
+Date: 2026-09-15
+Status: Accepted
+Related: ADR 005, ADR 006
+Triggers:
+  - changing how a pane's rows or bars are ordered
+  - adding a limit, a "top N", an "other" bucket or paging to a pane
+  - adding a sort direction or sorting by something other than the measure
+  - a pane rendering too many rows or bars to read
+Topics: ordering, limit, panes, urls, query-layer
+---
+
+# ADR 007: Ordering and Limits
+
+## Context
+
+A category pane returned its groups in whatever order the database
+produced them, and all of them. In the dummy application that is three
+statuses. In a real host it was a hundred projects in an arbitrary
+order, which is unreadable as a table and meaningless as a bar chart.
+Every BI tool sorts a categorical breakdown by its measure and offers
+"top N"; a pane that does neither is not finished.
+
+ADR 005 deliberately left this out of the URL grammar and asked that it
+be decided rather than added quietly.
+
+## Decision
+
+**A category pane is ordered by its measure, largest first.** Always,
+in SQL, using the alias ActiveRecord already gives the aggregate
+(`sum_amount`, `count_all`, `average_amount`). There is no option to
+turn this off or sort another way: one obvious ordering, and the one
+every analyst expects.
+
+**`limit` is a modifier, so it is a query parameter.** Following ADR
+005's naming table, an analyst says "top ten customers by revenue":
+
+```
+/dashboards/orders/revenue/customer?limit=10
+```
+
+`janela_pane Order, :revenue, by: :customer, limit: 10` emits the same.
+The limit is applied in SQL after the ordering, so the database does
+the work and the pane receives ten rows, not a thousand trimmed in
+Ruby. It must be an integer from 1 to 1000. A pane with a limit has it
+in its frame id, so "top five" and "all" of the same breakdown can
+share a page.
+
+**Time panes are exempt.** A time series is ordered by time and shows
+its whole range; ordering it by value would destroy it, and "the top
+ten days" is a different question from "revenue per day". A limit on a
+time pane is ignored. Narrowing a time range is a filter
+(`placed_on_gteq`), which ADR 006 already allows.
+
+**Not decided here, on purpose:** an "other" bucket that sums what the
+limit cut off, ascending order, sorting by label, and paging. Each is
+plausible; none is needed by the first host. They belong to the ADR
+that needs them and should start from the naming table: an analyst
+says "bottom five" or "the rest".
+
+## Consequences
+
+- Every existing category pane changes order to measure-descending.
+  That is a visible change and the right one; the old order was
+  accidental.
+- Ordering by the aggregate alias relies on ActiveRecord's naming of
+  grouped calculation columns, which has been stable across major
+  versions but is not a documented contract. If it changes, the test
+  that asserts the order will say so.
+- The naming table in ADR 005 gains a row: *top N* is `?limit=N`.
+- The unbounded-query concern in issue #8 is now bounded by hosts that
+  pass a limit. It remains unbounded for hosts that do not, and the
+  question of whether Janela should impose a ceiling stays with that
+  issue.

data/docs/decisions/008-dashboard-filters-in-the-page-url.md

@@ -0,0 +1,68 @@
+---
+Date: 2026-09-15
+Status: Accepted
+Related: ADR 003, ADR 005
+Triggers:
+  - changing where dashboard filter state lives or how it is serialised
+  - making a dashboard, not just a pane, shareable or bookmarkable
+  - touching browser history from the dashboard controller
+  - rendering a dashboard page that arrives with filters already applied
+Topics: cross-filtering, urls, stimulus, turbo, progressive-enhancement
+---
+
+# ADR 008: Dashboard Filters in the Page URL
+
+## Context
+
+ADR 003 kept a dashboard's filter state in the Stimulus controller and
+in each Turbo Frame's `src`, and named the cost: a reload lost every
+filter, and a filtered dashboard could not be shared as a link. ADR 005
+gave each pane a URL that carries its filters, which made a single
+pane shareable but not the dashboard around it.
+
+The host application's page URL is the natural home. It is what a
+browser bookmarks, what a person pastes into a message, and what Rails
+already parses into `params[:q]` on the way in.
+
+## Decision
+
+**The page URL carries the dashboard's filters as `q[...]`, the same
+Ransack parameters every pane already accepts.**
+
+```
+/reports/orders?q[customer_region_eq]=APAC&q[status_eq]=paid
+```
+
+**The server renders the initial state.** `janela_dashboard` reads
+`params[:q]` from the page request and sets it as the controller's
+starting filters; `janela_pane` bakes the same filters into each
+frame's initial `src`. A dashboard opened from a shared link is
+therefore correct before any JavaScript runs, and the controller's
+first pass over the frames changes nothing, so nothing loads twice.
+
+**The controller keeps the URL current.** Whenever filters change it
+rewrites the page URL's `q[...]` parameters with `history.replaceState`,
+preserving whatever else is in the query string and Turbo's own
+history state. Filter keys are written in sorted order on both sides
+so the server and the browser serialise identically.
+
+**Replace, not push.** Every click does not become a history entry.
+The back button leaves the dashboard, as it does in every BI tool;
+undoing a filter is clicking it again or clearing. Pushing each toggle
+would trap the user in their own click history.
+
+## Consequences
+
+- A reload keeps the filters. A pasted dashboard URL opens filtered.
+  Issue #1 is closed.
+- A pane URL and a dashboard URL now share the same `q` vocabulary, so
+  a filter copied from one works in the other. That is the payoff of
+  ADR 002 making Ransack parameters the contract rather than a Janela
+  vocabulary.
+- The host page's other query parameters survive untouched. Janela
+  only owns the `q` namespace on that URL, which a host using Ransack
+  for a search form on the same page would also want. Documented: put
+  a dashboard and a Ransack search form on different pages, or expect
+  them to share filters.
+- Two dashboards on one page would share one URL and one `q`. Not
+  supported and not a goal; one dashboard per page is the shape.

data/docs/decisions/009-snapshots.md

@@ -0,0 +1,141 @@
+---
+Date: 2026-09-15
+Status: Accepted
+Related: ADR 001, ADR 002, ADR 005, ADR 008
+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
+  - scheduling anything with ActiveJob
+  - changing what a snapshot stores or how a stored pane is addressed
+  - anything called static mode, publish, report history or as-of
+Topics: snapshots, static-mode, publishing, persistence, activejob, urls
+---
+
+# ADR 009: Snapshots
+
+## Context
+
+The founding brief describes two modes over one definition: a dynamic
+dashboard for analysts, with slicers and cross-filtering, and the same
+dashboard published as a locked, static view for an audience that
+should see exactly what was signed off and nothing else. Everything
+built so far is the dynamic mode. This ADR is the static one.
+
+The brief also settled the shape in principle: publishing spawns a
+frozen record through ActiveJob rather than toggling the live
+dashboard, so an analyst editing tomorrow cannot silently change what a
+client saw today. What remained open was what exactly is frozen, how a
+frozen pane is addressed, and how much new surface the engine grows.
+
+This is the first thing Janela writes to a database. Until now the
+engine was read-only over the host's own tables.
+
+The incumbent's vocabulary is a useful check. Power BI Report Server
+calls this a report snapshot, "a report that contains layout
+information and query results retrieved at a specific point in time",
+accumulates them as report history, and keeps saved filter state
+(bookmarks) as a separate concept. That separation matches ADR 008.
+
+## Decision
+
+**A snapshot freezes results, not HTML.** Each pane's result, the
+label-to-value hash or the single value, is stored as JSON together
+with what produced it: model route key, measure, dimension,
+granularity, limit. Rendering stays live code, so a snapshot taken
+today is drawn with tomorrow's chart improvements, stays a few
+kilobytes, and cannot freeze a rendering bug into history. The
+renderer is not stored; a stored pane can be shown as a table or a
+chart by whoever renders it, because the renderer is a viewing choice,
+not part of the data.
+
+**One row is one taking.** "Publish this dashboard as of today" means
+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
+here, nothing is declared twice.
+
+```ruby
+Janela::Snapshot.take(name: "September 2026", filters: { status_eq: "paid" }) do |take|
+  take.pane Order, :revenue,                                on: policy_scope(Order)
+  take.pane Order, :revenue, by: :status,                   on: policy_scope(Order)
+  take.pane Order, :revenue, by: :placed_on, granularity: :week
+end
+```
+
+`on:` is per pane, since a snapshot may span models and a relation
+cannot be serialised. It defaults to the model's `all`.
+
+**A stored pane has a URL, and it says as of.** Following ADR 005's
+naming table, an analyst says "orders revenue by status *as of* the
+September snapshot":
+
+```
+/dashboards/snapshots/42/orders/revenue/status
+/dashboards/snapshots/42/orders/revenue/status?as=bar
+```
+
+Same grammar as a live pane with a `snapshots/:id/` prefix. A pane the
+snapshot does not contain is a 404, and `q` is ignored: the filters
+were fixed when it was taken. The naming table gains a row: *as of* is
+`/snapshots/:id/`.
+
+**Static mode is what a stored pane is, not a switch.** It has no
+filter key, no click action, no dashboard controller, no `q`. Tables
+render values without buttons; charts ignore clicks. That is the
+"no slicers, no surprises" mode from the README, and it costs nothing
+new because time panes already taught the code to be non-clickable.
+The host renders one with `janela_snapshot_pane snapshot, Order,
+:revenue, by: :status, as: :bar`, the same shape as `janela_pane`.
+
+**Taking is a Ruby method; the job is a thin wrapper.**
+`Snapshot.take` is the API and runs wherever it is called. A
+`Janela::SnapshotJob` wraps it for ActiveJob so a host can schedule it
+with whatever it already uses, taking serialisable arguments (name,
+filters, a list of pane hashes). Because a job cannot receive a
+relation, the shipped job uses each model's default scope. A tenanted
+host writes its own job around `take`, passing `on:` from whatever
+identifies the tenant. This is documented rather than solved: tenancy
+is the host's, as ADR 002 decided.
+
+**One table, named by convention.** `janela_snapshots` with `name`,
+`taken_at`, `filters` (JSON), `panes` (JSON) and timestamps, installed
+with the standard `rails janela:install:migrations`. The `janela_`
+prefix is the Rails engine convention that keeps an engine's tables
+from colliding with the host's, as `active_storage_blobs` and
+`solid_queue_jobs` do. It is not configurable: the host never types
+the table name, only `Janela::Snapshot`, and a knob for a name nobody
+types is exactly what ADR 001 declines to add. Snapshots are
+immutable; deleting them is host policy.
+
+**Who may see a snapshot is the host's decision.** Snapshot panes are
+served through the same controllers, so the host's authentication
+applies by default. An external audience with no accounts is the case
+that motivates snapshots, and it is served by the host building its
+own page over `janela_snapshot_pane` behind whatever share tokens or
+signed links it already trusts. Janela stays out of access control,
+per ADR 002 and ADR 004.
+
+## Consequences
+
+- Janela gains a migration, a model and a job: its first write
+  surface. Hosts that never take a snapshot never need the migration;
+  live dashboards remain read-only over the host's tables.
+- Result JSON is small for category panes and bounded by `limit`
+  (ADR 007). A time pane over a long range at fine granularity is the
+  one way a snapshot gets large, and that is visible at take time.
+- Storing the renderer's inputs rather than its output means a
+  snapshot cannot reproduce an old rendering exactly. Accepted: the
+  numbers are the record, not the pixels.
+- Per-pane `on:` is more typing than one scope for the whole taking.
+  It is also the only honest option once a snapshot spans models, and
+  it keeps the tenancy question where ADR 002 put it.
+- The shipped job is deliberately naive. If most hosts turn out to
+  write their own, the job should be removed rather than grown.
+- Snapshots are additive to the public API. Whether they ship in the
+  next release or the one after is a release decision, not a design
+  one.
+- Not decided here: comparing two snapshots, an "other" bucket for
+  limited panes, retention, or an index page listing snapshots. Each
+  is its own ADR if a host needs it.

data/docs/decisions/INDEX.md

@@ -22,11 +22,14 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 |-------|------|
 | **Vision, scope, forkability** | 001 |
 | **Open-source & host-decoupling** | 001 |
-| **DSL & query layer** | 002 |
-| **Dependencies** | 002, 003, 004 |
-| **Authorisation** | 002, 003, 004 |
-| **Cross-filtering & Hotwire** | 003, 004 |
-| **JavaScript delivery & charts** | 004 |
+| **DSL & query layer** | 002, 006, 007 |
+| **Dependencies** | 002, 003, 004, 006 |
+| **Authorisation** | 002, 003, 004, 009 |
+| **Cross-filtering & Hotwire** | 003, 004, 005, 008 |
+| **JavaScript delivery & charts** | 004, 006 |
+| **Time dimensions** | 006 |
+| **Routes, URLs & naming** | 005, 007, 008, 009 |
+| **Snapshots & publishing** | 009 |
 | **Security** | 003 |
 | **Testing** | 003 |
 
@@ -38,7 +41,12 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 002 | Measures and Dimensions over Ransack | 2026-09-13 | Accepted |
 | 003 | Cross-filtering with Turbo Frames | 2026-09-13 | Accepted |
 | 004 | Charts and JavaScript Delivery | 2026-09-15 | Accepted |
+| 005 | Pane URLs and the Mount Path | 2026-09-15 | Accepted |
+| 006 | Time Dimensions with Groupdate | 2026-09-15 | Accepted |
+| 007 | Ordering and Limits | 2026-09-15 | Accepted |
+| 008 | Dashboard Filters in the Page URL | 2026-09-15 | Accepted |
+| 009 | Snapshots | 2026-09-15 | Accepted |
 
 ## Next number
 
-Next ADR: 005
+Next ADR: 010

data/lib/janela/definition.rb

@@ -12,31 +12,46 @@ module Janela
       measures[name] = Measure.build(name, **aggregate)
     end
 
-    def dimension(name, through: nil)
-      dimensions[name] = Dimension.new(name, model: model, through: through)
+    def dimension(name, through: nil, column: nil, granularity: nil)
+      dimensions[name] = Dimension.new(name, model: model, through: through, column: column, granularity: granularity)
     end
 
     # Filters are Ransack params, so a host can pass params[:q] straight
     # through from a search_form_for slicer. Scope with on: to respect the
-    # host's authorisation, e.g. on: policy_scope(Order).
-    def query(measure_name, by: nil, where: {}, on: nil)
+    # host's authorisation, e.g. on: policy_scope(Order). A time dimension
+    # buckets by its declared granularity unless one is given.
+    def query(measure_name, by: nil, where: {}, on: nil, granularity: nil, limit: nil)
+      measure = measure!(measure_name)
       relation = filter(on || model.all, where)
+      return measure.apply(relation) if by.nil?
 
-      if by
-        dimension = dimension!(by)
-        relation = relation.left_joins(dimension.through) if dimension.through
-        relation = relation.group(dimension.attribute)
-      end
+      dimension = dimension!(by)
+      relation = relation.left_joins(dimension.through) if dimension.through
 
-      measure!(measure_name).apply(relation)
+      if dimension.time?
+        granularity = Dimension.granularity!(granularity || dimension.granularity)
+        options = granularity == "week" ? { week_start: Date.beginning_of_week } : {}
+        buckets = relation.group_by_period(granularity, dimension.qualified_column, **options)
+        measure.apply(buckets).transform_keys { |bucket| dimension.label(bucket, granularity) }
+      else
+        grouped = relation.group(dimension.attribute).order(Arel.sql("#{measure.sql_alias} DESC"))
+        grouped = grouped.limit(limit!(limit)) if limit
+        measure.apply(grouped)
+      end
     end
 
     def dimension!(name)
       dimensions.fetch(name) { raise Error, "#{model} has no janela dimension #{name.inspect}" }
     end
 
+    def limit!(value)
+      limit = Integer(value, exception: false)
+      raise Error, "limit must be a whole number from 1 to 1000, got #{value.inspect}" unless limit&.between?(1, 1000)
+      limit
+    end
+
     def ransackable_attributes
-      dimensions.values.reject(&:through).map { |dimension| dimension.name.to_s }
+      dimensions.values.reject(&:through).map { |dimension| dimension.column.to_s }
     end
 
     def ransackable_associations

data/lib/janela/dimension.rb

@@ -1,21 +1,56 @@
 module Janela
   class Dimension
-    attr_reader :name, :model, :through
+    GRANULARITIES = %w[hour day week month quarter year].freeze
 
-    def initialize(name, model:, through: nil)
+    LABELS = {
+      "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") },
+      "quarter" => ->(t) { "Q#{(t.month - 1) / 3 + 1} #{t.year}" },
+      "year" => ->(t) { t.strftime("%Y") }
+    }.freeze
+
+    attr_reader :name, :model, :through, :column, :granularity
+
+    # A dimension is named for what it means on the dashboard and reads a
+    # column that may be called something else, usually on an association:
+    # dimension :customer, through: :customer, column: :name.
+    def initialize(name, model:, through: nil, column: nil, granularity: nil)
       @name = name
       @model = model
       @through = through
+      @column = (column || name).to_sym
+      @granularity = granularity&.to_s
 
       raise Error, "#{model} has no association #{through.inspect}" if through && reflection.nil?
+      self.class.granularity!(@granularity) if @granularity
+    end
+
+    def self.granularity!(value)
+      value = value.to_s
+      raise Error, "unknown granularity #{value.inspect}, use one of #{GRANULARITIES.join(', ')}" unless GRANULARITIES.include?(value)
+      value
+    end
+
+    def time?
+      !granularity.nil?
     end
 
     def attribute
-      klass.arel_table[name]
+      klass.arel_table[column]
+    end
+
+    def qualified_column
+      "#{klass.table_name}.#{column}"
     end
 
     def ransack_name
-      through ? "#{through}_#{name}" : name.to_s
+      through ? "#{through}_#{column}" : column.to_s
+    end
+
+    def label(bucket, granularity = self.granularity)
+      LABELS.fetch(granularity).call(bucket)
     end
 
     private