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

package/dist/src/workspace/reports/table/snapshot.d.ts

@@ -0,0 +1,40 @@
+import type { ReportParameterSetup, TableParameterSetup, TableSetup } from "@overvis/hmi-shared/report";
+import { type ReportTableAggregateCache, type ReportTableCadenceCache, type ReportTableDemandColumn, type ReportTableRawCache } from "./demand.js";
+export interface VisibleTableColumn {
+    column: TableParameterSetup;
+    snapshot: ReportParameterSetup;
+    demand: ReportTableDemandColumn;
+}
+export interface TableHtmlCell {
+    text: string;
+    background: string | undefined;
+}
+export interface TableHtmlRow {
+    kind: "body" | "subtotal";
+    timeLabel: string;
+    cells: TableHtmlCell[];
+}
+export interface TableHtmlSnapshot {
+    error: string | null;
+    loading: boolean;
+    headers: {
+        label: string;
+        units: string;
+        numeric: boolean;
+    }[];
+    rows: TableHtmlRow[];
+    footer: TableHtmlCell[] | null;
+}
+export declare function resolveVisibleTableColumns(setup: TableSetup, parametersById: ReadonlyMap<string, ReportParameterSetup>, visibleParameterIds: ReadonlySet<string>): VisibleTableColumn[];
+export declare function buildTableHtmlSnapshot(options: {
+    setup: TableSetup;
+    parametersById: ReadonlyMap<string, ReportParameterSetup>;
+    visibleParameterIds: ReadonlySet<string>;
+    from: number;
+    to: number;
+    timeZone: string;
+    locale: string;
+    tableCadenceCache: ReportTableCadenceCache;
+    tableRawCache: ReportTableRawCache;
+    tableAggregateCache: ReportTableAggregateCache;
+}): TableHtmlSnapshot;

package/dist/src/workspace/reports/table/totals.d.ts

@@ -0,0 +1,4 @@
+import type { TableSetup } from "@overvis/hmi-shared/report";
+export declare function tableSubtotalsAreNoOp(rowCadenceMs: TableSetup["rowCadenceMs"], subtotals: TableSetup["subtotals"]): boolean;
+/** Map a table `totals` operator to the cadence/aggregate aggregation(s) to fetch. */
+export declare function aggregationsForTotals(totals: string): readonly ("first" | "latest" | "sum" | "average" | "min" | "max" | "delta")[];

package/dist/src/workspace/reports/time-buckets/build.d.ts

@@ -0,0 +1,40 @@
+import type { TimeBucketsSetup } from "@overvis/hmi-shared/report";
+import type { TimeBucketsPaintedGrain } from "./navigate.js";
+export declare function timeBucketsDisplayYs(grid: readonly number[], rows: readonly {
+    bucketStart: number;
+    value: number | string;
+}[], scaleMultiplier: number, scaleShift: number): (number | null)[];
+/** Daily grid whose 1d span does not overlap the cadence window, plus cadence starts. */
+export declare function spliceTimeBucketsGrid(options: {
+    dailyStarts: readonly number[];
+    cadenceStarts: readonly number[] | null;
+    cadenceFrom: number;
+    cadenceTo: number;
+    timeZone: string;
+}): {
+    xs: number[];
+    grain: TimeBucketsPaintedGrain[];
+};
+/**
+ * HTML / PNG grid: under-budget cadence in the session window, or full-extent daily when
+ * cadence would exceed the on-screen budget.
+ */
+export declare function timeBucketsHtmlPaintGrid(options: {
+    from: number;
+    to: number;
+    cadence: TimeBucketsSetup["cadence"];
+    timeZone: string;
+    overBudget: boolean;
+    sparseExtent: {
+        from: number;
+        to: number;
+    } | null;
+}): {
+    xs: number[];
+    grain: TimeBucketsPaintedGrain[];
+};
+/**
+ * Autoscale Y from aligned values whose bucket start sits in `[fromMs, toMs)`.
+ * Bars and fills are anchored at zero; only the far end gets headroom.
+ */
+export declare function timeBucketsYRange(xsMs: readonly number[], alignedYs: readonly ArrayLike<number | null | undefined>[], fromMs: number, toMs: number): [number, number];

package/dist/src/workspace/reports/time-buckets/demand.d.ts

