payload-canvas 0.1.0 → 0.2.0

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.
Files changed (124) hide show
  1. package/README.md +202 -26
  2. package/dist/admin/editor/Canvas.js +30 -8
  3. package/dist/admin/editor/Editor.js +2 -0
  4. package/dist/admin/editor/Inspector.js +14 -7
  5. package/dist/admin/editor/Outline.js +15 -9
  6. package/dist/admin/editor/Overlay.js +2 -1
  7. package/dist/admin/editor/actions.d.ts +5 -0
  8. package/dist/admin/editor/actions.js +23 -1
  9. package/dist/admin/editor/counts.d.ts +6 -0
  10. package/dist/admin/editor/counts.js +10 -0
  11. package/dist/admin/editor/dnd/displace.js +3 -1
  12. package/dist/admin/editor/editor.scss +53 -0
  13. package/dist/admin/editor/inline.d.ts +12 -0
  14. package/dist/admin/editor/inline.js +48 -3
  15. package/dist/admin/editor/insert/spots.js +4 -2
  16. package/dist/admin/editor/live/useMultiplayer.js +8 -2
  17. package/dist/admin/editor/media/ImageEditor.js +21 -15
  18. package/dist/admin/editor/media/actions.d.ts +13 -9
  19. package/dist/admin/editor/media/actions.js +67 -28
  20. package/dist/admin/editor/media/model.d.ts +8 -0
  21. package/dist/admin/editor/media/model.js +14 -6
  22. package/dist/admin/editor/menu/blockMenu.js +13 -8
  23. package/dist/admin/editor/regions/RegionOverlay.d.ts +18 -0
  24. package/dist/admin/editor/regions/RegionOverlay.js +44 -0
  25. package/dist/admin/editor/regions/RegionPane.d.ts +5 -0
  26. package/dist/admin/editor/regions/RegionPane.js +26 -0
  27. package/dist/admin/editor/regions/RegionRows.d.ts +1 -0
  28. package/dist/admin/editor/regions/RegionRows.js +23 -0
  29. package/dist/admin/editor/regions/controller.d.ts +73 -0
  30. package/dist/admin/editor/regions/controller.js +231 -0
  31. package/dist/admin/editor/regions/select.d.ts +17 -0
  32. package/dist/admin/editor/regions/select.js +31 -0
  33. package/dist/admin/editor/runtime.d.ts +6 -0
  34. package/dist/admin/editor/runtime.js +49 -4
  35. package/dist/admin/editor/sections/controller.d.ts +6 -2
  36. package/dist/admin/editor/sections/controller.js +9 -3
  37. package/dist/admin/editor/shortcuts.js +11 -4
  38. package/dist/admin/editor/storage.d.ts +7 -0
  39. package/dist/admin/editor/storage.js +15 -0
  40. package/dist/admin/editor/store.d.ts +39 -0
  41. package/dist/admin/editor/store.js +106 -2
  42. package/dist/admin/editor/templates/Bindable.js +1 -1
  43. package/dist/admin/editor/templates/SamplePicker.js +1 -1
  44. package/dist/admin/editor/topbar/DocumentActions.js +38 -5
  45. package/dist/admin/editor/topbar/closeSave.d.ts +50 -0
  46. package/dist/admin/editor/topbar/closeSave.js +90 -0
  47. package/dist/admin/editor/topbar/document.d.ts +10 -2
  48. package/dist/admin/editor/topbar/document.js +9 -1
  49. package/dist/admin/editor/topbar/drawerLabels.d.ts +22 -0
  50. package/dist/admin/editor/topbar/drawerLabels.js +69 -0
  51. package/dist/admin/editor/topbar/problems.d.ts +9 -0
  52. package/dist/admin/editor/topbar/problems.js +15 -1
  53. package/dist/admin/editor/topbar/settingsDrawer.js +88 -4
  54. package/dist/admin/editor/topbar/settingsFocus.d.ts +11 -0
  55. package/dist/admin/editor/topbar/settingsFocus.js +46 -0
  56. package/dist/admin/editor/ui/payloadA11y.d.ts +17 -0
  57. package/dist/admin/editor/ui/payloadA11y.js +12 -5
  58. package/dist/admin/editor/valueStore.d.ts +2 -0
  59. package/dist/admin/editor/valueStore.js +6 -0
  60. package/dist/core/dropTarget.js +3 -1
  61. package/dist/core/index.d.ts +2 -0
  62. package/dist/core/index.js +2 -0
  63. package/dist/core/payloadBlocks.d.ts +53 -0
  64. package/dist/core/payloadBlocks.js +391 -0
  65. package/dist/core/regions.d.ts +63 -0
  66. package/dist/core/regions.js +239 -0
  67. package/dist/core/types.d.ts +53 -0
  68. package/dist/index.d.ts +1 -0
  69. package/dist/index.js +1 -0
  70. package/dist/live/document.d.ts +9 -1
  71. package/dist/live/document.js +57 -17
  72. package/dist/live/draftAccess.d.ts +36 -0
  73. package/dist/live/draftAccess.js +146 -0
  74. package/dist/live/endpoints.d.ts +11 -2
  75. package/dist/live/endpoints.js +120 -10
  76. package/dist/live/fieldChecks.d.ts +3 -3
  77. package/dist/live/fieldsGuard.d.ts +56 -2
  78. package/dist/live/fieldsGuard.js +107 -11
  79. package/dist/live/index.d.ts +2 -0
  80. package/dist/live/index.js +2 -0
  81. package/dist/live/regions.d.ts +89 -0
  82. package/dist/live/regions.js +401 -0
  83. package/dist/live/runtime.d.ts +1 -1
  84. package/dist/live/runtime.js +5 -2
  85. package/dist/live/session.d.ts +74 -9
  86. package/dist/live/session.js +655 -123
  87. package/dist/live/storage.d.ts +97 -0
  88. package/dist/live/storage.js +269 -0
  89. package/dist/live/types.d.ts +64 -0
  90. package/dist/live/writeGate.d.ts +72 -0
  91. package/dist/live/writeGate.js +478 -0
  92. package/dist/mcp/index.js +56 -12
  93. package/dist/plugin/hook.d.ts +44 -6
  94. package/dist/plugin/hook.js +176 -20
  95. package/dist/plugin/index.d.ts +23 -1
  96. package/dist/plugin/index.js +172 -10
  97. package/dist/plugin/references.d.ts +4 -2
  98. package/dist/plugin/references.js +2 -0
  99. package/dist/plugin/sectionsBuilder.js +3 -3
  100. package/dist/protocol/index.d.ts +28 -2
  101. package/dist/react/canvas/BuilderCanvas.js +198 -8
  102. package/dist/react/canvas/frame.d.ts +70 -0
  103. package/dist/react/canvas/frame.js +66 -0
  104. package/dist/react/canvas/inline/dom.d.ts +7 -1
  105. package/dist/react/canvas/inline/dom.js +19 -9
  106. package/dist/react/canvas/inline/mapper.d.ts +26 -0
  107. package/dist/react/canvas/inline/mapper.js +59 -32
  108. package/dist/react/canvas/inline/session.d.ts +7 -1
  109. package/dist/react/canvas/inline/session.js +6 -2
  110. package/dist/react/canvas/measure.js +26 -1
  111. package/dist/react/index.d.ts +2 -0
  112. package/dist/react/index.js +2 -0
  113. package/dist/react/render/LayoutOutlet.d.ts +11 -0
  114. package/dist/react/render/LayoutOutlet.js +16 -0
  115. package/dist/react/render/canvasFrame.d.ts +46 -0
  116. package/dist/react/render/canvasFrame.js +59 -0
  117. package/dist/react/render/canvasServer.d.ts +13 -0
  118. package/dist/react/render/canvasServer.js +3 -0
  119. package/dist/react/render/canvasServerTypes.d.ts +17 -0
  120. package/dist/react/render/regions.d.ts +13 -0
  121. package/dist/react/render/regions.js +8 -0
  122. package/dist/react/server.d.ts +2 -1
  123. package/dist/react/server.js +1 -0
  124. package/package.json +1 -1
