payload-canvas 0.5.2 → 0.6.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 (203) hide show
  1. package/README.md +342 -30
  2. package/dist/admin/ArrayRowLabel.d.ts +12 -0
  3. package/dist/admin/ArrayRowLabel.js +21 -0
  4. package/dist/admin/client.d.ts +1 -0
  5. package/dist/admin/client.js +2 -0
  6. package/dist/admin/editor/Editor.js +8 -1
  7. package/dist/admin/editor/Inspector.js +23 -17
  8. package/dist/admin/editor/Library.d.ts +2 -2
  9. package/dist/admin/editor/Library.js +7 -5
  10. package/dist/admin/editor/Outline.js +20 -12
  11. package/dist/admin/editor/Overlay.js +6 -4
  12. package/dist/admin/editor/actions.d.ts +7 -2
  13. package/dist/admin/editor/actions.js +44 -12
  14. package/dist/admin/editor/assistant/AssistantPanel.js +32 -20
  15. package/dist/admin/editor/comments/controller.d.ts +7 -0
  16. package/dist/admin/editor/comments/controller.js +12 -0
  17. package/dist/admin/editor/comments/useCommentFromURL.d.ts +2 -0
  18. package/dist/admin/editor/comments/useCommentFromURL.js +36 -0
  19. package/dist/admin/editor/dnd/smooth.js +1 -1
  20. package/dist/admin/editor/editor.scss +28 -0
  21. package/dist/admin/editor/fields/ArrayField.js +3 -3
  22. package/dist/admin/editor/fields/FormBlock.d.ts +20 -0
  23. package/dist/admin/editor/fields/FormBlock.js +167 -0
  24. package/dist/admin/editor/fields/FormFieldName.d.ts +25 -0
  25. package/dist/admin/editor/fields/FormFieldName.js +58 -0
  26. package/dist/admin/editor/fields/GroupField.d.ts +22 -2
  27. package/dist/admin/editor/fields/GroupField.js +30 -1
  28. package/dist/admin/editor/fields/MergeTags.d.ts +8 -0
  29. package/dist/admin/editor/fields/MergeTags.js +62 -0
  30. package/dist/admin/editor/fields/arrayRows.d.ts +0 -2
  31. package/dist/admin/editor/fields/arrayRows.js +0 -4
  32. package/dist/admin/editor/fields/fields.scss +150 -0
  33. package/dist/admin/editor/fields/values.d.ts +0 -2
  34. package/dist/admin/editor/fields/values.js +0 -14
  35. package/dist/admin/editor/icons.d.ts +3 -0
  36. package/dist/admin/editor/icons.js +3 -0
  37. package/dist/admin/editor/insert/InsertHandle.js +1 -1
  38. package/dist/admin/editor/insert/picker.d.ts +3 -2
  39. package/dist/admin/editor/insert/picker.js +9 -3
  40. package/dist/admin/editor/layout/LeftPanel.js +5 -3
  41. package/dist/admin/editor/layout/leftTabs.d.ts +15 -0
  42. package/dist/admin/editor/layout/leftTabs.js +18 -0
  43. package/dist/admin/editor/media/ImageEditor.d.ts +8 -2
  44. package/dist/admin/editor/media/ImageEditor.js +16 -10
  45. package/dist/admin/editor/media/media.scss +12 -2
  46. package/dist/admin/editor/media/model.d.ts +10 -1
  47. package/dist/admin/editor/media/model.js +19 -0
  48. package/dist/admin/editor/menu/blockMenu.js +3 -3
  49. package/dist/admin/editor/names.d.ts +9 -0
  50. package/dist/admin/editor/names.js +18 -0
  51. package/dist/admin/editor/regions/RegionFields.d.ts +6 -0
  52. package/dist/admin/editor/regions/RegionFields.js +122 -0
  53. package/dist/admin/editor/regions/RegionPane.js +5 -3
  54. package/dist/admin/editor/regions/RegionRows.js +2 -2
  55. package/dist/admin/editor/regions/required.d.ts +16 -0
  56. package/dist/admin/editor/regions/required.js +43 -0
  57. package/dist/admin/editor/renderField.d.ts +9 -2
  58. package/dist/admin/editor/renderField.js +86 -32
  59. package/dist/admin/editor/runtime.d.ts +3 -2
  60. package/dist/admin/editor/runtime.js +12 -18
  61. package/dist/admin/editor/styles/StylesPanel.js +4 -2
  62. package/dist/admin/editor/styles/context.js +9 -4
  63. package/dist/admin/editor/topbar/ContentModeToggle.js +1 -1
  64. package/dist/admin/editor/topbar/DocumentActions.js +4 -3
  65. package/dist/admin/editor/topbar/contentMode.scss +0 -9
  66. package/dist/admin/editor/topbar/topbar.scss +1 -41
  67. package/dist/admin/editor/ui/Tabs.d.ts +17 -0
  68. package/dist/admin/editor/ui/Tabs.js +17 -0
  69. package/dist/admin/forms/SubmissionCells.d.ts +6 -0
  70. package/dist/admin/forms/SubmissionCells.js +31 -0
  71. package/dist/admin/forms/SubmissionView.d.ts +5 -0
  72. package/dist/admin/forms/SubmissionView.js +106 -0
  73. package/dist/admin/forms/submissionData.d.ts +32 -0
  74. package/dist/admin/forms/submissionData.js +63 -0
  75. package/dist/admin/forms/submissions.scss +197 -0
  76. package/dist/admin/rsc.d.ts +2 -0
  77. package/dist/admin/rsc.js +5 -0
  78. package/dist/ai/endpoint.d.ts +5 -0
  79. package/dist/ai/endpoint.js +18 -8
  80. package/dist/ai/prompt.d.ts +8 -0
  81. package/dist/ai/prompt.js +30 -0
  82. package/dist/ai/tools.d.ts +6 -1
  83. package/dist/ai/tools.js +90 -6
  84. package/dist/blocks/builtins/carousel.js +10 -1
  85. package/dist/blocks/defaults.js +27 -2
  86. package/dist/blocks/index.d.ts +1 -1
  87. package/dist/blocks/index.js +1 -1
  88. package/dist/blocks/payload.d.ts +7 -0
  89. package/dist/blocks/payload.js +16 -2
  90. package/dist/comments/shared.d.ts +5 -0
  91. package/dist/comments/shared.js +5 -0
  92. package/dist/core/blocks.d.ts +17 -3
  93. package/dist/core/blocks.js +92 -10
  94. package/dist/core/classes.d.ts +5 -0
  95. package/dist/core/classes.js +26 -1
  96. package/dist/core/conditions.d.ts +7 -0
  97. package/dist/core/conditions.js +22 -0
  98. package/dist/core/dropTarget.d.ts +3 -2
  99. package/dist/core/dropTarget.js +7 -1
  100. package/dist/core/index.d.ts +6 -3
  101. package/dist/core/index.js +6 -3
  102. package/dist/core/payloadBlocks.js +25 -3
  103. package/dist/core/references.d.ts +7 -0
  104. package/dist/core/references.js +29 -11
  105. package/dist/core/regions.d.ts +14 -0
  106. package/dist/core/regions.js +17 -1
  107. package/dist/core/rowLabel.d.ts +8 -0
  108. package/dist/core/rowLabel.js +98 -0
  109. package/dist/core/starter.d.ts +10 -0
  110. package/dist/core/starter.js +40 -0
  111. package/dist/core/tree.js +4 -0
  112. package/dist/core/types.d.ts +96 -0
  113. package/dist/core/uniqueProps.d.ts +40 -0
  114. package/dist/core/uniqueProps.js +156 -0
  115. package/dist/core/validate.js +43 -3
  116. package/dist/forms/answers.d.ts +21 -0
  117. package/dist/forms/answers.js +82 -0
  118. package/dist/forms/blocks.d.ts +33 -0
  119. package/dist/forms/blocks.js +178 -0
  120. package/dist/forms/conditions.d.ts +78 -0
  121. package/dist/forms/conditions.js +184 -0
  122. package/dist/forms/emails.d.ts +23 -0
  123. package/dist/forms/emails.js +64 -0
  124. package/dist/forms/fieldConfigs.d.ts +35 -0
  125. package/dist/forms/fieldConfigs.js +167 -0
  126. package/dist/forms/fieldOps.d.ts +78 -0
  127. package/dist/forms/fieldOps.js +378 -0
  128. package/dist/forms/fieldSettings.d.ts +81 -0
  129. package/dist/forms/fieldSettings.js +239 -0
  130. package/dist/forms/files.d.ts +54 -0
  131. package/dist/forms/files.js +128 -0
  132. package/dist/forms/index.d.ts +16 -0
  133. package/dist/forms/index.js +18 -0
  134. package/dist/forms/mergeTags.d.ts +103 -0
  135. package/dist/forms/mergeTags.js +150 -0
  136. package/dist/forms/noScript.d.ts +60 -0
  137. package/dist/forms/noScript.js +109 -0
  138. package/dist/forms/pageForms.d.ts +99 -0
  139. package/dist/forms/pageForms.js +294 -0
  140. package/dist/forms/pageSync.d.ts +91 -0
  141. package/dist/forms/pageSync.js +325 -0
  142. package/dist/forms/rateLimit.d.ts +21 -0
  143. package/dist/forms/rateLimit.js +50 -0
  144. package/dist/forms/settings.d.ts +13 -0
  145. package/dist/forms/settings.js +92 -0
  146. package/dist/forms/spam.d.ts +100 -0
  147. package/dist/forms/spam.js +218 -0
  148. package/dist/forms/spamSettings.d.ts +43 -0
  149. package/dist/forms/spamSettings.js +25 -0
  150. package/dist/forms/submission.d.ts +34 -0
  151. package/dist/forms/submission.js +89 -0
  152. package/dist/forms/submissionsAdmin.d.ts +26 -0
  153. package/dist/forms/submissionsAdmin.js +108 -0
  154. package/dist/forms/summary.d.ts +60 -0
  155. package/dist/forms/summary.js +113 -0
  156. package/dist/forms/uploads.d.ts +41 -0
  157. package/dist/forms/uploads.js +132 -0
  158. package/dist/index.d.ts +8 -2
  159. package/dist/index.js +8 -2
  160. package/dist/live/document.d.ts +12 -0
  161. package/dist/live/document.js +8 -1
  162. package/dist/live/endpoints.d.ts +1 -0
  163. package/dist/live/session.js +3 -1
  164. package/dist/live/storage.d.ts +13 -2
  165. package/dist/live/storage.js +18 -7
  166. package/dist/mcp/forms.d.ts +26 -0
  167. package/dist/mcp/forms.js +280 -0
  168. package/dist/mcp/index.d.ts +7 -0
  169. package/dist/mcp/index.js +29 -10
  170. package/dist/mcp/shared.d.ts +1 -0
  171. package/dist/mcp/shared.js +1 -0
  172. package/dist/plugin/forms.d.ts +30 -0
  173. package/dist/plugin/forms.js +63 -0
  174. package/dist/plugin/formsSync.d.ts +138 -0
  175. package/dist/plugin/formsSync.js +345 -0
  176. package/dist/plugin/hook.d.ts +22 -0
  177. package/dist/plugin/hook.js +19 -7
  178. package/dist/plugin/index.d.ts +14 -0
  179. package/dist/plugin/index.js +99 -28
  180. package/dist/plugin/links.d.ts +7 -2
  181. package/dist/plugin/links.js +9 -3
  182. package/dist/plugin/references.d.ts +6 -0
  183. package/dist/plugin/references.js +12 -0
  184. package/dist/react/canvas/BuilderCanvas.d.ts +2 -0
  185. package/dist/react/canvas/BuilderCanvas.js +29 -6
  186. package/dist/react/canvas/inline/mapper.d.ts +6 -1
  187. package/dist/react/canvas/inline/mapper.js +35 -4
  188. package/dist/react/components/AutoplayVideo.d.ts +20 -0
  189. package/dist/react/components/AutoplayVideo.js +34 -0
  190. package/dist/react/components/Video.d.ts +9 -1
  191. package/dist/react/components/Video.js +39 -11
  192. package/dist/react/components/lazy.d.ts +2 -0
  193. package/dist/react/components/lazy.js +2 -0
  194. package/dist/react/components/videoPlayback.d.ts +30 -0
  195. package/dist/react/components/videoPlayback.js +33 -0
  196. package/dist/react/render/LayoutOutlet.d.ts +7 -3
  197. package/dist/react/render/LayoutOutlet.js +9 -4
  198. package/dist/react/render/RenderLayout.js +18 -9
  199. package/dist/react/render/resolve.d.ts +1 -0
  200. package/dist/react/render/resolve.js +5 -1
  201. package/dist/react/render/types.d.ts +1 -1
  202. package/dist/react/server.js +19 -0
  203. package/package.json +5 -1