@@ -0,0 +1,52 @@
+import { type ReadingsCadenceParameter, type ReadingsNumericAggregation } from "@overvis/hmi-shared/parameter";
+import type { TimeBucketsSetup } from "@overvis/hmi-shared/report";
+import type { CadenceNeed } from "../table/fetch.js";
+import type { ReportTableCadenceEntry } from "../table/demand.js";
+/** Skip `readings.cadence` when the closed window would paint this many slots or more. */
+export declare const TIME_BUCKETS_MAX_ON_SCREEN_BUCKETS = 1000;
+export interface ReportTimeBucketsDemandSeries {
+    parameterId: string;
+    sourceValueType: string;
+    aggregation: ReadingsNumericAggregation;
+}
+export interface ReportTimeBucketsDemand {
+    series: ReportTimeBucketsDemandSeries[];
+    cadence: TimeBucketsSetup["cadence"];
+}
+export type ReportTimeBucketsCadenceEntry = ReportTableCadenceEntry;
+export type ReportTimeBucketsCadenceCache = Map<string, ReportTimeBucketsCadenceEntry>;
+export type ReportTimeBucketsDaysCache = ReportTimeBucketsCadenceCache;
+export interface TimeBucketsDaysNeed {
+    key: string;
+    parameterId: string;
+    sourceValueType: string;
+    aggregation: ReadingsCadenceParameter["aggregation"];
+    timeZone: string;
+    from: number;
+    to: number;
+}
+export declare function timeBucketsCadenceWindowOverBudget(parts: {
+    from: number;
+    to: number;
+    cadence: TimeBucketsSetup["cadence"];
+}): boolean;
+export declare function timeBucketsCadenceCacheKey(parts: {
+    parameterId: string;
+    sourceValueType: string;
+    aggregation: string;
+    cadence: TimeBucketsSetup["cadence"];
+    timeZone: string;
+    from: number;
+    to: number;
+}): string;
+export declare function timeBucketsDaysCacheKey(parts: {
+    parameterId: string;
+    sourceValueType: string;
+    aggregation: string;
+    timeZone: string;
+    from: number;
+    to: number;
+}): string;
+export declare function serializeReportTimeBucketsDemand(demand: ReportTimeBucketsDemand): string;
+export declare function collectTimeBucketsCadenceNeeds(demands: ReadonlyMap<string, ReportTimeBucketsDemand>, from: number, to: number, timeZone: string): CadenceNeed[];
+export declare function collectTimeBucketsDaysNeeds(demands: ReadonlyMap<string, ReportTimeBucketsDemand>, extentFrom: number, extentTo: number, timeZone: string): TimeBucketsDaysNeed[];

package/dist/src/workspace/reports/time-buckets/navigate.d.ts

@@ -0,0 +1,26 @@
+import type { TimeBucketsSetup } from "@overvis/hmi-shared/report";
+export type TimeBucketsPaintedGrain = "daily" | "cadence";
+export declare function timeBucketsCadenceMinDurationMs(options: {
+    bucketStartMs: number;
+    cadence: TimeBucketsSetup["cadence"];
+    timeZone: string;
+}): number;
+/**
+ * Shared-window after a click on a painted bar.
+ * Cadence bar: that bucket. Daily bar: that local day, or a 1000-slot window
+ * centered on the click when the day is over budget.
+ */
+export declare function timeBucketsClickWindow(options: {
+    grain: TimeBucketsPaintedGrain;
+    bucketStartMs: number;
+    clickMs: number;
+    cadence: TimeBucketsSetup["cadence"];
+    timeZone: string;
+    extent: {
+        from: number;
+        to: number;
+    } | null;
+}): {
+    from: number;
+    to: number;
+} | null;

package/dist/src/workspace/reports/time-buckets/plot.d.ts

