@tekki-forge/runtime-api 0.2.0 → 0.3.0

package/dist/dashboard.d.ts

@@ -1,12 +1,31 @@
+import type { WidgetIR } from "@tekki-forge/compiler";
 import type { ForgeRequestContext } from "./extension.js";
 import type { ForgeService } from "./service.js";
 type Row = Record<string, any>;
+type Bucket = "day" | "week" | "month" | "year";
 /** "$today", "$today-30d", "$now", "$startOfMonth", "$me" → concrete values. */
 export declare function resolveTokens(where: Record<string, string>, userId: string | null, now?: Date): Record<string, string>;
-export declare function bucketKey(d: Date, by: "day" | "week" | "month" | "year"): string;
+/** `d` as wall-clock time in `timeZone`, expressed as a Date whose UTC fields hold the local values. */
+export declare function zonedWallClock(d: Date, timeZone: string): Date;
+/** The instant at which the wall clock in `timeZone` shows midnight of `date` (YYYY-MM-DD); DST-safe. */
+export declare function zonedMidnight(date: string, timeZone: string): Date;
+export declare function bucketKey(d: Date, by: Bucket, timeZone?: string): string;
+/**
+ * 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 declare function bucketRange(key: string, by: Bucket, kind: string, timeZone?: string): {
+    gte: string;
+    lt: string;
+};
 export type ComparePeriod = "week" | "month" | "quarter" | "year";
 /** Periods in a metric's sparkline (the last one is the current period). */
 export declare const TREND_PERIODS = 12;
+/** Start of the current calendar period (weeks start on Monday) in `timeZone`: the local date and its instant. */
+export declare function periodStart(now: Date, period: ComparePeriod, timeZone?: string): {
+    date: string;
+    instant: Date;
+};
 /** `d` moved by `n` periods; months clamp to the month's last day (31 Mar − 1 month = 28/29 Feb). */
 export declare function shiftPeriod(d: Date, period: ComparePeriod, n: number): Date;
 /**
@@ -35,24 +54,102 @@ export interface MetricTrend {
         value: number | null;
     }[];
 }
+/** One point of a chart: `label` in the default language, `key` the raw group value (clients localize it). */
+export interface ChartPoint {
+    label: string;
+    key: string | null;
+    value: number;
+    href?: string;
+}
+/** A series of a multi-series chart, aligned with the chart's categories (`data`). */
+export interface ChartSeriesData {
+    /** Series id (config series) or the stack value (stackBy; null = none, "__other" = the rest). */
+    key: string | null;
+    label: string;
+    entity: string;
+    path: string;
+    aggregate: WidgetIR["aggregate"];
+    field?: string;
+    axis: "left" | "right";
+    values: number[];
+    hrefs: (string | null)[];
+}
+/** Ratio of two aggregates, null without a denominator. */
+export declare const ratioOf: (numerator: number | null, denominator: number | null) => number | null;
 export declare class DashboardService {
     private readonly service;
     constructor(service: ForgeService);
+    private entityReadable;
+    private sourceReadable;
     private readable;
     private fieldReadable;
-    /** `now` is injectable for tests; relative dates in filters ($today…) are resolved against it. */
-    compute(ctx: ForgeRequestContext, now?: Date): Promise<{
+    /** Tabs the viewer may see (none when the dashboard has no tabs). */
+    visibleTabs(ctx: ForgeRequestContext): {
+        id: string;
+        title: string;
+    }[];
+    /**
+     * 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.
+     */
+    compute(ctx: ForgeRequestContext, now?: Date, tab?: string): Promise<{
         widgets: null;
     } | {
+        tabs?: {
+            id: string;
+            title: string;
+        }[] | undefined;
         widgets: Row[];
     }>;
+    private get timeZone();
+    /** The viewer's row-level, tenant and owner rules plus the widget's filter. */
+    private where;
+    /**
+     * 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.
+     */
+    private periodFilter;
+    private metric;
+    /** One ratio side, within the viewer's rules, optionally limited to a calendar period or a [start, end) window. */
+    private sourceValue;
     private aggregate;
     /**
      * The metric over each of the last TREND_PERIODS rolling periods, within exactly the same row-level, tenant and
      * owner rules as the value itself; relative dates in the filter ($today…) are resolved as of each period.
      */
     private trend;
-    /** `label` is ready to show (default language); `key` is the raw group value so clients can localize it ("__other" = the rest). */
-    private series;
+    private chart;
+    private href;
+    /** Contiguous date buckets (from the first to the last record), computed from the rows so every permission rule stays in the Prisma where. */
+    private dateBuckets;
+    /** `where` and the date present (createdAt and required fields always are: Prisma rejects `not: null` on them). */
+    private notNull;
+    /** Date-only fields hold a calendar date: they are bucketed as stored, whatever the dashboard's timezone. */
+    private fieldTimeZone;
+    private fieldKind;
+    private rangeParams;
+    private dateSeries;
+    /** Labels of category values in the default language (enum labels, yes/no, related records' display field). */
+    private labeler;
+    private column;
+    private groupRows;
+    /** One point per category value, largest first. */
+    private categories;
+    /** Enum stages in order; cumulative = records at a stage or any later one. */
+    private funnel;
+    /** groupBy × stackBy: categories plus one series per stack value (the smallest beyond MAX_STACKS merged as "Other"). */
+    private stacked;
+    /**
+     * 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).
+     */
+    private multiSeries;
+    /**
+     * 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.
+     */
+    private heatmap;
 }
+export declare function reduce(values: number[], aggregate: WidgetIR["aggregate"]): number;
 export {};