@riverbankcms/sdk 0.147.0 → 0.149.0

package/dist/_dts/content-editor/src/sync/runLifecycle.d.ts

@@ -0,0 +1,64 @@
+import type { EditorBlockId, EditorBlockValues, EditorValueRecord } from '../../../core/src/index';
+import type { EditorUiState, EditorUiStoreInstance } from '../ui/editorUiStore';
+import type { HeldOperation, LifecycleFailure, LifecycleOperation, LifecycleOutcome } from '../ui/stores/types';
+import { type FlushPolicy, type LifecycleDrain } from './sendPlanning';
+import { type OwnWriteSince } from './valueSync';
+/**
+ * The one shell for the document's lifecycle operations (issue 1553, B-ownership). Save
+ * draft and restore replay run under the lifecycle status; publish, schedule, cancel,
+ * discard draft and delete also hold the document while their request is out, because
+ * they write the same route or draft that autosave does. What each held operation
+ * settles first, and what its response's edits are measured from, is data
+ * (`LIFECYCLE_RECONCILIATION`), not branches here.
+ */
+export declare const DONE: LifecycleOutcome;
+export declare const failed: (failure: LifecycleFailure) => LifecycleOutcome;
+/**
+ * What a held operation settles before its request, and what the person's edits are
+ * measured from when its response comes back (the "Reconciliation per operation" table).
+ * - `settle`: a flush policy. The hold starts immediately. Sending policies drain a
+ *   frozen checkpoint under that hold; later typing waits. `grant-wait` sends nothing
+ *   and waits only for requests already out before the operation writes.
+ * - `since`: `baseline` keeps every edit (publish, schedule, cancel); `displayed` makes
+ *   the edits present when the person confirmed part of what the operation throws away
+ *   (discard draft, rows X1–X4). Delete applies nothing: on success the editor goes.
+ */
+type LifecycleReconciliation = Readonly<{
+    settle: FlushPolicy;
+    since: 'baseline' | 'displayed';
+}>;
+export declare const LIFECYCLE_RECONCILIATION: Readonly<Record<HeldOperation, LifecycleReconciliation>>;
+/** What the document's values were when the hold started, for the response's rebase. */
+export type DocumentSince = Readonly<{
+    metadata: OwnWriteSince<EditorValueRecord | null>;
+    content: OwnWriteSince<EditorValueRecord | null>;
+    blocks: ReadonlyMap<EditorBlockId, OwnWriteSince<EditorBlockValues | null>>;
+}>;
+export declare function documentSince(state: EditorUiState, kind: LifecycleReconciliation['since']): DocumentSince;
+/**
+ * Runs a document lifecycle operation under the store's lifecycle status: running while
+ * it's under way, then idle or failed with its typed failure, which the banner and the
+ * status derive from. A rejected request is the operation's `server` failure; callers
+ * get the outcome rather than a throw.
+ */
+export declare function runLifecycle(uiStore: EditorUiStoreInstance, operation: LifecycleOperation, action: () => Promise<LifecycleOutcome>): Promise<LifecycleOutcome>;
+/** Waits until the values are settled under `policy`; a refusal is the operation's failure. */
+export declare function flushBefore(uiStore: EditorUiStoreInstance, policy: FlushPolicy, drain?: LifecycleDrain): Promise<LifecycleOutcome | null>;
+export type HeldLifecycle = Readonly<{
+    operation: HeldOperation;
+    /** A refusal before anything settles or is held (publish's validation), else null. */
+    precheck?: () => LifecycleOutcome | null;
+    /**
+     * The request, and applying its response (as own writes rebased against `since`).
+     * The document is held throughout; the hold ends when this settles.
+     */
+    write: (since: DocumentSince) => Promise<LifecycleOutcome>;
+}>;
+/**
+ * Runs a held operation: its precheck, what it settles first, then its request with the
+ * document held. Edits typed during the hold aren't sent; once the hold ends they're
+ * rebased on the response and autosave sends them against the new revision (rows R2, X3).
+ * On failure nothing was applied, so they send as usual (row X5).
+ */
+export declare function runHeldLifecycle(uiStore: EditorUiStoreInstance, lifecycle: HeldLifecycle): Promise<LifecycleOutcome>;
+export {};