package/README.md CHANGED
@@ -33,7 +33,7 @@ One package holds everything: the Payload plugin and admin editor (`payload-canv
33
33
  npx create-payload-canvas my-website
34
34
  ```
35
35
 
36
- The starter also has a calmer Payload admin: a sidebar in groups with icons, a neutral look in light and dark mode, and a dashboard with quick actions, recent edits, drafts, form messages, site checks, scheduled publishes and optional Plausible or Umami numbers. Each part is plain code in `src/admin/` of the starter. The CLI asks which parts to keep (see [Features](../create-payload-canvas/README.md#features)).
36
+ The starter also has a calmer Payload admin: a sidebar in groups with icons, a neutral look in light and dark mode, list cells that show values by field type (a check mark, option chips, short dates, "3 links", a rich text excerpt) instead of raw code, array rows named by their content, and a dashboard with quick actions, recent edits, open comments, form messages, site checks, broken links (a 404 log and links to missing pages), unused media, scheduled publishes and optional Plausible or Umami numbers. Each part is plain code in `src/admin/` of the starter. The CLI asks which parts to keep (see [Features](../create-payload-canvas/README.md#features)).
37
37
 
38
38
  ## Contents
39
39
 
@@ -53,22 +53,24 @@ The starter also has a calmer Payload admin: a sidebar in groups with icons, a n
53
53
  - [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields)
54
54
  - [Built-in blocks](#built-in-blocks)
55
55
  9. [Using existing Payload blocks](#using-existing-payload-blocks)
56
- 10. [Sections](#sections)
57
- 11. [Styling](#styling)
56
+ 10. [Form builder](#form-builder)
57
+ 11. [Sections](#sections)
58
+ 12. [Styling](#styling)
58
59
  - [Editable classes](#editable-classes)
59
- 12. [Animations](#animations)
60
- 13. [Theme](#theme)
61
- 14. [Templates and binding](#templates-and-binding)
62
- 15. [References and Used in](#references-and-used-in)
63
- 16. [Localization](#localization)
64
- 17. [AI assistant](#ai-assistant)
65
- 18. [AI editing over MCP](#ai-editing-over-mcp)
66
- 19. [Multiplayer editing](#multiplayer-editing)
60
+ 13. [Animations](#animations)
61
+ 14. [Theme](#theme)
62
+ 15. [Templates and binding](#templates-and-binding)
63
+ 16. [References and Used in](#references-and-used-in)
64
+ - [Array row labels](#array-row-labels)
65
+ 17. [Localization](#localization)
66
+ 18. [AI assistant](#ai-assistant)
67
+ 19. [AI editing over MCP](#ai-editing-over-mcp)
68
+ 20. [Multiplayer editing](#multiplayer-editing)
67
69
  - [Comments on the canvas](#comments-on-the-canvas)
68
- 20. [Production and Docker](#production-and-docker)
69
- 21. [Deploying](#deploying)
70
- 22. [Troubleshooting](#troubleshooting)
71
- 23. [Limits](#limits)
70
+ 21. [Production and Docker](#production-and-docker)
71
+ 22. [Deploying](#deploying)
72
+ 23. [Troubleshooting](#troubleshooting)
73
+ 24. [Limits](#limits)
72
74
 
73
75
  ## Requirements
74
76
 
@@ -449,7 +451,7 @@ The top bar, left to right:
449
451
  - **Page settings** opens the document's own edit form in a Payload drawer: title, slug, SEO, and for a template its collection and sample document. The top bar updates after each save.
450
452
  - The AI assistant (with the `ai` option), the keyboard shortcuts, and **Publish changes**. Its menu has **Unpublish**, **Revert to published** (drops all draft changes, after a confirmation), **Versions** and **API** (Payload's own screens, in a drawer over the builder), **All fields** (Payload's edit form) and a link to the live page. In the Versions drawer, open a version to compare it, then **Restore as draft**: every open editor gets the restored layout, and the site keeps the published version until you publish.
451
453
 
452
- The left sidebar has three tabs: **Layers** (the block tree), **Blocks** and **Sections**. Each fills the sidebar. Alt+1, Alt+2 and Alt+3 (⌥1, ⌥2, ⌥3 on a Mac) open them, and the browser keeps the last tab. To drop a block or section into the tree, drag it onto the **Layers** tab and hold it there for a moment: the tab opens.
454
+ The left sidebar has three tabs: **Layers** (the block tree), **Blocks** and **Sections** (only when there are sections to insert or a place to save them). Each fills the sidebar. Alt+1, Alt+2 and Alt+3 (⌥1, ⌥2, ⌥3 on a Mac) open them, and the browser keeps the last tab. As in Webflow, adding a block or section from **Blocks** or **Sections** opens **Layers**: a click shows the new block there, selected; a drag opens Layers when it starts, so you can drop on the canvas or anywhere in the tree (an empty tree too).
453
455
 
454
456
  The sidebars resize: drag the edge, or focus it with Tab and use the arrow keys (Shift for larger steps). A double-click or Enter resets the default size. The sizes are kept in the browser.
455
457
 
@@ -497,7 +499,7 @@ In content mode, editors can:
497
499
 
498
500
  They cannot add, move, duplicate or delete other blocks, and they see no Blocks or Sections tab, no **+** buttons, no drag and drop, no Styles, Motion or Advanced tab, no classes, section variants, visibility conditions, bindings or page regions. Design props (selects, checkboxes, numbers, relationships, heading levels) are hidden too. The top bar shows **Content mode**.
499
501
 
500
- Users with design rights get **Preview as client** in the top bar. It shows the editor as clients see it. Turn it off to edit the design again.
502
+ Users with design rights get **Preview as client** (the eye icon) in the top bar. It shows the editor as clients see it. Turn it off to edit the design again.
501
503
 
502
504
  Which props are content. The field type decides: `text`, `textarea`, `richText`, `upload`, `email` and link groups (`linkField()`) are content. A group, row or array is content when every field inside it is. Everything else is design. Override it per field with `admin.custom.builderContent`:
503
505
 
@@ -554,7 +556,7 @@ Put the mark on the element that holds the text and nothing else.
554
556
 
555
557
  Every image that shows an upload prop can be replaced on the canvas:
556
558
 
557
- - Hover the image: a **Replace** chip shows in its top left corner. Text over an image (a hero heading) wins: hover a free part of the image.
559
+ - Hover the image: a **Replace** chip shows inside its top right corner (above a small image, and lower down when the selected block's action bar sits in that corner). It uses the part of the image that shows, so an image cut off by a carousel or a card gets the chip on its visible part. Text over an image (a hero heading) wins: hover a free part of the image.
558
560
  - Double-click the image, or click the chip, to open the media popover:
559
561
  - **Choose from library**: Payload's list drawer for the field's upload collection.
560
562
  - **Upload a file**: a file picker. The file goes to the upload collection with its name as alt text.
@@ -600,6 +602,7 @@ websiteBuilder({
600
602
  theme: { admin: { group: 'Settings' } }, // the Theme global; `false` leaves it out
601
603
  editor: { dragMode: 'smooth', openInBuilder: true }, // drag and drop style; open saved documents in the builder
602
604
  references: { usedIn: ['media'], protectDelete: ['media'] }, // "Used in" lists; `false` turns them off
605
+ forms: true, // the form builder for @payloadcms/plugin-form-builder
603
606
  })
604
607
  ```
605
608
 
@@ -610,7 +613,8 @@ websiteBuilder({
610
613
  | `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. |
611
614
  | `collections[slug].templates` | `boolean` | Documents render through templates. See [Templates](#templates-and-binding). |
612
615
  | `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. |
613
- | `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). |
616
+ | `collections[slug].regions` | `{ name, label?, fields, panel?, sections? }[]` | 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. `panel: true`: the right panel edits the region's fields itself, and shows them when no block is selected (the form builder's settings use it). `sections: [{ label, fields }]` puts a panel region's fields under headings that open and close (the first starts open); a `group` field in no section gets a section of its own. See [Whole-page editing](#whole-page-editing-regions-outside-the-layout). |
617
+ | `collections[slug].sections` | `false` | The editor of this collection offers no sections: no Sections tab and no "Save as section…". The `forms` option sets it. |
614
618
  | `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). |
615
619
  | `blocks` | `BlockDefinition[]` | The blocks editors can use. Default `defaultBlocks()`. |
616
620
  | `listCollections` | `string[]` | More collections the collection list block can show, after the collections with a `url`. Use it for data collections without pages of their own, such as testimonials or team members. Their items have no `$url`. Each slug must be a collection of the config. Pass the same list to `builderMcpTools`. |
@@ -632,6 +636,7 @@ websiteBuilder({
632
636
  | `editor.openInBuilder` | `boolean` | Opening a saved document goes straight to the builder instead of Payload's form. Default `false`. Run `generate:importmap` after you turn it on. See [The builder view](#the-builder-view). |
633
637
  | `css.fontFamilies` | `(payload) => Record<name, family>` | Font families set at runtime some other way than the Theme global, for the Styles panel's Font list. Its names win over the theme's. |
634
638
  | `references` | `{ field?, usedIn?, protectDelete?, maxListed? } \| false` | Which media and documents each layout uses: "Used in" lists and delete protection. On by default. `false` turns it off. See [References and Used in](#references-and-used-in). |
639
+ | `forms` | `{ collection? } \| boolean` | The form builder for the forms of `@payloadcms/plugin-form-builder` (add that plugin first). Default slug `forms`. See [Form builder](#form-builder). |
635
640
  | `comments` | `{ slug?, access?, admin?, hooks? } \| boolean` | Comments on blocks in the builder, stored in a `builder-comments` collection. On by default. `false` turns it off. See [Comments on the canvas](#comments-on-the-canvas). |
636
641
 
637
642
  For each listed collection the plugin adds:
@@ -667,9 +672,10 @@ It also adds these endpoints (signed-in users only):
667
672
 
668
673
  | Import | Use it in | Holds |
669
674
  |---|---|---|
670
- | `payload-canvas` | `payload.config.ts` (server) | `websiteBuilder`, `defineBlock`, `defaultBlocks`, `fromPayloadBlocks`, `migrateBlocksField`, types |
675
+ | `payload-canvas` | `payload.config.ts` (server) | `websiteBuilder`, `defineBlock`, `defaultBlocks`, `fromPayloadBlocks`, `migrateBlocksField`, `formSubmissionConditions`, types |
676
+ | `payload-canvas/forms` | anywhere | form display conditions (`withFormConditions`, `hiddenFormFields`, `describeConditions`), field settings (`withFormFieldSettings`, `withStoredWidth`), answer checks (`formAnswerProblem`, `fileProblem`, `filesProblem`), the extra field types (`moreFormFields`), the email fields (`withFormEmailFields`) and merge tags (`mergeTags`, `formEmailMessage`), `formFieldType`, `formFieldSlug`, `FORM_SETTINGS_REGION`, forms on pages (`formBlocks`, `formBlockMode`, `formBlockFields`, `formDataFromBlock`, `formBlockFromDoc`, `withSavedFormFields`). See [Form builder](#form-builder). |
671
677
  | `payload-canvas/blocks` | anywhere | `defaultBlocks`, `defineBlock`, `linkField`, `fromPayloadBlocks`, `prepareBlocks`, `listCollectionsOf`, `BUILDER_CSS_CLASS`, `withBuilderCssClass` |
672
- | `payload-canvas/core` | anywhere | layout types, `normalizeLayout`, `validateLayout`, `applyOperations`, tree helpers, `convertPayloadBlocksLayout`, `toPayloadBlock` |
678
+ | `payload-canvas/core` | anywhere | layout types, `normalizeLayout`, `validateLayout`, `applyOperations`, tree helpers, `convertPayloadBlocksLayout`, `toPayloadBlock`, `fieldReferences`, `rowLabel` |
673
679
  | `payload-canvas/css` | server | `compileClasses`, `getStyleTokens`, `tracingIncludes` |
674
680
  | `payload-canvas/theme` | anywhere | `themeCss`, `themeVariables`, `themeOutput`, `deriveColors`, `googleFontsHref`, `themeConfigOf`, theme types |
675
681
  | `payload-canvas/theme-client` | Payload import map, or your own fields | `ThemeColorField`, `ThemeFontField`, `ThemeSliderField` |
@@ -678,7 +684,7 @@ It also adds these endpoints (signed-in users only):
678
684
  | `payload-canvas/ai/openrouter`, `/ai/cloudflare-gateway`, `/ai/cloudflare-workers-ai`, `/ai/openai-compatible`, `/ai/anthropic`, `/ai/fake` | `payload.config.ts` (server) | one AI adapter each. See [Adapters](#adapters). |
679
685
  | `payload-canvas/ai/images/openrouter`, `/ai/images/openai`, `/ai/images/cloudflare-workers-ai`, `/ai/images/fake` | `payload.config.ts` (server) | one image adapter each. See [Image generation](#image-generation). |
680
686
  | `payload-canvas/live` | server | the live sessions and endpoints |
681
- | `payload-canvas/client` | Payload import map only | admin client components (layout field, Builder tab, `DocumentEditView` for `openInBuilder`) |
687
+ | `payload-canvas/client` | Payload import map only | admin client components (layout field, Builder tab, `DocumentEditView` for `openInBuilder`, `ArrayRowLabel`) |
682
688
  | `payload-canvas/rsc` | Payload import map only | admin server components (the builder view, the tab redirect) |
683
689
  | `payload-canvas/react` | your site and the canvas (server and client) | `RenderLayout`, `defaultComponents`, `fromPayloadComponent(s)`, `withPageData`, `withLinkComponent`, `lazyBlock`, `renderOnServer`, `editableText`, `editableImage`, `useCanvasMode`, `useCanvasReveal`, `REVEAL_EVENT`, `CANVAS_CONTROL_ATTRIBUTE`, `builtinComponents`, link helpers, `ThemeLive`, types |
684
690
  | `payload-canvas/react/server` | server only | `loadLayoutData`, `loadTemplate`, `loadTheme`, `ThemeStyle`, `createCanvasServer` (they call Payload's Local API) |
@@ -701,7 +707,7 @@ Every entry point is ESM with `.d.ts` types. Client components keep their `'use
701
707
  | `context` | `{ collection, doc }` | The document a template renders. See [Templates](#templates-and-binding). |
702
708
  | `pageData` | `Record<string, unknown>` | Data the page loads once for its blocks. See [Page data](#page-data-and--block-context--components). |
703
709
  | `linkComponent` | client component | Renders the links of the button, link and menu blocks on the site. Default: a plain `<a>`. Pass `next/link` for client-side navigation and prefetching. It must be a client component (the menu is one and gets it as a prop). Your own components get it as `linkComponent` when you mark them with `withLinkComponent(Component)`. The canvas keeps plain links. |
704
- | `priorityImages` | `number` | How many images of the first section load first (`fetchpriority="high"`, not lazy), in page order. Default `1`, usually the hero image. An image whose **Load first** is switched off keeps lazy loading. Give layouts further down the page (a footer) `0`. |
710
+ | `priorityImages` | `number` | How many images of the first section load first (`fetchpriority="high"`, not lazy), in page order. Default `1`, usually the hero image. An image whose **Load first** is switched off keeps lazy loading. Videos do not count: their **Load first** is only what the editor sets. Give layouts further down the page (a footer) `0`. |
705
711
 
706
712
  ```tsx
707
713
  import Link from 'next/link'
@@ -986,7 +992,7 @@ export async function builderCanvas(request: CanvasServerRequest) {
986
992
  }
987
993
  ```
988
994
 
989
- `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.
995
+ `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. The layout sits in one `div`. To style that box (a flex row of blocks), render `<LayoutOutlet className="…" />` from `payload-canvas/react` instead of `layout`. Return `layout` alone (or `null`) to show the layout without a frame.
990
996
 
991
997
  **What editors can do with a region:**
992
998
 
@@ -1045,9 +1051,10 @@ export const blocks = [...defaultBlocks({ linkCollections: ['pages'] }), pricing
1045
1051
  ```
1046
1052
 
1047
1053
  - `description` is one short plain sentence for editors. The block library shows it as the tooltip. Without it, the tooltip shows only the label. The library search also reads `ai.description`. Keep code and syntax out of it: those go in `ai.description`.
1048
- - `slots` declares where child blocks go. `allow` lists the accepted block types, or `['*']`. `max` caps the number of direct children: a full slot refuses insert, move, paste and duplicate (also from MCP and the assistant), and the canvas offers no drop target or "+" there. `min` is the fewest children: fewer block **Publish** but not draft saves.
1054
+ - `slots` declares where child blocks go. `allow` lists the accepted block types, or `['*']`. `max` caps the number of direct children: a full slot refuses insert, move, paste and duplicate (also from MCP and the assistant), and the canvas offers no drop target or "+" there. `min` is the fewest children: fewer block **Publish** but not draft saves. Three optional keys explain a slot to editors: `description` (one short sentence, shown inside the slot while it is empty, and given to MCP), `itemLabel` (Layers names each direct child without a name of its own "<itemLabel> 1", "<itemLabel> 2", …) and `newBlock` (`{ type, label?, className?, props? }`: the block the canvas "+" picker offers first in this slot). The carousel's `slides` slot sets all three: "Each block here is one slide", `Slide`, and a Stack named "Slide".
1049
1055
  - `inline: true` says the block renders no link, button or other control of its own (an icon, a badge, a rating). Such a block may go directly inside a `link` block, whose content slot sets `allowInline: true`. A slot of your own can set `allowInline: true` too. `websiteBuilder` and `builderMcpTools` add the inline types to those slots' `allow` lists (`withInlineBlocks`); a slot's `disallow` still wins. Blocks without `inline` stay out of links. `validateLayout` applies the same rule itself, so a seed or a test can check a layout against your own block list. To check a collection list's picked `ids` as a relationship, give that list `defaultBlocks({ listCollections })`, as the plugin does with the collections that have a `url`. A list you do not build with `defaultBlocks` (for example from `fromPayloadBlocks`) can get the same preparation as `websiteBuilder` with `prepareBlocks(blocks, listCollections)` from `payload-canvas/blocks`. `listCollectionsOf(blocks, listCollections)` does only the collection list part.
1050
1056
  - `parents` limits where a block may go: only directly inside the listed block types (never in the root list). The `listItem` block uses `parents: ['list']`. A new block whose slot accepts exactly one such type starts with children of it: the slot's `min`, or one. So a new list starts with one item, and new tabs start with two tabs.
1057
+ - `upgrade(block)` turns a block stored in an older shape into the current one. The builder runs it when it opens a stored layout (the editor, the MCP tools), so the next save stores the new shape. Until then the component must still read the old shape. Return the same block when nothing changes. The form field blocks use it to turn the plugin's old `width` into classes ([Field width](#field-width)).
1051
1058
  - `classes`: classes your component uses itself that your site's CSS does not have. Components in your app need no list: Tailwind finds their classes in your files, and the site's CSS has them on the site and on the canvas. List classes only for a component in a package that your CSS entry does not scan (no `@source` for it). The generated CSS styles only elements with the class `builder-css` (`BUILDER_CSS_CLASS` from `payload-canvas/blocks`), so add that class to each element that uses the listed classes. The built-in Menu block does this for its toggle, panel and links.
1052
1059
  - Block fields keep Payload's `validate`, `hooks` and `access`. See [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields).
1053
1060
  - `parts` names inner elements that take classes of their own, for example a carousel's arrows. See [Classes on inner elements](#classes-on-inner-elements).
@@ -1057,6 +1064,13 @@ export const blocks = [...defaultBlocks({ linkCollections: ['pages'] }), pricing
1057
1064
  - Field help in the inspector stays short. Put syntax and examples for agents in the field's `custom.ai.description`, and a hint inside an empty input in `admin.placeholder` (the inspector shows it).
1058
1065
  - Props worth knowing on the default blocks:
1059
1066
  - `image`: `priority` (load first: `loading="eager"` and `fetchpriority="high"`, for the hero image; the first image of the first section gets it unless switched off, see `priorityImages`) and `sizes` (the HTML `sizes` attribute, for example `(min-width: 768px) 50vw, 100vw`). The media's focal point (`focalX`, `focalY`) sets `object-position`, so a cropped image keeps its subject. Payload's default 50/50 counts as unset, so an `object-position` class (`object-top`) sets the crop of a photo whose focal point nobody moved. Limit: a focal point set to exactly 50/50 loses to such a class.
1067
+ - `video`: an upload or a link (YouTube, Vimeo or a video file), with `poster`, `autoplay`, `loop`, `muted` and `controls` (default on). New in 0.6.1, all off by default:
1068
+ - `decorative` (**Decorative**): for a background video. It sets `aria-hidden="true"` and `tabindex="-1"` and turns the controls off, also for YouTube and Vimeo.
1069
+ - `priority` (**Load first**): for the main video at the top. The video gets `preload="auto"` (else `preload="metadata"`), and the poster preloads with `fetchpriority="high"` (React `preload()`, a `<link rel="preload" as="image">`). An embed loads eagerly. Unlike an image, a video never gets it from `priorityImages`, because that would load the whole file: switch it on yourself.
1070
+ - Autoplay respects reduced motion. A `<video>` never gets the `autoplay` attribute. On the site a small client component starts it after mount, and only when the visitor does not ask for less motion (`prefers-reduced-motion: reduce`). Otherwise the video shows its poster and stays paused. A change of that setting plays or pauses it. Its JavaScript loads only on pages with an autoplaying video. Without JavaScript the video stays on its poster. A YouTube or Vimeo embed cannot check the setting: the player decides.
1071
+ - On the canvas and in section thumbnails an autoplaying video stays paused on its poster, and an embed does not autoplay, so editing stays calm.
1072
+ - The poster's focal point (`focalX`, `focalY`) sets `object-position` on the video, with the image block's rule: Payload's default 50/50 leaves the crop to the classes (`object-top`).
1073
+ - A hero background video: in a stack with `relative isolate`, a `video` first with `autoplay`, `muted`, `loop`, `decorative`, `priority` and a `poster`, and the classes `absolute inset-0 -z-10 size-full object-cover`.
1060
1074
  - `heading`: `accent`, words of the text to highlight. They render as `<em>`. Style them with classes on the heading, for example `[&_em]:text-primary [&_em]:not-italic`.
1061
1075
  - `stack`: `as` (the inspector's **Tag**) also takes `ol`, `ul`, `li`, `dl`, `dt`, `dd`, `figure` and `figcaption`, for lists, term lists and captions. It takes no `p` or `span`: those cannot hold block children such as a heading.
1062
1076
  - The `menu` block folds its links into a "Menu" button and a panel on small screens. Set `ctaLabel` and `cta` (a link) to add a button as the last row of that panel, for example the header's call to action, which a header hides on phones. The inline links, and so the wide-screen header, do not change. `toggleLabel` is the text of the menu button (default "Menu"). The menu's labels (`label`, `toggleLabel`, `submenuLabel`) store nothing until someone types one: empty, they use the site's labels (`builtinComponents({ labels: { menu } })`, see [Labels](#labels)) or English. The panel and dropdown colours read the theme's CSS variables (`--color-background`, `--color-foreground`, `--color-border`, `--color-primary`) with the system colours as the fallback, so the menu needs no particular design system.
@@ -1217,7 +1231,7 @@ export const components: BlockComponents = { ...builtinComponents({ icons, label
1217
1231
  - Every built-in takes its look from `className`. The definitions have plain `defaultClassName`s without colours. Inner elements that have their own entry in the **Style target** select are parts (see [Classes on inner elements](#classes-on-inner-elements)). The other inner elements have `data-*` attributes, so you style them from the block's `className` with variants such as `[&_[data-page-gap]]:opacity-50`.
1218
1232
  - **Replace a built-in** with your own block of the same type: leave it out of `include` and add your block. Block types must be unique, so the plugin refuses both at once. In the components map, a key of yours with the same type wins over `builtinComponents()`.
1219
1233
  - `builtinComponents()` returns every built-in component. The interactive ones (carousel, popup, tabs, accordion, filter link) load their JavaScript only on pages that render them, so blocks you do not use cost nothing on the page. The marquee and previous / next are server components with no JavaScript.
1220
- - For a photo that opens large, use a popup with a small image in its trigger and the large image in its content. For a background, put an `image` or `video` block first in a stack with `relative isolate`, and give the media `absolute inset-0 -z-10 size-full object-cover`.
1234
+ - For a photo that opens large, use a popup with a small image in its trigger and the large image in its content. For a background, put an `image` or `video` block first in a stack with `relative isolate`, and give the media `absolute inset-0 -z-10 size-full object-cover`. Mark a background video **Decorative**, and switch on **Load first** when it is the first thing on the page.
1221
1235
 
1222
1236
  #### Labels
1223
1237
 
@@ -1321,7 +1335,7 @@ builtinBlocks({ embed: { canEdit: ({ req }) => req.user?.role === 'admin' } })
1321
1335
 
1322
1336
  #### Carousel
1323
1337
 
1324
- `carousel` shows the blocks of its `slides` slot as slides. It runs on [Embla Carousel](https://www.embla-carousel.com/). Each direct child is one slide. Set how many slides show at once with each slide's `className`: `basis-full md:basis-1/2` (or a width such as `w-[85%]`). A single `collectionList` or `repeat` child makes each of its items a slide: set the basis on the item. Any other single child is one slide.
1338
+ `carousel` shows the blocks of its `slides` slot as slides. It runs on [Embla Carousel](https://www.embla-carousel.com/). Each direct child is one slide: Layers names them "Slide 1", "Slide 2", … (unless a slide has its own name), the empty slot says "Each block here is one slide", and the "+" picker offers a **Slide** (a Stack named "Slide") first. Set how many slides show at once with each slide's `className`: `basis-full md:basis-1/2` (or a width such as `w-[85%]`). A single `collectionList` or `repeat` child makes each of its items a slide: set the basis on the item. Any other single child is one slide.
1325
1339
 
1326
1340
  - Visitors swipe or drag the slides, click the arrows or dots, or use the arrow keys when the carousel has the focus.
1327
1341
  - Props: `mode` (`scroll`: the slides slide sideways; `fade`: one slide fades into the next), `align` (**Slide position**: `start` or `center`, where the current slide sits when the slides are narrower than the carousel), `arrows` (default on), `dots`, `loop`, `autoplay` (milliseconds, 0 is off) and `label` (the region's name, default "Carousel").
@@ -1570,6 +1584,294 @@ The `builder` prop holds `mode`, `className`, `slots` (rendered children by slot
1570
1584
  - **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.
1571
1585
  - A Payload slug `list` with an `items` array is read as the old built-in list (`normalizeLayout`). Use `prefix` to avoid that.
1572
1586
 
1587
+ ## Form builder
1588
+
1589
+ Edit the forms of the official [`@payloadcms/plugin-form-builder`](https://payloadcms.com/docs/plugins/form-builder) in the same full-screen builder as pages:
1590
+
1591
+ - **Left:** the form's fields in Layers. Drag to reorder. The Blocks tab adds a field of any type the form-builder plugin offers. Duplicate and delete work as for blocks.
1592
+ - **Centre:** a live preview of the form alone, rendered by your app's own form component, so it matches the site. A click on a field selects it.
1593
+ - **Right:** the selected field's settings with Payload's own inputs, on up to three tabs: **Field** (name, label, description, placeholder, default value, options, label visibility, radio display), **Validation** (required, file types, size and number of files) and **Conditions** (display conditions). The settings hold only content and behaviour. Looks, the width too, are the field's classes in the **Styles** panel, as for any block: see [Field width](#field-width). With no field selected, the panel shows the form's settings in sections that fold: **General** (title, submit button label), **After submit** (confirmation type, message, redirect) and **Mail** (the emails). Any other top-level `group` field of the forms collection (for example spam protection settings) gets a section of its own.
1594
+ - **No sections:** form fields are not page sections, so the form builder has no Sections tab and no "Save as section…".
1595
+ - **Top bar:** title, save state, undo and redo, and **All fields** for Payload's own edit screen. Each change saves at once (forms have no drafts).
1596
+ - **Styles:** a field's looks (its box, label, input, help text, error, options) are edited in the Styles panel, as on pages. They are stored in the field's hidden `cssClass` and `partClasses`.
1597
+
1598
+ The form's `fields` stay a Payload `blocks` field: the builder edits it in place, as in [Using existing Payload blocks](#using-existing-payload-blocks). Nothing is copied and nothing needs a migration.
1599
+
1600
+ ### Turn it on
1601
+
1602
+ 1. Add `formBuilderPlugin()` before `websiteBuilder()`, and set `forms: true` (or `{ collection: 'my-forms' }` for another slug):
1603
+
1604
+ ```ts
1605
+ import { fields as formFields, formBuilderPlugin } from '@payloadcms/plugin-form-builder'
1606
+ import { formEmails, formFileUploads, formFileUploadsCleanup, formSubmissionConditions, websiteBuilder } from 'payload-canvas'
1607
+ import { withFormConditions, withFormEmailFields, withFormFieldSettings } from 'payload-canvas/forms'
1608
+
1609
+ plugins: [
1610
+ formBuilderPlugin({
1611
+ // The plugin's own field blocks, each with a `conditions` field and more settings (both optional, see below).
1612
+ fields: { text: withFormFieldSettings(withFormConditions(formFields.text)), email: withFormFieldSettings(withFormConditions(formFields.email)) /* … */ },
1613
+ // Each email: To, From name, From email, Reply-To, CC, BCC, Subject, rich text or HTML body (see "Emails").
1614
+ beforeEmail: formEmails(),
1615
+ formOverrides: { fields: ({ defaultFields }) => withFormEmailFields(defaultFields) },
1616
+ formSubmissionOverrides: {
1617
+ hooks: {
1618
+ // Hidden fields are never required, and their answers are dropped. Wrong formats are refused.
1619
+ beforeValidate: [formSubmissionConditions()],
1620
+ // Files of `file` fields go to a private upload collection and are linked on the submission (see "More field types").
1621
+ beforeChange: [formFileUploads({ collection: 'form-files', field: 'attachments' })],
1622
+ // A submission that fails after its files were stored removes them again.
1623
+ afterError: [formFileUploadsCleanup()],
1624
+ },
1625
+ },
1626
+ }),
1627
+ websiteBuilder({ collections, forms: true /* … */ }),
1628
+ ]
1629
+ ```
1630
+
1631
+ The plugin adds a **Builder** tab to each form. With `editor.openInBuilder`, a saved form opens in the builder.
1632
+
1633
+ 2. Show the form in the canvas. The canvas route renders each field with a component of yours. The server action renders the form around the fields as a page frame (see [Whole-page editing](#whole-page-editing-regions-outside-the-layout)). The field types are `formText`, `formEmail`, and so on (`formFieldType('text')`); `formFieldSlug(type)` gives the plugin's `blockType` back.
1634
+
1635
+ ```tsx
1636
+ // CanvasClient.tsx ('use client')
1637
+ import { formFieldType } from 'payload-canvas/forms'
1638
+ const formComponents = Object.fromEntries(['text', 'email', 'textarea', 'select', 'checkbox'].map((slug) => [formFieldType(slug), FormFieldBlock]))
1639
+ <BuilderCanvas components={{ ...blockComponents, ...formComponents }} /* … */ />
1640
+
1641
+ // FormFieldBlock: one field, with the canvas attributes on its root element
1642
+ export function FormFieldBlock({ block, props, attributes }: BlockComponentProps) {
1643
+ const field = { ...props, blockType: formFieldSlug(block.type) }
1644
+ return <MyFormField field={field} attributes={attributes} preview />
1645
+ }
1646
+
1647
+ // actions.tsx ('use server'): the form around the fields
1648
+ createCanvasServer({
1649
+ /* … */
1650
+ frame: ({ document, doc, region }) =>
1651
+ document.collection === 'forms' ? (
1652
+ <form className="flex flex-col gap-5">
1653
+ <LayoutOutlet className="flex flex-wrap gap-x-4 gap-y-5" />
1654
+ {region(FORM_SETTINGS_REGION, <SubmitButton label={doc.submitButtonLabel} />)}
1655
+ </form>
1656
+ ) : null,
1657
+ })
1658
+ ```
1659
+
1660
+ `LayoutOutlet` (from `payload-canvas/react`) is where the fields go. Its `className` styles their box, so fields with a width share a line as on the site. The submit button is the form settings region: a click on it selects the settings. In the preview, inputs should take no clicks (`pointer-events: none`), so a click selects the field. The starter's `FormParts.tsx`, `FormFieldBlock.tsx` and `FormFrame.tsx` are a complete example: the site's `FormView` and the preview render the same field component.
1661
+
1662
+ ### Forms on pages
1663
+
1664
+ Build a form right on a page, like in Webflow: the fields are blocks inside a **Form** block, in Layers, the Blocks tab, the inspector and the Styles panel. There is no trip to the Forms collection.
1665
+
1666
+ 1. List the Form block and the Submit button block in your blocks, next to `forms: true`:
1667
+
1668
+ ```ts
1669
+ import { formBlocks } from 'payload-canvas/forms'
1670
+
1671
+ export const blocks = [
1672
+ ...defaultBlocks(),
1673
+ // Default classes of the form-wide parts: labels, inputs, help texts, errors and the button.
1674
+ ...formBlocks({ partClassNames: { label: 'text-sm font-medium', input: 'w-full rounded-md border px-3 py-2' } }),
1675
+ ]
1676
+ ```
1677
+
1678
+ The plugin completes the Form block with the forms collection's own settings fields and adds one block per field type of the collection (`formText`, `formEmail`, …), so each field and each setting has one definition. Your site renders them with your components: `form`, `formSubmit` and every field type (the starter's `Form.tsx`, `FormFieldBlock.tsx`, `FormSubmitBlock.tsx` and `FormRuntime.tsx` are a complete renderer).
1679
+
1680
+ 2. In the editor, **Form** in the Blocks tab adds a ready contact form: Name, Email, Message and a Submit button. The field blocks are in the **Fields** category. They go only inside a Form block, at any depth (in a grid or a stack inside it too); a drop or a click elsewhere is refused with the reason. Layers shows each field's name.
1681
+
1682
+ | On the Form block | |
1683
+ |---|---|
1684
+ | **Form fields** | **Build here**: the blocks inside are the form. **Use a saved form**: shows a form of the Forms collection, read only, with **Edit form** (the form builder) and **Move into this page** (its fields become blocks here). Layouts from before keep showing their saved form. |
1685
+ | **General, After submit, Mail, Spam protection** | The same settings as in the form builder, folding. |
1686
+ | **Styles** | The Form block is the `<form>` element. Its parts **Labels**, **Inputs**, **Help texts**, **Error messages** and **Submit button** style every field inside. |
1687
+
1688
+ - **Field names** are unique within one Form block: two forms may each have an `email`. A copied, pasted or duplicated field gets a free name (`email2`). Renaming a field of a form with submissions shows a warning: old submissions keep the old name.
1689
+ - **A field's own looks:** each field block has its own classes (its box) and parts (Label, Input, Help text, Error message, Options). A part without classes uses the Form block's classes; the Styles panel starts from them, so changing one value copies the rest. Clearing a part's classes goes back to the form's.
1690
+ - **Publishing** the page (or saving it, for collections without drafts) writes each "Build here" Form block to a document of the Forms collection: its fields in tree order (the plugin's own field rows) and its settings. Emails, spam protection and submissions keep working through the plugin. Drafts and the canvas use the block's own data, so a draft never changes the live form. A form without a title gets the page title ("Contact form"); without a confirmation message, "Thank you. We will reply soon." A page created already published (REST, MCP, a copy in a collection without drafts) gets its forms right after the create. A Form block without a `mode` that holds fields (as MCP and the assistant insert it) is "Build here", and the publish sets `mode: 'build'`.
1691
+ - **Copies:** each form remembers the block it was made from (a hidden `source` group: collection, document id, block id). A copied page or a duplicated Form block gets its own new form when it is published, never the original's. A create never takes over another document's form.
1692
+ - **Removed forms:** deleting a Form block keeps its form, with its submissions. A new submission to a form built on a page or a saved section is refused (410, "This form is no longer on the site.") when that document no longer shows it: the block is gone, or the page is unpublished or deleted. Forms made in the Forms collection are not checked.
1693
+ - **Saved sections:** a Form block in a saved section (`builder-sections`) is written when the section is saved (sections have no drafts): one form per section block, shared by every page that shows the section live. A copy of the section on a page (inserted or detached) is a page block and gets its own form.
1694
+ - **Move into this page** puts the saved form's fields in place of the block's content, in one undo step. It writes nothing: the page's next publish takes the form over (its id and its submissions stay) when no other document uses it and no other block owns it. Otherwise, or without the references index (`references: false`, so usage is unknown), the page gets its own copy on publish. An undo, or closing the page without publishing, leaves the form as it was. The form is read with the user's access. The form builder shows a note on forms built on a page, with a link to the page: a publish that changes the form there replaces changes made in the form builder.
1695
+ - **Who edits a page form:** the publish writes the form as the system (access off), so whoever may publish the page edits its form, emails included. To limit that, limit who may update or publish the page collection, or give a setting field of the forms collection its own `access.update` (for example on `emails`): the Form block's props keep the field's access, so the inspector, REST and MCP keep the stored value for users without it.
1696
+ - **Locales:** with Payload's localization the publish writes the default locale explicitly. When the forms collection has localized fields, it writes each other locale too, from the block's translations.
1697
+ - **AI:** MCP tools and the assistant use the same blocks. `listBlocks` explains the Form block, its modes and that fields go inside it.
1698
+
1699
+ The `source` group is a new set of columns on the forms table: production needs a migration (`pnpm payload migrate:create`).
1700
+
1701
+ ### Forms without JavaScript
1702
+
1703
+ A form must send when JavaScript is off or failed to load. The starter's form is a real `<form method="post" action="/forms/submit" enctype="multipart/form-data">` with two hidden inputs (`_form`: the form id, `_return`: the page path). With JavaScript, its submit handler sends the request as before and the post never happens.
1704
+
1705
+ - `app/(frontend)/forms/submit/route.ts` reads the native form data, builds the same submission the script sends (`noScriptSubmission(form.fields, formData)`: answers by field name, files as parts, the honeypot), and creates it with the Local API as the visitor (no user, `overrideAccess: false`, the request's headers and files), so every submissions hook runs. It sets `context[FORM_NO_SCRIPT_CONTEXT]` (only server code can): the fill time cannot be measured, so that check passes; the honeypot and the rate limit stay. A form that uses Turnstile is refused with a clear message (the check needs its widget). Files of a failed submission are removed (`removeStoredFormFiles`).
1706
+ - It redirects with 303 back to the page (the `Referer` on this site, else `_return`; `safeReturnPath` refuses other hosts), with the result in the query (`formResultSearch`: `?form-result=sent|error&form-id=…`, the message and the problems) and `#form-<id>`. A form with a redirect confirmation goes there instead.
1707
+ - Pages stay static: `proxy.ts` rewrites only addresses with `form-result` to the dynamic `app/(frontend)/form-result/[[...slug]]` route, which renders the same page inside `FormResultProvider` (`readFormResult`). The form the result belongs to shows its confirmation, or its problems above the button, in the server render. A result view is `noindex`, and a submission's page address leaves the result out (`withoutFormResult`).
1708
+ - Limits: after a refused post the answers are empty again (they never go into the address). Fields that need JavaScript to change (the dropdown, the file drop zone's list) post their default or native value.
1709
+
1710
+ ### Display conditions
1711
+
1712
+ `withFormConditions(block)` adds a **Display conditions** group to a field block. **Show when** is "all rules match" or "any rule matches". Each rule is *field*, *test*, *value*. Tests: equals, does not equal, contains, is empty, is not empty. Text compares without case; a ticked checkbox equals `true`. In the builder, the rule's field is a list of the form's other fields, and the preview notes each field's conditions under it ("Shows when topic equals “website”"). The preview always shows every field.
1713
+
1714
+ - **On the site:** `hiddenFormFields(fields, values)` from `payload-canvas/forms` returns the names of the fields the current answers hide. Do not render, check or send those fields. A rule that reads a hidden field sees it as empty, so chains of conditions work.
1715
+ - **On submission:** `formSubmissionConditions()` (a `beforeValidate` hook for the submissions collection) reads the form and drops the answers of hidden fields. It refuses a submission that leaves a shown required field empty (400, "Company is required.") or gives an answer in the wrong format (400, "Web address: Enter a web address like https://example.com."). The form-builder plugin has no server checks of its own; this hook adds them. `formAnswerProblem(field, value)` in `payload-canvas/forms` is the same check for the site's form, so both show the same messages.
1716
+ - `applyFormConditions(fields, submissionData)` (pure, in `payload-canvas`) is the same rule without Payload, for your own handlers.
1717
+
1718
+ ### Field settings
1719
+
1720
+ `withFormFieldSettings(block)` adds the Gravity Forms style settings a field block lacks. It keeps the settings a block has already. The form-builder plugin stores form fields as JSON, so no migration is needed.
1721
+
1722
+ | Setting | Field types | On the site |
1723
+ |---|---|---|
1724
+ | **Description** (`description`) | all but hidden and message | help text under the input, linked with `aria-describedby` |
1725
+ | **Label visibility** (`labelVisibility`: `visible`, `hidden`) | all but hidden, message, checkbox and consent | `hidden` keeps the label for screen readers only |
1726
+ | **Placeholder** (`placeholder`) | text, email, long text, number, phone, web address, dropdown, country, state | grey text in the empty input; a dropdown's empty choice |
1727
+ | **Default value** (`defaultValue`) | email, country and state (the others have it already) | the starting answer |
1728
+ | **Display** (`display`: `list`, `inline`, `buttons`, `cards`) | radio | one option per line, on one line, joined buttons, or a box per option. Real radio inputs underneath, so arrow keys and screen readers work |
1729
+ | **Classes** (hidden `cssClass` and `partClasses`) | all but hidden | the field's box and its parts, edited in the builder's Styles panel. Older "CSS class" values show there as the field's classes |
1730
+
1731
+ `withFormFieldSettings` also hides the plugin's `width` (see [Field width](#field-width)). `radioDisplay`, `isLabelShown` and `maxFileCount` read the settings. The starter's `FormParts.tsx` renders every setting; its dropdown is the project's shadcn Select (Base UI, with a hidden input that submits the value).
1732
+
1733
+ ### Field width
1734
+
1735
+ A field's width is classes on the field, set in the Styles panel like any block's: **Width**, or **Flex basis** and **Col span** under "As a child". The settings have no width. Fields sit side by side through the form's own layout: the fields area wraps (`flex flex-wrap gap-x-4 gap-y-5`, the Form block's default), or put fields in a Grid or Stack block inside the form. In a wrapping row with a 1rem gap, half a row from the `sm` breakpoint is `sm:w-[calc(50%-0.5rem)]`: the field's share of the row less its share of the gap. A plain `w-1/2` leaves no room for the gap, so the next field wraps.
1736
+
1737
+ Forms from before keep their look. The plugin's `width` (a percentage) becomes classes:
1738
+
1739
+ | Stored `width` | Classes |
1740
+ |---|---|
1741
+ | empty, 0, above 75 | none (full width) |
1742
+ | 68 to 75 | `sm:w-[calc(75%-0.25rem)]` |
1743
+ | 51 to 67 | `sm:w-[calc(66.667%-0.333rem)]` |
1744
+ | 35 to 50 | `sm:w-[calc(50%-0.5rem)]` |
1745
+ | 26 to 34 | `sm:w-[calc(33.333%-0.667rem)]` |
1746
+ | 1 to 25 | `sm:w-[calc(25%-0.75rem)]` |
1747
+
1748
+ - **When the builder opens** a form or a page (editor, MCP tools), each field with a stored `width` gets these classes (`withWidthClass`, the field blocks' `upgrade`), unless its classes set a width already. Its `width` becomes `null`, so the next save stores the classes and clears the plugin's value. Clearing it means the classes alone decide the width: remove the width class and the field is full width. A number kept next to the classes could not hold a grid span or a different width per breakpoint, and it would bring the old width back.
1749
+ - **Until that save** the site draws a stored `width` with the same classes (`withStoredWidth(className, width)`, in the starter's `FormParts.tsx`), so nothing moves. The generated CSS has these classes wherever there are form fields or a Form block (their definitions' `classes`). The field's box needs the `builder-css` class for them.
1750
+ - `withFormFieldSettings` and `formFieldBlocks` hide the plugin's `width` field, in Payload's own form too. MCP and the assistant set the width with `className`, never `width`.
1751
+
1752
+ ### More field types
1753
+
1754
+ `moreFormFields` from `payload-canvas/forms` adds five field types to the plugin's `fields` option. Each has a label, an icon and a tooltip in the Blocks tab, and display conditions work with all of them.
1755
+
1756
+ | Type | Stores | Checks |
1757
+ |---|---|---|
1758
+ | `phone` | text | 6 to 15 digits; `+`, spaces, `-`, `.`, `(` `)` allowed |
1759
+ | `url` | text | an http or https address; `example.com` counts |
1760
+ | `hidden` | its **Value**, sent with every answer | none. The preview shows it as a dashed note |
1761
+ | `consent` | `true` or `false` | must be ticked when required (the default). Its **Text** is rich text, so it can link to the privacy policy |
1762
+ | `file` | the files, in an upload collection | **Allowed file types** (`image/*, application/pdf, .docx`; empty: images, PDF, office documents, text and CSV), **Largest file (MB)** for each file (at most 10 MB), and **Allow several files** with **Most files** (default 5, at most 20). HTML, SVG, scripts and XML are never taken |
1763
+
1764
+ The plugin's own `radio` and `date` types need nothing extra. `formAnswerProblem` checks that a radio or select answer is one of the options, and that a date is a real date.
1765
+
1766
+ ```ts
1767
+ import { fields as formFields } from '@payloadcms/plugin-form-builder'
1768
+ import { moreFormFields, withFormConditions, withFormFieldSettings } from 'payload-canvas/forms'
1769
+
1770
+ formBuilderPlugin({
1771
+ fields: {
1772
+ radio: withFormConditions(formFields.radio),
1773
+ date: withFormConditions(formFields.date),
1774
+ ...Object.fromEntries(Object.entries(moreFormFields).map(([slug, block]) => [slug, withFormFieldSettings(withFormConditions(block))])),
1775
+ },
1776
+ })
1777
+ ```
1778
+
1779
+ Your form renders them (the starter's `FormParts.tsx` is an example). For a `file` field, send the submission as multipart form data: the JSON in `_payload`, and each file as a part named after its field (several files: several parts with the same name), with the file names as the field's answer in `submissionData`. `filesProblem(files, field)` checks the number of files, their type and size; the starter's drop zone (`FileDropZone.tsx`) shows its message at once. `formFileUploads({ collection, field })` (a submissions `beforeChange` hook) runs the same check again, stores each file in `collection` (required), and links them on `field` (default `attachments`: a `hasMany` relationship or upload field you add to the submissions). It replaces the answer with the file names and addresses, so emails show them. Keep `collection` private: visitors send CVs and other private files. Give it `read` access for signed-in users only and a `staticDir` outside `public/` (the starter's `src/collections/FormFiles.ts`); never use a public collection such as Media. A file field that the visitor's answers hide is skipped. Links a visitor sends in `attachments` are ignored, and so is any answer a visitor writes for a file field: only stored files answer it.
1780
+
1781
+ File types are checked by the file's ending and its MIME type (`fileTypeAllowed`). An ending in `accept` (`.pdf`) must match the name; a MIME pattern (`image/*`) needs both the type the browser sends and the type of the ending to match, so a file never passes on the browser's word alone. An empty `accept` takes `DEFAULT_FILE_ACCEPT` (images except SVG, PDF, office documents, text, CSV), never any type. HTML, SVG, scripts and XML (`fileTypeBlocked`) are refused whatever `accept` says: a stored file opens on the site's own address, where its script would run with a signed-in admin's cookies. Serve the upload collection's files as downloads too: the starter's `FormFiles.ts` sets `Content-Disposition: attachment` and `X-Content-Type-Options: nosniff` with `upload.modifyResponseHeaders`.
1782
+
1783
+ When a submission fails after its files were stored (a refused answer, a database error), `formFileUploadsCleanup()` (a submissions `afterError` hook) deletes the upload documents and their files on disk. Payload runs `afterError` for REST and GraphQL requests; server code calls `removeStoredFormFiles(req)` after a failed Local API create. With a cloud storage adapter (no `staticDir`) the files stay. The plugin's own `upload` type cannot take display conditions (the plugin ignores a config for it), so use `file`.
1784
+
1785
+ ### Emails
1786
+
1787
+ Each form has a list of emails, as in Contact Form 7: for example a notification to the site owner and an auto-reply to the visitor. `withFormEmailFields(defaultFields)` (for `formOverrides.fields`) gives each email **To**, **From name**, **From email**, **Reply-To**, **CC**, **BCC**, **Subject** and a **Body** that is rich text or **Custom HTML**. The plugin's own field names stay, so stored emails keep working. `fromName`, `bodyType` and `html` are new columns (production needs a migration).
1788
+
1789
+ Merge tags work in every line and in the body:
1790
+
1791
+ - `{{name}}`: the answer of the field named `name`. An empty or hidden answer gives nothing. A tag that names no field stays as it is, so you see the typo.
1792
+ - `{{*}}`: every answer, with the field labels. A table in the body, "Label: value" in a line. A ticked box reads "Yes".
1793
+ - `{{formTitle}}` and `{{formSubmissionID}}`.
1794
+
1795
+ In the builder, each of these inputs has an **Insert field** menu with the form's fields and `{{*}}`. It inserts the tag at the cursor, also in the rich text body. `formEmails()` (the plugin's `beforeEmail`) builds each email. Answers are HTML-escaped in the body. Address lines keep only valid addresses, so an answer can never add a recipient or a header. An email with no To address is not sent. Without a From email, the email adapter's address is used; without both From fields, its name too. Each email also gets a plain text part.
1796
+
1797
+ ### AI agents edit forms
1798
+
1799
+ `builderMcpTools({ forms: true })` (the same value as the plugin's `forms`) adds five MCP tools:
1800
+
1801
+ | Tool | Does |
1802
+ |---|---|
1803
+ | `listForms` | The forms with their field names and the form builder link. |
1804
+ | `getForm` | One form: its fields in order (type, name, label, required, className (its classes, width included), options, message text, display conditions and `shows`, the conditions in words), the field types this site offers, the settings and a guide. Includes unsaved edits of people who have the form open. |
1805
+ | `createForm` | A new form with its fields and settings. |
1806
+ | `editFormFields` | Changes the fields, in order, all or nothing: `add { type, values, index? }`, `update { field, values, unset? }`, `move { field, index }`, `remove { field }`, `setConditions { field, conditions }`. `field` is the name or the id. |
1807
+ | `updateFormSettings` | Title, submit button, confirmation, redirect, emails and other settings groups (spam protection). |
1808
+
1809
+ - Field changes are commits to the form's live session, as in the form builder. An open builder shows each change at once, and the form saves about a second later.
1810
+ - Settings save through the same code as the settings panel (Payload's Local API as the key's user, with the document's write gate). An open builder reloads them.
1811
+ - Agents send rich text (a message field, the confirmation message, email bodies) as plain text, one paragraph per line, and read it back as plain text.
1812
+ - The tools check names (letters, digits and `_`, unique in the form) and conditions (a rule names another field of the form). A new field without a name gets one from its label ("Company size" becomes `company_size`); options sent as strings get a value from the label. Renaming a field renames it in the other fields' rules.
1813
+ - The tool descriptions explain the field types and the condition format: `{ match: "all" | "any", rules: [{ field, operator, value }] }`, operators `equals`, `notEquals`, `contains`, `isEmpty`, `isNotEmpty`.
1814
+ - The editor's AI assistant has the same field changes in the form builder (`getForm`, `editFormFields`), with a prompt and suggestions for forms.
1815
+ - `formFieldOps(layout, changes, definitions)` (pure, in `payload-canvas/forms`) turns the changes into builder operations, for your own tools.
1816
+
1817
+ ### Spam protection
1818
+
1819
+ `spamProtectionField()` adds a **Spam protection** group to each form, and `formSpamProtection()` checks every submission on the server:
1820
+
1821
+ ```ts
1822
+ import { formSpamProtection, formSubmissionConditions, spamProtectionField } from 'payload-canvas'
1823
+
1824
+ formBuilderPlugin({
1825
+ formOverrides: { fields: ({ defaultFields }) => [...defaultFields, spamProtectionField()] },
1826
+ // Spam checks first, then the display conditions.
1827
+ // trustedIpHeader: the header the proxy in front of the server sets (see "Rate limit").
1828
+ formSubmissionOverrides: { hooks: { beforeValidate: [formSpamProtection({ trustedIpHeader: 'x-forwarded-for' }), formSubmissionConditions()] } },
1829
+ })
1830
+ ```
1831
+
1832
+ - **Honeypot** (on by default): a hidden input people never see. A bot that fills it is refused.
1833
+ - **Minimum fill time** (default 3 seconds): a form sent faster than this after it showed is refused. This is a heuristic only: the visitor's browser measures the time, so a bot can send any value. The honeypot, the rate limit and Turnstile are the real checks. (Signed timestamps are not used: cached pages make them unreliable.)
1834
+ - **Cloudflare Turnstile** (off by default): needs `TURNSTILE_SITE_KEY` and `TURNSTILE_SECRET_KEY`. Without both keys it stays off, even when a form turns it on. The server checks each token with Cloudflare and refuses when the check fails.
1835
+ - **Rate limit** per visitor IP (default 5 per 10 minutes, 0 turns it off). Counts live in Payload's key-value store (`payload.kv`) under a hash of the IP. Any visitor can send IP headers, so none is trusted by default, and without an IP the limit does not apply. Set `trustedIpHeader` to the header your proxy sets: `'x-forwarded-for'` behind one reverse proxy (nginx, Caddy, Traefik) that appends the address it sees (the rightmost entry is used, never the ones the visitor wrote before it); `'x-real-ip'` for a proxy that sets that header; `'cf-connecting-ip'` only when Cloudflare is the only way to reach the server. For other setups pass `ipOf(req)`. The starter trusts `x-forwarded-for`.
1836
+
1837
+ A blocked submission is not stored. The server logs it (`Form submission blocked`, with the reason) and answers with one generic message, "Your message could not be sent. Please try again later." (400, or 429 for the rate limit), so bots learn nothing.
1838
+
1839
+ Your form sends the checks' values next to the answers: `{ form, submissionData, spam: { honeypot, elapsedMs, token } }`. `honeypot` is the value of the hidden input named `HONEYPOT_NAME`, `elapsedMs` the time since the form showed, `token` the Turnstile token. The hook removes `spam` before the submission is stored. `spamProtection.turnstileSiteKey` (a virtual field) holds the site key on read, only when the form uses Turnstile and both keys are set, so the renderer needs no environment variable. Server code (Local API) that sends no `spam` values and signed-in admins in the admin's create view are not checked; server code that sends them (the no-JavaScript route) is. The starter's `FormView.tsx` and `Turnstile.tsx` are a complete renderer.
1840
+
1841
+ ### Form submissions admin
1842
+
1843
+ `formSubmissionsAdmin()` arranges the plugin's submissions for the people who read them:
1844
+
1845
+ ```ts
1846
+ import { formSubmissionsAdmin } from 'payload-canvas'
1847
+
1848
+ const submissionsAdmin = formSubmissionsAdmin()
1849
+
1850
+ formBuilderPlugin({
1851
+ formSubmissionOverrides: {
1852
+ admin: { ...submissionsAdmin.admin },
1853
+ fields: ({ defaultFields }) => submissionsAdmin.fields([...defaultFields /* your fields */]),
1854
+ },
1855
+ })
1856
+ ```
1857
+
1858
+ - **List:** the sender (name and email when the form has them) with the start of the message, the form, a **New** badge until someone opens the submission, and the date.
1859
+ - **Detail:** a table of the form's questions (its field labels) and the answers, checkboxes as Yes or No, email answers as links, files as thumbnails (the `attachments` upload field, option `attachments`, and the plugin's own uploads), the date and the page the form was sent from, and **Reply by email**. The raw `submissionData` stays in a collapsed **Raw data** group.
1860
+ - Opening a submission as an admin user sets `readAt` once (`context.formSubmissionRead`, so hooks can skip that update).
1861
+ - `sourceUrl` stores the page on create: the value the form sends, else the `Referer` header. Only site paths and http(s) URLs are kept.
1862
+ - `submissionSummary(submissionData, formFields)` and `submissionAnswers(formFields, submissionData)` from `payload-canvas/forms` give the same summary and table to your own views (the starter's dashboard widget uses them).
1863
+ - The new fields need a migration in production: run `pnpm payload migrate:create` when you prepare the release.
1864
+ - Example submissions for a demo: the starter's `pnpm seed:submissions` adds 12 to the Contact form and 4 to every other form, over the past 3 weeks, some new and some read, one with a file from the media library. It runs once (it looks for its `@example.net` answers) and sends no emails.
1865
+
1866
+ ### Limits
1867
+
1868
+ - A new field starts with its type as its name (`text`, `checkbox`). A second one gets `text2`, and a duplicated or pasted field gets a free name too (`uniqueProps`, scoped to the Form block on pages). Payload itself does not check that names are unique, so a field renamed by hand can still clash; on pages, Publish reports it.
1869
+ - Forms on pages write the forms collection's other locales only when its fields are localized; otherwise the form holds the default locale's text.
1870
+ - A Form block in "Use a saved form" mode shows the saved form's own field classes on the site; the canvas preview of it shows only classes the site's CSS has.
1871
+ - A setting that needs another field (choosing **Redirect** needs a page or a URL) waits until that field has a value, then both save together.
1872
+ - Labels that the form-builder plugin writes as translation functions show as words from the field name in the builder ("Submit Button Label").
1873
+ - The AI assistant edits a form's fields, not its settings. It tells people where the settings are.
1874
+
1573
1875
  ## Sections
1574
1876
 
1575
1877
  A section is a ready-made block tree: a hero, a feature grid, a footer. Editors insert it from the **Sections** tab. AI agents use sections as their main building unit.
@@ -1679,7 +1981,7 @@ An inserted section is a copy: later edits of the saved section do not reach the
1679
1981
  - Prop: `section`, a relationship to the saved sections collection. It has no classes and no slots. On the site it renders the section's blocks with no element of its own.
1680
1982
  - `loadLayoutData` loads the sections first, so their lists, images, bindings and translations load like the page's own. The canvas does the same. Copies of the section's blocks get ids prefixed with the ref's id (`<ref id>_<block id>`). A `sectionRef` inside a saved section loads too, up to 5 levels. A section never includes itself: saving one that would is refused, and such a ref renders nothing.
1681
1983
  - CSS: the save hook compiles only the page's own classes. Output the page CSS with `compilePageCss(payload, [{ layout: loaded }])` (from `payload-canvas/react/server`), with the layout `loadLayoutData` returned, so the section's classes are in it.
1682
- - On the canvas the section's blocks show but cannot be edited there: a click selects the `sectionRef`. **Detach section** in its **…** menu replaces it with a copy of the blocks (new ids), as one undo step. A component's copy keeps its own values in the blocks.
1984
+ - On the canvas the section's blocks show as on the site, at full strength, but cannot be edited there: a click selects the `sectionRef`. Components have their own colour (purple, as in Figma) for the hover and selection outline, the name tag, the action bar and their Layers row. Change it with the `--be-component`, `--be-component-solid` and `--be-component-text` CSS variables on `.builder-editor`. **Detach section** in its **…** menu replaces it with a copy of the blocks (new ids), as one undo step. A component's copy keeps its own values in the blocks.
1683
1985
  - A deleted section shows "Component not found" on the canvas and nothing on the site.
1684
1986
  - References: the saved section lists the pages that show it (**Used in**), and it cannot be deleted while a page uses it, as with media. With saved sections on, the references field also points at the saved sections collection: run `pnpm payload migrate:create` for production.
1685
1987
 
@@ -2163,7 +2465,7 @@ Only published templates count (all templates in draft mode). Templates with an
2163
2465
  - A **binding** connects a block prop to a document field: `bindings: { "text": "title", "image": "author.avatar" }`. Paths are dot paths from the document root. At render time the prop takes the document's value. A missing value falls back to the prop's own value. In the editor, the binding picker lists only compatible fields of the target collection, including one relationship hop.
2164
2466
  - The **Field** block (`field`) shows one field of the document by path, rendered by its type: rich text, an upload as an image, a date, a relationship's title, or text. Use it for the post body.
2165
2467
  - The **Collection list** block (`collectionList`) lists the latest documents of a collection (`collection`, `limit`, `sort`, `excludeCurrent`, `offset`, `depth`, and the filters `filterField`, `filterBy`, `where` and `queryFilters` below). Its `item` slot is the design of one item and repeats for every document. Its `empty` slot shows instead when no document matches, for example a text "No posts yet". Blocks in the item bind to the item's fields, for example a heading with `bindings: { "text": "title" }` and a link with `bindings: { "link": "$url" }` (the item's URL from the collection's `url` option). The block offers the collections with a `url`; add data collections without pages (testimonials, team members) with the plugin's `listCollections` option. The site shows published documents only. It works on normal pages too, not only in templates.
2166
- - In the inspector, the fields show under the headings **Filter**, **Sort and count** and **Pages**. **Sort** is a select of the collection's fields with a direction ("Newest first", "A to Z") and **Random order**. It stores the same `sort` text (`-publishedAt`, `$random`). Your own blocks can use the same controls: `admin.custom.builderSort: { collectionField: 'collection' }` on a text field, and `admin.custom.builderHeading: 'Filter'` for a heading above a field.
2468
+ - In the inspector, the fields show under the headings **Filter**, **Sort and count** and **Pages**. **Sort** is a select of the collection's fields with a direction ("Newest first", "A to Z") and **Random order**. It stores the same `sort` text (`-publishedAt`, `$random`). Your own blocks can use the same controls: `admin.custom.builderSort: { collectionField: 'collection' }` on a text field, and `admin.custom.builderHeading: 'Filter'` for a heading above a field. A Payload `tabs` field with several tabs shows as a tab strip in the inspector (the tab stays chosen when you select another block with the same tabs); a `collapsible` with `admin.initCollapsed` starts folded.
2167
2469
  - `offset` skips documents after the sort (at most 100).
2168
2470
  - `depth` is `"1"` (default) or `"2"`: how deep the related documents of each item load. Use `"2"` to reach, for example, `categories.image`.
2169
2471
  - The **Repeat** block (`repeat`) repeats its `item` slot per row of an array or hasMany field. See "Repeat the rows of a field" below.
@@ -2445,6 +2747,15 @@ It writes only the `builderRefs` field of each document and of each latest draft
2445
2747
 
2446
2748
  **Database schema.** The field adds rows to the builder collections' `_rels` tables (and their version tables). In development, `pnpm dev` pushes the change. Before a production deploy, create a migration with `pnpm payload migrate:create`.
2447
2749
 
2750
+ ### Array row labels
2751
+
2752
+ The inspector names each array row by its content: "Sales team (sales)" for a dropdown option, "email: ada@example.com" for a key and value, the heading of a slide. It reads the row's text fields in this order of names: label, title, name, heading, question, text, value, url, href, slug, email, caption, alt. Then it takes the first text field, also inside groups. A row without text gets "Item 1" (the field's singular label and the row number from 1).
2753
+
2754
+ The same rule is public, so Payload's own admin can name rows the same way:
2755
+
2756
+ - `rowLabel(row, fields, index, singular?)` from `payload-canvas/core` returns the label as text.
2757
+ - `ArrayRowLabel` is a RowLabel component for any Payload array field: `admin: { components: { RowLabel: 'payload-canvas/client#ArrayRowLabel' } }`. Run `pnpm generate:importmap` after you add it. The starter sets it on every array field without its own RowLabel (`src/admin/fields/rowLabels.ts`).
2758
+
2448
2759
  ## Localization
2449
2760
 
2450
2761
  Turn on Payload's `localization`, and builder pages translate. Every language shares one layout: the same blocks, order, classes and bindings. Only the text props differ per language. This is the Webflow model.
@@ -2759,7 +3070,7 @@ plugins: [
2759
3070
  - `generateImage` makes an image with the site's image adapter (`ai.images` in `websiteBuilder`) and saves it in the media collection. Clients that cannot make images (Claude Code with a Claude plan) use the site's adapter this way. The key needs `create` on the media collection.
2760
3071
  - Every tool checks the key's access to the collection. Handlers run as the key's user with `overrideAccess: false`.
2761
3072
  - Writes are commits to the document's live session, like an editor's own changes. Open editors show them at once, and the agent appears in the collaborator list while it works. The draft is saved about a second later. `getLayout` returns the session's layout, unsaved changes included.
2762
- - `builderMcpTools` options: `blocks`, `sections`, `collections` (the same map as the plugin), `listCollections` (the same list as the plugin), `siteUrl` (default: Payload `serverURL`, then `NEXT_PUBLIC_SERVER_URL`), `apiKeyCollection`, `mediaCollection` (default `media`, the same as `ai.mediaCollection`).
3073
+ - `builderMcpTools` options: `blocks`, `sections`, `collections` (the same map as the plugin), `listCollections` (the same list as the plugin), `siteUrl` (default: Payload `serverURL`, then `NEXT_PUBLIC_SERVER_URL`), `apiKeyCollection`, `mediaCollection` (default `media`, the same as `ai.mediaCollection`), `forms` (the same value as the plugin's `forms`: adds the [form tools](#ai-agents-edit-forms)).
2763
3074
 
2764
3075
  ## Multiplayer editing
2765
3076
 
@@ -2817,6 +3128,7 @@ Data and access:
2817
3128
  - Each comment is a document of the plugin's **Comments** collection (slug `builder-comments`): the page (`docCollection`, `docId`), the block (`blockId`), the pin (`x`, `y`, 0 to 1 inside the block's box), the text (`body`), the author, and for a thread its resolved state (`resolved`, `resolvedByName`, `resolvedAt`). A reply has `parent` set to its thread.
2818
3129
  - People who may change the page may comment on it, reply, resolve and reopen. A hook checks this on every save, also over REST. Only the author changes the text or deletes a comment. Signed-in users read comments; set `comments.access.read` to restrict that.
2819
3130
  - The editor reads and writes the collection over Payload's REST API. Each save or delete goes to the page's open editors as a `comments` event on the live channel (see [Multiplayer editing](#multiplayer-editing)). A reconnect loads the list again.
3131
+ - `/admin/builder/<collection>/<id>?comment=<thread id>` opens the builder in comment mode with that thread open (`builderViewPath(admin, collection, id, { comment })`). The starter's "Open comments" dashboard widget links there.
2820
3132
  - On by default. `websiteBuilder({ comments: false })` turns it off. Options: `comments: { slug?, access?, admin?, hooks? }`. The new collection needs a migration in production (`pnpm payload migrate:create`).
2821
3133
 
2822
3134
  Not included yet: mentions and email notifications.
@@ -0,0 +1,12 @@
1
+ import type { ClientField } from 'payload';
2
+ type Props = {
3
+ /** The array field, sent by Payload to every RowLabel component. */
4
+ readonly field?: ClientField;
5
+ };
6
+ /**
7
+ * A row label for any Payload array field: the row's most telling value ("Sales team (sales)"),
8
+ * else "Item 1" with the field's singular label. The same rule names rows in the builder's
9
+ * inspector (`rowLabel` in `payload-canvas/core`). Set it as `admin.components.RowLabel`.
10
+ */
11
+ export declare function ArrayRowLabel({ field }: Props): import("react").JSX.Element;
12
+ export {};