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

package/dist/src/workspace/parameters/live/diagnostics.d.ts

@@ -0,0 +1,9 @@
+import { type ParameterDiagnostic } from "./model.js";
+interface ParameterDiagnosticsProps {
+    diagnostics: readonly ParameterDiagnostic[];
+    workspaceId?: string;
+    dashboardId?: string;
+    onRetry?: () => void;
+}
+export declare function ParameterDiagnostics(props: ParameterDiagnosticsProps): import("react").JSX.Element | null;
+export {};

package/dist/src/workspace/parameters/live/history-windows.d.ts

@@ -0,0 +1,53 @@
+import type { ReadingsCadence } from "@overvis/hmi-shared/parameter";
+import type { ParameterHistoryPoint } from "./use-history.js";
+/** A history window that ends now, read from the historian as closed buckets of `cadence`. */
+export interface StoredHistoryWindow {
+    /** Length of the window in milliseconds. */
+    window: number;
+    cadence: ReadingsCadence;
+    cadenceMs: number;
+    /** How often the stored buckets load again. */
+    refetchMs: number;
+}
+export type StoredHistoryWindowKey = "1h" | "24h" | "7d";
+/**
+ * The usual chart windows: 1 h by minute, 24 h by 15 minutes and 7 d by hour, each one request of
+ * at most 168 buckets per parameter.
+ */
+export declare const storedHistoryWindows: Readonly<Record<StoredHistoryWindowKey, StoredHistoryWindow>>;
+/**
+ * How many live values to keep for a window's tail: every reading of its open bucket at
+ * `fastestRefreshMs`, so the line reaches the current time without a hole. Pass it as
+ * `maxPoints` to `useParameterValueHistory`.
+ */
+export declare function liveTailPoints(window: StoredHistoryWindow, fastestRefreshMs?: number): number;
+/**
+ * Stored buckets followed by the live values received after the last closed bucket, so the line
+ * reaches the current time. Without stored buckets there is no history to extend.
+ */
+export declare function withLiveTail(stored: readonly ParameterHistoryPoint[], live: readonly ParameterHistoryPoint[], cadenceMs: number): readonly ParameterHistoryPoint[];
+/**
+ * The minimum and maximum of stored extremes and of live values; null when there is no number.
+ * Stored values that are not numbers are left out.
+ */
+export declare function rangeExtremes(stored: readonly (number | string | undefined)[], live: readonly number[]): {
+    min: number;
+    max: number;
+} | null;
+/**
+ * The minimum and maximum of a parameter over a window that ends now: the historian's
+ * `readings.minMax`, reloaded every `refetchMs`, with the `live` values read since. Null while
+ * there is no number. Mount it again for another window, so another window's extremes never show.
+ */
+export declare function useStoredWindowExtremes({ workspaceId, parameterId, sourceValueType, window, live, enabled, }: {
+    workspaceId: string;
+    parameterId: string;
+    /** The parameter's value-type name, such as `num`. */
+    sourceValueType: string;
+    window: StoredHistoryWindow;
+    live: readonly ParameterHistoryPoint[];
+    enabled?: boolean;
+}): {
+    min: number;
+    max: number;
+} | null;

package/dist/src/workspace/parameters/live/metric.d.ts

@@ -0,0 +1,29 @@
+import type { AppLocale } from "@overvis/hmi-shared";
+import type { ReactNode } from "react";
+import type { ParameterValueState } from "./model.js";
+/**
+ * A live value with an engineering unit, retaining loading and stale-value semantics. The unit sits
+ * on the value's baseline, so units of any shape line up with the number. The value shows as its
+ * parameter formats it, or at exactly `fractionDigits` places; a value that is not a number then
+ * shows as a dash.
+ */
+export declare function ParameterReading({ state, locale, unit, fractionDigits, unavailable, skeletonClassName, }: {
+    state: ParameterValueState;
+    locale: AppLocale;
+    unit?: string;
+    fractionDigits?: number;
+    /** Shown while the value cannot be read; a translated "unavailable" by default. */
+    unavailable?: ReactNode;
+    skeletonClassName?: string;
+}): import("react").JSX.Element;
+/** A labeled reading for dashboard summaries; callers choose domain labels and icons. */
+export declare function ParameterMetric({ label, icon, state, locale, unit, compact, marker, }: {
+    label: string;
+    icon?: ReactNode;
+    state: ParameterValueState;
+    locale: AppLocale;
+    unit?: string;
+    compact?: boolean;
+    /** Shown after the value, such as a stale-value marker. */
+    marker?: ReactNode;
+}): import("react").JSX.Element;

