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

package/dist/src/workspace/device-presets/relay-test.d.ts

@@ -0,0 +1,164 @@
+import type { ParameterWriteSequenceResult, ParameterWriteSequenceStep, ParameterWriteValuesInput, ParameterWriteValuesOutput } from "@overvis/hmi-shared/parameter";
+import { type ParameterValueState } from "../parameters/live/model.js";
+/** One output relay of a relay test: where its state is read and where it is commanded. */
+export interface DeviceRelayTestRelay {
+    key: string;
+    label: string;
+    /** A boolean reading of the relay's present state. */
+    stateParameterId: string;
+    /** The register that switches the relay while the device is under remote control. */
+    commandParameterId: string;
+}
+/** The device setting that hands its relays to remote control, and its two codes. */
+export interface DeviceRelayTestRemote {
+    parameterId: string;
+    /** The code that puts the relays under remote control. */
+    testValue: number;
+    /** The code a test returns to when it did not record the previous one. */
+    normalValue: number;
+}
+export type DeviceRelayTestAvailability = "ready" | "forbidden" | "disconnected"
+/** The remote-control setting or a relay state is not known from a fresh read. */
+ | "pending"
+/** The relays are already under remote control, possibly by another master. */
+ | "remote"
+/** The browser cannot keep the test, so a reload could leave it running with no End test. */
+ | "noStorage";
+/** The value comes from a fresh read and no write to it is under way, so it is not changing. */
+export declare const relayTestFresh: (state: ParameterValueState) => boolean;
+/**
+ * Whether a test can start now. It starts only from fresh readings of the remote-control setting
+ * and every relay, so the relays are handed over in the positions they hold, and never while the
+ * relays are already under remote control.
+ */
+export declare function deviceRelayTestAvailability(input: {
+    canWrite: boolean;
+    connected: boolean;
+    /** The browser can keep a running test, see `deviceRelayTestStorageWorks`. */
+    storage: boolean;
+    remote: ParameterValueState;
+    remoteTestValue: number;
+    relayStates: readonly ParameterValueState[];
+    /** Each relay's command register, which the end puts back. */
+    commandStates: readonly ParameterValueState[];
+}): DeviceRelayTestAvailability;
+/**
+ * Starting a test: hand the relays to remote control, then command each relay to the state it
+ * holds now. This keeps the handover change short, not absent: between the first write and the
+ * commands, the device applies its old command values, so a relay may switch briefly.
+ */
+export declare function deviceRelayTestStartSteps(input: {
+    remote: DeviceRelayTestRemote;
+    relays: readonly DeviceRelayTestRelay[];
+    /** Each relay's present state, by key. */
+    states: Readonly<Record<string, boolean>>;
+}): ParameterWriteSequenceStep[];
+/** Whether the device acknowledged the remote-control write, the first step of a start sequence. */
+export declare function deviceRelayTestRemoteAcknowledged(result: ParameterWriteSequenceResult): boolean;
+/**
+ * Whether a start sequence may have handed the relays over. The remote-control write is its first
+ * step: once it was acknowledged, or its result is unknown and so it may have been applied, the
+ * test runs so it can be ended, even if a later command failed.
+ */
+export declare function deviceRelayTestHandedOver(result: ParameterWriteSequenceResult): boolean;
+/**
+ * A test this page runs: what to restore, whether the handover is confirmed (by the device's
+ * acknowledgement of the write or by a read showing it), and whether it was taken up from the
+ * browser after a reload rather than started on this page.
+ */
+export interface DeviceRelayTestSession extends DeviceRelayTestRecord {
+    confirmed: boolean;
+    restored: boolean;
+}
+/** The session a settled start sequence leaves, or null when it cannot have handed over. */
+export declare function deviceRelayTestSessionAfterStart(result: ParameterWriteSequenceResult, record: DeviceRelayTestRecord): DeviceRelayTestSession | null;
+/** The session a test kept in the browser resumes as after a reload. */
+export declare const deviceRelayTestRestoredSession: (stored: DeviceRelayTestRecord) => DeviceRelayTestSession;
+/**
+ * What a fresh read of the remote-control code does to a session: the test code confirms one
+ * started here; any other code ends a confirmed one (the device took control back, after its link
+ * supervision timed out or someone changed the setting) and drops a restored one (it ended while
+ * the page was away). An unconfirmed test started here keeps waiting for its first step to show.
+ * A restored test is never confirmed: the remote control it reads may be another master's, taken
+ * after the device returned to normal, so it only offers End test.
+ */
+export declare function deviceRelayTestSessionAfterRead(session: DeviceRelayTestSession, remoteValue: number, testValue: number): {
+    session: DeviceRelayTestSession | null;
+    takenBack: boolean;
+} | null;
+/**
+ * What the browser keeps for a test: what to restore while it runs, and after it ended on its own
+ * until its command registers are put back (`leftover`, kept for a retry after a reload if that
+ * fails); nothing once it is over; and "unchanged" while a start is being sent, which its first
+ * write already kept.
+ */
+export declare function deviceRelayTestKept(session: DeviceRelayTestSession | null, handingOver: boolean, leftover?: DeviceRelayTestRecord | null): DeviceRelayTestRecord | null | "unchanged";
+/** Leaving the page asks first from the first write of a start until the test ends. */
+export declare const deviceRelayTestBlocksLeaving: (session: DeviceRelayTestSession | null, handingOver: boolean) => boolean;
+/** Commanding one relay while the test runs: 1 switches it on, 0 off. */
+export declare const deviceRelayTestCommandItem: (relay: DeviceRelayTestRelay, on: boolean) => {
+    paramId: string;
+    value: string;
+};
+/**
+ * Writes one item of a test and reports whether the device acknowledged it; a missing result, an
+ * error result or a failed request all count as not acknowledged.
+ */
+export declare function deviceRelayTestWrite(write: (input: ParameterWriteValuesInput) => Promise<ParameterWriteValuesOutput>, item: {
+    paramId: string;
+    value: string;
+}): Promise<boolean>;
+/** Ending a test: return the remote-control setting to the code it had before the test. */
+export declare function deviceRelayTestEndItem(remote: DeviceRelayTestRemote, previous: number | null): {
+    paramId: string;
+    value: string;
+};
+/** What a test puts back when it ends, kept in the browser so a reload can still end it. */
+export interface DeviceRelayTestRecord {
+    /** The remote-control code to restore. */
+    previous: number | null;
+    /** Each relay's command code before the test, by relay key. */
+    commands: Readonly<Record<string, number>>;
+}
+/**
+ * After the device is back under its own control: put each relay's command register back to its
+ * code before the test, so the test's commands do not wait for the next remote control.
+ */
+export declare function deviceRelayTestRestoreItems(relays: readonly DeviceRelayTestRelay[], commands: Readonly<Record<string, number>>): {
+    paramId: string;
+    value: string;
+}[];
+/** Write items from their JSON text; none when the text is not a list of them. */
+export declare function parseDeviceRelayTestWriteItems(text: string): {
+    paramId: string;
+    value: string;
+}[];
+/** A record from its JSON text, or null when the text is not one. */
+export declare function parseDeviceRelayTestRecord(text: string): DeviceRelayTestRecord | null;
+/** The parameters a relay test belongs to: the remote setting, then each relay's state and command. */
+export declare function deviceRelayTestParameterIds(remote: DeviceRelayTestRemote, relays: readonly DeviceRelayTestRelay[]): string[];
+/**
+ * The code to restore of a relay test kept for these parameters, or null when there is none, it is
+ * unreadable, it belongs to other parameters, or storage is blocked.
+ */
+export declare function readStoredDeviceRelayTest(storage: Storage | undefined, key: string, parameterIds: readonly string[]): DeviceRelayTestRecord | null;
+/**
+ * Keeps a relay test's code to restore, or removes it with null, and reports whether the storage
+ * now holds exactly that: blocked or full storage, or a write that did not stick, reports false.
+ */
+export declare function writeStoredDeviceRelayTest(storage: Storage | undefined, key: string, test: DeviceRelayTestRecord | null, parameterIds: readonly string[]): boolean;
+/** Whether the browser's storage keeps what is written to it; blocked or full storage does not. */
+export declare function deviceRelayTestStorageWorks(storage: Storage | undefined): boolean;
+/** The browser's local storage, when this page may use it. */
+export declare function deviceRelayTestStorage(): Storage | undefined;
+/** Marks the test under `key` as running here with a confirmed handover, or not. */
+export declare function setDeviceRelayTestActive(key: string, active: boolean): void;
+/** Whether the test under `key` runs here with a confirmed handover. */
+export declare const isDeviceRelayTestActive: (key: string) => boolean;
+/**
+ * Whether `DeviceRelayTest` with this `storageKey` runs a test on this page: from the first write
+ * of its start, and then while the device confirms the handover, updated as it changes. A banner that offers to end remote control stays out of
+ * the way of such a test. A test taken up after a reload never counts: the remote control it reads
+ * may be another master's.
+ */
+export declare function useDeviceRelayTestActive(storageKey: string): boolean;

