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

package/dist/src/workspace/alarms/history.d.ts

@@ -0,0 +1,17 @@
+import { type AlarmEventKind, type AlarmLogEvent } from "@overvis/hmi-shared/automation";
+/** The history filters; the alarms page keeps them in its URL. */
+export interface AlarmHistoryFilters {
+    readonly severity?: AlarmLogEvent["severity"];
+    readonly kind?: AlarmEventKind;
+    readonly source?: string;
+    readonly alarm?: string;
+    /** App date-time text, as the range picker edits it. */
+    readonly from?: string;
+    readonly to?: string;
+}
+/** The workspace's alarm log, newest first, as the alarms page's history tab shows it. */
+export declare function AlarmHistory({ workspaceId, filters, onFiltersChange, }: {
+    workspaceId: string;
+    filters: AlarmHistoryFilters;
+    onFiltersChange: (next: AlarmHistoryFilters) => void;
+}): import("react").JSX.Element;

package/dist/src/workspace/alarms/model.d.ts

@@ -0,0 +1,29 @@
+import type { Alarm, AlarmMessage, AlarmSource } from "@overvis/hmi-shared/automation";
+export declare function alarmSourceId(source: AlarmSource): string;
+/** Shelved now: a shelf that is over may stay on the alarm until the runner ends it. */
+export declare function isShelved(alarm: Alarm, now: number): boolean;
+/** Waiting for someone: unacknowledged, active or cleared but latching, and not shelved. */
+export declare function needsAttention(alarm: Alarm, now: number): boolean;
+/** What the navigation badge counts. */
+export declare function attentionCount(alarms: readonly Alarm[], now: number): number;
+/** The alarms the opt-in sound plays for: warning and urgent ones waiting for someone. */
+export declare function soundingAlarms(alarms: readonly Alarm[], now: number): Alarm[];
+/** Unacknowledged first, then the most severe, then the newest. */
+export declare function sortAlarms(alarms: readonly Alarm[], now: number): Alarm[];
+/** Which alarms a list shows; every given filter must match. */
+export interface AlarmFilter {
+    /** Alarm rule or automation ids. */
+    readonly sourceIds?: readonly string[];
+    /** Keys starting with this; an alarm rule raises `alarm` and `unavailable`. */
+    readonly keyPrefix?: string;
+    /** Alarms whose rule or automation reads any of these parameters. */
+    readonly parameterIds?: readonly string[];
+}
+export declare function filterAlarms(alarms: readonly Alarm[], filter: AlarmFilter): Alarm[];
+/** When the next shelf among these ends, so a list can re-sort then; null when none will. */
+export declare function nextShelfEnd(alarms: readonly Alarm[], now: number): number | null;
+/** An alarm's title and body as raised, in the viewer's language, with its values filled in. */
+export declare function alarmMessageText(message: AlarmMessage, locale: string, timeZone: string): {
+    title: string;
+    body: string;
+};

package/dist/src/workspace/alarms/nav.d.ts