package/dist/src/workspace/parameters/live/model.d.ts

@@ -0,0 +1,133 @@
+import { type LocalizedLiveValue } from "@overvis/hmi-shared";
+import type { ParameterReadValueResult, ParameterRuntimeError, ParameterRuntimeErrorCode, ParameterRuntimeErrorParams, ParameterRuntimeErrorReason, ParameterWriteValueResult } from "@overvis/hmi-shared/parameter";
+export type ParameterDiagnosticKind = "permission" | "endpoint" | "device-timeout" | "configuration" | "protocol" | "capacity" | "internal" | "unavailable";
+export interface ParameterDiagnostic {
+    kind: ParameterDiagnosticKind;
+    code: ParameterRuntimeErrorCode | "permission_denied" | "request_failed";
+    parameterIds: readonly string[];
+    reason?: ParameterRuntimeErrorReason;
+    params?: ParameterRuntimeErrorParams;
+    retryAfterMs?: number;
+    /**
+     * Requests to different registers that failed the same way on the same device, each with its
+     * register params and affected ids. Present only when there are several; `params` then leaves
+     * out the register location.
+     */
+    requests?: readonly ParameterDiagnostic[];
+}
+export interface ParameterValueSnapshot {
+    value: LocalizedLiveValue;
+    rawHex: string;
+    numberValue?: number;
+    boolValue?: boolean;
+    receivedAt: number;
+}
+export type ParameterValueState = {
+    status: "idle";
+    reason: "no-demand" | "disabled" | "forbidden";
+} | {
+    status: "loading";
+} | {
+    status: "value";
+    snapshot: ParameterValueSnapshot;
+    freshness: "fresh" | "stale";
+    refreshing: boolean;
+    saving: boolean;
+    diagnostic?: ParameterDiagnostic;
+} | {
+    status: "error";
+    diagnostic: ParameterDiagnostic;
+    refreshing: boolean;
+    saving: boolean;
+    retryAt?: number;
+};
+export type ParameterValuesStatus = "idle" | "loading" | "partial" | "ready" | "degraded" | "error" | "paused";
+export interface ParameterValuesDemandSnapshot {
+    status: ParameterValuesStatus;
+    states: ReadonlyMap<string, ParameterValueState>;
+    diagnostics: readonly ParameterDiagnostic[];
+    latestReceivedAt: number | null;
+    reading: boolean;
+    saving: boolean;
+}
+export interface ParameterValuesDemand extends ParameterValuesDemandSnapshot {
+    retry: () => void;
+}
+export declare const noDemandParameterValueState: ParameterValueState;
+/**
+ * A reading of the device as it is now: a fresh value read without a failure since. A value kept
+ * from an earlier read may no longer be on the device, so conditions, colors and decisions that
+ * write wait for a current one.
+ */
+export declare function isCurrentParameterValue(state: ParameterValueState | undefined): state is Extract<ParameterValueState, {
+    status: "value";
+}>;
+export interface ParameterValueReadOptions {
+    /**
+     * Read only a current value (see `isCurrentParameterValue`): one kept from an earlier read
+     * reads as none, so nothing is shown, decided or offered on old information.
+     */
+    current?: boolean;
+}
+/**
+ * The value conditions compare: a number, or a flag as 0 or 1; null for text, date-times and
+ * missing values.
+ */
+export declare function parameterValueComparable(state: ParameterValueState | undefined, options?: ParameterValueReadOptions): number | null;
+/**
+ * A date-time value, such as a maintenance date, as milliseconds since the epoch; null without a
+ * value or when it is not a date-time.
+ */
+export declare function parameterValueTime(state: ParameterValueState | undefined, options?: ParameterValueReadOptions): number | null;
+/** The typed numeric projection of the value, if one exists. */
+export declare function parameterValueNumber(state: ParameterValueState | undefined, options?: ParameterValueReadOptions): number | null;
+/** The typed boolean projection of the value, if one exists. */
+export declare function parameterValueBoolean(state: ParameterValueState | undefined, options?: ParameterValueReadOptions): boolean | null;
+/** A boolean flag from a typed boolean or a numeric zero/nonzero value. */
+export declare function parameterValueFlag(state: ParameterValueState | undefined, options?: ParameterValueReadOptions): boolean | null;
+/**
+ * When the oldest of `states` kept from an earlier read was received, as a "stale since" time;
+ * null when none is kept.
+ */
+export declare function parameterStatesStaleSince(states: Iterable<ParameterValueState | undefined>): number | null;
+/** Latest `snapshot.receivedAt` among current values, or null if none have a value. */
+export declare function latestParameterReceivedAt(states: Iterable<ParameterValueState>): number | null;
+/** Initial demand is pending before and during the first request. */
+export declare function isParameterValuePending(state: ParameterValueState): state is {
+    status: "loading";
+} | {
+    status: "idle";
+    reason: "no-demand";
+};
+export declare function primaryParameterDiagnosticKind(diagnostics: readonly ParameterDiagnostic[]): ParameterDiagnosticKind | null;
+export declare function parameterDiagnosticFromResult(parameterId: string, result: Extract<ParameterReadValueResult, {
+    status: "error";
+}>): ParameterDiagnostic;
+/**
+ * What a write did: `done` when the device acknowledged it; `no-response` when it may or may not
+ * have taken effect (a device or gateway timeout, a unit the gateway could not reach, a dropped
+ * connection, or no result at all); otherwise `failed` with the device's or host's error.
+ */
+export type ParameterWriteOutcome = {
+    kind: "done";
+} | {
+    kind: "no-response";
+} | {
+    kind: "failed";
+    error: ParameterRuntimeError;
+};
+export declare function parameterWriteOutcome(result: ParameterWriteValueResult | undefined): ParameterWriteOutcome;
+export declare function parameterDiagnosticKey(diagnostic: ParameterDiagnostic): string;
+/**
+ * Group diagnostics by root cause. The same failure on the same device collapses into one
+ * diagnostic for all affected parameters; when it spans several registers, `requests` keeps them.
+ */
+export declare function groupParameterDiagnostics(diagnostics: readonly ParameterDiagnostic[]): ParameterDiagnostic[];
+/** Combine independently refreshed parameter cohorts into one dashboard summary. */
+export declare function combineParameterValuesDemands(demands: readonly ParameterValuesDemand[]): ParameterValuesDemand;
+export declare function aggregateParameterValues(input: {
+    parameterIds: readonly string[];
+    getState: (parameterId: string) => ParameterValueState;
+    enabled: boolean;
+    paused: boolean;
+}): ParameterValuesDemandSnapshot;