@@ -0,0 +1,58 @@
+import uPlot from "uplot";
+import { type ReportColor, type TimeBucketsSetup } from "@overvis/hmi-shared/report";
+import { type ChartCommentStripe } from "../chart/comment-gutter.js";
+import type { TimeBucketsPaintedGrain } from "./navigate.js";
+export interface TimeBucketsPlotSeries {
+    parameterId: string;
+    label: string;
+    units: string;
+    defaultColor: ReportColor;
+    ys: (number | null)[];
+    stroke: string;
+    fill: string | undefined;
+    scaleMultiplier: number;
+    scaleShift: number;
+    decimalPlaces: number;
+}
+/** Visual slot inside `[bucketStart, bucketStart+step)`. Negative leftFrac bleeds into the previous grain. */
+export declare function timeBucketsBarFracs(displayAs: TimeBucketsSetup["displayAs"], seriesCount: number, seriesIndex: number): {
+    leftFrac: number;
+    widthFrac: number;
+};
+export declare function timeBucketsBarSeriesOpts(seriesNow: readonly {
+    label: string;
+    stroke: string;
+    fill: string | undefined;
+}[], displayAs: TimeBucketsSetup["displayAs"], xValues: () => number[], steps: () => number[]): {
+    seriesOpts: uPlot.Series[];
+    bands: uPlot.Band[];
+};
+/** Day-or-coarser: `YYYY-MM-DD`. Finer: date and time on two lines so more ticks fit. */
+export declare function formatTimeBucketsXAxisTick(epochMs: number, timeZone: string, incrSec: number): string;
+/** uPlot `axes[0].values` for bucket starts in the report timezone, edge labels clipped. */
+export declare function timeBucketsXAxisValues(u: uPlot, splits: number[], foundIncr: number, timeZone: string): string[];
+export declare const TimeBucketsPlot: import("react").MemoExoticComponent<({ xs, series, grain, displayAs, cadence, timeZone, height, from, to, showTooltip, interactiveClick, onBucketClick, panZoomEnabled, onPanZoom, onBrushSelect, windowOverlay, showXTickLabels, className, dataReportPlot, commentStripes, }: {
+    xs: number[];
+    series: TimeBucketsPlotSeries[];
+    grain: TimeBucketsPaintedGrain[];
+    displayAs: TimeBucketsSetup["displayAs"];
+    cadence: TimeBucketsSetup["cadence"];
+    timeZone: string;
+    height: number;
+    from: number;
+    to: number;
+    showTooltip: boolean;
+    interactiveClick: boolean;
+    onBucketClick?: (bucketStartMs: number, grain: TimeBucketsPaintedGrain, clickMs: number) => void;
+    panZoomEnabled?: boolean;
+    onPanZoom?: (from: number, to: number) => void;
+    onBrushSelect?: (from: number, to: number) => void;
+    windowOverlay?: {
+        from: number;
+        to: number;
+    };
+    showXTickLabels?: boolean;
+    className?: string;
+    dataReportPlot?: string;
+    commentStripes?: ChartCommentStripe[];
+}) => import("react").JSX.Element>;

package/dist/src/workspace/reports/time-buckets/representation.d.ts

@@ -0,0 +1,8 @@
+import { type ReactNode } from "react";
+import type { TimeBucketsSetup } from "@overvis/hmi-shared/report";
+export interface TimeBucketsRepresentationProps {
+    representationKey: string;
+    setup: TimeBucketsSetup;
+    className?: string;
+}
+export declare function TimeBucketsRepresentation({ representationKey, setup, className, }: TimeBucketsRepresentationProps): ReactNode;

package/dist/src/workspace/reports/time-buckets/slots.d.ts

@@ -0,0 +1,23 @@
+import type { ReadingsCadence } from "@overvis/hmi-shared/parameter";
+import { type TimeBucketsSetup } from "@overvis/hmi-shared/report";
+import type { TimeBucketsPaintedGrain } from "./navigate.js";
+export type TimeBucketsCadence = TimeBucketsSetup["cadence"];
+export declare function timeBucketsClickNavigateAllowed(options: {
+    chartDisplay: "frozen" | "movable";
+    immutableTimeRange: boolean;
+}): boolean;
+export declare function timeBucketsNumericValue(value: number | string): number | null;
+export declare function timeBucketsClosedTo(from: number, to: number, cadence: TimeBucketsCadence, timeZone: string): number;
+/**
+ * Local-day starts that intersect `[from, to)`, including today.
+ * Hour-closed like `readings.days`, not day-closed cadence `1d`.
+ */
+export declare function timeBucketsDayStarts(from: number, to: number, timeZone: string): number[];
+/** Closed bucket starts in `[from, closedTo)` at the grain (time X grid). */
+export declare function closedTimeBucketStarts(from: number, closedTo: number, cadence: ReadingsCadence, timeZone: string): number[];
+export declare function timeBucketsNextBucketEnd(bucketStart: number, cadence: TimeBucketsCadence, timeZone: string): number | null;
+/** Seconds for a lone time-axis bar (click-navigate leaves one closed bucket). */
+export declare function timeBucketsFallbackStepSec(bucketStartMs: number, cadence: TimeBucketsCadence, timeZone: string): number;
+/** Bar width in seconds from the painted grain, not the next `xs` neighbour. */
+export declare function timeBucketsBarStepSec(bucketStartMs: number, grain: TimeBucketsPaintedGrain, cadence: TimeBucketsCadence, timeZone: string): number;
+export declare function timeBucketsBarSteps(xsMs: readonly number[], grain: readonly TimeBucketsPaintedGrain[], cadence: TimeBucketsCadence, timeZone: string): number[];