package/dist/src/workspace/device-presets/series-colors.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Colors of the series of a device trend, in order. Phase L1, L2 and L3 are the first three, so a
+ * table or a headline that marks a phase with its swatch matches the chart.
+ */
+export declare const deviceSeriesColors: readonly [{
+    readonly stroke: `
+      stroke-primary
+      dark:stroke-cyan-300
+    `;
+    readonly fill: `
+      fill-primary
+      dark:fill-cyan-300
+    `;
+    readonly swatch: `
+      bg-primary
+      dark:bg-cyan-300
+    `;
+}, {
+    readonly stroke: `
+      stroke-amber-600
+      dark:stroke-amber-300
+    `;
+    readonly fill: `
+      fill-amber-600
+      dark:fill-amber-300
+    `;
+    readonly swatch: `
+      bg-amber-600
+      dark:bg-amber-300
+    `;
+}, {
+    readonly stroke: `
+      stroke-violet-600
+      dark:stroke-violet-300
+    `;
+    readonly fill: `
+      fill-violet-600
+      dark:fill-violet-300
+    `;
+    readonly swatch: `
+      bg-violet-600
+      dark:bg-violet-300
+    `;
+}, {
+    readonly stroke: `
+      stroke-pink-600
+      dark:stroke-pink-300
+    `;
+    readonly fill: `
+      fill-pink-600
+      dark:fill-pink-300
+    `;
+    readonly swatch: `
+      bg-pink-600
+      dark:bg-pink-300
+    `;
+}];
+export declare function deviceSeriesColor(index: number): (typeof deviceSeriesColors)[number];

