@clickless/react 0.0.0-stage → 0.1.0

package/dist/region/regionSnapshot.d.ts

@@ -0,0 +1,52 @@
+import type { Layout, LayoutChange, Manifest } from "../core/index.js";
+export interface RegionSnapshot {
+    /** Built from the mounted `Adaptive` components. Null until the region has mounted. */
+    manifest: Manifest | null;
+    /**
+     * The committed layout. `order` and `items` hold the components on screen;
+     * `offScreen` holds what is kept for the ones that are not.
+     */
+    layout: Layout | null;
+    /** A proposed layout awaiting `commitPreview`, `discardPreview` or `cancelPreview`. */
+    preview: Layout | null;
+    /**
+     * How the region first looked, before any change, while it is shown in place
+     * of the layout. Null otherwise, and always while there is a preview.
+     */
+    original: Layout | null;
+    /** True when what is on the screen differs from how it first looked. */
+    differsFromOriginal: boolean;
+    /**
+     * Ids of the components the preview, or the original while it is shown,
+     * draws differently from the layout. Empty when neither is showing.
+     */
+    changedComponentIds: ReadonlySet<string>;
+    /**
+     * How the saved layout had to change to fit the components now on screen:
+     * components new in this version, settings the manifest no longer allows,
+     * and what was dropped for good (components past the limit kept off screen,
+     * or entries with nothing saved). Empty when it fits. Components that are
+     * only off screen for now, such as another tab's, are not changes.
+     */
+    savedLayoutAdjustments: readonly LayoutChange[];
+    /** True while the saved layout is being fetched from the engine. */
+    loading: boolean;
+    /**
+     * True when the saved layout could not be fetched, so the screen may not
+     * show it. It is fetched again on its own, a few seconds later and then less
+     * often, and at once when the engine answers again after being out of
+     * reach; false once it has been.
+     */
+    loadFailed: boolean;
+    canUndo: boolean;
+    /** Number of the latest saved change. 0 when there is none, or no engine. */
+    revision: number;
+    /** True when changes are stored by the engine, so there is a history to read. */
+    hasHistory: boolean;
+    /**
+     * True while a change made with the application's own controls is shown but
+     * not saved yet, as when the engine cannot be reached. It is saved when the
+     * engine is back.
+     */
+    hasUnsavedChanges: boolean;
+}

package/dist/region/regionStore.d.ts

