@overvis/hmi-workspace-ui 0.0.0-stage → 0.1.0

package/dist/src/workspace/reports/chart/tooltip.d.ts

@@ -0,0 +1,36 @@
+import type { ReportColor } from "@overvis/hmi-shared/report";
+/** Keep the cursor tooltip inside the plot wrap; flip when it would overflow. */
+export declare function placeChartTooltip(options: {
+    cursorLeft: number;
+    cursorTop: number;
+    overOffsetLeft: number;
+    overOffsetTop: number;
+    wrapWidth: number;
+    wrapHeight: number;
+    tooltipWidth: number;
+    tooltipHeight: number;
+    gap?: number;
+}): {
+    left: number;
+    top: number;
+};
+export type ChartTooltipLine = {
+    kind: "time";
+    text: string;
+} | {
+    kind: "series";
+    color: ReportColor;
+    name: string;
+    value: string;
+};
+export declare function chartTooltipHasSeriesValue(lines: ChartTooltipLine[]): boolean;
+/** Native readout for a tooltip row; `null` omits the series at this cursor. */
+export declare function chartTooltipSeriesValue(options: {
+    alignedValue: number | null | undefined;
+    decimalPlaces: number;
+    scaleMultiplier: number;
+    scaleShift: number;
+    changeLabel: string | null;
+    reprLabel?: string | null;
+}): string | null;
+export declare function renderChartTooltip(el: HTMLElement, lines: ChartTooltipLine[]): void;

package/dist/src/workspace/reports/chart/use-realtime.d.ts

@@ -0,0 +1,44 @@
+import { type Dispatch, type SetStateAction } from "react";
+import { type ReportParameterSetup, type ReportPreset, type ReportQuickRangeId } from "@overvis/hmi-shared/report";
+import { type ReportChartDemand } from "./demand.js";
+import { type ReportRealtimeOverlay } from "./realtime.js";
+interface SessionSlice {
+    from: number;
+    to: number;
+    visibleParameterIds: string[];
+    usedFullRangeFallback: boolean;
+}
+export declare function useReportRealtime(options: {
+    workspaceId: string;
+    preset: ReportPreset;
+    currentParamIds: string[];
+    parametersById: ReadonlyMap<string, ReportParameterSetup>;
+    demands: ReadonlyMap<string, ReportChartDemand>;
+    session: SessionSlice | null;
+    setSession: Dispatch<SetStateAction<SessionSlice | null>>;
+    storedTo: number | null;
+    usingStoredRange: boolean;
+    timeZone: string;
+    fullRangeFromMs: number | null;
+    sessionScope?: string | undefined;
+    /** Window owned by the host; the session follows it. */
+    hostTimeRange?: {
+        from: number;
+        to: number;
+    } | undefined;
+}): {
+    liveOverlay: ReportRealtimeOverlay;
+    realtimeError: string | null;
+    followLive: boolean;
+    hpWindow: {
+        from: number;
+        to: number;
+    } | null;
+    setFollowLive: Dispatch<SetStateAction<boolean>>;
+    flushLivePersist: () => void;
+    trimOverlayToHp: (hpToByKey: ReadonlyMap<string, number>) => void;
+    setTimeRange: (from: number, to: number) => boolean;
+    resetTimeRange: () => void;
+    applyQuickRange: (id: ReportQuickRangeId) => void;
+};
+export {};

package/dist/src/workspace/reports/color/cascade.d.ts

@@ -0,0 +1,3 @@
+import type { ReportColor, ReportParameterSetup } from "@overvis/hmi-shared/report";
+/** Inclusive zone / valueColors lookup; unmatched finite samples fall back to `defaultColor`. */
+export declare function cascadeReportColor(snapshot: ReportParameterSetup, value: number | string): ReportColor;

package/dist/src/workspace/reports/color/css.d.ts

@@ -0,0 +1,5 @@
+import type { ReportColor } from "@overvis/hmi-shared/report";
+export type ReportColorChannel = "fill" | "border" | "text";
+/** CSS custom property for a report color channel. */
+export declare function reportColorCssVar(color: ReportColor, channel: ReportColorChannel): string;
+export declare const REPORT_COLOR_LIST: readonly ReportColor[];

