payload-canvas 0.3.0-next.1 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1010 -55
- package/dist/admin/AiKeyField.d.ts +8 -0
- package/dist/admin/AiKeyField.js +54 -0
- package/dist/admin/BuilderTab.js +4 -1
- package/dist/admin/DocumentEditView.d.ts +9 -0
- package/dist/admin/DocumentEditView.js +45 -0
- package/dist/admin/LayoutField.d.ts +2 -2
- package/dist/admin/LayoutField.js +10 -7
- package/dist/admin/TemplateConditionsField.d.ts +9 -0
- package/dist/admin/TemplateConditionsField.js +22 -0
- package/dist/admin/aiKeyField.scss +58 -0
- package/dist/admin/client.d.ts +3 -0
- package/dist/admin/client.js +6 -0
- package/dist/admin/diff/LayoutDiff.js +3 -3
- package/dist/admin/diff/changes.js +13 -0
- package/dist/admin/diff/layoutDiff.scss +48 -48
- package/dist/admin/editor/Canvas.js +20 -5
- package/dist/admin/editor/DragLayer.js +1 -1
- package/dist/admin/editor/Editor.d.ts +3 -1
- package/dist/admin/editor/Editor.js +6 -3
- package/dist/admin/editor/InlineToolbar.js +1 -1
- package/dist/admin/editor/Inspector.js +115 -23
- package/dist/admin/editor/Library.js +40 -15
- package/dist/admin/editor/Outline.js +26 -19
- package/dist/admin/editor/Overlay.js +9 -4
- package/dist/admin/editor/actions.d.ts +18 -2
- package/dist/admin/editor/actions.js +53 -3
- package/dist/admin/editor/assistant/AssistantPanel.js +4 -2
- package/dist/admin/editor/assistant/ConnectAgents.js +1 -1
- package/dist/admin/editor/assistant/assistant.scss +65 -65
- package/dist/admin/editor/classes/ClassManager.d.ts +4 -0
- package/dist/admin/editor/classes/ClassManager.js +56 -0
- package/dist/admin/editor/classes/controller.d.ts +112 -0
- package/dist/admin/editor/classes/controller.js +326 -0
- package/dist/admin/editor/classes/manager.scss +262 -0
- package/dist/admin/editor/classes/managerModel.d.ts +5 -0
- package/dist/admin/editor/classes/managerModel.js +27 -0
- package/dist/admin/editor/comments/CommentLayer.d.ts +2 -0
- package/dist/admin/editor/comments/CommentLayer.js +143 -0
- package/dist/admin/editor/comments/CommentsPanel.d.ts +8 -0
- package/dist/admin/editor/comments/CommentsPanel.js +73 -0
- package/dist/admin/editor/comments/Thread.d.ts +26 -0
- package/dist/admin/editor/comments/Thread.js +84 -0
- package/dist/admin/editor/comments/comments.scss +539 -0
- package/dist/admin/editor/comments/controller.d.ts +48 -0
- package/dist/admin/editor/comments/controller.js +142 -0
- package/dist/admin/editor/contentMode.d.ts +17 -0
- package/dist/admin/editor/contentMode.js +37 -0
- package/dist/admin/editor/dnd/DropOutlines.d.ts +1 -0
- package/dist/admin/editor/dnd/DropOutlines.js +73 -0
- package/dist/admin/editor/dnd/dnd.scss +45 -2
- package/dist/admin/editor/dnd/mode.d.ts +4 -0
- package/dist/admin/editor/dnd/mode.js +39 -0
- package/dist/admin/editor/editor.scss +138 -183
- package/dist/admin/editor/empty/EmptyStart.js +21 -43
- package/dist/admin/editor/empty/empty.scss +3 -3
- package/dist/admin/editor/fields/AddButton.d.ts +15 -0
- package/dist/admin/editor/fields/AddButton.js +14 -0
- package/dist/admin/editor/fields/ArrayField.js +4 -3
- package/dist/admin/editor/fields/CheckedInputs.d.ts +1 -0
- package/dist/admin/editor/fields/ConditionRows.d.ts +19 -0
- package/dist/admin/editor/fields/ConditionRows.js +137 -0
- package/dist/admin/editor/fields/GroupField.d.ts +5 -2
- package/dist/admin/editor/fields/GroupField.js +6 -2
- package/dist/admin/editor/fields/ListWhereField.d.ts +8 -0
- package/dist/admin/editor/fields/ListWhereField.js +20 -0
- package/dist/admin/editor/fields/QueryFiltersField.d.ts +18 -0
- package/dist/admin/editor/fields/QueryFiltersField.js +41 -0
- package/dist/admin/editor/fields/RelatedField.d.ts +19 -0
- package/dist/admin/editor/fields/RelatedField.js +44 -0
- package/dist/admin/editor/fields/SortField.d.ts +13 -0
- package/dist/admin/editor/fields/SortField.js +37 -0
- package/dist/admin/editor/fields/WhereField.d.ts +25 -0
- package/dist/admin/editor/fields/WhereField.js +47 -0
- package/dist/admin/editor/fields/access.d.ts +1 -1
- package/dist/admin/editor/fields/collectionFields.d.ts +6 -0
- package/dist/admin/editor/fields/collectionFields.js +15 -0
- package/dist/admin/editor/fields/conditions.d.ts +99 -0
- package/dist/admin/editor/fields/conditions.js +339 -0
- package/dist/admin/editor/fields/fields.scss +346 -34
- package/dist/admin/editor/fields/listOptions.d.ts +44 -0
- package/dist/admin/editor/fields/listOptions.js +111 -0
- package/dist/admin/editor/fields/queryFilterRows.d.ts +8 -0
- package/dist/admin/editor/fields/queryFilterRows.js +29 -0
- package/dist/admin/editor/fields/whereRows.d.ts +27 -0
- package/dist/admin/editor/fields/whereRows.js +167 -0
- package/dist/admin/editor/generate/GenerateImage.js +1 -1
- package/dist/admin/editor/generate/generate.scss +48 -48
- package/dist/admin/editor/icons.d.ts +17 -1
- package/dist/admin/editor/icons.js +33 -2
- package/dist/admin/editor/inline.js +9 -0
- package/dist/admin/editor/insert/InsertHandle.js +5 -2
- package/dist/admin/editor/insert/picker.d.ts +3 -1
- package/dist/admin/editor/insert/picker.js +17 -10
- package/dist/admin/editor/insert/spots.d.ts +12 -1
- package/dist/admin/editor/insert/spots.js +49 -10
- package/dist/admin/editor/layout/FrameResize.js +1 -1
- package/dist/admin/editor/layout/LeftPanel.js +12 -7
- package/dist/admin/editor/layout/layout.scss +4 -4
- package/dist/admin/editor/live/PresenceUI.js +1 -1
- package/dist/admin/editor/live/presence.scss +1 -1
- package/dist/admin/editor/live/useMultiplayer.js +9 -1
- package/dist/admin/editor/locale/LocaleField.d.ts +2 -2
- package/dist/admin/editor/locale/LocaleField.js +4 -2
- package/dist/admin/editor/locale/locale.scss +12 -12
- package/dist/admin/editor/media/ImageEditor.js +1 -1
- package/dist/admin/editor/media/media.scss +23 -23
- package/dist/admin/editor/menu/Menu.js +1 -1
- package/dist/admin/editor/menu/blockMenu.js +32 -18
- package/dist/admin/editor/menu/menu.scss +16 -16
- package/dist/admin/editor/motion/MotionPanel.js +2 -2
- package/dist/admin/editor/motion/model.d.ts +2 -2
- package/dist/admin/editor/motion/model.js +2 -2
- package/dist/admin/editor/motion/motion.scss +2 -2
- package/dist/admin/editor/names.js +11 -3
- package/dist/admin/editor/regions/RegionOverlay.js +1 -1
- package/dist/admin/editor/regions/RegionPane.js +1 -1
- package/dist/admin/editor/renderField.d.ts +5 -1
- package/dist/admin/editor/renderField.js +73 -13
- package/dist/admin/editor/runtime.d.ts +14 -0
- package/dist/admin/editor/runtime.js +68 -6
- package/dist/admin/editor/sections/ComponentFields.d.ts +8 -0
- package/dist/admin/editor/sections/ComponentFields.js +116 -0
- package/dist/admin/editor/sections/PropertyControls.d.ts +18 -0
- package/dist/admin/editor/sections/PropertyControls.js +65 -0
- package/dist/admin/editor/sections/components.d.ts +29 -0
- package/dist/admin/editor/sections/components.js +112 -0
- package/dist/admin/editor/sections/components.scss +238 -0
- package/dist/admin/editor/sections/variants.d.ts +32 -0
- package/dist/admin/editor/sections/variants.js +59 -0
- package/dist/admin/editor/sections/variants.scss +90 -0
- package/dist/admin/editor/shortcuts.d.ts +4 -1
- package/dist/admin/editor/shortcuts.js +19 -3
- package/dist/admin/editor/store.d.ts +18 -0
- package/dist/admin/editor/store.js +46 -0
- package/dist/admin/editor/styles/ClassBar.d.ts +14 -0
- package/dist/admin/editor/styles/ClassBar.js +90 -0
- package/dist/admin/editor/styles/ClassCss.d.ts +4 -0
- package/dist/admin/editor/styles/ClassCss.js +28 -0
- package/dist/admin/editor/styles/ClassDialog.d.ts +2 -0
- package/dist/admin/editor/styles/ClassDialog.js +151 -0
- package/dist/admin/editor/styles/ColorPicker.js +6 -3
- package/dist/admin/editor/styles/RawClasses.d.ts +26 -1
- package/dist/admin/editor/styles/RawClasses.js +184 -32
- package/dist/admin/editor/styles/StylesPanel.d.ts +3 -1
- package/dist/admin/editor/styles/StylesPanel.js +53 -11
- package/dist/admin/editor/styles/VariantBar.js +3 -3
- package/dist/admin/editor/styles/classEdit.d.ts +4 -0
- package/dist/admin/editor/styles/classEdit.js +20 -0
- package/dist/admin/editor/styles/classes.scss +381 -0
- package/dist/admin/editor/styles/context.d.ts +24 -4
- package/dist/admin/editor/styles/context.js +32 -9
- package/dist/admin/editor/styles/controls.d.ts +3 -1
- package/dist/admin/editor/styles/controls.js +31 -13
- package/dist/admin/editor/styles/popover.d.ts +6 -0
- package/dist/admin/editor/styles/popover.js +5 -5
- package/dist/admin/editor/styles/sections.js +2 -2
- package/dist/admin/editor/styles/styles.scss +115 -139
- package/dist/admin/editor/styles/suggestions.d.ts +22 -0
- package/dist/admin/editor/styles/suggestions.js +77 -0
- package/dist/admin/editor/styles/tokens.js +14 -0
- package/dist/admin/editor/templates/Bindable.d.ts +14 -6
- package/dist/admin/editor/templates/Bindable.js +146 -61
- package/dist/admin/editor/templates/SamplePicker.js +2 -2
- package/dist/admin/editor/templates/Visibility.d.ts +9 -0
- package/dist/admin/editor/templates/Visibility.js +54 -0
- package/dist/admin/editor/templates/binding.d.ts +11 -4
- package/dist/admin/editor/templates/binding.js +23 -3
- package/dist/admin/editor/templates/templates.scss +117 -90
- package/dist/admin/editor/templates/visibilityRows.d.ts +22 -0
- package/dist/admin/editor/templates/visibilityRows.js +83 -0
- package/dist/admin/editor/tooltip/tooltip.scss +4 -4
- package/dist/admin/editor/topbar/ContentModeToggle.d.ts +5 -0
- package/dist/admin/editor/topbar/ContentModeToggle.js +26 -0
- package/dist/admin/editor/topbar/DocumentActions.d.ts +1 -1
- package/dist/admin/editor/topbar/DocumentActions.js +6 -5
- package/dist/admin/editor/topbar/DocumentTitle.js +8 -3
- package/dist/admin/editor/topbar/TopBar.js +15 -3
- package/dist/admin/editor/topbar/contentMode.scss +35 -0
- package/dist/admin/editor/topbar/screens/DrawerRouter.d.ts +1 -1
- package/dist/admin/editor/topbar/screens/ScreenDrawer.js +1 -1
- package/dist/admin/editor/topbar/screens/drawerRouterSupport.d.ts +1 -1
- package/dist/admin/editor/topbar/screens/screens.scss +20 -20
- package/dist/admin/editor/topbar/settingsDrawer.js +3 -3
- package/dist/admin/editor/topbar/settingsDrawer.scss +7 -7
- package/dist/admin/editor/topbar/topbar.scss +50 -48
- package/dist/admin/editor/ui/Select.js +1 -1
- package/dist/admin/editor/ui/controls.scss +26 -26
- package/dist/admin/formChoice.d.ts +3 -0
- package/dist/admin/formChoice.js +10 -0
- package/dist/admin/layoutField.scss +69 -0
- package/dist/admin/screen/BuilderScreen.d.ts +6 -1
- package/dist/admin/screen/BuilderScreen.js +5 -4
- package/dist/admin/server/BuilderView.js +10 -3
- package/dist/admin/templateConditions.scss +24 -0
- package/dist/ai/adapters/anthropic.d.ts +2 -2
- package/dist/ai/adapters/anthropic.js +17 -4
- package/dist/ai/adapters/cloudflare-gateway.js +7 -1
- package/dist/ai/adapters/cloudflare-workers-ai.js +2 -0
- package/dist/ai/adapters/openai-compatible.js +1 -0
- package/dist/ai/adapters/openrouter.js +2 -0
- package/dist/ai/config.d.ts +24 -4
- package/dist/ai/config.js +27 -8
- package/dist/ai/endpoint.d.ts +5 -2
- package/dist/ai/endpoint.js +31 -26
- package/dist/ai/images/cloudflare-workers-ai.js +6 -2
- package/dist/ai/images/openai.js +8 -3
- package/dist/ai/images/openrouter.js +6 -2
- package/dist/ai/images/service.d.ts +10 -4
- package/dist/ai/images/service.js +24 -8
- package/dist/ai/loop.d.ts +5 -5
- package/dist/ai/openai-format.d.ts +7 -0
- package/dist/ai/openai-format.js +17 -5
- package/dist/ai/prompt.d.ts +8 -0
- package/dist/ai/prompt.js +30 -4
- package/dist/ai/settings/index.d.ts +62 -0
- package/dist/ai/settings/index.js +264 -0
- package/dist/ai/settings/secret.d.ts +11 -0
- package/dist/ai/settings/secret.js +46 -0
- package/dist/ai/settings/shared.d.ts +22 -0
- package/dist/ai/settings/shared.js +3 -0
- package/dist/ai/tools.d.ts +3 -0
- package/dist/ai/tools.js +83 -10
- package/dist/ai/types.d.ts +43 -0
- package/dist/blocks/builtins/adjacentLinks.d.ts +5 -0
- package/dist/blocks/builtins/adjacentLinks.js +76 -0
- package/dist/blocks/builtins/carousel.d.ts +5 -0
- package/dist/blocks/builtins/carousel.js +115 -0
- package/dist/blocks/builtins/disclosure.d.ts +14 -0
- package/dist/blocks/builtins/disclosure.js +97 -0
- package/dist/blocks/builtins/embed.d.ts +15 -0
- package/dist/blocks/builtins/embed.js +47 -0
- package/dist/blocks/builtins/faq.d.ts +17 -0
- package/dist/blocks/builtins/faq.js +88 -0
- package/dist/blocks/builtins/filterLink.d.ts +4 -0
- package/dist/blocks/builtins/filterLink.js +35 -0
- package/dist/blocks/builtins/icon.d.ts +10 -0
- package/dist/blocks/builtins/icon.js +45 -0
- package/dist/blocks/builtins/index.d.ts +40 -0
- package/dist/blocks/builtins/index.js +71 -0
- package/dist/blocks/builtins/marquee.d.ts +5 -0
- package/dist/blocks/builtins/marquee.js +68 -0
- package/dist/blocks/builtins/popup.d.ts +5 -0
- package/dist/blocks/builtins/popup.js +83 -0
- package/dist/blocks/builtins/sectionRef.d.ts +40 -0
- package/dist/blocks/builtins/sectionRef.js +100 -0
- package/dist/blocks/builtins/shared.d.ts +28 -0
- package/dist/blocks/builtins/shared.js +62 -0
- package/dist/blocks/builtins/tableOfContents.d.ts +7 -0
- package/dist/blocks/builtins/tableOfContents.js +38 -0
- package/dist/blocks/builtins/tabs.d.ts +6 -0
- package/dist/blocks/builtins/tabs.js +87 -0
- package/dist/blocks/client/adjacentLinks.d.ts +4 -0
- package/dist/blocks/client/adjacentLinks.js +4 -0
- package/dist/blocks/client/carousel.d.ts +45 -0
- package/dist/blocks/client/carousel.js +53 -0
- package/dist/blocks/client/embed.d.ts +21 -0
- package/dist/blocks/client/embed.js +23 -0
- package/dist/blocks/client/field.d.ts +7 -0
- package/dist/blocks/client/field.js +8 -0
- package/dist/blocks/client/filterLink.d.ts +19 -0
- package/dist/blocks/client/filterLink.js +30 -0
- package/dist/blocks/client/helpers.d.ts +21 -0
- package/dist/blocks/client/helpers.js +24 -0
- package/dist/blocks/client/marquee.d.ts +14 -0
- package/dist/blocks/client/marquee.js +25 -0
- package/dist/blocks/client/menu.d.ts +46 -0
- package/dist/blocks/client/menu.js +49 -0
- package/dist/blocks/client/popup.d.ts +15 -0
- package/dist/blocks/client/popup.js +16 -0
- package/dist/blocks/client/tabs.d.ts +10 -0
- package/dist/blocks/client/tabs.js +11 -0
- package/dist/blocks/defaults.d.ts +15 -34
- package/dist/blocks/defaults.js +339 -180
- package/dist/blocks/index.d.ts +4 -3
- package/dist/blocks/index.js +3 -2
- package/dist/classes/actions.d.ts +97 -0
- package/dist/classes/actions.js +296 -0
- package/dist/classes/collection.d.ts +5 -0
- package/dist/classes/collection.js +189 -0
- package/dist/classes/config.d.ts +34 -0
- package/dist/classes/config.js +8 -0
- package/dist/classes/endpoints.d.ts +2 -0
- package/dist/classes/endpoints.js +120 -0
- package/dist/classes/index.d.ts +36 -0
- package/dist/classes/index.js +42 -0
- package/dist/classes/mcp.d.ts +6 -0
- package/dist/classes/mcp.js +161 -0
- package/dist/classes/shared.d.ts +131 -0
- package/dist/classes/shared.js +300 -0
- package/dist/classes/sheet.d.ts +34 -0
- package/dist/classes/sheet.js +126 -0
- package/dist/classes/usage.d.ts +57 -0
- package/dist/classes/usage.js +208 -0
- package/dist/comments/collection.d.ts +38 -0
- package/dist/comments/collection.js +226 -0
- package/dist/comments/config.d.ts +15 -0
- package/dist/comments/config.js +2 -0
- package/dist/comments/index.d.ts +20 -0
- package/dist/comments/index.js +22 -0
- package/dist/comments/shared.d.ts +54 -0
- package/dist/comments/shared.js +104 -0
- package/dist/core/attrs.d.ts +27 -0
- package/dist/core/attrs.js +132 -0
- package/dist/core/bindings.d.ts +171 -15
- package/dist/core/bindings.js +697 -27
- package/dist/core/blockNames.d.ts +9 -0
- package/dist/core/blockNames.js +11 -0
- package/dist/core/blocks.d.ts +62 -4
- package/dist/core/blocks.js +164 -7
- package/dist/core/classes.d.ts +18 -2
- package/dist/core/classes.js +37 -4
- package/dist/core/components.d.ts +72 -0
- package/dist/core/components.js +294 -0
- package/dist/core/contentMode.d.ts +27 -0
- package/dist/core/contentMode.js +0 -0
- package/dist/core/dropTarget.d.ts +11 -0
- package/dist/core/dropTarget.js +24 -1
- package/dist/core/fieldAccess.js +1 -1
- package/dist/core/fieldHooks.d.ts +1 -1
- package/dist/core/fields.d.ts +5 -0
- package/dist/core/fields.js +11 -0
- package/dist/core/headings.d.ts +24 -0
- package/dist/core/headings.js +55 -0
- package/dist/core/index.d.ts +10 -3
- package/dist/core/index.js +10 -3
- package/dist/core/layers.d.ts +9 -0
- package/dist/core/layers.js +29 -0
- package/dist/core/motion.d.ts +24 -15
- package/dist/core/motion.js +20 -12
- package/dist/core/operations.d.ts +6 -0
- package/dist/core/operations.js +124 -6
- package/dist/core/payloadBlocks.js +7 -1
- package/dist/core/references.js +28 -0
- package/dist/core/schema.js +35 -1
- package/dist/core/sectionOrigin.d.ts +6 -0
- package/dist/core/sectionOrigin.js +21 -0
- package/dist/core/sections.d.ts +72 -0
- package/dist/core/sections.js +331 -0
- package/dist/core/templateChoice.d.ts +24 -0
- package/dist/core/templateChoice.js +43 -0
- package/dist/core/tree.js +37 -2
- package/dist/core/types.d.ts +219 -2
- package/dist/core/validate.d.ts +4 -1
- package/dist/core/validate.js +48 -6
- package/dist/core/visibility.d.ts +63 -0
- package/dist/core/visibility.js +214 -0
- package/dist/core/whereValues.d.ts +22 -0
- package/dist/core/whereValues.js +43 -0
- package/dist/css/classes.d.ts +16 -0
- package/dist/css/classes.js +172 -0
- package/dist/css/index.d.ts +32 -1
- package/dist/css/index.js +64 -5
- package/dist/css/tokens.d.ts +14 -1
- package/dist/css/tokens.js +61 -2
- package/dist/index.d.ts +6 -3
- package/dist/index.js +7 -2
- package/dist/live/contentMode.d.ts +24 -0
- package/dist/live/contentMode.js +39 -0
- package/dist/live/draftAccess.js +1 -1
- package/dist/live/endpoints.js +3 -0
- package/dist/live/session.d.ts +6 -1
- package/dist/live/session.js +8 -0
- package/dist/live/storage.js +4 -2
- package/dist/live/types.d.ts +16 -1
- package/dist/mcp/index.d.ts +12 -1
- package/dist/mcp/index.js +177 -48
- package/dist/mcp/shared.d.ts +123 -30
- package/dist/mcp/shared.js +222 -11
- package/dist/plugin/hook.d.ts +7 -1
- package/dist/plugin/hook.js +30 -4
- package/dist/plugin/index.d.ts +27 -8
- package/dist/plugin/index.js +113 -26
- package/dist/plugin/links.d.ts +24 -0
- package/dist/plugin/links.js +27 -0
- package/dist/plugin/listCollections.d.ts +20 -3
- package/dist/plugin/listCollections.js +54 -8
- package/dist/plugin/references.d.ts +5 -0
- package/dist/plugin/references.js +1 -1
- package/dist/plugin/sections.d.ts +14 -7
- package/dist/plugin/sections.js +69 -23
- package/dist/plugin/sectionsUsedIn.d.ts +6 -0
- package/dist/plugin/sectionsUsedIn.js +24 -0
- package/dist/plugin/templateEndpoint.d.ts +9 -0
- package/dist/plugin/templateEndpoint.js +49 -0
- package/dist/plugin/templates.d.ts +4 -0
- package/dist/plugin/templates.js +42 -12
- package/dist/protocol/index.d.ts +19 -2
- package/dist/react/canvas/BuilderCanvas.js +149 -24
- package/dist/react/canvas/classes.d.ts +17 -0
- package/dist/react/canvas/classes.js +102 -0
- package/dist/react/canvas/controls.d.ts +31 -0
- package/dist/react/canvas/controls.js +75 -0
- package/dist/react/canvas/fetchDocs.d.ts +17 -3
- package/dist/react/canvas/fetchDocs.js +51 -10
- package/dist/react/canvas/inline/rich/editor.js +1 -6
- package/dist/react/canvas/measure.d.ts +12 -1
- package/dist/react/canvas/measure.js +130 -7
- package/dist/react/canvas/resolveLayout.d.ts +1 -1
- package/dist/react/canvas/resolveLayout.js +19 -7
- package/dist/react/canvas/serverBlocks.d.ts +11 -0
- package/dist/react/canvas/serverBlocks.js +28 -1
- package/dist/react/canvas/thumbnail/ThumbnailCanvas.js +18 -5
- package/dist/react/classes/ClassesStyle.d.ts +27 -0
- package/dist/react/classes/ClassesStyle.js +27 -0
- package/dist/react/components/Button.d.ts +1 -1
- package/dist/react/components/Button.js +4 -2
- package/dist/react/components/CollectionList.d.ts +9 -3
- package/dist/react/components/CollectionList.js +28 -7
- package/dist/react/components/Container.d.ts +5 -2
- package/dist/react/components/Container.js +10 -4
- package/dist/react/components/Field.js +2 -2
- package/dist/react/components/Heading.js +9 -2
- package/dist/react/components/Image.d.ts +9 -0
- package/dist/react/components/Image.js +16 -1
- package/dist/react/components/Link.d.ts +1 -1
- package/dist/react/components/Link.js +5 -3
- package/dist/react/components/List.d.ts +2 -1
- package/dist/react/components/List.js +8 -2
- package/dist/react/components/Menu.d.ts +26 -1
- package/dist/react/components/Menu.js +116 -25
- package/dist/react/components/RichText.d.ts +6 -2
- package/dist/react/components/RichText.js +23 -2
- package/dist/react/components/builtins/Accordion.d.ts +10 -0
- package/dist/react/components/builtins/Accordion.js +38 -0
- package/dist/react/components/builtins/AdjacentLinks.d.ts +11 -0
- package/dist/react/components/builtins/AdjacentLinks.js +20 -0
- package/dist/react/components/builtins/Carousel.d.ts +24 -0
- package/dist/react/components/builtins/Carousel.js +209 -0
- package/dist/react/components/builtins/Disclosure.d.ts +8 -0
- package/dist/react/components/builtins/Disclosure.js +14 -0
- package/dist/react/components/builtins/Embed.d.ts +11 -0
- package/dist/react/components/builtins/Embed.js +23 -0
- package/dist/react/components/builtins/EmbedHtml.d.ts +15 -0
- package/dist/react/components/builtins/EmbedHtml.js +51 -0
- package/dist/react/components/builtins/EmbedPreview.d.ts +34 -0
- package/dist/react/components/builtins/EmbedPreview.js +105 -0
- package/dist/react/components/builtins/FilterLink.d.ts +8 -0
- package/dist/react/components/builtins/FilterLink.js +30 -0
- package/dist/react/components/builtins/Icon.d.ts +14 -0
- package/dist/react/components/builtins/Icon.js +28 -0
- package/dist/react/components/builtins/Marquee.d.ts +8 -0
- package/dist/react/components/builtins/Marquee.js +15 -0
- package/dist/react/components/builtins/Popup.d.ts +26 -0
- package/dist/react/components/builtins/Popup.js +146 -0
- package/dist/react/components/builtins/SectionRef.d.ts +8 -0
- package/dist/react/components/builtins/SectionRef.js +21 -0
- package/dist/react/components/builtins/Tab.d.ts +7 -0
- package/dist/react/components/builtins/Tab.js +21 -0
- package/dist/react/components/builtins/TableOfContents.d.ts +21 -0
- package/dist/react/components/builtins/TableOfContents.js +36 -0
- package/dist/react/components/builtins/Tabs.d.ts +17 -0
- package/dist/react/components/builtins/Tabs.js +71 -0
- package/dist/react/components/builtins/glyphs.d.ts +8 -0
- package/dist/react/components/builtins/glyphs.js +7 -0
- package/dist/react/components/builtins/index.d.ts +49 -0
- package/dist/react/components/builtins/index.js +70 -0
- package/dist/react/components/builtins/tabsContext.d.ts +12 -0
- package/dist/react/components/builtins/tabsContext.js +6 -0
- package/dist/react/components/index.js +13 -8
- package/dist/react/components/lazy.d.ts +32 -0
- package/dist/react/components/lazy.js +20 -0
- package/dist/react/components/lazyBlock.d.ts +17 -0
- package/dist/react/components/lazyBlock.js +23 -0
- package/dist/react/index.d.ts +8 -3
- package/dist/react/index.js +7 -2
- package/dist/react/motion/runtime.js +10 -6
- package/dist/react/motion/style.js +1 -1
- package/dist/react/render/PayloadRoot.js +1 -1
- package/dist/react/render/RenderLayout.d.ts +9 -7
- package/dist/react/render/RenderLayout.js +145 -41
- package/dist/react/render/canvasMode.d.ts +13 -0
- package/dist/react/render/canvasMode.js +13 -0
- package/dist/react/render/canvasServer.js +4 -3
- package/dist/react/render/canvasServerTypes.d.ts +5 -0
- package/dist/react/render/lists.d.ts +139 -5
- package/dist/react/render/lists.js +401 -9
- package/dist/react/render/marks.d.ts +15 -0
- package/dist/react/render/marks.js +23 -0
- package/dist/react/render/payload.d.ts +8 -1
- package/dist/react/render/payload.js +12 -3
- package/dist/react/render/preview.d.ts +11 -0
- package/dist/react/render/preview.js +13 -0
- package/dist/react/render/relations.d.ts +10 -0
- package/dist/react/render/relations.js +39 -0
- package/dist/react/render/resolve.d.ts +26 -2
- package/dist/react/render/resolve.js +52 -25
- package/dist/react/render/reveal.d.ts +17 -0
- package/dist/react/render/reveal.js +39 -0
- package/dist/react/render/sections.d.ts +15 -0
- package/dist/react/render/sections.js +79 -0
- package/dist/react/render/templates.d.ts +47 -0
- package/dist/react/render/templates.js +139 -0
- package/dist/react/render/types.d.ts +66 -4
- package/dist/react/server.d.ts +3 -38
- package/dist/react/server.js +9 -86
- package/dist/react/theme/ThemeLiveLoader.d.ts +4 -0
- package/dist/react/theme/ThemeLiveLoader.js +5 -0
- package/dist/react/theme/ThemeStyle.d.ts +13 -2
- package/dist/react/theme/ThemeStyle.js +14 -4
- package/dist/theme/admin/ColorField.d.ts +2 -2
- package/dist/theme/admin/ColorField.js +2 -2
- package/dist/theme/admin/FontField.d.ts +2 -2
- package/dist/theme/admin/FontField.js +2 -2
- package/dist/theme/admin/SaveSignal.js +2 -2
- package/dist/theme/admin/Variables.d.ts +11 -0
- package/dist/theme/admin/Variables.js +115 -0
- package/dist/theme/admin/fields.scss +161 -48
- package/dist/theme/client.d.ts +1 -0
- package/dist/theme/client.js +2 -0
- package/dist/theme/css.d.ts +6 -1
- package/dist/theme/css.js +12 -4
- package/dist/theme/global.js +83 -0
- package/dist/theme/index.d.ts +1 -0
- package/dist/theme/index.js +1 -0
- package/dist/theme/server.d.ts +15 -0
- package/dist/theme/server.js +43 -0
- package/dist/theme/usage.d.ts +23 -0
- package/dist/theme/usage.js +68 -0
- package/dist/theme/variables.d.ts +72 -0
- package/dist/theme/variables.js +231 -0
- package/package.json +25 -28
- package/dist/react/components/Quote.d.ts +0 -3
- package/dist/react/components/Quote.js +0 -12
- package/dist/react/components/Spacer.d.ts +0 -3
- package/dist/react/components/Spacer.js +0 -6
package/README.md
CHANGED
|
@@ -15,11 +15,11 @@
|
|
|
15
15
|
</tr>
|
|
16
16
|
</table>
|
|
17
17
|
|
|
18
|
-
A visual page builder for Payload CMS
|
|
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.
|
|
19
19
|
|
|
20
20
|
The npm package is `payload-canvas`.
|
|
21
21
|
|
|
22
|
-
-
|
|
22
|
+
- Works in any Payload 3.90+ app on Next.js 16 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,26 +27,35 @@ 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
|
|
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:
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
```bash
|
|
33
|
+
npx create-payload-canvas my-website
|
|
34
|
+
```
|
|
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)).
|
|
33
37
|
|
|
34
38
|
## Contents
|
|
35
39
|
|
|
36
40
|
1. [Requirements](#requirements)
|
|
37
41
|
2. [Install](#install)
|
|
38
42
|
3. [The builder view](#the-builder-view)
|
|
43
|
+
- [Content mode for clients](#content-mode-for-clients)
|
|
39
44
|
4. [Inline editing](#inline-editing)
|
|
40
45
|
5. [Plugin options](#plugin-options)
|
|
41
46
|
6. [Rendering the layout on your site](#rendering-the-layout-on-your-site)
|
|
42
47
|
- [Custom components](#custom-components)
|
|
48
|
+
- [Cache Components](#cache-components)
|
|
43
49
|
7. [Server components in the canvas](#server-components-in-the-canvas)
|
|
44
50
|
- [Whole-page editing: regions outside the layout](#whole-page-editing-regions-outside-the-layout)
|
|
45
51
|
8. [Custom blocks](#custom-blocks)
|
|
52
|
+
- [Interactive blocks on the canvas](#interactive-blocks-on-the-canvas)
|
|
46
53
|
- [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields)
|
|
54
|
+
- [Built-in blocks](#built-in-blocks)
|
|
47
55
|
9. [Using existing Payload blocks](#using-existing-payload-blocks)
|
|
48
56
|
10. [Sections](#sections)
|
|
49
57
|
11. [Styling](#styling)
|
|
58
|
+
- [Editable classes](#editable-classes)
|
|
50
59
|
12. [Animations](#animations)
|
|
51
60
|
13. [Theme](#theme)
|
|
52
61
|
14. [Templates and binding](#templates-and-binding)
|
|
@@ -55,6 +64,7 @@ The bundled starter and `create-payload-canvas@latest` still target Payload 3. T
|
|
|
55
64
|
17. [AI assistant](#ai-assistant)
|
|
56
65
|
18. [AI editing over MCP](#ai-editing-over-mcp)
|
|
57
66
|
19. [Multiplayer editing](#multiplayer-editing)
|
|
67
|
+
- [Comments on the canvas](#comments-on-the-canvas)
|
|
58
68
|
20. [Production and Docker](#production-and-docker)
|
|
59
69
|
21. [Deploying](#deploying)
|
|
60
70
|
22. [Troubleshooting](#troubleshooting)
|
|
@@ -62,37 +72,43 @@ The bundled starter and `create-payload-canvas@latest` still target Payload 3. T
|
|
|
62
72
|
|
|
63
73
|
## Requirements
|
|
64
74
|
|
|
65
|
-
- `payload`, `@payloadcms/ui`, `@payloadcms/richtext-lexical`
|
|
66
|
-
- `next` 16.
|
|
75
|
+
- `payload`, `@payloadcms/ui`, `@payloadcms/richtext-lexical` 3.90 or later (Payload 3 only, not the Payload 4 canary)
|
|
76
|
+
- `next` 16.3 or later, `react` and `react-dom` 19.2 or later
|
|
67
77
|
- `tailwindcss` 4.3 or later (the plugin compiles your Tailwind entry CSS)
|
|
68
|
-
- Node.js
|
|
78
|
+
- Node.js 20.9 or later
|
|
69
79
|
- Any Payload database adapter. Postgres and SQLite store the layout as `jsonb`/JSON.
|
|
70
80
|
|
|
71
|
-
The package ships compiled JavaScript.
|
|
81
|
+
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.
|
|
72
82
|
|
|
73
83
|
Peer dependencies:
|
|
74
84
|
|
|
75
85
|
| Package | Range | Needed for |
|
|
76
86
|
|---|---|---|
|
|
77
|
-
| `payload`, `@payloadcms/ui`, `@payloadcms/richtext-lexical` |
|
|
78
|
-
| `next` | `^16.
|
|
87
|
+
| `payload`, `@payloadcms/ui`, `@payloadcms/richtext-lexical` | `^3.90.0` | everything |
|
|
88
|
+
| `next` | `^16.3.0` | everything |
|
|
79
89
|
| `react`, `react-dom` | `^19.2.0` | everything |
|
|
80
90
|
| `tailwindcss` | `^4.3.0` | the CSS compile on save and in the canvas |
|
|
81
91
|
| `@anthropic-ai/sdk` | `>=0.131.0`, optional | only the `/ai/anthropic` adapter |
|
|
82
|
-
| `payload-mcp-toolkit` |
|
|
92
|
+
| `payload-mcp-toolkit` | `>=0.9.0`, optional | only `builderMcpTools()` (`/mcp`) |
|
|
83
93
|
| `zod` | `^3.25 \|\| ^4`, optional | only `builderMcpTools()` (`/mcp`) |
|
|
84
94
|
|
|
85
95
|
## Install
|
|
86
96
|
|
|
87
|
-
These steps start from
|
|
97
|
+
These steps start from a blank Payload app with Postgres:
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
npx create-payload-app@latest -n my-site -t blank --db postgres --use-pnpm
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
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.
|
|
88
104
|
|
|
89
105
|
### 1. Add the package
|
|
90
106
|
|
|
91
107
|
```bash
|
|
92
|
-
pnpm add payload-canvas
|
|
108
|
+
pnpm add payload-canvas tailwindcss @tailwindcss/postcss postcss
|
|
93
109
|
```
|
|
94
110
|
|
|
95
|
-
With npm: `npm install payload-canvas
|
|
111
|
+
With npm: `npm install payload-canvas tailwindcss @tailwindcss/postcss postcss`.
|
|
96
112
|
|
|
97
113
|
### 2. Add a collection with pages
|
|
98
114
|
|
|
@@ -230,8 +246,7 @@ import type { ReactNode } from 'react'
|
|
|
230
246
|
// Your site's CSS: it holds every class Tailwind found in your files.
|
|
231
247
|
import '../(frontend)/globals.css'
|
|
232
248
|
|
|
233
|
-
export default
|
|
234
|
-
const payload = await getPayload({ config })
|
|
249
|
+
export default function CanvasLayout({ children }: { children: ReactNode }) {
|
|
235
250
|
return (
|
|
236
251
|
<html lang="en">
|
|
237
252
|
{/* The same body classes as your site layout. */}
|
|
@@ -239,7 +254,7 @@ export default async function CanvasLayout({ children }: { children: ReactNode }
|
|
|
239
254
|
{/* The Theme global's variables and fonts (React moves them into the head). `live` reloads
|
|
240
255
|
them after a theme save. Not in a <head> element: `live` adds a client component, and
|
|
241
256
|
Next's metadata then fails to hydrate on some loads. */}
|
|
242
|
-
<ThemeStyle payload={
|
|
257
|
+
<ThemeStyle payload={getPayload({ config })} live />
|
|
243
258
|
{children}
|
|
244
259
|
</body>
|
|
245
260
|
</html>
|
|
@@ -317,12 +332,12 @@ import type { ReactNode } from 'react'
|
|
|
317
332
|
|
|
318
333
|
import './globals.css'
|
|
319
334
|
|
|
320
|
-
export default
|
|
321
|
-
const payload = await getPayload({ config })
|
|
335
|
+
export default function RootLayout({ children }: { children: ReactNode }) {
|
|
322
336
|
return (
|
|
323
337
|
<html lang="en">
|
|
324
338
|
<head>
|
|
325
|
-
|
|
339
|
+
{/* The promise, not the instance: the read stays inside ThemeStyle's <Suspense> (Cache Components). */}
|
|
340
|
+
<ThemeStyle payload={getPayload({ config })} />
|
|
326
341
|
</head>
|
|
327
342
|
<body className="font-sans antialiased">{children}</body>
|
|
328
343
|
</html>
|
|
@@ -418,18 +433,21 @@ The builder is a full-screen admin view at `/admin/builder/<collection>/<id>`. I
|
|
|
418
433
|
How editors open it:
|
|
419
434
|
|
|
420
435
|
- the document's **Builder** tab (a link to the view),
|
|
421
|
-
- the **Open builder** button on the layout field in the normal Edit view (a new document must be saved first),
|
|
422
|
-
- the old tab URL `/admin/collections/<collection>/<id>/builder`, which redirects to the view
|
|
436
|
+
- the **Open builder** button on the layout field in the normal Edit view (a new document must be saved first). The field also shows "3 sections · 24 blocks" and the list of sections,
|
|
437
|
+
- the old tab URL `/admin/collections/<collection>/<id>/builder`, which redirects to the view,
|
|
438
|
+
- with `editor.openInBuilder: true`, a click on a saved document in the collection list.
|
|
439
|
+
|
|
440
|
+
**Open documents in the builder.** `websiteBuilder({ editor: { openInBuilder: true } })` (default `false`) makes the builder the document's main view. Opening a saved document goes straight to `/admin/builder/<collection>/<id>`. Payload's form stays for new documents until their first save, in drawers, for users who cannot save, for documents in the trash, and with `?form=1` in the URL. The builder's **All fields** menu item opens the form with `?form=1`. The form then stays for that document until a full page load, or until you open the builder for it again. The builder's back arrow goes to the collection list. A collection that sets its own `admin.components.views.edit.default` keeps it. The option registers `payload-canvas/client#DocumentEditView`, so run `pnpm payload generate:importmap` after you turn it on.
|
|
423
441
|
|
|
424
442
|
The top bar, left to right:
|
|
425
443
|
|
|
426
|
-
- **Back** to the document's Edit view, the admin icon (to the dashboard), and `Collection › Title`. Click the title to rename the document: Enter or leaving the field saves it (as a draft when the collection has drafts). Escape cancels.
|
|
444
|
+
- **Back** to the document's Edit view (to the collection list with `openInBuilder`), the admin icon (to the dashboard), and `Collection › Title`. Click the title to rename the document: Enter or leaving the field saves it (as a draft when the collection has drafts). Escape cancels.
|
|
427
445
|
- The status: **Draft** (never published), **Published**, or **Changed** (published, with newer draft changes). Hover it for the last change, the creation date, the last publish and the number of versions (opens the Versions drawer).
|
|
428
446
|
- Undo and redo, the canvas width and the active breakpoint. **Fluid** (the default) fills the space between the sidebars, so the breakpoint follows the free width. Desktop (1280 px), tablet, mobile and a custom width are fixed widths. In a template: the sample document the canvas previews.
|
|
429
447
|
- The people on the page, and the save state: **Saving…** while changes are on their way, then **Saved · 12:04**.
|
|
430
448
|
- **Preview** opens the draft preview (the collection's `admin.livePreview.url`, else `admin.preview`), or the public page (the plugin's `url` option), in a new tab.
|
|
431
449
|
- **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.
|
|
432
|
-
- 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),
|
|
450
|
+
- 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.
|
|
433
451
|
|
|
434
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.
|
|
435
453
|
|
|
@@ -441,7 +459,9 @@ Publishing. All editors of a document share one live session (see [Multiplayer e
|
|
|
441
459
|
|
|
442
460
|
Save rules. Every save checks the layout. A broken layout (wrong shape, duplicate ids, unknown block types, wrong prop types) blocks every save. Unfinished blocks do not block drafts, autosave or live sessions: a missing required prop, a prop whose value does not match its `builderFormat` (for example a half-typed video URL), a value outside the field's limits (`minLength`, `maxLength`, `min`, `max`, `minRows`, `maxRows`, an email address without a valid form), a message from the field's own `validate` function, a block in a slot that refuses it, and a binding the prop cannot use. All of these can be true while someone is still typing. They block **Publish** only, and the problem list names the block ("Video: this YouTube link does not point to a video", "Product: SKU: use a SKU like ABC-123"). Click a problem to select the block. See [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields).
|
|
443
461
|
|
|
444
|
-
Adding blocks on the canvas. Hover the canvas: a small **+** shows on the edge between two blocks next to the pointer (above or below in a column, left or right in a row), and in the middle of an empty container. Click it to open a picker with the blocks and sections that fit there (slot rules apply). Type to search, use the arrow keys and Enter, or click. The new block goes in exactly that place and is selected. The **+** hides while you drag and while you edit text on the canvas.
|
|
462
|
+
Adding blocks on the canvas. Hover the canvas: a small **+** shows on the edge between two blocks next to the pointer (above or below in a column, left or right in a row), and in the middle of an empty container. Click it to open a picker with the blocks and sections that fit there (slot rules apply). Type to search, use the arrow keys and Enter, or click. The new block goes in exactly that place and is selected. The **+** hides while you drag and while you edit text on the canvas. It does not show next to a small block (under 48 px along the list and under 160 px across, at 100 % zoom), and it never covers more than a fifth of a block: the parent gets the **+** instead. It also hides over the controls of interactive blocks (a carousel's arrows, a tab).
|
|
463
|
+
|
|
464
|
+
Interactive blocks on the canvas. Select a block inside a closed accordion item, a hidden tab, another slide or a closed popup, on the canvas or in Layers: the canvas opens the item, the tab or the popup, or moves to the slide, and scrolls the block into view. Arrows, dots, tab buttons and popup triggers work as on the site: a click on them selects nothing. Outlines of blocks inside a container that hides its overflow (a carousel's viewport) are cut at the container's edge.
|
|
445
465
|
|
|
446
466
|
Drag and drop. Drag a block by its row in the outline, by the grip on the selected block's bar, or from the **Blocks** and **Sections** tabs. Slot rules apply: a slot that refuses the block is never a target. Escape cancels the drag. One drop is one undo step, and collaborators see the move at once. There are two styles:
|
|
447
467
|
|
|
@@ -450,8 +470,46 @@ Drag and drop. Drag a block by its row in the outline, by the grip on the select
|
|
|
450
470
|
|
|
451
471
|
Set the default with `websiteBuilder({ editor: { dragMode: 'smooth' } })`. Each user can change it with the grip button in the canvas status bar, next to the zoom. The choice stays in that browser. When the system asks for less motion (`prefers-reduced-motion: reduce`), the editor always uses the drop line. Both styles use the same drop rules, so the same drop gives the same result. Smooth mode moves blocks with CSS transforms only and never changes the layout before the drop.
|
|
452
472
|
|
|
473
|
+
Drop outlines. While you drag, a thin dashed line marks every container on the canvas that takes the block, by the same slot rules. The container the block would drop into gets a stronger line, and its name when a drop line shows. The lines are drawn over the canvas, so the page never moves. Turn them off in the same grip menu (**Outline where blocks can drop**), or set the default with `websiteBuilder({ editor: { dropOutlines: false } })`.
|
|
474
|
+
|
|
453
475
|
Access. The view sends signed-out visitors to the login page and back. Users without admin access go to Payload's "unauthorized" page. A document that does not exist, or a collection without the builder, shows "not found". A user who can read but not update the document gets the normal Edit view.
|
|
454
476
|
|
|
477
|
+
### Content mode for clients
|
|
478
|
+
|
|
479
|
+
Content mode lets a site owner's client change text, images and links without breaking the design. Webflow's Editor and Elementor's role manager work the same way.
|
|
480
|
+
|
|
481
|
+
```ts
|
|
482
|
+
websiteBuilder({
|
|
483
|
+
editor: {
|
|
484
|
+
// Users with the "editor" role get content mode. Everyone else keeps full rights.
|
|
485
|
+
canEditDesign: ({ user }) => user?.role !== 'editor',
|
|
486
|
+
},
|
|
487
|
+
})
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
The default is `true` for everyone, so nothing changes until you set it. A function that throws counts as `false`. The starter adds a **Role** field (Admin or Editor) to its users and uses it here.
|
|
491
|
+
|
|
492
|
+
In content mode, editors can:
|
|
493
|
+
|
|
494
|
+
- change text, textarea, rich text, upload (image and video), email and link props in the inspector,
|
|
495
|
+
- edit text on the canvas,
|
|
496
|
+
- in a block marked **Editors can add, remove and reorder its items**: duplicate, delete and reorder its direct children (FAQ items, team cards). They cannot restyle them.
|
|
497
|
+
|
|
498
|
+
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
|
+
|
|
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.
|
|
501
|
+
|
|
502
|
+
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
|
+
|
|
504
|
+
```ts
|
|
505
|
+
{ name: 'anchor', type: 'text', admin: { custom: { builderContent: false } } }, // a setting, not text
|
|
506
|
+
{ name: 'badge', type: 'select', options: ['New', 'Sale'], admin: { custom: { builderContent: true } } },
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
Mark a list. Select the block that holds the items, open the **Advanced** tab and turn on **Editors can add, remove and reorder its items**. It is stored as `editableItems: true` on the block. A new item must be a copy of an item already there.
|
|
510
|
+
|
|
511
|
+
The server enforces it. Every write checks the change against the layout before it: the live editor's commits, the operations endpoint, the MCP tools, the AI assistant, editable class renames, and saves through REST, GraphQL or the Edit view. A design change from a user in content mode is refused with a 403 and a message such as `In content mode you can change only text, images and links. "Hero" cannot be moved.` The editable classes collection and the theme global are design too: content mode cannot create, update or delete them. Payload's **Restore** of a version is checked the same way: a version with another design is refused with `This version has a different design, so only a designer can restore it.`, and a version that differs only in content restores. (Payload's Restore button shows its own generic error; the API response carries the message.) Publishing, unpublishing and **Revert to published** stay allowed: they never bring back a design that is not already published.
|
|
512
|
+
|
|
455
513
|
## Inline editing
|
|
456
514
|
|
|
457
515
|
Text and images edit in place on the canvas, in every block: the default blocks, your own components, and existing Payload components adopted with `fromPayloadComponents`. You do not need to change your components.
|
|
@@ -528,6 +586,7 @@ websiteBuilder({
|
|
|
528
586
|
posts: { templates: true, url: (doc) => `/blog/${doc.slug}` },
|
|
529
587
|
},
|
|
530
588
|
blocks, // default: defaultBlocks()
|
|
589
|
+
listCollections: ['testimonials', 'team'], // more collections for the collection list block
|
|
531
590
|
sections, // ready-made sections for the library and AI tools
|
|
532
591
|
savedSections: { slug: 'builder-sections' }, // sections people save; `false` turns it off
|
|
533
592
|
css: {
|
|
@@ -535,11 +594,11 @@ websiteBuilder({
|
|
|
535
594
|
plugins: { '@tailwindcss/typography': typography },
|
|
536
595
|
},
|
|
537
596
|
canvasPath: '/builder-canvas',
|
|
538
|
-
templates: { slug: 'builder-templates' },
|
|
597
|
+
templates: { slug: 'builder-templates', admin: { group: 'Design' } },
|
|
539
598
|
live: { heartbeatMs: 15000 },
|
|
540
599
|
ai: { adapter: openRouterAdapter({ apiKey: process.env.OPENROUTER_API_KEY }) }, // the AI assistant
|
|
541
600
|
theme: { admin: { group: 'Settings' } }, // the Theme global; `false` leaves it out
|
|
542
|
-
editor: { dragMode: 'smooth' }, //
|
|
601
|
+
editor: { dragMode: 'smooth', openInBuilder: true }, // drag and drop style; open saved documents in the builder
|
|
543
602
|
references: { usedIn: ['media'], protectDelete: ['media'] }, // "Used in" lists; `false` turns them off
|
|
544
603
|
})
|
|
545
604
|
```
|
|
@@ -554,6 +613,7 @@ websiteBuilder({
|
|
|
554
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). |
|
|
555
614
|
| `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). |
|
|
556
615
|
| `blocks` | `BlockDefinition[]` | The blocks editors can use. Default `defaultBlocks()`. |
|
|
616
|
+
| `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`. |
|
|
557
617
|
| `sections` | `SectionDefinition[]` | Ready-made sections. See [Sections](#sections). |
|
|
558
618
|
| `savedSections` | `{ slug?, access?, admin?, hooks? } \| false` | The collection for sections people save in the editor. Default slug `builder-sections`; default access: every signed-in user. `false` turns it off. See [Saved sections](#saved-sections). |
|
|
559
619
|
| `css.entry` | `string` | Your Tailwind entry CSS, absolute or relative to `process.cwd()`. Required. |
|
|
@@ -561,13 +621,18 @@ websiteBuilder({
|
|
|
561
621
|
| `canvasPath` | `string` | The canvas route. Default `/builder-canvas`. |
|
|
562
622
|
| `templates.slug` | `string` | Slug of the templates collection. Default `builder-templates`. |
|
|
563
623
|
| `templates.hooks` | `CollectionConfig['hooks']` | Hooks for the templates collection, for example to revalidate pages. |
|
|
624
|
+
| `templates.admin` | `CollectionConfig['admin']` | Merged into the templates collection's `admin` options, for example `group` or `hidden`. |
|
|
564
625
|
| `live.heartbeatMs` | `number` | Interval of the keep-alive message on the live event stream. Default 10 s. |
|
|
565
626
|
| `multiplayer` | `boolean` | Deprecated, no effect. Several people can always edit a layout at once, and Payload's document lock stays on for the other fields. See [Multiplayer editing](#multiplayer-editing). |
|
|
566
627
|
| `ai` | `AiOptions` | Turns on the AI assistant in the editor. See [AI assistant](#ai-assistant). |
|
|
567
628
|
| `theme` | `ThemeOptions \| false` | The Theme global. On by default. `false` leaves it out. See [Theme](#theme). |
|
|
568
629
|
| `editor.dragMode` | `'indicator' \| 'smooth'` | The default drag and drop style. `indicator` (the default) shows a drop line; `smooth` lifts the block and moves the other blocks out of the way. Each user can change it in the editor. See [The builder view](#the-builder-view). |
|
|
630
|
+
| `editor.dropOutlines` | `boolean` | Thin outlines of every container that takes the dragged block, while you drag. Default `true`. Each user can change it in the editor. See [The builder view](#the-builder-view). |
|
|
631
|
+
| `editor.canEditDesign` | `({ req, user }) => boolean \| Promise<boolean>` | Who may change the design. Users for whom it returns `false` get content mode: text, images and links only. Default: everyone. See [Content mode for clients](#content-mode-for-clients). |
|
|
632
|
+
| `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). |
|
|
569
633
|
| `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. |
|
|
570
634
|
| `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). |
|
|
635
|
+
| `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). |
|
|
571
636
|
|
|
572
637
|
For each listed collection the plugin adds:
|
|
573
638
|
|
|
@@ -613,9 +678,9 @@ It also adds these endpoints (signed-in users only):
|
|
|
613
678
|
| `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). |
|
|
614
679
|
| `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). |
|
|
615
680
|
| `payload-canvas/live` | server | the live sessions and endpoints |
|
|
616
|
-
| `payload-canvas/client` | Payload import map only | admin client components (layout field, Builder tab) |
|
|
681
|
+
| `payload-canvas/client` | Payload import map only | admin client components (layout field, Builder tab, `DocumentEditView` for `openInBuilder`) |
|
|
617
682
|
| `payload-canvas/rsc` | Payload import map only | admin server components (the builder view, the tab redirect) |
|
|
618
|
-
| `payload-canvas/react` | your site and the canvas (server and client) | `RenderLayout`, `defaultComponents`, `fromPayloadComponent(s)`, `withPageData`, `renderOnServer`, `editableText`, `editableImage`, link helpers, `ThemeLive`, types |
|
|
683
|
+
| `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 |
|
|
619
684
|
| `payload-canvas/react/server` | server only | `loadLayoutData`, `loadTemplate`, `loadTheme`, `ThemeStyle`, `createCanvasServer` (they call Payload's Local API) |
|
|
620
685
|
| `payload-canvas/react/canvas` | client only | `BuilderCanvas`, the runtime for the editor's iframe |
|
|
621
686
|
| `payload-canvas/protocol`, `/css-browser` | used by `payload-canvas/react` | the editor–canvas message types, the in-browser CSS compiler. You do not import them yourself. |
|
|
@@ -635,6 +700,26 @@ Every entry point is ESM with `.d.ts` types. Client components keep their `'use
|
|
|
635
700
|
| `resolveLink` | `(link) => string \| null` | Turns links into an `href`. Default: the URL, or `/<slug>` for a loaded document. |
|
|
636
701
|
| `context` | `{ collection, doc }` | The document a template renders. See [Templates](#templates-and-binding). |
|
|
637
702
|
| `pageData` | `Record<string, unknown>` | Data the page loads once for its blocks. See [Page data](#page-data-and--block-context--components). |
|
|
703
|
+
| `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`. |
|
|
705
|
+
|
|
706
|
+
```tsx
|
|
707
|
+
import Link from 'next/link'
|
|
708
|
+
|
|
709
|
+
<RenderLayout layout={layout} blocks={blocks} components={components} linkComponent={Link} />
|
|
710
|
+
```
|
|
711
|
+
|
|
712
|
+
The interactive blocks (menu, carousel, popup, tabs, accordion, filter link) load their JavaScript only on pages that render them: their components load with `next/dynamic`. Do the same for a heavy client block of your own, in a `'use client'` module:
|
|
713
|
+
|
|
714
|
+
```tsx
|
|
715
|
+
'use client'
|
|
716
|
+
import dynamic from 'next/dynamic'
|
|
717
|
+
import { lazyBlock } from 'payload-canvas/react'
|
|
718
|
+
|
|
719
|
+
export const FormBlock = lazyBlock(dynamic(() => import('./Form').then((m) => m.FormBlock)))
|
|
720
|
+
```
|
|
721
|
+
|
|
722
|
+
`lazyBlock` gives the block its own Suspense boundary on the canvas, where it can mount after the page.
|
|
638
723
|
|
|
639
724
|
`loadLayoutData(layout, blocks, payload, options)` (from `payload-canvas/react/server`) loads the documents that upload and relationship props point to, in one `find` per collection. Options: `draft`, `context`, `resolveLink`.
|
|
640
725
|
|
|
@@ -663,12 +748,13 @@ type BlockComponentProps = {
|
|
|
663
748
|
className?: string
|
|
664
749
|
slots: Record<string, ReactNode> // rendered children per slot
|
|
665
750
|
attributes: Record<string, string> // spread on the root element
|
|
666
|
-
|
|
751
|
+
partAttributes: Record<string, Record<string, string>> // by slot or part name: spread on its element
|
|
667
752
|
mode: 'site' | 'canvas'
|
|
668
753
|
}
|
|
669
754
|
```
|
|
670
755
|
|
|
671
756
|
- Spread `attributes` on the root element. In the canvas it holds `data-block-id`, which the editor needs to select and measure the block.
|
|
757
|
+
- Spread `partAttributes[slot]` on the element that holds a slot's children. For a part (a slot with `styles: true`, or a name in `parts`) it also carries the part's `className` (see [Classes on inner elements](#classes-on-inner-elements)), so join it with any `className` you set on that element. Components written for 0.2 that read `slotAttributes` still work: it is the same object.
|
|
672
758
|
- Props are plain data. A component can be a client component (`'use client'`).
|
|
673
759
|
- Use one components map for the site and the canvas, in a file without server code:
|
|
674
760
|
|
|
@@ -687,9 +773,36 @@ export const components: BlockComponents = { pricingTable: PricingTable }
|
|
|
687
773
|
|
|
688
774
|
`BuilderCanvas` takes the same `blocks`, `components` and `resolveLink` as `RenderLayout`. It also takes `plugins` (your Tailwind plugins map, see [Styling](#styling)) and `server` (a server action made with `createCanvasServer`, see [Server components in the canvas](#server-components-in-the-canvas)).
|
|
689
775
|
|
|
776
|
+
### Cache Components
|
|
777
|
+
|
|
778
|
+
With Next's Cache Components (`cacheComponents: true` in `next.config`), a route fails to build when a component reads data outside `<Suspense>` and outside `'use cache'`. The plugin's server parts work with it:
|
|
779
|
+
|
|
780
|
+
- **`ThemeStyle`** reads the Theme global inside its own `<Suspense>` boundary (fallback: nothing). It works as it is, in the `<head>` too, and the theme streams in with the dynamic part of the page. Pass `payload={getPayload({ config })}` (the promise), not an instance you awaited in the layout: a layout that awaits `getPayload` connects to the database outside any boundary, and the route fails. To put it in the static shell, render it inside your own cached component. The plugin clears the theme's cache tag (`theme.cacheTag`, default the slug `theme-settings`) after each theme save:
|
|
781
|
+
|
|
782
|
+
```tsx
|
|
783
|
+
// src/components/SiteTheme.tsx
|
|
784
|
+
import config from '@payload-config'
|
|
785
|
+
import { cacheTag } from 'next/cache'
|
|
786
|
+
import { getPayload } from 'payload'
|
|
787
|
+
import { DEFAULT_THEME_SLUG } from 'payload-canvas'
|
|
788
|
+
import { ThemeStyle } from 'payload-canvas/react/server'
|
|
789
|
+
|
|
790
|
+
export async function SiteTheme() {
|
|
791
|
+
'use cache'
|
|
792
|
+
cacheTag(DEFAULT_THEME_SLUG)
|
|
793
|
+
const payload = await getPayload({ config })
|
|
794
|
+
return <ThemeStyle payload={payload} />
|
|
795
|
+
}
|
|
796
|
+
```
|
|
797
|
+
|
|
798
|
+
Put `<SiteTheme />` in the root layout's `<head>`. In the canvas layout, keep `<ThemeStyle payload={getPayload({ config })} live />` uncached, so the editor sees each save at once.
|
|
799
|
+
- **`loadLayoutData`, `loadTemplate` and `compilePageCss`** are functions that read Payload. Call them inside your own `'use cache'` function (with `cacheTag` and a revalidate hook on the collection) or in a component under `<Suspense>`. Draft mode and `searchParams` (collection list filters and pages) are request data: read them under `<Suspense>`, not in a cached function.
|
|
800
|
+
- **The canvas route** only renders `BuilderCanvas` (a client component). Its server action runs per request, so it needs nothing.
|
|
801
|
+
- **The admin.** Payload's admin layout reads the session on every request. Add `export const instant = false` to `src/app/(payload)/layout.tsx`, so the admin stays a request-time route.
|
|
802
|
+
|
|
690
803
|
## Server components in the canvas
|
|
691
804
|
|
|
692
|
-
Some block components load their own data: a model grid that calls `payload.find`, a review carousel, a blog listing, a FAQ from a collection. They are async server components, and they import Payload and your config. The canvas iframe is a client page, so it cannot import them. The canvas sends these blocks to a server action in the canvas route instead. The action renders them with your site's components and sends back the result as React Server Component output. Client components inside it (a carousel, a
|
|
805
|
+
Some block components load their own data: a model grid that calls `payload.find`, a review carousel, a blog listing, a FAQ from a collection. They are async server components, and they import Payload and your config. The canvas iframe is a client page, so it cannot import them. The canvas sends these blocks to a server action in the canvas route instead. The action renders them with your site's components and sends back the result as React Server Component output. Client components inside it (a carousel, a popup) work in the canvas as on the site. You do not change your components.
|
|
693
806
|
|
|
694
807
|
You keep two component maps:
|
|
695
808
|
|
|
@@ -741,7 +854,7 @@ How it works in the editor:
|
|
|
741
854
|
|
|
742
855
|
- The first render shows a gray box with the block's name. Then the server output shows.
|
|
743
856
|
- After a change to the block (its props, its classes or its children), the canvas asks again 250 ms after the last change, and at the latest after 1 s. The changes of several blocks go in one request, because Next runs server actions one at a time. The old output stays on the screen until the new one is ready. It dims only when the answer takes longer than 300 ms.
|
|
744
|
-
- The canvas keeps the results by the block's content, so undo shows the earlier output at once. A block that did not change never asks again while the editor is open. Data that changes somewhere else (a new post) shows when you open the editor again.
|
|
857
|
+
- The canvas keeps the results by the block's content, so undo shows the earlier output at once. A block that did not change never asks again while the editor is open. Animation settings are not part of the content: the canvas puts them on the output itself, so the Motion tab never asks the server. When the editor saves a document (an image's alt text), the server blocks on screen ask again and keep their output meanwhile. Data that changes somewhere else (a new post) shows when you open the editor again.
|
|
745
858
|
- The data loads as on the site (`loadLayoutData`): the latest drafts, uploads and relationships one level deep, and the user's access for collection lists. In a template, bindings use the sample document.
|
|
746
859
|
- Only signed-in users of the admin collection get an answer.
|
|
747
860
|
- When a component fails, that block shows "Name: the preview failed" with the error. The other blocks are not affected.
|
|
@@ -911,6 +1024,7 @@ import { defaultBlocks, defineBlock, linkField } from 'payload-canvas/blocks'
|
|
|
911
1024
|
export const pricingTable = defineBlock({
|
|
912
1025
|
type: 'pricingTable',
|
|
913
1026
|
label: 'Pricing table',
|
|
1027
|
+
description: 'A price card with a button.', // the block library's tooltip, for editors
|
|
914
1028
|
icon: 'grid', // a name from the editor's icon set; unknown names get a generic icon
|
|
915
1029
|
category: 'Marketing', // group in the block library
|
|
916
1030
|
fields: [
|
|
@@ -930,16 +1044,103 @@ export const pricingTable = defineBlock({
|
|
|
930
1044
|
export const blocks = [...defaultBlocks({ linkCollections: ['pages'] }), pricingTable]
|
|
931
1045
|
```
|
|
932
1046
|
|
|
1047
|
+
- `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`.
|
|
933
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.
|
|
934
|
-
- `
|
|
1049
|
+
- `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`.
|
|
1050
|
+
- `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.
|
|
935
1051
|
- `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.
|
|
936
1052
|
- 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
|
+
- `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).
|
|
937
1054
|
- `admin.custom.builderFormat` on a `text` field names a value check, for example `custom: { builderFormat: 'videoUrl' }` (the Video block's URL). The inspector shows the message while the user types, and a bad value blocks **Publish** but not draft saves. `videoUrl` is the only built-in format. Formats live in a registry in `payload-canvas/core` (`FORMATS`, `formatProblem`). The renderer can use the same parser (`parseVideoUrl`).
|
|
938
1055
|
- `linkField()` stores `{ type, url, reference, newTab }`. The component receives it resolved, with `href`, `target` and `rel`.
|
|
939
|
-
- The default blocks are `stack`, `grid`, `heading`, `text`, `richText`, `image`, `video`, `button`, `link`, `menu`, `list` with its `listItem` blocks, `
|
|
940
|
-
-
|
|
1056
|
+
- The 15 default blocks are `stack`, `grid`, `heading`, `text`, `richText`, `image`, `video`, `button`, `link`, `menu`, `list` with its `listItem` blocks, `divider`, `collectionList` (documents from a collection), `field` (a field of the document a template renders) and `repeat` (the rows of an array or hasMany field of that document).
|
|
1057
|
+
- 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
|
+
- Props worth knowing on the default blocks:
|
|
1059
|
+
- `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.
|
|
1060
|
+
- `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
|
+
- `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
|
+
- 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.
|
|
1063
|
+
- A `menu` item can have `children`: one level of links (`label`, `link`) in a dropdown. The item's own link is optional. With a link, the item shows the link and a small arrow toggle beside it, which screen readers hear as `submenuLabel` (default "{label} menu", localized). Without a link, the label is the toggle. The dropdown is a native `<details>`: Enter and Space open it, Escape closes it and returns the focus to the toggle, and it closes when the focus or a click leaves it. Opening one closes the others. A current child gets `aria-current="page"` and its parent `aria-current="true"`. In the small-screen panel the children show as a nested list. Its classes are in `MENU_CLASS_MAP` (`submenu`, `submenuToggle`, `submenuList`, `submenuLink`, `panelSubList`, `panelSubLink`); restyle them from the menu's `className`, for example `[&_li>details>ul]:rounded-lg`. Items without children render as before.
|
|
941
1064
|
- The `field` block renders rich text with the `prose` typography (and `max-w-none`) when its own `className` has no `prose` class. Add `prose prose-lg` or another `prose` class to take control.
|
|
942
|
-
-
|
|
1065
|
+
- `field` `path` takes a binding formatter after a `|` (see "Binding syntax"): `price|currency:EUR` gives `€1,200`, `publishedAt|date:en-GB` a date in that language, `content|readingTime` gives `5 min read`. The inspector edits it with the **Format** select under the field. `formatBindingValue(value, "currency:EUR")` in `payload-canvas/core` formats a value the same way.
|
|
1066
|
+
- `field` and `richText` give each rich-text heading an `id` from its text, for `#id` links and the [table of contents](#table-of-contents): `headingId('Über uns & Preise')` is `uber-uns-preise`. A repeated text gets `-2`, `-3`, and a heading without letters or digits gets `section`. `richTextHeadings(value)` in `payload-canvas/core` lists the headings with the same ids (`{ id, text, level, node }`). Two rich texts on one page with the same heading text give two elements the same id; the first one wins a `#id` link.
|
|
1067
|
+
- A list holds its items as `listItem` blocks in its `items` slot, so each item can be selected, dragged, styled and edited on the canvas. Enter at the end of an item adds the next one; Backspace at the start of an item joins it to the one before. Older layouts stored the items as a prop (`props.items: [{ text }]`). `normalizeLayout` turns them into `listItem` blocks when a layout loads, and the List component still renders the old prop until the layout is saved again. A list whose `items` prop is bound to document data keeps the old form. A `listItem` takes an optional `link` (the same link group as `button`): the item renders as `<li><a href>text</a></li>`, and the text stays editable in place. Do not set it on items of a list inside a `link` block, because a link cannot hold another link; the item's link is a prop, so the link block's type rules do not catch it.
|
|
1068
|
+
|
|
1069
|
+
### Where a block renders: `useCanvasMode()`
|
|
1070
|
+
|
|
1071
|
+
A block component can render differently in the editor. `useCanvasMode()` from `payload-canvas/react` tells a client component where it renders:
|
|
1072
|
+
|
|
1073
|
+
- `'site'`: the live website. This is the value on any page without the canvas.
|
|
1074
|
+
- `'canvas'`: the editor's canvas iframe.
|
|
1075
|
+
- `'thumbnail'`: the hidden canvas that takes the pictures of the section library.
|
|
1076
|
+
|
|
1077
|
+
Use it to keep heavy work out of the editor. This 3D block shows a still poster in a thumbnail, and pauses its animation loop on the canvas:
|
|
1078
|
+
|
|
1079
|
+
```tsx
|
|
1080
|
+
'use client'
|
|
1081
|
+
import { useEffect, useRef } from 'react'
|
|
1082
|
+
import { useCanvasMode, type BlockComponentProps } from 'payload-canvas/react'
|
|
1083
|
+
import { startScene } from '@/lib/scene' // your WebGL code: returns { pause(), resume(), dispose() }
|
|
1084
|
+
|
|
1085
|
+
export function ProductScene({ props, className, attributes }: BlockComponentProps) {
|
|
1086
|
+
const mode = useCanvasMode()
|
|
1087
|
+
const canvasRef = useRef<HTMLCanvasElement>(null)
|
|
1088
|
+
const poster = (props.poster as { url?: string } | undefined)?.url
|
|
1089
|
+
|
|
1090
|
+
useEffect(() => {
|
|
1091
|
+
if (mode === 'thumbnail' || !canvasRef.current) return
|
|
1092
|
+
const scene = startScene(canvasRef.current)
|
|
1093
|
+
// On the canvas the scene draws one frame and stops, so the editor stays fast.
|
|
1094
|
+
if (mode === 'canvas') scene.pause()
|
|
1095
|
+
return () => scene.dispose()
|
|
1096
|
+
}, [mode])
|
|
1097
|
+
|
|
1098
|
+
if (mode === 'thumbnail') return <img {...attributes} className={className} src={poster} alt="" />
|
|
1099
|
+
return <canvas {...attributes} ref={canvasRef} className={className} />
|
|
1100
|
+
}
|
|
1101
|
+
```
|
|
1102
|
+
|
|
1103
|
+
A server component cannot call hooks. When the canvas renders a block on the server (see [Server components in the canvas](#server-components-in-the-canvas)), the component gets the same value as its `canvasMode` prop: `'canvas'` or `'thumbnail'`. On the site the prop is missing. A component made with `fromPayloadComponent` gets it as `builder.canvasMode`, so a `{ block, context }` component can pass it on: `props: (block, context, builder) => ({ block, context: { ...context, mode: builder.canvasMode ?? 'site' } })`. Client components inside a server block call `useCanvasMode()` as usual.
|
|
1104
|
+
|
|
1105
|
+
### Interactive blocks on the canvas
|
|
1106
|
+
|
|
1107
|
+
A tab, a slide or a popup keeps some content out of view. On the canvas, an editor must still reach that content, and must still use the block's buttons. `payload-canvas/react` has three tools for this:
|
|
1108
|
+
|
|
1109
|
+
- `useCanvasReveal(ref, onReveal)`: calls `onReveal(target)` when the editor selects a block inside the element of `ref` (on the canvas or in Layers), or that element itself. Show the hidden part there: open the item, scroll to the slide, pick the tab. Only the canvas sends the event, so on the site it never fires.
|
|
1110
|
+
- `REVEAL_EVENT` (`'builder:reveal'`): the DOM event behind the hook. The canvas sends it from the selected block's element, and it bubbles. Listen for it yourself in code that is not a React component.
|
|
1111
|
+
- `CANVAS_CONTROL_ATTRIBUTE` (`'data-builder-control'`): put it on the block's controls (arrows, dots, tab buttons, a close button). On the canvas a click on such an element works as on the site and selects nothing. The hover outline and the "+" do not show over it.
|
|
1112
|
+
|
|
1113
|
+
What the canvas does when a block is selected: it opens every closed `<details>` around the block, sends the reveal event from the block's element, and after two animation frames scrolls the block into view. When the selection is cleared (Escape), it sends the reveal event from `<html>`, outside every block, so a box that closes when the editor selects something outside it closes then too. So a native `<details>` needs no code. A block that moves its content with CSS transforms (a slider) can send `element.dispatchEvent(new Event('scroll'))` after each move, so the canvas measures the block outlines again.
|
|
1114
|
+
|
|
1115
|
+
A "Read more" block that hides part of its content:
|
|
1116
|
+
|
|
1117
|
+
```tsx
|
|
1118
|
+
'use client'
|
|
1119
|
+
import { useRef, useState } from 'react'
|
|
1120
|
+
import { CANVAS_CONTROL_ATTRIBUTE, useCanvasReveal, type BlockComponentProps } from 'payload-canvas/react'
|
|
1121
|
+
|
|
1122
|
+
const CONTROL = { [CANVAS_CONTROL_ATTRIBUTE]: '' }
|
|
1123
|
+
|
|
1124
|
+
export function ReadMore({ attributes, className, partAttributes, slots }: BlockComponentProps) {
|
|
1125
|
+
const root = useRef<HTMLDivElement>(null)
|
|
1126
|
+
const [open, setOpen] = useState(false)
|
|
1127
|
+
// The editor selected the block or a block in its hidden part: show it.
|
|
1128
|
+
useCanvasReveal(root, () => setOpen(true))
|
|
1129
|
+
return (
|
|
1130
|
+
<div {...attributes} ref={root} className={className}>
|
|
1131
|
+
<div {...partAttributes.more} hidden={!open}>{slots.more}</div>
|
|
1132
|
+
{/* On the canvas the button opens and closes the part, as on the site. */}
|
|
1133
|
+
<button {...CONTROL} type="button" aria-expanded={open} onClick={() => setOpen(!open)}>
|
|
1134
|
+
{open ? 'Show less' : 'Read more'}
|
|
1135
|
+
</button>
|
|
1136
|
+
</div>
|
|
1137
|
+
)
|
|
1138
|
+
}
|
|
1139
|
+
```
|
|
1140
|
+
|
|
1141
|
+
The built-in carousel, popup and tabs use the hook and mark their controls. The disclosure and the accordion are native `<details>`, so the canvas opens them by itself.
|
|
1142
|
+
|
|
1143
|
+
A box that shows over the page on the canvas (an open popover, such as the built-in popup) is a layer. The canvas measures each one (`CanvasMeasurement.layers`) and marks the blocks inside it. Over a layer, the hover outline, selection, the "+" and drops reach only the layer's blocks, never the page under it. A click on the layer's padding selects its block. A click on its backdrop works as on the site and selects nothing. `reachableAt(measurement, point)` in `payload-canvas/core` gives the blocks and slots a point can reach.
|
|
943
1144
|
|
|
944
1145
|
### Validation, hooks and access on block fields
|
|
945
1146
|
|
|
@@ -987,6 +1188,195 @@ Limits:
|
|
|
987
1188
|
- Saved sections (`builder-sections`) store blocks without running their field hooks.
|
|
988
1189
|
- `migrateBlocksField` writes through the database adapter, so no hooks run. The values come from the old field, where Payload already ran the hooks.
|
|
989
1190
|
|
|
1191
|
+
### Built-in blocks
|
|
1192
|
+
|
|
1193
|
+
Some blocks most sites need come with the plugin, but they are off until you add them: `icon`, `disclosure`, `accordion`, `popup`, `tabs` (with its `tab` blocks), `carousel`, `marquee`, `tableOfContents`, `filterLink`, `adjacentLinks` (previous / next) and `embed` (custom HTML). (The live saved section block, `sectionRef`, is not one of them: the plugin adds it, see [Live saved sections](#live-saved-sections-sectionref).) Add the definitions next to `defaultBlocks()`, and the components next to yours:
|
|
1194
|
+
|
|
1195
|
+
```ts
|
|
1196
|
+
// src/builder.ts
|
|
1197
|
+
import { builtinBlocks, defaultBlocks } from 'payload-canvas/blocks'
|
|
1198
|
+
import { ICON_NAMES } from './icons/names'
|
|
1199
|
+
|
|
1200
|
+
export const blocks = [
|
|
1201
|
+
...defaultBlocks({ mediaCollection: 'media' }),
|
|
1202
|
+
...builtinBlocks({ include: ['icon', 'carousel', 'popup'], icons: ICON_NAMES }),
|
|
1203
|
+
]
|
|
1204
|
+
```
|
|
1205
|
+
|
|
1206
|
+
```tsx
|
|
1207
|
+
// src/components/blocks.ts
|
|
1208
|
+
import { builtinComponents, type BlockComponents } from 'payload-canvas/react'
|
|
1209
|
+
import { icons } from './icons'
|
|
1210
|
+
|
|
1211
|
+
// Call it once, at module level.
|
|
1212
|
+
export const components: BlockComponents = { ...builtinComponents({ icons, labels }), pricingTable: PricingTable }
|
|
1213
|
+
```
|
|
1214
|
+
|
|
1215
|
+
- Without `include`, `builtinBlocks()` adds all of them (`icon` only when you give `icons`, `embed` only when you give `embed`).
|
|
1216
|
+
- The MCP tools and the AI assistant read the same `blocks` list, so they see each built-in you include, with its description and example.
|
|
1217
|
+
- 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
|
+
- **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
|
+
- `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`.
|
|
1221
|
+
|
|
1222
|
+
#### Labels
|
|
1223
|
+
|
|
1224
|
+
The carousel, popup, tabs, table of contents, previous / next and menu have labels: the text of their controls and their names for screen readers ("Next slide", "Close", "Tab {n}", "On this page", "Previous and next", "Menu"). A new block stores none of them. An empty label uses the site's label, else the English one, which the empty input shows as its placeholder. Set the site's labels once, for example in its language:
|
|
1225
|
+
|
|
1226
|
+
```ts
|
|
1227
|
+
const labels = {
|
|
1228
|
+
carousel: { label: 'Karussell', previousLabel: 'Vorherige Folie', nextLabel: 'Nächste Folie', dotLabel: 'Folie {n}' },
|
|
1229
|
+
popup: { closeLabel: 'Schließen' },
|
|
1230
|
+
tabs: { tabLabel: 'Reiter {n}' },
|
|
1231
|
+
tableOfContents: { label: 'Auf dieser Seite' },
|
|
1232
|
+
adjacentLinks: { label: 'Vorheriger und nächster Beitrag' },
|
|
1233
|
+
menu: { label: 'Hauptmenü', toggleLabel: 'Menü', submenuLabel: 'Untermenü {label}' },
|
|
1234
|
+
} satisfies BuiltinLabels
|
|
1235
|
+
builtinComponents({ labels })
|
|
1236
|
+
```
|
|
1237
|
+
|
|
1238
|
+
- One block can still have its own label: type it in the block's props (under **Labels** for control labels). Label props are localized.
|
|
1239
|
+
- With `menu` labels, the map also holds a `menu` component (the default menu with those labels). A `menu` component of yours that comes after it in the map wins.
|
|
1240
|
+
- The English defaults are exported: `CAROUSEL_LABELS`, `POPUP_LABELS`, `TABS_LABELS`, `TABLE_OF_CONTENTS_LABELS`, `ADJACENT_LINKS_LABELS` and `MENU_LABELS` from `payload-canvas/blocks`.
|
|
1241
|
+
|
|
1242
|
+
#### Icon
|
|
1243
|
+
|
|
1244
|
+
`icon` draws one icon of your own icon set. `builtinBlocks({ icons })` takes the names as plain strings, so `payload.config.ts` loads no React. `builtinComponents({ icons })` takes the components by the same names. Let TypeScript check that both lists match:
|
|
1245
|
+
|
|
1246
|
+
```ts
|
|
1247
|
+
// src/icons/names.ts (no React here)
|
|
1248
|
+
export const ICON_NAMES = ['arrowRight', 'check', 'close'] as const
|
|
1249
|
+
|
|
1250
|
+
// src/icons/index.ts
|
|
1251
|
+
import type { IconMap } from 'payload-canvas/react'
|
|
1252
|
+
export const icons = { arrowRight: ArrowRight, check: Check, close: Close } satisfies IconMap<(typeof ICON_NAMES)[number]>
|
|
1253
|
+
```
|
|
1254
|
+
|
|
1255
|
+
- Props: `name` (one of the names) and `label`. Without a label the icon is decoration (`aria-hidden="true"`). With a label it is an image (`role="img"`, `aria-label`).
|
|
1256
|
+
- Each icon component gets `className`, the ARIA attributes and, on the canvas, the editor attributes. Spread its props on the `<svg>`.
|
|
1257
|
+
- An unknown name renders nothing on the site and a note on the canvas.
|
|
1258
|
+
|
|
1259
|
+
**A button with an icon.** Put a `text` block and an `icon` block in a `link` block. An icon is an inline block, so it may go straight into a link. Give the link the button's classes (`inline-flex items-center gap-2 rounded-md bg-primary px-4 py-2`). The `button` block has no icon props.
|
|
1260
|
+
|
|
1261
|
+
|
|
1262
|
+
#### Disclosure and accordion
|
|
1263
|
+
|
|
1264
|
+
`disclosure` is one show/hide item: a native `<details>` with a `summary` slot (always visible) and a `content` slot. It opens with the mouse and the keyboard without script, and the closed content stays in the HTML for search engines. `accordion` is a list of disclosures in its `items` slot (also a `repeat` or `collectionList` of disclosures). Include both: `include: ['disclosure', 'accordion']`.
|
|
1265
|
+
|
|
1266
|
+
- `disclosure` props: `open` (open at first) and `animate` (the content grows and fades in, in 200 ms, in CSS only; off with reduced motion, and in browsers without `::details-content`).
|
|
1267
|
+
- On the canvas it starts open or closed as on the site. A click on the title opens or closes it, a double-click edits the title text, and selecting a block inside opens it.
|
|
1268
|
+
- The summary slot refuses links, buttons and other controls: a `<summary>` is the button.
|
|
1269
|
+
- Style the summary row with `[&>summary]:` classes and the content with `[&>div]:` classes on the disclosure. `open:` and `group-open:` classes style the open state, for example `group-open:rotate-45` on an icon in the summary.
|
|
1270
|
+
- `accordion` props: `multiple` (default on; off keeps one item open, with the browser's exclusive `<details name>`) and `faqSchema`, **Mark up as FAQ for search engines** (default off). Turn it on only for real questions and answers: search engines treat FAQ markup on other content as spam.
|
|
1271
|
+
- FAQPage JSON-LD: `RenderLayout` outputs it on the site by itself. When an accordion in the layout has `faqSchema` on, the layout renders one `<script type="application/ld+json">` with the questions (summary text) and answers (content text), with `<` escaped. Bound props, `field` blocks, repeats and collection lists give the document's values. Nothing is output on the canvas, or when no accordion opts in.
|
|
1272
|
+
- `<RenderLayout faqJsonLd={false} />` turns it off, for a site that writes its own. `faqItems(layout, blocks)` and `faqJsonLd(items)` from `payload-canvas/blocks` build the same data, for example to merge the FAQs of several layouts into one script:
|
|
1273
|
+
|
|
1274
|
+
```tsx
|
|
1275
|
+
const items = [layout, templateLayout].flatMap((value) => faqItems(value, blocks))
|
|
1276
|
+
const jsonLd = faqJsonLd(items)
|
|
1277
|
+
// <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd).replace(/</g, '\\u003c') }} />
|
|
1278
|
+
// and <RenderLayout faqJsonLd={false} … /> for those layouts
|
|
1279
|
+
```
|
|
1280
|
+
|
|
1281
|
+
#### Popup
|
|
1282
|
+
|
|
1283
|
+
`popup` is a button that opens a box over the page: a video, a large photo, a form. Its `trigger` slot is what the visitor clicks (a text, an icon, a small image). Its `content` slot is the box. The content stays in the HTML for search engines.
|
|
1284
|
+
|
|
1285
|
+
- The box is a native modal `<dialog>`. It keeps the focus inside and makes the page inert. Escape, the close button and a click beside the box close it, and the page does not scroll while it is open.
|
|
1286
|
+
- The trigger renders inside a `<button>`, so its slot refuses links, buttons, other controls, popups and tabs.
|
|
1287
|
+
- Props: `label` (the box's name for screen readers; empty: the first heading in the content) and `anchor`. With `anchor: 'newsletter'`, every link to `#newsletter` on the page opens the popup, and so does a page address that ends in `#newsletter`. With an anchor the trigger may stay empty: the site then renders no button.
|
|
1288
|
+
- Parts: the `trigger` and `content` slots, `panel` (the dialog box; `backdrop:` classes colour the backdrop, for example `backdrop:bg-black/60`) and `close` (the close button, placed absolutely in the panel). A new popup starts with a centred panel that fades and grows in (150 ms, `starting:opacity-0 starting:scale-95`; not with reduced motion) and a round close button.
|
|
1289
|
+
- **A photo that opens large.** Put a small image in the trigger and the large image in the content. Give the panel `max-w-5xl p-0` and the content `gap-0`.
|
|
1290
|
+
- On the canvas the box shows as on the site: centred over the page, with its backdrop. It opens when you click the trigger, or when you select the popup or a block inside it (on the canvas or in **Layers**). It is not modal: you select and edit the blocks in it as anywhere else, and a click on the box's padding selects the popup. Escape, the close button, a click on the backdrop and selecting a block outside it close it.
|
|
1291
|
+
- Control label, under **Labels** in the Content tab: `closeLabel` ("Close"). An empty label uses the site's label or the English one (see [Labels](#labels)).
|
|
1292
|
+
|
|
1293
|
+
#### Tabs
|
|
1294
|
+
|
|
1295
|
+
`tabs` shows one row of tab names and one panel at a time. Its `tabs` slot takes only `tab` blocks, at least two. A new tabs block starts with two. Each `tab` has a `label` (the tab name) and a `content` slot (its panel). Include `tabs`: it brings the `tab` block with it.
|
|
1296
|
+
|
|
1297
|
+
- The first tab is open at first. It follows the WAI-ARIA tabs pattern: the arrow keys move between tabs (and wrap), Home and End jump to the first and last tab, and only the open tab is in the Tab order. Hidden panels stay in the HTML with `hidden`.
|
|
1298
|
+
- Props: `label` (the tab row's name for screen readers) and `vertical` (the tabs stand in a column; the up and down arrows move). For a column, lay out the block with `flex flex-row gap-8` and give the `list` part `flex flex-col`.
|
|
1299
|
+
- Parts: `list` (the row of tabs), `tab` (each tab button) and `panel` (each panel). The open tab has `aria-selected="true"`, so `aria-selected:` classes style it: a new tabs block starts with `aria-selected:border-current aria-selected:opacity-100`. A `tab` block's own `className` styles its own panel.
|
|
1300
|
+
- The panel that becomes visible fades in: a new tabs block's `panel` part starts with `transition-opacity duration-150 ease-out starting:opacity-0 motion-reduce:transition-none`. Change or remove those classes in the Styles panel.
|
|
1301
|
+
- On the canvas a click on a tab opens it, and selecting a block opens the tab that holds it.
|
|
1302
|
+
- Control label: `tabLabel` ("Tab {n}"), the name of a tab without a label. `{n}` is the tab number.
|
|
1303
|
+
|
|
1304
|
+
#### Embed
|
|
1305
|
+
|
|
1306
|
+
`embed` holds custom HTML: a booking widget, a map, a newsletter form from another service. It is off until you turn it on, because its code runs on your site:
|
|
1307
|
+
|
|
1308
|
+
```ts
|
|
1309
|
+
builtinBlocks({ embed: {} }) // or include: [..., 'embed']
|
|
1310
|
+
// Only admins may change the code and the mode:
|
|
1311
|
+
builtinBlocks({ embed: { canEdit: ({ req }) => req.user?.role === 'admin' } })
|
|
1312
|
+
```
|
|
1313
|
+
|
|
1314
|
+
- Props: `code` (HTML, edited in Payload's code editor), `mode` and `title`.
|
|
1315
|
+
- `mode: 'inline'` (**In the page**, the default) puts the HTML in the page. Its `<script>` tags run once the page loads: the browser runs those of the server's HTML, and the block runs them again after a page change in the app (it copies each script, so external scripts keep their order). This JavaScript loads only on pages with an inline embed.
|
|
1316
|
+
- `mode: 'isolated'` (**In its own frame**) shows the HTML in a sandboxed `<iframe srcdoc>`. Scripts, forms and links to new tabs work, but the code cannot reach your page or the visitor's session (no `allow-same-origin`). A frame does not grow with its content: give the block a height, for example `h-96` or `aspect-video`. `title` is the frame's name for screen readers (empty: "Embedded content", or the site's label `builtinComponents({ labels: { embed: { title } } })`).
|
|
1317
|
+
- The editor never runs the code. The canvas shows it in a frame with scripts off, with the page's styles for inline code. Empty code, or code with nothing to see (only scripts), shows a "Custom code" box.
|
|
1318
|
+
- Access: `embed.canEdit` is a Payload field access function on `code` and `mode` (as `access.create` and `access.update`). Default: everyone who may edit the document may change them. Users without it see the code read-only. MCP agents and the AI assistant act as their user, so the same rule applies to them. See [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields).
|
|
1319
|
+
- `embed.maxLength`: the longest code, in characters. Default 50,000 (`EMBED_MAX_LENGTH`). Longer code blocks **Publish**.
|
|
1320
|
+
|
|
1321
|
+
|
|
1322
|
+
#### Carousel
|
|
1323
|
+
|
|
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.
|
|
1325
|
+
|
|
1326
|
+
- Visitors swipe or drag the slides, click the arrows or dots, or use the arrow keys when the carousel has the focus.
|
|
1327
|
+
- 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").
|
|
1328
|
+
- Dots: one per stop, not one per slide. When two slides show at once, six slides have three dots.
|
|
1329
|
+
- The optional `previous` and `next` slots hold the content of the arrow buttons, for example an `icon` block. Empty, they show a chevron.
|
|
1330
|
+
- Accessibility: the carousel is a `<section>` region with `aria-roledescription="carousel"` and its label. Each slide is a group labelled "2 of 6". The viewport takes the keyboard focus. The track announces slide changes (`aria-live="polite"`) unless autoplay is running.
|
|
1331
|
+
- Autoplay shows a Pause button (WCAG 2.2.2). It pauses while the pointer is over the carousel and while it has the focus, stops when the visitor swipes, and never runs when the visitor asks for less motion.
|
|
1332
|
+
- Style the inner elements as parts (`partClassName`, the **Style target** select): `slides` for the track (the gap between slides), `arrow` for both arrows (`disabled:` at either end without `loop`), `dot` for each dot (the current dot has `aria-current="true"`; its visible mark is its `::after`), `controls` for the row of controls and `pause` for the pause button. A new carousel starts with round bordered arrows and small round dots, in the text colour.
|
|
1333
|
+
- Control labels, under **Labels** in the Content tab: `previousLabel` ("Previous slide"), `nextLabel` ("Next slide"), `pauseLabel` ("Pause"), `playLabel` ("Play"), `dotLabel` ("Slide {n}"), `slideLabel` ("{n} of {count}") and the `aria-roledescription` names `carouselRole` ("carousel") and `slideRole` ("slide"). `{n}` is the slide number and `{count}` the number of slides. An empty label uses the site's label or the English one (see [Labels](#labels)).
|
|
1334
|
+
- On the canvas the arrows and dots work, the slides do not drag (you drag blocks there), fade shows as sliding, and autoplay is off. Selecting a block in a slide moves the carousel to that slide.
|
|
1335
|
+
- Carousels saved before the move to Embla render as they are.
|
|
1336
|
+
|
|
1337
|
+
#### Marquee
|
|
1338
|
+
|
|
1339
|
+
`marquee` is a row of logos or words that scrolls sideways without end. It is CSS only: a server component with no JavaScript. Each direct child of its `children` slot is one item; give images a fixed height (`h-8 w-auto`).
|
|
1340
|
+
|
|
1341
|
+
- Props: `speed` (`slow`, `normal` or `fast`: 60, 35 or 20 seconds per round), `direction` (`left` or `right`) and `pauseOnHover` (default on; it also stops while a link in it has the focus).
|
|
1342
|
+
- The items render twice, so the row loops without a gap. The copy is hidden from screen readers and the keyboard. Keep the row wider than the screen: repeat a short list of items.
|
|
1343
|
+
- Space the items with margins in the `children` part (a new marquee has `*:mx-8`), not with a gap, so the loop does not jump.
|
|
1344
|
+
- The default `className` fades the edges with a mask, so it works on any background.
|
|
1345
|
+
- With reduced motion, and on the canvas, it stands still and the items wrap.
|
|
1346
|
+
|
|
1347
|
+
#### Table of contents
|
|
1348
|
+
|
|
1349
|
+
`tableOfContents` links to the H2 headings of a rich text field of the current document, for example the body of a post template. Bind its `content` prop to that field: `bindings: { content: 'content' }` (in the inspector, the bind button next to "Rich text"). It renders a `<nav>` of bare `<a href="#id">` links; style them with `[&>a]:` classes on the block.
|
|
1350
|
+
|
|
1351
|
+
- Props: `content` (the rich text, usually bound), `minHeadings` (default 3; with fewer headings the block renders nothing) and `label` (the nav's name, default "On this page").
|
|
1352
|
+
- The `richText` and `field` blocks give each heading on the page an id from its text (`headingId(text)` in `payload-canvas/core`): lower case, accents dropped, other characters as hyphens, letters of every script kept ("Über uns?" becomes `uber-uns`). So the links find the headings with no setting. Only top-level H2 headings with letters or digits are listed.
|
|
1353
|
+
- Headings with the same text get their own ids: the second `pricing-2`, the third `pricing-3`, the same ids the rich text renders.
|
|
1354
|
+
- On the canvas, with too few headings, it shows three sample links, so it can be selected and styled.
|
|
1355
|
+
|
|
1356
|
+
#### Filter link
|
|
1357
|
+
|
|
1358
|
+
`filterLink` is a link to the current page with one URL query value set, toggled or cleared. It pairs with a collection list's `queryFilters`: a filter link with `param: 'category'` and `value: 'news'` goes to `?category=news`, and the list filters by it. Its `children` slot holds the label (a text, an icon); links and controls are refused there.
|
|
1359
|
+
|
|
1360
|
+
- Props: `param`, `value` and `multiple`. An empty `param` clears every query value (the "All" link). An empty `value` clears its param. `multiple` adds or removes the value in a comma list (`?tag=css,react`) instead of replacing it. The page's other query values stay.
|
|
1361
|
+
- The current filter gets `aria-current="true"`. Style it with `aria-[current=true]:` classes.
|
|
1362
|
+
- A new filter starts the lists at page 1: the link drops `page`, and the `pageParam` of every paginated list in the same layout (`loadLayoutData` and the canvas give each filter link these as the runtime `$pageParams` prop). Limit: a list in another layout (a page region) is not known, so its own page param stays.
|
|
1363
|
+
- It is a client component that reads the browser's URL. The server renders a relative href (`?category=news`), so the link works before the script runs and search engines can follow it. The active state and the kept query values appear after hydration.
|
|
1364
|
+
- `filterHref(path, query, { param, value, multiple, pageParams })` in `payload-canvas/blocks` is the same rule as a pure function, for a server component of your own.
|
|
1365
|
+
- Send `noindex, follow` for filtered URLs.
|
|
1366
|
+
|
|
1367
|
+
#### Previous / next
|
|
1368
|
+
|
|
1369
|
+
`adjacentLinks` (**Previous / next**) links to the previous and the next document of the same collection, at the end of a template: blog posts, case studies. It is a `<nav>` with two slots, `previous` and `next`. Each slot holds one collection list that finds its document with a value of the page's own document:
|
|
1370
|
+
|
|
1371
|
+
- `previous`: `sort: '-publishedAt'`, `limit: 1`, `where: { publishedAt: { less_than: '$page.publishedAt' } }`.
|
|
1372
|
+
- `next`: `sort: 'publishedAt'`, `limit: 1`, `where: { publishedAt: { greater_than: '$page.publishedAt' } }`.
|
|
1373
|
+
|
|
1374
|
+
`createdAt`, or any date or number field, works the same way. The list's `item` slot is the link: a `link` bound to `$url` around a text ("← Previous") and a heading bound to `title`. The starter's post template shows the full pattern (`apps/starter/src/data/sections/postTemplate.ts`).
|
|
1375
|
+
|
|
1376
|
+
- On the site a side without a document renders nothing. With no document on either side, the whole block renders nothing. The canvas always shows both sides.
|
|
1377
|
+
- Parts: the `previous` and `next` slots. A new block puts the next link at the end (`ms-auto`).
|
|
1378
|
+
- Control label: `label` (the `<nav>`'s name, default "Previous and next").
|
|
1379
|
+
|
|
990
1380
|
## Using existing Payload blocks
|
|
991
1381
|
|
|
992
1382
|
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.
|
|
@@ -1168,7 +1558,7 @@ export function TwoColumnComponent({ leftColumn, rightColumn, builder }: Payload
|
|
|
1168
1558
|
}
|
|
1169
1559
|
```
|
|
1170
1560
|
|
|
1171
|
-
The `builder` prop holds `mode`, `className`, `slots` (rendered children by slot name) and `
|
|
1561
|
+
The `builder` prop holds `mode`, `className`, `slots` (rendered children by slot name) and `partAttributes`. In the canvas, the adapter puts the block id on your component's first element. It adds no wrapper element, so the layout stays as on the site: container rules such as `space-y-8` and `divide-y` reach your elements. A component that renders nothing gets a small placeholder.
|
|
1172
1562
|
|
|
1173
1563
|
### Limitations
|
|
1174
1564
|
|
|
@@ -1212,13 +1602,68 @@ export const sections: SectionDefinition[] = [
|
|
|
1212
1602
|
|
|
1213
1603
|
Pass them to `websiteBuilder({ sections })` and to `builderMcpTools({ sections })`. Block ids are regenerated on every insert.
|
|
1214
1604
|
|
|
1605
|
+
A section block without a `className` key gets its block type's `defaultClassName`, as a block inserted from the library does. `websiteBuilder` and `builderMcpTools` fill it, so the library, its pictures, the MCP tools and the assistant all see the classes. To keep a block without classes, set `className: ''`. A seed that builds layouts by hand can run the same step: `withDefaultClassNames(blocks, blockDefinitions)` (from `payload-canvas` or `payload-canvas/blocks`). A collection that stores a Payload `blocks` field gets the sections as written, because that field holds no classes.
|
|
1606
|
+
|
|
1607
|
+
`defineSection()` (from `payload-canvas` or `payload-canvas/blocks`) writes the block ids for you. Leave out `id` on any block, at any depth. It fills each missing id as `<section id>_1`, `_2`, … in tree order and skips ids you gave. The same input always gives the same ids. It throws an `Error` when the section has no `id` or `label`, or when two blocks have the same id. The input type is `SectionInput`.
|
|
1608
|
+
|
|
1609
|
+
```ts
|
|
1610
|
+
import { defineSection } from 'payload-canvas/blocks'
|
|
1611
|
+
|
|
1612
|
+
export const hero = defineSection({
|
|
1613
|
+
id: 'hero',
|
|
1614
|
+
label: 'Hero',
|
|
1615
|
+
blocks: [
|
|
1616
|
+
{
|
|
1617
|
+
type: 'stack',
|
|
1618
|
+
className: 'flex flex-col items-center gap-6 py-24 text-center',
|
|
1619
|
+
slots: {
|
|
1620
|
+
children: [
|
|
1621
|
+
{ type: 'heading', props: { text: 'Build faster', level: '1' } }, // id: 'hero_2'
|
|
1622
|
+
{ type: 'button', props: { label: 'Start', link: { type: 'url', url: '/contact' } } },
|
|
1623
|
+
],
|
|
1624
|
+
},
|
|
1625
|
+
},
|
|
1626
|
+
],
|
|
1627
|
+
})
|
|
1628
|
+
```
|
|
1629
|
+
|
|
1630
|
+
### Section variants
|
|
1631
|
+
|
|
1632
|
+
One section file can hold 2 or 3 versions of a section, for example a centred hero and a split hero. Put the other versions in `variants`. Each variant has an `id` (unique in the section), a `label`, an optional `description` and its own `blocks`. The section's own `blocks` stay the first version.
|
|
1633
|
+
|
|
1634
|
+
```ts
|
|
1635
|
+
export const hero = defineSection({
|
|
1636
|
+
id: 'hero',
|
|
1637
|
+
label: 'Hero',
|
|
1638
|
+
category: 'Heroes',
|
|
1639
|
+
blocks: [{ type: 'stack', slots: { children: [{ type: 'heading', props: { text: 'Build faster', level: '1' } }] } }],
|
|
1640
|
+
variants: [
|
|
1641
|
+
{
|
|
1642
|
+
id: 'split',
|
|
1643
|
+
label: 'Split',
|
|
1644
|
+
blocks: [{ type: 'grid', className: 'grid md:grid-cols-2 gap-8', slots: { children: [/* … */] } }],
|
|
1645
|
+
},
|
|
1646
|
+
],
|
|
1647
|
+
})
|
|
1648
|
+
```
|
|
1649
|
+
|
|
1650
|
+
How the versions show up:
|
|
1651
|
+
|
|
1652
|
+
- **Sections tab.** A section with variants is one card. The ‹ › arrows on its picture flip the card between the versions ("2 / 3"). A click or a drag inserts the version the card shows. Search also finds a section by a variant's label.
|
|
1653
|
+
- **Switch after the insert.** The root block of an inserted section remembers where it came from: `block.section = { id: 'hero', variant: 'split' }` (no `variant` for the section's own version). When you select that block, its action bar on the canvas shows ‹ Split ›. The arrows replace the section in place with the previous or next version, as one undo step. Text and images you changed come along: blocks pair by the same `id` in both versions first, then by type in order (the first heading with the first heading). Give a block the same `id` in each version to pair it exactly. The root block keeps its name and HTML id. Classes, animations and the structure come from the new version. Blocks you added inside the section are not carried over; undo brings them back. A translation stays only when the text it translates did not change.
|
|
1654
|
+
- **`variantLabel`** names the section's own version in the switch. Default "Default".
|
|
1655
|
+
- **MCP and the assistant.** `listSections` lists the variants under their section (`variants: [{ id, label, description?, outline }]`; `full: true` gives their `blocks`). `insertSection` takes `variant: "split"`. The old ids such as `hero/split` still work.
|
|
1656
|
+
- Only a section with one root block gets `block.section`: a section of several top-level blocks has nothing to switch. Saved sections have no variants, and "Save as section…" drops `block.section`.
|
|
1657
|
+
|
|
1658
|
+
`defineSection` fills a variant's missing block ids as `<section id>_<variant id>_1`, `_2`, …, and throws when a variant has no `id` or `label` or two variants share an id. Variant blocks get their `defaultClassName` like section blocks. `sectionVersion(section, variant?)` (from `payload-canvas`) returns one version ready to insert, with `block.section` set, for your own code such as a seed. `sectionsWithVariants(sections)` still returns the old flat list (`hero/split` as a section of its own), but the plugin no longer uses it.
|
|
1659
|
+
|
|
1215
1660
|
The library shows each section as a real picture: the hidden canvas page (`?mode=thumbnail`) renders one section at a time with your components and theme, at a desktop width of 1280 px, and the editor keeps the picture in IndexedDB. A picture changes when the section, the theme or the block definitions change. Cards show a wireframe until their picture is ready, or when it fails.
|
|
1216
1661
|
|
|
1217
1662
|
### Saved sections
|
|
1218
1663
|
|
|
1219
1664
|
Editors save their own sections: select a block (a whole section, or any block with its children), open **…** on the canvas or in the inspector, and choose **Save as section…**. Give it a name and, if you like, a category. It appears in **Add › Sections** under **Saved**, for everyone who edits pages. Insert it like any section; every insert gets new block ids. The card's **…** menu edits, renames or deletes it. A deleted section stays on the pages that use it.
|
|
1220
1665
|
|
|
1221
|
-
**Edit section** (in the card's **…** menu) opens the section in the full-screen builder, like a page, at `/admin/builder/builder-sections/<id>`. The top bar shows "Section: <name>" and its category; click either to change it. **Back** returns to the page you came from. Sections have no drafts: each change saves to the section at once, and the library pictures follow on their own. Pages that already inserted the section keep their own copy
|
|
1666
|
+
**Edit section** (in the card's **…** menu) opens the section in the full-screen builder, like a page, at `/admin/builder/builder-sections/<id>`. The top bar shows "Section: <name>" and its category; click either to change it. **Back** returns to the page you came from. Sections have no drafts: each change saves to the section at once, and the library pictures follow on their own. Pages that already inserted the section as plain blocks keep their own copy: a change applies only to later inserts. Copies of a component (see [Components](#components-sections-with-properties)) follow every change. The section's **Builder** tab in the admin opens the same view.
|
|
1222
1667
|
|
|
1223
1668
|
The collection stores the blocks in its `blocks` field. The builder edits a virtual `layout` field (no database column) that reads from `blocks`, and a save hook writes the layout back to `blocks`. While the section is open in the builder, the live session owns its blocks: a REST save of `blocks` gets the session's blocks, as on pages. Otherwise a REST or MCP save of `blocks` works as before.
|
|
1224
1669
|
|
|
@@ -1226,10 +1671,52 @@ The plugin stores them in the `builder-sections` collection (next to Templates i
|
|
|
1226
1671
|
|
|
1227
1672
|
A saved section runs the same field logic as a page save: the `beforeValidate` and `beforeChange` hooks of block props change its values before it is stored. The props' `validate` messages and other problems that block **Publish** (a missing required prop, a value outside its limits) do not stop the save: a section is never published. They go to the server log as warnings.
|
|
1228
1673
|
|
|
1674
|
+
#### Live saved sections (`sectionRef`)
|
|
1675
|
+
|
|
1676
|
+
An inserted section is a copy: later edits of the saved section do not reach the page. A `sectionRef` block shows a saved section **live** instead: the page renders the section's current blocks, so one edit changes every page that uses it. Use it for blocks many pages share, such as a call to action or a footer band.
|
|
1677
|
+
|
|
1678
|
+
- The plugin adds the block when saved sections are on (the default), pointed at their collection (`savedSections.slug`). Your own block list does not need it, and `defaultComponents` has its component. `loadLayoutData` reads the collection from the Payload config.
|
|
1679
|
+
- 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
|
+
- `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
|
+
- 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.
|
|
1683
|
+
- A deleted section shows "Component not found" on the canvas and nothing on the site.
|
|
1684
|
+
- 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
|
+
|
|
1686
|
+
#### Components (sections with properties)
|
|
1687
|
+
|
|
1688
|
+
A component is a saved section with **properties**: the parts each copy may change, like a title, a text, an image, a link or whether a button shows. The design stays in one place: change the component, and every copy follows. This works like Webflow's components.
|
|
1689
|
+
|
|
1690
|
+
**Make one.** Save a section, then open it with **Edit section**. Select a block and open its **Content** tab. Next to a text, rich text, image or link field, click the ◆ button (**Make it a property**) and give the property a name. The field now shows a **Property** chip; its own value is the default every copy starts with. The **Visible** row under the fields makes a property that shows or hides the block. Use the same name on two fields to fill both with one value. The **×** on the chip makes it a normal field again. A banner on top of the inspector says how many places use the component.
|
|
1691
|
+
|
|
1692
|
+
**Use one.** Components are in **Add › Sections** under **Saved**, with a ◆ mark and "Component". A click or a drag adds a copy that stays in sync (a `sectionRef` block). Select it to see the component's properties as normal fields; an empty field shows the component's own content. **Edit component** opens the component; **Back** returns to the page. The card's **…** menu adds the component as plain blocks instead. A saved section without properties still goes in as plain blocks; its **…** menu adds a copy that stays in sync.
|
|
1693
|
+
|
|
1694
|
+
**Detach.** **Detach section** in the copy's **…** menu turns it into plain blocks with the copy's values in them.
|
|
1695
|
+
|
|
1696
|
+
How it is stored:
|
|
1697
|
+
|
|
1698
|
+
- A property is a binding inside the saved section that reads `$component.<name>`, for example `bindings: { text: '$component.title' }` on a heading. The bindings are the only record of the properties: no extra field, no migration. The type comes from the bound field (`text`, `richText`, `image` for an upload, `link` for a link group), the default is the prop's own value. A visible property uses the binding key `$visible`: `bindings: { $visible: '$component.showButton' }`.
|
|
1699
|
+
- A copy stores its values in `props.values` of the `sectionRef` block, by property name. Images are stored as `{ relationTo, value }`, so the page's references and **Used in** count them.
|
|
1700
|
+
- `attachSections` (used by `loadLayoutData` and the canvas) puts the values into the section's blocks before the rest of the data loading, so it works on the site, on the canvas and in server-rendered blocks. A template string may mix both: `{{$component.title}} for {{title}}`.
|
|
1701
|
+
- `core`: `componentProperties(blocks, definitions)`, `applyComponentValues(blocks, values, definitions)`, `checkComponentValues(properties, values)`.
|
|
1702
|
+
- MCP and the assistant: `listSections` shows `component: true` and the `properties` (name, type, default). `insertSection` takes `values` and inserts a copy that stays in sync; `linked: false` inserts plain blocks with the values in them.
|
|
1703
|
+
|
|
1229
1704
|
## Styling
|
|
1230
1705
|
|
|
1231
1706
|
- **Classes.** Each block stores Tailwind v4 classes in `className`. Variants use normal Tailwind syntax: `md:flex-row`, `hover:bg-primary`, `dark:text-white`.
|
|
1232
|
-
- **Styles panel.** Visual controls for layout, spacing, size, position, typography, background, border and effects read and write classes. The breakpoint bar (`base`, `sm`, `md`, `lg`, `xl`, `2xl`) and the state bar (Default, Hover, Focus, Active) set the variant prefix.
|
|
1707
|
+
- **Styles panel.** Visual controls for layout, spacing, size, position, typography, background, border and effects read and write classes. The breakpoint bar (`base`, `sm`, `md`, `lg`, `xl`, `2xl`) and the state bar (Default, Hover, Focus, Active) set the variant prefix. A line under them says what the controls change: "Editing this block at all screen sizes", or "Editing .card at md · 768 px and wider" while you edit a class.
|
|
1708
|
+
- **The Classes field** at the top of the Styles tab holds every class the controls do not show. [Editable classes](#editable-classes) are solid chips: click one to edit that class. Other classes (`dark:pt-4`, a code `@utility` class) are quiet chips in monospace: click one to change it, or × to remove it. Classes that a control shows (`p-4`, `md:flex`) have no chip. The input at the end adds any class, with suggestions. The "⋯" menu has **New class from these styles…**, **Import from the site's CSS** and **Edit as text** (the whole class list as one text box).
|
|
1709
|
+
- **Hide a block.** The inspector's **Advanced** tab has **Hide at all screen sizes** (`block.hidden`): the site does not render the block. To hide it at some sizes only, use Styles → Layout → **Display** → **Hidden** at a breakpoint. Hidden at `md` writes `md:hidden`: the block hides at `md` and wider. To hide it only on small screens, set Hidden at **All sizes** and a display at `md`: `hidden md:flex`.
|
|
1710
|
+
- **Site classes.** The **Classes** field in the Styles panel suggests your CSS entry's own static `@utility` classes (`type-h2`, `btn-primary`, `glass`) before Tailwind's classes. When the input gets the focus, it lists them by group, without the ones the block has. Typing filters them by class name or label. After a typed variant such as `md:`, the input lists them again, and the picked class gets the variant, as when you type it. A site class on the block shows its label next to the class name, and its tooltip shows the rule's CSS. A comment right above the rule sets a label and a group: `/* @canvas Buttons: Primary button */` (group "Buttons", label "Primary button") or `/* @canvas Primary button */` (a label only). Without a comment the class shows by its name. Classes from the files the entry imports count too, but not from packages in `node_modules`, and not functional utilities such as `tab-*`. `getStyleTokens()` returns them as `siteClasses` (`{ name, label?, group?, css }`). The MCP tool `listBlocks` and the assistant's prompt list them, so agents use the site's look.
|
|
1711
|
+
|
|
1712
|
+
```css
|
|
1713
|
+
/* @canvas Buttons: Primary button */
|
|
1714
|
+
@utility btn-primary {
|
|
1715
|
+
background: var(--color-brand);
|
|
1716
|
+
color: var(--color-ground);
|
|
1717
|
+
}
|
|
1718
|
+
```
|
|
1719
|
+
|
|
1233
1720
|
- **Theme tokens.** Classes compile against your CSS entry, so tokens from your `@theme` work: `bg-primary`, `font-heading`, `rounded-card`. The Styles panel lists your colors, fonts and sizes.
|
|
1234
1721
|
- **In the editor.** The canvas compiles the classes in the browser with Tailwind's own compiler. A new class shows at once.
|
|
1235
1722
|
- **On save.** The `beforeChange` hook compiles only the classes the layout uses and stores the CSS in `<field>Css` (`{ hash, css }`). The output holds the utilities, their `@property` and `@keyframes` rules, and the theme variables. It has no Preflight. `RenderLayout` writes it into a `<style>` tag, so the site does not need a Tailwind build of its own. If the site has one, import the same CSS entry in your site layout for Preflight and base styles.
|
|
@@ -1254,6 +1741,181 @@ export default function CanvasPage() {
|
|
|
1254
1741
|
- **Theme variables in the canvas.** The canvas gets the Theme global from `<ThemeStyle live />` in its layout. If you set other variables at runtime, render the same tag in the canvas layout too.
|
|
1255
1742
|
- **Standalone output** needs `outputFileTracingIncludes`. See [step 8](#8-add-the-standalone-tracing-lines).
|
|
1256
1743
|
|
|
1744
|
+
### Classes on inner elements
|
|
1745
|
+
|
|
1746
|
+
A block can let the user style some of its inner elements, not only its root: a carousel's arrows, a collection list's page links, the `empty` slot of a collection list. These elements are the block's **parts**. Each part's classes live in `block.partClassName`, by part name.
|
|
1747
|
+
|
|
1748
|
+
There are two kinds of part:
|
|
1749
|
+
|
|
1750
|
+
- A slot with `styles: true`: the element that holds the slot's children, for example the `summary` and `content` of a disclosure.
|
|
1751
|
+
- An entry of `parts`: any other element, for example the carousel's `arrow`. A part name must not be a slot name.
|
|
1752
|
+
|
|
1753
|
+
```ts
|
|
1754
|
+
defineBlock({
|
|
1755
|
+
type: 'gallery',
|
|
1756
|
+
label: 'Gallery',
|
|
1757
|
+
fields: [],
|
|
1758
|
+
slots: { items: { label: 'Items', styles: true, defaultClassName: 'gap-4' } },
|
|
1759
|
+
parts: { caption: { label: 'Caption', defaultClassName: 'text-sm text-muted-foreground' } },
|
|
1760
|
+
})
|
|
1761
|
+
```
|
|
1762
|
+
|
|
1763
|
+
```tsx
|
|
1764
|
+
function Gallery({ attributes, className, partAttributes, slots }: BlockComponentProps) {
|
|
1765
|
+
return (
|
|
1766
|
+
<figure {...attributes} className={className}>
|
|
1767
|
+
<div {...partAttributes.items} className={['grid', partAttributes.items?.className].filter(Boolean).join(' ')}>{slots.items}</div>
|
|
1768
|
+
<figcaption className={partAttributes.caption?.className}>A caption</figcaption>
|
|
1769
|
+
</figure>
|
|
1770
|
+
)
|
|
1771
|
+
}
|
|
1772
|
+
```
|
|
1773
|
+
|
|
1774
|
+
```json
|
|
1775
|
+
{ "type": "collectionList", "className": "grid grid-cols-3 gap-6", "partClassName": { "empty": "col-span-full text-center", "pager": "flex gap-2" } }
|
|
1776
|
+
```
|
|
1777
|
+
|
|
1778
|
+
- The component gets the classes in `partAttributes[name].className`, with the `builder-css` marker. Join them with the element's own classes.
|
|
1779
|
+
- `defaultClassName` on a part (or on a styled slot) gives a new block those classes, like the block's `defaultClassName`. Sections get them too (`withDefaultClassNames`).
|
|
1780
|
+
- The save hook and the canvas compile them like `className`.
|
|
1781
|
+
- In the Styles tab, a block with parts shows a **Style target** select: **This block**, or one of its parts. The panel then edits that part's classes. A dot marks parts that have classes.
|
|
1782
|
+
- An update merges per part: `{ "type": "update", "id": "b_list01", "partClassName": { "empty": "p-8" } }`. `null` or `""` removes a part's classes.
|
|
1783
|
+
- `validateLayout` refuses classes on a name that is not a part. The MCP tools and the assistant list each block's `parts`.
|
|
1784
|
+
- Built-in parts: the collection list's `empty` slot, `pager` (the page links' `<nav>`) and `pageLink`; the carousel's `slides` slot (the track), `controls`, `arrow`, `dot` and `pause`; the menu's `link`, `submenu` (a dropdown box), `submenuLink` and `panel` (the small-screen panel); the disclosure's `summary` and `content`; the popup's `trigger` and `content` slots, `panel` and `close`; the tabs' `list`, `tab` and `panel`; the marquee's `children` slot; the previous / next block's `previous` and `next` slots.
|
|
1785
|
+
|
|
1786
|
+
### HTML attributes
|
|
1787
|
+
|
|
1788
|
+
Each block can carry three HTML attributes in `block.attrs`. Edit them in the inspector's **Advanced** tab.
|
|
1789
|
+
|
|
1790
|
+
| Key | HTML | What it does |
|
|
1791
|
+
| --- | --- | --- |
|
|
1792
|
+
| `id` | `id` | An anchor for `#id` links, for example `contact`. Letters, digits, `-` and `_`, starting with a letter. Unique in the layout. |
|
|
1793
|
+
| `ariaLabel` | `aria-label` | The name screen readers read, for example for a link that shows only an icon. |
|
|
1794
|
+
| `ariaHidden` | `aria-hidden="true"` | Screen readers skip the block: decorative shapes, dots and repeated links. |
|
|
1795
|
+
|
|
1796
|
+
```json
|
|
1797
|
+
{ "id": "b_k3x9qa", "type": "stack", "attrs": { "id": "contact", "ariaLabel": "Contact us" } }
|
|
1798
|
+
```
|
|
1799
|
+
|
|
1800
|
+
- `RenderLayout` puts them in `attributes`, which every block component spreads on its root element.
|
|
1801
|
+
- An update merges per key: `{ "type": "update", "id": "b_k3x9qa", "attrs": { "ariaHidden": true, "ariaLabel": null } }`. `null` removes a key, and `attrs: null` removes all.
|
|
1802
|
+
- Inserting a block with an id the layout already uses fails, and so does an update to such an id. A duplicate, a paste and a second copy of a section leave out the id. `validateLayout` reports a repeated id as a `constraint` problem, which blocks publishing.
|
|
1803
|
+
- Inside a collection list item or a repeat row, only the first item keeps the `id`. The other items leave it out, so the id stays unique on the page.
|
|
1804
|
+
- A Payload `blocks` field cannot store them, so the Advanced tab is hidden there.
|
|
1805
|
+
|
|
1806
|
+
## Editable classes
|
|
1807
|
+
|
|
1808
|
+
An editor changes a class once in the Styles panel, and every block that uses it changes, on every page, without a deploy. A class is a document of the plugin's **Classes** collection (slug `builder-classes`): a name such as `card`, Tailwind classes, and optional custom CSS. Blocks use it by name in their classes, next to Tailwind classes: `card md:col-span-2`.
|
|
1809
|
+
|
|
1810
|
+
It is on by default. `websiteBuilder({ classes: false })` turns it off. Options: `classes: { slug?, sheetSlug?, access?, admin?, hooks? }`. Default access: signed-in users read, create, update and delete. The site never reads the collection; it loads the compiled stylesheet.
|
|
1811
|
+
|
|
1812
|
+
**A class holds:**
|
|
1813
|
+
|
|
1814
|
+
| Field | Holds |
|
|
1815
|
+
|---|---|
|
|
1816
|
+
| `name` | The class name, without the dot. Letters, digits, `-` and `_`, starting with a letter or `_`. It must not be a Tailwind class (`flex`, `shadow`, `prose`), and it is unique. A code `@utility` name of your site is allowed: the class replaces that rule. |
|
|
1817
|
+
| `label`, `group` | Shown in the Classes field's suggestions, as for code classes: "Buttons: Primary button". |
|
|
1818
|
+
| `styles` | Tailwind classes with variants, as in a block's classes: `rounded-xl p-6 md:p-8 hover:shadow-lg`. Another class's name applies that class (`btn bg-primary`). The Styles panel edits this field. |
|
|
1819
|
+
| `css` | Custom CSS inside the class rule, for what Tailwind cannot express: layered gradients, `&::before { … }`, `&:hover { … }`, `@keyframes`. `@import`, `@theme`, `@utility` and other rules that change the design system are refused. |
|
|
1820
|
+
| `previousNames` | Names the class had when it was published before (read-only). Published pages that still use an old name keep their look until they are published again. |
|
|
1821
|
+
|
|
1822
|
+
The collection has drafts and versions, so every class has a history, and Payload's Versions screen compares and restores it.
|
|
1823
|
+
|
|
1824
|
+
### In the Styles panel
|
|
1825
|
+
|
|
1826
|
+
- **Find a class.** The **Classes** field at the top of the Styles tab shows each editable class of the block as a solid chip. A small dot on a chip means the class has unpublished changes.
|
|
1827
|
+
- **Edit a class.** Click its chip. A banner says "Editing .card" and how far a change reaches ("Changes 12 blocks on 3 pages"). Every control now reads and writes the class's `styles`. The breakpoint and state bars work as for a block: `md:` and `hover:` go into the class. Under the controls, **More classes in .card** holds the class's classes that no control shows, and a **Custom CSS** box edits its `css`. Click the chip again, or the banner's back button, to edit the block again.
|
|
1828
|
+
- **New class from these styles…** In the Classes field's "⋯" menu. It moves the block's Tailwind classes into a new class and gives the block the class. Classes the block already had stay on it. Add the class to other blocks in their Classes field: it is suggested first, with its label.
|
|
1829
|
+
- **Drafts.** A change shows on the canvas at once. It saves as a draft 0.6 s after the last change (one autosave version for a run of changes). **Ctrl+Z** undoes class changes in order with the other edits.
|
|
1830
|
+
- **Publish.** The banner's **Publish class** makes the class live on every page that uses it. Publishing a page also publishes the classes it uses that have unpublished changes (as the same user), so the live page looks like the canvas. A class the user may not update stays a draft (the server logs it).
|
|
1831
|
+
- **Rename and delete** are in the banner's **…** menu. Both dialogs say where the class is used first. **Rename** changes the class and every block that uses it, in each page's draft, through the live sessions (open editors see it at once). The old published name stays in `previousNames`, so published pages keep their look. **Delete** removes the class from every block's draft, then deletes it. Published pages lose its styles at once.
|
|
1832
|
+
- In the Payload admin, deleting a class that blocks still use is refused with the list of pages (409). Use the Styles panel's **Delete**, which removes it from the blocks first.
|
|
1833
|
+
|
|
1834
|
+
### Manage classes
|
|
1835
|
+
|
|
1836
|
+
**Manage classes…** in the Classes field's "⋯" menu opens every shared class in one list, as Webflow's style manager.
|
|
1837
|
+
|
|
1838
|
+
- **Search** by name, label or group.
|
|
1839
|
+
- **Usage.** Each row shows how many blocks and pages use the class, or "Unused". A click on a used row lists the documents: pages, posts, templates, template parts, saved sections, every collection with a layout. Each link opens that document in the builder in a new tab. The counts include unsaved edits of open builder sessions.
|
|
1840
|
+
- **Rename**, **Duplicate** and **Delete** sit on each row. Rename and Delete use the same dialogs as the Styles panel: they change every layout's draft through its live session, so an open editor keeps its unsaved edits and sees the change at once. **Duplicate** makes a draft copy named `<name>-copy`.
|
|
1841
|
+
- **Remove unused classes** deletes every class that no layout uses. The server checks again before it deletes: the latest drafts, open builder sessions and published pages of every document, under the class's name and its former names. A class that only a published page still uses stays.
|
|
1842
|
+
- Endpoint: `POST /api/builder/classes/remove-unused` returns `{ deleted, failed }`. Server helpers: `unusedClasses(req)` and `removeUnusedClasses(req)` from `payload-canvas`.
|
|
1843
|
+
|
|
1844
|
+
### Import from the site's CSS
|
|
1845
|
+
|
|
1846
|
+
**Import from the site's CSS** (the Classes field's "⋯" menu, or `POST /api/builder/classes/import`) makes a published class from each static `@utility` rule of your CSS entry and the files it imports (not packages). The `/* @canvas Group: Label */` comment gives the label and the group. `@apply` lists become `styles`; declarations and nested rules become `css`. Names that are classes already are skipped.
|
|
1847
|
+
|
|
1848
|
+
After the import, the classes are the source. Delete the `@utility` rules from your CSS: until then, Tailwind may still put them in the site's CSS (when its scanner finds the name in your source files), and properties the class does not set still come from them.
|
|
1849
|
+
|
|
1850
|
+
### On the site
|
|
1851
|
+
|
|
1852
|
+
Render `ClassesStyle` in the root layout, after `ThemeStyle`:
|
|
1853
|
+
|
|
1854
|
+
```tsx
|
|
1855
|
+
import { ClassesStyle, ThemeStyle } from 'payload-canvas/react/server'
|
|
1856
|
+
|
|
1857
|
+
<head>
|
|
1858
|
+
<ThemeStyle payload={payload} />
|
|
1859
|
+
<ClassesStyle payload={payload} />
|
|
1860
|
+
</head>
|
|
1861
|
+
```
|
|
1862
|
+
|
|
1863
|
+
- **One stylesheet for all published classes.** The classes collection's hooks compile it after every publish, unpublish and delete, with the plugin's Tailwind compile against your CSS entry, so theme tokens and plugins work. It is stored with a hash of its CSS in a hidden global (`builder-classes-sheet`). Drafts never reach it.
|
|
1864
|
+
- **Cached by the browser.** `ClassesStyle` renders `<link rel="stylesheet" href="/api/builder/classes-sheet/<hash>.css">`, served with `Cache-Control: public, max-age=31536000, immutable`. A publish makes a new hash, and the plugin clears Next's page cache (`revalidatePath('/', 'layout')`). An old hash gets the current stylesheet, cached for 60 s.
|
|
1865
|
+
- **Size.** 15 typical classes (cards, buttons, type styles, a gradient and a keyframes animation) compile to 13.9 KB, 2.4 KB gzipped, in about 50 ms. The link loads at the same time as Next's own CSS file, which also blocks the first paint, and the browser keeps it for every later page. `mode="inline"` puts the CSS in a `<style>` tag in each page instead: no extra request, but no browser cache. `origin` puts a host before the path when the site and Payload run on different hosts.
|
|
1866
|
+
- **After a deploy** with a changed CSS entry, the first request compiles the stylesheet again.
|
|
1867
|
+
- **The page's CSS leaves the classes out.** `compilePageCss` and the stored `<field>Css` compile no rule for a class name, with or without a variant prefix, so a code `@utility` with the same name never comes back on the page.
|
|
1868
|
+
- `loadClassesSheet(payload)` (`payload-canvas/react/server`, read once per request) returns the stored stylesheet: `{ hash, css, names }`.
|
|
1869
|
+
|
|
1870
|
+
### Which rule wins
|
|
1871
|
+
|
|
1872
|
+
| Order on the page | Holds |
|
|
1873
|
+
|---|---|
|
|
1874
|
+
| 1. The site's CSS (`<link>` in the head) | Your Tailwind build, with code `@utility` rules |
|
|
1875
|
+
| 2. The theme (`ThemeStyle`) | CSS variables |
|
|
1876
|
+
| 3. The classes (`ClassesStyle`) | Every published class |
|
|
1877
|
+
| 4. The page's CSS (`<style>` in the body) | The block's own Tailwind classes |
|
|
1878
|
+
|
|
1879
|
+
All the rules are in `@layer utilities` with the specificity of one class, so the later stylesheet wins:
|
|
1880
|
+
|
|
1881
|
+
- A class beats a code `@utility` rule with the same name. The class's rules never include the code rule: the compile builds each class under an internal name and renames it after the build.
|
|
1882
|
+
- A block's own Tailwind classes beat its class: `card p-2` gets the class's look with `p-2` padding.
|
|
1883
|
+
- Class rules are not limited to block elements (no `builder-css` marker): your own components can use the classes too.
|
|
1884
|
+
- Use a class without a variant prefix. Put variants into the class's styles (`md:p-8`), not before its name (`md:card` styles nothing).
|
|
1885
|
+
|
|
1886
|
+
The canvas keeps the same order: the classes' stylesheet (compiled in the browser from the latest drafts) comes before the layout's CSS.
|
|
1887
|
+
|
|
1888
|
+
### MCP tools
|
|
1889
|
+
|
|
1890
|
+
`builderMcpTools()` adds `listClasses`, `getClass`, `upsertClass` and `deleteClass`. Each takes `collection: "builder-classes"` (the default, so agents may leave it out), and the API key needs access to the classes collection.
|
|
1891
|
+
|
|
1892
|
+
- `upsertClass` creates or changes a class (a draft; `publish: true` publishes it). `newName` renames it on every page, as the Styles panel does. Without `publish`, the result lists the published pages that still show the old version (`publishedPagesWithOldVersion`).
|
|
1893
|
+
- `deleteClass` refuses a class that blocks use and lists the pages, unless `removeFromBlocks: true`. The result lists the published pages that still use the class and need publishing again.
|
|
1894
|
+
- `listBlocks` lists the editable classes with the code classes (`siteClasses`), so agents use them in `className`.
|
|
1895
|
+
- `builderMcpTools({ classes: false })` leaves the tools out; `classes: { slug }` matches a custom slug.
|
|
1896
|
+
|
|
1897
|
+
### Endpoints
|
|
1898
|
+
|
|
1899
|
+
| Endpoint | Use |
|
|
1900
|
+
|---|---|
|
|
1901
|
+
| `GET /api/builder/classes` | The classes' latest drafts, as the user may read them. The editor and the canvas use it. |
|
|
1902
|
+
| `GET /api/builder/classes/usage` | Blocks and pages per class name (`?names=a,b` limits it). |
|
|
1903
|
+
| `POST /api/builder/classes/rename` | `{ id, name }`: renames the class everywhere. |
|
|
1904
|
+
| `POST /api/builder/classes/delete` | `{ id, removeFromBlocks }` |
|
|
1905
|
+
| `POST /api/builder/classes/import` | `{ names? }`: imports code `@utility` classes. |
|
|
1906
|
+
| `GET /api/builder/classes-sheet/<hash>.css` | The site's stylesheet. Public. |
|
|
1907
|
+
|
|
1908
|
+
Style edits use Payload's own REST API (`PATCH /api/builder-classes/:id?draft=true&autosave=true`), so access, hooks, validation and versions apply. The server actions are exported from `payload-canvas` for scripts: `upsertClass`, `publishClass`, `renameClass`, `deleteClass`, `importSiteClasses`, `classUsage`, `storeClassesSheet`, `loadClassesSheet`.
|
|
1909
|
+
|
|
1910
|
+
### Limits
|
|
1911
|
+
|
|
1912
|
+
- Other people's class changes reach your editor when its window gets the focus again. Canvases in your own browser follow your changes at once.
|
|
1913
|
+
- Section thumbnails keep their picture until the section, the theme or the blocks change.
|
|
1914
|
+
- Usage counts read every builder layout (one query per collection: latest drafts and open sessions). This is fine for hundreds of pages.
|
|
1915
|
+
- The in-editor AI assistant's style hints list the code classes only; the MCP tools list both.
|
|
1916
|
+
- Classes are the same in every locale.
|
|
1917
|
+
- The new collection and global need a migration in production: run `pnpm payload migrate:create` when you prepare the release.
|
|
1918
|
+
|
|
1257
1919
|
## Animations
|
|
1258
1920
|
|
|
1259
1921
|
Editors and the AI can add motion to any block without code: an entrance when the block scrolls into view, hover and press effects, a scroll effect such as parallax, and a loop. The site plays them with the [`motion`](https://motion.dev) package (its DOM API). Animations are data, not classes.
|
|
@@ -1289,10 +1951,11 @@ A block stores its animations in `motion`. Every kind is optional. Times are mil
|
|
|
1289
1951
|
| `enter` | `fade`, `fade-up`, `fade-down`, `fade-left`, `fade-right`, `zoom-in`, `zoom-out`, `blur-in`, `wipe-up`, `wipe-down`, `wipe-left`, `wipe-right` | `duration` (600), `delay` (0), `easing` (`ease-out`, `ease-in-out`, `linear`, `spring`, `bouncy`), `distance` (24, fade-up/down/left/right), `trigger` (`view`, or `load` for the first section), `amount` in view 0-1 (0.2), `offset` px inside the window (0), `repeat` (false: once), `stagger` |
|
|
1290
1952
|
| `hover` | `lift`, `grow`, `tilt` | `distance` (lift, 4), `scale` (grow, 1.03), `angle` (tilt, 6) |
|
|
1291
1953
|
| `press` | `shrink` | `scale` (0.97) |
|
|
1292
|
-
| `scroll` | `parallax`, `fade`, `zoom` | `distance` (parallax, 60; negative moves with the scroll), `scale` (zoom start, 0.9) |
|
|
1954
|
+
| `scroll` | `parallax`, `fade`, `zoom`, `recede` | `distance` (parallax, 60; negative moves with the scroll), `scale` (zoom start or recede end, 0.9) |
|
|
1293
1955
|
| `loop` | `float`, `pulse` | `duration` (3000 float, 1500 pulse), `distance` (float, 8), `scale` (pulse, 1.04) |
|
|
1294
1956
|
|
|
1295
1957
|
- **Stagger.** `enter.stagger` is the gap in milliseconds between children. The block itself stays still, and its direct child blocks play the entrance one after another. Use it on grids and lists of cards, and on Collection lists. A child's own entrance does not play there (its hover, press, scroll and loop do).
|
|
1958
|
+
- **Stacked cards.** `scroll.recede` shrinks a card to `scale` and dims it to 70 % brightness while the next card scrolls over it. Give each card `sticky top-…` (and `origin-top` to shrink toward the top), and put `recede` on every card but the last. The effect follows the next sibling element from the window's bottom edge to its top edge, so `position: sticky` on the card does not stop it. A card with no next sibling does not recede.
|
|
1296
1959
|
- **Edits.** An `update` operation takes `motion` as a patch: each kind listed replaces that kind, `null` removes a kind, kinds left out stay, and `motion: null` removes all. The operations refuse unknown presets, unknown keys and values out of range, with a message that names the problem.
|
|
1297
1960
|
- The presets, limits and defaults live in `core/motion.ts` (`MOTION_SPECS`, `MOTION_PRESET_INFO`). The layout JSON Schema has the motion schema under `$defs.$motion`. The MCP tools and the assistant document it from the same source.
|
|
1298
1961
|
|
|
@@ -1303,12 +1966,12 @@ A block stores its animations in `motion`. Every kind is optional. Times are mil
|
|
|
1303
1966
|
- `MotionRuntime` loads the runtime as its own chunk (about 14 KB gzipped, Motion included) and starts it once per page, however many layouts render it. The runtime finds the elements, watches for new ones (client navigation, streaming), and drives them:
|
|
1304
1967
|
- Entrances run on the Web Animations API (`animate` from `motion/mini`), so the browser runs them off the main thread. They animate only `opacity`, `transform`, `filter` and `clip-path`, then hand the element back to its classes. Nothing changes layout, so there is no layout shift.
|
|
1305
1968
|
- Hover and press use Motion's `hover` and `press` gestures with short springs. Hover runs only on devices with a fine pointer. Press does not make a block focusable.
|
|
1306
|
-
- Scroll effects use Motion's `scroll`, which uses a native `ViewTimeline` where the browser has one. Scroll and loop effects use the separate `translate`, `scale` and `opacity` properties, so they add to the other effects.
|
|
1969
|
+
- Scroll effects use Motion's `scroll`, which uses a native `ViewTimeline` where the browser has one. Scroll and loop effects use the separate `translate`, `scale` and `opacity` properties (and `filter` for the recede dim), so they add to the other effects. Where the browser has no `ViewTimeline`, Motion follows the scroll in JavaScript.
|
|
1307
1970
|
- Loops pause while the block is out of view.
|
|
1308
1971
|
- **Entrances on load start at first paint.** An entrance with `trigger: "load"` plays in plain CSS: `MotionStyle` writes one rule per such block (it matches the block's `data-motion` value) with keyframes from the same preset data. It does not wait for JavaScript, so the block paints with the page. The runtime sees the CSS animation and leaves the block alone.
|
|
1309
1972
|
- **Entrances on scroll: no flash, and nothing hidden without JavaScript.** The style hides these blocks until the runtime takes them over, only under `@media (scripting: enabled) and (prefers-reduced-motion: no-preference)`. Visitors and crawlers without JavaScript see every block. The hiding is a 1.2-second CSS animation, so if the runtime never starts (a script error), the blocks show after 1.2 seconds.
|
|
1310
1973
|
- **Keep the largest element still.** Do not put an entrance on the page's main title or hero image: it is the page's Largest Contentful Paint. Animate the text and buttons around it. The starter's hero sections do this.
|
|
1311
|
-
- **Reduced motion.** When the visitor's system asks for less motion (`prefers-reduced-motion: reduce`), nothing is hidden and blocks in the window at load show at once. Blocks further down fade in briefly as they scroll into view. Hover, press, parallax, zoom and loops do not run. The scroll fade stays.
|
|
1974
|
+
- **Reduced motion.** When the visitor's system asks for less motion (`prefers-reduced-motion: reduce`), nothing is hidden and blocks in the window at load show at once. Blocks further down fade in briefly as they scroll into view. Hover, press, parallax, zoom, recede and loops do not run. The scroll fade stays.
|
|
1312
1975
|
|
|
1313
1976
|
### Custom components and renderers
|
|
1314
1977
|
|
|
@@ -1376,12 +2039,12 @@ import { getPayload } from 'payload'
|
|
|
1376
2039
|
import type { ReactNode } from 'react'
|
|
1377
2040
|
import './globals.css'
|
|
1378
2041
|
|
|
1379
|
-
export default
|
|
1380
|
-
const payload = await getPayload({ config })
|
|
2042
|
+
export default function RootLayout({ children }: { children: ReactNode }) {
|
|
1381
2043
|
return (
|
|
1382
2044
|
<html lang="en">
|
|
1383
2045
|
<head>
|
|
1384
|
-
|
|
2046
|
+
{/* The promise, not the instance: the read stays inside ThemeStyle's <Suspense> (Cache Components). */}
|
|
2047
|
+
<ThemeStyle payload={getPayload({ config })} />
|
|
1385
2048
|
</head>
|
|
1386
2049
|
<body>{children}</body>
|
|
1387
2050
|
</html>
|
|
@@ -1395,16 +2058,35 @@ For about 90 popular families (Inter, Roboto, Newsreader, Hanken Grotesk and oth
|
|
|
1395
2058
|
|
|
1396
2059
|
| Prop | Default | What it does |
|
|
1397
2060
|
|---|---|---|
|
|
1398
|
-
| `payload` | required | The Payload instance. |
|
|
2061
|
+
| `payload` | required | The Payload instance, or the promise from `getPayload({ config })`. Pass the promise under Cache Components: the connection is then made inside `ThemeStyle`'s `<Suspense>` boundary. |
|
|
1399
2062
|
| `fonts` | `true` | `false` leaves the Google Fonts links out (for self-hosted fonts). |
|
|
1400
2063
|
| `live` | `false` | Reloads the theme in the browser when the global is saved in another tab, or when the page becomes visible again. Use it in the canvas layout. |
|
|
1401
2064
|
|
|
1402
2065
|
Other frontends: `loadTheme(payload)` from `payload-canvas/react/server` returns `{ data, css, fontsHref }`. `themeOutput(doc)` from `payload-canvas/theme` turns any theme document into the same output. `GET /api/builder/theme` returns it over HTTP.
|
|
1403
2066
|
|
|
1404
|
-
**Caching.** `ThemeStyle` reads the global once per request, never from Next's data cache. After each save the plugin calls `revalidateTag(<cacheTag>, { expire: 0 })` and `revalidatePath('/', 'layout')`, so statically rendered pages render again with the new theme. Tag your own cached theme reads with the cache tag. Saves with `context: { disableRevalidate: true }` (seed scripts) skip this.
|
|
2067
|
+
**Caching.** `ThemeStyle` reads the global once per request, never from Next's data cache. The read sits in its own `<Suspense>` boundary, so it works with Next's Cache Components; see [Cache Components](#cache-components) to keep the theme in the static shell. After each save the plugin calls `revalidateTag(<cacheTag>, { expire: 0 })` and `revalidatePath('/', 'layout')`, so statically rendered pages render again with the new theme. Tag your own cached theme reads with the cache tag. Saves with `context: { disableRevalidate: true }` (seed scripts) skip this.
|
|
1405
2068
|
|
|
1406
2069
|
**Styles panel.** The color swatches read the canvas, so they show the theme's colors. The Font list shows the theme's families ("Inter", not `var(--font-sans)`).
|
|
1407
2070
|
|
|
2071
|
+
### Design variables
|
|
2072
|
+
|
|
2073
|
+
Named colors, sizes and fonts that blocks and classes use by name, as Webflow's variables. Change a variable once in **Theme > Variables**, and every page that uses it changes.
|
|
2074
|
+
|
|
2075
|
+
| Type | Value | Classes | CSS variable |
|
|
2076
|
+
|---|---|---|---|
|
|
2077
|
+
| Color | a hex color or any CSS color | `bg-brand`, `text-brand/80`, `border-brand`, `from-brand` … | `--color-brand` |
|
|
2078
|
+
| Size | a CSS length: `24px`, `1.5rem`, `clamp(1rem, 4vw, 3rem)` | `p-gutter`, `mt-gutter`, `gap-gutter`, `w-gutter`, `-mx-gutter` … | `--spacing-gutter` |
|
|
2079
|
+
| Font | a Google Fonts family (the site loads it) | `font-display` | `--font-display` |
|
|
2080
|
+
|
|
2081
|
+
- **Names**: lower-case letters, digits and single dashes, unique across all types. Names the theme already uses (`primary`, `background`, `sans`, `full`, palette shades like `red-500`) are refused.
|
|
2082
|
+
- **Dark mode.** Colors and sizes can have a **Dark mode** value. The theme had no dark mode before, so the variables follow the `.dark` class (Tailwind's class strategy): the dark value applies on an element with `dark` and everything inside it. `ThemeStyle` writes `:root:root.dark, :root:root .dark { --color-brand: … }`. With the `@custom-variant dark (&:is(.dark *))` of the starter, `dark:` classes and the variables switch together.
|
|
2083
|
+
- **How it works.** `ThemeStyle` writes the values as CSS variables. Both Tailwind compiles (the save hook and the canvas) add a `@theme inline reference { --color-brand: var(--color-brand); … }` block after your CSS entry, so the classes exist and read the variable. The compiled CSS holds no values: a new value changes every page at once, without a new compile. Adding, renaming or deleting a variable changes which classes exist; the next save or render compiles again (the stored page CSS and the classes stylesheet carry a hash of the names).
|
|
2084
|
+
- **Classes.** Variables work in editable classes too: `bg-brand p-gutter` in a class's styles, `var(--color-brand)` in its custom CSS.
|
|
2085
|
+
- **Styles panel.** The color picker lists the color variables first, under **Variables**, with a swatch. The spacing, size and font suggestions list their variables first. After a theme save, open editors and canvases load the variables again.
|
|
2086
|
+
- **Renaming or deleting a variable in use** shows a warning in the theme form before you save: which blocks and classes still use the old name, with links to the pages. The old classes stop working after the save.
|
|
2087
|
+
- **AI and MCP.** The assistant's system prompt and the MCP `listBlocks` tool list the variables with their values and example classes. `GET /api/builder/style-tokens` returns them as `variables`. `GET /api/builder/theme/variables/usage` returns where each variable is used.
|
|
2088
|
+
- Helpers in `payload-canvas/theme`: `variableTokens`, `variablesThemeCss`, `variableNameProblem`, `variableValueProblem`, `textUsesVariable`.
|
|
2089
|
+
|
|
1408
2090
|
**Options:**
|
|
1409
2091
|
|
|
1410
2092
|
```ts
|
|
@@ -1448,16 +2130,239 @@ websiteBuilder({
|
|
|
1448
2130
|
|
|
1449
2131
|
What the plugin adds:
|
|
1450
2132
|
|
|
1451
|
-
- A templates collection (`builder-templates`) with drafts and the builder. Each template has a target collection (`targetCollection`), a "default for this collection" checkbox (`isDefault`) and a sample document for the editor preview (`previewDocument`).
|
|
2133
|
+
- A templates collection (`builder-templates`) with drafts and the builder. Each template has a target collection (`targetCollection`), a "default for this collection" checkbox (`isDefault`), optional `conditions` with a `priority`, and a sample document for the editor preview (`previewDocument`).
|
|
1452
2134
|
- A `template` relationship in the sidebar of every document in a collection with `templates: true`.
|
|
1453
2135
|
|
|
1454
|
-
Which template a document uses:
|
|
2136
|
+
Which template a document uses:
|
|
2137
|
+
|
|
2138
|
+
1. Its own `template`.
|
|
2139
|
+
2. Else the template with the highest `priority` whose `conditions` match the document. On equal priority the older template (by creation date) wins. The name never counts, so renaming a template does not change which one wins.
|
|
2140
|
+
3. Else the most recently updated default template of its collection.
|
|
2141
|
+
4. Else none.
|
|
2142
|
+
|
|
2143
|
+
Only published templates count (all templates in draft mode). Templates with an empty layout are skipped.
|
|
2144
|
+
|
|
2145
|
+
#### Template conditions
|
|
2146
|
+
|
|
2147
|
+
`conditions` is a Payload `where` query against the document. Use it to give some documents their own default layout, for example featured products or posts in one category. The template's edit form shows it as condition rows: a field of the target collection, an operator and a value, in "or" groups of AND-ed rows (the same rows as a collection list's `where`). A date value can be relative to now (`"$now-30d"`). **Edit as JSON** takes any query, for example:
|
|
2148
|
+
|
|
2149
|
+
```json
|
|
2150
|
+
{ "category": { "equals": "news" } }
|
|
2151
|
+
{ "or": [{ "featured": { "equals": true } }, { "price": { "greater_than": 100 } }] }
|
|
2152
|
+
```
|
|
2153
|
+
|
|
2154
|
+
- `loadTemplate` reads the collection's templates once (without their layouts). When some have conditions, it asks Payload whether the document matches, one query per template with conditions, all at the same time, on the stored document (the latest draft in draft mode). Without conditions it runs no such query. Then it loads only the chosen template. Every operator and field path of a Payload query works, for example `equals`, `not_equals`, `in`, `not_in`, `exists`, `greater_than`, `less_than_equal`, `and`, `or` and relationship paths such as `category.slug`.
|
|
2155
|
+
- `priority` (a number in the sidebar, default 0, shown once the template has conditions) orders templates whose conditions match the same document: the highest wins. Equal priority: the older template wins.
|
|
2156
|
+
- Empty conditions (`null` or `{}`) never match. A template with conditions can also be the default: then it is still the fallback for every document.
|
|
2157
|
+
- A query that Payload refuses (an unknown field) counts as no match, and the error goes to the Payload log.
|
|
2158
|
+
- The editor's notice on an empty document ("This page uses a template") runs the same code on the server (`GET /api/builder/live/:collection/:id/template`), with published templates and the document's latest draft.
|
|
2159
|
+
- The conditions field is a custom admin component (`payload-canvas/client#TemplateConditionsField`). After you add `templates: true` to a collection, run `payload generate:importmap`.
|
|
1455
2160
|
|
|
1456
2161
|
### Bindings and dynamic blocks
|
|
1457
2162
|
|
|
1458
2163
|
- 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.
|
|
1459
2164
|
- 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.
|
|
1460
|
-
- The **Collection list** block (`collectionList`) lists the latest documents of a collection (`collection`, `limit`, `sort`, `excludeCurrent`). Its `item` slot is the design of one item and repeats for every document. Blocks in
|
|
2165
|
+
- 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.
|
|
2167
|
+
- `offset` skips documents after the sort (at most 100).
|
|
2168
|
+
- `depth` is `"1"` (default) or `"2"`: how deep the related documents of each item load. Use `"2"` to reach, for example, `categories.image`.
|
|
2169
|
+
- The **Repeat** block (`repeat`) repeats its `item` slot per row of an array or hasMany field. See "Repeat the rows of a field" below.
|
|
2170
|
+
|
|
2171
|
+
#### Binding syntax
|
|
2172
|
+
|
|
2173
|
+
| Binding | Example | What it gives |
|
|
2174
|
+
| --- | --- | --- |
|
|
2175
|
+
| A path | `"title"`, `"author.name"` | The field's value. |
|
|
2176
|
+
| `$url` | `{ "link": "$url" }` | The document's page URL (the collection's `url` option). |
|
|
2177
|
+
| `<path>.$url` | `{ "link": "categories.0.$url" }` | The page URL of a related document: the first category of a post, `venue.city.$url` through two relationships. See "URLs of related documents" below. |
|
|
2178
|
+
| A fallback chain | `"subtitle\|title"` | The first path that has a value. |
|
|
2179
|
+
| Formatters | `"publishedAt\|date:en-GB:Europe/London"`, `"price\|currency:EUR"`, `"summary\|truncate:160"` | Text. See the table below. Put them after the paths: `"subtitle\|title\|uppercase"`. |
|
|
2180
|
+
| A template string | `{ "text": "Read about {{title}}" }`, `"From {{price\|currency:EUR}}"` | Text with each `{{expression}}` filled in. A missing expression becomes empty. When every expression is missing, the prop keeps its own value. |
|
|
2181
|
+
| `$item`, `$index` | `{ "image": "$item" }`, `"{{$index}}."` | Inside a repeat: the row value itself. Inside a list or repeat item: the item number, from 1. |
|
|
2182
|
+
| `$parent.<path>` | `"$parent.name"` | Inside a list or repeat item: the enclosing document (the page's document, the listed document, or the outer row). |
|
|
2183
|
+
| `$page.<path>` | `"$page.title"` | Anywhere: the page's own document, also inside list and repeat items. |
|
|
2184
|
+
|
|
2185
|
+
The syntax stops here: paths, `|` fallbacks, formatters and `{{ }}` templates. Nothing else will be added.
|
|
2186
|
+
|
|
2187
|
+
Formatters. In the inspector, a bound text prop and the Field block have a **Format** select with an input per argument, so editors never type them.
|
|
2188
|
+
|
|
2189
|
+
| Formatter | Arguments | Example | Gives |
|
|
2190
|
+
| --- | --- | --- | --- |
|
|
2191
|
+
| `date` | language, time zone (default `en`, UTC) | `date:en-GB:Europe/London` | `11 Sept 2026` |
|
|
2192
|
+
| `number` | language | `number` | `1,200` |
|
|
2193
|
+
| `currency` | currency code (default `USD`), language | `currency:EUR` | `€1,200` (whole amounts have no cents) |
|
|
2194
|
+
| `uppercase`, `lowercase` | none | `uppercase` | `DESK LAMP` |
|
|
2195
|
+
| `truncate` | length, then `words` to count words | `truncate:160`, `truncate:25:words` | The plain text (rich text too) cut to 160 characters (on a whole word) or 25 words, with `…` |
|
|
2196
|
+
| `readingTime` | words per minute (default 200), text after the number (default `min read`) | `readingTime`, `readingTime:200:Min. Lesezeit` | `5 min read`: the time to read the text (rich text too), rounded up, at least 1 minute. Nothing for a text without words. |
|
|
2197
|
+
|
|
2198
|
+
After the first part of an expression, a name that is a formatter is always a formatter. So `"title|date"` formats `title`; it never falls back to a field called `date`. A field with a formatter's name works as the first path only: `"date|title"`.
|
|
2199
|
+
|
|
2200
|
+
URLs of related documents (`<path>.$url`):
|
|
2201
|
+
|
|
2202
|
+
- The URL comes from your `resolveLink`, called as for a link to that document: `{ type: 'reference', reference: { relationTo, value: doc } }`. So `resolveLink` is the site's "URL of a document" function, for pages and for `$url`.
|
|
2203
|
+
- The renderer must know the related collection. A `{ relationTo, value }` value (a relationship to several collections) names it. For a relationship to one collection, `loadLayoutData` reads it from the Payload config (`bindingRelations` in `payload-canvas/core` maps each relationship and upload field to its collection, in groups, named tabs and arrays too) and gives it to the collection lists and repeats whose items need it. You pass nothing. The plugin sends the same map to the canvas.
|
|
2204
|
+
- The related document must be loaded (list items load with `depth: 1`; use `depth: "2"` on the list for a relationship of a related document). An id alone gives no URL, and the prop keeps its own value.
|
|
2205
|
+
- `$parent.` and `$page.` paths do not take `.$url`.
|
|
2206
|
+
|
|
2207
|
+
Expressions are not checked against the collection's fields when you publish. The inspector shows a fallback chain or a template string as text with a preview of its value. Add or change one in the layout JSON or through the MCP tools.
|
|
2208
|
+
|
|
2209
|
+
#### Show a block only when conditions match
|
|
2210
|
+
|
|
2211
|
+
A block in a template, a collection list item or a repeat row can show only when its document matches conditions. In the inspector, **Show only when** at the end of the Content tab has condition rows: a field, an operator and a value. The field select lists the fields of the block's document (the template's collection, the listed collection, or the row), else the collection's fields from the Payload config. The rows in a group must all match. **Add "or" group** adds another group, and one matching group is enough. The block stores them as `visibility`:
|
|
2212
|
+
|
|
2213
|
+
```json
|
|
2214
|
+
{
|
|
2215
|
+
"id": "b_sale01",
|
|
2216
|
+
"type": "text",
|
|
2217
|
+
"props": { "text": "On sale" },
|
|
2218
|
+
"visibility": {
|
|
2219
|
+
"match": "any",
|
|
2220
|
+
"conditions": [
|
|
2221
|
+
{ "field": "onSale", "operator": "equals", "value": true },
|
|
2222
|
+
{ "field": "price", "operator": "less_than", "value": 20 }
|
|
2223
|
+
]
|
|
2224
|
+
}
|
|
2225
|
+
}
|
|
2226
|
+
```
|
|
2227
|
+
|
|
2228
|
+
| Operator | Shows the block when |
|
|
2229
|
+
| --- | --- |
|
|
2230
|
+
| `is_set`, `is_empty` | the field has a value, or not. `false`, `""`, `null` and `[]` count as empty. No `value`. |
|
|
2231
|
+
| `equals`, `not_equals` | the field equals the value, or not. For a list (hasMany), any item or document id matches. A checkbox without a value counts as `false`. |
|
|
2232
|
+
| `in`, `not_in` | the field equals one of the values, or none (`value` is a list). |
|
|
2233
|
+
| `greater_than`, `greater_than_equal`, `less_than`, `less_than_equal` | the field and the value are numbers (or numeric texts) or dates, and the comparison holds. Any other value fails. |
|
|
2234
|
+
| `like`, `contains` | the field's text holds every word of the value, or the value, in any case. |
|
|
2235
|
+
|
|
2236
|
+
- `field` is a path of the document, or `$index`, `$item`, `$parent.<path>` and `$page.<path>`.
|
|
2237
|
+
- `"count": true` compares the number of items of the field instead of its value: a list's length, `0` for an empty value, `1` for any other value. For example `{ "field": "gallery", "operator": "greater_than_equal", "value": 3, "count": true }` (at least 3 photos). The inspector offers it under "Number of items" as "Gallery (count)", with operators such as "has at least".
|
|
2238
|
+
- `"valueField"` compares with another field of the same document instead of a fixed `value`: `{ "field": "salePrice", "operator": "less_than", "valueField": "price" }`. A condition has `value` or `valueField`, never both. In the inspector, pick **Other field** next to the value.
|
|
2239
|
+
- `match` is `"all"` (the default, left out) or `"any"`. With `"any"`, an entry can be a group `{ "all": [conditions] }` that matches when all its conditions match. So `{ "match": "any", "conditions": [{ "all": [a, b] }, c] }` means "(a and b) or c". This is how the inspector stores "or" groups.
|
|
2240
|
+
- The inspector offers the operators that fit the field's type ("is after" for dates, "contains" for text, "includes" for hasMany fields) and a value input of the same type: a select's options, checked or not checked, a number, a date, or a document picker for relationships and uploads.
|
|
2241
|
+
- A block that fails renders nothing on the site, and lists inside it load no documents. On the canvas it shows dimmed, like a hidden block. Without a current document (a normal page, outside list and repeat items) the conditions are not checked, and the block shows. The MCP tools return a `no-effect` warning for them there.
|
|
2242
|
+
- The outline marks a block whose condition reads a field the collection does not have.
|
|
2243
|
+
|
|
2244
|
+
#### Filter a collection list
|
|
2245
|
+
|
|
2246
|
+
A collection list can show only the documents related to the current document (the one a template renders). Set `filterField` to a field name and `filterBy` to one of three values:
|
|
2247
|
+
|
|
2248
|
+
| `filterBy` | The list shows | Payload query | Example |
|
|
2249
|
+
| --- | --- | --- | --- |
|
|
2250
|
+
| `current` (default) | documents whose `filterField` holds the current document | `{ [filterField]: { in: [doc.id] } }` | On a category template: the posts whose `categories` include this category. |
|
|
2251
|
+
| `shared` | documents whose `filterField` shares a value with the current document's own `filterField` | `{ [filterField]: { in: values } }` | Related posts with a `category` in common. Products with the same `brand` text. |
|
|
2252
|
+
| `linked` | the documents that the current document's `filterField` points to | `{ id: { in: values } }` | On a post template: the post's `authors`. |
|
|
2253
|
+
|
|
2254
|
+
- In the inspector this is one select, **Related to this page**, under the **Filter** heading. It lists the fields that relate the two collections in words ("Categories links to this page") and sets both props. It shows in templates, or when a filter is already set. Your own block gets it with `admin: { custom: { builderRelated: { collectionField: 'collection', modeField: 'filterBy' } } }` on the text field that stores the field name. `modeField` names the select that stores the mode.
|
|
2255
|
+
- `values` are read from the current document with `getByPath`. Populated documents (`{ id }`), `{ relationTo, value }` pairs, strings and numbers all work, one value or many.
|
|
2256
|
+
- With `shared` or `linked`, a current document without values shows an empty list. The plugin sends no query.
|
|
2257
|
+
- On a normal page (no current document), a list with `filterField` shows nothing (its `empty` slot). The plugin sends no query. The same holds on the canvas for a template without a sample document; the editor still shows the item design once.
|
|
2258
|
+
- `where` is a static Payload `where` query, AND-ed with the filter. For example `{ "featured": { "equals": true } }` or `{ "category": { "equals": "news" } }`. Only a plain object counts; anything else is ignored.
|
|
2259
|
+
- The inspector edits `where` as condition rows: a field of the chosen collection, an operator in plain words ("is", "is any of", "is after", "has all the words", "is set") and a value. The operators and the value input follow the field's type: a select's options, checked or not checked, a number, a date, or a document picker (ids are stored). Rows in a group are AND-ed. **Add "or" group** stores `{ "or": [group, group] }`. `is set` and `is empty` store Payload's `exists`. **Edit as JSON** switches to the raw query. A query the rows cannot show (a group inside a group, an unknown operator) opens as JSON, so no part of it is lost. The stored value is the same Payload `where` object either way.
|
|
2260
|
+
- A row's value can also come from elsewhere (the select next to the value): **Relative date** (`"$now-30d"`, see below), **URL parameter** (`"$query.<param>"`), and in a template **Page field** (`"$page.<path>"`, a field of the document the template renders; "This page" is its id). `listQueries` reads them when the list loads, on the site and on the canvas alike. Example: `{ "category": { "equals": "$page.category" } }` on a post template lists the posts of the same category. A page field with several values (hasMany) turns `equals` into `in`. A page field without a value makes the list empty, except with `not_equals` and `not_in`, which are then left out. A URL parameter that is not in the URL leaves its condition out, as `queryFilters` do. The canvas has no URL, so it leaves URL conditions out. In an "or", a group that matches nothing or has nothing left does not count. A JSON field of your own block gets the rows with `admin: { custom: { builderWhere: { collectionField: 'collection' } } }`, where `collectionField` names the sibling prop that holds the collection slug.
|
|
2261
|
+
- Date values in `where`, `queryFilters` and a template's `conditions` can be tokens: `"$now"`, `"$now-30d"`, `"$now+12h"` (units `d` and `h`). They become ISO dates, rounded down to the minute. Example: `{ "createdAt": { "greater_than": "$now-30d" } }` lists documents from the last 30 days.
|
|
2262
|
+
|
|
2263
|
+
```json
|
|
2264
|
+
{
|
|
2265
|
+
"type": "collectionList",
|
|
2266
|
+
"props": { "collection": "posts", "filterField": "categories", "filterBy": "current", "where": { "featured": { "equals": true } } }
|
|
2267
|
+
}
|
|
2268
|
+
```
|
|
2269
|
+
|
|
2270
|
+
Lists load with the visitor's access (`overrideAccess: false`). The site (`loadLayoutData`), the canvas and server blocks in the canvas build the same query (`listQueries`), so a template's canvas preview shows the list filtered by its sample document.
|
|
2271
|
+
|
|
2272
|
+
#### Filter by the URL query
|
|
2273
|
+
|
|
2274
|
+
`queryFilters` filters a list by the page's URL query. Each URL parameter has one of two forms:
|
|
2275
|
+
|
|
2276
|
+
- A field path (the usual case): `{ "category": "category" }`. The field equals the URL value, so `?category=news` lists the documents whose `category` is `news`. The value goes to Payload as it is, so a relationship field takes a document id (`?author=12`), and `tags.slug` reaches into related documents.
|
|
2277
|
+
- Values to `where` queries (for anything else): `{ "<param>": { "<value>": where } }`. Each `param=value` in the URL adds its `where`; unknown values are ignored.
|
|
2278
|
+
|
|
2279
|
+
```json
|
|
2280
|
+
{
|
|
2281
|
+
"type": "collectionList",
|
|
2282
|
+
"props": {
|
|
2283
|
+
"collection": "posts",
|
|
2284
|
+
"queryFilters": {
|
|
2285
|
+
"category": "category",
|
|
2286
|
+
"tag": "tags.slug",
|
|
2287
|
+
"age": { "recent": { "publishedAt": { "greater_than": "$now-30d" } } }
|
|
2288
|
+
}
|
|
2289
|
+
}
|
|
2290
|
+
}
|
|
2291
|
+
```
|
|
2292
|
+
|
|
2293
|
+
- `?category=news&age=recent` lists the news posts of the last 30 days.
|
|
2294
|
+
- Several values of one param are OR-ed: `?tag=css,react` or `?tag=css&tag=react`.
|
|
2295
|
+
- Params are AND-ed with each other and with the list's other filters. Unknown params are ignored.
|
|
2296
|
+
- The inspector edits the field-path form as rows: a URL parameter and a field of the chosen collection. **Edit as JSON** switches to the raw value. A value with the full form opens as JSON. A JSON field of your own block gets the rows with `admin: { custom: { builderQueryFilters: { collectionField: 'collection' } } }`.
|
|
2297
|
+
- Pass the query to `loadLayoutData`: `loadLayoutData(layout, blocks, payload, { query: await searchParams })`. It takes `URLSearchParams` or a Next.js `searchParams` object. Without `query`, the filters are off.
|
|
2298
|
+
- The canvas has no URL query, so it shows the list without these filters.
|
|
2299
|
+
- Filtered URLs show the same page with fewer items. Set `robots: { index: false, follow: true }` (`noindex, follow`) in the route's metadata when the URL has a filter param, so search engines index only the unfiltered page.
|
|
2300
|
+
|
|
2301
|
+
#### Picked documents, random order and pages
|
|
2302
|
+
|
|
2303
|
+
| Prop | What it does |
|
|
2304
|
+
| --- | --- |
|
|
2305
|
+
| `ids` | Picked documents, in the order you pick them. A relationship (hasMany) to the collections the list can show (with a `url`, and `listCollections`) when the plugin knows them, else a list of ids. The list shows only these, up to 100. `limit`, `sort`, `offset` and `paginate` do not apply; the other filters still do. A pick from another collection than `collection` is left out. |
|
|
2306
|
+
| `sort: "$random"` | Shuffles the newest 100 matching documents, then applies `offset` and `limit`. `loadLayoutData` picks a new seed per call, so a cached page shuffles once per cache build. Pass `randomSeed` to fix the order. The canvas keeps one order while you edit. Two random lists on a page get different orders. |
|
|
2307
|
+
| `paginate: "pages"` | Shows `limit` documents per page and page links under the items: `?page=2`, `?page=3` (`PAGE_PARAM`). The links keep the rest of the URL query (filters, other lists' pages), and page 1 has no page param. Seven pages or fewer: a link to each. More: the first, the last and the pages next to the current one, with a gap between (`1 … 4 5 6 … 20`; `pageWindow`). Pass the query to `loadLayoutData` (`query`), as for `queryFilters`, and the page's path (`path: '/guides'`): the links then start with the path, and page 1 is the bare path (`/guides`). Without `path` the links are relative, and page 1 with no other query values is `?`. `offset` does not apply. |
|
|
2308
|
+
| `pageParam` | The URL parameter of the page number. Empty: `page`. Give each paginated list on one page its own (`reviewsPage`), so they page apart. Letters, digits, `_` and `-`; any other value counts as `page`. |
|
|
2309
|
+
| `pagerLabel` | The name of the page links for screen readers (`aria-label` of the `<nav>`). Localized, default "Pages". |
|
|
2310
|
+
|
|
2311
|
+
- Style the links as parts (`partClassName`, the **Style target** select): `pager` is the `<nav>` around the links (a new list starts with `flex flex-wrap gap-2`), `pageLink` is each link. The current page has `aria-current="page"`, so `aria-[current=page]:font-bold` styles it. A gap is `<span data-page-gap aria-hidden="true">…</span>`: style it with `[&_[data-page-gap]]:` classes on `pager`.
|
|
2312
|
+
- With page links, the list renders a wrapper without classes that holds the items (with the block's classes) and then the `<nav>`, so a grid of items never takes the pager as a cell.
|
|
2313
|
+
- The page links are plain `<a href>` links, so search engines can crawl every page. Give `?page=N` pages their own canonical URL (with the page), not the first page.
|
|
2314
|
+
- Two paginated lists on one page share `page` unless one sets its own `pageParam`.
|
|
2315
|
+
- On the canvas a paginated list shows page 1 with its links.
|
|
2316
|
+
- Lists inside hidden blocks (hidden by hand or by visibility conditions) send no query on the site. The canvas shows hidden blocks dimmed, so it loads their lists.
|
|
2317
|
+
- After `loadLayoutData`, a paginated list carries its links as the runtime `$pages` prop (`LIST_PAGES_PROP`, type `ListPages`). A custom collection list component can render them its own way.
|
|
2318
|
+
- Not built: a "Load more" button. Use the page links.
|
|
2319
|
+
|
|
2320
|
+
**ItemList JSON-LD.** `loadedLists(layout)` reads the collection lists of a layout after `loadLayoutData`, with the documents each one shows, in order: `{ blockId, collection, docs }[]`. It sends no query. Hidden lists are left out. Build your structured data from it:
|
|
2321
|
+
|
|
2322
|
+
```ts
|
|
2323
|
+
import { loadedLists, loadLayoutData } from 'payload-canvas/react/server'
|
|
2324
|
+
|
|
2325
|
+
const layout = await loadLayoutData(page.layout, blocks, payload, { query: searchParams })
|
|
2326
|
+
const itemLists = loadedLists(layout).map((list) => ({
|
|
2327
|
+
'@context': 'https://schema.org',
|
|
2328
|
+
'@type': 'ItemList',
|
|
2329
|
+
itemListElement: list.docs.map((doc, i) => ({ '@type': 'ListItem', position: i + 1, url: urlOf(list.collection, doc) })),
|
|
2330
|
+
}))
|
|
2331
|
+
```
|
|
2332
|
+
|
|
2333
|
+
#### Repeat the rows of a field
|
|
2334
|
+
|
|
2335
|
+
The **Repeat** block (`repeat`) repeats its `item` slot once per row of a list field of the current document. Use it for an array field (FAQs `faqs: [{ question, answer }]`, plans `plans: [{ name, price }]`), a hasMany upload (a gallery), a hasMany relationship (the authors of a post) or a hasMany text or select field (tags).
|
|
2336
|
+
|
|
2337
|
+
| Prop | Type | What it does |
|
|
2338
|
+
| --- | --- | --- |
|
|
2339
|
+
| `path` | text, required | The field, as a dot path in the current document, for example `faqs` or `gallery`. `$parent.` and `$page.` paths work too. |
|
|
2340
|
+
| `limit` | number | The most rows to show. Empty shows every row. |
|
|
2341
|
+
| `offset` | number | Rows to skip at the start. `1` skips the first photo. |
|
|
2342
|
+
| `collection` | text (a select of the collections with a `url` when the plugin knows them) | For a relationship field: the related collection, so `$url` links to each document. A `{ relationTo, value }` row names its own collection. |
|
|
2343
|
+
| `as` | select: `div` (default), `none` | `div` wraps the rows in a `div` that takes the repeat's classes. `none` renders the rows with no wrapper, so they are direct children of the parent block: the cells of a grid, or the `li` items of a stack with `as: ul`. With `none`, the repeat's own classes and animations do nothing. On the canvas a `none` repeat is an element with `display: contents`, so the editor still selects and outlines it. |
|
|
2344
|
+
|
|
2345
|
+
Blocks in the `item` slot bind to the **row**:
|
|
2346
|
+
|
|
2347
|
+
- An array row's fields by name: `question`, `price`.
|
|
2348
|
+
- A related document's fields: `title`, `name`, `url` (uploads), and `$url` when `collection` is set.
|
|
2349
|
+
- `$item`: the row value itself. Bind an image's `image` to `$item` in a list of uploads, or a text's `text` to `$item` in a hasMany text list.
|
|
2350
|
+
- `$index`: the row number, from 1.
|
|
2351
|
+
- `$parent.<path>`: the enclosing document, for example `"Photos of {{$parent.name}}"`. `$page.<path>`: the page's document.
|
|
2352
|
+
|
|
2353
|
+
```json
|
|
2354
|
+
{
|
|
2355
|
+
"type": "repeat",
|
|
2356
|
+
"props": { "path": "gallery", "offset": 1 },
|
|
2357
|
+
"slots": { "item": [{ "type": "image", "bindings": { "image": "$item" } }] }
|
|
2358
|
+
}
|
|
2359
|
+
```
|
|
2360
|
+
|
|
2361
|
+
- The current document is the template's document, the listed document inside a collection list item, and the row inside another repeat.
|
|
2362
|
+
- Without a current document (a normal page), the site shows nothing. The canvas shows the item design once.
|
|
2363
|
+
- On the canvas, the first row is the editable one. The other rows are repeats (`data-builder-repeat`), as in a collection list. In the inspector, the field picker for `path` offers array and hasMany fields, and blocks in the item bind to the row's fields, `$item`, `$index`, `$parent` and `$page`.
|
|
2364
|
+
- After `loadLayoutData`, a repeat outside list items carries its rows as the runtime `$items` prop, like a collection list. A layout walker can read them there. A repeat inside a collection list item expands at render time, once per listed document.
|
|
2365
|
+
- Load the document with `depth: 1` (or more). Then relationship and upload rows are documents, not IDs. An ID row still gives `$item` and `$index`, but no fields.
|
|
1461
2366
|
|
|
1462
2367
|
### Render a document through its template
|
|
1463
2368
|
|
|
@@ -1479,8 +2384,8 @@ const layout = await loadLayoutData(found.layout, blocks, payload, { draft, cont
|
|
|
1479
2384
|
return <RenderLayout layout={layout} css={found.css} context={context} blocks={blocks} resolveLink={resolveLink} />
|
|
1480
2385
|
```
|
|
1481
2386
|
|
|
1482
|
-
- `loadTemplate(payload, { collection, doc, templatesSlug?, draft? })` returns `{ template, layout, css }` or `null`. Without `draft` it uses published templates only.
|
|
1483
|
-
- `loadLayoutData(layout, blocks, payload, { draft, context, resolveLink })` resolves bindings and Field blocks against `context`, loads collection lists, and loads upload and relationship props. Pass the same `context` to `RenderLayout`.
|
|
2387
|
+
- `loadTemplate(payload, { collection, doc, templatesSlug?, draft? })` returns `{ template, layout, css }` or `null`. Without `draft` it uses published templates only. The document needs its `id` for template conditions.
|
|
2388
|
+
- `loadLayoutData(layout, blocks, payload, { draft, context, resolveLink, user, query })` resolves bindings, visibility conditions and Field blocks against `context`, gives repeats their rows, loads collection lists, and loads upload and relationship props. `query` is the request's URL query for `queryFilters`. Pass the same `context` to `RenderLayout`.
|
|
1484
2389
|
- `getByPath(doc, path)` and `resolveBindings(layout, context, blocks)` from `payload-canvas/core` do the same work for a custom renderer.
|
|
1485
2390
|
|
|
1486
2391
|
## References and Used in
|
|
@@ -1551,7 +2456,7 @@ buildConfig({
|
|
|
1551
2456
|
})
|
|
1552
2457
|
```
|
|
1553
2458
|
|
|
1554
|
-
**Which props translate.** A prop translates when its field config says `localized: true`, as in Payload. A group or array that holds a localized field translates as a whole. The default blocks mark their text as localized: heading, text, rich text, button label, image alt text, list items,
|
|
2459
|
+
**Which props translate.** A prop translates when its field config says `localized: true`, as in Payload. A group or array that holds a localized field translates as a whole. The default blocks mark their text as localized: heading, text, rich text, button label, image alt text, list items, menu links and name, and the field block's fallback. Images, links, numbers, selects and checkboxes are shared. Add `localized: true` to the fields of your own blocks. Without Payload localization, `localized` does nothing.
|
|
1555
2460
|
|
|
1556
2461
|
**How it is stored.** The default language stays in `props`. Each other language keeps only its own values in `locales`:
|
|
1557
2462
|
|
|
@@ -1636,6 +2541,20 @@ The default model is `openai/gpt-6-luna`: cheap and good at tool calls. Pick ano
|
|
|
1636
2541
|
|
|
1637
2542
|
Without an adapter, or without a key, the panel shows a setup card. The card says what to set.
|
|
1638
2543
|
|
|
2544
|
+
### API keys in the admin
|
|
2545
|
+
|
|
2546
|
+
An admin can also paste the API key in the admin, without a deploy. The plugin adds an **AI settings** global (slug `builder-ai-settings`) when `ai` is set.
|
|
2547
|
+
|
|
2548
|
+
- **Precedence.** A key set there wins over the key in the adapter options (your env). Not set, or cleared: the adapter uses its own key.
|
|
2549
|
+
- **One field per provider.** The global shows a key field for the chat adapter and one for the image adapter. When both read the same env var (for example both use `OPENROUTER_API_KEY`), they share one field.
|
|
2550
|
+
- **Never shown again.** The field shows only "Set, ends in …4f2a", with **Replace key** and **Clear key**. REST and Local API reads never return the key, and the global has no GraphQL schema.
|
|
2551
|
+
- **Encrypted.** The key is stored with AES-256-GCM. The encryption key comes from Payload's `secret`. If the secret changes, the stored key cannot be read: it counts as not set, the server logs a warning, and the field says to paste the key again.
|
|
2552
|
+
- **No restart.** The server reads the key for each AI request, so a new key works on the next request. The setup card in the editor links to the settings page.
|
|
2553
|
+
- **Access.** Default: signed-in users of the admin user collection (`admin.user`). Sites with roles should allow admins only: `ai: { settings: { access: ({ req }) => req.user?.role === 'admin' } }`.
|
|
2554
|
+
- **Database.** One new global table with two text columns (`chatApiKey`, `imageApiKey`). Dev creates it on `pnpm dev` (`push: true`). Make a migration for production.
|
|
2555
|
+
|
|
2556
|
+
`ai.settings: false` turns the global off. `ai.settings: { slug }` renames it. The model stays in code: changing it starts a new chat, so it is not an admin setting.
|
|
2557
|
+
|
|
1639
2558
|
### Adapters
|
|
1640
2559
|
|
|
1641
2560
|
| Import | Adapter | Notes |
|
|
@@ -1655,7 +2574,7 @@ ai: { adapter: openAICompatibleAdapter({ baseURL: 'http://localhost:11434/v1', m
|
|
|
1655
2574
|
ai: { adapter: anthropicAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }) }
|
|
1656
2575
|
```
|
|
1657
2576
|
|
|
1658
|
-
You choose the adapter in your own config code, so you decide which environment variables to read. The starter picks `fakeAdapter()` when `BUILDER_AI_FAKE=1` (development only), else OpenRouter
|
|
2577
|
+
You choose the adapter in your own config code, so you decide which environment variables to read. The starter picks `fakeAdapter()` when `BUILDER_AI_FAKE=1` (development only), else OpenRouter. OpenRouter takes `OPENROUTER_API_KEY`, or a key an admin pastes in AI settings.
|
|
1659
2578
|
|
|
1660
2579
|
### Options
|
|
1661
2580
|
|
|
@@ -1669,6 +2588,7 @@ You choose the adapter in your own config code, so you decide which environment
|
|
|
1669
2588
|
| `images` | none | The image adapter. See [Image generation](#image-generation). |
|
|
1670
2589
|
| `imageLimits` | `{ perRequest: 3, perHour: 20 }` | Images per assistant reply, and per user per hour. |
|
|
1671
2590
|
| `imageMarkerField` | `generatedBy` | A media field that gets a note on generated images, when the collection has it. `false` turns it off. |
|
|
2591
|
+
| `settings` | on | The AI settings global for API keys. `{ slug?, access? }`, or `false` to turn it off. See [API keys in the admin](#api-keys-in-the-admin). |
|
|
1672
2592
|
|
|
1673
2593
|
The model, the key, `maxTokens` and provider settings belong to the adapter. See [providers.md](https://github.com/jon8800/payload-canvas/blob/main/docs/ai/providers.md) for each adapter's options.
|
|
1674
2594
|
|
|
@@ -1685,10 +2605,14 @@ type AiAdapter = {
|
|
|
1685
2605
|
setupProblem?: string | null // one sentence for the developer, e.g. "Set MY_API_KEY."
|
|
1686
2606
|
keyEnv?: string | null // shown in the setup card
|
|
1687
2607
|
keyUrl?: string | null // "Get an API key" link
|
|
2608
|
+
acceptsApiKey?: boolean // reads request.apiKey: AI settings show a key field for it
|
|
2609
|
+
missingKey?: boolean // ready is false only because the key is missing
|
|
1688
2610
|
stream(request: AiModelRequest): AsyncIterable<AiModelEvent>
|
|
1689
2611
|
}
|
|
1690
2612
|
```
|
|
1691
2613
|
|
|
2614
|
+
With `acceptsApiKey: true`, the request has `apiKey` when an admin set a key in AI settings. Use it instead of your own key for that request. Set `missingKey: true` when the only problem is the missing key: a key in AI settings then makes the adapter ready. Image adapters take the same two fields, and `AiImageRequest.apiKey`.
|
|
2615
|
+
|
|
1692
2616
|
`stream` runs one model call. The request has `system` (parts; `cache: true` marks a stable prefix you may cache), `messages` (the conversation), `tools`, `effort` and `signal`. Yield these events, in order:
|
|
1693
2617
|
|
|
1694
2618
|
- `{ type: 'text', text }`: assistant text as it arrives.
|
|
@@ -1826,10 +2750,16 @@ plugins: [
|
|
|
1826
2750
|
- Agents connect to `POST <your site>/api/mcp` with an API key from **Admin > MCP > API Keys**. Claude Code and Codex setup: [docs/ai/connect-claude-code-and-codex.md](https://github.com/jon8800/payload-canvas/blob/main/docs/ai/connect-claude-code-and-codex.md).
|
|
1827
2751
|
- Sign-in with the website account (OAuth, no key to copy) is a `payload-mcp-toolkit` feature: pass `oauth: { canAuthorize, access: 'editor' }` to `mcpToolkitPlugin()` and add the discovery rewrites. The starter shows the setup, and the doc above has the Claude Code and Codex commands. API keys keep working next to it.
|
|
1828
2752
|
- Tools (`listSections` and `insertSection` include [saved sections](#saved-sections)): `listBlocks`, `getBlockSchema`, `listSections`, `insertSection`, `getLayout`, `applyOperations`, `validateLayout`, `getPreviewUrl`, `generateImage`, plus `listTemplates` and `getBindingSources` for templates.
|
|
2753
|
+
- Builder layouts change only through `applyOperations` and `insertSection`. The tool descriptions say so; agents must not write the layout field with `updateDocument` or `patchLayout`.
|
|
2754
|
+
- `listBlocks` returns the layout guide (`guide`: block keys, ids, positions, classes, motion presets, HTML attributes) and the bindings guide (`bindings`). The guides are in the result, not in the tool descriptions, so `tools/list` stays small.
|
|
2755
|
+
- `update` operations take `className` (replaces the list), `addClassName` and `removeClassName` (space-separated, the other classes stay).
|
|
2756
|
+
- `applyOperations` returns `changes` (id, type, changed keys, and the new class list after class changes) and the warnings of the blocks it touched. `insertSection` returns `needsContent`: blocks whose image, form or other upload or relationship is still empty.
|
|
2757
|
+
- `visibility` and `bindings` work only in templates and inside collection list or repeat items. On a normal page they do nothing, and `applyOperations`, `insertSection` and `validateLayout` return a `no-effect` warning.
|
|
2758
|
+
- When an argument has one possible value (`collection` of the class tools, `generateImage`, `listTemplates`, and every builder tool with one builder collection), agents may leave it out.
|
|
1829
2759
|
- `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.
|
|
1830
2760
|
- Every tool checks the key's access to the collection. Handlers run as the key's user with `overrideAccess: false`.
|
|
1831
2761
|
- 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.
|
|
1832
|
-
- `builderMcpTools` options: `blocks`, `sections`, `collections` (the same map as the plugin), `siteUrl` (default: Payload `serverURL`, then `NEXT_PUBLIC_SERVER_URL`), `apiKeyCollection`, `mediaCollection` (default `media`, the same as `ai.mediaCollection`).
|
|
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`).
|
|
1833
2763
|
|
|
1834
2764
|
## Multiplayer editing
|
|
1835
2765
|
|
|
@@ -1866,6 +2796,31 @@ Limits:
|
|
|
1866
2796
|
- 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.
|
|
1867
2797
|
- Two people typing in the same text field at the same moment: the later value wins for the whole field.
|
|
1868
2798
|
|
|
2799
|
+
### Comments on the canvas
|
|
2800
|
+
|
|
2801
|
+
Team members leave comments on blocks, reply, and resolve them, as in Figma or Webflow. Everyone with the page open sees new comments, replies and changes at once.
|
|
2802
|
+
|
|
2803
|
+
In the builder:
|
|
2804
|
+
|
|
2805
|
+
- Click the speech bubble in the top bar, or press **C**, for comment mode. The comments panel takes the inspector's place. Press **C** or **Esc** to leave.
|
|
2806
|
+
- In comment mode, click a block on the canvas. A pin goes on that spot, and a box opens for the comment. **Enter** sends, **Shift+Enter** adds a line.
|
|
2807
|
+
- Pins stay on their spot of the block when the page scrolls, the layout changes or the canvas zooms. Comment mode shows the pins; normal editing shows none.
|
|
2808
|
+
- Click a pin to open its thread: reply, resolve or reopen. Authors edit and delete their own comments. Deleting a thread deletes its replies.
|
|
2809
|
+
- The panel lists the threads: open ones first, then resolved ones. **All**, **Open** and **Resolved** filter the list. Click a thread to select its block and scroll to it.
|
|
2810
|
+
- A thread whose block was deleted stays in the panel, marked **Block deleted**. It opens in the panel.
|
|
2811
|
+
- The top bar button shows the number of open threads.
|
|
2812
|
+
|
|
2813
|
+
Comments are not part of the layout. They never change the layout JSON, undo history, saves or publishing. The canvas does no comment work outside comment mode.
|
|
2814
|
+
|
|
2815
|
+
Data and access:
|
|
2816
|
+
|
|
2817
|
+
- 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
|
+
- 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
|
+
- 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.
|
|
2820
|
+
- 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
|
+
|
|
2822
|
+
Not included yet: mentions and email notifications.
|
|
2823
|
+
|
|
1869
2824
|
## Production and Docker
|
|
1870
2825
|
|
|
1871
2826
|
- **Database schema.** In development, Payload's Postgres adapter pushes schema changes on `pnpm dev`. For production, create migrations with `pnpm payload migrate:create` and run them on start with `prodMigrations` in `postgresAdapter`, or run `pnpm payload migrate` in your deploy step. Never run `payload migrate` against a development database that uses push.
|