package/dist/src/workspace/device-presets/settings-choice.d.ts

@@ -0,0 +1,20 @@
+import type { ReactElement } from "react";
+import { type DeviceSettingOption } from "./settings-types.js";
+interface ChoiceProps {
+    id: string;
+    options: readonly DeviceSettingOption[];
+    /** The selected code as the form holds it. */
+    value: string;
+    disabled: boolean;
+    onChange: (value: string) => void;
+}
+/** A choice as segmented buttons; `compact` buttons fit their labels on wide sections. */
+export declare function SettingSegmented({ id, label, options, value, disabled, onChange, compact, }: ChoiceProps & {
+    label: string;
+    compact?: boolean;
+}): ReactElement;
+/** A choice as a drop-down. */
+export declare function SettingSelect({ id, options, value, disabled, onChange, onBlur, }: ChoiceProps & {
+    onBlur: () => void;
+}): ReactElement;
+export {};

package/dist/src/workspace/device-presets/settings-fields.d.ts

@@ -0,0 +1,39 @@
+/** A number the device accepts from `min` to `max`, in steps of 10^-`decimals`. */
+export interface DeviceSettingNumberSpec {
+    kind: "number";
+    min: number;
+    max: number;
+    decimals: number;
+}
+/** One of the device's codes for a setting. */
+export interface DeviceSettingChoiceSpec {
+    kind: "choice";
+    values: readonly number[];
+}
+/** What a device setting accepts; drafts outside it are reported and never written. */
+export type DeviceSettingSpec = DeviceSettingNumberSpec | DeviceSettingChoiceSpec;
+/** A number setting from `min` to `max` with `decimals` decimal places. */
+export declare const deviceSettingNumber: (min: number, max: number, decimals?: number) => DeviceSettingNumberSpec;
+/** A setting that takes one of the device's codes. */
+export declare const deviceSettingChoice: (...values: number[]) => DeviceSettingChoiceSpec;
+/** A draft as the operator typed it; a comma is accepted as the decimal separator. */
+export declare function parseDraft(text: string): number | null;
+export type FieldProblem = {
+    kind: "invalid";
+} | {
+    kind: "range";
+    min: number;
+    max: number;
+} | {
+    kind: "step";
+    decimals: number;
+};
+export declare function fieldProblem(spec: DeviceSettingSpec, text: string): FieldProblem | null;
+/** The draft of a device value: the value itself, or empty while it is unknown. */
+export declare function draftOf(value: number | null, spec: DeviceSettingSpec): string;
+/** Fields whose draft is a valid value different from the device value. */
+export declare function changedFields<Key extends string>(specs: Readonly<Record<Key, DeviceSettingSpec>>, baseline: Readonly<Record<string, string>>, drafts: Readonly<Record<string, string>>, keys: readonly Key[]): Key[];
+/** The value a draft writes: a canonical decimal string. */
+export declare function writeValue(spec: DeviceSettingSpec, text: string): string;
+/** Fields the operator edited: a draft that is not the device value, valid or not. */
+export declare function editedFields<Key extends string>(specs: Readonly<Record<Key, DeviceSettingSpec>>, baseline: Readonly<Record<string, string>>, drafts: Readonly<Record<string, string>>, keys: readonly Key[]): Key[];

