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

package/dist/src/workspace/parameters/value/state.d.ts

@@ -0,0 +1,96 @@
+import { type AppLocale, type LocalizedLiveValue } from "@overvis/hmi-shared";
+import type { ParameterRuntimeErrorCode, ParameterRuntimeErrorParams, ParameterRuntimeErrorReason } from "@overvis/hmi-shared/parameter";
+import type { ParameterValueState } from "../live/model.js";
+export type ParamValueDisplayMode = "repr" | "number" | "hex";
+interface SetupReading {
+    value: LocalizedLiveValue;
+    rawHex: string;
+    numberValue?: number;
+    boolValue?: boolean;
+}
+interface SetupOk extends SetupReading {
+    status: "ok";
+    receivedAt: number;
+    freshness: "fresh" | "stale";
+    refreshing: boolean;
+    saving: boolean;
+}
+interface SetupStaleOk extends SetupOk {
+    freshness: "stale";
+}
+interface SetupLastKnown extends SetupReading {
+    /** Dimmed snapshot from listTree KV enrichment; not editable. */
+    status: "lastKnown";
+    /** True while the first live read of this snapshot is in flight. */
+    refreshing: boolean;
+}
+export interface SetupCellFailure {
+    code: ParameterRuntimeErrorCode;
+    reason?: ParameterRuntimeErrorReason;
+    params?: ParameterRuntimeErrorParams;
+}
+interface SetupError extends SetupCellFailure {
+    status: "error";
+    refreshing: boolean;
+    saving: boolean;
+}
+export type ParamValueState = {
+    status: "loading";
+} | SetupOk | SetupLastKnown | SetupError | {
+    /** Last reading plus the failure of the attempt that did not replace it. */
+    status: "failedReading";
+    reading: SetupStaleOk | SetupLastKnown;
+    failure: SetupCellFailure;
+    refreshing: boolean;
+    saving: boolean;
+};
+export declare function setupStateFromLive(state: ParameterValueState): ParamValueState | null;
+/**
+ * Map a coordinator state onto a Setup cell. A timeout-class error keeps the last reading and
+ * puts that failure on the same cell. A live value or a definite device/config error replaces it.
+ */
+export declare function mergeSetupValueFromLive(previous: ParamValueState | undefined, live: ParameterValueState): ParamValueState | null;
+export declare function liveValuesEqual(a: LocalizedLiveValue, b: LocalizedLiveValue): boolean;
+export declare function displayLiveValue(value: LocalizedLiveValue, locale?: AppLocale): string;
+/**
+ * Label for an ok reading in the Setup value cell.
+ * Empty string becomes `""` so the cell stays visible and clickable.
+ */
+export declare function formatOkValueLabel(text: string): string;
+/** Number-mode text for an ok reading (never "—"). */
+export declare function displayNumberModeValue(state: {
+    value: LocalizedLiveValue;
+    numberValue?: number;
+    boolValue?: boolean;
+}, locale?: AppLocale): string;
+/** Hex-mode display: `0x` + uppercase rawHex. */
+export declare function displayHexModeValue(rawHex: string): string;
+export declare function isValidRawHexDraft(draft: string): boolean;
+/** Strip spaces and optional `0x` / `0X`; lowercase. Wire form has no prefix. */
+export declare function normalizeRawHexDraft(draft: string): string;
+export declare function isSavingDisplay(state: ParamValueState | undefined): boolean;
+export type LastKnownParamValue = Extract<ParamValueState, {
+    status: "lastKnown";
+}>;
+export declare function lastKnownFromReading(reading: {
+    value: LocalizedLiveValue;
+    rawHex: string;
+    numberValue?: number;
+    boolValue?: boolean;
+}): LastKnownParamValue;
+export declare function lastKnownEqual(a: LastKnownParamValue, b: LastKnownParamValue): boolean;
+/**
+ * Seed dimmed last-known cells from listTree enrichment.
+ * A session cell wins, including one that already shows a failure. Prior lastKnown may be
+ * replaced when the snapshot changes.
+ */
+export declare function seedLastKnownStates(prev: Map<string, ParamValueState>, parameters: readonly {
+    id: string;
+    lastReading: {
+        value: LocalizedLiveValue;
+        rawHex: string;
+        numberValue?: number;
+        boolValue?: boolean;
+    } | null;
+}[]): Map<string, ParamValueState>;
+export {};