package/dist/_dts/content-editor/src/sync/schedulerValues.d.ts

@@ -0,0 +1,27 @@
+import type { EditorUiState } from '../ui/editorUiStore';
+import type { AutosaveStatus, AutosaveType } from '../ui/stores/types';
+import { type ScheduledValue, type SchedulerValue, type LifecycleDrain } from './sendPlanning';
+import { type FailureFacts } from './lifecycleFailure';
+/**
+ * Loads the planners' inputs from the editor store: every value with the scheduler that
+ * saves it. The document's own linked entry is its content, so it is listed once.
+ */
+export declare function scheduledValues(state: EditorUiState): readonly ScheduledValue[];
+/**
+ * Every value with whether this tab may send it now. A document value (metadata, content,
+ * a block) isn't writable while a lifecycle operation holds the document: the operation
+ * writes the same route or draft, so edits typed meanwhile wait and send once it ends
+ * (rows R2, X3). Linked entries have their own revisions and aren't held.
+ */
+export declare function schedulerValues(state: EditorUiState, drain?: LifecycleDrain): readonly SchedulerValue[];
+/**
+ * The derived autosave status, for one scheduler or the whole document. The document
+ * lifecycle counts toward metadata and the whole.
+ */
+export declare function selectAutosaveStatus(state: EditorUiState, scheduler?: AutosaveType): AutosaveStatus;
+/**
+ * The error banner (rows B1–B7), from the same active failure as the status.
+ * `publishBlockedMessage` is the current publish validation message while it blocks.
+ */
+export declare function selectBannerMessage(state: EditorUiState, publishBlockedMessage: string | null): string | null;
+export declare function failureFacts(state: EditorUiState, publishBlockedMessage: string | null): FailureFacts;

package/dist/_dts/content-editor/src/sync/sendPlanning.d.ts