package/dist/src/workspace/device-presets/settings-form.d.ts

@@ -0,0 +1,35 @@
+import { type ReactElement, type ReactNode } from "react";
+import type { ParameterWriteSequenceSecret } from "../parameters/live/write-sequence-dialog.js";
+import { type DeviceSettingSpec } from "./settings-fields.js";
+import type { DeviceSettingsContext, DeviceSettingsValidator } from "./settings-types.js";
+import { type DeviceSettingsVerification, type DeviceSettingsWritePlan } from "./settings-write.js";
+/** The form of one settings section: drafts, row layout, confirmation, write and read-back. */
+export declare function SettingsForm<Key extends string>({ id, title, keys, bindings, specs, baseline, units, labels, canWrite, reading, optionLabel, plan, unlock, receivedAt, notKeptMessage, validate, unsupported, onDraftsChange, onWritten, onVerified, children, }: {
+    id: string;
+    title: string;
+    validate: DeviceSettingsValidator<Key> | undefined;
+    /** Registers the device does not have: shown as not supported and never written. */
+    unsupported: ReadonlySet<Key>;
+    keys: readonly Key[];
+    bindings: Readonly<Record<Key, string>>;
+    specs: Readonly<Record<Key, DeviceSettingSpec>>;
+    baseline: Readonly<Record<string, string>>;
+    /** When each setting's current value was read; null while it has none. */
+    receivedAt: ReadonlyMap<Key, number | null>;
+    unlock: ParameterWriteSequenceSecret | undefined;
+    notKeptMessage: string;
+    onVerified: ((verification: DeviceSettingsVerification<Key>) => void) | undefined;
+    units: ReadonlyMap<Key, string>;
+    labels: Readonly<Record<Key, string>>;
+    canWrite: boolean;
+    onDraftsChange: ((draft: (key: Key) => number | null) => void) | undefined;
+    /**
+     * A read of the settings is under way. The fields stay editable, but changes are not confirmed
+     * until it settles, so they are never reviewed against values about to be replaced.
+     */
+    reading: boolean;
+    optionLabel: (key: Key, value: number, setting: (key: Key) => number | null) => string | null;
+    plan: DeviceSettingsWritePlan<Key>;
+    onWritten: ((written: readonly Key[]) => void) | undefined;
+    children: (context: DeviceSettingsContext<Key>) => ReactNode;
+}): ReactElement;

