payload-canvas 0.1.1 → 0.3.0-next.1

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 (198) hide show
  1. package/README.md +201 -48
  2. package/dist/admin/BuilderTab.js +1 -1
  3. package/dist/admin/diff/LayoutDiff.js +3 -3
  4. package/dist/admin/diff/layoutDiff.scss +48 -48
  5. package/dist/admin/editor/Canvas.js +30 -8
  6. package/dist/admin/editor/DragLayer.js +1 -1
  7. package/dist/admin/editor/Editor.js +2 -0
  8. package/dist/admin/editor/InlineToolbar.js +1 -1
  9. package/dist/admin/editor/Inspector.js +15 -8
  10. package/dist/admin/editor/Outline.js +16 -10
  11. package/dist/admin/editor/Overlay.js +3 -2
  12. package/dist/admin/editor/actions.d.ts +5 -0
  13. package/dist/admin/editor/actions.js +23 -1
  14. package/dist/admin/editor/assistant/AssistantPanel.js +1 -1
  15. package/dist/admin/editor/assistant/ConnectAgents.js +1 -1
  16. package/dist/admin/editor/assistant/assistant.scss +65 -65
  17. package/dist/admin/editor/counts.d.ts +6 -0
  18. package/dist/admin/editor/counts.js +10 -0
  19. package/dist/admin/editor/dnd/displace.js +3 -1
  20. package/dist/admin/editor/dnd/dnd.scss +2 -2
  21. package/dist/admin/editor/editor.scss +186 -133
  22. package/dist/admin/editor/empty/EmptyStart.js +3 -3
  23. package/dist/admin/editor/empty/empty.scss +3 -3
  24. package/dist/admin/editor/fields/ArrayField.js +2 -2
  25. package/dist/admin/editor/fields/access.d.ts +1 -1
  26. package/dist/admin/editor/fields/fields.scss +33 -33
  27. package/dist/admin/editor/generate/GenerateImage.js +1 -1
  28. package/dist/admin/editor/generate/generate.scss +48 -48
  29. package/dist/admin/editor/icons.js +1 -1
  30. package/dist/admin/editor/inline.d.ts +12 -0
  31. package/dist/admin/editor/inline.js +48 -3
  32. package/dist/admin/editor/insert/InsertHandle.js +1 -1
  33. package/dist/admin/editor/insert/spots.js +4 -2
  34. package/dist/admin/editor/layout/FrameResize.js +1 -1
  35. package/dist/admin/editor/layout/LeftPanel.js +1 -1
  36. package/dist/admin/editor/layout/layout.scss +4 -4
  37. package/dist/admin/editor/live/PresenceUI.js +1 -1
  38. package/dist/admin/editor/live/presence.scss +1 -1
  39. package/dist/admin/editor/live/useMultiplayer.js +8 -2
  40. package/dist/admin/editor/locale/LocaleField.d.ts +1 -1
  41. package/dist/admin/editor/locale/LocaleField.js +1 -1
  42. package/dist/admin/editor/locale/locale.scss +12 -12
  43. package/dist/admin/editor/media/ImageEditor.js +22 -16
  44. package/dist/admin/editor/media/actions.d.ts +13 -9
  45. package/dist/admin/editor/media/actions.js +67 -28
  46. package/dist/admin/editor/media/media.scss +23 -23
  47. package/dist/admin/editor/media/model.d.ts +8 -0
  48. package/dist/admin/editor/media/model.js +14 -6
  49. package/dist/admin/editor/menu/Menu.js +1 -1
  50. package/dist/admin/editor/menu/blockMenu.js +13 -8
  51. package/dist/admin/editor/menu/menu.scss +16 -16
  52. package/dist/admin/editor/motion/MotionPanel.js +1 -1
  53. package/dist/admin/editor/motion/model.d.ts +2 -2
  54. package/dist/admin/editor/motion/motion.scss +2 -2
  55. package/dist/admin/editor/regions/RegionOverlay.d.ts +18 -0
  56. package/dist/admin/editor/regions/RegionOverlay.js +44 -0
  57. package/dist/admin/editor/regions/RegionPane.d.ts +5 -0
  58. package/dist/admin/editor/regions/RegionPane.js +26 -0
  59. package/dist/admin/editor/regions/RegionRows.d.ts +1 -0
  60. package/dist/admin/editor/regions/RegionRows.js +23 -0
  61. package/dist/admin/editor/regions/controller.d.ts +73 -0
  62. package/dist/admin/editor/regions/controller.js +231 -0
  63. package/dist/admin/editor/regions/select.d.ts +17 -0
  64. package/dist/admin/editor/regions/select.js +31 -0
  65. package/dist/admin/editor/renderField.js +1 -1
  66. package/dist/admin/editor/runtime.d.ts +6 -0
  67. package/dist/admin/editor/runtime.js +49 -4
  68. package/dist/admin/editor/sections/controller.d.ts +6 -2
  69. package/dist/admin/editor/sections/controller.js +9 -3
  70. package/dist/admin/editor/shortcuts.js +11 -4
  71. package/dist/admin/editor/storage.d.ts +7 -0
  72. package/dist/admin/editor/storage.js +15 -0
  73. package/dist/admin/editor/store.d.ts +39 -0
  74. package/dist/admin/editor/store.js +106 -2
  75. package/dist/admin/editor/styles/ColorPicker.js +1 -1
  76. package/dist/admin/editor/styles/VariantBar.js +1 -1
  77. package/dist/admin/editor/styles/controls.js +1 -1
  78. package/dist/admin/editor/styles/sections.js +1 -1
  79. package/dist/admin/editor/styles/styles.scss +93 -93
  80. package/dist/admin/editor/templates/Bindable.d.ts +1 -1
  81. package/dist/admin/editor/templates/Bindable.js +2 -2
  82. package/dist/admin/editor/templates/SamplePicker.js +2 -2
  83. package/dist/admin/editor/templates/templates.scss +90 -90
  84. package/dist/admin/editor/tooltip/tooltip.scss +4 -4
  85. package/dist/admin/editor/topbar/DocumentActions.js +39 -6
  86. package/dist/admin/editor/topbar/DocumentTitle.js +1 -1
  87. package/dist/admin/editor/topbar/closeSave.d.ts +50 -0
  88. package/dist/admin/editor/topbar/closeSave.js +90 -0
  89. package/dist/admin/editor/topbar/document.d.ts +10 -2
  90. package/dist/admin/editor/topbar/document.js +9 -1
  91. package/dist/admin/editor/topbar/drawerLabels.d.ts +22 -0
  92. package/dist/admin/editor/topbar/drawerLabels.js +69 -0
  93. package/dist/admin/editor/topbar/problems.d.ts +9 -0
  94. package/dist/admin/editor/topbar/problems.js +15 -1
  95. package/dist/admin/editor/topbar/screens/DrawerRouter.d.ts +1 -1
  96. package/dist/admin/editor/topbar/screens/ScreenDrawer.js +1 -1
  97. package/dist/admin/editor/topbar/screens/drawerRouterSupport.d.ts +1 -1
  98. package/dist/admin/editor/topbar/screens/screens.scss +20 -20
  99. package/dist/admin/editor/topbar/settingsDrawer.js +90 -6
  100. package/dist/admin/editor/topbar/settingsDrawer.scss +7 -7
  101. package/dist/admin/editor/topbar/settingsFocus.d.ts +11 -0
  102. package/dist/admin/editor/topbar/settingsFocus.js +46 -0
  103. package/dist/admin/editor/topbar/topbar.scss +47 -47
  104. package/dist/admin/editor/ui/Select.js +1 -1
  105. package/dist/admin/editor/ui/controls.scss +26 -26
  106. package/dist/admin/editor/ui/payloadA11y.d.ts +17 -0
  107. package/dist/admin/editor/ui/payloadA11y.js +12 -5
  108. package/dist/admin/editor/valueStore.d.ts +2 -0
  109. package/dist/admin/editor/valueStore.js +6 -0
  110. package/dist/admin/screen/BuilderScreen.js +1 -1
  111. package/dist/ai/adapters/anthropic.d.ts +2 -2
  112. package/dist/ai/images/service.js +1 -1
  113. package/dist/ai/loop.d.ts +5 -5
  114. package/dist/blocks/defaults.d.ts +9 -9
  115. package/dist/core/bindings.d.ts +1 -1
  116. package/dist/core/dropTarget.js +3 -1
  117. package/dist/core/fieldAccess.js +1 -1
  118. package/dist/core/fieldHooks.d.ts +1 -1
  119. package/dist/core/index.d.ts +2 -0
  120. package/dist/core/index.js +2 -0
  121. package/dist/core/motion.d.ts +7 -7
  122. package/dist/core/payloadBlocks.d.ts +53 -0
  123. package/dist/core/payloadBlocks.js +391 -0
  124. package/dist/core/regions.d.ts +63 -0
  125. package/dist/core/regions.js +239 -0
  126. package/dist/core/types.d.ts +53 -0
  127. package/dist/index.d.ts +1 -0
  128. package/dist/index.js +1 -0
  129. package/dist/live/document.d.ts +9 -1
  130. package/dist/live/document.js +57 -17
  131. package/dist/live/draftAccess.d.ts +36 -0
  132. package/dist/live/draftAccess.js +146 -0
  133. package/dist/live/endpoints.d.ts +11 -2
  134. package/dist/live/endpoints.js +120 -10
  135. package/dist/live/fieldChecks.d.ts +3 -3
  136. package/dist/live/fieldsGuard.d.ts +56 -2
  137. package/dist/live/fieldsGuard.js +107 -11
  138. package/dist/live/index.d.ts +2 -0
  139. package/dist/live/index.js +2 -0
  140. package/dist/live/regions.d.ts +89 -0
  141. package/dist/live/regions.js +401 -0
  142. package/dist/live/runtime.d.ts +1 -1
  143. package/dist/live/runtime.js +5 -2
  144. package/dist/live/session.d.ts +75 -10
  145. package/dist/live/session.js +655 -123
  146. package/dist/live/storage.d.ts +97 -0
  147. package/dist/live/storage.js +267 -0
  148. package/dist/live/types.d.ts +64 -0
  149. package/dist/live/writeGate.d.ts +72 -0
  150. package/dist/live/writeGate.js +478 -0
  151. package/dist/mcp/index.js +56 -12
  152. package/dist/mcp/shared.d.ts +31 -31
  153. package/dist/plugin/hook.d.ts +44 -6
  154. package/dist/plugin/hook.js +176 -20
  155. package/dist/plugin/index.d.ts +23 -1
  156. package/dist/plugin/index.js +175 -13
  157. package/dist/plugin/references.d.ts +4 -2
  158. package/dist/plugin/references.js +2 -0
  159. package/dist/plugin/sectionsBuilder.js +3 -3
  160. package/dist/plugin/templates.js +5 -1
  161. package/dist/protocol/index.d.ts +29 -3
  162. package/dist/react/canvas/BuilderCanvas.js +199 -9
  163. package/dist/react/canvas/frame.d.ts +70 -0
  164. package/dist/react/canvas/frame.js +66 -0
  165. package/dist/react/canvas/inline/dom.d.ts +7 -1
  166. package/dist/react/canvas/inline/dom.js +19 -9
  167. package/dist/react/canvas/inline/mapper.d.ts +26 -0
  168. package/dist/react/canvas/inline/mapper.js +59 -32
  169. package/dist/react/canvas/inline/rich/editor.js +6 -1
  170. package/dist/react/canvas/inline/session.d.ts +7 -1
  171. package/dist/react/canvas/inline/session.js +6 -2
  172. package/dist/react/canvas/measure.js +26 -1
  173. package/dist/react/canvas/thumbnail/ThumbnailCanvas.js +1 -1
  174. package/dist/react/index.d.ts +2 -0
  175. package/dist/react/index.js +2 -0
  176. package/dist/react/motion/style.js +1 -1
  177. package/dist/react/render/LayoutOutlet.d.ts +11 -0
  178. package/dist/react/render/LayoutOutlet.js +16 -0
  179. package/dist/react/render/PayloadRoot.js +1 -1
  180. package/dist/react/render/RenderLayout.js +1 -1
  181. package/dist/react/render/canvasFrame.d.ts +46 -0
  182. package/dist/react/render/canvasFrame.js +59 -0
  183. package/dist/react/render/canvasServer.d.ts +13 -0
  184. package/dist/react/render/canvasServer.js +3 -0
  185. package/dist/react/render/canvasServerTypes.d.ts +17 -0
  186. package/dist/react/render/regions.d.ts +13 -0
  187. package/dist/react/render/regions.js +8 -0
  188. package/dist/react/render/resolve.js +2 -0
  189. package/dist/react/server.d.ts +5 -2
  190. package/dist/react/server.js +6 -2
  191. package/dist/react/theme/ThemeStyle.js +1 -1
  192. package/dist/theme/admin/ColorField.d.ts +2 -2
  193. package/dist/theme/admin/ColorField.js +2 -2
  194. package/dist/theme/admin/FontField.d.ts +2 -2
  195. package/dist/theme/admin/FontField.js +2 -2
  196. package/dist/theme/admin/SaveSignal.js +2 -2
  197. package/dist/theme/admin/fields.scss +48 -48
  198. package/package.json +28 -23
