@widgetic/editor 4.1.11 → 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.
- package/dist/components/WidgetPreview.svelte +1 -1
- package/dist/components/editors/CompositionEditorApp.svelte +229 -2
- package/dist/components/editors/CompositionEditorApp.svelte.d.ts +27 -2
- package/dist/components/editors/EditLeaseNotice.svelte +150 -0
- package/dist/components/editors/EditLeaseNotice.svelte.d.ts +25 -0
- package/dist/composition/compositionApi.d.ts +80 -1
- package/dist/composition/compositionApi.js +132 -7
- package/dist/composition/compositionEditorController.d.ts +106 -6
- package/dist/composition/compositionEditorController.js +211 -27
- package/dist/composition/compositionHelpers.d.ts +10 -0
- package/dist/composition/compositionHelpers.js +23 -0
- package/dist/composition/editLeaseController.d.ts +157 -0
- package/dist/composition/editLeaseController.js +441 -0
- package/dist/i18n/language.d.ts +28 -0
- package/dist/i18n/messages.d.ts +56 -0
- package/dist/i18n/messages.js +58 -0
- package/dist/i18n/translate.d.ts +1 -1
- package/dist/index.d.ts +3 -1
- package/package.json +1 -1
|
@@ -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
|
-
|
|
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
|
-
|
|
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 =
|
|
35
|
-
this.code =
|
|
36
|
-
this.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
|
-
|
|
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
|
-
*
|
|
245
|
-
* the
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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. */
|