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

package/dist/src/workspace/fleet/group-command-dialogs.d.ts

@@ -0,0 +1,43 @@
+import type { ParameterWriteValueResult } from "@overvis/hmi-shared/parameter";
+import type { ParameterWriteOutcome } from "../parameters/live/model.js";
+import { type SiteGroupCommand, type SiteGroupTarget } from "./group-command.js";
+/**
+ * Confirmation of a group command: one row per write (per site, or per shared group register)
+ * with the sites' state when the list was built (`currentText`) and the `target` they get, the
+ * automatic-mode warnings, and every site left out with its reason. Confirming sends one batch.
+ * While `outdated`, live feedback changed who would be written or the warnings: confirming is
+ * disabled until `onRefresh` rebuilds the list.
+ */
+export declare function SiteGroupCommandConfirmation<Site extends {
+    id: string;
+    name: string;
+}>({ write, title, confirmLabel, target, currentText, canWrite, outdated, onRefresh, onClose, onSettled, }: {
+    write: SiteGroupCommand<Site>;
+    title: string;
+    confirmLabel: string;
+    target: string;
+    currentText: (target: SiteGroupTarget<Site>) => string;
+    canWrite: boolean;
+    outdated: boolean;
+    onRefresh: () => void;
+    onClose: () => void;
+    onSettled: (results: ReadonlyMap<string, ParameterWriteValueResult>) => void;
+}): import("react").JSX.Element;
+/**
+ * The result of the last group command per site, with the error of a failed write and the site's
+ * live state now (`liveText`), until dismissed. **Select failed** puts failed and unanswered
+ * sites back into the selection; nothing is retried automatically.
+ */
+export declare function SiteGroupCommandResults<Site extends {
+    id: string;
+    name: string;
+}>({ action, rows, liveText, onSelectFailed, onDismiss, }: {
+    action: string;
+    rows: readonly {
+        site: Site;
+        outcome: ParameterWriteOutcome;
+    }[];
+    liveText: (site: Site) => string;
+    onSelectFailed: () => void;
+    onDismiss: () => void;
+}): import("react").JSX.Element;

package/dist/src/workspace/fleet/group-command.d.ts

@@ -0,0 +1,83 @@
+import type { ParameterWriteValueResult, ParameterWriteValuesInput } from "@overvis/hmi-shared/parameter";
+import { type ParameterWriteOutcome } from "../parameters/live/model.js";
+import type { SiteCommand } from "./command-entry.js";
+import type { SiteControlMode, SiteLocalControl } from "./control-mode.js";
+import type { SiteState } from "./status.js";
+/** Most sites one confirmed group command may write. */
+export declare const siteGroupCommandLimit = 100;
+/**
+ * Why a selected site is left out: no command for the action, a command of several steps
+ * (operated from the site's page), local control at the site, or a command parameter that
+ * another selected site writes with a different value.
+ */
+export type SiteGroupExclusion = "no-command" | "several-steps" | "local" | "conflict";
+type WriteItem = ParameterWriteValuesInput["items"][number];
+/** A selected site the batch reaches, with its state when the list was built. */
+export interface SiteGroupTarget<Site> {
+    site: Site;
+    /** Key of the batch item that writes it; sites sharing a group register share one. */
+    key: string;
+    state: SiteState;
+    mode: SiteControlMode | null;
+    /** No current feedback: the site is still attempted and its result shown. */
+    noData: boolean;
+}
+export interface SiteGroupCommand<Site, Action extends string = string> {
+    action: Action;
+    targets: SiteGroupTarget<Site>[];
+    /** One write per distinct parameter, in selection order; its result applies to each site. */
+    items: {
+        key: string;
+        item: WriteItem;
+        sites: Site[];
+    }[];
+    excluded: {
+        site: Site;
+        reason: SiteGroupExclusion;
+    }[];
+    /** Included sites in automatic mode, whose controller may switch them back. */
+    automatic: number;
+    /** Included sites whose mode is unknown. */
+    unknownMode: number;
+    /** More included sites than one batch may write. */
+    overLimit: boolean;
+}
+/**
+ * The write list of a group command: each selected site whose command for the action is a single
+ * write, except while its local selector is on. Identical parameter/value pairs from several
+ * sites (a shared group register) become one item; a parameter written with different values by
+ * several sites leaves all of them out. `switching` counts sites in automatic or unknown mode,
+ * whose controllers may switch them back; leave it off for an action that hands control back.
+ */
+export declare function buildSiteGroupCommand<Site extends {
+    id: string;
+}, Action extends string>(input: {
+    sites: readonly Site[];
+    action: Action;
+    command: (site: Site) => SiteCommand | undefined;
+    localControl: (site: Site) => SiteLocalControl;
+    stateOf: (site: Site) => SiteState;
+    modeOf: (site: Site) => SiteControlMode | null;
+    switching: boolean;
+}): SiteGroupCommand<Site, Action>;
+/**
+ * Whether two write lists for the same selection would send the same writes with the same
+ * warnings, so a confirmation built from one still describes the other. Changes in data notes
+ * alone do not count.
+ */
+export declare function sameSiteGroupCommand<Site extends {
+    id: string;
+}>(a: SiteGroupCommand<Site>, b: SiteGroupCommand<Site>): boolean;
+/** One result per site of the batch, in the order of the confirmation. */
+export declare function siteGroupCommandResults<Site>(write: SiteGroupCommand<Site>, results: ReadonlyMap<string, ParameterWriteValueResult>): {
+    site: Site;
+    outcome: ParameterWriteOutcome;
+}[];
+/** Sites to select again for a deliberate second attempt: failed and unanswered ones. */
+export declare function siteGroupRetrySelection(results: readonly {
+    site: {
+        id: string;
+    };
+    outcome: ParameterWriteOutcome;
+}[]): Set<string>;
+export {};