@@ -0,0 +1,361 @@
+import { type Layout, type ApplyOperationsOutcome, type Component, type Manifest, type Operation } from "../core/index.js";
+import { type EngineClient, type PreviewToPlanFrom } from "../engine/engineClient.js";
+import type { HistoryPage, LayoutResponse, PlanResponse, UndoneChange } from "../engine/engineResponses.js";
+import type { RegionSnapshot } from "./regionSnapshot.js";
+import { type PreviewRequest } from "./previewRequests.js";
+import { textDirectionToPlanWith } from "./textDirection.js";
+/** How an undo went. */
+export interface UndoResult {
+    /**
+     * True when part of the undone change stays in place in a region this undo
+     * was not asked about, such as one on another page, because that region
+     * changed again since.
+     */
+    keptElsewhere: boolean;
+    /** The change taken back, or null when that is not known, as from an engine that does not say. */
+    undoneChange: UndoneChange | null;
+}
+/**
+ * What became of the preview when a planner's answer came: a new one shows,
+ * holding that answer only; the answer was added to the one showing; nothing
+ * is shown for it, as for a question or a preview taken back whole; or it no
+ * longer fits the screen, and any preview showing is left as it was.
+ */
+export type PlannedPreviewOutcome = "new" | "addedTo" | "none" | "doesNotFit";
+/** A preview a prompt is planned from, taken as planning starts. */
+export interface PreviewToBuildOn {
+    /** Handed back to `showPlannedPreview`, so the answer is added to this preview and no other. */
+    readonly handle: PendingPreview;
+    /** What the plan request carries of it. */
+    readonly planWith: PreviewToPlanFrom;
+}
+/** A change shown and not saved yet. Only the region's own store reads inside it. */
+export interface PendingPreview {
+    layout: Layout;
+    operations: readonly Operation[];
+    /** The requests whose answers make it up, oldest first; none for one that did not come from a prompt. */
+    requests: readonly PreviewRequest[];
+}
+/** What an engine's answer to an undo says about how it went. */
+export declare const undoResultOf: (undoAnswer: {
+    notUndoneIn?: string[];
+    undone?: unknown;
+}) => UndoResult;
+export interface RegionConfig {
+    regionId: string;
+    version: string;
+    columns: number;
+    title?: string;
+    /** Present, as false, only for a region that draws no grid of its own. */
+    grid?: false;
+}
+export type LayoutChangeHandler = (layout: Layout, operations: readonly Operation[]) => void;
+/**
+ * What a turn to write does first with the changes not saved yet: send them,
+ * send them and refuse to go on if any could not be saved, or leave them.
+ */
+export type UnsavedChangesFirst = "save" | "saveOrRefuse" | "leave";
+/**
+ * Where a layout the engine gave came from: a fresh read, the saving of a
+ * change not saved yet, an undo, or a change saved by prompt or restore, with
+ * the `sequence` it took when it began.
+ */
+export type SavedLayoutSource = "read" | "savedUnsavedChange" | "undo" | {
+    laterChangeSequence: number;
+};
+/**
+ * Holds one region's state. With an engine, every committed change is sent to
+ * it and its answer is the truth; without one, changes live in memory only.
+ *
+ * A change made with the application's own controls (one without a prompt)
+ * never waits on the engine: it is shown at once and saved behind the scenes.
+ * While the engine cannot be reached it is kept for the visit and saved when
+ * the engine is back, unless what it changed reads differently in the saved
+ * layout by then (see `carryOverUnsavedChanges`). Changes reach the engine in
+ * the order they were made: a prompt's change or a restore waits for the
+ * older ones to be saved, and is refused if they cannot be. An undo leaves
+ * them, since it takes the newest back itself when that is one of them.
+ */
+export declare class RegionStore {
+    readonly regionId: string;
+    private readonly engine;
+    private readonly nextChangeSequence;
+    onLayoutChange: LayoutChangeHandler | undefined;
+    /**
+     * The columns this screen draws the layout in, set by the region as the
+     * screen's width changes. The planner is told when they are fewer than the
+     * layout's, so its replies describe what the user sees.
+     */
+    drawnColumns: number | null;
+    private regionConfig;
+    private registeredComponents;
+    private savedLayout;
+    private pendingPreview;
+    /** The last preview saved, so an answer planned from it is shown on the layout it became. */
+    private lastSavedPreview;
+    /** True while the region shows how it first looked in place of the layout. */
+    private originalShown;
+    private snapshotListeners;
+    private savedLayoutListeners;
+    private cachedSnapshot;
+    private latestSavedRevision;
+    private latestSavedChangeId;
+    private savedLayoutLoading;
+    private loadFailed;
+    private loadStarted;
+    private engineAnswered;
+    private commitInProgress;
+    private engineCanUndo;
+    /** Without an engine: the layout before each change, and the change, oldest first. */
+    private undoStack;
+    private writeQueue;
+    /** Shown on top of `savedLayout`. Only ever holds anything with an engine. */
+    private readonly unsavedChanges;
+    /** The `sequence` of each saved change an undo here could take back, oldest first. */
+    private savedChangeSequences;
+    private stopListeningToReachability;
+    private readonly loadRetrier;
+    private readonly unsavedChangeSaver;
+    /**
+     * `nextChangeSequence` numbers changes across the regions of one provider, so the
+     * newest among several regions can be told.
+     */
+    constructor(regionId: string, engine: EngineClient | null, nextChangeSequence: () => number);
+    /** Anything else getting an answer is a sign the engine is back: what waits to be tried again is tried now. */
+    private listenToReachability;
+    /** The `sequence` of the newest change not saved yet, or 0 when there is none. */
+    get newestUnsavedChangeSequence(): number;
+    /** True while a change not saved yet may still be saved, whether or not the region is on the screen. */
+    get hasSaveableUnsavedChanges(): boolean;
+    /**
+     * The `sequence` of the newest change here an undo could take back, saved or
+     * not, or 0 when there is none from this visit.
+     */
+    get newestChangeSequence(): number;
+    /** The highest `sequence` among the saved changes here that an undo could still take back, or 0. */
+    get newestSavedChangeSequence(): number;
+    /** Kept in the order the engine took them, so an undo takes the last off as the engine does. */
+    private recordSavedChange;
+    /** A `sequence` for a change saved by prompt or restore, taken when it begins. */
+    takeChangeSequence: () => number;
+    /** True when the newest change here is one not saved yet, which only this screen can take back. */
+    private newestChangeIsUnsaved;
+    /** True when the saved layout of a region on the screen could not be read, and no read is under way. */
+    private get needsLoadRetry();
+    /** The number of the latest saved change, as the engine last gave it. */
+    get savedRevision(): number;
+    /** The number, counted across all the user's regions, of the change that made the latest revision. */
+    get latestChangeId(): number;
+    subscribe: (snapshotListener: () => void) => (() => void);
+    getSnapshot: () => RegionSnapshot;
+    getServerSnapshot: () => RegionSnapshot;
+    /** A layout set earlier in the session wins over `initialLayout`, so it survives a remount. */
+    mountRegion: (mountedRegionConfig: RegionConfig, initialLayout: Layout | undefined) => (() => void);
+    /** Reads the saved layout before the region mounts, unless it has been read or is being read. */
+    preloadSavedLayout: () => void;
+    private startLoading;
+    /** Reads the engine's copy again. If that fails, the region keeps the layout it has. */
+    private refreshSavedLayout;
+    /** The element an item is drawn in, or null if it is not mounted. */
+    elementOf: (componentId: string) => Element | null;
+    /** Which way the page reads where this region is drawn, as a plan request carries it. */
+    textDirectionToPlanWith: () => ReturnType<typeof textDirectionToPlanWith>;
+    /** What the planner is told about the screen besides the manifest: only what differs from a wide one. */
+    drawnColumnsToPlanWith: () => {
+        drawnColumns?: number;
+    };
+    registerComponent: (component: Component, element: Element | null) => (() => void);
+    /**
+     * Validates the operations and commits them if all are valid.
+     *
+     * A change from a prompt is shown once the engine has saved it, and rejects
+     * with an `EngineError` if the engine cannot be reached or the layout changed
+     * elsewhere. A change without a prompt, as from the application's own
+     * controls, is shown and resolves at once, and is saved behind the scenes:
+     * later, if the engine cannot be reached.
+     */
+    applyOperations: (operations: readonly Operation[], prompt?: string, message?: string, viaVoice?: boolean) => Promise<ApplyOperationsOutcome>;
+    /**
+     * `applyOperations` for a change that is shown before the engine has it.
+     * Async so that a fault, such as a region that is not mounted, rejects as it
+     * does for every other change.
+     */
+    private applyAtOnce;
+    /**
+     * Sends the changes not saved yet to the engine, oldest first. Run at the
+     * start of each turn to write but an undo's (see `oneWriteAtATime`), so they
+     * reach the engine before anything made after them. Never rejects: what
+     * could not be saved is tried again later.
+     */
+    private saveUnsavedChanges;
+    /**
+     * Drops the changes kept for this visit only that are older than a change
+     * saved by prompt or restore in another region of the same prompt box,
+     * which did not reach this one. They would otherwise be undone before it.
+     */
+    giveWayToLaterChange: (laterChangeSequence: number) => void;
+    /**
+     * Stops trying the engine again in the background, to save changes or to
+     * read the saved layout, for when the provider holding this store has gone.
+     */
+    dispose: () => void;
+    /** Takes up what `dispose` stopped, as when React mounts the provider once more. */
+    resume: () => void;
+    /** A turn to write with nothing of its own to write: it saves what is not saved yet, in turn. */
+    private queueSavingUnsavedChanges;
+    /** Shows the result of the operations without committing it. */
+    previewOperations: (operations: readonly Operation[], prompt?: string, message?: string, viaVoice?: boolean) => ApplyOperationsOutcome;
+    private showPreview;
+    /**
+     * Saves the preview. Resolves to null when there is none. A preview that
+     * turns out not to be valid is taken off the screen, since it can never be saved.
+     */
+    commitPreview: () => Promise<ApplyOperationsOutcome | null>;
+    /**
+     * Shows the region as it first looked, before any change, without saving
+     * anything, or goes back to its layout. A preview, or any change to the
+     * layout, ends it.
+     */
+    showOriginal: (shown: boolean) => void;
+    /** Takes the preview off the screen without saving it. */
+    cancelPreview: () => void;
+    /**
+     * `cancelPreview`, for when the user themselves chose not to keep it. The
+     * engine is told, so the application's team can see where a prompt's result
+     * was not what its user meant. A preview that did not come from a prompt has
+     * nothing to say about that and is only cancelled, as is one that is already
+     * being saved.
+     */
+    discardPreview: () => void;
+    /**
+     * Tells the engine the preview from a prompt was not kept. One that is being
+     * saved is not reported. Record-keeping only: the user is never made to wait
+     * on it or told it failed.
+     */
+    private reportPreviewNotKept;
+    /**
+     * Returns to the layout before the last committed change. A change not saved
+     * yet is taken back at once, on this screen alone, as the engine never had it.
+     */
+    undoLastChange: () => Promise<UndoResult>;
+    /**
+     * Takes back the newest change, if it is one not saved yet and not on its
+     * way to the engine. Returns it, or null when there was none to take back.
+     */
+    private takeBackUnsavedChange;
+    /**
+     * Puts a committed change on the screen: any preview goes, and the host is
+     * told. Returns the layout shown, or null when the region is not mounted.
+     */
+    private showChange;
+    /**
+     * Returns the screen to how it was after the given saved change; 0 is the
+     * original layout. Later changes stay in the history. Resolves to the number
+     * of the saved change the restore itself made.
+     */
+    restoreRevision: (revision: number) => Promise<number>;
+    /**
+     * Saved changes, newest first, `limit` at a time. Pass `before` to read older
+     * ones, and `promptedOnly` to leave out changes that were not made by prompt.
+     */
+    readHistory: (options: {
+        limit: number;
+        before?: number;
+        promptedOnly?: boolean;
+    }) => Promise<HistoryPage>;
+    /**
+     * Asks the engine to turn a request into operations and previews them.
+     * The returned message is written for the user.
+     *
+     * A request made while a preview is showing is planned from that preview,
+     * so a follow-up such as "bigger again" builds on what the user is looking
+     * at: the operations answered are what it changes from there, and are added
+     * to the preview, which is then kept or discarded as one change. An answer
+     * with nothing to change, such as a question, leaves the preview as it is.
+     * If the saved layout changed elsewhere since the preview was made, it is
+     * fetched again, which takes the preview off, and this rejects with an
+     * `EngineError` whose code is "conflict". If no answer comes, the preview
+     * stays, and can still be kept.
+     */
+    planFromPrompt: (prompt: string, viaVoice?: boolean) => Promise<PlanResponse>;
+    /** `planFromPrompt`, saying what became of the preview. */
+    planAndShowPreview: (prompt: string, viaVoice?: boolean) => Promise<{
+        planResponse: PlanResponse;
+        previewOutcome: PlannedPreviewOutcome;
+    }>;
+    /**
+     * The preview a prompt typed now is planned from, or null when there is
+     * none. One being saved is not built on: it is about to be the saved layout.
+     */
+    previewToBuildOn: () => PreviewToBuildOn | null;
+    /**
+     * Sends a plan request made with `previewToBuildOn`. When the engine says the
+     * preview no longer applies to the saved layout it was made on, the preview
+     * can never be saved, so it is taken off, as one that left the screen.
+     */
+    answeringForPreview: <T>(previewToBuildOn: PreviewToBuildOn | null, sendRequest: () => Promise<T>) => Promise<T>;
+    /**
+     * Shows what the planner proposed for a prompt. Planned from the preview in
+     * `previewBuiltOn`, it is added to that preview while it still shows; one
+     * that takes the whole preview back leaves nothing to keep, so the preview
+     * counts as discarded. Planned from the saved layout, it replaces any
+     * preview that was showing, which counts as discarded.
+     */
+    showPlannedPreview: (operations: readonly Operation[], previewRequest: PreviewRequest, previewBuiltOn: PreviewToBuildOn | null) => PlannedPreviewOutcome;
+    /**
+     * Shows a layout the engine stored for this region in a change it made to
+     * several at once, as `applyOperations` does for a change to this one.
+     */
+    acceptSavedLayout: (layoutResponse: LayoutResponse, operations: readonly Operation[], layoutSource: Exclude<SavedLayoutSource, "read" | "savedUnsavedChange">) => void;
+    /**
+     * Runs one saved change at a time. Each is checked against, and sent with the
+     * number of, the change before it, so two made in quick succession do not
+     * both claim to follow the same one. Without an engine nothing waits.
+     * `unsavedChangesFirst` says what happens first to the changes not saved yet: an
+     * undo leaves them, since it takes the newest back itself; a prompt's change
+     * or a restore is refused when they cannot be saved, so it never reaches the
+     * engine ahead of an older one.
+     */
+    oneWriteAtATime: <T>(writeChange: () => Promise<T>, unsavedChangesFirst?: UnsavedChangesFirst) => Promise<T>;
+    /** Throws why the changes not saved yet could not be saved, if any still wait. */
+    private refuseWhileUnsaved;
+    /** When the engine says the layout changed elsewhere, fetches it before failing. */
+    private reloadingOnConflict;
+    /**
+     * Fetches the engine's copy of the layout, which replaces the one shown and
+     * takes any preview off: on every mount, and after the engine said this
+     * region changed elsewhere.
+     */
+    loadSavedLayout: () => Promise<void>;
+    /**
+     * Calls `savedLayoutListener` when the engine has answered for the saved layout, just
+     * before the screen is told, while it still shows what it showed before.
+     */
+    beforeSavedLayoutIsShown: (savedLayoutListener: () => void) => (() => void);
+    /**
+     * Takes the engine's copy as the saved layout. Changes not saved yet stay on
+     * top of it. After a fresh read or an undo, those that cannot be carried
+     * over to it are still shown for the rest of the visit, so nothing changes
+     * under the user, but are never saved. A change saved by prompt or restore
+     * stands over the older ones: those kept for the visit only, and those that
+     * cannot be carried over to it, go.
+     */
+    private acceptEngineLayout;
+    /** Tells the host. A fault in its handler is reported, and does not stop the SDK keeping its own state right. */
+    private reportLayoutChange;
+    /**
+     * What the operations would do to the saved layout, without doing it.
+     * `fallbackManifest` stands in for the manifest when the region is no longer mounted.
+     */
+    applyToCurrentLayout: (operations: readonly Operation[], fallbackManifest?: Manifest | null) => {
+        manifest: Manifest;
+        applyOutcome: ApplyOperationsOutcome;
+    };
+    /**
+     * The screen changed under the preview, as on leaving the page, so it no
+     * longer describes it: it is taken off and reported as abandoned.
+     */
+    private dropPendingPreview;
+    private notifyListeners;
+    private computeSnapshot;
+}