@@ -0,0 +1,104 @@
+import type { EditorValueRecord, SendId, ValueSync } from '../../../core/src/index';
+import type { EditorValueKey } from '../ui/editorSnapshot';
+import type { AutosaveStatus, AutosaveType, LifecycleStatus } from '../ui/stores/types';
+import { type SendMode } from './valueSync';
+import type { ActiveFailure } from './lifecycleFailure';
+/**
+ * Pure planners over the editor's values (issue 1553): what autosave sends, when a
+ * flush is done, and the status the status bars show. The store loads the inputs
+ * (`schedulerValues`); the hooks and `flushValues` perform the effects.
+ */
+/** One value as the planners see it. */
+export type ScheduledValue = Readonly<{
+    key: EditorValueKey;
+    scheduler: AutosaveType;
+    sync: ValueSync<EditorValueRecord | null>;
+}>;
+/** A value plus whether this tab may send it now. */
+export type SchedulerValue = ScheduledValue & Readonly<{
+    /** The tab holds write authority for it (`canWriteDraftTarget`). */
+    writable: boolean;
+    /** Its values may be sent: blocks pass validation, metadata has a title. */
+    saveable: boolean;
+}>;
+/** How a flush treats a failed value: Save draft retries it, publish refuses, a grant only waits. */
+export type FlushPolicy = 'save-draft' | 'publish' | 'grant-wait';
+export type LifecycleDrain = Extract<LifecycleStatus, {
+    kind: 'holding';
+}>;
+export type FlushCheckpoint = Readonly<{
+    key: EditorValueKey;
+    values: EditorValueRecord | null;
+    saveable: boolean;
+    drain?: LifecycleDrain;
+}>;
+export type SendAcknowledgement = Readonly<{
+    key: EditorValueKey;
+    values: EditorValueRecord | null;
+    kind: 'accepted' | 'failed' | 'blocked';
+}>;
+export type FlushRequest = Readonly<{
+    scheduler: AutosaveType;
+    keys: readonly EditorValueKey[];
+    checkpoints?: readonly FlushCheckpoint[];
+    signal?: AbortSignal;
+}>;
+export type FlushPlan = Readonly<{
+    kind: 'ready';
+}> | Readonly<{
+    kind: 'wait';
+}> | Readonly<{
+    kind: 'send';
+    requests: readonly FlushRequest[];
+}> | Readonly<{
+    kind: 'failed';
+    keys: readonly EditorValueKey[];
+}> | Readonly<{
+    kind: 'blocked';
+    keys: readonly EditorValueKey[];
+}>;
+/** How a flush finished. */
+export type FlushResult = Exclude<FlushPlan, Readonly<{
+    kind: 'wait' | 'send';
+}>>;
+/** The values that may send now: edited, writable, saveable and allowed by `canSend`. */
+export declare function planSends(values: readonly SchedulerValue[], mode: SendMode): readonly SchedulerValue[];
+/**
+ * What an autosave trigger watches: each sendable value with its displayed values and
+ * request. It changes on an edit, when a request settles with newer edits, and when a
+ * value becomes writable again (rows S2, S5, D2).
+ */
+export type SendSignature = readonly unknown[];
+export declare function sendSignature(sendable: readonly SchedulerValue[]): SendSignature;
+export declare function sameSignature(left: SendSignature, right: SendSignature): boolean;
+export declare function valueKeyId(key: EditorValueKey): string;
+/**
+ * Whether "saved before X" holds yet. Outstanding requests (in flight or abandoned)
+ * are waited for; sendable values are sent; what can never send ends the flush.
+ * `retrying` holds the failures this flush may send again (Save draft, row S3b).
+ */
+export declare function planFlush(values: readonly SchedulerValue[], policy: FlushPolicy, retrying?: ReadonlySet<SendId>): FlushPlan;
+/** The failures a flush sends again: those it was asked to retry. */
+export declare function retryableFailures(values: readonly ScheduledValue[]): ReadonlySet<SendId>;
+export type AutosaveStatusInput = Readonly<{
+    syncs: readonly ValueSync<EditorValueRecord | null>[];
+    lifecycle: LifecycleStatus;
+    /** The lifecycle failure that still holds (`activeFailure`), the same one the banner reads. */
+    failure: ActiveFailure | null;
+    lastSavedAt: string | null;
+}>;
+/**
+ * The autosave status the status bars show, derived from the values' states plus the
+ * document lifecycle. A failure outranks saving, as the per-scheduler statuses it
+ * replaced did. Of the lifecycle failures only a refused request (`server`) is an error
+ * here: failed values already count through their own states, and blocked or invalid
+ * values are the banner's alone (rows B4, B5).
+ */
+export declare function deriveAutosaveStatus(input: AutosaveStatusInput): AutosaveStatus;
+/** An operation is under way: settling what it needs first, or holding while its request is out. */
+export declare function isLifecycleRunning(lifecycle: LifecycleStatus): boolean;
+/**
+ * The message of the first value whose save failed, which the error banner shows. It's
+ * null once no value is failed (a retry succeeded, the edit went back, or was discarded).
+ */
+export declare function saveFailureMessage(values: readonly ScheduledValue[]): string | null;

package/dist/_dts/content-editor/src/sync/valueSync.d.ts