package/dist/src/workspace/reports/color/select.d.ts

@@ -0,0 +1,11 @@
+import { type ReportColor } from "@overvis/hmi-shared/report";
+export declare function reportColorLabel(color: ReportColor): string;
+export declare function ReportColorSwatch({ color, className, }: {
+    color: ReportColor;
+    className?: string;
+}): import("react").JSX.Element;
+export declare function ColorSelect({ id, value, onChange, }: {
+    id?: string;
+    value: ReportColor;
+    onChange: (color: ReportColor) => void;
+}): import("react").JSX.Element;

package/dist/src/workspace/reports/comments/author.d.ts

@@ -0,0 +1,2 @@
+import type { ReportComment } from "@overvis/hmi-shared/report";
+export declare function reportCommentAuthorLabel(comment: ReportComment, authorsById: ReadonlyMap<string, string>, locale?: "de" | "en" | "pl" | "ru" | "uk"): string;

package/dist/src/workspace/reports/comments/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Why a comment cannot be deleted (`report_comment_forbidden` with `details.reason`), or `null`
+ * for the standard API error text.
+ */
+export declare function reportCommentErrorText(error: unknown): string | null;
+/** Comment range form fields for the `dataRange` API input. */
+export declare const commentRangeFieldMap: {
+    readonly dataRange: "from";
+    readonly "dataRange.to": "to";
+    readonly "dataRange.parameterId": "parameterId";
+};

package/dist/src/workspace/reports/comments/footer.d.ts

@@ -0,0 +1 @@
+export declare function ReportCommentsFooter(): import("react").JSX.Element | null;

package/dist/src/workspace/reports/comments/use-comments.d.ts

@@ -0,0 +1,9 @@
+import type { ReportComment } from "@overvis/hmi-shared/report";
+/** Comments of the provider's preset; none for a preset that is not saved. */
+export declare function useReportComments(): {
+    comments: ReportComment[];
+    authorsById: ReadonlyMap<string, string>;
+    viewerAccountId: string | null;
+    isPending: boolean;
+    error: unknown;
+};

package/dist/src/workspace/reports/csv/build.d.ts

@@ -0,0 +1,29 @@
+import type { ReportCsvColumn } from "./columns.js";
+export interface ReportCsvCell {
+    value: number | string | null;
+    repr?: string | null;
+}
+export type ReportCsvSeries = Map<number, ReportCsvCell>;
+export declare function csvQuoteField(field: string): string;
+/** Protect text cells when a CSV is opened directly in common spreadsheet applications. */
+export declare function csvQuoteTextField(field: string): string;
+export declare function formatCsvNumeric(value: number): string;
+export declare function formatCsvCell(cell: ReportCsvCell | undefined, snapshotType: ReportCsvColumn["snapshotType"], locale: string): string;
+export declare function sanitizeCsvFilenameTitle(title: string): string;
+export declare function reportCsvFilename(options: {
+    title: string;
+    from: number;
+    to: number;
+    timeZone: string;
+}): string;
+export declare function buildReportCsv(options: {
+    columns: readonly ReportCsvColumn[];
+    seriesByParameterId: ReadonlyMap<string, ReportCsvSeries>;
+    timeHeader: string;
+    timeZone: string;
+    precise: boolean;
+    locale: string;
+    signal?: AbortSignal;
+    onProgress?: (done: number, total: number) => void;
+}): Promise<string>;
+export declare function triggerCsvDownload(filename: string, csv: string): void;

package/dist/src/workspace/reports/csv/columns.d.ts

@@ -0,0 +1,18 @@
+import type { ReadingsCadenceParameter } from "@overvis/hmi-shared/parameter";
+import type { ReportExportToCsv, ReportParameterSetup } from "@overvis/hmi-shared/report";
+export interface ReportCsvColumn {
+    parameterId: string;
+    sourceValueType: string;
+    snapshotType: "numeric" | "integer" | "string";
+    aggregation: ReadingsCadenceParameter["aggregation"];
+    header: string;
+}
+export declare function aggregationForCsvSnapshot(snapshot: ReportParameterSetup, exportToCsv: ReportExportToCsv): ReadingsCadenceParameter["aggregation"];
+export declare function csvColumnHeaderBase(snapshot: ReportParameterSetup, locale: string): string;
+/** Unique `parameterIds` order ∩ visible ∩ snapshots. */
+export declare function resolveCsvExportColumns(options: {
+    exportToCsv: ReportExportToCsv;
+    parameters: readonly ReportParameterSetup[];
+    visibleParameterIds: ReadonlySet<string>;
+    locale: string;
+}): ReportCsvColumn[];