package/dist/src/workspace/parameters/live/provider.d.ts

@@ -0,0 +1,49 @@
+import { type ReactNode } from "react";
+import type { ParameterWriteValuesInput, ParameterWriteValuesOutput } from "@overvis/hmi-shared/parameter";
+import type { WorkspaceAccess } from "@overvis/hmi-shared/workspace";
+import { ParameterValuesCoordinator } from "./coordinator.js";
+import { type ParameterValueState, type ParameterValuesDemand } from "./model.js";
+export declare function ParameterValuesProvider({ children, access, }: {
+    children: ReactNode;
+    access?: WorkspaceAccess;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<ParameterValuesCoordinator | null>>;
+/** Joins the page's parameter values when it has them, or keeps its own for the children. */
+export declare function OptionalParameterValuesProvider({ children }: {
+    children: ReactNode;
+}): string | number | bigint | boolean | import("react").FunctionComponentElement<{
+    children: ReactNode;
+    access?: WorkspaceAccess;
+}> | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | null | undefined;
+export declare function normalizedParameterIdsKey(parameterIds: readonly string[]): string;
+export declare function parameterIdsFromKey(key: string): string[];
+export interface UseParameterValuesOptions {
+    parameterIds: readonly string[];
+    intervalMs: number;
+    enabled?: boolean;
+}
+export declare function useParameterValues({ parameterIds, intervalMs, enabled, }: UseParameterValuesOptions): ParameterValuesDemand;
+/**
+ * Whether a read of any of the parameters is under way, such as a retry after a failure. False
+ * outside `ParameterValuesProvider`.
+ */
+export declare function useParametersReading(parameterIds: readonly string[]): boolean;
+export declare function useParameterValue(parameterId: string): ParameterValueState;
+export interface ParameterValueActions {
+    refreshValues: (parameterIds: readonly string[]) => void;
+    /**
+     * Runs an ordered write sequence after any other on this page has finished, so their steps never
+     * interleave.
+     */
+    runSequence: <T>(sequence: () => Promise<T>) => Promise<T>;
+    /** Reads the written parameters again afterwards, except those in `writeOnly`. */
+    writeValues: (input: ParameterWriteValuesInput, options?: {
+        writeOnly?: readonly string[];
+    }) => Promise<ParameterWriteValuesOutput>;
+}
+export declare function useParameterValueActions(): ParameterValueActions;
+/**
+ * Read parameters once, for data the page does not show, such as a fleet summary requested from a
+ * site page. Resolves when every value has arrived or failed, or after `timeoutMs`.
+ */
+export declare function useReadParameterValuesOnce(): (parameterIds: readonly string[], timeoutMs?: number) => Promise<ReadonlyMap<string, ParameterValueState>>;
+export declare function useParameterValuesCoordinator(): ParameterValuesCoordinator;

package/dist/src/workspace/parameters/live/read-once.d.ts

@@ -0,0 +1,13 @@
+import type { ParameterValuesCoordinator } from "./coordinator.js";
+import { type ParameterValueState } from "./model.js";
+/** Longest wait for a one-off read before it settles with whatever states it has. */
+export declare const readParameterValuesOnceTimeoutMs = 8000;
+/**
+ * Read parameters once through the shared coordinator: a temporary demand and an immediate read,
+ * even for a parameter another page polls and that waits out a retry delay. Resolves when every
+ * scheduled value has arrived or failed, or at the deadline with the states known then; a
+ * suspended parameter answers with its known failure. Removing the demand also drops a read that
+ * never settled. Pages use it for data they do not show, such as a fleet summary requested from a
+ * site page.
+ */
+export declare function readParameterValuesOnce(coordinator: ParameterValuesCoordinator, parameterIds: readonly string[], timeoutMs?: number): Promise<ReadonlyMap<string, ParameterValueState>>;

package/dist/src/workspace/parameters/live/stale-note.d.ts

@@ -0,0 +1,8 @@
+import type { ParameterValueState } from "./model.js";
+/** The standard label of a value kept from an earlier read, such as "Stale · 2026-10-06 13:50:00". */
+export declare function parameterStaleSinceText(receivedAt: number): string;
+/**
+ * For a value kept from an earlier read, a note saying since when, such as "Stale ·
+ * 2026-10-06 13:50:00", for a title and screen readers; undefined for a current value.
+ */
+export declare function parameterStaleNote(state: ParameterValueState | undefined): string | undefined;

package/dist/src/workspace/parameters/live/use-history.d.ts

@@ -0,0 +1,30 @@
+export interface ParameterHistoryPoint {
+    at: number;
+    value: number;
+}
+export interface ParameterHistory {
+    parameterId: string;
+    points: ParameterHistoryPoint[];
+}
+export declare function appendParameterHistory(current: ParameterHistory, parameterId: string, point: ParameterHistoryPoint, maxPoints: number): ParameterHistory;
+type ParameterHistories = ReadonlyMap<string, ParameterHistory>;
+/** Add a reading to one parameter's history; the same map when nothing changed. */
+export declare function appendParameterHistories(current: ParameterHistories, parameterId: string, point: ParameterHistoryPoint, maxPoints: number): ParameterHistories;
+/** Forget the histories of parameters no longer shown; the same map when all stay. */
+export declare function keepParameterHistories(current: ParameterHistories, parameterIds: readonly string[]): ParameterHistories;
+/**
+ * Numeric readings of each of `parameterIds` received while the component is mounted, newest
+ * last and at most `maxPoints` each, in `parameterIds` order. The list may change length between
+ * renders; a parameter keeps its readings while it stays in the list, and an empty id has none.
+ * Each list keeps its identity until a reading is added to it.
+ */
+export declare function useParameterValueHistories(parameterIds: readonly string[], options?: {
+    maxPoints?: number;
+}): readonly (readonly ParameterHistoryPoint[])[];
+/** Numeric readings of one parameter received while the component is mounted, newest last. */
+export declare function useParameterValueHistory(parameterId: string, options?: {
+    maxPoints?: number;
+}): {
+    points: readonly ParameterHistoryPoint[];
+};
+export {};

package/dist/src/workspace/parameters/live/use-stored-history.d.ts

@@ -0,0 +1,85 @@
+import { type ReadingsCadence, type ReadingsCadenceInput, type ReadingsCadenceOutput, type ReadingsCadenceParameter } from "@overvis/hmi-shared/parameter";
+import type { ParameterHistoryPoint } from "./use-history.js";
+export interface StoredHistoryParameter {
+    parameterId: string;
+    /** The parameter's value-type name, such as `num`, `int` or `bool`. */
+    sourceValueType: string;
+}
+export interface StoredHistoryLoad {
+    points: ReadonlyMap<string, readonly ParameterHistoryPoint[]>;
+    /** Parameters whose request failed. */
+    failed: ReadonlySet<string>;
+}
+interface CadenceClient {
+    cadence: {
+        query: (input: ReadingsCadenceInput, opts?: {
+            signal?: AbortSignal;
+        }) => Promise<ReadingsCadenceOutput>;
+    };
+}
+/** Numeric value types are averaged per bucket; flags and labels keep their latest value. */
+export declare function storedHistoryAggregation(sourceValueType: string): ReadingsCadenceParameter["aggregation"];
+/**
+ * Closed `readings.cadence` buckets of `[from, to)` per parameter, at each bucket's start, in
+ * requests of at most 100 parameters. A failed request marks its parameters failed and leaves the
+ * others. Values that are not numbers are left out.
+ */
+export declare function loadStoredParameterHistory(options: {
+    workspaceId: string;
+    readings: CadenceClient;
+    parameters: readonly StoredHistoryParameter[];
+    from: number;
+    to: number;
+    cadence: ReadingsCadence;
+    timeZone: string;
+    signal?: AbortSignal;
+}): Promise<StoredHistoryLoad>;
+export type StoredParameterHistoryStatus = "loading" | "ready" | "empty" | "error";
+export interface StoredParameterSeries {
+    /** `empty` when the historian has no readings in the window. */
+    status: StoredParameterHistoryStatus;
+    /** Closed buckets in time order, at each bucket's start; empty unless `ready`. */
+    points: readonly ParameterHistoryPoint[];
+    /** Whether the parameter's readings are stored; null until its metadata loaded. */
+    recorded: boolean | null;
+}
+export interface UseStoredParameterHistoryOptions {
+    workspaceId: string;
+    parameterIds: readonly string[];
+    /** Length of the window that ends at each load, in milliseconds. */
+    window: number;
+    /** Bucket size; the open bucket at the end of the window is not included. */
+    cadence: ReadingsCadence;
+    /** How often to load again; each load moves the window to the current time. */
+    refetchMs: number;
+    /** Off while hidden: no requests are made. */
+    enabled?: boolean;
+}
+export interface StoredParameterHistory {
+    series: (parameterId: string) => StoredParameterSeries;
+    /** When the shown buckets were loaded; null before the first load. */
+    loadedAt: number | null;
+    retry: () => void;
+}
+/**
+ * One parameter's series from its metadata (undefined `recorded` while it loads) and the latest
+ * load: `error` when either failed, `empty` when the window has no readings.
+ */
+export declare function storedParameterSeries({ parameterId, metadata, load, loadFailed, }: {
+    parameterId: string;
+    metadata: {
+        isError: boolean;
+        recorded: boolean | undefined;
+    } | null;
+    load: StoredHistoryLoad | null;
+    loadFailed: boolean;
+}): StoredParameterSeries;
+/**
+ * Stored readings of parameters from the historian over a window that ends now, as closed buckets
+ * of `cadence`: averages for `num` parameters, latest values for others; values that are not
+ * numbers are left out. Each parameter's value type comes from `parameter.get`; `readings.cadence`
+ * is called in batches of 100 parameters. Unlike `useParameterValueHistory`, it shows readings
+ * from before the page opened. Join live values after the last bucket to reach the current time.
+ */
+export declare function useStoredParameterHistory({ workspaceId, parameterIds, window, cadence, refetchMs, enabled, }: UseStoredParameterHistoryOptions): StoredParameterHistory;
+export {};

package/dist/src/workspace/parameters/live/value-display.d.ts

@@ -0,0 +1,25 @@
+import { type AppLocale } from "@overvis/hmi-shared";
+import type { ComponentProps, ReactElement, ReactNode } from "react";
+import { Badge } from "../../../ui/badge.js";
+import { type ParameterValueSnapshot, type ParameterValueState } from "./model.js";
+type BadgeVariant = NonNullable<ComponentProps<typeof Badge>["variant"]>;
+export declare function ParameterValueDisplay({ state, locale, children, skeletonClassName, unavailable, }: {
+    state: ParameterValueState;
+    locale: AppLocale;
+    children?: (snapshot: ParameterValueSnapshot) => ReactNode;
+    skeletonClassName?: string;
+    unavailable?: ReactNode;
+}): ReactElement;
+/**
+ * A boolean reading as a badge: destructive while true and success while false by default. With
+ * `flag`, a numeric zero or nonzero value counts as false or true too.
+ */
+export declare function ParameterBooleanBadge({ state, trueLabel, falseLabel, trueVariant, falseVariant, flag, }: {
+    state: ParameterValueState;
+    trueLabel: ReactNode;
+    falseLabel: ReactNode;
+    trueVariant?: BadgeVariant;
+    falseVariant?: BadgeVariant;
+    flag?: boolean;
+}): ReactElement;
+export {};

package/dist/src/workspace/parameters/live/value-editor.d.ts

@@ -0,0 +1,24 @@
+import { type AppLocale } from "@overvis/hmi-shared";
+import type { ParameterValueState } from "./model.js";
+import { type ParameterWriteSequenceMessages } from "./write-sequence-dialog.js";
+export interface ParameterValueEditorMessages extends ParameterWriteSequenceMessages {
+    datetimeHint: string;
+    invalidDate: string;
+    current: string;
+    valueHint: string;
+    value: string;
+    datePlaceholder: string;
+    unavailable: string;
+    unknown: string;
+    confirm: string;
+}
+export declare function ParameterValueEditor({ messages, parameterId, label, state, locale, datetime, onClose, onAcknowledged, }: {
+    messages: ParameterValueEditorMessages;
+    parameterId: string;
+    label: string;
+    state: ParameterValueState;
+    locale: AppLocale;
+    datetime: boolean;
+    onClose: () => void;
+    onAcknowledged: () => void;
+}): import("react").JSX.Element;

package/dist/src/workspace/parameters/live/write-review-dialog.d.ts

@@ -0,0 +1,41 @@
+import type { ParameterWriteValueResult, ParameterWriteValuesInput, ParameterWriteValuesOutput } from "@overvis/hmi-shared/parameter";
+import type { ReactElement, ReactNode } from "react";
+export interface ParameterWriteReviewChange<Key extends string = string> {
+    key: Key;
+    label: ReactNode;
+    item: ParameterWriteValuesInput["items"][number];
+    oldValue: ReactNode;
+    newValue: ReactNode;
+}
+export declare function parameterWriteReviewItems<Key extends string>(changes: readonly ParameterWriteReviewChange<Key>[]): ParameterWriteValuesInput["items"];
+export declare function failedParameterWriteReviewChanges<Key extends string>(changes: readonly ParameterWriteReviewChange<Key>[], output: ParameterWriteValuesOutput): ReadonlySet<Key>;
+/**
+ * Each change's write result by key: `ok` or the runtime error. A change the output does not
+ * answer is missing from the map (and counted as failed).
+ */
+export declare function parameterWriteReviewResults<Key extends string>(changes: readonly ParameterWriteReviewChange<Key>[], output: ParameterWriteValuesOutput): ReadonlyMap<Key, ParameterWriteValueResult>;
+export declare function ParameterWriteReviewDialog<Key extends string>({ open, changes, title, description, confirmLabel, pendingLabel, errorMessage, disabled, writeOnlyParameterIds, onOpenChange, onSettled, }: {
+    open: boolean;
+    changes: readonly ParameterWriteReviewChange<Key>[];
+    title: ReactNode;
+    description: ReactNode;
+    confirmLabel: string;
+    pendingLabel?: string;
+    errorMessage: string | (() => string);
+    /**
+     * The changes can no longer be written, for example after access or the device values were
+     * lost while the confirmation was open; a write already sent completes.
+     */
+    disabled?: boolean;
+    /**
+     * Parameters written but not read back afterwards, such as command registers a device cannot
+     * read; watch their effect through separate feedback parameters.
+     */
+    writeOnlyParameterIds?: readonly string[];
+    onOpenChange: (open: boolean) => void;
+    /**
+     * Called after the batch is answered with the keys that did not write and each change's result;
+     * show a result's error with `parameterRuntimeErrorText(result.error)`.
+     */
+    onSettled: (failedChanges: ReadonlySet<Key>, results: ReadonlyMap<Key, ParameterWriteValueResult>) => void;
+}): ReactElement;

package/dist/src/workspace/parameters/live/write-review-form.d.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from "react";
+import { formOnlyError } from "../../../form/index.js";
+/** Shared confirmation form; callers own batch or ordered write execution. */
+export declare function ParameterWriteReviewForm({ open, title, description, children, cancelLabel, confirmLabel, pendingLabel, disabled, cancelDisabled, errorMessage, onOpenChange, submit, onConfirmed, }: {
+    open: boolean;
+    title: ReactNode;
+    description: ReactNode;
+    children: ReactNode;
+    cancelLabel: string;
+    confirmLabel: string;
+    pendingLabel: string;
+    disabled?: boolean;
+    cancelDisabled?: boolean;
+    errorMessage: string | (() => string);
+    onOpenChange: (open: boolean) => void;
+    submit: () => Promise<ReturnType<typeof formOnlyError> | null>;
+    onConfirmed: () => void;
+}): import("react").JSX.Element;

package/dist/src/workspace/parameters/live/write-sequence-dialog.d.ts

@@ -0,0 +1,80 @@
+import { type ReactNode } from "react";
+import { type AppLocale } from "@overvis/hmi-shared";
+import { type ParameterWriteSequenceResult, type ParameterWriteSequenceStep, type ParameterWriteValuesInput } from "@overvis/hmi-shared/parameter";
+export interface ParameterWriteSequenceMessages {
+    description: string;
+    failed: string;
+    step: string;
+    cancel: string;
+    execute: string;
+    pending: string;
+}
+/**
+ * A value the user types in the dialog, such as a device password, written to `parameterId` in a
+ * step before the others. It is shown masked and is dropped when the dialog closes.
+ */
+export interface ParameterWriteSequenceSecret {
+    parameterId: string;
+    label: string;
+    description?: string;
+    maxLength?: number;
+    /** Prefilled value, such as the last password that worked on this page. */
+    initialValue?: string;
+    /** An empty field skips the step instead of being checked by `validate`. */
+    optional?: boolean;
+    /** The message to show instead of running the sequence, or null when the secret can be sent. */
+    validate: (secret: string) => string | null;
+    /** Called with the typed value when the sequence starts; empty when the step was skipped. */
+    onSent?: (secret: string) => void;
+    /** Names the secret's step where a list shows steps by name, such as "Unlock the device". */
+    stepLabel?: string;
+}
+/** The steps to write: the secret's step first unless it is optional and left empty. */
+export declare function withSecretStep(steps: readonly {
+    items: ParameterWriteValuesInput["items"];
+}[], secret: Pick<ParameterWriteSequenceSecret, "parameterId" | "optional"> | undefined, value: string): {
+    items: ParameterWriteValuesInput["items"];
+}[];
+export declare function ParameterWriteSequenceDialog({ messages, title, steps: initialSteps, secret, secretParameterIds, writeOnlyParameterIds, children, locale, disabled, onClose, prepare, onStart, onAcknowledged, onSettled, }: {
+    messages: ParameterWriteSequenceMessages;
+    title: string;
+    /**
+     * Written in order; a step of several items is sent as one request. A function is called when
+     * the dialog opens, for the list, and again when the sequence is sent, such as for a clock that
+     * is set to the time of sending.
+     */
+    steps: readonly ParameterWriteSequenceStep[] | (() => readonly ParameterWriteSequenceStep[]);
+    /** Parameters whose values, such as passwords, are never shown in the list of steps. */
+    secretParameterIds?: readonly string[];
+    /**
+     * Parameters written but not read back afterwards, such as command registers a device cannot
+     * read; their values stay visible in the list. Secrets are never read back either.
+     */
+    writeOnlyParameterIds?: readonly string[];
+    secret?: ParameterWriteSequenceSecret;
+    children?: ReactNode;
+    locale: AppLocale;
+    /**
+     * The device would not act on the sequence now. It cannot be started; one already running
+     * finishes and reports its result.
+     */
+    disabled?: boolean;
+    onClose: () => void;
+    /**
+     * Called after the checks, right before the first write: returning a message stops the sequence
+     * with nothing written and shows the message, such as when a caller could not record what it
+     * must undo.
+     */
+    prepare?: () => string | null;
+    /**
+     * Called once, after the checks and right before the first write is sent, so a caller can
+     * record what it must undo if the sequence is interrupted.
+     */
+    onStart?: () => void;
+    onAcknowledged: () => void;
+    /**
+     * Called once the sequence was sent, with how it ended: the step that stopped it and that step's
+     * per-item results, so a form can mark the fields it did not write.
+     */
+    onSettled?: (result: ParameterWriteSequenceResult) => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,37 @@
+import { type AppLocale } from "@overvis/hmi-shared";
+import type { ParameterValueType, ParameterWithDeviceLog } from "@overvis/hmi-shared/parameter";
+/** What a dashboard shows of a parameter's metadata, in the UI language. */
+export interface ParameterMetadata {
+    id: string;
+    name: string;
+    branchId: string;
+    /** Empty when the parameter has no units. */
+    unit: string;
+    valueType: ParameterValueType;
+    writable: boolean;
+    /** Its readings are stored: see {@link isParameterRecorded}. */
+    recorded: boolean;
+}
+/**
+ * Whether a parameter's readings are stored: it is read in the background, or a device program
+ * logs readings of it that HMI imports.
+ */
+export declare function isParameterRecorded(parameter: Pick<ParameterWithDeviceLog, "backgroundReadingPeriodMs" | "deviceLog">): boolean;
+export type ParameterMetadataState = {
+    status: "loading";
+} | {
+    status: "missing";
+} | {
+    status: "error";
+} | {
+    status: "ready";
+    parameter: ParameterMetadata;
+};
+/** A parameter's metadata in `locale`. */
+export declare function parameterMetadata(parameter: ParameterWithDeviceLog, locale: AppLocale): ParameterMetadata;
+/**
+ * Metadata of the parameters a dashboard shows, from `parameter.get` (cached and batched), so
+ * names, units, value types and zones edited in Setup apply without editing the dashboard. Returns
+ * a lookup by id; an id not in `parameterIds`, or an empty one, stays loading.
+ */
+export declare function useParameterMetadata(parameterIds: readonly string[], locale: AppLocale): (parameterId: string) => ParameterMetadataState;