package/dist/src/workspace/device-presets/settings-page.d.ts

@@ -0,0 +1,29 @@
+import type { ReactElement, ReactNode } from "react";
+/**
+ * A link in a device settings page's index: a `DeviceSettingsSection` id, title and icon. With
+ * `unavailable`, the section is not on the page; the index lists it, unlinked, under that reason.
+ */
+export interface DeviceSettingsIndexEntry {
+    id: string;
+    title: string;
+    icon: ReactNode;
+    unavailable?: string;
+}
+/**
+ * A device settings page: an index of its sections beside them on wide screens and above them on
+ * a phone, then the intro, or why the operator cannot change settings, with **Read again**.
+ * `children` are the sections, with any notes that apply to all of them first. Place it in an
+ * `@container` so the index follows the dashboard width.
+ */
+export declare function DeviceSettingsPage({ sections, intro, canWrite, connected, onReadAgain, children, }: {
+    sections: readonly DeviceSettingsIndexEntry[];
+    /** What the page changes, shown to operators who can write. */
+    intro: ReactNode;
+    /** The workspace role can write parameter values. */
+    canWrite: boolean;
+    /** The device answers; reading again waits for its connection otherwise. */
+    connected: boolean;
+    /** Reads every setting from the device again. */
+    onReadAgain: () => void;
+    children: ReactNode;
+}): ReactElement;

package/dist/src/workspace/device-presets/settings-rows.d.ts

@@ -0,0 +1,25 @@
+/** The parts of a form field a settings row uses. */
+export interface FieldApi {
+    name: string;
+    state: {
+        value: string;
+        meta: {
+            errors: unknown[];
+            isValid: boolean;
+        };
+    };
+    handleChange: (value: string) => void;
+    handleBlur: () => void;
+}
+export declare const fieldName: (key: string) => string;
+/** Resets drafts of settings the layout no longer shows, so hidden values are never written. */
+export declare function ResetHidden({ hidden, onReset, }: {
+    hidden: readonly string[];
+    onReset: (keys: readonly string[]) => void;
+}): null;
+/** Setting rows sit in one column on a phone and beside their controls from 34rem up. */
+export declare const rowClass = "\n  relative grid gap-x-6 gap-y-2 py-3.5\n  @min-[34rem]/settings:grid-cols-[minmax(0,1fr)_minmax(0,14rem)] @min-[34rem]/settings:items-start\n";
+/** A row whose control takes its own width beside the label, or the full row under it. */
+export declare const fitRowClass = "relative flex flex-wrap items-start gap-x-6 gap-y-2 py-3.5";
+/** A changed setting is marked on its row until it is written or discarded. */
+export declare const changedClass = "\n  before:absolute before:inset-y-3 before:-left-4 before:w-0.5 before:rounded-full\n  before:bg-primary\n  sm:before:-left-5\n";

package/dist/src/workspace/device-presets/settings-section.d.ts