package/dist/src/workspace/fleet/indicator-lights.d.ts

@@ -0,0 +1,23 @@
+import type { LucideIcon } from "lucide-react";
+/** A light's state: lit, dark, or dark because its value is not known. */
+export type SiteLightState = "on" | "off" | "unknown";
+export interface SiteLight {
+    key: string;
+    icon: LucideIcon;
+    label: string;
+    state: SiteLightState;
+    /** Shown on hover after the label, such as `1/2` or `Open`; defaults to the state. */
+    detail?: string;
+    /** Lit from a value kept from an earlier read. */
+    stale?: boolean;
+    /** Colour while on: `info` (cooling, running), `success`, `attention` (defrost, open door), `danger`. */
+    tone: "neutral" | "info" | "success" | "attention" | "danger";
+}
+/**
+ * A row of indicator lights in a fixed order, like a controller's front panel: every light keeps
+ * its place, dim while off or unknown and coloured while on, so the row reads by position and
+ * never shifts. Hovering a light names it with its state.
+ */
+export declare function SiteIndicatorLights({ lights }: {
+    lights: readonly SiteLight[];
+}): import("react").JSX.Element;

package/dist/src/workspace/fleet/map.d.ts

@@ -0,0 +1,41 @@
+import type { ReactNode } from "react";
+import type { AppLocale } from "@overvis/hmi-shared";
+import { type DashboardTheme, type FleetBoard, type SitePosition } from "@overvis/hmi-shared/dashboard";
+import { type DashboardNavigation } from "../dashboards/navigation.js";
+import type { ParameterValueState } from "../parameters/live/model.js";
+import type { FleetSite } from "./overview.js";
+import { type SiteState } from "./status.js";
+import { type SiteStatusLabels } from "./status-badge.js";
+export interface FleetMapSite extends FleetSite {
+    position?: SitePosition;
+}
+/**
+ * Sites on a clustered map with status-coloured markers and a legend of the states shown. Geo
+ * parameter positions move with their live value; a stale one keeps its last known place with a
+ * faded marker. Each popup shows the status, summary readings and a link to the site page.
+ */
+export declare function FleetMap<Site extends FleetMapSite>({ sites, stateOf, states, board, navigation, sitePath, workspaceId, dashboardId, theme, locale, icon, subtitle, statusLabels, activityCount, openLabel, unavailable, empty, clusterLabel, details, }: {
+    sites: readonly Site[];
+    stateOf: (site: Site) => SiteState;
+    /** Live states, including the geo parameters listed by `sitePositionParameterIds`. */
+    states: ReadonlyMap<string, ParameterValueState>;
+    board: Pick<FleetBoard, "columns">;
+    navigation: DashboardNavigation;
+    sitePath: (site: Site) => string;
+    workspaceId: string;
+    dashboardId: string;
+    theme: DashboardTheme;
+    locale: AppLocale;
+    /** Icon in a popup header, such as the site kind. */
+    icon?: (site: Site) => ReactNode;
+    subtitle?: (site: Site) => ReactNode;
+    statusLabels?: SiteStatusLabels;
+    activityCount?: (count: number | "?", total: number) => string;
+    openLabel?: string;
+    unavailable?: string;
+    empty?: string;
+    /** Accessible cluster name; `status` is the label of the most urgent tone. */
+    clusterLabel?: (count: number, status: string) => string;
+    /** Preset content in a popup after the readings, such as period totals. */
+    details?: (site: Site) => ReactNode;
+}): import("react").JSX.Element;