package/dist/src/workspace/reports/time-nav.d.ts

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

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

@@ -0,0 +1,29 @@
+import { type DemandCacheMap, type DemandNeed, type DemandSlotSpec } from "./demand-cache.js";
+/** How a widget adds and removes its demand. All members are stable. */
+export interface DemandRegistration<D> {
+    register: (demandId: string, demand: D) => void;
+    unregister: (demandId: string) => void;
+    /** Demand identity: an equal string means an equal demand. */
+    serialize: (demand: D) => string;
+}
+export interface DemandRegistry<D> extends DemandRegistration<D> {
+    demands: ReadonlyMap<string, D>;
+}
+/** Mounted widget demands by mount id. */
+export declare function useDemandRegistry<D>(serialize: (demand: D) => string): DemandRegistry<D>;
+/** Register a widget demand for the life of the mount; re-registers when it serializes differently. */
+export declare function useRegisterDemand<D>(registration: DemandRegistration<D>, demand: D): void;
+/**
+ * One keyed cache that re-renders the component when it changes. `start` runs a slot over it and
+ * supersedes (aborts) the previous run; it returns the run's abort for effect cleanup.
+ */
+export declare function useDemandSlot<N extends DemandNeed, E>(): {
+    cache: DemandCacheMap<E>;
+    get: () => DemandCacheMap<E>;
+    start: (slot: Omit<DemandSlotSpec<N, E>, "store">) => () => void;
+};
+/** `from`/`to` after they stop changing for 300 ms (pan/zoom drags). */
+export declare function useSettledRange(from: number, to: number): {
+    from: number;
+    to: number;
+};

package/dist/src/workspace/reports/use-quick-report.d.ts

@@ -0,0 +1,45 @@
+import type { ReportPresetCreateTemporaryInput, ReportPresetCreateTemporaryOutput } from "@overvis/hmi-shared/report";
+export interface QuickReportCreateInput {
+    parameterIds: readonly string[];
+    title: ReportPresetCreateTemporaryInput["title"];
+    /**
+     * Counters among `parameterIds` (energy, heat, water, gas): their time buckets show
+     * per-bucket differences instead of averages.
+     */
+    counterParameterIds?: readonly string[];
+    /** Time-bucket size: hourly over the last day (default) or daily over the last 31 days. */
+    cadence?: ReportPresetCreateTemporaryInput["cadence"];
+}
+export interface UseQuickReportOptions {
+    workspaceId: string;
+    navigateToReport: (presetId: string) => void;
+    onSkipped: (skipped: ReportPresetCreateTemporaryOutput["skipped"]) => void;
+    onError: (error: unknown) => void;
+}
+export declare function completeQuickReportCreation(input: {
+    result: {
+        skipped: ReportPresetCreateTemporaryOutput["skipped"];
+        reportPreset: Pick<ReportPresetCreateTemporaryOutput["reportPreset"], "id">;
+    };
+    navigateToReport: (presetId: string) => void;
+    onSkipped: (skipped: ReportPresetCreateTemporaryOutput["skipped"]) => void;
+}): void;
+/**
+ * `report.preset.createTemporary` input with unique ids. Counters pass unchanged, so one outside
+ * `parameterIds` fails with `report_preset_temporary_counter_not_requested`. Null when there is
+ * nothing to show.
+ */
+export declare function quickReportInput(workspaceId: string, { parameterIds, title, counterParameterIds, cadence }: QuickReportCreateInput): ReportPresetCreateTemporaryInput | null;
+/** Create a temporary report and hand its route to the dashboard or host navigation. */
+export declare function useQuickReport({ workspaceId, navigateToReport, onSkipped, onError, }: UseQuickReportOptions): {
+    create: (report: QuickReportCreateInput) => Promise<void>;
+    isPending: boolean;
+};
+/**
+ * `useQuickReport` for a dashboard: the report opens with a page load, since a dashboard runs
+ * outside the host's router, and skipped parameters or a failure show as a toast.
+ */
+export declare function useDashboardQuickReport(workspaceId: string): {
+    create: (report: QuickReportCreateInput) => Promise<void>;
+    isPending: boolean;
+};

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

@@ -0,0 +1,6 @@
+export declare function ReportWidget({ representationKey, className, column, }: {
+    representationKey: string;
+    className?: string;
+    column?: "full" | "1/2" | "1/3" | "1/4";
+}): import("react").JSX.Element;
+export declare const ReportView: import("react").MemoExoticComponent<() => import("react").JSX.Element>;