@@ -0,0 +1,78 @@
+import { type AppLocale } from "@overvis/hmi-shared";
+import type { ReactElement, ReactNode } from "react";
+import type { ParameterWriteSequenceSecret } from "../parameters/live/write-sequence-dialog.js";
+import { type DeviceSettingSpec } from "./settings-fields.js";
+import { type DeviceSettingsVerification, type DeviceSettingsWritePlan } from "./settings-write.js";
+import type { DeviceSettingsContext, DeviceSettingsValidator } from "./settings-types.js";
+/**
+ * One section of a device's settings: shows the settings the dashboard polls as drafts, marks
+ * edited rows with the device value, reports values the device does not accept as they are typed,
+ * and writes the changes after a confirmation of old → new values, in one request or in the
+ * ordered steps of `plan`; changes a failed step did not write keep their drafts and errors on their
+ * rows. A newer reading
+ * updates untouched settings and keeps edits; settings kept from an earlier read are read-only
+ * until read again. The layout places the rows and decides which settings the current drafts
+ * hide; edits to hidden settings are reset to the device value.
+ */
+export declare function DeviceSettingsSection<Key extends string>({ id, icon, title, description, keys, bindings, specs, labels, locale, canWrite, pendingRead, optionLabel, plan, unlock, notKeptMessage, validate, units: unitOverrides, onDraftsChange, onWritten, onVerified, children, }: {
+    /** The section element's id, which a settings index links to. */
+    id: string;
+    icon: ReactNode;
+    title: string;
+    description: string;
+    keys: readonly Key[];
+    bindings: Readonly<Record<Key, string>>;
+    specs: Readonly<Record<Key, DeviceSettingSpec>>;
+    /** Setting names, for the rows and the confirmation. */
+    labels: Readonly<Record<Key, string>>;
+    locale: AppLocale;
+    canWrite: boolean;
+    /**
+     * How a value reads in the confirmation and as the device value, such as a choice code's label;
+     * the code with its unit by default. `setting` reads the other settings on the same side, device
+     * values beside a device value and drafts beside a draft, for a value whose meaning depends on
+     * another, such as a threshold in its source's unit.
+     */
+    optionLabel?: (key: Key, value: number, setting: (key: Key) => number | null) => string | null;
+    /**
+     * A read the settings depend on, such as of a mode that decides which of them apply, is under
+     * way. Edits continue but are not confirmed until it settles.
+     */
+    pendingRead?: boolean;
+    /**
+     * Orders the confirmed changes into steps, such as a password unlock before them and a save to
+     * device memory after them. Without it the changes are written together in one request.
+     */
+    plan?: DeviceSettingsWritePlan<Key>;
+    /**
+     * A password typed in the confirmation and written before the plan's steps, such as a device
+     * unlock; an optional one left empty adds no step.
+     */
+    unlock?: ParameterWriteSequenceSecret;
+    /**
+     * Shown on a setting whose write the device acknowledged but whose next read still shows another
+     * value, such as a device that ignores writes while locked.
+     */
+    notKeptMessage?: string;
+    /** Called once the written settings were read again, with those the device kept and did not. */
+    onVerified?: (verification: DeviceSettingsVerification<Key>) => void;
+    /**
+     * Checks between settings, shown on the rows as soon as something is edited and checked again
+     * before the confirmation opens.
+     */
+    validate?: DeviceSettingsValidator<Key>;
+    /** Units that replace the parameters' own, such as °F while the device displays Fahrenheit. */
+    units?: Partial<Readonly<Record<Key, string>>>;
+    /**
+     * Called with the drafts the device accepts whenever one changes, such as for another section
+     * whose previews follow them.
+     */
+    onDraftsChange?: (draft: (key: Key) => number | null) => void;
+    /**
+     * Called with the settings a confirmed write acknowledged. A setting whose write changes others on the
+     * device, such as a mode that resets them, reads them again here.
+     */
+    onWritten?: (written: readonly Key[]) => void;
+    /** Places the rows; settings it does not render for the current drafts are never written. */
+    children: (context: DeviceSettingsContext<Key>) => ReactNode;
+}): ReactElement;