package/dist/src/workspace/reports/csv/fetch.d.ts

@@ -0,0 +1,29 @@
+import type { ReadingsCadence, ReadingsCadenceInput, ReadingsCadenceOutput, ReadingsRawInput, ReadingsRawOutput } from "@overvis/hmi-shared/parameter";
+import type { TableSetup } from "@overvis/hmi-shared/report";
+import type { ReportCsvColumn } from "./columns.js";
+import type { ReportCsvSeries } from "./build.js";
+export interface ReportCsvReadingsClient {
+    cadence: {
+        query: (input: ReadingsCadenceInput, opts?: {
+            signal?: AbortSignal;
+        }) => Promise<ReadingsCadenceOutput>;
+    };
+    raw: {
+        query: (input: ReadingsRawInput, opts?: {
+            signal?: AbortSignal;
+        }) => Promise<ReadingsRawOutput>;
+    };
+}
+export interface FetchReportCsvDataInput {
+    workspaceId: string;
+    columns: readonly ReportCsvColumn[];
+    from: number;
+    to: number;
+    timeZone: string;
+    cadence: TableSetup["rowCadenceMs"];
+    client: ReportCsvReadingsClient;
+    signal: AbortSignal;
+    onProgress?: (done: number, total: number) => void;
+}
+export declare function countCsvCadenceSteps(columns: readonly ReportCsvColumn[], from: number, closedTo: number, cadence: ReadingsCadence, timeZone: string): number;
+export declare function fetchReportCsvData(options: FetchReportCsvDataInput): Promise<Map<string, ReportCsvSeries>>;

package/dist/src/workspace/reports/csv/use-export.d.ts

@@ -0,0 +1,7 @@
+export declare function useReportCsvExport(enabled: boolean): {
+    running: boolean;
+    /** 0–100 while paging; `null` when idle. */
+    progressValue: number | null;
+    start: () => void;
+    cancel: () => void;
+};

package/dist/src/workspace/reports/data/context.d.ts