package/dist/region/responsiveColumns.d.ts

@@ -0,0 +1,35 @@
+/** A region's columns: one number, or the columns to draw from each screen width up, in pixels. */
+export type RegionColumns = number | Readonly<Record<number, number>>;
+/**
+ * The columns a region's layout is kept in, and the columns it is drawn in on
+ * this screen.
+ *
+ * With breakpoints, the layout is kept in the widest one's columns whatever the
+ * screen, so the planner, the saved layout and every check see one grid, and a
+ * change made on a phone does not narrow what the user set for a wide screen.
+ * A narrower screen draws the same layout in fewer columns (see `drawnSpans`).
+ * The server, and the first paint in the browser, draw the widest.
+ */
+export declare function useResponsiveColumns(columns: RegionColumns): {
+    layoutColumns: number;
+    drawnColumns: number;
+};
+/**
+ * How many drawn columns an item `w` columns wide in the layout spans, on its
+ * own: its share of the width, rounded. Used only before the region has
+ * mounted; after that `drawnSpans` places whole rows.
+ */
+export declare function drawnSpan(width: number, layoutColumns: number, drawnColumns: number): number;
+/**
+ * How many drawn columns each item spans, worked out a row at a time so the
+ * rows stay as they are on a wide screen: an item covering columns `start` to
+ * `end` of the wide grid covers the same share of the narrow one, rounded at
+ * its edges, so the spans of one row add up to the drawn columns. Items are
+ * given in the order they are drawn, with their width and height, and each
+ * list is one grid.
+ */
+export declare function drawnSpans(grids: readonly (readonly {
+    id: string;
+    w: number;
+    h: number;
+}[])[], layoutColumns: number, drawnColumns: number): ReadonlyMap<string, number>;