@@ -0,0 +1,114 @@
+import type { BaselineRevision, EditorValueRecord, SaveFailure, SendId, ValueBaseline, ValueSync } from '../../../core/src/index';
+export { displayedValues, syncStateOf, valueStatus, type ValueStatus } from '../../../core/src/index';
+/**
+ * The one sync model for editor values (issue 1553). Metadata, content, blocks and
+ * linked entries all move through `applyValueSyncEvent`; every rule here is a row in
+ * the plan's sequence tables and in `valueSync.test.ts`. Pure: the clock and send ids
+ * come in as event data.
+ */
+export type SyncValues = EditorValueRecord | null;
+/** Values at the operation boundary, and the server baseline they were based on. */
+export type OwnWriteSince<V extends SyncValues> = Readonly<{
+    values: V;
+    basis: BaselineRevision;
+}>;
+/**
+ * How a refresh (a server read) treats a value the person has edited:
+ * - keep-local: an ordinary refresh; the edits stay.
+ * - take-back: the tab regained the lease; the edits survive only if nobody else changed the value.
+ * - replace: the server draft was discarded; the edits go.
+ *
+ * A response to this tab's own write isn't a read: it's the `own-write` event, rebased
+ * rather than refreshed (`rebaseOnOwnWrite`).
+ */
+export type RefreshPolicy = 'keep-local' | 'take-back' | 'replace';
+export type ValueSyncEvent<V extends SyncValues> = Readonly<{
+    kind: 'edited';
+    values: V;
+}> | Readonly<{
+    kind: 'send-started';
+    id: SendId;
+    checkpoint?: V;
+}> | Readonly<{
+    kind: 'send-succeeded';
+    id: SendId;
+    values: V;
+    revision: BaselineRevision;
+    at: string;
+    published?: Readonly<{
+        kind: 'known';
+        values: V;
+    } | {
+        kind: 'unknown';
+    }>;
+}> | Readonly<{
+    kind: 'send-failed';
+    id: SendId;
+    failure: SaveFailure;
+}> | Readonly<{
+    kind: 'discarded';
+}> | Readonly<{
+    kind: 'refreshed';
+    baseline: ValueBaseline<V>;
+    policy: RefreshPolicy;
+}>
+/** This tab's own write returned `baseline`; `since` is what the person's edits are measured from. */
+ | Readonly<{
+    kind: 'own-write';
+    baseline: ValueBaseline<V>;
+    since: OwnWriteSince<V>;
+}>;
+/** `accepted` records `lastSavedAt`; `discarded` asks for the "edited in another tab" notice. */
+export type ValueSyncOutcome = Readonly<{
+    kind: 'none';
+}> | Readonly<{
+    kind: 'accepted';
+    at: string;
+}> | Readonly<{
+    kind: 'discarded';
+}>;
+export type ValueSyncTransition<V extends SyncValues> = Readonly<{
+    sync: ValueSync<V>;
+    outcome: ValueSyncOutcome;
+}>;
+/** `background` sends leave a failure alone until its values change; `explicit` retries it. */
+export type SendMode = 'background' | 'explicit';
+export declare function applyValueSyncEvent<V extends SyncValues>(sync: ValueSync<V>, event: ValueSyncEvent<V>): ValueSyncTransition<V>;
+/** Send ids are unique per store; the store's closure owns the only allocator. */
+export declare function createSendIdAllocator(): () => SendId;
+export declare function isEdited<V extends SyncValues>(sync: ValueSync<V>): boolean;
+/** A request is in flight or abandoned: flushes and grants wait for it to settle. */
+export declare function hasOutstandingRequest<V extends SyncValues>(sync: ValueSync<V>): boolean;
+/** The baseline revision as the wire carries it; `undefined` until the editor receives one. */
+export declare function revisionValue(revision: BaselineRevision): string | null | undefined;
+export declare function baselineRevisionOf<V extends SyncValues>(sync: ValueSync<V>): string | null | undefined;
+/** An optional wire revision (`undefined` means none was received) as a `BaselineRevision`. */
+export declare function revisionFromWire(value: string | null | undefined): BaselineRevision;
+/**
+ * Whether a send may start. A failure waits for new values in the background, so a
+ * rejected save isn't retried in a loop; an explicit Save draft retries it.
+ */
+export declare function canSend<V extends SyncValues>(sync: ValueSync<V>, mode: SendMode): boolean;
+/**
+ * The same server baseline, for take-back. Two revisions decide it when both are
+ * present; otherwise the revisions (possibly missing) and the values must both match.
+ */
+export declare function sameServerBaseline<V extends SyncValues>(left: ValueBaseline<V>, right: ValueBaseline<V>): boolean;
+export declare function valueSyncEqual<V extends SyncValues>(left: ValueSync<V>, right: ValueSync<V>): boolean;
+/**
+ * Undo and redo restore what the person sees, never sync state: the target's displayed
+ * values become an edit over the present baseline and request (row U1, U2).
+ */
+export declare function restoreDisplayedValues<V extends SyncValues>(present: ValueSync<V>, target: ValueSync<V>): ValueSync<V>;
+/** A record brought back from history: its request is long gone (row U3). */
+export declare function withIdleRequest<V extends SyncValues>(sync: ValueSync<V>): ValueSync<V>;
+/**
+ * A response to this tab's own write (publish, schedule, cancel, discard). The displayed
+ * value keeps changes since the operation's snapshot: an edit is any
+ * top-level key whose presence or value differs between `since` and the local values, so
+ * a removed key stays removed and a key set to `null` counts. Nested values are whole
+ * fields (no deep merge), and where both sides changed a key the person's edit wins.
+ * Keys the person didn't touch take the server's value, including its removals. The
+ * request is kept: one based on the old revision isn't accepted over the new one (R6).
+ */
+export declare function rebaseOnOwnWrite<V extends SyncValues>(sync: ValueSync<V>, server: ValueBaseline<V>, since: OwnWriteSince<V>): ValueSync<V>;

