@widgetic/editor 4.1.10 → 4.1.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -11,6 +11,9 @@
11
11
  * - a save carries an `Idempotency-Key` (the API requires one on every PUT from a session), kept the same when
12
12
  * the request is sent again after a 401, so one save is never applied twice;
13
13
  * - only the fields editing changes can be sent (`SaveCompositionBody`); a session is refused any other;
14
+ * - a save can name the content version it was made from (`ifMatchVersion`, sent as `If-Match`). When somebody
15
+ * else saved the content since, the API refuses it (412 `CONTENT_VERSION_MISMATCH`, with the version it holds
16
+ * now in `details`) instead of replacing their work, and the error says so (`versionConflict`);
14
17
  * - every failure is a `CompositionApiError` with the API's own code, so the host can tell an ended session
15
18
  * (`EDITOR_SESSION_EXPIRED`...) from a missing composition (`NOT_FOUND`) from a widget that was never
16
19
  * published (`WIDGET_NOT_PUBLISHED`);
@@ -59,6 +62,54 @@ export interface CompositionRequestOptions {
59
62
  export interface SaveCompositionOptions extends CompositionRequestOptions {
60
63
  /** Identifies this save. Give the same key to send the same save again; default: a new one. */
61
64
  idempotencyKey?: string;
65
+ /**
66
+ * The content version this save was made from: the `contentVersion` the composition had when it was read, or the one
67
+ * the last save answered with. It goes in the `If-Match` header, so that a save made on a copy somebody else has saved
68
+ * over since is refused (412) instead of replacing their work. The API checks it only for a save that carries
69
+ * `content`. Left out, the save is made without the check.
70
+ */
71
+ ifMatchVersion?: number;
72
+ }
73
+ /**
74
+ * What the API says about who is editing a composition (`/edit-leases/composition/{id}`): the answer to asking to edit,
75
+ * to taking over, and to looking. It is presence, never a lock: no save is ever refused because of it.
76
+ *
77
+ * - `held`: this tab is the one editing (its claim lasts `ttlSeconds` from now and is renewed every `heartbeatSeconds`);
78
+ * - `held_by_other`: somebody else is editing (`holder`), in another window of the same account or in a teammate's;
79
+ * - `free`: nobody is editing (only a look says that: asking to edit answers `held`);
80
+ * - `not_applicable`: this composition has no presence (a personal one, or the feature is off): edit freely, say nothing;
81
+ * - `unavailable`: the API could not tell right now: edit freely and ask again later.
82
+ */
83
+ export type EditLeaseOutcomeName = 'held' | 'held_by_other' | 'free' | 'not_applicable' | 'unavailable';
84
+ /** Whoever holds an edit claim. The API gives a name only for a teammate who is a person, never an email. */
85
+ export interface EditLeaseHolder {
86
+ id: string;
87
+ /** The holder's name, or `null` when the API had none to give (say "Someone"). */
88
+ name: string | null;
89
+ /** The holder is the signed-in person's own account, in another window. */
90
+ isYou: boolean;
91
+ /** When the holder began editing (an ISO date), when the API said. */
92
+ since: string | null;
93
+ }
94
+ export interface EditLeaseAnswer {
95
+ outcome: EditLeaseOutcomeName;
96
+ /** How long a claim lasts without a renewal, in seconds. */
97
+ ttlSeconds?: number;
98
+ /** How often to renew it, in seconds. */
99
+ heartbeatSeconds?: number;
100
+ since?: string | null;
101
+ /** Who holds the claim, for `held_by_other` (and for `held`: this person). */
102
+ holder?: EditLeaseHolder;
103
+ /** Who the claim was taken from, when taking over displaced somebody. */
104
+ tookOverFrom?: EditLeaseHolder;
105
+ }
106
+ /** Options of a call that gives up the claim. */
107
+ export interface ReleaseEditLeaseOptions extends CompositionRequestOptions {
108
+ /**
109
+ * Lets the request finish after the page is gone (`fetch` `keepalive`): for the moment a tab is closed, when the
110
+ * claim should end at once instead of expiring a minute later.
111
+ */
112
+ keepalive?: boolean;
62
113
  }
63
114
  export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
64
115
  /** Codes the client itself reports (the API's own codes, such as `NOT_FOUND`, are passed through as they are). */
@@ -71,11 +122,23 @@ export declare class CompositionApiError extends Error {
71
122
  readonly code: string;
72
123
  /** The API's correlation id for the failed request, to quote in a support request. */
73
124
  readonly correlationId?: string;
74
- constructor(message: string, details: {
125
+ /**
126
+ * What the API said besides the code and the message (`error.details`). A save refused because the content changed
127
+ * says there which version the API holds now (`currentVersion`) and, when it knows, who saved it and when.
128
+ */
129
+ readonly details?: JsonRecord;
130
+ constructor(message: string, info: {
75
131
  status: number;
76
132
  code: string;
77
133
  correlationId?: string;
134
+ details?: JsonRecord;
78
135
  });
136
+ /**
137
+ * True when a save was refused because somebody else saved the composition's content after it was read: the API
138
+ * answered 412 (the version sent is not the one it holds), or 409 for a write that raced another one. Sending the
139
+ * same save again would be refused again; the person has to choose between the two versions.
140
+ */
141
+ get versionConflict(): boolean;
79
142
  /** True when the editor session cannot be used any more: the host page has to give a new one. */
80
143
  get sessionEnded(): boolean;
81
144
  /** True when sending the same request again later may work: nothing was refused, the network or the server failed. */
@@ -88,8 +151,24 @@ export interface CompositionApi {
88
151
  getContentSchema(compositionId: string, options?: CompositionRequestOptions): Promise<unknown>;
89
152
  getDesignSchema(compositionId: string, options?: CompositionRequestOptions): Promise<unknown>;
90
153
  saveComposition(compositionId: string, body: SaveCompositionBody, options?: SaveCompositionOptions): Promise<JsonRecord>;
154
+ /**
155
+ * Says this tab (`sessionId`: one per open editor) is editing, and renews that claim when it already is.
156
+ * Answers `held`, or `held_by_other` when somebody else holds it (nothing is taken from them).
157
+ */
158
+ acquireEditLease(compositionId: string, sessionId: string, options?: CompositionRequestOptions): Promise<EditLeaseAnswer>;
159
+ /** Takes the claim from whoever holds it, at once. Answers `held`, and who it was taken from (`tookOverFrom`). */
160
+ takeOverEditLease(compositionId: string, sessionId: string, options?: CompositionRequestOptions): Promise<EditLeaseAnswer>;
161
+ /** Looks at who is editing without claiming anything: `held_by_other` (whoever holds it, even this person's other window) or `free`. */
162
+ peekEditLease(compositionId: string, options?: CompositionRequestOptions): Promise<EditLeaseAnswer>;
163
+ /** Gives up this tab's claim (nothing happens when it holds none, or somebody else does now). */
164
+ releaseEditLease(compositionId: string, sessionId: string, options?: ReleaseEditLeaseOptions): Promise<void>;
91
165
  }
92
166
  /** A key that is unique, not secret: the page's `crypto.randomUUID`, else random bytes, else the clock and `Math.random`. */
93
167
  export declare function createRandomIdempotencyKey(): string;
168
+ /**
169
+ * What the API answered about an edit claim, checked. An answer the editor cannot read is `unavailable`: presence is a
170
+ * convenience, so the editor goes on as if it were not there rather than failing.
171
+ */
172
+ export declare function readEditLeaseAnswer(data: unknown): EditLeaseAnswer;
94
173
  /** Builds the client. `apiBasePath` and `getAccessToken` are required. */
95
174
  export declare function createCompositionApi(options: CompositionApiOptions): CompositionApi;
@@ -11,6 +11,9 @@
11
11
  * - a save carries an `Idempotency-Key` (the API requires one on every PUT from a session), kept the same when
12
12
  * the request is sent again after a 401, so one save is never applied twice;
13
13
  * - only the fields editing changes can be sent (`SaveCompositionBody`); a session is refused any other;
14
+ * - a save can name the content version it was made from (`ifMatchVersion`, sent as `If-Match`). When somebody
15
+ * else saved the content since, the API refuses it (412 `CONTENT_VERSION_MISMATCH`, with the version it holds
16
+ * now in `details`) instead of replacing their work, and the error says so (`versionConflict`);
14
17
  * - every failure is a `CompositionApiError` with the API's own code, so the host can tell an ended session
15
18
  * (`EDITOR_SESSION_EXPIRED`...) from a missing composition (`NOT_FOUND`) from a widget that was never
16
19
  * published (`WIDGET_NOT_PUBLISHED`);
@@ -20,6 +23,8 @@ import { unwrapApiData } from './compositionHelpers.js';
20
23
  export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
21
24
  /** What the API accepts as an idempotency key. */
22
25
  const IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9_-]{8,50}$/;
26
+ /** What the API accepts as the id of an editor tab (an edit claim's `sessionId`). */
27
+ const EDIT_LEASE_SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{8,64}$/;
23
28
  /** A request to the API that did not give the answer wanted. */
24
29
  export class CompositionApiError extends Error {
25
30
  /** The HTTP status; `0` when no answer arrived (network, timeout, abort, or no token to send). */
@@ -28,12 +33,28 @@ export class CompositionApiError extends Error {
28
33
  code;
29
34
  /** The API's correlation id for the failed request, to quote in a support request. */
30
35
  correlationId;
31
- constructor(message, details) {
36
+ /**
37
+ * What the API said besides the code and the message (`error.details`). A save refused because the content changed
38
+ * says there which version the API holds now (`currentVersion`) and, when it knows, who saved it and when.
39
+ */
40
+ details;
41
+ constructor(message, info) {
32
42
  super(message);
33
43
  this.name = 'CompositionApiError';
34
- this.status = details.status;
35
- this.code = details.code;
36
- this.correlationId = details.correlationId;
44
+ this.status = info.status;
45
+ this.code = info.code;
46
+ this.correlationId = info.correlationId;
47
+ this.details = info.details;
48
+ }
49
+ /**
50
+ * True when a save was refused because somebody else saved the composition's content after it was read: the API
51
+ * answered 412 (the version sent is not the one it holds), or 409 for a write that raced another one. Sending the
52
+ * same save again would be refused again; the person has to choose between the two versions.
53
+ */
54
+ get versionConflict() {
55
+ return (this.status === 412 ||
56
+ this.code === 'CONTENT_VERSION_MISMATCH' ||
57
+ this.code === 'CONTENT_WRITE_CONFLICT');
37
58
  }
38
59
  /** True when the editor session cannot be used any more: the host page has to give a new one. */
39
60
  get sessionEnded() {
@@ -53,6 +74,7 @@ const STATUS_CODES = {
53
74
  403: 'FORBIDDEN',
54
75
  404: 'NOT_FOUND',
55
76
  409: 'CONFLICT',
77
+ 412: 'PRECONDITION_FAILED',
56
78
  429: 'RATE_LIMITED'
57
79
  };
58
80
  /** A code for an error status the API gave no code with. */
@@ -90,6 +112,57 @@ function throwIfAborted(signal) {
90
112
  throw new CompositionApiError('The request was cancelled.', { status: 0, code: 'ABORTED' });
91
113
  }
92
114
  }
115
+ /** True for a number of seconds worth believing: a positive, finite number. */
116
+ function isSeconds(value) {
117
+ return typeof value === 'number' && Number.isFinite(value) && value > 0;
118
+ }
119
+ /** Whoever holds an edit claim, as the API wrote it; `undefined` when what came is no holder. */
120
+ function readEditLeaseHolder(value) {
121
+ if (!isRecord(value) || typeof value.id !== 'string' || value.id === '')
122
+ return undefined;
123
+ const name = typeof value.name === 'string' ? value.name.trim() : '';
124
+ return {
125
+ id: value.id,
126
+ name: name === '' ? null : name.slice(0, 120),
127
+ isYou: value.isYou === true,
128
+ since: typeof value.since === 'string' ? value.since : null
129
+ };
130
+ }
131
+ const EDIT_LEASE_OUTCOMES = [
132
+ 'held',
133
+ 'held_by_other',
134
+ 'free',
135
+ 'not_applicable',
136
+ 'unavailable'
137
+ ];
138
+ /**
139
+ * What the API answered about an edit claim, checked. An answer the editor cannot read is `unavailable`: presence is a
140
+ * convenience, so the editor goes on as if it were not there rather than failing.
141
+ */
142
+ export function readEditLeaseAnswer(data) {
143
+ if (!isRecord(data))
144
+ return { outcome: 'unavailable' };
145
+ const outcome = EDIT_LEASE_OUTCOMES.find((name) => name === data.outcome);
146
+ if (!outcome)
147
+ return { outcome: 'unavailable' };
148
+ const answer = { outcome };
149
+ if (isSeconds(data.ttlSeconds))
150
+ answer.ttlSeconds = data.ttlSeconds;
151
+ if (isSeconds(data.heartbeatSeconds))
152
+ answer.heartbeatSeconds = data.heartbeatSeconds;
153
+ // (Two branches, not one test: where `null` is not tracked as a type, a test for it does not narrow `unknown`.)
154
+ if (typeof data.since === 'string')
155
+ answer.since = data.since;
156
+ else if (data.since === null)
157
+ answer.since = null;
158
+ const holder = readEditLeaseHolder(data.holder);
159
+ if (holder)
160
+ answer.holder = holder;
161
+ const tookOverFrom = readEditLeaseHolder(data.tookOverFrom);
162
+ if (tookOverFrom)
163
+ answer.tookOverFrom = tookOverFrom;
164
+ return answer;
165
+ }
93
166
  /** Builds the client. `apiBasePath` and `getAccessToken` are required. */
94
167
  export function createCompositionApi(options) {
95
168
  if (typeof options?.apiBasePath !== 'string' || options.apiBasePath.trim() === '') {
@@ -146,6 +219,8 @@ export function createCompositionApi(options) {
146
219
  headers['Content-Type'] = 'application/json';
147
220
  if (extras.idempotencyKey)
148
221
  headers['Idempotency-Key'] = extras.idempotencyKey;
222
+ if (extras.ifMatch)
223
+ headers['If-Match'] = extras.ifMatch;
149
224
  try {
150
225
  const response = await fetchImplementation(url, {
151
226
  method,
@@ -155,7 +230,9 @@ export function createCompositionApi(options) {
155
230
  credentials: 'omit',
156
231
  // What a composition holds changes with every save; never serve it from a cache.
157
232
  cache: 'no-store',
158
- signal: controller.signal
233
+ signal: controller.signal,
234
+ // Only a request that must outlive the page asks for it (the claim given up as a tab closes).
235
+ ...(extras.keepalive ? { keepalive: true } : {})
159
236
  });
160
237
  const text = await response.text();
161
238
  return { status: response.status, ok: response.ok, text };
@@ -200,7 +277,13 @@ export function createCompositionApi(options) {
200
277
  ? failure.message
201
278
  : `The API answered ${answer.status}.`;
202
279
  const correlationId = typeof failure?.correlationId === 'string' ? failure.correlationId : undefined;
203
- throw new CompositionApiError(message, { status: answer.status, code, correlationId });
280
+ const details = isRecord(failure?.details) ? failure.details : undefined;
281
+ throw new CompositionApiError(message, {
282
+ status: answer.status,
283
+ code,
284
+ correlationId,
285
+ details
286
+ });
204
287
  }
205
288
  if (parsed === undefined) {
206
289
  throw new CompositionApiError('The API gave an answer that is not JSON.', {
@@ -237,6 +320,20 @@ export function createCompositionApi(options) {
237
320
  function invalidResponse(message) {
238
321
  return new CompositionApiError(message, { status: 200, code: 'INVALID_RESPONSE' });
239
322
  }
323
+ /** The address of a composition's edit claim, with `suffix` after it. */
324
+ function leasePath(compositionId, suffix = '') {
325
+ if (typeof compositionId !== 'string' || compositionId.trim() === '') {
326
+ throw new TypeError('A composition id is needed');
327
+ }
328
+ return `/edit-leases/composition/${encodeURIComponent(compositionId)}${suffix}`;
329
+ }
330
+ /** The tab's own id, which the API holds to a short plain alphabet; a bad one is a bug of the caller, never sent. */
331
+ function checkedSessionId(sessionId) {
332
+ if (typeof sessionId !== 'string' || !EDIT_LEASE_SESSION_ID_PATTERN.test(sessionId)) {
333
+ throw new TypeError('A session id is 8 to 64 letters, digits, dashes or underscores');
334
+ }
335
+ return sessionId;
336
+ }
240
337
  return {
241
338
  async getComposition(compositionId, requestOptions = {}) {
242
339
  const record = await request('GET', compositionPath(compositionId), requestOptions);
@@ -278,12 +375,40 @@ export function createCompositionApi(options) {
278
375
  if (!IDEMPOTENCY_KEY_PATTERN.test(idempotencyKey)) {
279
376
  throw new TypeError('An idempotency key is 8 to 50 letters, digits, dashes or underscores');
280
377
  }
378
+ const { ifMatchVersion } = saveOptions;
379
+ if (ifMatchVersion !== undefined &&
380
+ !(Number.isSafeInteger(ifMatchVersion) && ifMatchVersion >= 0)) {
381
+ throw new TypeError('A content version is a whole number of zero or more');
382
+ }
281
383
  const record = await request('PUT', compositionPath(compositionId), {
282
384
  body,
283
385
  signal: saveOptions.signal,
284
- idempotencyKey
386
+ idempotencyKey,
387
+ // Quoted, the way the API writes the ETag of a composition.
388
+ ifMatch: ifMatchVersion === undefined ? undefined : `"${ifMatchVersion}"`
285
389
  });
286
390
  return isRecord(record) ? record : {};
391
+ },
392
+ async acquireEditLease(compositionId, sessionId, requestOptions = {}) {
393
+ const answer = await request('PUT', leasePath(compositionId), {
394
+ body: { sessionId: checkedSessionId(sessionId) },
395
+ signal: requestOptions.signal
396
+ });
397
+ return readEditLeaseAnswer(answer);
398
+ },
399
+ async takeOverEditLease(compositionId, sessionId, requestOptions = {}) {
400
+ const answer = await request('POST', leasePath(compositionId, '/take-over'), {
401
+ body: { sessionId: checkedSessionId(sessionId) },
402
+ signal: requestOptions.signal
403
+ });
404
+ return readEditLeaseAnswer(answer);
405
+ },
406
+ async peekEditLease(compositionId, requestOptions = {}) {
407
+ const answer = await request('GET', leasePath(compositionId), requestOptions);
408
+ return readEditLeaseAnswer(answer);
409
+ },
410
+ async releaseEditLease(compositionId, sessionId, releaseOptions = {}) {
411
+ await request('DELETE', leasePath(compositionId, `?sessionId=${encodeURIComponent(checkedSessionId(sessionId))}`), { signal: releaseOptions.signal, keepalive: releaseOptions.keepalive });
287
412
  }
288
413
  };
289
414
  }
@@ -18,11 +18,26 @@
18
18
  * (the session ended, the field is refused) is not.
19
19
  * - The embed settings the composition already has (anything set by the site or by the partner's own backend)
20
20
  * are sent back with the new size, never replaced by it.
21
+ * - A save sends only what the person changed here: the content when settings or items were edited, the embed
22
+ * settings when the preview was given a size. The name is never sent (this editor cannot rename, and the name it
23
+ * loaded may be out of date). A save that carried everything would put back, unseen, whatever a teammate changed
24
+ * in the parts this person did not touch (the page this was taken from did exactly that).
25
+ * - A save that carries content names the content version it was made from (`If-Match`). When a teammate saved the
26
+ * content since, the API refuses it and the editor does NOT send it again: it keeps every edit, stops autosaving,
27
+ * and asks the person to choose (`state.conflict`): keep their own version (`keepMyChanges`, saved on top of the
28
+ * version the API holds now, which is read again first, so a third person's save is refused too and never
29
+ * replaced unseen) or load the latest one (`loadLatestVersion`, which drops their edits). Nothing is chosen for
30
+ * them. The version is adopted from a save's answer only when that save carried the content: the answer to a save
31
+ * of the embed settings alone may hold a teammate's newer version that this editor never loaded.
21
32
  * - The size that is saved is the one the user gave the preview (by dragging its corner or typing it in), and
22
33
  * nothing else. Looking at the preview as on a phone changes how it is drawn, not what is saved, and the
23
34
  * size a small box forces on the preview is not the user's choice, so it is never saved either (the page this
24
35
  * was taken from saved both, so opening a composition in a small window, or trying the mobile view, changed
25
36
  * the size of the widget embedded on a site).
37
+ * - A page that knows a teammate is editing the same composition (`EditLeaseController`) can block edits
38
+ * (`setEditsBlocked`): the props editor and the preview's resize then change nothing, however the call got there.
39
+ * Blocking is not locking: it never touches what was edited before it (that is saved as usual), and it never makes a
40
+ * save fail, so a teammate's presence can never cost a person their work.
26
41
  * - After `dispose()` nothing more happens: no request goes out, and answers still on their way are ignored.
27
42
  */
28
43
  import type { Translate } from '@widgetic/design-system/i18n';
@@ -55,6 +70,28 @@ export interface EditorFailure {
55
70
  /** The session cannot be used any more: the host page has to give a new one. */
56
71
  sessionEnded: boolean;
57
72
  correlationId?: string;
73
+ /** What the API said besides the code (`error.details`), when it said anything. A refused stale save names the version the API holds. */
74
+ details?: JsonRecord;
75
+ }
76
+ /** Which version the person chose after a refused save. */
77
+ export type ConflictResolution = 'keepMine' | 'loadLatest';
78
+ /** A save the API refused because somebody else saved the composition's content after this editor loaded it. */
79
+ export interface EditorConflict {
80
+ /** The content version the API holds now, when the refusal said so, else `null`. */
81
+ currentVersion: number | null;
82
+ /** Who saved it, when the API said (`{ id, name }`), else `null`. */
83
+ lastEditedBy: {
84
+ id?: string;
85
+ name?: string;
86
+ } | null;
87
+ /** When they saved it (the date as the API wrote it), when the API said, else `null`. */
88
+ lastEditedAt: string | null;
89
+ /** "Keep my changes" or "Load the latest version" is on its way. */
90
+ resolving: boolean;
91
+ /** Why the last attempt to resolve it failed, or `null`. The conflict stays, so the person can try again. */
92
+ resolveError: EditorFailure | null;
93
+ /** The API's correlation id for the refusal, to quote in a support request. */
94
+ correlationId?: string;
58
95
  }
59
96
  export interface CompositionEditorState {
60
97
  phase: EditorPhase;
@@ -87,8 +124,18 @@ export interface CompositionEditorState {
87
124
  /** There are edits no save has taken yet. */
88
125
  dirty: boolean;
89
126
  saving: boolean;
90
- /** The last save failed (cleared when the next one starts). */
127
+ /** The last save failed (cleared when the next one starts). A save refused because the content changed is a `conflict`, not this. */
91
128
  saveError: EditorFailure | null;
129
+ /**
130
+ * The last save was refused because a teammate saved the content since it was loaded. Every edit is kept and
131
+ * nothing is saved until the person chooses (`keepMyChanges` or `loadLatestVersion`). `null` when there is none.
132
+ */
133
+ conflict: EditorConflict | null;
134
+ /**
135
+ * The editor takes no new edit: a teammate is editing this composition, or the person chose to only look (see
136
+ * `setEditsBlocked`). What was edited before is still saved. The preview keeps working.
137
+ */
138
+ editsBlocked: boolean;
92
139
  /** The composition could not be loaded (`phase` is then `failed`). */
93
140
  loadError: EditorFailure | null;
94
141
  lastSavedAt: number | null;
@@ -107,6 +154,16 @@ export type CompositionEditorEvent = {
107
154
  during: 'load' | 'schemas' | 'save';
108
155
  failure: EditorFailure;
109
156
  fatal: boolean;
157
+ }
158
+ /** A save was refused because a teammate saved the content first (not an `error`: nothing is lost, the person chooses). */
159
+ | {
160
+ type: 'conflict';
161
+ conflict: EditorConflict;
162
+ }
163
+ /** The person chose a version; for `keepMine` the save that follows reports itself as `saved` or `error`. */
164
+ | {
165
+ type: 'conflictResolved';
166
+ resolution: ConflictResolution;
110
167
  };
111
168
  /** What the preview page is told when something changed. */
112
169
  export interface PreviewMessage {
@@ -178,6 +235,19 @@ export declare class CompositionEditorController {
178
235
  private failedAutosaves;
179
236
  /** The embed settings the composition has, sent back with the size on every save. */
180
237
  private storedEmbedSettings;
238
+ /**
239
+ * The content version the API held when this editor last read or wrote the content: what a save that carries
240
+ * content sends as `If-Match`. `null` when the API gave none (an API without versions): saves are then made
241
+ * without the check, as before.
242
+ */
243
+ private contentVersion;
244
+ /** Counts the edits of the content (settings and items), and of the size the composition is embedded at: a save sends the parts that changed. */
245
+ private contentRevision;
246
+ /** The content revision the last successful save took. */
247
+ private savedContentRevision;
248
+ private embedRevision;
249
+ /** The embed revision the last successful save took. */
250
+ private savedEmbedRevision;
181
251
  private autosaveTimer;
182
252
  /** What `getPropsEditorContentSchema` and `getPropsEditorContentValues` last made, and from what. */
183
253
  private propsEditorSchemaCache;
@@ -216,6 +286,13 @@ export declare class CompositionEditorController {
216
286
  /** Tells the preview page everything it needs to look like the composition (once its page has loaded). */
217
287
  syncPreview(): void;
218
288
  private buildPreviewSnapshot;
289
+ /**
290
+ * Says whether new edits are taken. While blocked (a teammate is editing this composition, or the person chose to
291
+ * only look) `changeProperty`, `changeContentItems` and a resize of the preview are ignored, so nothing can be
292
+ * saved over the teammate's work by a path the screen forgot to close. Edits made before are kept and saved as
293
+ * usual, and the preview, the device buttons and `adoptEmbedSettings` work as before: none of them is an edit.
294
+ */
295
+ setEditsBlocked(blocked: boolean): void;
219
296
  /** One property was changed in the props editor. */
220
297
  changeProperty(change: PropertyChange): void;
221
298
  /** The content items (slides, rows, cards...) were changed in the props editor. */
@@ -240,12 +317,17 @@ export declare class CompositionEditorController {
240
317
  */
241
318
  adoptEmbedSettings(settings: unknown): void;
242
319
  /**
243
- * The page renamed the composition itself (a page can have its own title field), so the name this editor loaded,
244
- * and sends back with every save, is out of date. From now on a save carries this one. Nothing becomes unsaved:
245
- * the page saved it already. Call it when no save of the editor is on its way (after `flush()`).
320
+ * The page renamed the composition itself (a page can have its own title field), so the name this editor loaded is
321
+ * out of date. From now on `getState().name` is this one. (A save never sends the name: this editor cannot rename,
322
+ * and sending the one it loaded would undo a rename made elsewhere.) Nothing becomes unsaved: the page saved it
323
+ * already. Call it when no save of the editor is on its way (after `flush()`).
246
324
  */
247
325
  adoptName(name: unknown): void;
248
- /** An edit was made: there is something new to save, the wait for the next autosave starts again, and so does the count of failures. */
326
+ /**
327
+ * An edit was made: there is something new to save, the wait for the next autosave starts again, and so does the count
328
+ * of failures. `part` says what it changed, because a save sends only what changed: the content (settings and items)
329
+ * or the size the composition is embedded at.
330
+ */
249
331
  private markEdited;
250
332
  private hasUnsavedChanges;
251
333
  /**
@@ -259,8 +341,26 @@ export declare class CompositionEditorController {
259
341
  */
260
342
  flush(): Promise<boolean>;
261
343
  private runSave;
262
- /** What a save sends: a copy of the values as they are now, so later edits cannot change it. */
344
+ /**
345
+ * What a save sends: a copy, taken now so later edits cannot change it, of the parts that changed since the last save.
346
+ * The content when settings or items were edited; the embed settings (the ones the composition has, with the new size)
347
+ * when the preview was given a size. The name is never sent: this editor cannot rename, so the name it holds is the
348
+ * one it loaded, and sending it back would undo a rename a teammate made since.
349
+ */
263
350
  private buildSaveBody;
351
+ /**
352
+ * After a refused save, the person chose to keep their own version: their edits are saved on top of what the API
353
+ * holds now. The version to save on top of is read again rather than taken from the refusal, because minutes may
354
+ * have passed: if a third person saved meanwhile, this save is refused too and the person is asked again, never
355
+ * replaced unseen. Resolves `true` when nothing is left unsaved afterwards, `false` otherwise (the conflict stays
356
+ * when it could not even be read, with `resolveError` saying why).
357
+ */
358
+ keepMyChanges(): Promise<boolean>;
359
+ /**
360
+ * After a refused save, the person chose the latest version: the composition is read again and their edits are
361
+ * dropped. The preview is told the new values (its page may not reload, when the widget is the same).
362
+ */
363
+ loadLatestVersion(): Promise<void>;
264
364
  /** Starts the wait for an autosave of what is unsaved (for callers that have something unsaved). */
265
365
  private scheduleAutosave;
266
366
  /** After an autosave failed for a reason that may pass: try again later, but only so many times. */