payload-canvas 0.1.1 → 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 +187 -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,391 @@
1
+ // The builder's storage codec for a Payload `blocks` field: one source of truth.
2
+ //
3
+ // A collection whose builder field is a Payload `blocks` field keeps that field as it is. Payload's
4
+ // editor, hooks, validation, access and versions work on it as before. The builder reads the same
5
+ // value into a layout while a page is open, and writes the layout back to the same field. Nothing
6
+ // is copied anywhere else.
7
+ //
8
+ // The codec is lossless, so a round trip changes nothing the builder did not change:
9
+ // - Every stored key of a block row is kept: fields the builder shows, fields it does not show
10
+ // (hidden in the admin, unknown to the block definition), `null` and empty values, row ids of
11
+ // arrays, values inside groups and arrays, nested blocks fields inside groups or arrays.
12
+ // - Nested blocks fields at a block's own data level become slots (the definitions from
13
+ // `fromPayloadBlocks` say which), so their blocks are blocks on the canvas too.
14
+ // - Block ids, order and `blockName` (the block's name in the builder) are kept. No defaults are
15
+ // added: a key that is missing stays missing.
16
+ // - Values are taken as stored (read with `depth: 0`): uploads and relationships stay ids.
17
+ // It refuses, visibly, what a blocks field cannot hold: a block type without a definition, a block
18
+ // type the field does not allow, two blocks with one id, and the builder's own block data that
19
+ // Payload has no field for (Tailwind classes, animations, bindings, "hidden", translations).
20
+ //
21
+ // Pure functions, safe on the server, in the admin and in the canvas.
22
+ import { getBlockDefinition } from './blocks.js';
23
+ import { createId } from './ids.js';
24
+ import { isPlainObject } from './tree.js';
25
+ /** The `blockType` a definition stands for in Payload data. */
26
+ const slugOf = (def) => def.payload?.slug ?? def.type;
27
+ /** The keys of a Payload block row that are not field values. */
28
+ const ROW_KEYS = new Set(['id', 'blockType', 'blockName']);
29
+ const definitionFor = (storage, blockType) => storage.blocks.find((def) => def.payload?.slug === blockType) ?? storage.blocks.find((def) => !def.payload && def.type === blockType);
30
+ /**
31
+ * Reads a stored Payload blocks value (`[{ id, blockType, blockName?, ...fields }]`) into a layout.
32
+ * `null` or a missing value is an empty layout. Refuses data it cannot keep exactly.
33
+ */
34
+ export function decodePayloadBlocks(value, storage) {
35
+ if (value === null || value === undefined)
36
+ return { ok: true, layout: { version: 1, blocks: [] } };
37
+ if (!Array.isArray(value))
38
+ return { ok: false, error: 'The field does not hold a list of blocks.' };
39
+ const seen = new Set();
40
+ const problems = [];
41
+ const readList = (rows, where) => rows.flatMap((row, index) => {
42
+ const block = readRow(row, `${where}${index + 1}`);
43
+ return block ? [block] : [];
44
+ });
45
+ const readRow = (row, where) => {
46
+ if (!isPlainObject(row) || typeof row.blockType !== 'string' || row.blockType === '') {
47
+ problems.push(`Block ${where} has no block type.`);
48
+ return null;
49
+ }
50
+ const def = definitionFor(storage, row.blockType);
51
+ if (!def) {
52
+ problems.push(`Block ${where} is a "${row.blockType}" block, which the builder has no definition for. Add it with fromPayloadBlocks().`);
53
+ return null;
54
+ }
55
+ let id = typeof row.id === 'string' || typeof row.id === 'number' ? String(row.id) : '';
56
+ if (id === '')
57
+ id = createId();
58
+ if (seen.has(id)) {
59
+ problems.push(`Two blocks have the id "${id}".`);
60
+ return null;
61
+ }
62
+ seen.add(id);
63
+ const slotNames = Object.keys(def.slots ?? {});
64
+ const props = {};
65
+ for (const [key, raw] of Object.entries(row)) {
66
+ if (ROW_KEYS.has(key) || raw === undefined || slotNames.includes(key))
67
+ continue;
68
+ props[key] = raw;
69
+ }
70
+ const slots = {};
71
+ for (const name of slotNames) {
72
+ const children = row[name];
73
+ // `null` and a missing nested blocks field both mean "no blocks".
74
+ if (!Array.isArray(children) || children.length === 0)
75
+ continue;
76
+ slots[name] = readList(children, `${where}.${name}.`);
77
+ }
78
+ const block = { id, type: def.type };
79
+ if (Object.keys(props).length > 0)
80
+ block.props = props;
81
+ if (Object.keys(slots).length > 0)
82
+ block.slots = slots;
83
+ if (typeof row.blockName === 'string' && row.blockName !== '')
84
+ block.label = row.blockName;
85
+ return block;
86
+ };
87
+ const blocks = readList(value, '');
88
+ if (problems.length > 0)
89
+ return { ok: false, error: problems.join(' ') };
90
+ return { ok: true, layout: { version: 1, blocks } };
91
+ }
92
+ /**
93
+ * What in a layout a Payload blocks field cannot hold. Empty when the layout can be stored as it is.
94
+ * The builder refuses such a change instead of saving part of it.
95
+ */
96
+ export function payloadBlocksProblems(layout, storage) {
97
+ const problems = [];
98
+ const check = (list, allowed) => {
99
+ for (const block of list) {
100
+ const def = getBlockDefinition(storage.blocks, block.type);
101
+ const name = def?.label ?? block.type;
102
+ if (!def) {
103
+ problems.push(`"${block.type}" blocks cannot be stored in this field.`);
104
+ continue;
105
+ }
106
+ if (allowed && !allowed.includes(block.type))
107
+ problems.push(`${name} blocks are not allowed here.`);
108
+ if (block.className)
109
+ problems.push(`${name}: this field cannot store Tailwind classes.`);
110
+ if (block.motion)
111
+ problems.push(`${name}: this field cannot store animations.`);
112
+ if (block.bindings)
113
+ problems.push(`${name}: this field cannot store bindings.`);
114
+ if (block.hidden)
115
+ problems.push(`${name}: this field cannot store hidden blocks.`);
116
+ if (block.locales)
117
+ problems.push(`${name}: translations are edited in Payload's editor for this field.`);
118
+ for (const [slot, children] of Object.entries(block.slots ?? {})) {
119
+ if (!def.slots?.[slot]) {
120
+ problems.push(`${name} has no "${slot}" slot.`);
121
+ continue;
122
+ }
123
+ check(children, def.slots[slot].allow ?? null);
124
+ }
125
+ }
126
+ };
127
+ check(layout.blocks, storage.rootTypes);
128
+ return [...new Set(problems)];
129
+ }
130
+ /**
131
+ * Writes a layout back as the Payload blocks value: `[{ id, blockType, blockName?, ...props,
132
+ * ...slots }]`. Every prop goes back as it is (no defaults). Check `payloadBlocksProblems` first:
133
+ * data the field cannot hold is not written.
134
+ *
135
+ * `previous`: the value stored now. Payload keeps a row's stored value for a key the saved row
136
+ * leaves out, so a value the layout removed (a cleared prop, a cleared block name) is written as
137
+ * `null` when the stored row (same id) has it. Keys the stored row does not have stay out.
138
+ */
139
+ export function encodePayloadBlocks(layout, storage, previous) {
140
+ const writeList = (list) => list.map(writeBlock);
141
+ const writeBlock = (block) => {
142
+ const def = getBlockDefinition(storage.blocks, block.type);
143
+ const row = { id: block.id, blockType: def ? slugOf(def) : block.type };
144
+ if (block.label)
145
+ row.blockName = block.label;
146
+ for (const [key, value] of Object.entries(block.props ?? {})) {
147
+ if (!ROW_KEYS.has(key))
148
+ row[key] = value;
149
+ }
150
+ for (const slot of Object.keys(def?.slots ?? {}))
151
+ row[slot] = writeList(block.slots?.[slot] ?? []);
152
+ return row;
153
+ };
154
+ const rows = writeList(layout.blocks);
155
+ if (Array.isArray(previous))
156
+ clearRemoved(rows, previous, storage);
157
+ return rows;
158
+ }
159
+ /** The stored block rows of a blocks value by id, at every depth of its slots. */
160
+ function storedRowsById(rows, storage, into = new Map()) {
161
+ for (const row of rows) {
162
+ if (!isPlainObject(row) || (typeof row.id !== 'string' && typeof row.id !== 'number'))
163
+ continue;
164
+ into.set(String(row.id), row);
165
+ const def = typeof row.blockType === 'string' ? definitionFor(storage, row.blockType) : undefined;
166
+ for (const slot of Object.keys(def?.slots ?? {})) {
167
+ const children = row[slot];
168
+ if (Array.isArray(children))
169
+ storedRowsById(children, storage, into);
170
+ }
171
+ }
172
+ return into;
173
+ }
174
+ /** See `encodePayloadBlocks`: writes `null` for the values the new rows removed. */
175
+ function clearRemoved(rows, previous, storage) {
176
+ const before = storedRowsById(previous, storage);
177
+ const visit = (list) => {
178
+ for (const row of list) {
179
+ const old = before.get(String(row.id));
180
+ const def = typeof row.blockType === 'string' ? definitionFor(storage, row.blockType) : undefined;
181
+ if (old && old.blockType === row.blockType) {
182
+ if (!('blockName' in row) && old.blockName !== undefined && old.blockName !== null)
183
+ row.blockName = null;
184
+ if (def)
185
+ clearFields(def.fields, old, row, storage);
186
+ }
187
+ for (const slot of Object.keys(def?.slots ?? {})) {
188
+ const children = row[slot];
189
+ if (Array.isArray(children))
190
+ visit(children);
191
+ }
192
+ }
193
+ };
194
+ visit(rows);
195
+ }
196
+ /** Follows Payload's field config: a key of `old` that `next` lacks becomes `null` in `next`. */
197
+ function clearFields(fields, old, next, storage) {
198
+ if (!isPlainObject(old) || !isPlainObject(next))
199
+ return;
200
+ for (const f of fields) {
201
+ if ((f.type === 'row' || f.type === 'collapsible' || (f.type === 'group' && !f.name)) && f.fields) {
202
+ clearFields(f.fields, old, next, storage);
203
+ continue;
204
+ }
205
+ if (f.type === 'tabs') {
206
+ for (const tab of f.tabs ?? []) {
207
+ if (tab.name)
208
+ clearFields(tab.fields, old[tab.name], next[tab.name], storage);
209
+ else
210
+ clearFields(tab.fields, old, next, storage);
211
+ }
212
+ continue;
213
+ }
214
+ // Hidden and virtual fields are not in the builder's data: their stored values stay.
215
+ if (!f.name || f.hidden || f.virtual || f.type === 'ui' || f.type === 'join')
216
+ continue;
217
+ if (!(f.name in next)) {
218
+ if (old[f.name] !== undefined && old[f.name] !== null)
219
+ next[f.name] = null;
220
+ continue;
221
+ }
222
+ const before = old[f.name];
223
+ const after = next[f.name];
224
+ if (f.type === 'group' && f.fields)
225
+ clearFields(f.fields, before, after, storage);
226
+ if ((f.type === 'array' || f.type === 'blocks') && Array.isArray(before) && Array.isArray(after)) {
227
+ const byId = new Map(before.filter(isPlainObject).map((r) => [String(r.id), r]));
228
+ for (const row of after) {
229
+ if (!isPlainObject(row))
230
+ continue;
231
+ const prior = byId.get(String(row.id));
232
+ if (!prior)
233
+ continue;
234
+ if (f.type === 'array' && f.fields)
235
+ clearFields(f.fields, prior, row, storage);
236
+ if (f.type === 'blocks' && prior.blockType === row.blockType) {
237
+ const slug = String(row.blockType);
238
+ const inline = f.blocks?.find((b) => b.slug === slug);
239
+ const reference = f.blockReferences?.find((b) => (typeof b === 'string' ? b : b.slug) === slug);
240
+ const config = inline ?? (typeof reference === 'object' ? reference : undefined);
241
+ const blockFields = config?.fields ?? definitionFor(storage, slug)?.fields;
242
+ if (blockFields)
243
+ clearFields(blockFields, prior, row, storage);
244
+ if (!('blockName' in row) && prior.blockName !== undefined && prior.blockName !== null)
245
+ row.blockName = null;
246
+ }
247
+ }
248
+ }
249
+ }
250
+ }
251
+ /**
252
+ * The storage of a Payload blocks field: the definitions of its block types at every depth, found
253
+ * by their Payload slug among `definitions`, and the types it allows at the top level. Throws when
254
+ * a block type of the field has no definition.
255
+ */
256
+ export function payloadBlocksStorage(topSlugs, definitions, where) {
257
+ const bySlug = (slug) => definitions.find((def) => def.payload?.slug === slug);
258
+ const missing = topSlugs.filter((slug) => !bySlug(slug));
259
+ if (missing.length > 0) {
260
+ throw new Error(`[websiteBuilder] ${where} is a Payload blocks field, and the builder has no definition for its block${missing.length > 1 ? 's' : ''} ${missing.map((s) => `"${s}"`).join(', ')}. Add them to \`blocks\` with fromPayloadBlocks().`);
261
+ }
262
+ const rootTypes = topSlugs.map((slug) => bySlug(slug).type);
263
+ const found = new Map();
264
+ const queue = [...rootTypes];
265
+ while (queue.length > 0) {
266
+ const type = queue.shift();
267
+ if (found.has(type))
268
+ continue;
269
+ const def = definitions.find((d) => d.type === type);
270
+ if (!def)
271
+ throw new Error(`[websiteBuilder] ${where}: a slot allows "${type}" blocks, and the builder has no definition for them.`);
272
+ found.set(type, def);
273
+ for (const slot of Object.values(def.slots ?? {}))
274
+ for (const child of slot.allow ?? [])
275
+ queue.push(child);
276
+ }
277
+ return { blocks: [...found.values()], rootTypes };
278
+ }
279
+ /**
280
+ * Calls `visit` for every row of an array field and every block of a blocks field inside `data`,
281
+ * following Payload's field config (so a `json` field's own objects are never touched). `visit`
282
+ * may give the row a new id.
283
+ */
284
+ function eachRow(fields, data, storage, visit) {
285
+ if (!isPlainObject(data))
286
+ return;
287
+ for (const f of fields) {
288
+ if ((f.type === 'row' || f.type === 'collapsible' || (f.type === 'group' && !f.name)) && f.fields) {
289
+ eachRow(f.fields, data, storage, visit);
290
+ continue;
291
+ }
292
+ if (f.type === 'tabs') {
293
+ for (const tab of f.tabs ?? [])
294
+ eachRow(tab.fields, tab.name ? data[tab.name] : data, storage, visit);
295
+ continue;
296
+ }
297
+ if (!f.name)
298
+ continue;
299
+ const value = data[f.name];
300
+ if (f.type === 'group' && f.fields)
301
+ eachRow(f.fields, value, storage, visit);
302
+ if (!Array.isArray(value))
303
+ continue;
304
+ if (f.type === 'array' && f.fields) {
305
+ for (const row of value) {
306
+ if (!isPlainObject(row))
307
+ continue;
308
+ visit(row);
309
+ eachRow(f.fields, row, storage, visit);
310
+ }
311
+ }
312
+ if (f.type === 'blocks') {
313
+ for (const row of value) {
314
+ if (!isPlainObject(row))
315
+ continue;
316
+ visit(row);
317
+ const slug = String(row.blockType);
318
+ const inline = f.blocks?.find((b) => b.slug === slug);
319
+ const reference = f.blockReferences?.find((b) => (typeof b === 'string' ? b : b.slug) === slug);
320
+ const config = inline ?? (typeof reference === 'object' ? reference : undefined);
321
+ const blockFields = config?.fields ?? definitionFor(storage, slug)?.fields;
322
+ if (blockFields)
323
+ eachRow(blockFields, row, storage, visit);
324
+ }
325
+ }
326
+ }
327
+ }
328
+ /** Every row id inside the props of `blocks` and their children (array rows, nested Payload blocks). */
329
+ function rowIdsOf(blocks, storage, into) {
330
+ for (const block of blocks) {
331
+ const def = getBlockDefinition(storage.blocks, block.type);
332
+ if (def) {
333
+ eachRow(def.fields, block.props ?? {}, storage, (row) => {
334
+ if (typeof row.id === 'string' || typeof row.id === 'number')
335
+ into.add(String(row.id));
336
+ });
337
+ }
338
+ for (const children of Object.values(block.slots ?? {}))
339
+ rowIdsOf(children, storage, into);
340
+ }
341
+ return into;
342
+ }
343
+ /** The row ids of a stored blocks value (array rows and nested Payload blocks, at every depth). */
344
+ export function payloadRowIds(value, storage) {
345
+ const decoded = decodePayloadBlocks(value, storage);
346
+ return decoded.ok ? rowIdsOf(decoded.layout.blocks, storage, new Set()) : new Set();
347
+ }
348
+ /**
349
+ * Payload stores the rows of array fields and nested blocks fields by their id, in one table per
350
+ * field for every document, and its own editor gives every pasted or copied row a new id. A block
351
+ * inserted by the builder (a duplicate, a paste from another page, a section) carries the rows of
352
+ * what it was copied from. This gives each inserted row a new id unless the id is this
353
+ * document's own: in `owned` (rows its stored value has held: undoing a removal puts the same rows
354
+ * back) and not in the layout or earlier in the same operations. Without `owned`, only ids already
355
+ * in the layout get new ones. Returns `ops` itself when nothing changed.
356
+ */
357
+ export function withUniqueRowIds(layout, ops, storage, owned) {
358
+ if (!ops.some((op) => op.type === 'insert'))
359
+ return ops;
360
+ const used = rowIdsOf(layout.blocks, storage, new Set());
361
+ let changed = false;
362
+ const renew = (block) => {
363
+ const def = getBlockDefinition(storage.blocks, block.type);
364
+ let props = block.props;
365
+ if (def && props) {
366
+ const copy = structuredClone(props);
367
+ eachRow(def.fields, copy, storage, (row) => {
368
+ const id = typeof row.id === 'string' || typeof row.id === 'number' ? String(row.id) : null;
369
+ if (id === null)
370
+ return;
371
+ if (!used.has(id) && (!owned || owned.has(id))) {
372
+ used.add(id);
373
+ return;
374
+ }
375
+ let next = createId();
376
+ while (used.has(next))
377
+ next = createId();
378
+ row.id = next;
379
+ used.add(next);
380
+ changed = true;
381
+ });
382
+ props = copy;
383
+ }
384
+ const slots = block.slots
385
+ ? Object.fromEntries(Object.entries(block.slots).map(([name, children]) => [name, children.map(renew)]))
386
+ : undefined;
387
+ return { ...block, ...(props ? { props } : {}), ...(slots ? { slots } : {}) };
388
+ };
389
+ const out = ops.map((op) => (op.type === 'insert' ? { ...op, block: renew(op.block) } : op));
390
+ return changed ? out : ops;
391
+ }
@@ -0,0 +1,63 @@
1
+ import type { BlockDefinition, RegionConfig, RegionField } from './types.js';
2
+ /** What a collection's `regions` option names. */
3
+ export type RegionOption = {
4
+ /** Unique name. The app's frame marks the region with it: `region('header', …)`. */
5
+ name: string;
6
+ /** Shown in the editor. Default: the name, in words. */
7
+ label?: string;
8
+ /** Dot paths of the document fields the region shows, e.g. `['title', 'header.image']`. */
9
+ fields: string[];
10
+ };
11
+ /**
12
+ * The region's fields, read from the collection's field configs. Throws a readable error for a
13
+ * name or path the region cannot use. `reserved`: the layout field and the plugin's own fields.
14
+ */
15
+ export declare function resolveRegions(collection: string, fields: readonly unknown[], options: readonly RegionOption[], reserved: {
16
+ fields: ReadonlySet<string>;
17
+ legacy?: ReadonlySet<string>;
18
+ }): RegionConfig[];
19
+ /** A path without its array row numbers: "links.2.label" -> "links.label". */
20
+ export declare const pathWithoutIndexes: (path: string) => string;
21
+ /**
22
+ * The region and its field that hold a document path: the field's own path, or a path inside it
23
+ * ("links.0.label" inside the "links" array). Null when no region shows it.
24
+ */
25
+ export declare function regionFieldOf(regions: readonly RegionConfig[] | undefined, path: string): {
26
+ region: RegionConfig;
27
+ field: RegionField;
28
+ } | null;
29
+ /** The value at a dot path of a document; number segments step into array rows. */
30
+ export declare function valueAtDocPath(doc: unknown, path: string): unknown;
31
+ /**
32
+ * Sets the value at a dot path and returns the changed copy (objects and rows on the way are
33
+ * copied). Missing groups are made; a missing array row fails: the path is gone (someone removed
34
+ * the row). Returns `{ ok: false }` then.
35
+ */
36
+ export declare function setDocPath(doc: unknown, path: string, value: unknown): {
37
+ ok: true;
38
+ value: Record<string, unknown>;
39
+ } | {
40
+ ok: false;
41
+ };
42
+ /** The document's values at the regions' paths, as one object of the document's shape. */
43
+ export declare function regionValues(doc: unknown, regions: readonly RegionConfig[] | undefined): Record<string, unknown>;
44
+ /** Payload's `select` for the regions' fields (with `updatedAt`), so a read loads nothing else. */
45
+ export declare function regionSelect(regions: readonly RegionConfig[] | undefined): Record<string, unknown>;
46
+ /** The block type the editor and the canvas use for a region's fields. Never stored in a layout. */
47
+ export declare const regionType: (name: string) => string;
48
+ /**
49
+ * A region's fields as a block definition, with groups along nested paths, so the inline editor,
50
+ * the automatic mapping and the image editor read the fields as they read block props. The
51
+ * definition never enters a layout and has no slots or styles.
52
+ */
53
+ export declare function regionDefinition(region: RegionConfig): BlockDefinition;
54
+ /** The region names a list of changed top-level fields touches. */
55
+ export declare function regionsTouched(regions: readonly RegionConfig[] | undefined, fields: readonly string[]): string[];
56
+ /** The rights at a document path: its own entry, else the nearest path above it. */
57
+ export declare function regionAccessAt(access: Record<string, {
58
+ read: boolean;
59
+ update: boolean;
60
+ }> | null | undefined, path: string): {
61
+ read: boolean;
62
+ update: boolean;
63
+ };