@@ -0,0 +1,97 @@
1
+ import { type PayloadRequest } from 'payload';
2
+ import { type PayloadBlocksStorage } from '../core/payloadBlocks.js';
3
+ import type { Layout, Operation } from '../core/types.js';
4
+ export type LayoutCodec = {
5
+ kind: 'json' | 'payload-blocks';
6
+ /** The stored field value as a layout. Throws a 422 when the value cannot be shown without loss. */
7
+ decode(value: unknown): Layout;
8
+ /**
9
+ * The layout as the stored field value. `previous`: the value stored now (a Payload blocks field
10
+ * writes `null` for values the layout removed, see `encodePayloadBlocks`).
11
+ */
12
+ encode(layout: Layout, previous?: unknown): unknown;
13
+ /** What in a layout the field cannot store. Empty: it can be stored as it is. */
14
+ problems(layout: Layout): string[];
15
+ /**
16
+ * The resolved operations of a commit as the field stores them (a Payload blocks field gives
17
+ * copied rows new ids; `owned`: the row ids the document's stored value has held). Returns `ops`
18
+ * itself when nothing changes.
19
+ */
20
+ prepare?(layout: Layout, ops: Operation[], owned?: ReadonlySet<string>): Operation[];
21
+ /** The row ids of a stored value (a Payload blocks field). */
22
+ rowIds?(value: unknown): Set<string>;
23
+ };
24
+ export declare const JSON_CODEC: LayoutCodec;
25
+ /** The codec of a Payload blocks field. */
26
+ export declare function payloadBlocksCodec(storage: PayloadBlocksStorage): LayoutCodec;
27
+ /** The codec of a builder collection's server config. JSON when it stores no Payload blocks. */
28
+ export declare function codecOf(collection: {
29
+ payloadBlocks?: PayloadBlocksStorage;
30
+ } | undefined): LayoutCodec;
31
+ /**
32
+ * True when Payload's read access lets the request's user read every value in `value` (a blocks
33
+ * field's rows, as the live session or the database holds them). Walks the field config the way
34
+ * Payload's read hooks do: each field's `access.read` runs with the row as `siblingData`, through
35
+ * groups, arrays, tabs, rows, collapsibles and nested blocks. A hidden field with a value, or a
36
+ * block type without a config, counts as unreadable. Values that are absent never count.
37
+ */
38
+ export declare function canReadBlocksValue(req: PayloadRequest, args: {
39
+ collection: string;
40
+ field: string;
41
+ id: string | number;
42
+ value: unknown;
43
+ doc: Record<string, unknown>;
44
+ }): Promise<boolean>;
45
+ /** Why the builder refuses a user who may not read every value of a Payload blocks field. */
46
+ export declare const UNREADABLE_BLOCKS_MESSAGE = "You may not read every field of these blocks, so the builder cannot show them. Edit the page in Payload's editor.";
47
+ /** Why the builder refuses a user who may not change a Payload blocks field. */
48
+ export declare const BLOCKS_NOT_EDITABLE_MESSAGE = "You may not change the blocks of this page.";
49
+ type BlocksTarget = {
50
+ collection: string;
51
+ id: string | number;
52
+ field: string;
53
+ drafts: boolean;
54
+ codec?: LayoutCodec;
55
+ };
56
+ /**
57
+ * True when Payload's field access lets the request's user update the builder field. Payload drops
58
+ * a field the user may not update from a save without an error, so the builder checks it before a
59
+ * change, never after a save says "saved".
60
+ */
61
+ export declare function canUpdateBlocksField(req: PayloadRequest, target: BlocksTarget): Promise<boolean>;
62
+ /**
63
+ * The check before a request uses the live session of a Payload blocks field, or sends a layout
64
+ * from it. Null: allowed. Always null for the builder's JSON layout.
65
+ * - `write`: the user may update the field (Payload drops a field the user may not update from a
66
+ * save without an error, so this is checked before a change).
67
+ * - Read: the user may read every value of the stored blocks and of each layout in `layouts` (the
68
+ * open session's layout, the layout a response sends). Payload's own `access.read` decides, on
69
+ * the values themselves, so a value that exists only in the live session counts too.
70
+ * - `stored: false` skips the database read (an event stream checks each event's live layout).
71
+ * Runs on every request: nothing is cached.
72
+ */
73
+ export declare function blocksAccessProblem(req: PayloadRequest, target: BlocksTarget, options: {
74
+ write: boolean;
75
+ layouts?: readonly (Layout | null | undefined)[];
76
+ doc?: Record<string, unknown>;
77
+ stored?: boolean;
78
+ }): Promise<string | null>;
79
+ /**
80
+ * Every state a batch of operations passes through, after each operation, starting from `before`.
81
+ * A value one operation writes and a later one removes is in one of them, in its real place
82
+ * (its block, its parent, its siblings). Null when an operation does not apply.
83
+ */
84
+ export declare function statesThrough(before: Layout, ops: readonly Operation[]): Layout[] | null;
85
+ type CommitAccess = (args: {
86
+ before: Layout;
87
+ after: Layout;
88
+ ops: readonly Operation[];
89
+ doc: Record<string, unknown>;
90
+ }) => Promise<string | null>;
91
+ /**
92
+ * A Payload blocks field: the commit's access check also refuses a batch that would show the user
93
+ * a value they may not read, in any state the batch passes through. It runs before the commit
94
+ * changes anything, so a refused batch is not applied. The JSON layout: `access` as it is.
95
+ */
96
+ export declare function withBlocksReadCheck(req: PayloadRequest, target: BlocksTarget, access?: CommitAccess): CommitAccess | undefined;
97
+ export {};
@@ -0,0 +1,269 @@
1
+ // How a builder collection stores its layout: the codec between the stored field value and the
2
+ // layout the live session, the canvas and the tools work on.
3
+ //
4
+ // - `json` (the builder's own JSON layout field): the stored value is the layout.
5
+ // - `payload-blocks` (the collection's own Payload `blocks` field): the stored value is Payload's
6
+ // block rows, read and written with the lossless codec of core/payloadBlocks.ts. The field stays
7
+ // the one source of truth; the layout is a view of it while a page is open.
8
+ import { APIError, docAccessOperation } from 'payload';
9
+ import { decodePayloadBlocks, encodePayloadBlocks, payloadBlocksProblems, payloadRowIds, withUniqueRowIds } from '../core/payloadBlocks.js';
10
+ import { normalizeLayout } from '../core/tree.js';
11
+ import { applyOperation } from '../core/operations.js';
12
+ export const JSON_CODEC = {
13
+ kind: 'json',
14
+ decode: (value) => normalizeLayout(value),
15
+ encode: (layout) => layout,
16
+ problems: () => [],
17
+ };
18
+ /** The codec of a Payload blocks field. */
19
+ export function payloadBlocksCodec(storage) {
20
+ return {
21
+ kind: 'payload-blocks',
22
+ decode(value) {
23
+ const result = decodePayloadBlocks(value, storage);
24
+ if (!result.ok)
25
+ throw new APIError(`The builder cannot open these blocks without changing them: ${result.error}`, 422, undefined, true);
26
+ return result.layout;
27
+ },
28
+ encode: (layout, previous) => encodePayloadBlocks(layout, storage, previous),
29
+ problems: (layout) => payloadBlocksProblems(layout, storage),
30
+ prepare: (layout, ops, owned) => withUniqueRowIds(layout, ops, storage, owned),
31
+ rowIds: (value) => payloadRowIds(value, storage),
32
+ };
33
+ }
34
+ const codecs = new WeakMap();
35
+ /** The codec of a builder collection's server config. JSON when it stores no Payload blocks. */
36
+ export function codecOf(collection) {
37
+ const storage = collection?.payloadBlocks;
38
+ if (!storage)
39
+ return JSON_CODEC;
40
+ let codec = codecs.get(storage);
41
+ if (!codec) {
42
+ codec = payloadBlocksCodec(storage);
43
+ codecs.set(storage, codec);
44
+ }
45
+ return codec;
46
+ }
47
+ /** The top-level field `name` of a field list (also inside rows, collapsibles and unnamed tabs). */
48
+ function topField(fields, name) {
49
+ for (const f of fields) {
50
+ if (f.name === name)
51
+ return f;
52
+ if ((f.type === 'row' || f.type === 'collapsible' || (f.type === 'group' && !f.name)) && f.fields) {
53
+ const found = topField(f.fields, name);
54
+ if (found)
55
+ return found;
56
+ }
57
+ if (f.type === 'tabs') {
58
+ for (const tab of f.tabs ?? []) {
59
+ if (tab.name)
60
+ continue;
61
+ const found = topField(tab.fields, name);
62
+ if (found)
63
+ return found;
64
+ }
65
+ }
66
+ }
67
+ return undefined;
68
+ }
69
+ /**
70
+ * True when Payload's read access lets the request's user read every value in `value` (a blocks
71
+ * field's rows, as the live session or the database holds them). Walks the field config the way
72
+ * Payload's read hooks do: each field's `access.read` runs with the row as `siblingData`, through
73
+ * groups, arrays, tabs, rows, collapsibles and nested blocks. A hidden field with a value, or a
74
+ * block type without a config, counts as unreadable. Values that are absent never count.
75
+ */
76
+ export async function canReadBlocksValue(req, args) {
77
+ const config = req.payload.collections[args.collection]?.config;
78
+ const root = config ? topField(config.fields, args.field) : undefined;
79
+ if (!root)
80
+ return false;
81
+ const references = new Map();
82
+ for (const block of req.payload.config.blocks ?? [])
83
+ references.set(block.slug, block);
84
+ const doc = { ...args.doc, [args.field]: args.value };
85
+ const readable = async (field, value, sibling, blockData) => {
86
+ if (value === undefined)
87
+ return true;
88
+ if (field.hidden)
89
+ return false;
90
+ if (field.access?.read) {
91
+ const ok = await field.access.read({ req, id: args.id, data: doc, doc, siblingData: sibling, blockData });
92
+ if (!ok)
93
+ return false;
94
+ }
95
+ return true;
96
+ };
97
+ const walk = async (fields, data, blockData) => {
98
+ if (!isRecord(data))
99
+ return true;
100
+ for (const f of fields) {
101
+ if ((f.type === 'row' || f.type === 'collapsible' || (f.type === 'group' && !f.name)) && f.fields) {
102
+ if (!(await walk(f.fields, data, blockData)))
103
+ return false;
104
+ continue;
105
+ }
106
+ if (f.type === 'tabs') {
107
+ for (const tab of f.tabs ?? []) {
108
+ if (tab.name && !(await readable(tab, data[tab.name], data, blockData)))
109
+ return false;
110
+ if (!(await walk(tab.fields, tab.name ? data[tab.name] : data, blockData)))
111
+ return false;
112
+ }
113
+ continue;
114
+ }
115
+ if (!f.name)
116
+ continue;
117
+ const value = data[f.name];
118
+ if (!(await readable(f, value, data, blockData)))
119
+ return false;
120
+ if (!(await walkValue(f, value, blockData)))
121
+ return false;
122
+ }
123
+ return true;
124
+ };
125
+ const walkValue = async (f, value, blockData) => {
126
+ if (value === undefined || value === null)
127
+ return true;
128
+ if (f.type === 'group' && f.fields)
129
+ return walk(f.fields, value, blockData);
130
+ if (f.type === 'array' && f.fields) {
131
+ for (const row of Array.isArray(value) ? value : [])
132
+ if (!(await walk(f.fields, row, blockData)))
133
+ return false;
134
+ return true;
135
+ }
136
+ if (f.type === 'blocks') {
137
+ const blocks = new Map();
138
+ for (const b of f.blocks ?? [])
139
+ blocks.set(b.slug, b);
140
+ for (const ref of f.blockReferences ?? []) {
141
+ const block = typeof ref === 'string' ? references.get(ref) : ref;
142
+ if (block)
143
+ blocks.set(block.slug, block);
144
+ }
145
+ for (const row of Array.isArray(value) ? value : []) {
146
+ if (!isRecord(row))
147
+ continue;
148
+ const block = blocks.get(String(row.blockType));
149
+ if (!block)
150
+ return false;
151
+ if (!(await walk(block.fields, row, row)))
152
+ return false;
153
+ }
154
+ }
155
+ return true;
156
+ };
157
+ if (!(await readable(root, args.value, doc)))
158
+ return false;
159
+ return walkValue(root, args.value);
160
+ }
161
+ /** Why the builder refuses a user who may not read every value of a Payload blocks field. */
162
+ export const UNREADABLE_BLOCKS_MESSAGE = "You may not read every field of these blocks, so the builder cannot show them. Edit the page in Payload's editor.";
163
+ const isRecord = (value) => typeof value === 'object' && value !== null;
164
+ /** A permission that allows: `true`, or `{ permission: true }`. */
165
+ const allowed = (value) => value === true || (isRecord(value) && value.permission === true);
166
+ /** Why the builder refuses a user who may not change a Payload blocks field. */
167
+ export const BLOCKS_NOT_EDITABLE_MESSAGE = 'You may not change the blocks of this page.';
168
+ /**
169
+ * True when Payload's field access lets the request's user update the builder field. Payload drops
170
+ * a field the user may not update from a save without an error, so the builder checks it before a
171
+ * change, never after a save says "saved".
172
+ */
173
+ export async function canUpdateBlocksField(req, target) {
174
+ const collection = req.payload.collections[target.collection];
175
+ if (!collection)
176
+ return false;
177
+ try {
178
+ // Sanitized permissions: `true` for "everything", and a refused key is left out.
179
+ const permissions = (await docAccessOperation({ collection, id: target.id, req }));
180
+ if (permissions === true)
181
+ return true;
182
+ if (!isRecord(permissions) || !allowed(permissions.update))
183
+ return false;
184
+ const fields = permissions.fields;
185
+ if (fields === true || fields === undefined)
186
+ return true;
187
+ const field = isRecord(fields) ? fields[target.field] : undefined;
188
+ return field === true || (isRecord(field) && allowed(field.update));
189
+ }
190
+ catch {
191
+ return false;
192
+ }
193
+ }
194
+ /**
195
+ * The check before a request uses the live session of a Payload blocks field, or sends a layout
196
+ * from it. Null: allowed. Always null for the builder's JSON layout.
197
+ * - `write`: the user may update the field (Payload drops a field the user may not update from a
198
+ * save without an error, so this is checked before a change).
199
+ * - Read: the user may read every value of the stored blocks and of each layout in `layouts` (the
200
+ * open session's layout, the layout a response sends). Payload's own `access.read` decides, on
201
+ * the values themselves, so a value that exists only in the live session counts too.
202
+ * - `stored: false` skips the database read (an event stream checks each event's live layout).
203
+ * Runs on every request: nothing is cached.
204
+ */
205
+ export async function blocksAccessProblem(req, target, options) {
206
+ const codec = target.codec;
207
+ if (codec?.kind !== 'payload-blocks')
208
+ return null;
209
+ if (options.write && !(await canUpdateBlocksField(req, target)))
210
+ return BLOCKS_NOT_EDITABLE_MESSAGE;
211
+ let doc = options.doc ?? {};
212
+ const values = [];
213
+ if (options.stored !== false) {
214
+ const stored = (await req.payload.findByID({
215
+ collection: target.collection,
216
+ id: target.id,
217
+ depth: 0,
218
+ draft: target.drafts,
219
+ overrideAccess: true,
220
+ req,
221
+ }));
222
+ doc = stored;
223
+ values.push(stored[target.field]);
224
+ }
225
+ for (const layout of options.layouts ?? [])
226
+ if (layout)
227
+ values.push(codec.encode(layout));
228
+ for (const value of values) {
229
+ if (!(await canReadBlocksValue(req, { collection: target.collection, field: target.field, id: target.id, value, doc }))) {
230
+ return UNREADABLE_BLOCKS_MESSAGE;
231
+ }
232
+ }
233
+ return null;
234
+ }
235
+ /**
236
+ * Every state a batch of operations passes through, after each operation, starting from `before`.
237
+ * A value one operation writes and a later one removes is in one of them, in its real place
238
+ * (its block, its parent, its siblings). Null when an operation does not apply.
239
+ */
240
+ export function statesThrough(before, ops) {
241
+ const states = [];
242
+ let layout = before;
243
+ for (const op of ops) {
244
+ const result = applyOperation(layout, op);
245
+ if (!result.ok)
246
+ return null;
247
+ layout = result.layout;
248
+ states.push(layout);
249
+ }
250
+ return states;
251
+ }
252
+ /**
253
+ * A Payload blocks field: the commit's access check also refuses a batch that would show the user
254
+ * a value they may not read, in any state the batch passes through. It runs before the commit
255
+ * changes anything, so a refused batch is not applied. The JSON layout: `access` as it is.
256
+ */
257
+ export function withBlocksReadCheck(req, target, access) {
258
+ if (target.codec?.kind !== 'payload-blocks')
259
+ return access;
260
+ return async (args) => {
261
+ const denied = access ? await access(args) : null;
262
+ if (denied)
263
+ return denied;
264
+ const states = statesThrough(args.before, args.ops);
265
+ if (!states)
266
+ return UNREADABLE_BLOCKS_MESSAGE;
267
+ return blocksAccessProblem(req, target, { write: false, stored: false, layouts: states, doc: args.doc });
268
+ };
269
+ }
@@ -179,6 +179,12 @@ export type LiveSavedEvent = {
179
179
  updatedAt?: string;
180
180
  /** `_status` of the saved document (collections with drafts). */
181
181
  status?: string;
182
+ /**
183
+ * Top-level fields other than the layout that this save changed (the settings drawer, the
184
+ * region fields endpoint, REST). Left out when only the layout changed. The editor shows the
185
+ * page frame again when a region's field is among them.
186
+ */
187
+ fields?: string[];
182
188
  };
