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
@@ -1,17 +1,25 @@
1
1
  import type { BlockDefinition, Layout, LocaleSettings, Operation } from '../core/types.js';
2
2
  import { type LayoutError } from '../core/validate.js';
3
3
  import { type LiveDocStore } from './apply.js';
4
+ import { type LayoutCodec } from './storage.js';
5
+ import { type WriteGate } from './writeGate.js';
4
6
  import type { Awareness, CollaboratorInfo, LiveActor, LiveFlushResponse, MultiplayerEvent } from './types.js';
5
7
  /** The document a session belongs to. */
6
8
  export type SessionTarget = {
7
9
  collection: string;
8
- id: string;
10
+ /** The document id, in the type the collection uses (a number for number ids, else text). */
11
+ id: string | number;
9
12
  /** Name of the layout field. */
10
13
  field: string;
11
14
  /** The collection has drafts: the session saves drafts. */
12
15
  drafts: boolean;
13
16
  /** The collection has draft autosave: the session updates the autosave version in place. */
14
17
  autosave?: boolean;
18
+ /**
19
+ * How the field stores the layout. Left out: the builder's JSON layout. A Payload blocks field
20
+ * is read and written with its codec (live/storage.ts), so it stays the one source of truth.
21
+ */
22
+ codec?: LayoutCodec;
15
23
  };
16
24
  /** Timers and clock. Tests pass fakes. */