package/dist/_dts/content-editor/src/ui/blockCollection.d.ts

@@ -0,0 +1,8 @@
+import { type EditorBlockCollectionOwner, type EditorBlockCollectionReadBaseline } from '../../../core/src/index';
+import { type DraftBlockRefresh, type EditorBlockItem, type EditorHistorySnapshot } from './editorSnapshot';
+/** A collection read enters through one boundary; a held lifecycle supplies its own result. */
+export declare function mountBlockCollection(snapshot: EditorHistorySnapshot, owner: EditorBlockCollectionOwner, blocks: readonly EditorBlockItem[], seeds: readonly DraftBlockRefresh[], held: boolean, reads?: readonly EditorBlockCollectionReadBaseline[]): EditorHistorySnapshot;
+export declare function unmountBlockCollection(snapshot: EditorHistorySnapshot, owner: EditorBlockCollectionOwner): EditorHistorySnapshot;
+/** Query facts are not history edits; a held write will supply the authoritative receipt. */
+export declare function refreshCollectionReadBaselines(snapshot: EditorHistorySnapshot, reads: readonly EditorBlockCollectionReadBaseline[], held?: boolean): EditorHistorySnapshot;
+export declare function hasUnpublishedCollectionChanges(snapshot: EditorHistorySnapshot): boolean;

package/dist/_dts/content-editor/src/ui/documentLifecycle.d.ts

@@ -0,0 +1,18 @@
+import type { DocumentBlockState } from '../../../api/src/content-editor';
+import { type BlockFieldExtensions } from '../../../editor-blocks/src/block-editor/blockDraftBaselineSeed';
+import type { DocumentSince } from '../sync/runLifecycle';
+import { type OwnWrite, type PublishSuccessRefresh } from './editorRefresh';
+import { type EditorHistorySnapshot } from './editorSnapshot';
+/** A complete document operation always reconciles its block collections too. */
+export type DocumentLifecycleResult = Readonly<{
+    blockState: DocumentBlockState;
+    since: DocumentSince;
+}> & (Readonly<{
+    operation: 'publish';
+    values: PublishSuccessRefresh;
+}> | Readonly<{
+    operation: 'discard';
+    values: readonly OwnWrite[];
+}>);
+/** Apply one receipt atomically: entry values, block values and block membership. */
+export declare function documentLifecycleSnapshot(snapshot: EditorHistorySnapshot, result: DocumentLifecycleResult, extensions?: BlockFieldExtensions | null): EditorHistorySnapshot;

package/dist/_dts/content-editor/src/ui/editorLeaseUiState.d.ts

@@ -0,0 +1,7 @@
+import type { EditorEditability } from '../controller/editorEditability';
+export type EditorLeaseUiState = {
+    editability: EditorEditability;
+    setEditability: (editability: EditorEditability) => void;
+    leaseDiscardedChanges: boolean;
+    setLeaseDiscardedChanges: (discarded: boolean) => void;
+};

package/dist/_dts/content-editor/src/ui/editorRefresh.d.ts