package/dist/src/workspace/device-presets/settings-text.d.ts

@@ -0,0 +1,5 @@
+import type { FieldProblem } from "./settings-fields.js";
+/** Why a typed setting is not accepted, in the dashboard language. */
+export declare function problemText(problem: FieldProblem, unit: string): string;
+/** The range hint under a number setting, such as "50–150 %". */
+export declare function rangeText(min: number, max: number, unit: string): string;

package/dist/src/workspace/device-presets/settings-types.d.ts

@@ -0,0 +1,122 @@
+import type { ReactElement, ReactNode } from "react";
+/** One of a choice setting's codes with its label. */
+export interface DeviceSettingOption {
+    value: number;
+    label: string;
+    /** What the option does, shown under the setting while it is selected. */
+    hint?: string;
+    /**
+     * A code the device can hold but the form never writes, such as one set only on the device's
+     * own keypad: named while it is the device's value, and not offered as a choice.
+     */
+    readOnly?: boolean;
+}
+export interface DeviceSettingRowOptions {
+    /** Replaces the setting's label, such as a delay that depends on the curve. */
+    label?: string;
+    /** Shown under the label; a disabled setting shows its reason instead. */
+    hint?: string;
+    /**
+     * The setting cannot be edited, for this reason. An empty reason disables the row without a
+     * note, for a reason the section states once for several rows.
+     */
+    disabledReason?: string | null;
+    /**
+     * Replaces the message for a draft the setting's spec rejects, such as when a custom control
+     * enters the value in another unit than the device stores.
+     */
+    invalidText?: string;
+}
+export interface DeviceSettingChoiceOptions extends DeviceSettingRowOptions {
+    options: readonly DeviceSettingOption[];
+    /**
+     * `segmented` shows every option as a button, under the label when there is not room
+     * beside it; `select` is a drop-down beside the label.
+     */
+    style: "segmented" | "select";
+}
+export interface DeviceSettingSwitchOptions extends DeviceSettingRowOptions {
+    /** The code the switch writes when on; 1 by default. */
+    on?: number;
+    /** The code the switch writes when off; 0 by default. */
+    off?: number;
+}
+export interface DeviceSettingCustomOptions extends DeviceSettingRowOptions {
+    /** `stacked` puts the control under the label on any width. */
+    layout?: "columns" | "stacked";
+    /** The setting's value in words, for the confirmation and the device value. */
+    describe?: (value: number) => string;
+}
+export interface DeviceSettingReadOnlyOptions {
+    /** Replaces the setting's label. */
+    label?: string;
+    /** Why the setting cannot be changed here, such as "Set on the device's front panel". */
+    reason: string;
+}
+/** What a custom setting control renders with: the draft as the device code, and its events. */
+export interface DeviceSettingControlProps {
+    /** The control's element id, which the row's label points to. */
+    id: string;
+    /** The draft as the device value, such as "30000" for 30 s stored in milliseconds. */
+    value: string;
+    disabled: boolean;
+    invalid: boolean;
+    onChange: (value: string) => void;
+    onBlur: () => void;
+}
+/**
+ * Problems between settings of a section, such as a lower limit above an upper one, by the setting
+ * that shows each. `draft` gives the drafts the device accepts as numbers, null otherwise.
+ */
+export type DeviceSettingsValidator<Key extends string> = (draft: (key: Key) => number | null) => Partial<Record<Key, string>>;
+/** What a settings section's layout reads and renders. */
+export interface DeviceSettingsContext<Key extends string> {
+    /** Draft numbers; null while a draft is not a number. */
+    draft: (key: Key) => number | null;
+    /** The setting's unit in the dashboard language; empty when it has none. */
+    unit: (key: Key) => string;
+    /** The draft differs from the device value. */
+    changed: (key: Key) => boolean;
+    /**
+     * The section's settings can be edited: write access, and device values from a fresh read. A
+     * helper that proposes drafts offers them only while this holds.
+     */
+    editable: boolean;
+    /**
+     * Replaces a setting's draft, such as with a value a helper proposes or offsets converted to keep
+     * the temperatures they stand for when their mode changes; it is rounded to the setting's
+     * decimals and reviewed and written like a typed edit. Ignored while the section is not editable.
+     */
+    setDraft: (key: Key, value: number) => void;
+    /** One setting as a row: its name and help beside a number field. */
+    number: (key: Key, options?: DeviceSettingRowOptions) => ReactElement;
+    /** One setting as a row with a choice of codes. */
+    choice: (key: Key, options: DeviceSettingChoiceOptions) => ReactElement;
+    /** A setting with two codes as a row with an on/off switch. */
+    switch: (key: Key, options?: DeviceSettingSwitchOptions) => ReactElement;
+    /** A setting shown with its device value and the reason it cannot be changed here. */
+    readOnly: (key: Key, options: DeviceSettingReadOnlyOptions) => ReactElement;
+    /**
+     * A setting as a row with the section's own control, such as a picker or a value entered in
+     * another unit. The draft stays the device value; the spec still checks it before writing.
+     */
+    custom: (key: Key, options: DeviceSettingCustomOptions, control: (props: DeviceSettingControlProps) => ReactNode) => ReactElement;
+    /**
+     * Keeps a setting the layout writes without a row of its own, such as one that follows another,
+     * so its edit is not reset as hidden.
+     */
+    keep: (key: Key) => void;
+    /**
+     * A choice whose code 0 switches a group of settings off, such as a protection: the choice in
+     * the group's header, and the group's settings only while it is not 0.
+     */
+    switched: (key: Key, options: {
+        title: string;
+        description?: string;
+        options: readonly DeviceSettingOption[];
+    }, 
+    /** Called only while the group is on, so its settings are known to be hidden otherwise. */
+    children?: () => ReactNode) => ReactElement;
+}
+/** The options a choice lists: a read-only one only while it is the selected value. */
+export declare function offeredOptions(options: readonly DeviceSettingOption[], value: string): readonly DeviceSettingOption[];