package/dist/region/retrier.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tries something again later, less often each time it fails, and at once
+ * when the device comes back online. Stopped, as when the provider holding it
+ * has gone, it schedules nothing until started again.
+ */
+export declare class Retrier {
+    private readonly attemptAgain;
+    private retryTimer;
+    private nextRetryDelayMs;
+    private stopped;
+    constructor(attemptAgain: () => void);
+    get isWaiting(): boolean;
+    /** Tries again later, unless already waiting to or stopped. */
+    schedule(): void;
+    /** Tries again at once, if it was waiting to. */
+    retryNow: () => void;
+    /** What it was waiting to try worked, so the next failure waits the shortest time again. */
+    succeeded(): void;
+    cancel(): void;
+    stop(): void;
+    start(): void;
+}

package/dist/region/savedLayoutParsing.d.ts

@@ -0,0 +1,7 @@
+import { Layout } from "../core/index.js";
+/**
+ * The layout if it has the shape of one, else null. A saved layout comes from
+ * storage the SDK does not control, and one that is cut short or from another
+ * format must fall back to the default instead of breaking the screen.
+ */
+export declare function parseSavedLayout(savedLayout: unknown): Layout | null;

package/dist/region/settleIntoSavedLayout.d.ts

@@ -0,0 +1,14 @@
+import type { Layout } from "../core/index.js";
+import type { RegionStore } from "./regionStore.js";
+/**
+ * While the saved layout is being fetched the region shows what it has, often
+ * the default, and nothing waits for the engine. When the saved layout arrives,
+ * each item that it puts somewhere else glides there from where it was, and an
+ * item that was not drawn fades in, so the change reads as the screen settling
+ * rather than jumping. Users who ask for less motion get the change at once.
+ *
+ * Where items were is read the moment the engine answers, while the screen
+ * still shows the old layout, so scrolling or the page's own content moving
+ * while the engine was slow makes nothing slide.
+ */
+export declare function useSettleIntoSavedLayout(regionStore: RegionStore, layout: Layout | null): void;