@@ -0,0 +1,82 @@
+import { type EditorBlockValues, type EditorBlockVersions, type EditorValueRecord } from '../../../core/src/index';
+import type { OwnWriteSince, RefreshPolicy } from '../sync/valueSync';
+import { type DraftBlockRefresh, type EditorHistorySnapshot } from './editorSnapshot';
+/**
+ * A server read of one value, applied as a `refreshed` sync event (issue 1553). Every path
+ * that sets a baseline without a save response goes through here: the RSC reconciliation
+ * hooks, block seeding, both grant reads and discard draft. Responses to this tab's own
+ * writes are rebased instead (`OwnWrite`).
+ *
+ * A metadata or content refresh without a `revision` keeps the baseline's own: publish and
+ * discard-draft responses don't always carry one, and wiping it would make the next save
+ * fail. `published`, when present, moves the published baseline too.
+ */
+export type ValueRefresh = Readonly<{
+    kind: 'metadata' | 'content';
+    values: EditorValueRecord | null;
+    revision?: string | null;
+    published?: EditorValueRecord | null;
+}> | Readonly<{
+    kind: 'linked-entry';
+    entryId: string;
+    values: EditorValueRecord | null;
+    revision: string | null;
+}> | Readonly<{
+    kind: 'block';
+    block: DraftBlockRefresh;
+    versions?: EditorBlockVersions;
+}>;
+/** A metadata or content refresh, as the value's own facade takes it. */
+export type DocumentValueRefreshInput = Omit<Extract<ValueRefresh, {
+    kind: 'metadata' | 'content';
+}>, 'kind'>;
+/** `discarded` asks for the "edited in another tab" notice: a take-back threw local edits away. */
+export type RefreshTransition = Readonly<{
+    snapshot: EditorHistorySnapshot;
+    discarded: boolean;
+}>;
+export declare function refreshValuesSnapshot(snapshot: EditorHistorySnapshot, refreshes: readonly ValueRefresh[], policy: RefreshPolicy): RefreshTransition;
+/**
+ * What this tab's own write (publish, schedule, cancel, discard draft) returned for one
+ * document value. It's rebased rather than refreshed (`rebaseOnOwnWrite`): an edit typed
+ * during the round trip survives on top of the new baseline (rows P6, R1–R11, X1–X4).
+ * `since` is what the edits are measured from: the baseline when the operation started,
+ * or for discard what was displayed when the person confirmed. A missing `revision`
+ * keeps the baseline's own, as a refresh does.
+ */
+export type OwnWrite = DocumentOwnWrite | Readonly<{
+    kind: 'block';
+    block: DraftBlockRefresh;
+    since: OwnWriteSince<EditorBlockValues | null>;
+}>;
+type DocumentOwnWrite = Readonly<{
+    kind: 'metadata' | 'content';
+    values: EditorValueRecord | null;
+    revision?: string | null;
+    published?: EditorValueRecord | null;
+    since: OwnWriteSince<EditorValueRecord | null>;
+}>;
+export declare function ownWritesSnapshot(snapshot: EditorHistorySnapshot, writes: readonly OwnWrite[]): EditorHistorySnapshot;
+/**
+ * What a successful publish tells the editor. Metadata is the route the publish wrote.
+ * Content is what it wrote (`written`), or `unchanged` when it wrote none, in which case
+ * the content baseline and revision stay and only its published baseline moves (WR5b).
+ */
+export type PublishSuccessRefresh = Readonly<{
+    metadata: Omit<DocumentOwnWrite, 'kind'> & Readonly<{
+        published: EditorValueRecord | null;
+    }>;
+    content: Readonly<{
+        published: EditorValueRecord | null;
+        write: Readonly<{
+            kind: 'written';
+            values: EditorValueRecord;
+            revision: string;
+            since: OwnWriteSince<EditorValueRecord | null>;
+        }> | Readonly<{
+            kind: 'unchanged';
+        }>;
+    }>;
+}>;
+export declare function publishSuccessSnapshot(snapshot: EditorHistorySnapshot, publish: PublishSuccessRefresh): EditorHistorySnapshot;
+export {};