@@ -0,0 +1,79 @@
+import { type ReactNode } from "react";
+import type { ReportParameterSetup, ReportPreset, ReportQuickRangeId } from "@overvis/hmi-shared/report";
+import type { ReportCalendarDemand } from "../calendar/demand.js";
+import type { ReportChartCaches } from "../chart/caches.js";
+import type { ReportChartDemand } from "../chart/demand.js";
+import type { ReportRealtimeOverlay } from "../chart/realtime.js";
+import type { ReportHistogramDemand } from "../histogram/demand.js";
+import type { ReportHourlyMatrixDemand } from "../hourly-matrix/demand.js";
+import type { ReportMountedWidget } from "../html/mounted.js";
+import type { ReportSankeyDemand } from "../sankey/demand.js";
+import type { ReportSankeyCaches } from "../sankey/use-caches.js";
+import type { ReportStateDurationDemand } from "../state-duration/demand.js";
+import type { ReportStateDurationCaches } from "../state-duration/use-caches.js";
+import type { ReportTableDemand } from "../table/demand.js";
+import type { ReportTimeBucketsDemand } from "../time-buckets/demand.js";
+import type { DemandRegistration } from "../use-demand-cache.js";
+import type { ReportCalendarCaches, ReportHistogramCaches, ReportHourlyMatrixCaches, ReportTableCaches, ReportTimeBucketsCaches } from "./specs.js";
+export interface ReportSessionContextValue {
+    workspaceId: string;
+    preset: ReportPreset;
+    /** False for a preset built in memory: nothing is stored for it on the server. */
+    saved: boolean;
+    timeZone: string;
+    from: number;
+    to: number;
+    followLive: boolean;
+    visibleParameterIds: ReadonlySet<string>;
+    usedFullRangeFallback: boolean;
+    rangeReady: boolean;
+    parametersById: ReadonlyMap<string, ReportParameterSetup>;
+    setTimeRange: (from: number, to: number) => boolean;
+    resetTimeRange: () => void;
+    applyQuickRange: (id: ReportQuickRangeId) => void;
+    setParameterVisible: (parameterId: string, visible: boolean) => void;
+    setVisibleParameterIds: (ids: readonly string[]) => void;
+}
+export type ReportChartCacheContextValue = ReportChartCaches & DemandRegistration<ReportChartDemand> & {
+    /** Full data extent for nav strips; null when empty/unavailable (soft empty — no strip). */
+    sparseExtent: {
+        from: number;
+        to: number;
+    } | null;
+    sparseExtentLoading: boolean;
+    sparseExtentError: string | null;
+    liveOverlay: ReportRealtimeOverlay;
+    realtimeError: string | null;
+};
+/** Mounted `ReportWidget` keys for Render wait/build (not state: registering does not re-render). */
+export interface ReportMountedWidgetsContextValue {
+    registerMountedWidget: (id: string, widget: ReportMountedWidget) => void;
+    unregisterMountedWidget: (id: string) => void;
+    getMountedWidgets: () => readonly ReportMountedWidget[];
+}
+/** Context values of one report provider: the session and one cache set per representation. */
+export interface ReportDataValues {
+    session: ReportSessionContextValue;
+    chart: ReportChartCacheContextValue;
+    table: ReportTableCaches & DemandRegistration<ReportTableDemand>;
+    timeBuckets: ReportTimeBucketsCaches & DemandRegistration<ReportTimeBucketsDemand>;
+    histogram: ReportHistogramCaches & DemandRegistration<ReportHistogramDemand>;
+    calendar: ReportCalendarCaches & DemandRegistration<ReportCalendarDemand>;
+    hourlyMatrix: ReportHourlyMatrixCaches & DemandRegistration<ReportHourlyMatrixDemand>;
+    stateDuration: ReportStateDurationCaches & DemandRegistration<ReportStateDurationDemand>;
+    sankey: ReportSankeyCaches & DemandRegistration<ReportSankeyDemand>;
+}
+export declare function useReportSession(): ReportSessionContextValue;
+export declare function useReportMountedWidgets(): ReportMountedWidgetsContextValue;
+export declare function useReportChartCaches(): ReportDataValues["chart"];
+export declare function useReportTableData(): ReportDataValues["table"];
+export declare function useReportTimeBucketsData(): ReportDataValues["timeBuckets"];
+export declare function useReportHistogramData(): ReportDataValues["histogram"];
+export declare function useReportCalendarData(): ReportDataValues["calendar"];
+export declare function useReportHourlyMatrixData(): ReportDataValues["hourlyMatrix"];
+export declare function useReportStateDurationData(): ReportDataValues["stateDuration"];
+export declare function useReportSankeyData(): ReportDataValues["sankey"];
+export declare function ReportDataProviders({ children, values, }: {
+    children: ReactNode;
+    values: ReportDataValues;
+}): ReactNode;

package/dist/src/workspace/reports/data/extent.d.ts