package/dist/region/textDirection.d.ts

@@ -0,0 +1,12 @@
+import type { TextDirection } from "../engine/engineClient.js";
+/**
+ * Which way the page reads where `element` is drawn, or at its root without
+ * one. Read from the browser, so it holds however the page set it: a `dir`
+ * attribute on the element or a parent, or a stylesheet's `direction`. A
+ * `lang` attribute alone does not change it.
+ */
+export declare function textDirectionAt(element: Element | null | undefined): TextDirection;
+/** The direction as a plan request carries it: only when the page reads right to left. */
+export declare function textDirectionToPlanWith(element: Element | null | undefined): {
+    textDirection?: TextDirection;
+};

package/dist/region/unsavedChangeSaver.d.ts

@@ -0,0 +1,45 @@
+import type { LayoutResponse } from "../engine/engineResponses.js";
+import type { UnsavedChange } from "./unsavedChanges.js";
+/** What the saver needs from the region whose changes it saves. */
+export interface UnsavedChangeSaverHost {
+    /** The oldest change the engine may still take. */
+    nextChangeToSave(): UnsavedChange | undefined;
+    /** Runs before the first change is sent, so each is sent against the layout the engine has. */
+    prepareToSave(): Promise<void>;
+    sendChange(change: UnsavedChange): Promise<LayoutResponse>;
+    /** Fetches the engine's copy, after it said the layout changed elsewhere. */
+    reloadSavedLayout(): Promise<void>;
+    changeSaved(change: UnsavedChange, layoutResponse: LayoutResponse): void;
+    /** Asks for a turn to write, in which `save` runs. */
+    queueSaving(): void;
+}
+/**
+ * Saves a region's unsaved changes behind the scenes. What the engine could
+ * not take is tried again later, sooner if the device comes back online.
+ */
+export declare class UnsavedChangeSaver {
+    private readonly host;
+    private savingChange;
+    private lastSaveFailure;
+    private readonly retrier;
+    constructor(host: UnsavedChangeSaverHost);
+    /** The change on its way to the engine right now, if any. */
+    get changeBeingSaved(): UnsavedChange | null;
+    get isWaitingToRetry(): boolean;
+    /** Why the last attempt to save stopped short, or null when everything it tried was saved. */
+    get lastFailure(): unknown;
+    /**
+     * Sends the changes the engine may still take, oldest first. Never rejects:
+     * what could not be saved is tried again later.
+     */
+    save(): Promise<void>;
+    /** Tries again later, unless already waiting to, stopped, or there is nothing to save. */
+    scheduleRetry(): void;
+    /** Tries again at once, if it was waiting to. */
+    retryNow(): void;
+    /** Nothing is left to save, so nothing needs trying again. */
+    cancelRetry(): void;
+    /** Tries nothing more until `start`, even after a save already under way fails. */
+    stop(): void;
+    start(): void;
+}