183
189
  /**
184
190
  * The session could not save the draft. The commits stay in the session (nothing is lost while the
@@ -331,6 +337,64 @@ export type SettingsLockResponse = {
331
337
  ok: false;
332
338
  error: string;
333
339
  };
340
+ /**
341
+ * What the user may do with each field of the regions, by path without row numbers ("title",
342
+ * "links", "links.label"). A path that is not listed follows the nearest listed path above it.
343
+ */
344
+ export type RegionAccess = Record<string, {
345
+ read: boolean;
346
+ update: boolean;
347
+ }>;
348
+ /**
349
+ * The regions' values (the document's shape, ids instead of documents) in one locale, and the
350
+ * user's access.
351
+ * - `values`: what the page shows, with Payload's locale fallback. Conflict checks compare with it.
352
+ * - `storedValues`: the locale's own values (no fallback). Every field path in `values` is in it
353
+ * too; `null` there means "no own value in this locale" (a fallback shows). Fields the user may
354
+ * not read are in neither. Without localization it equals `values`.
355
+ */
356
+ export type LiveRegionsResponse = {
357
+ ok: true;
358
+ values: Record<string, unknown>;
359
+ storedValues: Record<string, unknown>;
360
+ access: RegionAccess;
361
+ updatedAt: string | null;
362
+ } | {
363
+ ok: false;
364
+ error: string;
365
+ };
366
+ /**
367
+ * One field change. `path` is a document path inside a region's field ("title", "links.0.label").
368
+ * `base` is the value the editor showed before the change: when someone else changed the field
369
+ * since, the server refuses the whole request (409) instead of overwriting their change.
370
+ */
371
+ export type LiveFieldChange = {
372
+ path: string;
373
+ value: unknown;
374
+ base?: unknown;
375
+ };
376
+ export type LiveFieldsRequest = {
377
+ changes: LiveFieldChange[];
378
+ /** The locale the editor shows. Localized fields change in it. */
379
+ locale?: string | null;
380
+ };
381
+ /** A change the server refused because the field changed since the editor read it. */
382
+ export type LiveFieldConflict = {
383
+ path: string;
384
+ value: unknown;
385
+ };
386
+ /** `values` and `storedValues` as in `LiveRegionsResponse`, after the save. */
387
+ export type LiveFieldsResponse = {
388
+ ok: true;
389
+ values: Record<string, unknown>;
390
+ storedValues: Record<string, unknown>;
391
+ updatedAt: string | null;
392
+ } | {
393
+ ok: false;
394
+ error: string;
395
+ conflicts?: LiveFieldConflict[];
396
+ errors?: LiveError[];
397
+ };
334
398
  /** `GET {live}/:collection/:id/access`: the user's prop access, as in `BuilderDocMeta.fieldAccess`. */