@@ -0,0 +1,40 @@
+import { type ReportChartDemand } from "../chart/demand.js";
+import type { ReportReadingsEnv } from "../readings-client.js";
+import type { ReportTimeBucketsDemand } from "../time-buckets/demand.js";
+import type { ReportTimeWindow } from "./report-caches.js";
+export interface ReportDataExtentEntry {
+    status: "loading" | "ready" | "error";
+    /** Null when the parameters have no readings. */
+    extent: ReportTimeWindow | null;
+    /** Stable error code when `status` is `error`. */
+    error: string | null;
+}
+export interface ReportDataExtentNeed {
+    key: string;
+    parameterIds: readonly string[];
+    /** A mounted widget uses the extent; otherwise a loaded extent is only kept. */
+    wanted: boolean;
+}
+export interface ReportDataExtent {
+    /** Full data extent (chart and time-buckets nav strips); null when empty or unavailable. */
+    extent: ReportTimeWindow | null;
+    loading: boolean;
+    error: string | null;
+}
+/** The extent need of the preset parameters (none without parameters). */
+export declare function reportDataExtentNeeds(workspaceId: string, parameterIds: readonly string[], wanted: boolean): ReportDataExtentNeed[];
+/** Fetched once and frozen; an empty or failed extent is retried by the next run. */
+export declare function reportDataExtentNeedsFetch(entry: ReportDataExtentEntry | undefined, need: ReportDataExtentNeed): boolean;
+/** Charts with parameters and any time-buckets widget use the extent (nav strips). */
+export declare function reportDataExtentWanted(chartDemands: ReadonlyMap<string, ReportChartDemand>, timeBucketsDemands: ReadonlyMap<string, ReportTimeBucketsDemand>): boolean;
+/**
+ * `readings.timeExtent` of the preset parameters, shared by chart and time-buckets nav strips.
+ * Fetched while a mounted widget wants it and frozen once known. A demand change retries an
+ * empty or failed extent.
+ */
+export declare function useReportDataExtent(options: {
+    env: ReportReadingsEnv<"timeExtent">;
+    parameterIds: readonly string[];
+    chartDemands: ReadonlyMap<string, ReportChartDemand>;
+    timeBucketsDemands: ReadonlyMap<string, ReportTimeBucketsDemand>;
+}): ReportDataExtent;