package/dist/region/unsavedChanges.d.ts

@@ -0,0 +1,78 @@
+import { type Layout, type Manifest, type Operation } from "../core/index.js";
+/** A change made with the application's own controls that the engine has not saved yet. */
+export interface UnsavedChange {
+    operations: readonly Operation[];
+    /** The screen it was made on, for saving it after the region has gone. */
+    manifest: Manifest;
+    /**
+     * Counted across the regions of one provider, so the newest change among
+     * several can be undone first. Only the order of these numbers means anything.
+     */
+    sequence: number;
+    /**
+     * False once it will never be saved: the engine refused it for good, or it
+     * clashes with the saved layout read since it was made. It is then kept for
+     * this visit only, and gives way to the next change that is saved.
+     */
+    saveable: boolean;
+}
+/**
+ * A region's changes not saved yet, oldest first, shown on top of its saved
+ * layout until the engine has them.
+ */
+export declare class UnsavedChangeList {
+    private readonly nextChangeSequence;
+    private changes;
+    constructor(nextChangeSequence: () => number);
+    get isEmpty(): boolean;
+    /** True while any of them may still be saved. */
+    get hasSaveable(): boolean;
+    /** The `sequence` of the newest, or 0 when there is none. */
+    get newestSequence(): number;
+    /** The screen the newest was made on, for when the region is no longer mounted. */
+    get newestManifest(): Manifest | undefined;
+    /** The oldest the engine may still take. */
+    nextToSave(): UnsavedChange | undefined;
+    add(operations: readonly Operation[], manifest: Manifest): void;
+    /** Takes back the newest, unless it is `changeBeingSaved`. Returns the one taken back, or null. */
+    takeBackNewest(changeBeingSaved: UnsavedChange | null): UnsavedChange | null;
+    /**
+     * The engine has `change` now. It goes, and so do the changes kept for the
+     * visit only that were made before it: changes are saved oldest first, so
+     * those are all that come before it, and it is newer than every one of them.
+     */
+    dropSavedChange(change: UnsavedChange): void;
+    /**
+     * Drops the changes kept for the visit only that are older than a change
+     * saved by prompt or restore, numbered `laterChangeSequence`, which
+     * stands over them. Returns true when there were any.
+     */
+    giveWayTo(laterChangeSequence: number): boolean;
+    /**
+     * After a fresh read of the saved layout, carries the changes from the
+     * layout they were made on to it (see `carryOverUnsavedChanges`). Those that
+     * cannot be carried are kept for the visit only.
+     */
+    carryOverToReadLayout(manifest: Manifest, shownLayout: Layout, savedLayout: Layout): void;
+    /**
+     * After a change saved by prompt or restore, numbered
+     * `laterChangeSequence`: the older changes are carried over to the layout it
+     * made where they can be and dropped where they cannot, since it stands over
+     * them. Those made while it was on its way are newer, and stay as they are.
+     */
+    carryOverToLaterChange(manifest: Manifest, shownLayout: Layout, savedLayout: Layout, laterChangeSequence: number): void;
+    /** The layout with every change that fits it laid on top. One that does not waits, unshown, until it does. */
+    applyTo(manifest: Manifest, layout: Layout): Layout;
+}
+/**
+ * The changes that can be carried from the layout they were made on,
+ * `shownLayout`, to the saved layout the engine has now given, `savedLayout`.
+ * A change is carried only when what it acts on reads the same in both: a
+ * setting the user changed while their saved layout could not be read, or
+ * that was changed elsewhere meanwhile, is not overwritten with a value worked
+ * out from a screen they were not shown. One whose component is not on the
+ * screen now is carried as it is when what it acts on reads the same: it is
+ * saved with the screen it was made on. Both layouts must be reconciled
+ * against `manifest`.
+ */
+export declare function carryOverUnsavedChanges(manifest: Manifest, shownLayout: Layout, savedLayout: Layout, changes: readonly UnsavedChange[]): UnsavedChange[];

package/dist/region/userFacingTitle.d.ts

@@ -0,0 +1,7 @@
+import type { Component } from "../core/index.js";
+/**
+ * The component's title, for text the user reads, or null when it has none of
+ * its own. A component given no title carries its id as its title, for the
+ * planner, and an id such as "txns" means nothing to the user.
+ */
+export declare function userFacingTitleOf(component: Pick<Component, "id" | "title">): string | null;