package/dist/src/workspace/device-presets/settings-write-dialog.d.ts

@@ -0,0 +1,27 @@
+import { type ReactElement } from "react";
+import type { ParameterWriteReviewChange } from "../parameters/live/write-review-dialog.js";
+import type { ParameterWriteSequenceSecret } from "../parameters/live/write-sequence-dialog.js";
+import { type DeviceSettingsWriteOutcome, type DeviceSettingsWriteStep } from "./settings-write.js";
+/**
+ * The confirmation of a settings section's changes: the changes as old → new and the plan's other
+ * steps by their labels, in the order they are written. Confirming writes the steps in order and
+ * stops at the first that is not acknowledged. When the changes show the failure on their fields
+ * the dialog closes; a failure they cannot show, such as of an unlock or save step or a request
+ * that returned no results, is reported here.
+ */
+export declare function DeviceSettingsWriteDialog<Key extends string>({ open, title, changes, steps: plannedSteps, unlock, outdated, disabled, onOpenChange, onSettled, }: {
+    open: boolean;
+    title: string;
+    changes: readonly ParameterWriteReviewChange<Key>[];
+    steps: readonly DeviceSettingsWriteStep[];
+    /**
+     * A password typed in the confirmation and written in a step before `steps`, such as a device
+     * unlock; an optional one left empty adds no step.
+     */
+    unlock?: ParameterWriteSequenceSecret;
+    /** The device values changed after the changes were reviewed. */
+    outdated: boolean;
+    disabled: boolean;
+    onOpenChange: (open: boolean) => void;
+    onSettled: (outcome: DeviceSettingsWriteOutcome<Key>) => void;
+}): ReactElement;