package/dist/src/workspace/fleet/mode-badge.d.ts

@@ -0,0 +1,7 @@
+import type { SiteControlMode } from "./control-mode.js";
+/** Control mode labels: Automatic, Manual, Local, Mode unknown. */
+export declare function useSiteControlModeLabel(): (mode: SiteControlMode) => string;
+/** Who controls the site, beside its status; Local stands out. Nothing without a mode. */
+export declare function SiteModeBadge({ mode }: {
+    mode: SiteControlMode | null;
+}): import("react").JSX.Element | null;

package/dist/src/workspace/fleet/operations.d.ts

@@ -0,0 +1,23 @@
+import type { AppLocale } from "@overvis/hmi-shared";
+import type { SiteEquipment } from "@overvis/hmi-shared/dashboard";
+import type { ParameterValueState } from "../parameters/live/model.js";
+import type { SiteDueDate } from "./status.js";
+/**
+ * Controls grouped by purpose (setpoints, modes, start/stop, other), the maintenance due date and
+ * a history action for a site (`site`, framed with a heading) or one piece of equipment.
+ */
+export declare function EquipmentOperations({ equipment, history, states, locale, variant, dueDate, }: {
+    equipment: Pick<SiteEquipment, "controls" | "maintenanceParameterId">;
+    /** Opens a quick report with unique IDs; null or empty IDs hide the action. */
+    history: {
+        /** Omitted by older dashboard bundles; pass IDs to enable the report limit check. */
+        parameterIds?: readonly string[];
+        open: (parameterIds: string[]) => void;
+        pending: boolean;
+    } | null;
+    variant: "site" | "equipment";
+    states: ReadonlyMap<string, ParameterValueState>;
+    locale: AppLocale;
+    /** Labels the due date as maintenance (default) or verification. */
+    dueDate?: SiteDueDate;
+}): import("react").JSX.Element | null;

package/dist/src/workspace/fleet/order-editor.d.ts

@@ -0,0 +1,13 @@
+import { type FormValidationErrorResult } from "../../form/index.js";
+/** Reorders a list of named items; `onSave` receives the IDs in their new order. */
+export declare function FleetOrderEditor({ title, description, items, onSave, onClose, mapError, }: {
+    title: string;
+    description?: string;
+    items: readonly {
+        id: string;
+        name: string;
+    }[];
+    onSave: (order: string[]) => Promise<void>;
+    onClose: () => void;
+    mapError?: (error: unknown) => FormValidationErrorResult;
+}): import("react").JSX.Element;

package/dist/src/workspace/fleet/overview-model.d.ts