package/dist/src/workspace/parameters/value/type/datetime-parts.d.ts

@@ -0,0 +1,12 @@
+import type { ParameterValueType } from "@overvis/hmi-shared/parameter";
+type DatetimeComposition = Extract<ParameterValueType, {
+    name: "datetime";
+}>["composition"];
+type DatetimePartsComposition = Extract<DatetimeComposition, {
+    kind: "datetime";
+}>;
+export declare function DatetimePartsFields({ composition, onChange, }: {
+    composition: DatetimePartsComposition;
+    onChange: (next: DatetimePartsComposition) => void;
+}): import("react").JSX.Element;
+export {};

package/dist/src/workspace/parameters/value/type/fields.d.ts

@@ -0,0 +1,5 @@
+import { type ParameterValueType } from "@overvis/hmi-shared/parameter";
+export declare function ValueTypeFields({ valueType, onChange, }: {
+    valueType: ParameterValueType;
+    onChange: (next: ParameterValueType) => void;
+}): import("react").JSX.Element;

package/dist/src/workspace/parameters/value/type/geo.d.ts

@@ -0,0 +1,10 @@
+import type { ParameterValueType } from "@overvis/hmi-shared/parameter";
+type GeoValueType = Extract<ParameterValueType, {
+    name: "geo";
+}>;
+export declare function GeoValueTypeFields({ valueType, onChange, onEncodingChange, }: {
+    valueType: GeoValueType;
+    onChange: (next: GeoValueType) => void;
+    onEncodingChange: (encoding: "scalar" | "dms") => void;
+}): import("react").JSX.Element;
+export {};

package/dist/src/workspace/parameters/value/type/int-repr.d.ts

@@ -0,0 +1,9 @@
+import type { ParameterValueType } from "@overvis/hmi-shared/parameter";
+export declare function IntReprEditor({ repr, onChange, }: {
+    repr: Extract<ParameterValueType, {
+        name: "int";
+    }>["repr"];
+    onChange: (next: Extract<ParameterValueType, {
+        name: "int";
+    }>["repr"]) => void;
+}): import("react").JSX.Element;

package/dist/src/workspace/parameters/writability.d.ts

@@ -0,0 +1,26 @@
+import type { Parameter, ParameterValueType } from "@overvis/hmi-shared/parameter";
+import { type AppLocale } from "@overvis/hmi-shared";
+/** Client-side mirror of source writability (const allowWrite / modbus writeFunction). */
+export declare function isParameterValueWritable(param: Parameter): boolean;
+export interface ParameterValueEditChoice {
+    /** Locale-resolved label shown in the select. */
+    label: string;
+    /** Plain string committed on write (digits / true|false). */
+    writeValue: string;
+}
+/**
+ * Dropdown choices for int/bool reprs; null means free-text editor.
+ * `writeValue` is stable even when resolved labels collide.
+ */
+export declare function parameterValueEditChoices(valueType: ParameterValueType, locale?: AppLocale): ParameterValueEditChoice[] | null;
+export interface ParameterValueChoice {
+    /** Underlying value; stable across locales and representation edits. */
+    value: number | boolean;
+    /** Locale-resolved representation, or the value itself when none is defined. */
+    label: string;
+}
+/**
+ * Choices for mapping int/bool values, keyed by underlying value. Labels never carry codes, even
+ * when representations coincide; null means the value type has no finite choices.
+ */
+export declare function parameterValueChoices(valueType: ParameterValueType, locale?: AppLocale): ParameterValueChoice[] | null;