package/README.md CHANGED
@@ -15,11 +15,11 @@
15
15
  </tr>
16
16
  </table>
17
17
 
18
- A visual page builder for Payload CMS 3. It adds a full-screen builder to the collections you choose. Editors drag blocks onto a live canvas, nest them without limit, and style them with Tailwind classes. AI agents can build and edit the same pages over MCP, and an open editor shows each AI change as it happens.
18
+ A visual page builder for Payload CMS 4 beta. It adds a full-screen builder to the collections you choose. Editors drag blocks onto a live canvas, nest them without limit, and style them with Tailwind classes. AI agents can build and edit the same pages over MCP, and an open editor shows each AI change as it happens.
19
19
 
20
20
  The npm package is `payload-canvas`.
21
21
 
22
- - Works in any Payload 3.90+ app on Next.js 16 and React 19.
22
+ - This prerelease targets Payload `4.0.0-beta.3`, Next.js `16.4+` and React 19.
23
23
  - The layout is one JSON field per document. Nothing changes in your other fields.
24
24
  - The site renders the layout with `payload-canvas/react` (React Server Components), or with your own renderer.
25
25
  - Save, drafts, autosave, versions and access control stay Payload's own.
@@ -27,11 +27,9 @@ The npm package is `payload-canvas`.
27
27
 