@@ -0,0 +1,43 @@
+import type { ReactNode } from "react";
+import type { AppLocale } from "@overvis/hmi-shared";
+import { type SiteState } from "./status.js";
+/** A preset column: shown in the table and on cards, optionally sortable by `sortValue`. */
+export interface FleetColumn<Site> {
+    id: string;
+    label: string;
+    cell: (site: Site) => ReactNode;
+    /** Value a preset sort orders by; null (unknown) sorts last in both directions. */
+    sortValue?: (site: Site) => number | string | null;
+}
+/** A preset sort option: orders by a preset column's `sortValue`. `value` is kept in `?sort=`. */
+export interface FleetSort {
+    value: string;
+    label: string;
+    column: string;
+    direction: "asc" | "desc";
+}
+/** Built-in sorts: configured order (""), name and urgency (status). */
+export declare const builtInFleetSorts: readonly ["", "name", "status"];
+/** Preset sorts that do not reuse a built-in value or an earlier preset sort's value. */
+export declare function presetFleetSorts(sorts: readonly FleetSort[]): FleetSort[];
+/**
+ * Sites in the order of `sort`: configured order, name, urgency, or a preset sort. Ties and
+ * unknown sorts keep the configured order.
+ */
+export declare function sortFleetSites<Site extends {
+    name: string;
+}>(sites: readonly Site[], sort: string, { locale, stateOf, columns, sorts, }: {
+    locale: AppLocale;
+    stateOf: (site: Site) => SiteState;
+    columns?: readonly FleetColumn<Site>[];
+    sorts?: readonly FleetSort[];
+}): Site[];
+/**
+ * The URL filters that decide which sites match (search, zone, status and preset filters), but not
+ * the sort order. A selection is cleared when this changes.
+ */
+export declare function fleetFilterSignature(search: string, filterKeys: readonly string[]): string;
+/** Selected sites the filters still show, in list order; an action reaches only these. */
+export declare function selectedFleetSites<Site extends {
+    id: string;
+}>(filtered: readonly Site[], selected: ReadonlySet<string>): Site[];

package/dist/src/workspace/fleet/overview.d.ts

@@ -0,0 +1,93 @@
+import { type ReactNode } from "react";
+import type { AppLocale } from "@overvis/hmi-shared";
+import { type FleetBoard, type FleetZone, type SiteReading } from "@overvis/hmi-shared/dashboard";
+import { type DashboardNavigation } from "../dashboards/navigation.js";
+import type { ParameterValueState } from "../parameters/live/model.js";
+import { type SiteActiveAlarm, type SiteMaintenanceSummary } from "../page-state/dashboard.js";
+import { type FleetColumn, type FleetSort } from "./overview-model.js";
+import { type SiteState } from "./status.js";
+import { type SiteStatusLabels } from "./status-badge.js";
+/** What the overview reads from a preset's site. */
+export interface FleetSite {
+    id: string;
+    name: string;
+    zoneId?: string;
+    readings: readonly SiteReading[];
+}
+/** An extra URL filter, such as a site kind. `key` is its query parameter. */
+export interface FleetFilter<Site> {
+    key: string;
+    label: string;
+    allLabel: string;
+    options: readonly {
+        value: string;
+        label: string;
+    }[];
+    matches: (site: Site, value: string) => boolean;
+}
+/**
+ * Opt-in site selection. The preset holds the selected IDs; the overview offers Select, checkboxes,
+ * Select all matching and Clear, and clears the selection when a filter changes or selection
+ * ends. Nothing is stored in the URL.
+ */
+export interface FleetSelection<Site> {
+    selected: ReadonlySet<string>;
+    onChange: (selected: ReadonlySet<string>) => void;
+    /** Actions in the sticky selection bar for the selected sites that the filters still show. */
+    actions: (sites: readonly Site[]) => ReactNode;
+}
+/**
+ * Fleet overview: status totals, URL-backed search and filters (`q`, `zone`, `status`, `sort`
+ * and preset filters), optional zone grouping, and sites as cards or a table. `children`
+ * receives the filtered sites, for an alarm list or a map above the list. Presets can add a
+ * summary block (`siteSummary`), named `columns` with `sorts`, and site `selection`. A card is
+ * one link to the site; interactive preset content on a card needs `relative z-10` to sit above
+ * it.
+ */
+export declare function FleetOverview<Site extends FleetSite>({ sites, zones, board, states, stateOf, navigation, sitePath, locale, title, count, actions, notices, empty, searchPlaceholder, noResults, statusLabels, activityCount, filters, subtitle, badges, columnLabel, alarmsOf, maintenanceOf, siteSummary, columns, sorts, selection, children, }: {
+    sites: readonly Site[];
+    zones?: readonly FleetZone[];
+    board: FleetBoard;
+    states: ReadonlyMap<string, ParameterValueState>;
+    /** The site's evaluated status; evaluate once per update and reuse it. */
+    stateOf: (site: Site) => SiteState;
+    navigation: DashboardNavigation;
+    /** Dashboard path of a site page, such as `/stations/<id>`. */
+    sitePath: (site: Site) => string;
+    locale: AppLocale;
+    /** Page heading; leave it out where the host already shows the dashboard's name. */
+    title?: string;
+    /** Count line under the title, such as "Stations: 4 of 6". */
+    count?: (shown: number, total: number) => string;
+    /** Header buttons, such as board settings or adding a site. */
+    actions?: ReactNode;
+    /** Shown under the header, such as parameter diagnostics. */
+    notices?: ReactNode;
+    /** Shown instead of the list when the fleet has no sites. */
+    empty: ReactNode;
+    searchPlaceholder?: string;
+    noResults?: string;
+    statusLabels?: SiteStatusLabels;
+    activityCount?: (count: number | "?", total: number) => string;
+    filters?: readonly FleetFilter<Site>[];
+    subtitle?: (site: Site) => ReactNode;
+    /** Extra badges next to a site's status, such as overdue maintenance. */
+    badges?: (site: Site) => ReactNode;
+    /** Header of a summary column (a reading category). */
+    columnLabel: (category: string) => string;
+    /** The site's known active alarms, for the fleet summary the assistant reads. */
+    alarmsOf?: (site: Site) => readonly SiteActiveAlarm[];
+    /** Overdue maintenance and whether some dates are unavailable, for the same summary. */
+    maintenanceOf?: (site: Site) => SiteMaintenanceSummary;
+    /** A block on each card under the status line, and a table column after Status. */
+    siteSummary?: {
+        label: string;
+        render: (site: Site) => ReactNode;
+    };
+    /** Preset columns, after the reading columns in the table and with the readings on cards. */
+    columns?: readonly FleetColumn<Site>[];
+    /** Sort options after the built-in ones, ordering by the preset columns' sort values. */
+    sorts?: readonly FleetSort[];
+    selection?: FleetSelection<Site>;
+    children?: (filtered: readonly Site[]) => ReactNode;
+}): import("react").JSX.Element;