package/dist/src/workspace/pull-instructions.d.ts

@@ -0,0 +1,4 @@
+export declare function WorkspacePullInstructions({ workspaceId, showHeading, }: {
+    workspaceId: string;
+    showHeading?: boolean;
+}): import("react").JSX.Element;

package/dist/src/workspace/query-gate.d.ts

@@ -0,0 +1,40 @@
+import type { ReactNode } from "react";
+/** The part of a TanStack / tRPC query result that `QueryGate` branches on. */
+export interface QueryGateState<TData, TError> {
+    isLoading: boolean;
+    isError: boolean;
+    error: TError | null;
+    data: TData | undefined;
+}
+/**
+ * Loading / error / empty / data branching for one query result.
+ *
+ * Order: `isLoading` → `loading`; `isError` → `error`; no data yet (disabled or paused query) →
+ * `loading`; `isEmpty(data)` → `empty`; otherwise `children(data)`.
+ */
+export declare function QueryGate<TData, TError>({ query, loading, error, isEmpty, empty, children, }: {
+    query: QueryGateState<TData, TError>;
+    loading: ReactNode;
+    error: (error: TError | null) => ReactNode;
+    isEmpty?: (data: TData) => boolean;
+    empty?: ReactNode;
+    children: (data: TData) => ReactNode;
+}): ReactNode;
+/** "Request failed" notice for a failed query, with Retry when `onRetry` is set. */
+export declare function QueryErrorAlert({ message, onRetry, retrying, className, }: {
+    message: string;
+    onRetry?: () => unknown;
+    retrying?: boolean;
+    className?: string;
+}): import("react").JSX.Element;
+/**
+ * Centered failed-query state: `QueryErrorAlert` with Retry when `onRetry` is set. `actions`
+ * replaces Retry (e.g. a dialog's cancel button).
+ */
+export declare function QueryErrorState({ message, onRetry, retrying, actions, className, }: {
+    message: string;
+    onRetry?: () => unknown;
+    retrying?: boolean;
+    actions?: ReactNode;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/src/workspace/reports/aggregate-fetch.d.ts

@@ -0,0 +1,25 @@
+import type { ReadingsAggregateOutput, ReadingsCadenceParameter } from "@overvis/hmi-shared/parameter";
+import type { ReportReadingsEnv } from "./readings-client.js";
+import { type DemandFetchContext } from "./demand-cache.js";
+interface AggregateWindowNeed {
+    key: string;
+    parameterId: string;
+    sourceValueType: string;
+    aggregation: ReadingsCadenceParameter["aggregation"];
+    from: number;
+    to: number;
+}
+type AggregateValue = ReadingsAggregateOutput["values"][number];
+/**
+ * One `readings.aggregate` value per need. Needs sharing aggregation and window go in one
+ * request (parameter-batched); entry shapes come from the representation.
+ */
+export declare function fetchAggregateGroups<N extends AggregateWindowNeed, E>(options: {
+    needs: N[];
+    context: DemandFetchContext<E>;
+    env: ReportReadingsEnv<"aggregate">;
+    loading: (existing: E | undefined, need: N) => E;
+    ready: (found: AggregateValue | undefined) => E;
+    failed: (existing: E | undefined, code: string, need: N) => E;
+}): Promise<void>;
+export {};

package/dist/src/workspace/reports/bar-legend.d.ts

@@ -0,0 +1,12 @@
+import type { ReportColor } from "@overvis/hmi-shared/report";
+export declare function ReportBarLegend({ items, visibleParameterIds, interactive, onToggle, }: {
+    items: {
+        parameterId: string;
+        label: string;
+        units: string;
+        defaultColor: ReportColor;
+    }[];
+    visibleParameterIds: ReadonlySet<string>;
+    interactive: boolean;
+    onToggle: (parameterId: string, visible: boolean) => void;
+}): import("react").JSX.Element;

package/dist/src/workspace/reports/bar-path.d.ts

@@ -0,0 +1,25 @@
+import type uPlot from "uplot";
+export declare function stackedBarBaseline(u: uPlot, prevUplotIdx: number): number[];
+/**
+ * uPlot `paths.bars` only honours a custom baseline when both `y0` and `y1` are given;
+ * `y0` alone is ignored and every stacked bar is drawn from zero (blended overlaps).
+ */
+export declare function stackedBarsDisp(prevUplotIdx: number): uPlot.Series.BarsPathBuilderDisplay;
+/** True when `[bucketStart, bucketStart+step)` overlaps the visible x scale. */
+export declare function grainBarIntersectsScale(bucketStart: number, step: number, scaleMin: number, scaleMax: number): boolean;
+/**
+ * uPlot `paths.bars` with `disp.size` uses only `sizes[0]` for every bar.
+ * Mixed daily + cadence widths need per-index geometry.
+ * uPlot also asks for the points just outside the window; skip those whose grain
+ * span does not meet the scale so a next-day daily bar cannot paint into today.
+ */
+export declare function grainBarPaths(options: {
+    xValues: () => number[];
+    steps: () => number[];
+    leftFrac: number;
+    widthFrac: number;
+    prevUplotIdx: number | null;
+}): uPlot.Series.PathBuilder;
+export declare function neighbourBarSteps(xs: readonly number[], fallbackStep?: number): number[];
+/** `span` is `[xs[i], xs[i+1])` (last bucket uses `steps[i]`). `nearest` is closest x. */
+export declare function barIndexAtX(xs: readonly number[], steps: readonly number[], x: number, mode: "nearest" | "span"): number | null;

package/dist/src/workspace/reports/cadence-fetch.d.ts

@@ -0,0 +1,25 @@
+import type { ReadingsCadenceParameter } from "@overvis/hmi-shared/parameter";
+import type { ReportCacheEnv, ReportCacheSlot, ReportCacheWindowKind } from "./data/report-caches.js";
+import type { ReportReadingsEnv } from "./readings-client.js";
+import { type DemandFetchContext } from "./demand-cache.js";
+import { type ReportTableCadenceEntry } from "./table/demand.js";
+import { type CadenceNeed } from "./table/fetch.js";
+type CadenceContext = DemandFetchContext<ReportTableCadenceEntry>;
+/** A per-parameter bucketed series fetched chunk by chunk (`readings.cadence` / `readings.days`). */
+interface ChunkedCadenceNeed {
+    key: string;
+    parameterId: string;
+    sourceValueType: string;
+    aggregation: ReadingsCadenceParameter["aggregation"];
+    timeZone: string;
+    from: number;
+    to: number;
+}
+type CollectNeeds<D, N> = (demands: ReadonlyMap<string, D>, from: number, to: number, timeZone: string) => N[];
+/** A `readings.cadence` slot over `window` (resumes partial entries). */
+export declare function cadenceSlot<D>(window: ReportCacheWindowKind, collect: CollectNeeds<D, CadenceNeed>): ReportCacheSlot<D, CadenceNeed, ReportTableCadenceEntry, ReportCacheEnv>;
+/** A `readings.days` slot over `window` (resumes partial entries). */
+export declare function daysSlot<D>(window: ReportCacheWindowKind, collect: CollectNeeds<D, ChunkedCadenceNeed>): ReportCacheSlot<D, ChunkedCadenceNeed, ReportTableCadenceEntry, ReportCacheEnv>;
+/** `readings.cadence` for cadence needs; resumes after the last fetched chunk. */
+export declare function fetchCadenceGroups(needs: CadenceNeed[], context: CadenceContext, { workspaceId, readings }: ReportReadingsEnv<"cadence">): Promise<void>;
+export {};

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

@@ -0,0 +1,46 @@
+import type { ReadingsCadenceParameter, ReadingsNumericAggregation } from "@overvis/hmi-shared/parameter";
+import type { CalendarSetup } from "@overvis/hmi-shared/report";
+import type { CadenceNeed } from "../table/fetch.js";
+import type { ReportTableCadenceEntry, ReportTableCadenceValue } from "../table/demand.js";
+export type ReportCalendarSlotKind = "value" | "text" | "bg" | "border";
+export interface ReportCalendarDemandSlot {
+    kind: ReportCalendarSlotKind;
+    parameterId: string;
+    sourceValueType: string;
+    aggregation: ReadingsNumericAggregation;
+}
+export interface ReportCalendarDemand {
+    showAs: CalendarSetup["showAs"];
+    slots: ReportCalendarDemandSlot[];
+}
+export type ReportCalendarCadenceValue = ReportTableCadenceValue;
+export type ReportCalendarCadenceEntry = ReportTableCadenceEntry;
+export type ReportCalendarCadenceCache = Map<string, ReportCalendarCadenceEntry>;
+export interface CalendarDaysNeed {
+    key: string;
+    parameterId: string;
+    sourceValueType: string;
+    aggregation: ReadingsCadenceParameter["aggregation"];
+    timeZone: string;
+    from: number;
+    to: number;
+}
+export declare function calendarDaysCacheKey(parts: {
+    parameterId: string;
+    sourceValueType: string;
+    aggregation: string;
+    timeZone: string;
+    from: number;
+    to: number;
+}): string;
+export declare function calendarHourCacheKey(parts: {
+    parameterId: string;
+    sourceValueType: string;
+    aggregation: string;
+    timeZone: string;
+    from: number;
+    to: number;
+}): string;
+export declare function serializeReportCalendarDemand(demand: ReportCalendarDemand): string;
+export declare function collectCalendarDaysNeeds(demands: ReadonlyMap<string, ReportCalendarDemand>, from: number, to: number, timeZone: string): CalendarDaysNeed[];
+export declare function collectCalendarHourNeeds(demands: ReadonlyMap<string, ReportCalendarDemand>, from: number, to: number, timeZone: string): CadenceNeed[];

package/dist/src/workspace/reports/calendar/layout.d.ts

@@ -0,0 +1,98 @@
+import type { ReadingsNumericAggregation } from "@overvis/hmi-shared/parameter";
+export interface CalendarDay {
+    startMs: number;
+    endMs: number;
+    year: number;
+    month: number;
+    day: number;
+    weekdayMon0: number;
+    isoYear: number;
+    isoWeek: number;
+}
+export type CalendarGridCell = {
+    kind: "pad";
+} | {
+    kind: "day";
+    day: CalendarDay;
+};
+export interface CalendarMonthBlock {
+    year: number;
+    month: number;
+    rows: CalendarGridCell[][];
+}
+export interface CalendarWeekRow {
+    isoYear: number;
+    isoWeek: number;
+    cells: CalendarGridCell[];
+}
+export interface CalendarYearColumn {
+    isoYear: number;
+    isoWeek: number;
+    monthTick: string | null;
+    cells: CalendarGridCell[];
+}
+export type CalendarHourCell = {
+    kind: "pad";
+} | {
+    kind: "cell";
+    startMs: number;
+    endMs: number;
+    hour: number;
+    closed: boolean;
+};
+export interface CalendarWeekHoursDay {
+    day: CalendarDay;
+    hours: CalendarHourCell[];
+}
+export interface CalendarWeekHoursBlock {
+    isoYear: number;
+    isoWeek: number;
+    days: CalendarWeekHoursDay[];
+}
+export declare function isoWeekYearWeek(year: number, month: number, day: number): {
+    isoYear: number;
+    week: number;
+};
+export declare function formatIsoWeek(isoYear: number, week: number): string;
+export declare function formatYearMonth(year: number, month: number): string;
+export declare function isoWeekMonthTick(isoYear: number, week: number): string | null;
+export declare function intersectingLocalDays(from: number, to: number, timeZone: string): CalendarDay[];
+export declare function monthDayBlocks(days: readonly CalendarDay[]): CalendarMonthBlock[];
+export declare function weekDayRows(days: readonly CalendarDay[]): CalendarWeekRow[];
+export declare function yearDayColumns(days: readonly CalendarDay[]): CalendarYearColumn[];
+export declare function weekHoursBlocks(days: readonly CalendarDay[], from: number, to: number, timeZone: string, nowMs?: number): CalendarWeekHoursBlock[];
+export declare function calendarLocalDayRange(day: CalendarDay): {
+    from: number;
+    to: number;
+};
+export declare function calendarLocalHourRange(cell: Extract<CalendarHourCell, {
+    kind: "cell";
+}>): {
+    from: number;
+    to: number;
+};
+/** Exclusive end of closed local hours in `[from, min(to, now))`. */
+export declare function calendarHourClosedTo(from: number, to: number, timeZone: string, nowMs?: number): number;
+export declare function calendarHourIndexKey(day: Pick<CalendarDay, "year" | "month" | "day">, hour: number): string;
+export declare function indexCalendarDayRows<T extends {
+    bucketStart: number;
+}>(rows: readonly T[]): Map<number, T>;
+export declare function combineCalendarHourValues(aggregation: ReadingsNumericAggregation, prev: {
+    bucketStart: number;
+    value: number | string;
+    repr?: string | null;
+}, next: {
+    bucketStart: number;
+    value: number | string;
+    repr?: string | null;
+}, prevCount: number): {
+    value: number | string;
+    repr?: string | null;
+    bucketStart: number;
+    count: number;
+};
+export declare function indexCalendarHourRows<T extends {
+    bucketStart: number;
+    value: number | string;
+    repr?: string | null;
+}>(rows: readonly T[], timeZone: string, aggregation: ReadingsNumericAggregation): Map<string, T>;

package/dist/src/workspace/reports/calendar/representation.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from "react";
+import type { CalendarSetup } from "@overvis/hmi-shared/report";
+export interface CalendarRepresentationProps {
+    setup: CalendarSetup;
+    className?: string;
+}
+export declare function CalendarRepresentation({ setup, className, }: CalendarRepresentationProps): ReactNode;

package/dist/src/workspace/reports/cell-title.d.ts

@@ -0,0 +1,11 @@
+/** Native `title` for calendar / hourly-matrix cells. */
+export declare function reportCellNativeTitle(options: {
+    dateLabel: string;
+    valueText: string | null;
+    units: string;
+    showTitle: boolean;
+}): string | undefined;
+export declare function calendarUsesDotGrid(setup: {
+    compact: boolean;
+    dayValueParameter: unknown;
+}): boolean;

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

@@ -0,0 +1,17 @@
+import uPlot from "uplot";
+import type { PreparedSeries } from "./payload.js";
+/** Shared so the nav strip and legend line up with the main y-axis. */
+export declare const Y_AXIS_SIZE = 52;
+/** Min tick spacing: date-only when datetime spacing would already land on day+ incrs. */
+export declare function chartXAxisTickSpace(scaleMin: number, scaleMax: number, plotDim: number): number;
+/**
+ * Blank tick labels whose centered text would run past the canvas edge; uPlot would clip
+ * them mid-word otherwise. Room to the left is the y-axis gutter, to the right usually none.
+ */
+export declare function clipXTickLabels(u: uPlot, splits: number[], labels: string[]): string[];
+/** Day-or-coarser ticks omit the time; otherwise `YYYY-MM-DD HH:mm:ss`. */
+export declare function formatChartXAxisTick(epochMs: number, timeZone: string, incrSec: number): string;
+/** uPlot `axes[0].values` for a time axis in the report timezone, edge labels clipped. */
+export declare function chartXAxisValues(u: uPlot, splits: number[], foundIncr: number, timeZone: string): string[];
+/** Shared y axis from visible numeric series (values + min/max markers) inside the window. */
+export declare function chartYRange(series: readonly PreparedSeries[], fromMs: number, toMs: number, initMin: number, initMax: number): uPlot.Range.MinMax;