@@ -0,0 +1,15 @@
+/** Alarms waiting for someone in the open workspace: unacknowledged and not shelved. */
+export declare function useAlarmAttentionCount(): number;
+/** Whether the open workspace raises alarms, so its navigation offers the alarms page. */
+export declare function useAlarmsConfigured(): boolean;
+/** A count pill for alarms waiting for acknowledgement; names the count for screen readers. */
+export declare function AlarmCountBadge({ count }: {
+    count: number;
+}): import("react").JSX.Element;
+/** The workspace sidebar's link to the alarms page, with the count of alarms waiting. */
+export declare function AlarmsNavLink({ workspaceId, collapsed, onNavigate, className, }: {
+    workspaceId: string;
+    collapsed: boolean;
+    onNavigate?: () => void;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/src/workspace/alarms/page.d.ts

@@ -0,0 +1,10 @@
+import { type AlarmsSearch } from "./search.js";
+/**
+ * The workspace's alarms for every member: the live active alarms, which operators and above
+ * acknowledge and shelve, and the alarm log. The host keeps the tab and filters in the URL.
+ */
+export declare function AlarmsPage({ workspaceId, search, onSearchChange, }: {
+    workspaceId: string;
+    search: AlarmsSearch;
+    onSearchChange: (next: AlarmsSearch) => void;
+}): import("react").JSX.Element;

package/dist/src/workspace/alarms/provider.d.ts

@@ -0,0 +1,30 @@
+import { type ReactNode } from "react";
+import { type Alarm } from "@overvis/hmi-shared/automation";
+/** A workspace's active alarms as the live feed last sent them. */
+export interface WorkspaceAlarms {
+    /** Undefined until the first event arrives. */
+    readonly alarms: readonly Alarm[] | undefined;
+    /** The workspace raises alarms; false until the first event arrives. */
+    readonly configured: boolean;
+    /** The feed failed; it retries on its own. */
+    readonly failed: boolean;
+    /** Re-renders when a shelf ends, so shelved alarms come back without an event. */
+    readonly now: number;
+}
+/**
+ * Holds one `alarm.watch` subscription for the open workspace and serves the badge, the alarms
+ * page, the sound and every alarm list on its dashboards.
+ */
+export declare function WorkspaceAlarmsProvider({ workspaceId, children, }: {
+    workspaceId: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * The live active alarms of `workspaceId`: from the workspace's shared feed when one is open for
+ * it, otherwise from a subscription of its own.
+ */
+export declare function useWorkspaceAlarms(workspaceId: string): WorkspaceAlarms;
+/** The open workspace's shared feed; null outside a workspace. */
+export declare function useOpenWorkspaceAlarms(): (WorkspaceAlarms & {
+    workspaceId: string;
+}) | null;

package/dist/src/workspace/alarms/search.d.ts

@@ -0,0 +1,8 @@
+import type { AlarmHistoryFilters } from "./history.js";
+/** The alarms page URL: the history tab and its filters. Active alarms need no search. */
+export interface AlarmsSearch extends AlarmHistoryFilters {
+    readonly tab?: "history";
+}
+export declare function parseAlarmsSearch(search: Record<string, unknown>): AlarmsSearch;
+/** The history filters among the search, without the tab. */
+export declare function alarmHistoryFilters(search: AlarmsSearch): AlarmHistoryFilters;

package/dist/src/workspace/alarms/sound.d.ts

@@ -0,0 +1,9 @@
+/** Whether this browser plays alarm sounds; off until the user turns it on. */
+export declare function useAlarmSoundEnabled(): [boolean, (enabled: boolean) => void];
+/**
+ * Plays the open workspace's alarm sound when this browser has it turned on, and shows where it
+ * comes from and how to stop it while it plays. Renders nothing otherwise.
+ */
+export declare function AlarmSoundBar(): import("react").JSX.Element | null;
+/** The alarms page's switch for this browser's alarm sound, with what it does. */
+export declare function AlarmSoundToggle(): import("react").JSX.Element;

package/dist/src/workspace/automations/diagnostic-text.d.ts

@@ -0,0 +1,6 @@
+import type { AutomationDiagnostic } from "@overvis/hmi-shared/automation";
+/**
+ * What is wrong with an automation or alarm rule, in the UI language. Formula problems include
+ * the place in the formula; `diagnostic.path` says which field.
+ */
+export declare function automationDiagnosticText(diagnostic: AutomationDiagnostic): string;

package/dist/src/workspace/automations/editor-language.d.ts

@@ -0,0 +1,13 @@
+import { type AutomationDiagnostic, type AutomationEntityKind, type AutomationFix, type AutomationLanguageService, type FormulaScope } from "@overvis/hmi-shared/automation";
+import type { CodeEditorAction } from "../../code-editor/code-editor.js";
+import type { EditorLanguage } from "../../code-editor/language-features.js";
+/** Opens an entity's page in Setup; null for kinds that have none, such as members. */
+export type OpenEntity = ((kind: AutomationEntityKind, id: string) => void) | null;
+/** The editor features of an automation or alarm rule document. */
+export declare function automationEditorLanguage(service: AutomationLanguageService, openEntity: OpenEntity, docsLabel: string): EditorLanguage;
+/** The editor features of one formula field against its scope. */
+export declare function formulaEditorLanguage(scope: FormulaScope, docsLabel: string): EditorLanguage;
+/** A fix as a problem's action, in the UI language. */
+export declare function fixAction(fix: AutomationFix): CodeEditorAction;
+/** Fixes of a problem, as actions. */
+export declare function diagnosticFixActions(service: AutomationLanguageService, text: string, diagnostic: AutomationDiagnostic): CodeEditorAction[];

package/dist/src/workspace/automations/item-descriptions.d.ts

@@ -0,0 +1,3 @@
+import type { AutomationLanguageItemId } from "@overvis/hmi-shared/automation";
+/** One line about a function, operator, kind, field or value of automations, in the UI language. */
+export declare function automationItemDescription(id: AutomationLanguageItemId): string;

package/dist/src/workspace/automations/parameter-names.d.ts

@@ -0,0 +1,2 @@
+/** The workspace's parameter names by id in the UI language; null for an id it does not have. */
+export declare function useParameterNames(workspaceId: string): (id: string) => string | null;

package/dist/src/workspace/automations/run-text.d.ts

@@ -0,0 +1,18 @@
+import { type AutomationRunStep, type AutomationRunValue } from "@overvis/hmi-shared/automation";
+type Detail = Readonly<Record<string, unknown>>;
+/** A value of a run in the UI: unknown, a time, or the value as formulas write it. */
+export declare function runValueText(value: AutomationRunValue | undefined): string;
+/** What started a run, with its details. */
+export declare function runTriggerText(kind: string, trigger: Detail): string;
+/** Why a run failed, or the runner did not run it. */
+export declare function runErrorText(code: string, error: Detail | null): string;
+/** The kind of a step, as a short label. */
+export declare function stepKindText(kind: string): string;
+/**
+ * What a step did, in the UI language. `parameterName` names a parameter by id, `null` when it is
+ * not in the workspace.
+ */
+export declare function stepDetailText(step: AutomationRunStep, parameterName: (id: string) => string | null): string;
+/** A severity of alarms and notifications, as a short label. */
+export declare function severityText(severity: string): string;
+export {};

package/dist/src/workspace/automations/trace-view.d.ts

@@ -0,0 +1,24 @@
+import { type AutomationRunStep, type AutomationRunValue } from "@overvis/hmi-shared/automation";
+/** Names of a document's procedures by index, for step locations. */
+export declare function procedureNames(document: unknown): readonly string[];
+/** Values by variable name, as a run started with them or left them. */
+export declare function RunValues({ values, empty, }: {
+    values: Readonly<Record<string, AutomationRunValue>>;
+    /** Shown when there are none. */
+    empty: string;
+}): import("react").JSX.Element;
+/**
+ * Steps of a run in order. A step's location opens it in the editor when `onReveal` is given.
+ */
+export declare function RunSteps({ steps, procedures, parameterName, onReveal, }: {
+    steps: readonly AutomationRunStep[];
+    procedures: readonly string[];
+    parameterName: (id: string) => string | null;
+    onReveal?: (path: string) => void;
+}): import("react").JSX.Element;
+/** What a dry run would have done, in step order. */
+export declare function RunEffects({ effects, parameterName, empty, }: {
+    effects: readonly AutomationRunStep[];
+    parameterName: (id: string) => string | null;
+    empty: string;
+}): import("react").JSX.Element;

package/dist/src/workspace/automations/use-catalog.d.ts

@@ -0,0 +1,10 @@
+import { type AutomationCatalog } from "@overvis/hmi-shared/automation";
+import type { OpenEntity } from "./editor-language.js";
+/**
+ * The names of a workspace's parameters, endpoints, alarm rules, automations and members, for the
+ * automation editor's completion, hovers and name hints. Empty until they load; a part that fails
+ * to load stays empty.
+ */
+export declare function useAutomationCatalog(workspaceId: string): AutomationCatalog;
+/** Opens an entity's Setup page in a new tab, so the document being edited stays as it is. */
+export declare function useOpenEntityInSetup(workspaceId: string): OpenEntity;

package/dist/src/workspace/caches.d.ts

@@ -0,0 +1,41 @@
+import type { QueryClient } from "@tanstack/react-query";
+import type { trpc } from "../trpc.js";
+/** The tRPC utilities of the host's React client (`trpc.useUtils()`). */
+export type WorkspaceCacheUtils = ReturnType<typeof trpc.useUtils>;
+/**
+ * What changed. `workspace` is the workspace itself (name, suspension, the caller's access);
+ * `workspaceList` is which workspaces the user has, for creating, deleting or leaving one without
+ * refetching the gone workspace. `checkpoint` is a setup checkpoint, which activity history also
+ * shows. `setup` stands for everything the workspace setup revision covers: endpoints,
+ * parameters, dashboards and drawings, automations and alarm rules, reports and comments, files,
+ * branding and templates, and so the checkpoints taken around changes and their summaries.
+ * `automation` covers alarm rules and the workspace's automation limits too. `storage` is stored-data
+ * usage and retention.
+ */
+export type WorkspaceCacheEntity = "workspace" | "workspaceList" | "member" | "cliKey" | "checkpoint" | "branding" | "file" | "endpoint" | "edgeProgram" | "automation" | "parameter" | "dashboard" | "report" | "reportComment" | "storage" | "setup";
+export interface WorkspaceCacheChange {
+    readonly entity: WorkspaceCacheEntity;
+    /** The workspace it changed in. Omitted when unknown: the entity refreshes in every workspace. */
+    readonly workspaceId?: string;
+    /** The changed row: `get` queries of other rows of the entity stay fresh. */
+    readonly id?: string;
+}
+/**
+ * Marks every cached query `change` makes stale; open pages refetch them. Mutations, the live
+ * workspace feed and API calls made on the user's behalf all refresh caches through this table.
+ */
+export declare function invalidateWorkspaceCaches(utils: WorkspaceCacheUtils, change: WorkspaceCacheChange): Promise<void>;
+/** The entity a successful call of procedure `path` (e.g. `endpoint.update`) changes, if any. */
+export declare function workspaceCacheEntityForApiPath(path: string): WorkspaceCacheEntity | null;
+/**
+ * Refreshes what a successful call the assistant made without a confirmation card changed, where
+ * nothing else would: open pages follow setup changes through the live workspace feed, but a
+ * checkpoint changes no setup revision.
+ */
+export declare function invalidateAfterDirectApiCall(utils: WorkspaceCacheUtils, path: string): Promise<void>;
+/**
+ * Refreshes what a successful call of procedure `path` changed, for callers that run API calls
+ * on the user's behalf. Setup-wide changes also reload open dashboards, whose code may have
+ * changed with them.
+ */
+export declare function invalidateAfterApiCall(utils: WorkspaceCacheUtils, queryClient: QueryClient, path: string): Promise<void>;

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

@@ -0,0 +1,71 @@
+import { type ReactNode } from "react";
+import type { EndpointMintDeviceUiTicketInput, EndpointMintDeviceUiTicketOutput } from "@overvis/hmi-shared/endpoint";
+import { type WorkspaceGetOutput } from "@overvis/hmi-shared/workspace";
+export type WorkspaceHostMode = "cloud" | "local";
+/** What the host adds at the foot of the workspace navigation, above the Setup menu. */
+export type RenderNavFooter = (input: {
+    workspaceId: string;
+    /** The navigation is narrowed to icons. */
+    collapsed: boolean;
+    /** Closes the mobile navigation after a link is followed. */
+    onNavigate?: () => void;
+}) => ReactNode;
+/** Mints a short-lived ticket that opens a VPN endpoint's device web UI through the proxy. */
+export type MintDeviceUiTicket = (input: EndpointMintDeviceUiTicketInput) => Promise<EndpointMintDeviceUiTicketOutput>;
+interface WorkspaceHostContextValue {
+    mode: WorkspaceHostMode;
+    /**
+     * The signed-in user. Separates preferences kept in this browser, such as favorite symbols, so
+     * they do not leak between users; without it they last for the page only.
+     */
+    userId?: string;
+    onWorkspaceLoaded?: (workspaceId: string) => void;
+    /**
+     * Open a host-provided assistant panel when available; with `draft`, in a new chat with that
+     * message written for the user to send.
+     */
+    openAssistant?: (draft?: string) => void;
+    /** Resolve a dashboard module URL for the current host. */
+    getDashboardEntrypointUrl: (dashboardId: string) => string;
+    /**
+     * Origin for authenticated HTTP (uploads). Empty string = same-origin relative
+     * URLs. Local hosts pass the API origin used for tRPC.
+     */
+    apiBaseUrl: string;
+    credentials: RequestCredentials;
+    getHeaders?: () => HeadersInit;
+    /** Device web UI access; the Device UI tab is hidden when the host does not offer it. */
+    mintDeviceUiTicket?: MintDeviceUiTicket;
+    /** Host content at the foot of the workspace navigation; nothing when absent. */
+    renderNavFooter?: RenderNavFooter;
+    /**
+     * What the host offers on the page of a workspace suspended for balance, such as its billing
+     * account's balance and a way to top it up.
+     */
+    renderSuspendedBilling?: (workspace: WorkspaceGetOutput) => ReactNode;
+}
+export declare function useWorkspaceHost(): WorkspaceHostContextValue;
+export declare function useOptionalWorkspace(): WorkspaceGetOutput | null;
+export declare function useWorkspace(): WorkspaceGetOutput;
+/** Whether links into Setup may show: only inside a workspace the user may set up. */
+export declare function useCanOpenSetup(): boolean;
+/** The loaded workspace for everything below; `WorkspaceLayout` provides it. */
+export declare function WorkspaceProvider({ workspace, children, }: {
+    workspace: WorkspaceGetOutput;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function WorkspaceHostProvider({ children, mode, userId, onWorkspaceLoaded, openAssistant, getDashboardEntrypointUrl, apiBaseUrl, credentials, getHeaders, mintDeviceUiTicket, renderNavFooter, renderSuspendedBilling, }: {
+    children: ReactNode;
+    mode?: WorkspaceHostMode;
+    userId?: string;
+    onWorkspaceLoaded?: (workspaceId: string) => void;
+    openAssistant?: (draft?: string) => void;
+    getDashboardEntrypointUrl?: (dashboardId: string) => string;
+    apiBaseUrl?: string;
+    credentials?: RequestCredentials;
+    getHeaders?: () => HeadersInit;
+    mintDeviceUiTicket?: MintDeviceUiTicket;
+    renderNavFooter?: RenderNavFooter;
+    renderSuspendedBilling?: (workspace: WorkspaceGetOutput) => ReactNode;
+}): import("react").JSX.Element;
+export {};

package/dist/src/workspace/copyable-id.d.ts

@@ -0,0 +1,4 @@
+/** Quiet copy-id chip: uuid and copy icon sit together, not stretched across the header. */
+export declare function CopyableId({ id }: {
+    id: string;
+}): import("react").JSX.Element;

package/dist/src/workspace/dashboards/actions-menu.d.ts

@@ -0,0 +1,4 @@
+import type { Dashboard } from "@overvis/hmi-shared/dashboard";
+export declare function DashboardActionsMenu({ dashboard }: {
+    dashboard: Dashboard;
+}): import("react").JSX.Element | null;

package/dist/src/workspace/dashboards/anchor-scroll.d.ts

@@ -0,0 +1,11 @@
+import { type RefObject } from "react";
+/**
+ * Scrolls to the element whose id is `anchor` and keeps it at the top while `container` changes
+ * size, such as while a drawing and live readings above it load, until the page settles after
+ * `settleMs` or the user scrolls, types or taps. Null scrolls nowhere. A new `anchor` or `key`
+ * (such as another site on the same page) starts again.
+ */
+export declare function useAnchorScroll(container: RefObject<HTMLElement | null>, anchor: string | null, { key, settleMs }?: {
+    key?: string;
+    settleMs?: number;
+}): void;

package/dist/src/workspace/dashboards/bindings.d.ts

@@ -0,0 +1,26 @@
+import type { TObject } from "typebox";
+export interface DashboardBindingRequirement {
+    path: string;
+    bindings: Readonly<Record<string, string | undefined>> | undefined;
+    requiredFields: readonly string[];
+}
+export interface MissingDashboardBindingGroup {
+    path: string;
+    fields: readonly string[];
+}
+/** Report incomplete semantic parameter-binding groups for a public dashboard template. */
+export declare function missingDashboardBindings(requirements: readonly DashboardBindingRequirement[]): MissingDashboardBindingGroup[];
+/** A configuration's `parameters`: binding groups by name, each binding a parameter id. */
+export type DashboardBindingGroups = Readonly<Record<string, Readonly<Record<string, string | undefined>> | undefined>>;
+/** Field names of a binding group's schema, in declaration order. */
+export declare function dashboardBindingFields(group: TObject): string[];
+/**
+ * Incomplete groups among `groups`, the schemas of a template's binding groups by name, when
+ * every field of each is required. `parameters` is the configuration's own.
+ */
+export declare function missingDashboardBindingGroups(groups: Readonly<Record<string, TObject>>, parameters: DashboardBindingGroups | undefined): MissingDashboardBindingGroup[];
+/**
+ * An example configuration's `parameters`: every field of `groups` bound to a distinct
+ * placeholder id, numbered in declaration order from 1.
+ */
+export declare function exampleDashboardBindings(groups: Readonly<Record<string, TObject>>): Record<string, Record<string, string>>;

package/dist/src/workspace/dashboards/configuration-rename-dialog.d.ts

@@ -0,0 +1,10 @@
+import type { Static, TSchema } from "typebox";
+export declare function DashboardConfigurationRenameDialog<T extends TSchema>({ dashboardId, workspaceId, schema: configurationSchema, transform, currentName, nameMaxLength, onClose, }: {
+    dashboardId: string;
+    workspaceId: string;
+    schema: T;
+    transform: (configuration: Static<T>, name: string) => Static<T>;
+    currentName: string;
+    nameMaxLength: number;
+    onClose: () => void;
+}): import("react").JSX.Element;

package/dist/src/workspace/dashboards/configuration-required.d.ts

@@ -0,0 +1,10 @@
+import { type ReactElement, type ReactNode } from "react";
+import type { MissingDashboardBindingGroup } from "./bindings.js";
+export declare function DashboardConfigurationRequired({ workspaceId, dashboardId, title, description, missing, exampleConfiguration, }: {
+    workspaceId: string;
+    dashboardId: string;
+    title: ReactNode;
+    description: ReactNode;
+    missing: readonly MissingDashboardBindingGroup[];
+    exampleConfiguration: Record<string, unknown>;
+}): ReactElement;

package/dist/src/workspace/dashboards/configuration-update-queue.d.ts

@@ -0,0 +1,2 @@
+/** Run dashboard configuration writes one at a time so overlapping patches cannot clobber. */
+export declare function enqueueDashboardConfigurationUpdate(dashboardId: string, run: () => Promise<void>): Promise<void>;

package/dist/src/workspace/dashboards/copy-dialog.d.ts

@@ -0,0 +1,7 @@
+import { type DashboardListItem } from "@overvis/hmi-shared/dashboard";
+/** Mount when opened so each copy starts with the current localized name. */
+export declare function DashboardCopyDialog({ workspaceId, dashboard, onClose, }: {
+    workspaceId: string;
+    dashboard: Pick<DashboardListItem, "id" | "name">;
+    onClose: () => void;
+}): import("react").JSX.Element;

package/dist/src/workspace/dashboards/document/blocks.d.ts

@@ -0,0 +1,42 @@
+import { type AppLocale, type LocalizedString } from "@overvis/hmi-shared";
+import { type DocumentAnalysis, type DocumentBlock, type DocumentDensity, type DocumentEnvironment, type DocumentReadings, type DocumentTile, type DocumentValues } from "@overvis/hmi-shared/document";
+import { type ExpressionValue, type ExpressionValueType } from "@overvis/hmi-shared/expression";
+import { type TileContext } from "./tiles/context.js";
+/** Everything the blocks of a page read. */
+export interface DocumentRenderContext {
+    analysis: DocumentAnalysis;
+    values: DocumentValues;
+    readings: DocumentReadings;
+    environment: DocumentEnvironment;
+    locale: AppLocale;
+    workspaceId: string;
+    dashboardId: string;
+    inputs: Readonly<Record<string, ExpressionValue>>;
+    setInput: (name: string, value: ExpressionValue) => void;
+    tiles: TileContext;
+    density: DocumentDensity;
+    /** Opens a quick report of parameters; null while one is being made. */
+    report: ((parameterIds: readonly string[], title: string) => void) | null;
+}
+/** Names a repeated row sees, with their types. */
+interface RowScope {
+    values: DocumentValues;
+    types: ReadonlyMap<string, ExpressionValueType>;
+}
+/** A text in the UI language with its `{name}` placeholders replaced by their values. */
+export declare function documentText(context: DocumentRenderContext, value: LocalizedString, row?: RowScope, escape?: (text: string) => string): string;
+/** Numeric parameters of tiles, for a row's quick report. */
+export declare function reportParameterIds(tiles: readonly DocumentTile[], context: DocumentRenderContext): string[];
+/** One block of a document; `pointer` is its JSON pointer in the document. */
+export declare function DocumentBlockView({ block, pointer, context, }: {
+    block: DocumentBlock;
+    pointer: string;
+    context: DocumentRenderContext;
+}): import("react").JSX.Element;
+/** The report button of a titled row with tiles; a quick report takes up to 20 parameters. */
+export declare function RowReportButton({ parameterIds, title, context, }: {
+    parameterIds: readonly string[];
+    title: string;
+    context: DocumentRenderContext;
+}): import("react").JSX.Element | null;
+export {};

package/dist/src/workspace/dashboards/document/chart-data.d.ts

@@ -0,0 +1,13 @@
+import Type, { type Static } from "typebox";
+/** Missing keys and null values are gaps, never zero readings. */
+export declare const DocumentChartDataType: Type.TObject<{
+    rows: Type.TArray<Type.TObject<{
+        label: Type.TString;
+        values: Type.TRecord<"^.*$", Type.TUnion<[Type.TNumber, Type.TNull]>>;
+    }>>;
+    series: Type.TArray<Type.TObject<{
+        key: Type.TString;
+        label: Type.TString;
+    }>>;
+}>;
+export type DocumentChartData = Static<typeof DocumentChartDataType>;

package/dist/src/workspace/dashboards/document/chart.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+import type { DocumentChartData } from "./chart-data.js";
+/** Category labels are supplied by the author, including formatting any timestamps. */
+export declare function DocumentChart({ data, kind, label, formatValue, empty, }: {
+    data: DocumentChartData;
+    kind: "bar" | "line";
+    label: string;
+    formatValue: (value: number) => string;
+    empty: ReactNode;
+}): import("react").JSX.Element;

package/dist/src/workspace/dashboards/document/layout.d.ts

@@ -0,0 +1,29 @@
+import { type ComponentProps, type ReactNode } from "react";
+import { Table } from "../../../ui/table.js";
+/** A flowing document inside the dashboard host, which supplies the page title. Bare text
+ * inherits the prose size so unstyled elements match the surrounding document. */
+export declare function DashboardDocument({ className, ...props }: ComponentProps<"article">): import("react").JSX.Element;
+/** Use a conclusion here; the dashboard host already displays the catalog title. */
+export declare function DocumentLead({ title, context, children, className, ...props }: Omit<ComponentProps<"header">, "title"> & {
+    title: ReactNode;
+    context?: ReactNode;
+}): import("react").JSX.Element;
+export declare function DocumentSection({ title, children, className, ...props }: Omit<ComponentProps<"section">, "title"> & {
+    title: ReactNode;
+}): import("react").JSX.Element;
+/** Equal columns stack according to available document width, not the browser width. */
+export declare function DocumentColumns({ columns, className, ...props }: ComponentProps<"div"> & {
+    columns?: 2 | 3;
+}): import("react").JSX.Element;
+/** Rich text is authored as React elements; this component does not parse Markdown or HTML. */
+export declare function DocumentProse({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
+export declare function DocumentMetric({ label, value, detail, className, ...props }: ComponentProps<"dl"> & {
+    label: ReactNode;
+    value: ReactNode;
+    detail?: ReactNode;
+}): import("react").JSX.Element;
+export declare function DocumentFigure({ caption, children, className, ...props }: ComponentProps<"figure"> & {
+    caption: ReactNode;
+}): import("react").JSX.Element;
+/** Descriptions go in the first column; remaining columns retain the table's compact values. */
+export declare function DocumentTable({ className, ...props }: ComponentProps<typeof Table>): import("react").JSX.Element;

package/dist/src/workspace/dashboards/document/markdown.d.ts

@@ -0,0 +1,7 @@
+/** A value to place into Markdown as literal text. */
+export declare function escapeMarkdown(value: string): string;
+/** Document Markdown in the document's prose style; raw HTML shows as text. */
+export declare function DocumentMarkdown({ text, className }: {
+    text: string;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/src/workspace/dashboards/document/sources.d.ts

@@ -0,0 +1,32 @@
+import { type ReactNode } from "react";
+import { type AppLocale } from "@overvis/hmi-shared";
+import { type DocumentAnalysis, type DocumentEnvironment, type DocumentReadings, type DocumentValues } from "@overvis/hmi-shared/document";
+import { type ExpressionValue } from "@overvis/hmi-shared/expression";
+import type { ExpressionValueType } from "@overvis/hmi-shared/expression";
+import type { ParameterValueState } from "../../parameters/live/model.js";
+import type { ParameterMetadataState } from "../../parameters/metadata.js";
+/**
+ * A live value as a formula sees it, by the parameter's formula type, as automations read it:
+ * numbers from their text where the reading has no number, such as a big integer. Text is in the
+ * viewer's language. Unknown without a value.
+ */
+export declare function liveExpressionValue(state: ParameterValueState | undefined, type: ExpressionValueType | undefined, locale: AppLocale): ExpressionValue;
+/**
+ * Reads a document's sources and evaluates its values: live values from `states`, history
+ * aggregates and API procedures through queries, device operations through device reads. A
+ * source whose input formulas are not known yet is not read. `readers` renders the device reads.
+ */
+export declare function useDocumentValues({ analysis, workspaceId, dashboardId, locale, inputs, states, parameter, environment, }: {
+    analysis: DocumentAnalysis;
+    workspaceId: string;
+    dashboardId: string;
+    locale: AppLocale;
+    inputs: Readonly<Record<string, ExpressionValue>>;
+    states: ReadonlyMap<string, ParameterValueState>;
+    parameter: (parameterId: string) => ParameterMetadataState;
+    environment: DocumentEnvironment;
+}): {
+    values: DocumentValues;
+    readings: DocumentReadings;
+    readers: ReactNode;
+};

package/dist/src/workspace/dashboards/document/tiles/chart.d.ts

@@ -0,0 +1,23 @@
+import type { AppLocale } from "@overvis/hmi-shared";
+import { type DocumentChartTile, type DocumentHistoryWindow } from "@overvis/hmi-shared/document";
+import type { StoredParameterSeries } from "../../../parameters/live/use-stored-history.js";
+import type { ParameterMetadataState } from "../../../parameters/metadata.js";
+import type { TileContext } from "./context.js";
+/**
+ * Stored history of one to four parameters in one unit over a window, with the values read
+ * since the page opened at the end of each line; its loading, empty and failed states.
+ */
+export declare function ParameterHistoryTrend({ parameterIds, window: windowKey, unit, label, locale, parameter, history, }: {
+    parameterIds: readonly string[];
+    window: DocumentHistoryWindow;
+    unit: string;
+    label: string;
+    locale: AppLocale;
+    parameter: (parameterId: string) => ParameterMetadataState;
+    history: (window: DocumentHistoryWindow, parameterId: string) => StoredParameterSeries;
+}): import("react").JSX.Element;
+/** One to four parameters in one unit over 1 h, 24 h or 7 d from the historian. */
+export declare function ChartTileView({ tile, context, }: {
+    tile: DocumentChartTile;
+    context: TileContext;
+}): import("react").JSX.Element;

package/dist/src/workspace/dashboards/document/tiles/context.d.ts

@@ -0,0 +1,23 @@
+import type { AppLocale } from "@overvis/hmi-shared";
+import type { DocumentHistoryWindow, DocumentTile } from "@overvis/hmi-shared/document";
+import type { ParameterValueState } from "../../../parameters/live/model.js";
+import type { StoredParameterSeries } from "../../../parameters/live/use-stored-history.js";
+import type { ParameterMetadataState } from "../../../parameters/metadata.js";
+import type { ParameterValueEditorMessages } from "../../../parameters/live/value-editor.js";
+import type { ToneMemory } from "./tones.js";
+/** What every tile of a page reads: live values, metadata, stored history and the page's mode. */
+export interface TileContext {
+    locale: AppLocale;
+    workspaceId: string;
+    states: ReadonlyMap<string, ParameterValueState>;
+    parameter: (parameterId: string) => ParameterMetadataState;
+    history: (window: DocumentHistoryWindow, parameterId: string) => StoredParameterSeries;
+    /** Operators and above may write values and run commands. */
+    canWriteValues: boolean;
+    messages: ParameterValueEditorMessages;
+    /** Opens a chart tile's report; null when there is none to open. */
+    onOpen: ((tile: DocumentTile, name: string) => void) | null;
+    /** The document's memory of its tiles' last tones, so stale tiles keep theirs across pages. */
+    tones: ToneMemory;
+}
+export declare function stateOf(states: ReadonlyMap<string, ParameterValueState>, parameterId: string): ParameterValueState;