17
25
  export type SessionTimers = {
@@ -39,6 +47,11 @@ export type SessionManagerOptions = {
39
47
  logger?: {
40
48
  error(message: string, error?: unknown): void;
41
49
  };
50
+ /**
51
+ * The write gate (live/writeGate.ts). The session's save holds it from before it reads the
52
+ * layout to the commit, so a save of the document outside the session never lands in between.
53
+ */
54
+ gate?: WriteGate;
42
55
  };
43
56
  /** Sends one event to one connection. `id` is the SSE event id (set on session and commit events). */
44
57
  export type SessionSend = (event: MultiplayerEvent, id?: string) => void;
@@ -82,6 +95,7 @@ export type CommitArgs = {
82
95
  access?: (args: {
83
96
  before: Layout;
84
97
  after: Layout;
98
+ ops: readonly Operation[];
85
99
  doc: Record<string, unknown>;
86
100
  }) => Promise<string | null>;
87
101
  /** The document's locales: `update` operations with a `locale` write that locale's values. */
@@ -103,23 +117,31 @@ export type CommitResult = {
103
117
  errors?: LayoutError[];
104
118
  };
105
119
  /**
106
- * A read-only view of an open session. `doc` is the document as the session loaded it, without
107
- * the layout field (other fields may have changed since).
120
+ * A read-only view of an open session. `doc` is the document as the session last read it, without
121
+ * the layout field (a read after a save may still run: access checks use `currentDoc`).
122
+ * `resetting`: a Restore or Revert of the document runs, and the caller is not its own save. Its
123
+ * layout may still be rolled back, so no other save may store it. `adopting`: a committed save's
124
+ * hook changes wait for the session lock. The stored document holds them and `layout` does not
125
+ * yet, so no save may store `layout` until they are in it.
108
126
  */
109
127
  export type SessionSnapshot = {
110
128
  sessionId: string;
111
129
  seq: number;
112
130
  layout: Layout;
113
131
  doc: Record<string, unknown>;
132
+ resetting?: true;
133
+ adopting?: true;
114
134
  };
115
135
  /**
116
136
  * What one save did to the layout through the props' hooks: the layout it got (`input`, the
117
- * session's layout at `seq`) and the layout it stored (`output`).
137
+ * session's layout at `seq`) and the layout it stored (`output`). `sessionId`: the session the save
138
+ * read. Changes from a save of another session are applied, but never count as saved.
118
139
  */
119
140
  export type SavedHookChanges = {
120
141
  input: Layout;
121
142
  output: Layout;
122
143
  seq: number;
144
+ sessionId?: string;
123
145
  };
124
146
  /** The actor of the commits that bring hook changes from a save to the editors. */
125
147
  export declare const FIELD_HOOKS_ACTOR: LiveActor;
@@ -127,6 +149,7 @@ export declare const FIELD_HOOKS_ACTOR: LiveActor;
127
149
  export type SavedInfo = {
128
150
  updatedAt?: unknown;
129
151
  status?: unknown;
152
+ fields?: readonly string[];
130
153
  };
131
154
  export interface SessionManager {
132
155
  /** Opens the session (loading the draft) and adds a connection. Initial events go to `send` first. */
@@ -146,9 +169,14 @@ export interface SessionManager {
146
169
  peek(collection: string, id: string | number): SessionSnapshot | null;
147
170
  /**
148
171
  * Records that a save outside the session stored the layout at `seq` (the save-hook guard),
149
- * and tells the editors with a `saved` event.
172
+ * and tells the editors with a `saved` event. Call it after the save committed: it reads the
173
+ * document's other fields again (`currentDoc`). `info.sessionId`: the session the guard read.
174
+ * When the session has another id now (a reset, or the session closed and opened again), the
175
+ * save counts as a completed write, and none of the session's commits count as saved.
150
176
  */
151
- markSaved(collection: string, id: string | number, seq: number, info?: SavedInfo): void;
177
+ markSaved(collection: string, id: string | number, seq: number, info?: SavedInfo & {
178
+ sessionId?: string;
179
+ }): void;
152
180
  /**
153
181
  * A save outside the session (the save-hook guard) stored the session's layout at `seq` after
154
182
  * the props' hooks changed it. The changed values go to every editor as a commit; a value someone
@@ -157,15 +185,52 @@ export interface SessionManager {
157
185
  adoptSaved(collection: string, id: string | number, changes: SavedHookChanges): void;
158
186
  /** Sends an event to every editor of an open session. False when no session is open. */
159
187
  broadcast(collection: string, id: string | number, event: MultiplayerEvent): boolean;
188
+ /**
189
+ * A save outside the session committed (the Edit view, REST, the Local API). Editors hear of it.
190
+ * With `layoutChanged` (a field that stores its own layout, a Payload blocks field), that save is
191
+ * the truth: the session reads the stored value again and replays its own unsaved commits on top,
192
+ * before its next save. Every call reads the document's other fields again (`currentDoc`), so
193
+ * call it after the save committed. No-op without an open session.
194
+ */
195
+ externalSaved(collection: string, id: string | number, info: SavedInfo & {
196
+ layoutChanged?: boolean;
197
+ }): void;
198
+ /**
199
+ * The document's other fields (not the builder field) as stored now. Every committed save of the
200
+ * document (the session's own, and any from outside, also one that left the layout alone) reads
201
+ * them again; this waits for those reads. Throws when the last read failed and a new one fails
202
+ * too: a check must never run on fields it cannot trust. Null without an open session. Never
203
+ * takes the write gate or the session's lock (a plain read), so it cannot wait on a save.
204
+ */
205
+ currentDoc(collection: string, id: string | number): Promise<Record<string, unknown> | null>;
206
+ /**
207
+ * Runs `check` with `currentDoc`, and again while a save committed during the check changed the
208
+ * fields (so the answer always belongs to the fields as stored when it returns), at most
209
+ * 3 times. Throws when the fields cannot be read or keep changing. Null without an open session.
210
+ */
211
+ withCurrentDoc<T>(collection: string, id: string | number, check: (doc: Record<string, unknown>) => Promise<T>): Promise<{
212
+ value: T;
213
+ } | null>;
160
214
  /**
161
215
  * Replaces the layout of an open session as a whole (Revert to published). Unsaved commits are
162
- * dropped: the caller saves the new layout. The session gets a new id, and every editor gets a
216
+ * dropped: the caller saves the new layout. `stored`: the field value the caller stores (a Payload
217
+ * blocks field's next save builds on it). The session gets a new id, and every editor gets a
163
218
  * fresh `session` event with `reset: true`. False when no session is open.
164
219
  */
165
- reset(collection: string, id: string | number, layout: Layout): Promise<boolean>;
220
+ reset(collection: string, id: string | number, layout: Layout, stored?: unknown): Promise<boolean>;
221
+ /**
222
+ * `reset`, then `save` (the caller's save of that layout: Revert, a version restore). When `save`
223
+ * throws, the session gets back what the reset replaced: its layout, its stored value and its
224
+ * unsaved commits, saved or unsaved as they were (unsaved commits never count as saved, and a
225
+ * session without any stays saved: nothing new is written), and every editor gets that layout
226
+ * again (`reset: true`). Commits made on the new layout meanwhile go. The error is thrown on.
227
+ * Without an open session it only runs `save`.
228
+ */
229
+ resetFor<T>(collection: string, id: string | number, layout: Layout, stored: unknown, save: () => Promise<T>): Promise<T>;
166
230
  /**
167
231
  * Saves now if the session has unsaved commits (also during a retry wait). Resolves when the
168
- * save ends: `ok: false` with the reason when it failed (the session keeps retrying).
232
+ * save ends: `ok: false` with the reason when it failed (the session keeps retrying). First waits
233
+ * for an active Restore or Revert and for the queued hook changes of committed saves.
169
234
  */
170
235
  flush(collection: string, id: string | number): Promise<LiveFlushResponse>;
171
236
  /** Saves every session with unsaved commits. */