28
28
  One package holds everything: the Payload plugin and admin editor (`payload-canvas`), and the React renderer and canvas runtime for your site (`payload-canvas/react`). See [Entry points](#entry-points).
29
29
 
30
- **Quick start.** Add the builder to an existing Payload app with the [install guide](#install) (about ten minutes). Or create a new project from the starter app:
30
+ **Quick start.** Add `payload-canvas@next` to an existing Payload `4.0.0-beta.3` app with the [install guide](#install).
31
31
 
32
- ```bash
33
- npx create-payload-canvas my-website
34
- ```
32
+ The bundled starter and `create-payload-canvas@latest` still target Payload 3. This prerelease publishes only the plugin.
35
33
 
36
34
  ## Contents
37
35
 
@@ -43,6 +41,7 @@ npx create-payload-canvas my-website
43
41
  6. [Rendering the layout on your site](#rendering-the-layout-on-your-site)
44
42
  - [Custom components](#custom-components)
45
43
  7. [Server components in the canvas](#server-components-in-the-canvas)
44
+ - [Whole-page editing: regions outside the layout](#whole-page-editing-regions-outside-the-layout)
46
45
  8. [Custom blocks](#custom-blocks)
47
46
  - [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields)
48
47
  9. [Using existing Payload blocks](#using-existing-payload-blocks)
@@ -63,43 +62,37 @@ npx create-payload-canvas my-website
63
62
 
64
63
  ## Requirements
65
64
 
66
- - `payload`, `@payloadcms/ui`, `@payloadcms/richtext-lexical` 3.90 or later (Payload 3 only, not the Payload 4 canary)
67
- - `next` 16.3 or later, `react` and `react-dom` 19.2 or later
65
+ - `payload`, `@payloadcms/ui`, `@payloadcms/richtext-lexical` exactly `4.0.0-beta.3`
66
+ - `next` 16.4 or later, `react` and `react-dom` 19.2 or later
68
67
  - `tailwindcss` 4.3 or later (the plugin compiles your Tailwind entry CSS)
69
- - Node.js 20.9 or later
68
+ - Node.js 24.15 or later; TypeScript 6.0.3 or later for source development
70
69
  - Any Payload database adapter. Postgres and SQLite store the layout as `jsonb`/JSON.
71
70
 
72
- You do not need `transpilePackages` or a `sass` install. The package ships compiled JavaScript. The admin styles are `.scss` files, and Next compiles them with the `sass` that `@payloadcms/next` already installs, the same way it compiles Payload's own admin styles.
71
+ The package ships compiled JavaScript. Its admin styles remain SCSS and use Payload 4 semantic tokens. Payload 4's own admin uses CSS. Install `sass` if your app does not already provide it.
73
72
 
74
73
  Peer dependencies:
75
74
 
76
75
  | Package | Range | Needed for |
77
76
  |---|---|---|
78
- | `payload`, `@payloadcms/ui`, `@payloadcms/richtext-lexical` | `^3.90.0` | everything |
79
- | `next` | `^16.3.0` | everything |
77
+ | `payload`, `@payloadcms/ui`, `@payloadcms/richtext-lexical` | `4.0.0-beta.3` | everything |
78
+ | `next` | `^16.4.0` | everything |
80
79
  | `react`, `react-dom` | `^19.2.0` | everything |
81
80
  | `tailwindcss` | `^4.3.0` | the CSS compile on save and in the canvas |
82
81
  | `@anthropic-ai/sdk` | `>=0.131.0`, optional | only the `/ai/anthropic` adapter |
83
- | `payload-mcp-toolkit` | `>=0.9.0`, optional | only `builderMcpTools()` (`/mcp`) |
82
+ | `payload-mcp-toolkit` | `0.10.0-next.1`, optional | only `builderMcpTools()` (`/mcp`) |
84
83
  | `zod` | `^3.25 \|\| ^4`, optional | only `builderMcpTools()` (`/mcp`) |
85
84
 
86
85
  ## Install
87
86
 
88
- These steps start from a blank Payload app with Postgres:
89
-
90
- ```bash
91
- npx create-payload-app@latest -n my-site -t blank --db postgres --use-pnpm
92
- ```
93
-
94
- They were tested step by step on such an app with Payload 3.90.2, Next.js 16.3.3, React 19.2.6, Tailwind 4.3.3, TypeScript 5.7 and pnpm 10, in `next dev` and in `next build` + `next start`. An existing Payload app works the same way: skip what you already have.
87
+ These steps start from an existing Payload `4.0.0-beta.3` app. Keep every `@payloadcms/*` package on that exact beta version.
95
88
 
96
89
  ### 1. Add the package
97
90
 
98
91
  ```bash
99
- pnpm add payload-canvas tailwindcss @tailwindcss/postcss postcss
92
+ pnpm add payload-canvas@next tailwindcss @tailwindcss/postcss postcss sass
100
93
  ```
101
94
 
102
- With npm: `npm install payload-canvas tailwindcss @tailwindcss/postcss postcss`.
95
+ With npm: `npm install payload-canvas@next tailwindcss @tailwindcss/postcss postcss sass`.
103
96
 
104
97
  ### 2. Add a collection with pages
105
98
 
@@ -254,19 +247,32 @@ export default async function CanvasLayout({ children }: { children: ReactNode }
254
247
  }
255
248
  ```
256
249
 
250
+ The page is a server component that imports the server action, and passes it to a small client component that renders `BuilderCanvas`:
251
+
257
252
  ```tsx
258
- // src/app/(builder-canvas)/builder-canvas/page.tsx
253
+ // src/app/(builder-canvas)/builder-canvas/page.tsx (a server component: no 'use client')
254
+ import { builderCanvas } from './actions'
255
+ import { CanvasClient } from './CanvasClient'
256
+
257
+ export default function CanvasPage() {
258
+ return <CanvasClient server={builderCanvas} />
259
+ }
260
+ ```
261
+
262
+ ```tsx
263
+ // src/app/(builder-canvas)/builder-canvas/CanvasClient.tsx
259
264
  'use client'
260
265
 
261
- import { BuilderCanvas } from 'payload-canvas/react/canvas'
266
+ import { BuilderCanvas, type BuilderCanvasProps } from 'payload-canvas/react/canvas'
262
267
  import { blocks } from '@/builder'
263
- import { builderCanvas } from './actions'
264
268
 
265
- export default function CanvasPage() {
266
- return <BuilderCanvas blocks={blocks} server={builderCanvas} />
269
+ export function CanvasClient({ server }: { server: BuilderCanvasProps['server'] }) {
270
+ return <BuilderCanvas blocks={blocks} server={server} />
267
271
  }
268
272
  ```
269
273
 
274
+ Keep the page a server component. The server action returns React Server Component output that holds client components: yours inside server-rendered blocks (an image, a carousel), and the builder's own (slot outlets, the page frame's layout). Next registers them in the route's client manifest only when a server component of the route imports the action. When a `'use client'` page imports it, they are missing, and the canvas shows "Could not find the module … in the React Client Manifest". Client-only props (`plugins`, `components`, `resolveLink`) belong in `CanvasClient`.
275
+
270
276
  ```ts
271
277
  // src/app/(builder-canvas)/builder-canvas/actions.ts
272
278
  'use server'
@@ -541,10 +547,11 @@ websiteBuilder({
541
547
  | Option | Type | What it does |
542
548
  |---|---|---|
543
549
  | `collections` | `Record<slug, { field?, url?, templates? }>` | The collections that get the builder. Required. |
544
- | `collections[slug].field` | `string` | Name of the layout JSON field. Default `layout`. The generated CSS goes in `<field>Css`. If a `json` field with this name exists (also inside rows, collapsibles or unnamed tabs), the plugin reuses it and moves it to the top level. |
550
+ | `collections[slug].field` | `string` | Name of the builder's field. Default `layout`. Its type decides the storage. A Payload `blocks` field of the collection: the builder edits that field itself, the one source of truth (see [Using existing Payload blocks](#using-existing-payload-blocks)). Otherwise the builder's JSON layout: the generated CSS goes in `<field>Css`, and a `json` field with this name (also inside rows, collapsibles or unnamed tabs) is reused and moved to the top level. |
545
551
  | `collections[slug].url` | `(doc) => string` | The frontend path of a document. AI tools use it for preview links. The collection list block uses it for links. |
546
552
  | `collections[slug].templates` | `boolean` | Documents render through templates. See [Templates](#templates-and-binding). |
547
553
  | `collections[slug].legacyFields` | `string[]` | Top-level fields the builder replaced but the collection still has (the old `blocks` field after `migrateBlocksField`). **Publish** in the builder keeps their published value, so only the builder content goes live. See [Using existing Payload blocks](#using-existing-payload-blocks), step 7. |
554
+ | `collections[slug].regions` | `{ name, label?, fields }[]` | Fixed parts of the page that show ordinary document fields outside the layout (a header made of the title and an image). The builder shows and edits the whole page. Left out: the layout alone. See [Whole-page editing](#whole-page-editing-regions-outside-the-layout). |
548
555
  | `collections[slug].localization` | `'props' \| false` | With Payload `localization` on: `'props'` (the default) translates localized props in one shared layout; `false` keeps one set of values. See [Localization](#localization). |
549
556
  | `blocks` | `BlockDefinition[]` | The blocks editors can use. Default `defaultBlocks()`. |
550
557
  | `sections` | `SectionDefinition[]` | Ready-made sections. See [Sections](#sections). |
@@ -727,6 +734,8 @@ The canvas renders a block on the server when:
727
734
  | `components` | The server map. |
728
735
  | `resolveLink` | The same link resolver as the site. |
729
736
  | `pageData` | `({ payload, user, document, context, locale }) => data`: the page data. `locale` is the language the editor shows (null without localization); load your data in it. See below. |
737
+ | `frame` | `({ doc, layout, region, … }) => ReactNode`: the page around the layout, for collections with `regions`. See [Whole-page editing](#whole-page-editing-regions-outside-the-layout). |
738
+ | `frameDepth` | The `depth` of the document `frame` gets. Default 1. |
730
739
 
731
740
  How it works in the editor:
732
741
 
@@ -785,6 +794,112 @@ The loader also gets `user`, `document` (the document open in the builder, `{ co
785
794
 
786
795
  Only components that ask for the page data get it: every `fromPayloadComponent` component, and components marked with `withPageData(Component)` (they get it as `pageData`). So a client component does not carry the page data in the page's payload.
787
796
 
797
+ ## Whole-page editing: regions outside the layout
798
+
799
+ Many pages show more than their layout. A header shows the page's `title` and `coverImage` fields; a post shows its author above the body. These fields are ordinary Payload fields, rendered by your own component before or after the layout. Without regions, the canvas shows the layout alone, so these parts are missing in the editor.
800
+
801
+ Regions make the canvas show the whole page and let editors edit those fields in place. The fields stay where they are: the builder never copies them into the layout, and no sync runs. A region is fixed: it can be selected and edited, but never dragged, duplicated or deleted.
802
+
803
+ Regions are optional. A site that builds its pages from blocks alone needs none of this, and the editor does no extra work without them.
804
+
805
+ **1. Name the regions** of a collection. Each region lists the document fields it shows, by dot path. Fields in rows, collapsibles and unnamed tabs are named directly; a path goes through groups and named tabs (`header.title`). Name an array or upload field as a whole.
806
+
807
+ ```ts
808
+ websiteBuilder({
809
+ collections: {
810
+ pages: {
811
+ field: 'layout',
812
+ regions: [{ name: 'header', label: 'Header', fields: ['title', 'subtitle', 'coverImage', 'links'] }],
813
+ },
814
+ },
815
+ // ...
816
+ })
817
+ ```
818
+
819
+ The plugin checks the paths when it starts. It refuses the layout field and its own fields, Payload's `id`, `_status` and timestamps, `legacyFields`, join and virtual fields, paths through arrays, and a field in two regions.
820
+
821
+ **2. Put the page around the layout in one component**, used by the site and by the canvas. It gets the document, the layout to render, and `region`, which marks the part that shows a region:
822
+
823
+ ```tsx
824
+ // src/components/PageFrame.tsx (a server component)
825
+ import type { ReactNode } from 'react'
826
+ import type { RegionMark } from 'payload-canvas/react'
827
+ import type { Page } from '@/payload-types'
828
+ import { PageHeader } from './PageHeader'
829
+
830
+ export function PageFrame({ page, layout, region }: { page: Page; layout: ReactNode; region: RegionMark }) {
831
+ return (
832
+ <>
833
+ {region('header', <PageHeader title={page.title} subtitle={page.subtitle} image={page.coverImage} links={page.links} />)}
834
+ <main>{layout}</main>
835
+ </>
836
+ )
837
+ }
838
+ ```
839
+
840
+ `region(name, node)` adds no element. In the canvas it puts the region's mark on the first element of `node`. On the site you pass `siteRegion`, which returns `node` as it is. The frame's output holds client components (the layout outlet, the region mark), so the canvas page must be a server page that imports the action ([step 6 of Install](#6-add-the-canvas-route)).
841
+
842
+ **3. Render it on the site** with `siteRegion`:
843
+
844
+ ```tsx
845
+ import { siteRegion } from 'payload-canvas/react'
846
+
847
+ <PageFrame page={page} region={siteRegion} layout={<RenderLayout layout={layout} css={css} components={serverComponents} />} />
848
+ ```
849
+
850
+ **4. Render it in the canvas** with the `frame` option of `createCanvasServer`. The action file then holds JSX, so name it `actions.tsx`:
851
+
852
+ ```tsx
853
+ // src/app/(builder-canvas)/builder-canvas/actions.tsx
854
+ 'use server'
855
+
856
+ import config from '@payload-config'
857
+ import { createCanvasServer, type CanvasServerRequest } from 'payload-canvas/react/server'
858
+ import { blocks } from '@/builder'
859
+ import { serverComponents } from '@/components/blocks.server'
860
+ import { PageFrame } from '@/components/PageFrame'
861
+ import type { Page } from '@/payload-types'
862
+
863
+ const canvas = createCanvasServer({
864
+ config,
865
+ blocks,
866
+ components: serverComponents,
867
+ frame: ({ document, doc, layout, region }) =>
868
+ document.collection === 'pages' ? <PageFrame page={doc as Page} layout={layout} region={region} /> : layout,
869
+ })
870
+
871
+ export async function builderCanvas(request: CanvasServerRequest) {
872
+ return canvas(request)
873
+ }
874
+ ```
875
+
876
+ `frame` gets the document's latest draft, read as the signed-in user, at `frameDepth` (default 1, so uploads and relationships arrive as documents), in the language the editor shows. It also gets `pageData`, `user`, `locale`, `context` and `mode`. Put `layout` where the page shows the layout: the canvas renders the live layout there, so every block stays selectable, draggable and editable at once. Return `layout` alone (or `null`) to show the layout without a frame.
877
+
878
+ **What editors can do with a region:**
879
+
880
+ - Hover or click it on the canvas, or click it in the **Layers** panel above the tree. The inspector shows its fields; **Edit fields** opens the page settings drawer at the region's first field. The drawer is Payload's own form, so every field type works with Payload's validation, hooks and access.
881
+ - Double-click its text to edit it in place: text, textarea and rich text fields, also inside array rows and groups. Double-click an image (or drop a file on it) to replace it, as in blocks. The automatic mapping finds the elements by their values, as for blocks. For elements it cannot find, `frame` gets `mode` (`'canvas'`): pass it on and mark them with `editableText(mode, path)` and `editableImage(mode, path)`, with the field's document path (`links.0.label`). On the site, pass `'site'`.
882
+ - Each change saves to the document when editing ends, as the user: a draft on collections with drafts, so **Publish** publishes it with the layout. One Ctrl+Z undoes it, and redo works too.
883
+ - Saves from anywhere show on every open canvas: a region edit, the settings drawer, REST, another editor. The `saved` event lists the fields a save changed, and the canvas asks for the frame again.
884
+
885
+ **What protects the fields:**
886
+
887
+ - The fields endpoint (`POST {api}/builder/live/:collection/:id/fields`) takes only paths inside the regions. It checks the user's update access to the document and to each field (Payload's own document access) and says no with 403, instead of dropping the change without a word.
888
+ - Each change carries the value the editor saw, also through a long inline edit. When someone else changed the field since, the save is refused (409) and the canvas shows their value. The answer never holds values the user may not read, also inside groups and array rows, and a save keeps those fields as they are.
889
+ - Undo and redo of a region change write the language the change was made in, and expect the value the server stored after the fields' hooks.
890
+ - Someone else's document lock (the Edit view or the settings drawer) refuses the save with 423. While your own settings drawer is open, canvas edits of region fields wait: the drawer's form holds its own copy of the fields.
891
+ - An open settings drawer renews its protection. If a close or renewal request is lost, protection expires after the configured document-lock duration (300 seconds by default).
892
+ - Saves of one document never overlap. Payload's update reads the newest version and writes the whole version back, so two overlapping saves (a layout save and a settings autosave) could lose one of the changes. The plugin lets one update of a builder document run at a time, from Payload's read to the commit of its transaction. This applies to every builder collection, with or without regions. A save that cannot get its turn (a wait that would never end) fails with a clear 409 instead. Editors hear of a save only after the database committed it: a rollback or a failed commit announces nothing.
893
+
894
+ **When the frame cannot show,** the canvas says so above the layout, and the layout stays editable: no `server` on `BuilderCanvas`, no `frame` option, a frame that throws, or a frame that never renders `layout`.
895
+
896
+ Limits:
897
+
898
+ - The canvas edits text, textarea, rich text and upload fields of a region. Edit other field types (selects, checkboxes, relationships, dates) in the settings drawer.
899
+ - Typing in a region reaches other editors when the editing ends, not letter by letter.
900
+ - AI tools (MCP and the assistant) edit the layout only.
901
+ - Templates show no frame: a template's regions would be its sample document's fields.
902
+
788
903
  ## Custom blocks
789
904
 
790
905
  Declare a block with `defineBlock`. Props are Payload field configs. The editor builds its inputs from them, and the plugin builds a JSON Schema for validation and AI tools.
@@ -874,7 +989,17 @@ Limits:
874
989
 
875
990
  ## Using existing Payload blocks
876
991
 
877
- A site that already has a Payload `blocks` field (for example `pages.layout` with sections and nested blocks) can keep its block configs and its components. The builder gets a field of its own, one script copies the content over, and the old field stays until you remove it.
992
+ A site that already has a Payload `blocks` field (for example `pages.layout` with sections and nested blocks) keeps its field, its block configs, its components and its content. Point the builder at that field. The builder then edits the field itself: there is one source of truth, no second copy of the page, and nothing to migrate.
993
+
994
+ ```ts
995
+ websiteBuilder({
996
+ collections: { pages: { field: 'layout', url: (doc) => `/${doc.slug}` } },
997
+ blocks,
998
+ css: { entry: 'src/app/(frontend)/globals.css' },
999
+ })
1000
+ ```
1001
+
1002
+ The type of the field decides how the builder stores the layout. A `blocks` field: the builder reads and writes that field. A `json` field, or no field with that name: the builder's own JSON layout, with every feature. There is no switch per document.
878
1003
 
879
1004
  What carries over:
880
1005
 
@@ -883,7 +1008,7 @@ What carries over:
883
1008
  - **Conditions.** An `admin.condition` that tests one sibling field, such as `(_, siblingData) => siblingData?.type === 'custom'`, becomes a JSON condition. The inspector hides the field, and an empty required field that is hidden does not block publishing.
884
1009
  - **Components.** `fromPayloadComponents()` renders components written for Payload's data (`{ blockType, ...fields }`) unchanged.
885
1010
  - **Field logic.** `validate`, field hooks and field `access` of the block fields run in the builder and the API, as in Payload. See [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields).
886
- - **Content.** `migrateBlocksField()` converts every document, its drafts and its versions.
1011
+ - **Content.** Nothing to convert: the builder edits the blocks field itself.
887
1012
  - **Canvas editing.** Text and images of your components edit in place on the canvas, with no marks in your code. See [Inline editing](#inline-editing).
888
1013
 
889
1014
  ### Step by step
@@ -892,17 +1017,7 @@ These steps assume a site like this: `pages.layout` is a `blocks` field that ref
892
1017
 
893
1018
  **1. Install** the package and add the canvas route, as in [Install](#install).
894
1019
 
895
- **2. Give the builder its own field.** Keep `layout` as it is.
896
-
897
- ```ts
898
- websiteBuilder({
899
- collections: { pages: { field: 'builderLayout', url: (doc) => `/${doc.slug}` } },
900
- blocks,
901
- css: { entry: 'src/app/(frontend)/globals.css' },
902
- })
903
- ```
904
-
905
- If you give the builder the name of the existing `blocks` field (`field: 'layout'`), the app does not start, and the error points here.
1020
+ **2. Point the builder at your blocks field** (`field: 'layout'`, as above). Keep the field as it is: its place, its admin options, its hooks, its access and its versions do not change. The plugin adds a Builder tab, and a hidden virtual field (`layoutBuilder`, no database column) that carries the editor's config.
906
1021
 
907
1022
  **3. Make builder blocks from your block configs.** Put them in the client-safe blocks file:
908
1023
 
@@ -933,6 +1048,8 @@ export const blocks = [...defaultBlocks({ linkCollections: ['pages'] }), ...site
933
1048
 
934
1049
  `labels.singular` becomes the label, and `admin.group` the library category. `interfaceName`, `dbName`, `imageURL` and the block's own admin components are not used.
935
1050
 
1051
+ Every block type the field holds, at any depth and through `blockReferences`, needs a builder block. The app does not start without one, and the error names the missing slugs.
1052
+
936
1053
  **4. Wrap your components.** Use the same map as your `RenderBlocks`, keyed by Payload slug:
937
1054
 
938
1055
  ```ts
@@ -950,7 +1067,32 @@ Each component gets the props it always got: `{ id, blockType, blockName, ...fie
950
1067
  - **Components that take `{ block, context }`** instead of the fields as props: add `{ props: (block, context) => ({ block, context }) }` as the third argument. `context` is the page data. See [Page data](#page-data-and--block-context--components).
951
1068
  - **Components that load data** (async server components, or components that import Payload): leave them out of this client-safe map and put them in the server map. The canvas renders them on the server. See [Server components in the canvas](#server-components-in-the-canvas). A section whose file imports such a component (through its own `RenderLeaves`) goes in the server map too.
952
1069
 
953
- **5. Convert the content.** Run a dry run first. It writes nothing and lists what it would do:
1070
+ **5. Keep your page route.** The site renders `page.layout` with its own `RenderBlocks`, as before. Canvas edits are in that field right after each save.
1071
+
1072
+ ### How the builder edits a Payload blocks field
1073
+
1074
+ - **One field.** When the builder opens a page, it reads the stored blocks (`depth: 0`) into the editor. Each save writes them back to the same field through Payload's Local API, as the editor's user (`overrideAccess: false`). Payload's field hooks, validation, access, versions and locales run once per save, as for a save in Payload's editor. Opening the builder saves nothing.
1075
+ - **Nothing lost.** A round trip keeps every stored value: fields the inspector does not show, unknown keys, `null` and empty values, block ids and order, `blockName` (the block's name in the builder), array rows with their ids, groups, nested blocks fields inside groups and arrays, and upload and relationship ids. No HTML is read back and no defaults are added. Data the builder cannot keep exactly (a block type without a builder block, two blocks with one id) is not changed: the builder refuses to open the page (422) and says why. Payload's editor still opens it.
1076
+ - **Saves from elsewhere win.** A save from Payload's editor, the REST API or the Local API is the stored truth. An open builder shows it at once and replays its own unsaved edits on top, after every such save until the builder saves.
1077
+ - **Copied rows.** Rows pasted from another page or inserted from a saved section get new ids. The page keeps its own row ids through remove, save, undo and save.
1078
+ - **Hooks.** After each save the builder reads the stored blocks again. What Payload's hooks stored becomes the builder's state at once: changed values and also added, removed or moved blocks. Edits made while the save ran stay on top. So a later edit or undo keeps what the hooks did.
1079
+ - **Old forms.** A form that loaded the page before its blocks last changed (the builder's settings drawer, a second tab) sends the blocks back as it loaded them. When the form did not change them, the save keeps the newer blocks. When it did, the save is refused (409, "Not saved. … changed Layout after you opened this form"), also when the same person made both changes.
1080
+ - **Publish, revert and restore** work on the same field. Publish stops if pending edits cannot be saved. Revert and restore require read access to every source value and update access to the blocks field. Payload's own version restore also updates an open builder after the transaction commits.
1081
+
1082
+ ### Limits of a Payload blocks field
1083
+
1084
+ - **One language in the builder.** The builder edits the default locale. Translations stay in Payload's editor, and a canvas save keeps every other locale's values.
1085
+ - **No builder-only block data.** A Payload block has no place for Tailwind classes, animations, bindings or hidden blocks. The builder turns off the Styles and Motion tabs, Copy, Paste and Reset styles, and "Hide", also for blocks whose definition sets `styles: true` for JSON layouts. The editor refuses a change that carries such data before it shows it, and the server refuses it too (422): nothing of it is saved. The library lists only the sections and saved sections the field can store.
1086
+ - **No templates.** Templates hold builder JSON layouts. The plugin refuses `templates: true` on a collection whose builder field is a `blocks` field.
1087
+ - **Access.** The live session holds every value of the blocks, also values not saved yet. Payload's field `access.read` decides on those values themselves: stored ones and the open session's. A user who may not read one of them, or may not update the blocks field itself, cannot open, change or save the page in the builder or through MCP (403). The check runs on every request, and an open event stream checks each event before it goes out, against the values that event carried when it was sent: when the user may not read one, the stream ends instead. A reconnect gets the current state, never old changes. They edit in Payload's editor, which keeps the hidden values.
1088
+
1089
+ ### Copying into a builder JSON field (opt-in)
1090
+
1091
+ Copy the content into a builder field of its own only when you want what a Payload block cannot hold: Tailwind classes, animations, bindings, hidden blocks, translations in the builder, or templates. The copy is one-way. After it, the builder field is the page's content, and the old field stays only until you remove it.
1092
+
1093
+ Give the builder a field of its own (`field: 'builderLayout'`), then convert the content:
1094
+
1095
+ **Convert the content.** Run a dry run first. It writes nothing and lists what it would do:
954
1096
 
955
1097
  ```ts
956
1098
  // scripts/migrate-blocks.ts
@@ -990,9 +1132,9 @@ Close every builder tab while it runs. An open builder keeps its own copy of the
990
1132
  - It writes through the database adapter (`updateOne`, `updateVersion`), so no hooks run. It compiles the CSS itself. Tested on Postgres. On MongoDB it converts the documents but not the versions.
991
1133
  - Options: `where` (only some documents), `versions: false`, `overwrite`, `blocks` (default: the plugin's blocks), `log`.
992
1134
 
993
- **6. Render pages with the builder.** Change the page route to `RenderLayout` with `page.builderLayout` and `page.builderLayoutCss` (see [step 7 of Install](#7-render-pages-on-the-site)). Pass your wrapped `components` to `RenderLayout` and to `BuilderCanvas`.
1135
+ **Render pages with the builder.** Change the page route to `RenderLayout` with `page.builderLayout` and `page.builderLayoutCss` (see [step 7 of Install](#7-render-pages-on-the-site)). Pass your wrapped `components` to `RenderLayout` and to `BuilderCanvas`.
994
1136
 
995
- **7. Keep the old field out of Publish, and remove it later.** Payload publishes the whole document. Without more setup, **Publish** in the builder would also publish the old field's latest draft (for example an edit someone made in the Edit view after the migration). List the old field in `legacyFields`:
1137
+ **Keep the old field out of Publish, and remove it later.** Payload publishes the whole document. Without more setup, **Publish** in the builder would also publish the old field's latest draft (for example an edit someone made in the Edit view after the migration). List the old field in `legacyFields`:
996
1138
 
997
1139
  ```ts
998
1140
  websiteBuilder({
@@ -1035,7 +1177,7 @@ The `builder` prop holds `mode`, `className`, `slots` (rendered children by slot
1035
1177
  - **Custom admin components** on fields (a custom `Field`) need Payload's form, so the inspector shows the default input for the field type. `fromPayloadBlocks` lists them in a warning.
1036
1178
  - **Conditions** that read the document, the user or several fields are not converted: the field always shows (also listed in a warning). Function `defaultValue`s of block fields do not run in the builder. `validate`, field hooks and field `access` do run: see [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields).
1037
1179
  - **Loaded data** is one level deep. A component that needs deeper data loads it itself.
1038
- - **Blocks fields inside a group, a named tab or an array** stay props, edited as JSON. Localized block fields are not supported.
1180
+ - **Blocks fields inside a group, a named tab or an array** stay props, edited as JSON. With a Payload blocks field as the builder field, localized fields inside blocks keep every locale, and the builder edits the default locale. A copied JSON layout does not support localized block fields.
1039
1181
  - A Payload slug `list` with an `items` array is read as the old built-in list (`normalizeLayout`). Use `prefix` to avoid that.
1040
1182
 
1041
1183
  ## Sections
@@ -1696,9 +1838,14 @@ Several people can have the same page open in the builder. Each change shows for
1696
1838
  How it works:
1697
1839
 
1698
1840
  - The server keeps one live session per open document, in memory. The session holds the layout and a sequence number `seq`.
1841
+ - Live editing requires access to the newest draft. Read access limited to published documents does not grant access to the live draft.
1842
+ - This also applies before the first draft save. The server checks collection read access on every streamed event and live edit. Query rules on the layout field cannot be checked against unsaved edits, so they refuse live editing. Other query rules use Payload's current stored document. A user role change applies after reconnecting.
1843
+ - After each committed save, the session reads the document's other fields again. Block access checks use those current fields, including for events still waiting to be sent. If the read fails, the check refuses access.
1699
1844
  - An editor applies its own change at once, then sends it to `commit`. The server applies changes in the order they arrive, raises `seq` by 1, and sends each change to every open editor. A change that no longer applies (for example, someone deleted its block) is rejected, and that editor drops it.
1700
1845
  - The server saves the session as a draft about 1 second after the last change (at the latest every 5 seconds). The save runs as the person who made the last change, with their access rules, and the normal save hook compiles the CSS.
1701
- - While a session is open, the session owns the layout. Any other save of the document gets the session's layout: a stale autosave from another tab, a REST update, or **Publish**. Publish therefore publishes what everyone sees in the editor.
1846
+ - For native JSON layouts, an open session protects its unsaved layout from other document saves. Publish first saves pending edits and stops if that save fails. Payload's own version restore replaces the session from the restored version after commit. Existing Payload blocks fields follow the authoritative stored field, as described above.
1847
+ - Builder Restore and Revert pause background layout saves and outside layout sync until their save finishes. Concurrent actions run in order. Flush waits for an active action. Other JSON document saves during the action return 409; retry after it finishes. This includes Publish if the action starts after its flush. A failed action keeps earlier unsaved edits, and outside saves remain authoritative.
1848
+ - Flush also waits for a committed save's field-hook changes to reach the live session. Other guarded JSON saves return 409 while those changes wait. Retry after they apply. Background saves resume automatically.
1702
1849
  - Every editor gets a `saved` event after each save and a `published` event after Publish, Unpublish or Revert, so the top bar shows the same status for everyone.
1703
1850
  - The session closes 60 seconds after the last editor leaves and its draft is saved.
1704
1851
 
@@ -1709,9 +1856,12 @@ The other fields (title, slug, SEO, …) are edited in Payload's Edit view or in
1709
1856
 
1710
1857
  To turn the lock off for a collection, set `lockDocuments: false` on it. The out-of-date check still runs.
1711
1858
 
1859
+ Saves of one document never overlap: Payload's update reads the newest version and writes the whole version back, so a session save and a settings autosave that overlap could put back the other one's old values. The plugin lets one update of a builder document run at a time, from Payload's read to the commit of its database transaction. Saves of different documents still run at the same time. Like the sessions, this works inside one server process.
1860
+
1712
1861
  Limits:
1713
1862
 
1714
1863
  - Sessions live in the memory of one server process. With more than one app server, route all requests for a document to the same server (sticky routing), or keep one app server.
1864
+ - Builder collections disable bulk editing. Bulk updates (`payload.update` with `where`) return 403 or 409. Update each document by ID. This keeps every update inside the write gate. Bulk publish, unpublish, trash changes and folder moves are unavailable; use the document's Edit view. Permanent bulk delete still works.
1715
1865
  - Two people who change the same prop at the same time: the later change wins.
1716
1866
  - On SIGINT/SIGTERM the plugin saves unsaved session edits before the process exits. To make that possible, it holds back `process.exit` for at most 3 seconds, and only while unsaved edits exist. A hard kill (`SIGKILL`, a crash) can still lose the last 1–5 seconds of edits.
1717
1867
  - Two people typing in the same text field at the same moment: the later value wins for the whole field.
@@ -1789,7 +1939,9 @@ All entries must show one version. Pin `payload`, `@payloadcms/*` and `next` to
1789
1939
 
1790
1940
  **Saving fails with "Tailwind plugin "x" is used by @plugin in the CSS entry but is not in the plugins map".** Add the plugin to `css.plugins` and to the canvas page's `plugins`.
1791
1941
 
1792
- **"Collection "pages" already has a "blocks" field named "layout"".** The builder needs a `json` field. Give it its own name (`field: 'builderLayout'`) and convert the content: see [Using existing Payload blocks](#using-existing-payload-blocks).
1942
+ **""pages.layout" is a Payload blocks field, and the builder has no definition for its block "x"".** Every block type of the field needs a builder block. Add its config to `fromPayloadBlocks()` (with `references` for `blockReferences`): see [Using existing Payload blocks](#using-existing-payload-blocks).
1943
+
1944
+ **"The builder cannot open these blocks without changing them: …".** The stored blocks hold data the builder cannot keep exactly, for example a block type without a builder block. The message names it. Add the block, or fix the page in Payload's editor.
1793
1945
 
1794
1946
  **"Two blocks have the type "heading"".** A block made with `fromPayloadBlocks` has the same type as another block. Set `prefix` in `fromPayloadBlocks`.
1795
1947
 
@@ -1799,7 +1951,7 @@ All entries must show one version. Pin `payload`, `@payloadcms/*` and `next` to
1799
1951
 
1800
1952
  ## Limits
1801
1953
 
1802
- This is version 0.1. Before 1.0, a minor version can change the API. Known limits:
1954
+ This is version 0.2. Before 1.0, a minor version can change the API. Known limits:
1803
1955
 
1804
1956
  - **Payload 3 only.** Payload 4 (canary today) changes the admin UI. The builder does not support it yet.
1805
1957
  - **Next.js and React only.** The admin editor and the canvas need a Next.js app (Payload's own requirement). Other frontends can render the stored JSON with their own code.
@@ -1807,6 +1959,7 @@ This is version 0.1. Before 1.0, a minor version can change the API. Known limit
1807
1959
  - **The canvas runtime runs only in the editor's iframe.** `payload-canvas/react/canvas` belongs on the canvas route and nowhere else.
1808
1960
  - **Tailwind CSS v4 only.** Styles are Tailwind classes, compiled from your Tailwind v4 entry CSS.
1809
1961
  - **One server process.** Live sessions live in memory. See [Multiplayer editing](#multiplayer-editing) and [Deploying](#deploying). Serverless platforms are not supported.
1962
+ - **Updates by ID.** Builder collections disable bulk editing and refuse bulk updates with 403 or 409. Update each document by ID to preserve the order of saves.
1810
1963
  - **Tested databases.** Postgres is tested end to end. Other Payload adapters store the layout in a JSON field and should work, but are not tested.
1811
1964
  - **The editor's own labels are in English.** Payload's inputs inside it follow the admin language.
1812
1965
 
@@ -11,5 +11,5 @@ export function BuilderTab() {
11
11
  const { config: { routes }, } = useConfig();
12
12
  if (id === undefined || id === null || !collectionSlug)
13
13
  return null;
14
- return (_jsx(Button, { buttonStyle: "tab", className: "doc-tab", el: "link", margin: false, size: "medium", to: builderViewPath(routes.admin, collectionSlug, id), children: _jsx("span", { className: "doc-tab__label", children: "Builder" }) }));
14
+ return (_jsx(Button, { buttonStyle: "ghost", className: "doc-tab", el: "link", margin: false, size: "medium", to: builderViewPath(routes.admin, collectionSlug, id), children: _jsx("span", { className: "doc-tab__label", children: "Builder" }) }));
15
15
  }
@@ -51,12 +51,12 @@ function ChangeRow({ change, settings }) {
51
51
  return (_jsxs("li", { className: `${base}__change ${base}__change--${change.kind}`, children: [_jsxs("div", { className: `${base}__head`, children: [_jsx("span", { className: `${base}__pill ${base}__pill--${change.kind}`, children: KIND_LABELS[change.kind] }), _jsx("strong", { className: `${base}__name`, children: change.name }), (change.kind === 'added' || change.kind === 'removed') && change.where ? (_jsxs("span", { className: `${base}__where`, children: ["in ", change.where] })) : null, (change.kind === 'added' || change.kind === 'removed') && change.inside > 0 ? (_jsxs("span", { className: `${base}__where`, children: ["with ", change.inside, " ", change.inside === 1 ? 'block' : 'blocks', " inside"] })) : null, change.kind === 'moved' ? (_jsxs("span", { className: `${base}__where`, children: ["from ", change.from, " to ", change.to] })) : null] }), change.kind === 'changed' ? (_jsx("ul", { className: `${base}__details`, children: change.details.map((detail, index) => (_jsx(Detail, { detail: detail, settings: settings }, index))) })) : null] }));
52
52
  }
53
53
  export function LayoutDiff(props) {
54
- const { comparisonValue, versionValue, field, clientField, i18n, locale, nestingLevel, selectedLocales } = props;
54
+ const { valueFrom, valueTo, field, clientField, i18n, locale, nestingLevel, selectedLocales } = props;
55
55
  const builder = field.admin?.custom?.builder;
56
56
  const settings = builder?.localization ?? null;
57
57
  // Translations follow the locales picked in the compare view; all of them when none are picked.
58
58
  const locales = settings && selectedLocales?.length ? selectedLocales : undefined;
59
- const changes = diffLayouts(comparisonValue, versionValue, { blocks: builder?.blocks ?? [], ...(locales ? { locales } : {}) });
59
+ const changes = diffLayouts(valueFrom, valueTo, { blocks: builder?.blocks ?? [], ...(locales ? { locales } : {}) });
60
60
  const label = fieldLabel(clientField?.label ?? field.label, i18n?.language ?? 'en', field.name);
61
- return (_jsxs("div", { className: `${base} nested-level-${nestingLevel ?? 0}`, children: [_jsxs(FieldDiffLabel, { children: [locale ? _jsx("span", { className: "field-diff__locale-label", children: locale }) : null, label] }), _jsxs("div", { className: `${base}__content`, children: [_jsx("p", { className: `${base}__summary`, children: summarizeLayoutChanges(changes) }), changes.length > 0 ? (_jsx("ul", { className: `${base}__list`, children: changes.map((change) => (_jsx(ChangeRow, { change: change, settings: settings }, `${change.kind}:${change.id}`))) })) : null, _jsx(LayoutJsonDiff, { from: comparisonValue, to: versionValue })] })] }));
61
+ return (_jsxs("div", { className: `${base} nested-level-${nestingLevel ?? 0}`, children: [_jsxs(FieldDiffLabel, { children: [locale ? _jsx("span", { className: "field-diff__locale-label", children: locale }) : null, label] }), _jsxs("div", { className: `${base}__content`, children: [_jsx("p", { className: `${base}__summary`, children: summarizeLayoutChanges(changes) }), changes.length > 0 ? (_jsx("ul", { className: `${base}__list`, children: changes.map((change) => (_jsx(ChangeRow, { change: change, settings: settings }, `${change.kind}:${change.id}`))) })) : null, _jsx(LayoutJsonDiff, { from: valueFrom, to: valueTo })] })] }));
62
62
  }