335
399
  export type LiveAccessResponse = {
336
400
  ok: true;
@@ -0,0 +1,72 @@
1
+ import { type CollectionAfterErrorHook, type CollectionAfterOperationHook, type CollectionBeforeOperationHook, type Config } from 'payload';
2
+ export type WriteGateOptions = {
3
+ waitMs?: number;
4
+ logger?: {
5
+ error?(message: string, error?: unknown): void;
6
+ };
7
+ };
8
+ export type WriteGate = {
9
+ /**
10
+ * Runs `task` while it holds the document's gate. Updates inside it that get the same `req`
11
+ * join the hold. Rejects with a 409 when the gate stays busy.
12
+ */
13
+ run<T>(key: string, req: object, task: () => Promise<T>): Promise<T>;
14
+ /** True while `req` holds a gate. */
15
+ holds(req: object): boolean;
16
+ /**
17
+ * Runs `fn` once the update of `key` that `req` runs now is stored: after its transaction
18
+ * committed, or after the operation succeeded without one. Never after a rollback or a failed
19
+ * commit. Outside a gated update it runs at once.
20
+ */
21
+ afterCommit(req: object, key: string, fn: () => void): void;
22
+ /** The adapter committed (`committed: true`), rolled back, or failed to commit a transaction. */
23
+ transactionEnded(transaction: unknown, committed: boolean): void;
24
+ /**
25
+ * Runs one Local API call in its own async context. When it settles, the updates it ran (not
26
+ * those of a call inside it, nor of another call at the same time) that never reached
27
+ * `afterOperation` failed: their holds end and their work goes.
28
+ */
29
+ localCall<T>(call: () => Promise<T>): Promise<T>;
30
+ /** A request failed (Payload's config-level `afterError`: REST, GraphQL): its updates without a transaction end. */
31
+ failRequest(req: object): void;
32
+ /** Hooks that put every update of `collection` through the gate. */
33
+ hooks(collection: string): {
34
+ beforeOperation: CollectionBeforeOperationHook;
35
+ afterOperation: CollectionAfterOperationHook;
36
+ afterError: CollectionAfterErrorHook;
37
+ };
38
+ /** Documents with a held or waiting gate. For tests. */
39
+ size(): number;
40
+ };
41
+ /** The gate key of a document. Number and text ids of one document share a key. */
42
+ export declare const writeKey: (collection: string, id: string | number) => string;
43
+ export declare function createWriteGate(options?: WriteGateOptions): WriteGate;
44
+ /** The part of a database adapter the signals wrap. */
45
+ export type TransactionAdapter = {
46
+ commitTransaction?: (id: never) => Promise<unknown>;
47
+ rollbackTransaction?: (id: never) => Promise<unknown>;
48
+ };
49
+ /**
50
+ * Tells the gate when the adapter committed or rolled back a transaction, from the adapter's own
51
+ * answer: wraps `commitTransaction` and `rollbackTransaction` of `payload.db` once. A commit that
52
+ * throws counts as not committed.
53
+ */
54
+ export declare function installTransactionSignals(db: TransactionAdapter, gate: WriteGate): void;
55
+ /** The part of the Payload instance the Local API boundary wraps. */
56
+ export type LocalApi = {
57
+ update: (options: Record<string, unknown>) => Promise<unknown>;
58
+ };
59
+ /** Gives the gate the end of every Local API update: wraps `payload.update` once. The call itself is unchanged. */
60
+ export declare function installLocalApiBoundary(payload: LocalApi, gate: WriteGate): void;
61
+ /**
62
+ * Payload's `config.db` with the gate's signals installed as soon as the adapter exists. Payload
63
+ * calls `config.db.init({ payload })` first thing in `payload.init`, before the adapter's own
64
+ * `init` and `connect`, before migrations (`payload migrate` runs without `onInit`, and migrations
65
+ * on connect run before it) and before any operation. So the adapter's commit and rollback, and
66
+ * `payload.update` (failed Local API saves without a transaction), report to the gate from the
67
+ * first save on. The adapter object itself is returned unchanged; the plugin's `onInit` and the
68
+ * gate's first update install the same signals again as fallbacks (each install runs once).
69
+ */
70
+ export declare function withGateSignals(db: Config['db'], gate: WriteGate): Config['db'];
71
+ /** The process-wide write gate. Kept on `globalThis`, so a dev hot reload keeps it. */
72
+ export declare function defaultWriteGate(): WriteGate;