package/dist/src/workspace/fleet/page-header.d.ts

@@ -0,0 +1,27 @@
+import type { ReactNode } from "react";
+import { type DashboardNavigation } from "../dashboards/navigation.js";
+/**
+ * Site page header: back link to the overview (keeping its filters), name, subtitle, status
+ * line, and for editors a settings toggle with setup actions shown while it is on.
+ */
+export declare function SitePageHeader({ navigation, overviewSearch, backLabel, title, subtitle, status, canEdit, editing, onEditingChange, actions, }: {
+    navigation: Pick<DashboardNavigation, "href" | "navigate">;
+    /** Overview query to restore on the back link. */
+    overviewSearch: string;
+    backLabel: string;
+    title: string;
+    subtitle?: ReactNode;
+    status?: ReactNode;
+    canEdit: boolean;
+    editing: boolean;
+    onEditingChange: (editing: boolean) => void;
+    /** Setup buttons shown while editing. */
+    actions?: ReactNode;
+}): import("react").JSX.Element;
+/** A missing site or page, with a link back to the overview. */
+export declare function SiteNotFound({ navigation, overviewSearch, message, backLabel, }: {
+    navigation: Pick<DashboardNavigation, "href" | "navigate">;
+    overviewSearch: string;
+    message?: string;
+    backLabel: string;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,65 @@
+export interface ParameterInfo {
+    unit: string;
+    writable: boolean;
+    datetime: boolean;
+    /** A geo position value, usable as a moving site position. */
+    geo: boolean;
+    /** Value-type name, e.g. `num`, `int`, `bool`. */
+    valueType: string;
+    /** Background reading period; null when background readings are off. */
+    backgroundReadingPeriodMs: number | null;
+}
+/**
+ * Looks up a bound parameter's unit, value type and write capability for setup forms, so units
+ * default from parameter metadata and write controls cannot be bound to read-only parameters. Returns null when
+ * nothing is selected and "unavailable" when the lookup fails, which callers must not save past.
+ */
+export declare function useParameterInfo(): (parameterId: string) => Promise<ParameterInfo | "unavailable" | null>;
+/**
+ * Workspace parameters with their branch paths, from the same inventory the pickers use. An empty
+ * list means no parameters only when the inventory is neither pending nor failed.
+ */
+export declare function useTreeParameters(workspaceId: string): {
+    parameters: import("@overvis/hmi-shared/dashboard").TreeParameter[];
+    isPending: boolean;
+    isError: boolean;
+    isFetching: boolean;
+    retry: () => void;
+};
+/**
+ * Field error for a parameter bound to a write: an unverified selection blocks saving, like a
+ * read-only one. `datetime` additionally requires a datetime value type (maintenance dates).
+ */
+export declare function writeBindingError(info: ParameterInfo | "unavailable" | null, { datetime }?: {
+    datetime?: boolean;
+}): (() => string) | null;
+/**
+ * The unit to fill after a parameter is picked, or null to keep the current one: a unit the user
+ * typed (not the one last filled) stays, and so does any unit when the lookup failed.
+ */
+export declare function filledUnit(current: string, lastFilled: string | null | undefined, info: ParameterInfo | "unavailable" | null): string | null;
+/** Field error for a site position parameter: it must be a verified geo parameter. */
+export declare function geoBindingError(info: ParameterInfo | "unavailable" | null): (() => string) | null;
+/**
+ * Field error for a counter (energy, heat, water, gas): only `num` parameters give period totals.
+ * An integer pulse counter needs a `calc` parameter that scales pulses to the metered quantity.
+ */
+export declare function counterBindingError(info: ParameterInfo | "unavailable" | null): (() => string) | null;
+/**
+ * Field error for a reading charted or compared over time, such as power for a peak: history is read
+ * as numbers, so only `num` parameters fit. An integer reading needs a scaling `calc` parameter.
+ */
+export declare function numericBindingError(info: ParameterInfo | "unavailable" | null): (() => string) | null;
+/** Form errors for a failed fleet configuration update; other failures map as API errors. */
+export declare function fleetConfigurationFormError(error: unknown): import("../../index.js").FormValidationErrorResult;
+/**
+ * The same as one sentence, for a change made without a form, such as dragging an item: what
+ * failed in the configuration, or the API's message. A conflict asks to make the change again, so
+ * the caller shows the latest configuration after it.
+ */
+export declare function fleetConfigurationErrorText(error: unknown): string;
+/**
+ * Parameter names in the UI language by ID, the last segment of each branch path, such as an
+ * alarm flag named after its parameter. Empty until the inventory loads.
+ */
+export declare function useParameterNames(workspaceId: string): ReadonlyMap<string, string>;

package/dist/src/workspace/fleet/period-settings.d.ts

@@ -0,0 +1,66 @@
+import Type, { type Static } from "typebox";
+import { type CounterPeriodId } from "@overvis/hmi-shared/dashboard";
+import { type FormFieldErrors } from "../../form/index.js";
+/** A board's default counter period and calendar time zone as `PeriodSettingsFields` edits them. */
+export declare const periodSettingsFormType: Type.TObject<{
+    defaultPeriod: Type.TEnum<("24h" | "30d" | "7d" | "last-month" | "last-week" | "this-month" | "this-week" | "today" | "yesterday")[]>;
+    timeZoneSource: Type.TUnion<[Type.TLiteral<"workspace">, Type.TLiteral<"browser">, Type.TLiteral<"zone">]>;
+    timeZone: Type.TString;
+}>;
+export type PeriodSettingsFormValue = Static<typeof periodSettingsFormType>;
+/** A board's default period and time zone (`dashboardTimeZoneType`; null follows the workspace). */
+export interface PeriodSettings {
+    defaultPeriod: CounterPeriodId;
+    timeZone: string | null;
+}
+/** Form values of a board's period settings. */
+export declare function periodSettingsFormValue(settings: PeriodSettings): PeriodSettingsFormValue;
+/** The period settings a form describes, or a field error under `path` for an unknown zone. */
+export declare function periodSettingsFromForm(value: PeriodSettingsFormValue, path: string): {
+    settings: PeriodSettings;
+    errors: FormFieldErrors;
+};
+/**
+ * A board's default counter period and the time zone its calendar periods and charts follow:
+ * the workspace's, each viewer's own, or a named IANA zone. Place it with `fields` at a
+ * `periodSettingsFormValue` and validate with `periodSettingsFromForm`.
+ */
+export declare const PeriodSettingsFields: <TFormData, TFields extends import("@tanstack/react-form").DeepKeysOfType<TFormData, {
+    defaultPeriod: "24h" | "30d" | "7d" | "last-month" | "last-week" | "this-month" | "this-week" | "today" | "yesterday";
+    timeZoneSource: "browser" | "workspace" | "zone";
+    timeZone: string;
+} | null | undefined> | import("@tanstack/react-form").FieldsMap<TFormData, {
+    defaultPeriod: "24h" | "30d" | "7d" | "last-month" | "last-week" | "this-month" | "this-week" | "today" | "yesterday";
+    timeZoneSource: "browser" | "workspace" | "zone";
+    timeZone: string;
+}>, TOnMount extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnChange extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnChangeAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnBlur extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnBlurAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnSubmit extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnSubmitAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnDynamic extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnDynamicAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnServer extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TFormSubmitMeta>(params: import("react").PropsWithChildren<NoInfer<{
+    /** Periods offered as the default, in order. Default: every period. */
+    periods?: readonly CounterPeriodId[];
+}> & {
+    form: import("@tanstack/react-form").AppFieldExtendedReactFieldGroupApi<unknown, TFormData, string | import("@tanstack/react-form").FieldsMap<unknown, TFormData>, any, any, any, any, any, any, any, any, any, any, TFormSubmitMeta, {
+        readonly TextField: typeof import("../../index.js").TextField;
+        readonly TextAreaField: typeof import("../../index.js").TextAreaField;
+        readonly OtpField: typeof import("../../index.js").OtpField;
+        readonly CheckboxField: typeof import("../../index.js").CheckboxField;
+        readonly ParameterPickerField: typeof import("../../index.js").ParameterPickerField;
+        readonly DashboardPickerField: typeof import("../../index.js").DashboardPickerField;
+        readonly FormulaField: typeof import("../../index.js").FormulaField;
+    }, {
+        readonly FormRoot: typeof import("../../index.js").FormRoot;
+        readonly FormErrorBanner: typeof import("../../index.js").FormErrorBanner;
+        readonly SubmitButton: typeof import("../../index.js").SubmitButton;
+    }> | import("@tanstack/react-form").AppFieldExtendedReactFormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TFormSubmitMeta, {
+        readonly TextField: typeof import("../../index.js").TextField;
+        readonly TextAreaField: typeof import("../../index.js").TextAreaField;
+        readonly OtpField: typeof import("../../index.js").OtpField;
+        readonly CheckboxField: typeof import("../../index.js").CheckboxField;
+        readonly ParameterPickerField: typeof import("../../index.js").ParameterPickerField;
+        readonly DashboardPickerField: typeof import("../../index.js").DashboardPickerField;
+        readonly FormulaField: typeof import("../../index.js").FormulaField;
+    }, {
+        readonly FormRoot: typeof import("../../index.js").FormRoot;
+        readonly FormErrorBanner: typeof import("../../index.js").FormErrorBanner;
+        readonly SubmitButton: typeof import("../../index.js").SubmitButton;
+    }>;
+    fields: TFields;
+}>) => ReturnType<import("react").FunctionComponent>;

package/dist/src/workspace/fleet/placement-fields.d.ts

@@ -0,0 +1,104 @@
+import Type from "typebox";
+import type { Static } from "typebox";
+import { type DashboardTheme, type FleetZone, type SitePosition } from "@overvis/hmi-shared/dashboard";
+import { type FormFieldErrors } from "../../form/index.js";
+import { type ParameterInfo } from "./parameters.js";
+/** A site's zone and map position as `SitePlacementFields` edits them. */
+export declare const sitePlacementFormType: Type.TObject<{
+    zoneId: Type.TString;
+    positionSource: Type.TUnion<[Type.TLiteral<"coordinates">, Type.TLiteral<"parameter">]>;
+    lat: Type.TString;
+    lng: Type.TString;
+    positionParameterId: Type.TUnion<[Type.TLiteral<"">, Type.TString]>;
+}>;
+export type SitePlacementFormValue = Static<typeof sitePlacementFormType>;
+/** Where a site is: an optional zone and an optional fixed or parameter-driven position. */
+export interface SitePlacement {
+    zoneId?: string;
+    position?: SitePosition;
+}
+/** Form values of a site's placement; a new site starts with fixed, empty coordinates. */
+export declare function sitePlacementFormValue(site: SitePlacement | null): SitePlacementFormValue;
+/** Decimal degrees within ±limit; a decimal comma is accepted. Hex, exponents and blanks are not. */
+export declare function parseSiteCoordinate(text: string, limit: number): number | null;
+/**
+ * The placement a form describes, or field errors under `path`, such as `placement`. Both
+ * coordinates must be given or both left empty; a position parameter must be a geo parameter.
+ * `parameterInfo` is `useParameterInfo`'s lookup.
+ */
+export declare function sitePlacementFromForm(value: SitePlacementFormValue, path: string, parameterInfo: (parameterId: string) => Promise<ParameterInfo | "unavailable" | null>): Promise<{
+    placement: SitePlacement;
+    errors: FormFieldErrors;
+}>;
+/**
+ * A site's zone and map position: fixed coordinates, typed or picked on a map, or a geo
+ * parameter for a mobile unit. Place it with `fields` at a `sitePlacementFormValue`, validate
+ * with `sitePlacementFromForm` and list the board's other sites as `context`.
+ */
+export declare const SitePlacementFields: <TFormData, TFields extends import("@tanstack/react-form").DeepKeysOfType<TFormData, {
+    zoneId: string;
+    positionSource: "coordinates" | "parameter";
+    lat: string;
+    lng: string;
+    positionParameterId: string;
+} | null | undefined> | import("@tanstack/react-form").FieldsMap<TFormData, {
+    zoneId: string;
+    positionSource: "coordinates" | "parameter";
+    lat: string;
+    lng: string;
+    positionParameterId: string;
+}>, TOnMount extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnChange extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnChangeAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnBlur extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnBlurAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnSubmit extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnSubmitAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnDynamic extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnDynamicAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnServer extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TFormSubmitMeta>(params: import("react").PropsWithChildren<NoInfer<{
+    zones: readonly FleetZone[];
+    /** Other sites with fixed coordinates, shown on the picker map for orientation. */
+    context: readonly {
+        id: string;
+        name: string;
+        position: {
+            lat: number;
+            lng: number;
+        };
+    }[];
+    workspaceId: string;
+    dashboardId: string;
+    theme: DashboardTheme;
+}> & {
+    form: import("@tanstack/react-form").AppFieldExtendedReactFieldGroupApi<unknown, TFormData, string | import("@tanstack/react-form").FieldsMap<unknown, TFormData>, any, any, any, any, any, any, any, any, any, any, TFormSubmitMeta, {
+        readonly TextField: typeof import("../../index.js").TextField;
+        readonly TextAreaField: typeof import("../../index.js").TextAreaField;
+        readonly OtpField: typeof import("../../index.js").OtpField;
+        readonly CheckboxField: typeof import("../../index.js").CheckboxField;
+        readonly ParameterPickerField: typeof import("../../index.js").ParameterPickerField;
+        readonly DashboardPickerField: typeof import("../../index.js").DashboardPickerField;
+        readonly FormulaField: typeof import("../../index.js").FormulaField;
+    }, {
+        readonly FormRoot: typeof import("../../index.js").FormRoot;
+        readonly FormErrorBanner: typeof import("../../index.js").FormErrorBanner;
+        readonly SubmitButton: typeof import("../../index.js").SubmitButton;
+    }> | import("@tanstack/react-form").AppFieldExtendedReactFormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TFormSubmitMeta, {
+        readonly TextField: typeof import("../../index.js").TextField;
+        readonly TextAreaField: typeof import("../../index.js").TextAreaField;
+        readonly OtpField: typeof import("../../index.js").OtpField;
+        readonly CheckboxField: typeof import("../../index.js").CheckboxField;
+        readonly ParameterPickerField: typeof import("../../index.js").ParameterPickerField;
+        readonly DashboardPickerField: typeof import("../../index.js").DashboardPickerField;
+        readonly FormulaField: typeof import("../../index.js").FormulaField;
+    }, {
+        readonly FormRoot: typeof import("../../index.js").FormRoot;
+        readonly FormErrorBanner: typeof import("../../index.js").FormErrorBanner;
+        readonly SubmitButton: typeof import("../../index.js").SubmitButton;
+    }>;
+    fields: TFields;
+}>) => ReturnType<import("react").FunctionComponent>;
+/** Other sites with fixed coordinates, for `SitePlacementFields`' `context`. */
+export declare function sitePlacementContext(sites: readonly {
+    id: string;
+    name: string;
+    position?: SitePosition;
+}[], exceptId: string | undefined): {
+    id: string;
+    name: string;
+    position: {
+        lat: number;
+        lng: number;
+    };
+}[];