package/dist/src/workspace/reports/data/provider.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from "react";
+import { type ReportPreset } from "@overvis/hmi-shared/report";
+export declare function resolveEffectiveReportTimeZone(presetTimezone: string): string;
+export interface ReportHostTimeRange {
+    from: number;
+    to: number;
+}
+export declare function ReportDataProvider({ workspaceId, preset, sessionScope, timeRange, saved, children, }: {
+    workspaceId: string;
+    preset: ReportPreset;
+    sessionScope?: string;
+    /**
+     * Window owned by the host. The session follows it whenever it changes, the viewer can't change
+     * it, and it is never remembered.
+     */
+    timeRange?: ReportHostTimeRange;
+    /** False for a preset built in memory: comments and other stored data are not looked up. */
+    saved?: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/src/workspace/reports/data/report-caches.d.ts

@@ -0,0 +1,56 @@
+import { type DemandCacheMap, type DemandFetchContext, type DemandNeed, type PlannedDemandSlot } from "../demand-cache.js";
+import type { ReportReadingsEnv } from "../readings-client.js";
+import type { DemandRegistration, DemandRegistry } from "../use-demand-cache.js";
+export interface ReportTimeWindow {
+    from: number;
+    to: number;
+}
+/**
+ * Windows a cache slot can follow. Each kind runs under its own gate: a change of one window
+ * never aborts the fetches that follow another.
+ */
+export interface ReportCacheWindows {
+    /** The session window. */
+    session: ReportTimeWindow;
+    /** The session window once pan/zoom has left it unchanged for 300 ms. */
+    settled: ReportTimeWindow;
+    /** Frozen data extent of the preset parameters; null until known or without readings. */
+    extent: ReportTimeWindow | null;
+    /** Chart high-precision window: follows navigation and a periodic live refresh, not live ticks. */
+    highPrecision: ReportTimeWindow | null;
+}
+export type ReportCacheWindowKind = keyof ReportCacheWindows;
+/** What every slot fetch gets besides its needs. */
+export interface ReportCacheEnv extends ReportReadingsEnv {
+    timeZone: string;
+}
+/** One keyed cache: the window it follows, its needs, and how to fetch them. */
+export interface ReportCacheSlot<D, N extends DemandNeed, E, X extends ReportCacheEnv> {
+    window: ReportCacheWindowKind;
+    /** Needs of the mounted demands. Not called while the window is unknown or empty. */
+    needs: (demands: ReadonlyMap<string, D>, window: ReportTimeWindow, env: X) => readonly N[];
+    needsFetch: (entry: E | undefined, need: N) => boolean;
+    fetch: (needs: N[], context: DemandFetchContext<E>, env: X) => Promise<void>;
+}
+/**
+ * A representation's caches: declares its slots (`slot` returns a reader of the slot's cache) and
+ * returns the view the representation's context exposes, read from those caches.
+ */
+export type ReportCacheSpec<D, V extends object, X extends ReportCacheEnv = ReportCacheEnv> = (slot: <N extends DemandNeed, E>(slot: ReportCacheSlot<D, N, E, X>) => () => DemandCacheMap<E>) => () => V;
+interface PlannableSlot<D, X> {
+    window: ReportCacheWindowKind;
+    plan: (demands: ReadonlyMap<string, D>, window: ReportTimeWindow | null, env: X) => PlannedDemandSlot;
+}
+interface ReportCachesInstance<D, V, X> {
+    subscribe: (listener: () => void) => () => void;
+    /** The view; a new object only after a cache changed. */
+    view: () => V;
+    slots: readonly PlannableSlot<D, X>[];
+}
+export declare function createReportCaches<D, V extends object, X extends ReportCacheEnv>(spec: ReportCacheSpec<D, V, X>): ReportCachesInstance<D, V, X>;
+/**
+ * Run a representation's cache slots for its mounted demands and return its context value: the
+ * spec's view plus the demand registration. One run per window kind and dependency change.
+ */
+export declare function useReportCaches<D, V extends object, X extends ReportCacheEnv>(spec: ReportCacheSpec<D, V, X>, registry: DemandRegistry<D>, windows: ReportCacheWindows, env: X): V & DemandRegistration<D>;
+export {};

package/dist/src/workspace/reports/data/specs.d.ts

@@ -0,0 +1,38 @@
+import { type ReportCalendarCadenceCache, type ReportCalendarDemand } from "../calendar/demand.js";
+import { type ReportHistogramCadenceCache, type ReportHistogramDemand } from "../histogram/demand.js";
+import { type ReportHourlyMatrixCadenceCache, type ReportHourlyMatrixDemand } from "../hourly-matrix/demand.js";
+import { type ReportTableAggregateCache, type ReportTableCadenceCache, type ReportTableDemand, type ReportTableRawCache } from "../table/demand.js";
+import { type ReportTimeBucketsCadenceCache, type ReportTimeBucketsDaysCache, type ReportTimeBucketsDemand } from "../time-buckets/demand.js";
+import type { ReportCacheSpec } from "./report-caches.js";
+export interface ReportTableCaches {
+    tableCadenceCache: ReportTableCadenceCache;
+    tableRawCache: ReportTableRawCache;
+    tableAggregateCache: ReportTableAggregateCache;
+}
+/** Table body (cadence or precise rows) and footer aggregates over the session window. */
+export declare const reportTableCaches: ReportCacheSpec<ReportTableDemand, ReportTableCaches>;
+export interface ReportTimeBucketsCaches {
+    timeBucketsCadenceCache: ReportTimeBucketsCadenceCache;
+    timeBucketsDaysCache: ReportTimeBucketsDaysCache;
+}
+/**
+ * Cadence buckets over the settled session window, and local days over the frozen data extent
+ * (the daily layer and nav strip).
+ */
+export declare const reportTimeBucketsCaches: ReportCacheSpec<ReportTimeBucketsDemand, ReportTimeBucketsCaches>;
+export interface ReportHistogramCaches {
+    histogramCadenceCache: ReportHistogramCadenceCache;
+}
+/** Closed cadence rows over the settled session window. */
+export declare const reportHistogramCaches: ReportCacheSpec<ReportHistogramDemand, ReportHistogramCaches>;
+export interface ReportCalendarCaches {
+    calendarDaysCache: ReportCalendarCadenceCache;
+    calendarHourCache: ReportCalendarCadenceCache;
+}
+/** Local days (`readings.days`) and hours (`readings.cadence`) over the settled session window. */
+export declare const reportCalendarCaches: ReportCacheSpec<ReportCalendarDemand, ReportCalendarCaches>;
+export interface ReportHourlyMatrixCaches {
+    hourlyMatrixCadenceCache: ReportHourlyMatrixCadenceCache;
+}
+/** Closed cadence cells over the settled session window. */
+export declare const reportHourlyMatrixCaches: ReportCacheSpec<ReportHourlyMatrixDemand, ReportHourlyMatrixCaches>;

package/dist/src/workspace/reports/demand-cache.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Demand-driven report caches.
+ *
+ * Widgets register demands (by mount id). A representation turns the demand set plus the session
+ * window into needs, each with a cache key. One run per dependency change:
+ *
+ * - evicts cache entries whose key no need names any more;
+ * - asks the representation which needed entries to (re)fetch — missing, idle, a superseded
+ *   run's `loading`, partial or failed entries, as the representation decides;
+ * - fetches them, merging results into the cache per key.
+ *
+ * A newer run supersedes older ones: they stop writing (`isStale`) and their requests are aborted.
+ * Entries keep their data when a later fetch for the same key fails, so partial pages stay visible.
+ */
+/** A keyed cache: one entry per need key. */
+export type DemandCacheMap<E> = Map<string, E>;
+export interface DemandNeed {
+    readonly key: string;
+}
+export interface DemandRun {
+    readonly signal: AbortSignal;
+    /** A newer run started; results of this one must be dropped. */
+    isStale: () => boolean;
+    /** Stale, or aborted (dependency change or unmount). */
+    isCancelled: () => boolean;
+}
+export interface DemandRunGate {
+    /** Start a run that supersedes every earlier run of this gate. Returns its abort. */
+    start: (task: (run: DemandRun) => Promise<void>) => () => void;
+}
+export declare function createDemandRunGate(): DemandRunGate;
+/** Where a cache lives. */
+export interface DemandCacheStore<E> {
+    /** Current cache. */
+    get: () => DemandCacheMap<E>;
+    update: (updater: (prev: DemandCacheMap<E>) => DemandCacheMap<E>) => void;
+}
+/** A cache held in memory; `onChange` runs after every update that replaces the map. */
+export declare function createDemandCacheStore<E>(onChange?: () => void): DemandCacheStore<E>;
+/** Listeners notified after any of a set of caches changes. */
+export declare function createDemandCacheListeners(): {
+    subscribe: (listener: () => void) => () => void;
+    notify: () => void;
+};
+export interface DemandFetchContext<E> {
+    run: DemandRun;
+    /** Cache as it was when the run planned its needs (before eviction). */
+    seed: ReadonlyMap<string, E>;
+    setCache: (updater: (prev: DemandCacheMap<E>) => DemandCacheMap<E>) => void;
+}
+export interface DemandSlotSpec<N extends DemandNeed, E> {
+    store: DemandCacheStore<E>;
+    needs: readonly N[];
+    /** Whether the need's entry must be (re)fetched this run. */
+    needsFetch: (entry: E | undefined, need: N) => boolean;
+    fetch: (needs: N[], context: DemandFetchContext<E>) => Promise<void>;
+}
+export interface PlannedDemandSlot {
+    /** Needs this run will fetch. */
+    readonly pending: number;
+    evict: () => void;
+    fetch: (run: DemandRun) => Promise<void>;
+}
+/** Freeze one cache's work for a run: keys to keep and needs to fetch, from the seed cache. */
+export declare function planDemandSlot<N extends DemandNeed, E>(spec: DemandSlotSpec<N, E>): PlannedDemandSlot;
+/** Evict every slot, then fetch the slots that have pending needs (concurrently). */
+export declare function runDemandSlots(run: DemandRun, slots: readonly PlannedDemandSlot[]): Promise<void>;
+export declare function evictUnused<V>(prev: Map<string, V>, needed: ReadonlySet<string>): Map<string, V>;
+/** Copy `prev` and replace the entry of every need with `patch(existing, need)`. */
+export declare function patchEntries<N extends DemandNeed, E>(prev: ReadonlyMap<string, E>, needs: readonly N[], patch: (existing: E | undefined, need: N) => E): DemandCacheMap<E>;
+/** Add or replace a widget demand; returns `prev` when the serialized demand is unchanged. */
+export declare function withDemand<D>(prev: Map<string, D>, demandId: string, demand: D, serialize: (demand: D) => string): Map<string, D>;
+/** Remove a widget demand; returns `prev` when it was not registered. */
+export declare function withoutDemand<D>(prev: Map<string, D>, demandId: string): Map<string, D>;
+/** Group needs that share one request window (same `groupKey`), in first-seen order. */
+export declare function groupNeeds<N>(needs: readonly N[], groupKey: (need: N) => string): N[][];

package/dist/src/workspace/reports/element-size.d.ts

@@ -0,0 +1,7 @@
+/** Width/height of a host element; skips React updates when the box is unchanged. */
+export declare function useElementSize(ref: {
+    current: HTMLElement | null;
+}): {
+    width: number;
+    height: number;
+};

package/dist/src/workspace/reports/generated.d.ts

@@ -0,0 +1,46 @@
+import { type ReactNode } from "react";
+import type { CounterPeriod } from "@overvis/hmi-shared/dashboard";
+import { type ReportParameterSetup, type ReportPreset } from "@overvis/hmi-shared/report";
+/** Parameter setups frozen from live parameters, by parameter ID. */
+export type FrozenReportParameters = ReadonlyMap<string, ReportParameterSetup>;
+/**
+ * Parameter setups for a report generated in a dashboard, frozen from the parameters' current
+ * metadata with `report.preset.freezeFromLive`, in as many requests as its limit needs. Null until
+ * every request has answered; parameters that are missing or unsupported are left out. `retry`
+ * requests the failed batches again; failures are not retried by themselves.
+ */
+export declare function useFrozenReportParameters(workspaceId: string, parameterIds: readonly string[]): {
+    parameters: FrozenReportParameters | null;
+    isError: boolean;
+    retry: () => void;
+};
+/**
+ * Runs a report preset generated in a dashboard over a counter period, for the
+ * `GeneratedReportSection`s inside it. The preset is never saved, so comments, signing,
+ * rendering and CSV are off, and the window follows the period instead of the viewer. A recipe
+ * rebuilt on every render keeps its session until its content changes.
+ */
+export declare function GeneratedReport({ workspaceId, preset, period, children, }: {
+    workspaceId: string;
+    preset: ReportPreset;
+    period: CounterPeriod;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * A titled representation of the surrounding `GeneratedReport`; content wider than the page
+ * scrolls inside its own area, at least `minWidth` wide (a Tailwind class).
+ */
+export declare function GeneratedReportSection({ title, representationKey, note, minWidth, }: {
+    title: string;
+    representationKey: string;
+    note?: ReactNode;
+    minWidth?: string;
+}): import("react").JSX.Element;
+/**
+ * Stands in for generated charts while their parameters freeze, or explains that they failed with
+ * a Retry that calls `onRetry` (`useFrozenReportParameters`' `retry`).
+ */
+export declare function GeneratedReportPending({ isError, onRetry, }: {
+    isError: boolean;
+    onRetry: () => void;
+}): import("react").JSX.Element;

package/dist/src/workspace/reports/histogram/build.d.ts

@@ -0,0 +1 @@
+export declare function histogramOfAvgDisplayYs(slotNatives: readonly (number | null)[], scaleMultiplier: number, scaleShift: number): (number | null)[];

package/dist/src/workspace/reports/histogram/demand.d.ts

@@ -0,0 +1,26 @@
+import type { ReadingsNumericAggregation } from "@overvis/hmi-shared/parameter";
+import type { HistogramSetup } from "@overvis/hmi-shared/report";
+import type { CadenceNeed } from "../table/fetch.js";
+import type { ReportTableCadenceEntry } from "../table/demand.js";
+export interface ReportHistogramDemandSeries {
+    parameterId: string;
+    sourceValueType: string;
+    aggregation: ReadingsNumericAggregation;
+}
+export interface ReportHistogramDemand {
+    series: ReportHistogramDemandSeries[];
+    cadence: HistogramSetup["cadence"];
+}
+export type ReportHistogramCadenceEntry = ReportTableCadenceEntry;
+export type ReportHistogramCadenceCache = Map<string, ReportHistogramCadenceEntry>;
+export declare function histogramCadenceCacheKey(parts: {
+    parameterId: string;
+    sourceValueType: string;
+    aggregation: string;
+    cadence: HistogramSetup["cadence"];
+    timeZone: string;
+    from: number;
+    to: number;
+}): string;
+export declare function serializeReportHistogramDemand(demand: ReportHistogramDemand): string;
+export declare function collectHistogramCadenceNeeds(demands: ReadonlyMap<string, ReportHistogramDemand>, from: number, to: number, timeZone: string): CadenceNeed[];