@tekki-forge/runtime-api 0.1.0 → 0.3.0

package/dist/dashboard.js

@@ -2,6 +2,8 @@ import { authorize, evaluate } from "@tekki-forge/runtime-permissions";
 import { QueryError, parseListQuery, parseSort } from "./query.js";
 import { relationInclude } from "./serialize.js";
 const MAX_BUCKET_ROWS = 50_000;
+const MAX_STACKS = 8;
+const TIMESTAMPS = ["createdAt", "updatedAt"];
 /** "$today", "$today-30d", "$now", "$startOfMonth", "$me" → concrete values. */
 export function resolveTokens(where, userId, now = new Date()) {
     const today = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
@@ -28,7 +30,32 @@ export function resolveTokens(where, userId, now = new Date()) {
     }
     return out;
 }
-export function bucketKey(d, by) {
+// ---- Timezones ----
+const PARTS = new Map();
+/** `d` as wall-clock time in `timeZone`, expressed as a Date whose UTC fields hold the local values. */
+export function zonedWallClock(d, timeZone) {
+    if (timeZone === "UTC")
+        return d;
+    let f = PARTS.get(timeZone);
+    if (!f) {
+        f = new Intl.DateTimeFormat("en-US", { timeZone, year: "numeric", month: "numeric", day: "numeric", hour: "numeric", minute: "numeric", second: "numeric", hourCycle: "h23" });
+        PARTS.set(timeZone, f);
+    }
+    const p = Object.fromEntries(f.formatToParts(d).map((x) => [x.type, x.value]));
+    return new Date(Date.UTC(Number(p.year), Number(p.month) - 1, Number(p.day), Number(p.hour) % 24, Number(p.minute), Number(p.second), d.getUTCMilliseconds()));
+}
+/** The instant at which the wall clock in `timeZone` shows midnight of `date` (YYYY-MM-DD); DST-safe. */
+export function zonedMidnight(date, timeZone) {
+    const guess = new Date(`${date}T00:00:00Z`).getTime();
+    if (timeZone === "UTC")
+        return new Date(guess);
+    const offset = (t) => zonedWallClock(new Date(t), timeZone).getTime() - t;
+    const first = guess - offset(guess);
+    const second = guess - offset(first);
+    return new Date(second);
+}
+export function bucketKey(d, by, timeZone = "UTC") {
+    d = zonedWallClock(d, timeZone);
     const y = d.getUTCFullYear();
     const m = String(d.getUTCMonth() + 1).padStart(2, "0");
     if (by === "year")
@@ -53,8 +80,35 @@ function nextBucket(key, by) {
     d.setUTCDate(d.getUTCDate() + (by === "week" ? 7 : 1));
     return d.toISOString().slice(0, 10);
 }
+const bucketStart = (key) => (key.length === 4 ? `${key}-01-01` : key.length === 7 ? `${key}-01` : key);
+/**
+ * List filters selecting one bucket: dates for date fields (and UTC dashboards), instants of local midnight otherwise,
+ * so clicking a point opens exactly the records it counts.
+ */
+export function bucketRange(key, by, kind, timeZone = "UTC") {
+    const start = bucketStart(key);
+    const end = bucketStart(nextBucket(key, by));
+    if (kind === "date" || timeZone === "UTC")
+        return { gte: start, lt: end };
+    return { gte: zonedMidnight(start, timeZone).toISOString(), lt: zonedMidnight(end, timeZone).toISOString() };
+}
 /** Periods in a metric's sparkline (the last one is the current period). */
 export const TREND_PERIODS = 12;
+/** Start of the current calendar period (weeks start on Monday) in `timeZone`: the local date and its instant. */
+export function periodStart(now, period, timeZone = "UTC") {
+    const l = zonedWallClock(now, timeZone);
+    const y = l.getUTCFullYear();
+    const m = l.getUTCMonth();
+    const start = period === "week"
+        ? new Date(Date.UTC(y, m, l.getUTCDate() - ((l.getUTCDay() + 6) % 7)))
+        : period === "month"
+            ? new Date(Date.UTC(y, m, 1))
+            : period === "quarter"
+                ? new Date(Date.UTC(y, m - (m % 3), 1))
+                : new Date(Date.UTC(y, 0, 1));
+    const date = start.toISOString().slice(0, 10);
+    return { date, instant: zonedMidnight(date, timeZone) };
+}
 /** `d` moved by `n` periods; months clamp to the month's last day (31 Mar − 1 month = 28/29 Feb). */
 export function shiftPeriod(d, period, n) {
     if (period === "week")
@@ -77,21 +131,30 @@ export function trendWindows(now, period, count = TREND_PERIODS) {
     });
 }
 const toNumber = (v) => (v === null || v === undefined ? 0 : Number(typeof v === "object" ? String(v) : v));
+/** Ratio of two aggregates, null without a denominator. */
+export const ratioOf = (numerator, denominator) => (numerator === null || !denominator ? null : numerator / denominator);
 export class DashboardService {
     service;
     constructor(service) {
         this.service = service;
     }
-    readable(entity, w, ctx) {
+    entityReadable(entity, fields, ctx) {
         if (!authorize(entity, "read", ctx.principal).allowed)
             return false;
         if (entity.features.tenant && !ctx.principal?.organizationId)
             return false;
-        for (const name of [w.field, w.groupBy?.field, ...Object.keys(w.where).map((k) => k.split(".")[0])]) {
-            if (!this.fieldReadable(entity, name, ctx))
-                return false;
-        }
-        return true;
+        return fields.every((name) => this.fieldReadable(entity, name, ctx));
+    }
+    sourceReadable(s, ctx, extra = []) {
+        const entity = this.service.entityByName(s.entity);
+        return !!entity && this.entityReadable(entity, [s.field, s.groupField, ...Object.keys(s.where).map((k) => k.split(".")[0]), ...extra], ctx);
+    }
+    readable(entity, w, ctx) {
+        if (w.ratio)
+            return [w.ratio.numerator, w.ratio.denominator].every((s) => this.sourceReadable(s, ctx, w.period || w.compare ? [s.dateField] : []));
+        if (w.series)
+            return w.series.some((s) => this.sourceReadable(s, ctx));
+        return this.entityReadable(entity, [w.field, w.groupBy?.field, w.stackBy, w.period?.dateField, ...Object.keys(w.where).map((k) => k.split(".")[0])], ctx);
     }
     fieldReadable(entity, name, ctx) {
         const f = entity.fields.find((x) => x.name === name || x.apiName === name);
@@ -100,32 +163,44 @@ export class DashboardService {
         const d = evaluate(f.access.read, ctx.principal);
         return d.allowed && d.scope === "all";
     }
-    /** `now` is injectable for tests; relative dates in filters ($today…) are resolved against it. */
-    async compute(ctx, now = new Date()) {
+    /** Tabs the viewer may see (none when the dashboard has no tabs). */
+    visibleTabs(ctx) {
+        const tabs = this.service.app.dashboard?.tabs ?? [];
+        return tabs.filter((t) => !t.visibleTo || t.visibleTo.some((r) => ctx.principal?.roles.includes(r))).map((t) => ({ id: t.id, title: t.title }));
+    }
+    /**
+     * The widgets computed for the viewer. With tabs, `tab` picks one (default: every visible tab's widgets);
+     * `now` is injectable for tests; relative dates in filters ($today…) are resolved against it.
+     */
+    async compute(ctx, now = new Date(), tab) {
         const dashboard = this.service.app.dashboard;
         if (!dashboard)
             return { widgets: null };
+        const tabs = dashboard.tabs ? this.visibleTabs(ctx) : undefined;
+        let ids;
+        if (dashboard.tabs) {
+            const chosen = dashboard.tabs.filter((t) => tabs.some((v) => v.id === t.id) && (tab === undefined || t.id === tab));
+            ids = new Set(chosen.flatMap((t) => t.widgets));
+        }
         const out = [];
         for (const w of dashboard.widgets) {
+            if (ids && !ids.has(w.id))
+                continue;
             const entity = this.service.entityByName(w.entity);
+            if (w.visibleTo && !w.visibleTo.some((r) => ctx.principal?.roles.includes(r)))
+                continue;
             if (!this.readable(entity, w, ctx))
                 continue;
             const base = { id: w.id, type: w.type, title: w.title, span: w.span, entity: entity.name, path: entity.path, ...(w.aggregate !== "count" && w.field ? { field: w.field } : {}) };
             try {
-                const access = { ...this.service.queryAccess(entity, ctx), anyField: true };
-                const filters = parseListQuery(entity, resolveTokens(w.where, ctx.principal?.id ?? null, now), access).where;
-                const where = { AND: [...this.service.readWhere(entity, ctx), ...filters] };
-                if (w.type === "metric") {
-                    // The trend is dropped (not the widget) when the viewer can't read the date field it is based on.
-                    const withTrend = w.compare && this.fieldReadable(entity, w.compare.dateField, ctx);
-                    const [value, trend] = await Promise.all([this.aggregate(entity, where, w), withTrend ? this.trend(entity, w, ctx, now) : undefined]);
-                    out.push({ ...base, value, ...(trend ? { trend } : {}) });
-                }
+                if (w.type === "metric")
+                    out.push({ ...base, ...(await this.metric(entity, w, ctx, now)) });
                 else if (w.type === "chart")
-                    out.push({ ...base, chart: w.chart, groupBy: w.groupBy, data: await this.series(entity, where, w) });
+                    out.push({ ...base, chart: w.chart, groupBy: w.groupBy, ...(await this.chart(entity, w, ctx, now)) });
                 else {
+                    const access = { ...this.service.queryAccess(entity, ctx), anyField: true };
                     const rows = await this.service.delegate(entity).findMany({
-                        where,
+                        where: this.where(entity, w.where, ctx, now),
                         orderBy: parseSort(entity, w.sort, access),
                         take: w.limit,
                         include: relationInclude(entity),
@@ -140,16 +215,74 @@ export class DashboardService {
                 out.push({ ...base, error: e instanceof QueryError ? e.message : "This widget could not be loaded" });
             }
         }
-        return { widgets: out };
+        return { widgets: out, ...(tabs ? { tabs } : {}) };
+    }
+    get timeZone() {
+        return this.service.app.dashboard?.timezone ?? "UTC";
+    }
+    /** The viewer's row-level, tenant and owner rules plus the widget's filter. */
+    where(entity, where, ctx, now) {
+        const access = { ...this.service.queryAccess(entity, ctx), anyField: true };
+        const filters = parseListQuery(entity, resolveTokens(where, ctx.principal?.id ?? null, now), access).where;
+        return { AND: [...this.service.readWhere(entity, ctx), ...filters] };
+    }
+    /**
+     * The whole current calendar period: `{ start of this period <= dateField < start of the next }`, so records
+     * dated later this month (upcoming bookings, due dates) count too. Date fields compare by local date,
+     * datetimes by instant.
+     */
+    periodFilter(entity, dateField, period, now) {
+        const start = periodStart(now, period, this.timeZone);
+        const nextDate = shiftPeriod(new Date(`${start.date}T00:00:00Z`), period, 1).toISOString().slice(0, 10);
+        // A date field holds a calendar date (stored at UTC midnight): compare it with the local dates.
+        if (this.fieldKind(entity, dateField) === "date")
+            return { [dateField]: { gte: new Date(`${start.date}T00:00:00Z`), lt: new Date(`${nextDate}T00:00:00Z`) } };
+        return { [dateField]: { gte: start.instant, lt: zonedMidnight(nextDate, this.timeZone) } };
+    }
+    async metric(entity, w, ctx, now) {
+        let value;
+        let parts = {};
+        if (w.ratio) {
+            const [n, d] = await Promise.all([w.ratio.numerator, w.ratio.denominator].map((s) => this.sourceValue(s, ctx, now, w.period ? { period: w.period.period } : undefined)));
+            value = ratioOf(n ?? null, d ?? null);
+            parts = { ratio: { numerator: n, denominator: d } };
+        }
+        else {
+            const where = this.where(entity, w.where, ctx, now);
+            value = await this.aggregate(entity, w.period ? { AND: [where, this.periodFilter(entity, w.period.dateField, w.period.period, now)] } : where, w.aggregate, w.field);
+        }
+        // The trend is dropped (not the widget) when the viewer can't read the date field it is based on.
+        const withTrend = w.compare && (w.ratio || this.fieldReadable(entity, w.compare.dateField, ctx));
+        const trend = withTrend ? await this.trend(entity, w, ctx, now) : undefined;
+        const numeric = value === null ? null : toNumber(value);
+        const goal = w.goal
+            ? {
+                target: w.goal.target,
+                progress: numeric === null ? 0 : numeric / w.goal.target,
+                reached: numeric !== null && numeric >= w.goal.target,
+                good: numeric === null ? null : (numeric >= w.goal.target) === (w.goal.trend === "up-is-good"),
+            }
+            : undefined;
+        return { value, ...parts, ...(trend ? { trend } : {}), ...(goal ? { goal } : {}), ...(w.period ? { period: w.period.period } : {}) };
     }
-    async aggregate(entity, where, w) {
+    /** One ratio side, within the viewer's rules, optionally limited to a calendar period or a [start, end) window. */
+    async sourceValue(s, ctx, now, window) {
+        const entity = this.service.entityByName(s.entity);
+        const asOf = window && "asOf" in window ? window.asOf : now;
+        const where = this.where(entity, s.where, ctx, asOf);
+        const dateField = s.dateField ?? "createdAt";
+        const extra = !window ? [] : "period" in window ? [this.periodFilter(entity, dateField, window.period, now)] : [{ [dateField]: { gte: window.start, lt: window.end } }];
+        const v = await this.aggregate(entity, { AND: [where, ...extra] }, s.aggregate, s.field);
+        return v === null ? null : toNumber(v);
+    }
+    async aggregate(entity, where, aggregate, field) {
         const d = this.service.delegate(entity);
-        if (w.aggregate === "count")
+        if (aggregate === "count")
             return d.count({ where });
-        const op = `_${w.aggregate}`;
-        const r = await d.aggregate({ where, [op]: { [w.field]: true } });
-        const v = r[op]?.[w.field];
-        return v === null || v === undefined ? (w.aggregate === "sum" ? 0 : null) : typeof v === "object" ? String(v) : v;
+        const op = `_${aggregate}`;
+        const r = await d.aggregate({ where, [op]: { [field]: true } });
+        const v = r[op]?.[field];
+        return v === null || v === undefined ? (aggregate === "sum" ? 0 : null) : typeof v === "object" ? String(v) : v;
     }
     /**
      * The metric over each of the last TREND_PERIODS rolling periods, within exactly the same row-level, tenant and
@@ -157,12 +290,13 @@ export class DashboardService {
      */
     async trend(entity, w, ctx, now) {
         const { period, dateField, trend } = w.compare;
-        const access = { ...this.service.queryAccess(entity, ctx), anyField: true };
-        const scope = this.service.readWhere(entity, ctx);
         const windows = trendWindows(now, period);
-        const values = await Promise.all(windows.map(async ({ start, end, asOf }) => {
-            const filters = parseListQuery(entity, resolveTokens(w.where, ctx.principal?.id ?? null, asOf), access).where;
-            const v = await this.aggregate(entity, { AND: [...scope, ...filters, { [dateField]: { gte: start, lt: end } }] }, w);
+        const values = await Promise.all(windows.map(async (win) => {
+            if (w.ratio) {
+                const [n, d] = await Promise.all([this.sourceValue(w.ratio.numerator, ctx, now, win), this.sourceValue(w.ratio.denominator, ctx, now, win)]);
+                return ratioOf(n, d);
+            }
+            const v = await this.aggregate(entity, { AND: [this.where(entity, w.where, ctx, win.asOf), { [dateField]: { gte: win.start, lt: win.end } }] }, w.aggregate, w.field);
             return v === null ? null : toNumber(v);
         }));
         const current = values.at(-1) ?? null;
@@ -180,48 +314,88 @@ export class DashboardService {
             series: windows.map((x, i) => ({ start: x.start.toISOString().slice(0, 10), end: x.end.toISOString().slice(0, 10), value: values[i] ?? null })),
         };
     }
-    /** `label` is ready to show (default language); `key` is the raw group value so clients can localize it ("__other" = the rest). */
-    async series(entity, where, w) {
-        const g = w.groupBy;
-        const d = this.service.delegate(entity);
-        const f = entity.fields.find((x) => x.name === g.field);
-        if (g.by) {
-            // Date buckets computed from the rows (keeps every permission rule in the Prisma where).
-            const rows = await d.findMany({ where: { AND: [where, { [g.field]: { not: null } }] }, select: { [g.field]: true, ...(w.field ? { [w.field]: true } : {}) }, orderBy: { [g.field]: "asc" }, take: MAX_BUCKET_ROWS });
-            const buckets = new Map();
-            for (const r of rows) {
-                const key = bucketKey(new Date(r[g.field]), g.by);
-                buckets.set(key, [...(buckets.get(key) ?? []), w.field ? toNumber(r[w.field]) : 1]);
-            }
-            const keys = [...buckets.keys()];
-            if (!keys.length)
-                return [];
-            const out = [];
-            for (let k = keys[0];; k = nextBucket(k, g.by)) {
-                const values = buckets.get(k) ?? [];
-                out.push({ label: k, key: k, value: reduce(values, w.aggregate) });
-                if (k >= keys[keys.length - 1] || out.length > 1000)
-                    break;
-            }
-            return out;
-        }
-        const column = f?.relation ? f.relation.foreignKey : g.field;
-        const grouped = await d.groupBy({
-            by: [column],
-            where,
-            _count: { _all: true },
-            ...(w.aggregate !== "count" ? { [`_${w.aggregate}`]: { [w.field]: true } } : {}),
+    // ---- Charts ----
+    async chart(entity, w, ctx, now) {
+        if (w.series)
+            return this.multiSeries(w, ctx, now);
+        const where = this.where(entity, w.where, ctx, now);
+        const filter = resolveTokens(w.where, ctx.principal?.id ?? null, now);
+        if (w.chart === "heatmap")
+            return { heatmap: await this.heatmap(entity, where, w, filter, now) };
+        if (w.chart === "funnel")
+            return { data: await this.funnel(entity, where, w, filter) };
+        if (w.stackBy)
+            return this.stacked(entity, where, w, filter);
+        const data = w.groupBy.by
+            ? await this.dateSeries(entity, where, { field: w.groupBy.field, by: w.groupBy.by, aggregate: w.aggregate, value: w.field, filter })
+            : await this.categories(entity, where, w.groupBy.field, w.aggregate, w.field, filter);
+        return { data: w.groupBy.by ? data : limitOther(data, w.limit) };
+    }
+    href(entity, filter, params) {
+        return `/${entity.path}?${new URLSearchParams({ ...filter, ...params }).toString()}`;
+    }
+    /** Contiguous date buckets (from the first to the last record), computed from the rows so every permission rule stays in the Prisma where. */
+    async dateBuckets(entity, where, field, by, value, extra = []) {
+        const rows = await this.service.delegate(entity).findMany({
+            where: this.notNull(entity, where, field),
+            select: { [field]: true, ...(value ? { [value]: true } : {}), ...Object.fromEntries(extra.map((x) => [x, true])) },
+            orderBy: { [field]: "asc" },
+            take: MAX_BUCKET_ROWS,
         });
-        const value = (r) => (w.aggregate === "count" ? r._count._all : toNumber(r[`_${w.aggregate}`]?.[w.field]));
+        const tz = this.fieldTimeZone(entity, field);
+        const buckets = new Map();
+        for (const r of rows) {
+            const key = bucketKey(new Date(r[field]), by, tz);
+            buckets.set(key, [...(buckets.get(key) ?? []), r]);
+        }
+        const found = [...buckets.keys()].sort();
+        if (!found.length)
+            return { keys: [], buckets };
+        const keys = [];
+        for (let k = found[0];; k = nextBucket(k, by)) {
+            keys.push(k);
+            if (k >= found[found.length - 1] || keys.length > 1000)
+                break;
+        }
+        return { keys, buckets };
+    }
+    /** `where` and the date present (createdAt and required fields always are: Prisma rejects `not: null` on them). */
+    notNull(entity, where, field) {
+        const f = entity.fields.find((x) => x.name === field);
+        return !f || f.required ? where : { AND: [where, { [field]: { not: null } }] };
+    }
+    /** Date-only fields hold a calendar date: they are bucketed as stored, whatever the dashboard's timezone. */
+    fieldTimeZone(entity, field) {
+        return entity.fields.find((f) => f.name === field)?.kind === "date" ? "UTC" : this.timeZone;
+    }
+    fieldKind(entity, field) {
+        return TIMESTAMPS.includes(field) ? "datetime" : (entity.fields.find((f) => f.name === field)?.kind ?? "datetime");
+    }
+    rangeParams(entity, field, key, by) {
+        const range = bucketRange(key, by, this.fieldKind(entity, field), this.fieldTimeZone(entity, field));
+        return { [`${field}.gte`]: range.gte, [`${field}.lt`]: range.lt };
+    }
+    async dateSeries(entity, where, o) {
+        const { keys, buckets } = await this.dateBuckets(entity, where, o.field, o.by, o.value);
+        return keys.map((k) => ({
+            label: k,
+            key: k,
+            value: reduce((buckets.get(k) ?? []).map((r) => (o.value ? toNumber(r[o.value]) : 1)), o.aggregate),
+            href: this.href(entity, o.filter, this.rangeParams(entity, o.field, k, o.by)),
+        }));
+    }
+    /** Labels of category values in the default language (enum labels, yes/no, related records' display field). */
+    async labeler(entity, fieldName, keys) {
+        const f = entity.fields.find((x) => x.name === fieldName);
         let labels = new Map();
         if (f?.relation) {
-            const ids = grouped.map((r) => r[column]).filter(Boolean);
+            const ids = keys.filter(Boolean);
             const target = f.relation.entity === "User" ? this.service.prisma.user : this.service.prisma[f.relation.delegate];
             const display = f.relation.targetDisplay;
             const rows = ids.length ? await target.findMany({ where: { id: { in: ids } }, select: { id: true, [display]: true } }) : [];
             labels = new Map(rows.map((r) => [r.id, String(r[display] ?? r.id)]));
         }
-        const label = (v) => {
+        return (v) => {
             if (v === null || v === undefined)
                 return "None";
             if (f?.enumValues)
@@ -230,16 +404,262 @@ export class DashboardService {
                 return v ? "Yes" : "No";
             return labels.get(String(v)) ?? String(v);
         };
-        const data = grouped
-            .map((r) => ({ label: label(r[column]), key: r[column] === null || r[column] === undefined ? null : String(r[column]), value: value(r), href: `/${entity.path}?${encodeURIComponent(g.field)}=${r[column] === null ? "null" : encodeURIComponent(String(r[column]))}` }))
+    }
+    column(entity, fieldName) {
+        const f = entity.fields.find((x) => x.name === fieldName);
+        return f?.relation ? f.relation.foreignKey : fieldName;
+    }
+    async groupRows(entity, where, columns, aggregate, value) {
+        const rows = await this.service.delegate(entity).groupBy({
+            by: columns,
+            where,
+            _count: { _all: true },
+            ...(aggregate !== "count" ? { [`_${aggregate}`]: { [value]: true } } : {}),
+        });
+        return { rows, value: (r) => (aggregate === "count" ? r._count._all : toNumber(r[`_${aggregate}`]?.[value])) };
+    }
+    /** One point per category value, largest first. */
+    async categories(entity, where, fieldName, aggregate, value, filter) {
+        const column = this.column(entity, fieldName);
+        const { rows, value: of } = await this.groupRows(entity, where, [column], aggregate, value);
+        const label = await this.labeler(entity, fieldName, rows.map((r) => r[column]));
+        return rows
+            .map((r) => ({ label: label(r[column]), key: keyOf(r[column]), value: of(r), href: this.href(entity, filter, { [fieldName]: r[column] === null || r[column] === undefined ? "null" : String(r[column]) }) }))
             .sort((a, b) => b.value - a.value);
-        if (data.length <= w.limit)
-            return data;
-        const rest = data.slice(w.limit - 1);
-        return [...data.slice(0, w.limit - 1), { label: "Other", key: "__other", value: rest.reduce((s, x) => s + x.value, 0) }];
     }
+    /** Enum stages in order; cumulative = records at a stage or any later one. */
+    async funnel(entity, where, w, filter) {
+        const field = w.groupBy.field;
+        const stages = w.stages ?? [];
+        const { rows, value } = await this.groupRows(entity, { AND: [where, { [field]: { in: stages } }] }, [field], w.aggregate, w.field);
+        const label = await this.labeler(entity, field, []);
+        const at = new Map(rows.map((r) => [String(r[field]), value(r)]));
+        return stages.map((s, i) => {
+            const included = w.cumulative ? stages.slice(i) : [s];
+            return { label: label(s), key: s, value: included.reduce((sum, x) => sum + (at.get(x) ?? 0), 0), href: this.href(entity, filter, { [field]: included.join(",") }) };
+        });
+    }
+    /** groupBy × stackBy: categories plus one series per stack value (the smallest beyond MAX_STACKS merged as "Other"). */
+    async stacked(entity, where, w, filter) {
+        const g = w.groupBy;
+        const stackField = w.stackBy;
+        const stackColumn = this.column(entity, stackField);
+        // cells: category key → stack key → value
+        const cells = new Map();
+        const put = (c, s, v) => {
+            const row = cells.get(c) ?? new Map();
+            row.set(s, (row.get(s) ?? 0) + v);
+            cells.set(c, row);
+        };
+        let categories;
+        const NULL = "\u0000null";
+        const sk = (v) => (v === null || v === undefined ? NULL : String(v));
+        const stackRaw = new Map();
+        if (g.by) {
+            const by = g.by;
+            const { keys, buckets } = await this.dateBuckets(entity, where, g.field, by, w.field, [stackColumn]);
+            // Per bucket and stack value, the same reduction as a single series.
+            for (const k of keys) {
+                const byStack = new Map();
+                for (const r of buckets.get(k) ?? []) {
+                    stackRaw.set(sk(r[stackColumn]), r[stackColumn]);
+                    byStack.set(sk(r[stackColumn]), [...(byStack.get(sk(r[stackColumn])) ?? []), w.field ? toNumber(r[w.field]) : 1]);
+                }
+                for (const [s, vals] of byStack)
+                    put(k, s, reduce(vals, w.aggregate));
+            }
+            categories = keys.map((k) => ({ label: k, key: k, value: 0, href: this.href(entity, filter, this.rangeParams(entity, g.field, k, by)) }));
+        }
+        else {
+            const column = this.column(entity, g.field);
+            const { rows, value } = await this.groupRows(entity, where, [column, stackColumn], w.aggregate, w.field);
+            for (const r of rows) {
+                stackRaw.set(sk(r[stackColumn]), r[stackColumn]);
+                put(sk(r[column]), sk(r[stackColumn]), value(r));
+            }
+            const label = await this.labeler(entity, g.field, rows.map((r) => r[column]));
+            const raw = new Map(rows.map((r) => [sk(r[column]), r[column]]));
+            categories = [...cells.keys()].map((c) => ({ label: label(raw.get(c)), key: c === NULL ? null : c, value: 0, href: this.href(entity, filter, { [g.field]: c === NULL ? "null" : c }) }));
+        }
+        const catKey = (c) => (c.key === null ? NULL : c.key);
+        for (const c of categories)
+            c.value = [...(cells.get(catKey(c))?.values() ?? [])].reduce((a, b) => a + b, 0);
+        if (!g.by)
+            categories.sort((a, b) => b.value - a.value);
+        // Categories beyond the limit are merged into "Other" (category axes only; dates stay contiguous).
+        if (!g.by && categories.length > w.limit) {
+            const rest = categories.slice(w.limit - 1);
+            const other = new Map();
+            for (const c of rest)
+                for (const [s, v] of cells.get(catKey(c)) ?? [])
+                    other.set(s, (other.get(s) ?? 0) + v);
+            cells.set("__other", other);
+            categories = [...categories.slice(0, w.limit - 1), { label: "Other", key: "__other", value: rest.reduce((s, x) => s + x.value, 0) }];
+        }
+        // Stack values, largest first; the smallest are merged.
+        const totals = new Map();
+        for (const row of cells.values())
+            for (const [s, v] of row)
+                totals.set(s, (totals.get(s) ?? 0) + v);
+        const enumOrder = entity.fields.find((f) => f.name === stackField)?.enumValues?.map((v) => v.value);
+        let stacks = [...totals.keys()].sort((a, b) => (enumOrder ? enumOrder.indexOf(a) - enumOrder.indexOf(b) : (totals.get(b) ?? 0) - (totals.get(a) ?? 0)));
+        let otherStacks = [];
+        if (stacks.length > MAX_STACKS) {
+            const bySize = [...stacks].sort((a, b) => (totals.get(b) ?? 0) - (totals.get(a) ?? 0));
+            otherStacks = bySize.slice(MAX_STACKS - 1);
+            stacks = stacks.filter((s) => !otherStacks.includes(s));
+        }
+        const label = await this.labeler(entity, stackField, stacks.map((s) => stackRaw.get(s)));
+        const series = [...stacks, ...(otherStacks.length ? ["__other_stack"] : [])].map((s) => {
+            const keys = s === "__other_stack" ? otherStacks : [s];
+            return {
+                key: s === "__other_stack" ? "__other" : s === NULL ? null : s,
+                label: s === "__other_stack" ? "Other" : label(stackRaw.get(s)),
+                entity: entity.name,
+                path: entity.path,
+                aggregate: w.aggregate,
+                ...(w.field ? { field: w.field } : {}),
+                axis: "left",
+                values: categories.map((c) => keys.reduce((sum, k) => sum + (cells.get(catKey(c))?.get(k) ?? 0), 0)),
+                hrefs: categories.map((c) => {
+                    if (!c.href || s === "__other_stack")
+                        return null;
+                    return `${c.href}&${new URLSearchParams({ [stackField]: s === NULL ? "null" : s }).toString()}`;
+                }),
+            };
+        });
+        return { data: categories, series, stackBy: stackField };
+    }
+    /**
+     * Several series (possibly from several entities) on one axis. Each series is computed within its entity's
+     * rules; a series the viewer can't read is dropped (not the chart).
+     */
+    async multiSeries(w, ctx, now) {
+        const visible = w.series.filter((s) => this.sourceReadable(s, ctx));
+        const by = w.groupBy?.by;
+        const computed = await Promise.all(visible.map(async (s) => {
+            const entity = this.service.entityByName(s.entity);
+            const where = this.where(entity, s.where, ctx, now);
+            const filter = resolveTokens(s.where, ctx.principal?.id ?? null, now);
+            const points = by
+                ? await this.dateSeries(entity, where, { field: s.groupField, by, aggregate: s.aggregate, value: s.field, filter })
+                : await this.categories(entity, where, s.groupField, s.aggregate, s.field, filter);
+            return { s, entity, points };
+        }));
+        // The shared axis: contiguous dates spanning every series, or the union of category values.
+        let keys;
+        const labels = new Map();
+        for (const c of computed)
+            for (const p of c.points)
+                if (!labels.has(p.key))
+                    labels.set(p.key, p.label);
+        if (by) {
+            const all = [...labels.keys()].filter((k) => k !== null).sort();
+            keys = [];
+            if (all.length)
+                for (let k = all[0];; k = nextBucket(k, by)) {
+                    keys.push(k);
+                    if (k >= all[all.length - 1] || keys.length > 1000)
+                        break;
+                }
+        }
+        else {
+            const total = new Map();
+            for (const c of computed)
+                for (const p of c.points)
+                    total.set(p.key, (total.get(p.key) ?? 0) + p.value);
+            const first = computed[0] && computed[0].entity.fields.find((f) => f.name === computed[0].s.groupField)?.enumValues?.map((v) => v.value);
+            keys = [...total.keys()].sort((a, b) => (first ? first.indexOf(a ?? "") - first.indexOf(b ?? "") : (total.get(b) ?? 0) - (total.get(a) ?? 0)));
+            if (keys.length > w.limit)
+                keys = keys.slice(0, w.limit);
+        }
+        const series = computed.map(({ s, entity, points }) => {
+            const at = new Map(points.map((p) => [p.key, p]));
+            return {
+                key: s.id,
+                label: s.label,
+                entity: entity.name,
+                path: entity.path,
+                aggregate: s.aggregate,
+                ...(s.field ? { field: s.field } : {}),
+                axis: s.axis,
+                values: keys.map((k) => at.get(k)?.value ?? 0),
+                hrefs: keys.map((k) => {
+                    if (at.get(k)?.href)
+                        return at.get(k).href;
+                    // Empty buckets still link to the (empty) filtered list.
+                    return by && k ? this.href(entity, resolveTokens(s.where, ctx.principal?.id ?? null, now), this.rangeParams(entity, s.groupField, k, by)) : null;
+                }),
+            };
+        });
+        const data = keys.map((k, i) => ({ label: labels.get(k) ?? String(k), key: k, value: series.reduce((sum, x) => sum + (x.values[i] ?? 0), 0) }));
+        return { data, series };
+    }
+    /**
+     * Heatmap cells. `by: "hour"`: day of week (rows, Monday first) × hour of day (columns), in the dashboard's
+     * timezone. `by: "day"`: one cell per day, a column per week (Monday), up to the last 53 weeks.
+     */
+    async heatmap(entity, where, w, filter, now) {
+        const field = w.groupBy.field;
+        const tz = this.fieldTimeZone(entity, field);
+        const rows = await this.service.delegate(entity).findMany({
+            where: this.notNull(entity, where, field),
+            select: { [field]: true, ...(w.field ? { [w.field]: true } : {}) },
+            orderBy: { [field]: "desc" },
+            take: MAX_BUCKET_ROWS,
+        });
+        const val = (r) => (w.field ? toNumber(r[w.field]) : 1);
+        if (w.groupBy.by === "hour") {
+            const grid = new Map();
+            for (const r of rows) {
+                const local = zonedWallClock(new Date(r[field]), tz);
+                const key = `${(local.getUTCDay() + 6) % 7}:${local.getUTCHours()}`;
+                grid.set(key, [...(grid.get(key) ?? []), val(r)]);
+            }
+            const cells = [];
+            for (let row = 0; row < 7; row++)
+                for (let h = 0; h < 24; h++)
+                    cells.push({ row, column: String(h), value: reduce(grid.get(`${row}:${h}`) ?? [], w.aggregate) });
+            return { by: "hour", timezone: tz, columns: Array.from({ length: 24 }, (_, h) => String(h)), cells };
+        }
+        const days = new Map();
+        for (const r of rows) {
+            const key = bucketKey(new Date(r[field]), "day", tz);
+            days.set(key, [...(days.get(key) ?? []), val(r)]);
+        }
+        const today = bucketKey(now, "day", tz);
+        const sorted = [...days.keys()].sort();
+        const last = sorted.length && sorted[sorted.length - 1] > today ? sorted[sorted.length - 1] : today;
+        const lastWeek = bucketKey(new Date(`${last}T00:00:00Z`), "week");
+        const earliest = new Date(`${lastWeek}T00:00:00Z`);
+        earliest.setUTCDate(earliest.getUTCDate() - 52 * 7);
+        const firstWeek = sorted.length ? [bucketKey(new Date(`${sorted[0]}T00:00:00Z`), "week"), earliest.toISOString().slice(0, 10)].sort()[1] : lastWeek;
+        const columns = [];
+        for (let k = firstWeek; k <= lastWeek; k = nextBucket(k, "week"))
+            columns.push(k);
+        const cells = [];
+        for (const week of columns) {
+            for (let row = 0; row < 7; row++) {
+                const d = new Date(`${week}T00:00:00Z`);
+                d.setUTCDate(d.getUTCDate() + row);
+                const date = d.toISOString().slice(0, 10);
+                if (date > last)
+                    continue;
+                cells.push({ row, column: week, date, value: reduce(days.get(date) ?? [], w.aggregate), href: this.href(entity, filter, this.rangeParams(entity, field, date, "day")) });
+            }
+        }
+        return { by: "day", timezone: tz, columns, cells };
+    }
+}
+const keyOf = (v) => (v === null || v === undefined ? null : String(v));
+/** The first `limit − 1` points and the rest summed as "Other". */
+function limitOther(data, limit) {
+    if (data.length <= limit)
+        return data;
+    const rest = data.slice(limit - 1);
+    return [...data.slice(0, limit - 1), { label: "Other", key: "__other", value: rest.reduce((s, x) => s + x.value, 0) }];
 }
-function reduce(values, aggregate) {
+export function reduce(values, aggregate) {
     if (!values.length)
         return 0;
     switch (aggregate) {