payload-canvas 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +1799 -2
- package/dist/admin/BuilderTab.d.ts +5 -0
- package/dist/admin/BuilderTab.js +15 -0
- package/dist/admin/LayoutField.d.ts +8 -0
- package/dist/admin/LayoutField.js +50 -0
- package/dist/admin/TemplateDefaultCell.d.ts +3 -0
- package/dist/admin/TemplateDefaultCell.js +6 -0
- package/dist/admin/client.d.ts +4 -0
- package/dist/admin/client.js +9 -0
- package/dist/admin/diff/LayoutDiff.d.ts +2 -0
- package/dist/admin/diff/LayoutDiff.js +62 -0
- package/dist/admin/diff/LayoutJsonDiff.d.ts +5 -0
- package/dist/admin/diff/LayoutJsonDiff.js +17 -0
- package/dist/admin/diff/NoDiff.d.ts +1 -0
- package/dist/admin/diff/NoDiff.js +5 -0
- package/dist/admin/diff/changes.d.ts +68 -0
- package/dist/admin/diff/changes.js +347 -0
- package/dist/admin/diff/layoutDiff.scss +181 -0
- package/dist/admin/editor/Canvas.d.ts +1 -0
- package/dist/admin/editor/Canvas.js +396 -0
- package/dist/admin/editor/DragLayer.d.ts +6 -0
- package/dist/admin/editor/DragLayer.js +38 -0
- package/dist/admin/editor/Editor.d.ts +20 -0
- package/dist/admin/editor/Editor.js +175 -0
- package/dist/admin/editor/InlineToolbar.d.ts +7 -0
- package/dist/admin/editor/InlineToolbar.js +99 -0
- package/dist/admin/editor/Inspector.d.ts +1 -0
- package/dist/admin/editor/Inspector.js +131 -0
- package/dist/admin/editor/Library.d.ts +15 -0
- package/dist/admin/editor/Library.js +202 -0
- package/dist/admin/editor/Outline.d.ts +17 -0
- package/dist/admin/editor/Outline.js +343 -0
- package/dist/admin/editor/Overlay.d.ts +6 -0
- package/dist/admin/editor/Overlay.js +151 -0
- package/dist/admin/editor/actions.d.ts +65 -0
- package/dist/admin/editor/actions.js +312 -0
- package/dist/admin/editor/assistant/AssistantPanel.d.ts +4 -0
- package/dist/admin/editor/assistant/AssistantPanel.js +341 -0
- package/dist/admin/editor/assistant/ConnectAgents.d.ts +9 -0
- package/dist/admin/editor/assistant/ConnectAgents.js +72 -0
- package/dist/admin/editor/assistant/MarkdownView.d.ts +5 -0
- package/dist/admin/editor/assistant/MarkdownView.js +38 -0
- package/dist/admin/editor/assistant/assistant.scss +944 -0
- package/dist/admin/editor/assistant/controller.d.ts +72 -0
- package/dist/admin/editor/assistant/controller.js +423 -0
- package/dist/admin/editor/assistant/history.d.ts +120 -0
- package/dist/admin/editor/assistant/history.js +243 -0
- package/dist/admin/editor/assistant/markdown.d.ts +38 -0
- package/dist/admin/editor/assistant/markdown.js +118 -0
- package/dist/admin/editor/assistant/sse.d.ts +7 -0
- package/dist/admin/editor/assistant/sse.js +48 -0
- package/dist/admin/editor/dnd/displace.d.ts +76 -0
- package/dist/admin/editor/dnd/displace.js +353 -0
- package/dist/admin/editor/dnd/dnd.scss +218 -0
- package/dist/admin/editor/dnd/mode.d.ts +12 -0
- package/dist/admin/editor/dnd/mode.js +53 -0
- package/dist/admin/editor/dnd/smooth.d.ts +52 -0
- package/dist/admin/editor/dnd/smooth.js +588 -0
- package/dist/admin/editor/editor.scss +2593 -0
- package/dist/admin/editor/empty/EmptyStart.d.ts +2 -0
- package/dist/admin/editor/empty/EmptyStart.js +127 -0
- package/dist/admin/editor/empty/empty.scss +92 -0
- package/dist/admin/editor/fields/ArrayField.d.ts +22 -0
- package/dist/admin/editor/fields/ArrayField.js +78 -0
- package/dist/admin/editor/fields/CheckedInputs.d.ts +35 -0
- package/dist/admin/editor/fields/CheckedInputs.js +61 -0
- package/dist/admin/editor/fields/FieldProblems.d.ts +11 -0
- package/dist/admin/editor/fields/FieldProblems.js +69 -0
- package/dist/admin/editor/fields/GroupField.d.ts +22 -0
- package/dist/admin/editor/fields/GroupField.js +14 -0
- package/dist/admin/editor/fields/JsonField.d.ts +14 -0
- package/dist/admin/editor/fields/JsonField.js +28 -0
- package/dist/admin/editor/fields/ManyValuesField.d.ts +13 -0
- package/dist/admin/editor/fields/ManyValuesField.js +21 -0
- package/dist/admin/editor/fields/PointField.d.ts +15 -0
- package/dist/admin/editor/fields/PointField.js +25 -0
- package/dist/admin/editor/fields/RichTextField.d.ts +22 -0
- package/dist/admin/editor/fields/RichTextField.js +47 -0
- package/dist/admin/editor/fields/access.d.ts +36 -0
- package/dist/admin/editor/fields/access.js +96 -0
- package/dist/admin/editor/fields/accessRules.d.ts +13 -0
- package/dist/admin/editor/fields/accessRules.js +23 -0
- package/dist/admin/editor/fields/arrayRows.d.ts +28 -0
- package/dist/admin/editor/fields/arrayRows.js +91 -0
- package/dist/admin/editor/fields/arrayState.d.ts +20 -0
- package/dist/admin/editor/fields/arrayState.js +101 -0
- package/dist/admin/editor/fields/fields.scss +316 -0
- package/dist/admin/editor/fields/undoPath.d.ts +8 -0
- package/dist/admin/editor/fields/undoPath.js +55 -0
- package/dist/admin/editor/fields/values.d.ts +67 -0
- package/dist/admin/editor/fields/values.js +151 -0
- package/dist/admin/editor/generate/GenerateImage.d.ts +11 -0
- package/dist/admin/editor/generate/GenerateImage.js +108 -0
- package/dist/admin/editor/generate/generate.scss +276 -0
- package/dist/admin/editor/icons.d.ts +88 -0
- package/dist/admin/editor/icons.js +94 -0
- package/dist/admin/editor/inline.d.ts +67 -0
- package/dist/admin/editor/inline.js +122 -0
- package/dist/admin/editor/insert/InsertHandle.d.ts +1 -0
- package/dist/admin/editor/insert/InsertHandle.js +118 -0
- package/dist/admin/editor/insert/picker.d.ts +37 -0
- package/dist/admin/editor/insert/picker.js +53 -0
- package/dist/admin/editor/insert/spots.d.ts +43 -0
- package/dist/admin/editor/insert/spots.js +186 -0
- package/dist/admin/editor/layout/FrameResize.d.ts +12 -0
- package/dist/admin/editor/layout/FrameResize.js +127 -0
- package/dist/admin/editor/layout/LeftPanel.d.ts +1 -0
- package/dist/admin/editor/layout/LeftPanel.js +106 -0
- package/dist/admin/editor/layout/Splitter.d.ts +8 -0
- package/dist/admin/editor/layout/Splitter.js +126 -0
- package/dist/admin/editor/layout/frameWidth.d.ts +14 -0
- package/dist/admin/editor/layout/frameWidth.js +21 -0
- package/dist/admin/editor/layout/layout.scss +240 -0
- package/dist/admin/editor/layout/leftTabs.d.ts +22 -0
- package/dist/admin/editor/layout/leftTabs.js +48 -0
- package/dist/admin/editor/layout/panels.d.ts +22 -0
- package/dist/admin/editor/layout/panels.js +57 -0
- package/dist/admin/editor/live/PresenceUI.d.ts +27 -0
- package/dist/admin/editor/live/PresenceUI.js +202 -0
- package/dist/admin/editor/live/field.d.ts +13 -0
- package/dist/admin/editor/live/field.js +40 -0
- package/dist/admin/editor/live/index.d.ts +4 -0
- package/dist/admin/editor/live/index.js +5 -0
- package/dist/admin/editor/live/presence.d.ts +28 -0
- package/dist/admin/editor/live/presence.js +122 -0
- package/dist/admin/editor/live/presence.scss +24 -0
- package/dist/admin/editor/live/sync.d.ts +109 -0
- package/dist/admin/editor/live/sync.js +373 -0
- package/dist/admin/editor/live/useFollow.d.ts +2 -0
- package/dist/admin/editor/live/useFollow.js +78 -0
- package/dist/admin/editor/live/useMultiplayer.d.ts +52 -0
- package/dist/admin/editor/live/useMultiplayer.js +442 -0
- package/dist/admin/editor/locale/LocaleField.d.ts +30 -0
- package/dist/admin/editor/locale/LocaleField.js +167 -0
- package/dist/admin/editor/locale/LocaleSwitcher.d.ts +2 -0
- package/dist/admin/editor/locale/LocaleSwitcher.js +33 -0
- package/dist/admin/editor/locale/locale.d.ts +38 -0
- package/dist/admin/editor/locale/locale.js +145 -0
- package/dist/admin/editor/locale/locale.scss +154 -0
- package/dist/admin/editor/media/ImageEditor.d.ts +3 -0
- package/dist/admin/editor/media/ImageEditor.js +215 -0
- package/dist/admin/editor/media/actions.d.ts +58 -0
- package/dist/admin/editor/media/actions.js +168 -0
- package/dist/admin/editor/media/media.scss +223 -0
- package/dist/admin/editor/media/model.d.ts +37 -0
- package/dist/admin/editor/media/model.js +94 -0
- package/dist/admin/editor/menu/Menu.d.ts +65 -0
- package/dist/admin/editor/menu/Menu.js +110 -0
- package/dist/admin/editor/menu/blockMenu.d.ts +13 -0
- package/dist/admin/editor/menu/blockMenu.js +104 -0
- package/dist/admin/editor/menu/dismiss.d.ts +4 -0
- package/dist/admin/editor/menu/dismiss.js +19 -0
- package/dist/admin/editor/menu/keys.d.ts +21 -0
- package/dist/admin/editor/menu/keys.js +35 -0
- package/dist/admin/editor/menu/menu.scss +132 -0
- package/dist/admin/editor/menu/requests.d.ts +39 -0
- package/dist/admin/editor/menu/requests.js +82 -0
- package/dist/admin/editor/menu/styleClipboard.d.ts +25 -0
- package/dist/admin/editor/menu/styleClipboard.js +61 -0
- package/dist/admin/editor/menu/useCanvasMenus.d.ts +2 -0
- package/dist/admin/editor/menu/useCanvasMenus.js +46 -0
- package/dist/admin/editor/motion/MotionPanel.d.ts +11 -0
- package/dist/admin/editor/motion/MotionPanel.js +117 -0
- package/dist/admin/editor/motion/model.d.ts +33 -0
- package/dist/admin/editor/motion/model.js +84 -0
- package/dist/admin/editor/motion/motion.scss +84 -0
- package/dist/admin/editor/motion/play.d.ts +6 -0
- package/dist/admin/editor/motion/play.js +39 -0
- package/dist/admin/editor/names.d.ts +17 -0
- package/dist/admin/editor/names.js +149 -0
- package/dist/admin/editor/placement.d.ts +22 -0
- package/dist/admin/editor/placement.js +49 -0
- package/dist/admin/editor/renderField.d.ts +52 -0
- package/dist/admin/editor/renderField.js +287 -0
- package/dist/admin/editor/runtime.d.ts +134 -0
- package/dist/admin/editor/runtime.js +231 -0
- package/dist/admin/editor/sections/SectionDialog.d.ts +8 -0
- package/dist/admin/editor/sections/SectionDialog.js +101 -0
- package/dist/admin/editor/sections/controller.d.ts +30 -0
- package/dist/admin/editor/sections/controller.js +116 -0
- package/dist/admin/editor/sections/thumbnailCache.d.ts +2 -0
- package/dist/admin/editor/sections/thumbnailCache.js +81 -0
- package/dist/admin/editor/sections/thumbnailKey.d.ts +12 -0
- package/dist/admin/editor/sections/thumbnailKey.js +49 -0
- package/dist/admin/editor/sections/thumbnails.d.ts +35 -0
- package/dist/admin/editor/sections/thumbnails.js +214 -0
- package/dist/admin/editor/sections/useThumbnail.d.ts +8 -0
- package/dist/admin/editor/sections/useThumbnail.js +48 -0
- package/dist/admin/editor/shortcuts.d.ts +38 -0
- package/dist/admin/editor/shortcuts.js +315 -0
- package/dist/admin/editor/store.d.ts +147 -0
- package/dist/admin/editor/store.js +331 -0
- package/dist/admin/editor/styles/BoxModel.d.ts +17 -0
- package/dist/admin/editor/styles/BoxModel.js +37 -0
- package/dist/admin/editor/styles/ColorPicker.d.ts +9 -0
- package/dist/admin/editor/styles/ColorPicker.js +152 -0
- package/dist/admin/editor/styles/RawClasses.d.ts +8 -0
- package/dist/admin/editor/styles/RawClasses.js +134 -0
- package/dist/admin/editor/styles/StylesPanel.d.ts +5 -0
- package/dist/admin/editor/styles/StylesPanel.js +46 -0
- package/dist/admin/editor/styles/VariantBar.d.ts +4 -0
- package/dist/admin/editor/styles/VariantBar.js +50 -0
- package/dist/admin/editor/styles/context.d.ts +35 -0
- package/dist/admin/editor/styles/context.js +38 -0
- package/dist/admin/editor/styles/controls.d.ts +98 -0
- package/dist/admin/editor/styles/controls.js +318 -0
- package/dist/admin/editor/styles/icons.d.ts +30 -0
- package/dist/admin/editor/styles/icons.js +48 -0
- package/dist/admin/editor/styles/model.d.ts +27 -0
- package/dist/admin/editor/styles/model.js +75 -0
- package/dist/admin/editor/styles/popover.d.ts +46 -0
- package/dist/admin/editor/styles/popover.js +159 -0
- package/dist/admin/editor/styles/sections.d.ts +1 -0
- package/dist/admin/editor/styles/sections.js +167 -0
- package/dist/admin/editor/styles/styles.scss +1147 -0
- package/dist/admin/editor/styles/tokens.d.ts +35 -0
- package/dist/admin/editor/styles/tokens.js +136 -0
- package/dist/admin/editor/styles/useProp.d.ts +20 -0
- package/dist/admin/editor/styles/useProp.js +31 -0
- package/dist/admin/editor/styles/viewport.d.ts +8 -0
- package/dist/admin/editor/styles/viewport.js +24 -0
- package/dist/admin/editor/templates/Bindable.d.ts +43 -0
- package/dist/admin/editor/templates/Bindable.js +234 -0
- package/dist/admin/editor/templates/FieldPicker.d.ts +23 -0
- package/dist/admin/editor/templates/FieldPicker.js +96 -0
- package/dist/admin/editor/templates/SamplePicker.d.ts +5 -0
- package/dist/admin/editor/templates/SamplePicker.js +86 -0
- package/dist/admin/editor/templates/binding.d.ts +82 -0
- package/dist/admin/editor/templates/binding.js +296 -0
- package/dist/admin/editor/templates/state.d.ts +30 -0
- package/dist/admin/editor/templates/state.js +20 -0
- package/dist/admin/editor/templates/templates.scss +627 -0
- package/dist/admin/editor/templates/useTemplate.d.ts +38 -0
- package/dist/admin/editor/templates/useTemplate.js +207 -0
- package/dist/admin/editor/tooltip/Tooltips.d.ts +2 -0
- package/dist/admin/editor/tooltip/Tooltips.js +26 -0
- package/dist/admin/editor/tooltip/controller.d.ts +3 -0
- package/dist/admin/editor/tooltip/controller.js +185 -0
- package/dist/admin/editor/tooltip/place.d.ts +22 -0
- package/dist/admin/editor/tooltip/place.js +38 -0
- package/dist/admin/editor/tooltip/tooltip.scss +39 -0
- package/dist/admin/editor/topbar/DocumentActions.d.ts +21 -0
- package/dist/admin/editor/topbar/DocumentActions.js +243 -0
- package/dist/admin/editor/topbar/DocumentTitle.d.ts +21 -0
- package/dist/admin/editor/topbar/DocumentTitle.js +167 -0
- package/dist/admin/editor/topbar/TopBar.d.ts +11 -0
- package/dist/admin/editor/topbar/TopBar.js +148 -0
- package/dist/admin/editor/topbar/document.d.ts +80 -0
- package/dist/admin/editor/topbar/document.js +245 -0
- package/dist/admin/editor/topbar/problems.d.ts +30 -0
- package/dist/admin/editor/topbar/problems.js +113 -0
- package/dist/admin/editor/topbar/saveTime.d.ts +14 -0
- package/dist/admin/editor/topbar/saveTime.js +19 -0
- package/dist/admin/editor/topbar/screens/DrawerRouter.d.ts +36 -0
- package/dist/admin/editor/topbar/screens/DrawerRouter.js +122 -0
- package/dist/admin/editor/topbar/screens/DrawerWidth.d.ts +4 -0
- package/dist/admin/editor/topbar/screens/DrawerWidth.js +14 -0
- package/dist/admin/editor/topbar/screens/ScreenDrawer.d.ts +3 -0
- package/dist/admin/editor/topbar/screens/ScreenDrawer.js +218 -0
- package/dist/admin/editor/topbar/screens/drawerRouterSupport.d.ts +54 -0
- package/dist/admin/editor/topbar/screens/drawerRouterSupport.js +71 -0
- package/dist/admin/editor/topbar/screens/screens.scss +134 -0
- package/dist/admin/editor/topbar/settingsDrawer.d.ts +9 -0
- package/dist/admin/editor/topbar/settingsDrawer.js +75 -0
- package/dist/admin/editor/topbar/settingsDrawer.scss +32 -0
- package/dist/admin/editor/topbar/topbar.scss +683 -0
- package/dist/admin/editor/topbar/useDismiss.d.ts +6 -0
- package/dist/admin/editor/topbar/useDismiss.js +35 -0
- package/dist/admin/editor/ui/Select.d.ts +33 -0
- package/dist/admin/editor/ui/Select.js +81 -0
- package/dist/admin/editor/ui/Slider.d.ts +16 -0
- package/dist/admin/editor/ui/Slider.js +11 -0
- package/dist/admin/editor/ui/controls.scss +320 -0
- package/dist/admin/editor/ui/modalA11y.d.ts +7 -0
- package/dist/admin/editor/ui/modalA11y.js +36 -0
- package/dist/admin/editor/ui/payloadA11y.d.ts +3 -0
- package/dist/admin/editor/ui/payloadA11y.js +70 -0
- package/dist/admin/editor/valueStore.d.ts +30 -0
- package/dist/admin/editor/valueStore.js +59 -0
- package/dist/admin/rsc.d.ts +4 -0
- package/dist/admin/rsc.js +9 -0
- package/dist/admin/screen/BuilderScreen.d.ts +19 -0
- package/dist/admin/screen/BuilderScreen.js +30 -0
- package/dist/admin/server/BuilderRedirect.d.ts +6 -0
- package/dist/admin/server/BuilderRedirect.js +12 -0
- package/dist/admin/server/BuilderView.d.ts +10 -0
- package/dist/admin/server/BuilderView.js +73 -0
- package/dist/ai/adapters/anthropic.d.ts +73 -0
- package/dist/ai/adapters/anthropic.js +200 -0
- package/dist/ai/adapters/cloudflare-gateway.d.ts +21 -0
- package/dist/ai/adapters/cloudflare-gateway.js +47 -0
- package/dist/ai/adapters/cloudflare-workers-ai.d.ts +15 -0
- package/dist/ai/adapters/cloudflare-workers-ai.js +45 -0
- package/dist/ai/adapters/fake.d.ts +29 -0
- package/dist/ai/adapters/fake.js +154 -0
- package/dist/ai/adapters/openai-compatible.d.ts +19 -0
- package/dist/ai/adapters/openai-compatible.js +46 -0
- package/dist/ai/adapters/openrouter.d.ts +20 -0
- package/dist/ai/adapters/openrouter.js +44 -0
- package/dist/ai/config.d.ts +13 -0
- package/dist/ai/config.js +49 -0
- package/dist/ai/endpoint.d.ts +45 -0
- package/dist/ai/endpoint.js +420 -0
- package/dist/ai/images/cloudflare-workers-ai.d.ts +20 -0
- package/dist/ai/images/cloudflare-workers-ai.js +103 -0
- package/dist/ai/images/fake.d.ts +17 -0
- package/dist/ai/images/fake.js +102 -0
- package/dist/ai/images/openai.d.ts +32 -0
- package/dist/ai/images/openai.js +104 -0
- package/dist/ai/images/openrouter.d.ts +24 -0
- package/dist/ai/images/openrouter.js +132 -0
- package/dist/ai/images/ratios.d.ts +4 -0
- package/dist/ai/images/ratios.js +6 -0
- package/dist/ai/images/service.d.ts +111 -0
- package/dist/ai/images/service.js +306 -0
- package/dist/ai/images/shared.d.ts +86 -0
- package/dist/ai/images/shared.js +201 -0
- package/dist/ai/index.d.ts +4 -0
- package/dist/ai/index.js +3 -0
- package/dist/ai/loop.d.ts +40 -0
- package/dist/ai/loop.js +260 -0
- package/dist/ai/openai-format.d.ts +115 -0
- package/dist/ai/openai-format.js +605 -0
- package/dist/ai/prompt.d.ts +52 -0
- package/dist/ai/prompt.js +231 -0
- package/dist/ai/sse.d.ts +9 -0
- package/dist/ai/sse.js +57 -0
- package/dist/ai/tools.d.ts +114 -0
- package/dist/ai/tools.js +810 -0
- package/dist/ai/types.d.ts +343 -0
- package/dist/ai/types.js +6 -0
- package/dist/blocks/defaults.d.ts +54 -0
- package/dist/blocks/defaults.js +578 -0
- package/dist/blocks/index.d.ts +6 -0
- package/dist/blocks/index.js +8 -0
- package/dist/blocks/link.d.ts +34 -0
- package/dist/blocks/link.js +57 -0
- package/dist/blocks/payload.d.ts +62 -0
- package/dist/blocks/payload.js +223 -0
- package/dist/core/bindings.d.ts +121 -0
- package/dist/core/bindings.js +441 -0
- package/dist/core/blocks.d.ts +56 -0
- package/dist/core/blocks.js +170 -0
- package/dist/core/classes.d.ts +6 -0
- package/dist/core/classes.js +29 -0
- package/dist/core/conditions.d.ts +31 -0
- package/dist/core/conditions.js +156 -0
- package/dist/core/convertPayload.d.ts +134 -0
- package/dist/core/convertPayload.js +475 -0
- package/dist/core/dropTarget.d.ts +23 -0
- package/dist/core/dropTarget.js +268 -0
- package/dist/core/fieldAccess.d.ts +95 -0
- package/dist/core/fieldAccess.js +363 -0
- package/dist/core/fieldHooks.d.ts +44 -0
- package/dist/core/fieldHooks.js +83 -0
- package/dist/core/fieldSemantics.d.ts +97 -0
- package/dist/core/fieldSemantics.js +346 -0
- package/dist/core/fieldValidate.d.ts +34 -0
- package/dist/core/fieldValidate.js +88 -0
- package/dist/core/fields.d.ts +67 -0
- package/dist/core/fields.js +106 -0
- package/dist/core/formats.d.ts +37 -0
- package/dist/core/formats.js +146 -0
- package/dist/core/ids.d.ts +2 -0
- package/dist/core/ids.js +12 -0
- package/dist/core/index.d.ts +20 -0
- package/dist/core/index.js +22 -0
- package/dist/core/issues.d.ts +30 -0
- package/dist/core/issues.js +173 -0
- package/dist/core/locale.d.ts +143 -0
- package/dist/core/locale.js +678 -0
- package/dist/core/motion.d.ts +245 -0
- package/dist/core/motion.js +477 -0
- package/dist/core/operations.d.ts +13 -0
- package/dist/core/operations.js +448 -0
- package/dist/core/references.d.ts +35 -0
- package/dist/core/references.js +188 -0
- package/dist/core/schema.d.ts +9 -0
- package/dist/core/schema.js +299 -0
- package/dist/core/styles/edit.d.ts +42 -0
- package/dist/core/styles/edit.js +165 -0
- package/dist/core/styles/parse.d.ts +18 -0
- package/dist/core/styles/parse.js +93 -0
- package/dist/core/styles/properties.d.ts +55 -0
- package/dist/core/styles/properties.js +264 -0
- package/dist/core/styles/types.d.ts +87 -0
- package/dist/core/styles/types.js +5 -0
- package/dist/core/styles/values.d.ts +52 -0
- package/dist/core/styles/values.js +264 -0
- package/dist/core/styles.d.ts +4 -0
- package/dist/core/styles.js +18 -0
- package/dist/core/textList.d.ts +30 -0
- package/dist/core/textList.js +92 -0
- package/dist/core/tree.d.ts +27 -0
- package/dist/core/tree.js +203 -0
- package/dist/core/types.d.ts +390 -0
- package/dist/core/types.js +4 -0
- package/dist/core/validate.d.ts +39 -0
- package/dist/core/validate.js +402 -0
- package/dist/css/browser.d.ts +17 -0
- package/dist/css/browser.js +23 -0
- package/dist/css/index.d.ts +45 -0
- package/dist/css/index.js +236 -0
- package/dist/css/marker.d.ts +15 -0
- package/dist/css/marker.js +20 -0
- package/dist/css/shared.d.ts +64 -0
- package/dist/css/shared.js +225 -0
- package/dist/css/tokens.d.ts +34 -0
- package/dist/css/tokens.js +277 -0
- package/dist/index.d.ts +14 -0
- package/dist/index.js +12 -0
- package/dist/live/apply.d.ts +56 -0
- package/dist/live/apply.js +122 -0
- package/dist/live/document.d.ts +132 -0
- package/dist/live/document.js +533 -0
- package/dist/live/endpoints.d.ts +55 -0
- package/dist/live/endpoints.js +413 -0
- package/dist/live/fieldChecks.d.ts +64 -0
- package/dist/live/fieldChecks.js +143 -0
- package/dist/live/fieldsGuard.d.ts +168 -0
- package/dist/live/fieldsGuard.js +319 -0
- package/dist/live/index.d.ts +8 -0
- package/dist/live/index.js +11 -0
- package/dist/live/mutex.d.ts +11 -0
- package/dist/live/mutex.js +18 -0
- package/dist/live/runtime.d.ts +35 -0
- package/dist/live/runtime.js +130 -0
- package/dist/live/session.d.ts +198 -0
- package/dist/live/session.js +719 -0
- package/dist/live/staleMessages.d.ts +6 -0
- package/dist/live/staleMessages.js +45 -0
- package/dist/live/types.d.ts +353 -0
- package/dist/live/types.js +3 -0
- package/dist/mcp/index.d.ts +50 -0
- package/dist/mcp/index.js +674 -0
- package/dist/mcp/shared.d.ts +89 -0
- package/dist/mcp/shared.js +189 -0
- package/dist/migrate/index.d.ts +130 -0
- package/dist/migrate/index.js +332 -0
- package/dist/plugin/hook.d.ts +168 -0
- package/dist/plugin/hook.js +430 -0
- package/dist/plugin/index.d.ts +141 -0
- package/dist/plugin/index.js +525 -0
- package/dist/plugin/jsonSafe.d.ts +6 -0
- package/dist/plugin/jsonSafe.js +44 -0
- package/dist/plugin/labels.d.ts +5 -0
- package/dist/plugin/labels.js +19 -0
- package/dist/plugin/links.d.ts +7 -0
- package/dist/plugin/links.js +43 -0
- package/dist/plugin/listCollections.d.ts +7 -0
- package/dist/plugin/listCollections.js +18 -0
- package/dist/plugin/references.d.ts +118 -0
- package/dist/plugin/references.js +355 -0
- package/dist/plugin/sections.d.ts +76 -0
- package/dist/plugin/sections.js +221 -0
- package/dist/plugin/sectionsBuilder.d.ts +9 -0
- package/dist/plugin/sectionsBuilder.js +23 -0
- package/dist/plugin/templates.d.ts +51 -0
- package/dist/plugin/templates.js +274 -0
- package/dist/protocol/index.d.ts +383 -0
- package/dist/protocol/index.js +78 -0
- package/dist/protocol/motion.d.ts +37 -0
- package/dist/protocol/motion.js +49 -0
- package/dist/react/canvas/BuilderCanvas.d.ts +33 -0
- package/dist/react/canvas/BuilderCanvas.js +772 -0
- package/dist/react/canvas/ServerBlock.d.ts +16 -0
- package/dist/react/canvas/ServerBlock.js +79 -0
- package/dist/react/canvas/drag.d.ts +20 -0
- package/dist/react/canvas/drag.js +397 -0
- package/dist/react/canvas/fetchDocs.d.ts +20 -0
- package/dist/react/canvas/fetchDocs.js +89 -0
- package/dist/react/canvas/index.d.ts +2 -0
- package/dist/react/canvas/index.js +3 -0
- package/dist/react/canvas/inline/candidates.d.ts +46 -0
- package/dist/react/canvas/inline/candidates.js +195 -0
- package/dist/react/canvas/inline/dom.d.ts +45 -0
- package/dist/react/canvas/inline/dom.js +138 -0
- package/dist/react/canvas/inline/mapper.d.ts +49 -0
- package/dist/react/canvas/inline/mapper.js +440 -0
- package/dist/react/canvas/inline/model.d.ts +40 -0
- package/dist/react/canvas/inline/model.js +130 -0
- package/dist/react/canvas/inline/rich/editor.d.ts +22 -0
- package/dist/react/canvas/inline/rich/editor.js +158 -0
- package/dist/react/canvas/inline/rich/index.d.ts +6 -0
- package/dist/react/canvas/inline/rich/index.js +109 -0
- package/dist/react/canvas/inline/rich/nodes.d.ts +72 -0
- package/dist/react/canvas/inline/rich/nodes.js +326 -0
- package/dist/react/canvas/inline/session.d.ts +52 -0
- package/dist/react/canvas/inline/session.js +179 -0
- package/dist/react/canvas/measure.d.ts +11 -0
- package/dist/react/canvas/measure.js +67 -0
- package/dist/react/canvas/motion.d.ts +14 -0
- package/dist/react/canvas/motion.js +60 -0
- package/dist/react/canvas/resolveLayout.d.ts +8 -0
- package/dist/react/canvas/resolveLayout.js +15 -0
- package/dist/react/canvas/serverBlocks.d.ts +51 -0
- package/dist/react/canvas/serverBlocks.js +184 -0
- package/dist/react/canvas/serverComponents.d.ts +9 -0
- package/dist/react/canvas/serverComponents.js +20 -0
- package/dist/react/canvas/share.d.ts +6 -0
- package/dist/react/canvas/share.js +42 -0
- package/dist/react/canvas/thumbnail/ThumbnailCanvas.d.ts +2 -0
- package/dist/react/canvas/thumbnail/ThumbnailCanvas.js +155 -0
- package/dist/react/canvas/thumbnail/capture.d.ts +17 -0
- package/dist/react/canvas/thumbnail/capture.js +292 -0
- package/dist/react/canvas/thumbnail/css.d.ts +28 -0
- package/dist/react/canvas/thumbnail/css.js +83 -0
- package/dist/react/components/Button.d.ts +3 -0
- package/dist/react/components/Button.js +16 -0
- package/dist/react/components/CollectionList.d.ts +6 -0
- package/dist/react/components/CollectionList.js +12 -0
- package/dist/react/components/Container.d.ts +5 -0
- package/dist/react/components/Container.js +7 -0
- package/dist/react/components/Divider.d.ts +2 -0
- package/dist/react/components/Divider.js +4 -0
- package/dist/react/components/Field.d.ts +6 -0
- package/dist/react/components/Field.js +59 -0
- package/dist/react/components/Heading.d.ts +4 -0
- package/dist/react/components/Heading.js +17 -0
- package/dist/react/components/Image.d.ts +9 -0
- package/dist/react/components/Image.js +53 -0
- package/dist/react/components/Link.d.ts +3 -0
- package/dist/react/components/Link.js +10 -0
- package/dist/react/components/List.d.ts +22 -0
- package/dist/react/components/List.js +57 -0
- package/dist/react/components/Menu.d.ts +4 -0
- package/dist/react/components/Menu.js +110 -0
- package/dist/react/components/Quote.d.ts +3 -0
- package/dist/react/components/Quote.js +12 -0
- package/dist/react/components/RichText.d.ts +10 -0
- package/dist/react/components/RichText.js +77 -0
- package/dist/react/components/Spacer.d.ts +3 -0
- package/dist/react/components/Spacer.js +6 -0
- package/dist/react/components/Text.d.ts +5 -0
- package/dist/react/components/Text.js +14 -0
- package/dist/react/components/Video.d.ts +6 -0
- package/dist/react/components/Video.js +68 -0
- package/dist/react/components/index.d.ts +2 -0
- package/dist/react/components/index.js +34 -0
- package/dist/react/components/placeholder.d.ts +13 -0
- package/dist/react/components/placeholder.js +25 -0
- package/dist/react/components/videoUrl.d.ts +1 -0
- package/dist/react/components/videoUrl.js +3 -0
- package/dist/react/index.d.ts +18 -0
- package/dist/react/index.js +19 -0
- package/dist/react/motion/MotionRuntime.d.ts +9 -0
- package/dist/react/motion/MotionRuntime.js +25 -0
- package/dist/react/motion/runtime.d.ts +20 -0
- package/dist/react/motion/runtime.js +588 -0
- package/dist/react/motion/style.d.ts +35 -0
- package/dist/react/motion/style.js +124 -0
- package/dist/react/render/PayloadRoot.d.ts +22 -0
- package/dist/react/render/PayloadRoot.js +102 -0
- package/dist/react/render/RenderLayout.d.ts +26 -0
- package/dist/react/render/RenderLayout.js +217 -0
- package/dist/react/render/SlotOutlet.d.ts +14 -0
- package/dist/react/render/SlotOutlet.js +16 -0
- package/dist/react/render/canvasServer.d.ts +65 -0
- package/dist/react/render/canvasServer.js +150 -0
- package/dist/react/render/canvasServerTypes.d.ts +61 -0
- package/dist/react/render/canvasServerTypes.js +3 -0
- package/dist/react/render/editable.d.ts +28 -0
- package/dist/react/render/editable.js +32 -0
- package/dist/react/render/fields.d.ts +31 -0
- package/dist/react/render/fields.js +69 -0
- package/dist/react/render/link.d.ts +17 -0
- package/dist/react/render/link.js +49 -0
- package/dist/react/render/lists.d.ts +18 -0
- package/dist/react/render/lists.js +49 -0
- package/dist/react/render/locale.d.ts +24 -0
- package/dist/react/render/locale.js +27 -0
- package/dist/react/render/marks.d.ts +16 -0
- package/dist/react/render/marks.js +24 -0
- package/dist/react/render/payload.d.ts +127 -0
- package/dist/react/render/payload.js +91 -0
- package/dist/react/render/resolve.d.ts +34 -0
- package/dist/react/render/resolve.js +182 -0
- package/dist/react/render/types.d.ts +103 -0
- package/dist/react/render/types.js +2 -0
- package/dist/react/server.d.ts +61 -0
- package/dist/react/server.js +122 -0
- package/dist/react/theme/ThemeLive.d.ts +16 -0
- package/dist/react/theme/ThemeLive.js +76 -0
- package/dist/react/theme/ThemeStyle.d.ts +29 -0
- package/dist/react/theme/ThemeStyle.js +32 -0
- package/dist/react/theme/constants.d.ts +12 -0
- package/dist/react/theme/constants.js +19 -0
- package/dist/theme/admin/ColorField.d.ts +4 -0
- package/dist/theme/admin/ColorField.js +49 -0
- package/dist/theme/admin/FieldShell.d.ts +18 -0
- package/dist/theme/admin/FieldShell.js +12 -0
- package/dist/theme/admin/FontField.d.ts +4 -0
- package/dist/theme/admin/FontField.js +60 -0
- package/dist/theme/admin/SaveSignal.d.ts +5 -0
- package/dist/theme/admin/SaveSignal.js +23 -0
- package/dist/theme/admin/SliderField.d.ts +21 -0
- package/dist/theme/admin/SliderField.js +28 -0
- package/dist/theme/admin/fields.scss +250 -0
- package/dist/theme/admin/googleFonts.d.ts +2 -0
- package/dist/theme/admin/googleFonts.js +3 -0
- package/dist/theme/client.d.ts +4 -0
- package/dist/theme/client.js +11 -0
- package/dist/theme/colors.d.ts +32 -0
- package/dist/theme/colors.js +142 -0
- package/dist/theme/config.d.ts +39 -0
- package/dist/theme/config.js +13 -0
- package/dist/theme/css.d.ts +57 -0
- package/dist/theme/css.js +90 -0
- package/dist/theme/fallbacks.d.ts +9 -0
- package/dist/theme/fallbacks.js +119 -0
- package/dist/theme/global.d.ts +5 -0
- package/dist/theme/global.js +124 -0
- package/dist/theme/index.d.ts +3 -0
- package/dist/theme/index.js +5 -0
- package/package.json +213 -3
package/README.md
CHANGED
|
@@ -1,3 +1,1800 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Payload Canvas
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
The npm package is `payload-canvas`.
|
|
6
|
+
|
|
7
|
+
- Works in any Payload 3.90+ app on Next.js 16 and React 19.
|
|
8
|
+
- The layout is one JSON field per document. Nothing changes in your other fields.
|
|
9
|
+
- The site renders the layout with `payload-canvas/react` (React Server Components), or with your own renderer.
|
|
10
|
+
- Save, drafts, autosave, versions and access control stay Payload's own.
|
|
11
|
+
- Several people (and AI agents) can edit one page at the same time. See [Multiplayer editing](#multiplayer-editing).
|
|
12
|
+
|
|
13
|
+
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).
|
|
14
|
+
|
|
15
|
+
**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:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npx create-payload-canvas my-website
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Contents
|
|
22
|
+
|
|
23
|
+
1. [Requirements](#requirements)
|
|
24
|
+
2. [Install](#install)
|
|
25
|
+
3. [The builder view](#the-builder-view)
|
|
26
|
+
4. [Inline editing](#inline-editing)
|
|
27
|
+
5. [Plugin options](#plugin-options)
|
|
28
|
+
6. [Rendering the layout on your site](#rendering-the-layout-on-your-site)
|
|
29
|
+
- [Custom components](#custom-components)
|
|
30
|
+
7. [Server components in the canvas](#server-components-in-the-canvas)
|
|
31
|
+
8. [Custom blocks](#custom-blocks)
|
|
32
|
+
- [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields)
|
|
33
|
+
9. [Using existing Payload blocks](#using-existing-payload-blocks)
|
|
34
|
+
10. [Sections](#sections)
|
|
35
|
+
11. [Styling](#styling)
|
|
36
|
+
12. [Animations](#animations)
|
|
37
|
+
13. [Theme](#theme)
|
|
38
|
+
14. [Templates and binding](#templates-and-binding)
|
|
39
|
+
15. [References and Used in](#references-and-used-in)
|
|
40
|
+
16. [Localization](#localization)
|
|
41
|
+
17. [AI assistant](#ai-assistant)
|
|
42
|
+
18. [AI editing over MCP](#ai-editing-over-mcp)
|
|
43
|
+
19. [Multiplayer editing](#multiplayer-editing)
|
|
44
|
+
20. [Production and Docker](#production-and-docker)
|
|
45
|
+
21. [Deploying](#deploying)
|
|
46
|
+
22. [Troubleshooting](#troubleshooting)
|
|
47
|
+
23. [Limits](#limits)
|
|
48
|
+
|
|
49
|
+
## Requirements
|
|
50
|
+
|
|
51
|
+
- `payload`, `@payloadcms/ui`, `@payloadcms/richtext-lexical` 3.90 or later (Payload 3 only, not the Payload 4 canary)
|
|
52
|
+
- `next` 16.3 or later, `react` and `react-dom` 19.2 or later
|
|
53
|
+
- `tailwindcss` 4.3 or later (the plugin compiles your Tailwind entry CSS)
|
|
54
|
+
- Node.js 20.9 or later
|
|
55
|
+
- Any Payload database adapter. Postgres and SQLite store the layout as `jsonb`/JSON.
|
|
56
|
+
|
|
57
|
+
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.
|
|
58
|
+
|
|
59
|
+
Peer dependencies:
|
|
60
|
+
|
|
61
|
+
| Package | Range | Needed for |
|
|
62
|
+
|---|---|---|
|
|
63
|
+
| `payload`, `@payloadcms/ui`, `@payloadcms/richtext-lexical` | `^3.90.0` | everything |
|
|
64
|
+
| `next` | `^16.3.0` | everything |
|
|
65
|
+
| `react`, `react-dom` | `^19.2.0` | everything |
|
|
66
|
+
| `tailwindcss` | `^4.3.0` | the CSS compile on save and in the canvas |
|
|
67
|
+
| `@anthropic-ai/sdk` | `>=0.131.0`, optional | only the `/ai/anthropic` adapter |
|
|
68
|
+
| `payload-mcp-toolkit` | `>=0.9.0`, optional | only `builderMcpTools()` (`/mcp`) |
|
|
69
|
+
| `zod` | `^3.25 \|\| ^4`, optional | only `builderMcpTools()` (`/mcp`) |
|
|
70
|
+
|
|
71
|
+
## Install
|
|
72
|
+
|
|
73
|
+
These steps start from a blank Payload app with Postgres:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
npx create-payload-app@latest -n my-site -t blank --db postgres --use-pnpm
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
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.
|
|
80
|
+
|
|
81
|
+
### 1. Add the package
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
pnpm add payload-canvas tailwindcss @tailwindcss/postcss postcss
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
With npm: `npm install payload-canvas tailwindcss @tailwindcss/postcss postcss`.
|
|
88
|
+
|
|
89
|
+
### 2. Add a collection with pages
|
|
90
|
+
|
|
91
|
+
Any collection works. This one uses drafts, so the editor gets **Save Draft** and **Publish**.
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
// src/collections/Pages.ts
|
|
95
|
+
import type { CollectionConfig } from 'payload'
|
|
96
|
+
|
|
97
|
+
export const Pages: CollectionConfig = {
|
|
98
|
+
slug: 'pages',
|
|
99
|
+
admin: { useAsTitle: 'title' },
|
|
100
|
+
access: {
|
|
101
|
+
// Signed-in users see drafts. Visitors see published pages only.
|
|
102
|
+
read: ({ req }) => (req.user ? true : { _status: { equals: 'published' } }),
|
|
103
|
+
},
|
|
104
|
+
versions: { drafts: true },
|
|
105
|
+
fields: [
|
|
106
|
+
{ name: 'title', type: 'text', required: true },
|
|
107
|
+
{ name: 'slug', type: 'text', required: true, unique: true, index: true },
|
|
108
|
+
],
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### 3. Make one block list
|
|
113
|
+
|
|
114
|
+
The plugin, the site and the canvas must use the same block list. Put it in its own file. Import blocks from `payload-canvas/blocks`: that entry has no server code, so client components can import it too.
|
|
115
|
+
|
|
116
|
+
```ts
|
|
117
|
+
// src/builder.ts
|
|
118
|
+
import { defaultBlocks } from 'payload-canvas/blocks'
|
|
119
|
+
|
|
120
|
+
export const blocks = defaultBlocks({ mediaCollection: 'media', linkCollections: ['pages'] })
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### 4. Add the Tailwind entry CSS
|
|
124
|
+
|
|
125
|
+
This file is your site's CSS. The plugin also compiles each page's classes from it. The variables on `:root` are defaults: the plugin's **Theme** global overrides them, so editors can change the colors, fonts and radius in the admin. See [Theme](#theme).
|
|
126
|
+
|
|
127
|
+
```css
|
|
128
|
+
/* src/app/(frontend)/globals.css */
|
|
129
|
+
@import "tailwindcss";
|
|
130
|
+
|
|
131
|
+
/* Defaults. The Theme global (admin > Theme) overrides them. */
|
|
132
|
+
:root {
|
|
133
|
+
--background: oklch(1 0 0);
|
|
134
|
+
--foreground: oklch(0.145 0 0);
|
|
135
|
+
--primary: oklch(0.55 0.2 260);
|
|
136
|
+
--primary-foreground: oklch(0.985 0 0);
|
|
137
|
+
--secondary: oklch(0.97 0 0);
|
|
138
|
+
--secondary-foreground: oklch(0.205 0 0);
|
|
139
|
+
--muted: oklch(0.97 0 0);
|
|
140
|
+
--muted-foreground: oklch(0.556 0 0);
|
|
141
|
+
--accent: oklch(0.97 0 0);
|
|
142
|
+
--accent-foreground: oklch(0.205 0 0);
|
|
143
|
+
--border: oklch(0.922 0 0);
|
|
144
|
+
--radius: 0.625rem;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
@theme {
|
|
148
|
+
--font-sans: ui-sans-serif, system-ui, sans-serif; /* the theme's body font replaces it */
|
|
149
|
+
--font-heading: var(--font-sans); /* `font-heading`; the theme's heading font replaces it */
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
@theme inline {
|
|
153
|
+
--color-background: var(--background);
|
|
154
|
+
--color-foreground: var(--foreground);
|
|
155
|
+
--color-primary: var(--primary);
|
|
156
|
+
--color-primary-foreground: var(--primary-foreground);
|
|
157
|
+
--color-secondary: var(--secondary);
|
|
158
|
+
--color-secondary-foreground: var(--secondary-foreground);
|
|
159
|
+
--color-muted: var(--muted);
|
|
160
|
+
--color-muted-foreground: var(--muted-foreground);
|
|
161
|
+
--color-accent: var(--accent);
|
|
162
|
+
--color-accent-foreground: var(--accent-foreground);
|
|
163
|
+
--color-border: var(--border);
|
|
164
|
+
--radius-sm: calc(var(--radius) - 4px);
|
|
165
|
+
--radius-md: calc(var(--radius) - 2px);
|
|
166
|
+
--radius-lg: var(--radius);
|
|
167
|
+
--radius-xl: calc(var(--radius) + 4px);
|
|
168
|
+
}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
```js
|
|
172
|
+
// postcss.config.mjs
|
|
173
|
+
export default {
|
|
174
|
+
plugins: { '@tailwindcss/postcss': {} },
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
The site layout imports this file in [step 7](#7-render-pages-on-the-site). The blank template has `src/app/(frontend)/styles.css` with a dark style for its welcome page, and its rules fight Tailwind's. Delete the file and the `import './styles.css'` line in `src/app/(frontend)/page.tsx`. Step 7 replaces the layout that imports it too.
|
|
179
|
+
|
|
180
|
+
### 5. Add the plugin
|
|
181
|
+
|
|
182
|
+
```ts
|
|
183
|
+
// src/payload.config.ts
|
|
184
|
+
import { websiteBuilder } from 'payload-canvas'
|
|
185
|
+
import { blocks } from './builder'
|
|
186
|
+
import { Pages } from './collections/Pages'
|
|
187
|
+
|
|
188
|
+
export default buildConfig({
|
|
189
|
+
collections: [Users, Media, Pages],
|
|
190
|
+
// ...
|
|
191
|
+
plugins: [
|
|
192
|
+
// other plugins first
|
|
193
|
+
websiteBuilder({
|
|
194
|
+
collections: { pages: { url: (doc) => `/${doc.slug}` } },
|
|
195
|
+
blocks,
|
|
196
|
+
css: { entry: 'src/app/(frontend)/globals.css' },
|
|
197
|
+
}),
|
|
198
|
+
],
|
|
199
|
+
})
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Keep `websiteBuilder` **last** in `plugins`. See [Troubleshooting](#troubleshooting).
|
|
203
|
+
|
|
204
|
+
Then regenerate the import map and the types:
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
pnpm payload generate:importmap
|
|
208
|
+
pnpm payload generate:types
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
### 6. Add the canvas route
|
|
212
|
+
|
|
213
|
+
The editor shows the page in an iframe. The iframe loads a route in your app, so the canvas uses your real block components and your CSS. Give the route its own root layout, without your site header and footer, and import your site's CSS in it.
|
|
214
|
+
|
|
215
|
+
```tsx
|
|
216
|
+
// src/app/(builder-canvas)/layout.tsx
|
|
217
|
+
import { ThemeStyle } from 'payload-canvas/react/server'
|
|
218
|
+
import config from '@payload-config'
|
|
219
|
+
import { getPayload } from 'payload'
|
|
220
|
+
import type { ReactNode } from 'react'
|
|
221
|
+
|
|
222
|
+
// Your site's CSS: it holds every class Tailwind found in your files.
|
|
223
|
+
import '../(frontend)/globals.css'
|
|
224
|
+
|
|
225
|
+
export default async function CanvasLayout({ children }: { children: ReactNode }) {
|
|
226
|
+
const payload = await getPayload({ config })
|
|
227
|
+
return (
|
|
228
|
+
<html lang="en">
|
|
229
|
+
{/* The same body classes as your site layout. */}
|
|
230
|
+
<body className="font-sans antialiased">
|
|
231
|
+
{/* The Theme global's variables and fonts (React moves them into the head). `live` reloads
|
|
232
|
+
them after a theme save. Not in a <head> element: `live` adds a client component, and
|
|
233
|
+
Next's metadata then fails to hydrate on some loads. */}
|
|
234
|
+
<ThemeStyle payload={payload} live />
|
|
235
|
+
{children}
|
|
236
|
+
</body>
|
|
237
|
+
</html>
|
|
238
|
+
)
|
|
239
|
+
}
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
```tsx
|
|
243
|
+
// src/app/(builder-canvas)/builder-canvas/page.tsx
|
|
244
|
+
'use client'
|
|
245
|
+
|
|
246
|
+
import { BuilderCanvas } from 'payload-canvas/react/canvas'
|
|
247
|
+
import { blocks } from '@/builder'
|
|
248
|
+
import { builderCanvas } from './actions'
|
|
249
|
+
|
|
250
|
+
export default function CanvasPage() {
|
|
251
|
+
return <BuilderCanvas blocks={blocks} server={builderCanvas} />
|
|
252
|
+
}
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
```ts
|
|
256
|
+
// src/app/(builder-canvas)/builder-canvas/actions.ts
|
|
257
|
+
'use server'
|
|
258
|
+
|
|
259
|
+
import config from '@payload-config'
|
|
260
|
+
import { createCanvasServer, type CanvasServerRequest } from 'payload-canvas/react/server'
|
|
261
|
+
import { blocks } from '@/builder'
|
|
262
|
+
|
|
263
|
+
const canvas = createCanvasServer({ config, blocks })
|
|
264
|
+
|
|
265
|
+
export async function builderCanvas(request: CanvasServerRequest) {
|
|
266
|
+
return canvas(request)
|
|
267
|
+
}
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
The server action renders the blocks the canvas cannot render itself: server components that load data. It is optional. Without it, those blocks show "Name: no preview in the editor". See [Server components in the canvas](#server-components-in-the-canvas).
|
|
271
|
+
|
|
272
|
+
How the canvas gets its CSS, in this order:
|
|
273
|
+
|
|
274
|
+
1. **Your site's CSS.** Tailwind puts every class it finds in your files into it, so your components' own classes work on the canvas as on the site. Blocks do not have to list them in `classes`.
|
|
275
|
+
2. **The theme** (`ThemeStyle`). Its `:root:root` rule wins over the `:root` defaults in your CSS.
|
|
276
|
+
3. **The CSS for the classes in the layout** and in each block's `classes`. The canvas compiles it in the browser (about 4 ms per new class) from the same entry file as the save hook, and puts it after your CSS. On the site, the generated CSS also comes after your CSS, so the canvas shows the same result. This CSS also holds Preflight and your base styles a second time. Both copies come from the same entry file, so they are identical and change nothing.
|
|
277
|
+
|
|
278
|
+
The generated CSS styles only block elements, so it never changes the order of your own classes. Every rule in it matches only elements with the class `builder-css`, and `RenderLayout` adds that class to the `className` of every block with classes. Example: a header layout uses `flex`, and your component has `flex md:grid`. Your component's element has no `builder-css`, so the generated `flex` does not reach it, and your site's CSS makes it `grid` from `md` up. A block's element has all its classes in the generated CSS, which is in Tailwind's order and comes last. The rules use `:where(.builder-css)`, which adds no specificity.
|
|
279
|
+
|
|
280
|
+
Earlier versions told you to leave your site's CSS out of the canvas, because the canvas compiles the full CSS for the layout's classes itself. That missed the classes your components use themselves. If you skip the import, the canvas still works, but only the classes in the layout and in each block's `classes` have CSS.
|
|
281
|
+
|
|
282
|
+
The same page also renders the library's section thumbnails: the editor loads it hidden, with `?mode=thumbnail`, when the **Sections** tab needs pictures. Nothing to add for that. A thumbnail copies the page's stylesheets into the picture, and it waits for server blocks before it takes the picture.
|
|
283
|
+
|
|
284
|
+
The default path is `/builder-canvas`. Change it with the `canvasPath` option. If your app has a single root `app/layout.tsx`, move the site into a route group first, so the canvas can have its own root layout. Payload's templates already use `(frontend)` and `(payload)` groups.
|
|
285
|
+
|
|
286
|
+
### 7. Render pages on the site
|
|
287
|
+
|
|
288
|
+
The site layout imports your CSS and renders the Theme global's variables and fonts in the `<head>`. Replace the blank template's layout with this one:
|
|
289
|
+
|
|
290
|
+
```tsx
|
|
291
|
+
// src/app/(frontend)/layout.tsx
|
|
292
|
+
import { ThemeStyle } from 'payload-canvas/react/server'
|
|
293
|
+
import config from '@payload-config'
|
|
294
|
+
import { getPayload } from 'payload'
|
|
295
|
+
import type { ReactNode } from 'react'
|
|
296
|
+
|
|
297
|
+
import './globals.css'
|
|
298
|
+
|
|
299
|
+
export default async function RootLayout({ children }: { children: ReactNode }) {
|
|
300
|
+
const payload = await getPayload({ config })
|
|
301
|
+
return (
|
|
302
|
+
<html lang="en">
|
|
303
|
+
<head>
|
|
304
|
+
<ThemeStyle payload={payload} />
|
|
305
|
+
</head>
|
|
306
|
+
<body className="font-sans antialiased">{children}</body>
|
|
307
|
+
</html>
|
|
308
|
+
)
|
|
309
|
+
}
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
The page route loads a page by its slug and renders its layout:
|
|
313
|
+
|
|
314
|
+
```tsx
|
|
315
|
+
// src/app/(frontend)/[slug]/page.tsx
|
|
316
|
+
import type { GeneratedCss } from 'payload-canvas'
|
|
317
|
+
import { normalizeLayout } from 'payload-canvas/core'
|
|
318
|
+
import { RenderLayout } from 'payload-canvas/react'
|
|
319
|
+
import { loadLayoutData } from 'payload-canvas/react/server'
|
|
320
|
+
import config from '@payload-config'
|
|
321
|
+
import { draftMode } from 'next/headers'
|
|
322
|
+
import { notFound } from 'next/navigation'
|
|
323
|
+
import { getPayload } from 'payload'
|
|
324
|
+
|
|
325
|
+
import { blocks } from '@/builder'
|
|
326
|
+
|
|
327
|
+
type Props = { params: Promise<{ slug: string }> }
|
|
328
|
+
|
|
329
|
+
export default async function Page({ params }: Props) {
|
|
330
|
+
const { slug } = await params
|
|
331
|
+
const { isEnabled: draft } = await draftMode()
|
|
332
|
+
const payload = await getPayload({ config })
|
|
333
|
+
const { docs } = await payload.find({ collection: 'pages', where: { slug: { equals: slug } }, limit: 1, draft })
|
|
334
|
+
const page = docs[0]
|
|
335
|
+
if (!page) notFound()
|
|
336
|
+
|
|
337
|
+
const layout = await loadLayoutData(normalizeLayout(page.layout), blocks, payload, { draft })
|
|
338
|
+
return <RenderLayout layout={layout} blocks={blocks} css={(page.layoutCss as GeneratedCss | null)?.css} />
|
|
339
|
+
}
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
`page.layout` and `page.layoutCss` exist in `payload-types.ts` after `generate:types` (step 5). The `draft` flag shows drafts only in Next's draft mode, so the site shows the published version.
|
|
343
|
+
|
|
344
|
+
### 8. Add the standalone tracing lines
|
|
345
|
+
|
|
346
|
+
Skip this step if you do not use `output: 'standalone'`. On every save, the plugin compiles Tailwind classes. The compile reads your CSS entry and Tailwind's CSS files from disk, so Next's file tracer cannot see them. List them in `next.config.ts`:
|
|
347
|
+
|
|
348
|
+
```ts
|
|
349
|
+
const nextConfig: NextConfig = {
|
|
350
|
+
output: 'standalone',
|
|
351
|
+
outputFileTracingIncludes: {
|
|
352
|
+
'/*': [
|
|
353
|
+
'./src/app/\\(frontend\\)/globals.css',
|
|
354
|
+
'./node_modules/tailwindcss/package.json',
|
|
355
|
+
'./node_modules/tailwindcss/*.css',
|
|
356
|
+
// Add every package your CSS entry imports, e.g. './node_modules/tw-animate-css/dist/*.css'
|
|
357
|
+
],
|
|
358
|
+
},
|
|
359
|
+
}
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
Escape `(` and `)` in route group names: the paths are globs.
|
|
363
|
+
|
|
364
|
+
### 9. Turn off Next's compression
|
|
365
|
+
|
|
366
|
+
In `next.config.ts`, set `compress: false` and let your reverse proxy compress responses (see [Deploying](#deploying)). Next's built-in gzip adds one listener to the gzip stream for each backpressure event while it streams a large HTML page. The admin and builder pages are large. In production this logs `MaxListenersExceededWarning: 11 drain listeners added to [Gzip]` many times. The listeners are freed when the response ends, so this is only noise, but it hides real warnings.
|
|
367
|
+
|
|
368
|
+
```ts
|
|
369
|
+
const nextConfig: NextConfig = {
|
|
370
|
+
compress: false,
|
|
371
|
+
}
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
### 10. Run it
|
|
375
|
+
|
|
376
|
+
```bash
|
|
377
|
+
pnpm dev
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
1. Open `http://localhost:3000/admin` and create the first user.
|
|
381
|
+
2. Create a page with a title and a slug, for example `about`.
|
|
382
|
+
3. Click the **Builder** tab (or **Open builder** on the layout field). The builder opens full screen. Click or drag blocks from the **Blocks** tab. Double-click text on the canvas to edit it in place, or edit it in the right panel. Style the selected block in **Styles**.
|
|
383
|
+
4. Click **Publish changes** in the top bar and open `http://localhost:3000/about`.
|
|
384
|
+
|
|
385
|
+
In development, Payload's Postgres adapter pushes the new tables and columns on `pnpm dev`. Before your first production deploy, create a migration and commit it:
|
|
386
|
+
|
|
387
|
+
```bash
|
|
388
|
+
pnpm payload migrate:create
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
Run it in production with `pnpm payload migrate`, or with `prodMigrations` in `postgresAdapter`. Never run `payload migrate` on a development database that uses push. See [Production and Docker](#production-and-docker).
|
|
392
|
+
|
|
393
|
+
## The builder view
|
|
394
|
+
|
|
395
|
+
The builder is a full-screen admin view at `/admin/builder/<collection>/<id>`. It has no Payload nav and no document header: one top bar holds everything.
|
|
396
|
+
|
|
397
|
+
How editors open it:
|
|
398
|
+
|
|
399
|
+
- the document's **Builder** tab (a link to the view),
|
|
400
|
+
- the **Open builder** button on the layout field in the normal Edit view (a new document must be saved first),
|
|
401
|
+
- the old tab URL `/admin/collections/<collection>/<id>/builder`, which redirects to the view.
|
|
402
|
+
|
|
403
|
+
The top bar, left to right:
|
|
404
|
+
|
|
405
|
+
- **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.
|
|
406
|
+
- 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).
|
|
407
|
+
- 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.
|
|
408
|
+
- The people on the page, and the save state: **Saving…** while changes are on their way, then **Saved · 12:04**.
|
|
409
|
+
- **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.
|
|
410
|
+
- **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.
|
|
411
|
+
- 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), and links to the Edit view and 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.
|
|
412
|
+
|
|
413
|
+
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.
|
|
414
|
+
|
|
415
|
+
The sidebars resize: drag the edge, or focus it with Tab and use the arrow keys (Shift for larger steps). A double-click or Enter resets the default size. The sizes are kept in the browser.
|
|
416
|
+
|
|
417
|
+
The canvas frame resizes too. Drag the handle on its left or right edge: the frame stays centered and shows its width and breakpoint while you drag. Hold Shift to snap to the breakpoint and device widths. The new width is a custom width. Double-click a handle (or press Enter on it) to go back to the device you started from, or to fluid. The stage scrolls sideways only when the frame is wider than the stage, for example a fixed width at 100 % zoom.
|
|
418
|
+
|
|
419
|
+
Publishing. All editors of a document share one live session (see [Multiplayer editing](#multiplayer-editing)). The session saves the layout as a draft about a second after each change. **Publish changes** saves what is still unsaved, then publishes with Payload's Local API as the signed-in user, so access control, hooks and versions work as usual. **Unpublish** sets the document back to draft. **Revert to published** loads the published version into the session, so every open editor reloads the canvas, and saves it again. Every open editor sees the new status at once.
|
|
420
|
+
|
|
421
|
+
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).
|
|
422
|
+
|
|
423
|
+
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.
|
|
424
|
+
|
|
425
|
+
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:
|
|
426
|
+
|
|
427
|
+
- **Drop line** (`'indicator'`, the default). A line or a box shows where the block lands. Blocks move when you drop.
|
|
428
|
+
- **Smooth** (`'smooth'`). The block lifts and follows the pointer. The other blocks and the outline rows slide out of the way, so a gap shows where the block lands. In a grid, blocks move into the next cell. On drop, the block slides into the gap. On cancel, it slides back.
|
|
429
|
+
|
|
430
|
+
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.
|
|
431
|
+
|
|
432
|
+
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.
|
|
433
|
+
|
|
434
|
+
## Inline editing
|
|
435
|
+
|
|
436
|
+
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.
|
|
437
|
+
|
|
438
|
+
### Text
|
|
439
|
+
|
|
440
|
+
- Hover text that can be edited: the cursor turns into a text cursor and a faint dashed outline shows.
|
|
441
|
+
- Double-click the text, or select the block and press Enter. Type. Escape ends editing. In a one-line text field, Enter ends it too. In a textarea, Enter adds a line break and Ctrl+Enter ends editing.
|
|
442
|
+
- Rich text opens a small Lexical editor with a toolbar (paragraph and heading types, lists, bold, italic, links). Ctrl+K adds a link.
|
|
443
|
+
- One editing session is one undo step. Collaborators see the typing live.
|
|
444
|
+
- A prop bound to document data, and a prop the user may not change (field `access`), stay closed: the editor says why.
|
|
445
|
+
|
|
446
|
+
**How the canvas finds the text.** After a block renders, the canvas compares the block's props with the text of its elements:
|
|
447
|
+
|
|
448
|
+
- It looks at text, textarea and richText fields, also inside groups, array rows (`headingLines.0.text`, `cards.2.heading`) and `hasMany` text fields (`tags.1`). A field with no value counts as its `defaultValue`, as your component renders it.
|
|
449
|
+
- An element matches a prop when its text equals the prop's value. Runs of whitespace count as one space. Rich text matches without any whitespace, because paragraphs have no separator in the DOM.
|
|
450
|
+
- The smallest element with that text wins. A value split across elements (an accent word in a `<span>`) maps to the element around both parts. Icons and empty decoration inside the element stay out of the editing.
|
|
451
|
+
- Rich text maps to its container (the `<div>` around the paragraphs), never to one paragraph, so the editor can add paragraphs.
|
|
452
|
+
- The canvas does not guess. Nothing is marked when one value shows in two visible elements, when two props have the same text, or when one element matches two props.
|
|
453
|
+
- Blocks rendered on the server ([Server components in the canvas](#server-components-in-the-canvas)) map the same way. When editing ends, the value is saved and the server renders the block again.
|
|
454
|
+
|
|
455
|
+
**Limits.** The text on screen must equal the prop. These cases stay in the inspector:
|
|
456
|
+
|
|
457
|
+
- Text your component changes in JavaScript: `.toUpperCase()`, truncation, a heading split into words, markup such as `*accent*` that becomes a `<span>`. (CSS `text-transform: uppercase` is fine: the DOM text is unchanged.)
|
|
458
|
+
- A prop shown inside a sentence with other text in the same element (`<p>Call us on {phone}</p>`).
|
|
459
|
+
- The same text twice on the block (a marquee that repeats its items).
|
|
460
|
+
|
|
461
|
+
**Mark the element yourself** when the automatic mapping cannot find it. `editableText(mode, path)` returns the attribute in the canvas and nothing on the site. A mark always wins over the automatic mapping.
|
|
462
|
+
|
|
463
|
+
```tsx
|
|
464
|
+
import { editableText, type PayloadBlockProps } from 'payload-canvas/react'
|
|
465
|
+
|
|
466
|
+
export function Hero({ heading, builder }: PayloadBlockProps<HeroBlock>) {
|
|
467
|
+
// The site shows "*Your* day" with an accent span. The mark tells the canvas which prop it is.
|
|
468
|
+
return <h1 {...editableText(builder.mode, 'heading')}>{heading}</h1>
|
|
469
|
+
}
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
Put the mark on the element that holds the text and nothing else.
|
|
473
|
+
|
|
474
|
+
### Images
|
|
475
|
+
|
|
476
|
+
Every image that shows an upload prop can be replaced on the canvas:
|
|
477
|
+
|
|
478
|
+
- Hover the image: a **Replace** chip shows in its top left corner. Text over an image (a hero heading) wins: hover a free part of the image.
|
|
479
|
+
- Double-click the image, or click the chip, to open the media popover:
|
|
480
|
+
- **Choose from library**: Payload's list drawer for the field's upload collection.
|
|
481
|
+
- **Upload a file**: a file picker. The file goes to the upload collection with its name as alt text.
|
|
482
|
+
- **Generate image**: the AI image action. Shown when `ai.images` is set up. See [Image generation](#image-generation).
|
|
483
|
+
- **Remove**: empties the field. Not shown for required fields.
|
|
484
|
+
- **Alt text**: saved in the block's own alt prop when it has one next to the upload (`alt`, `altText`, `<field>Alt`). Otherwise it is saved on the media document, so it changes everywhere that file is used.
|
|
485
|
+
- Drag an image file from your computer onto an image on the canvas to upload it and replace the image.
|
|
486
|
+
- When several uploads lie under the pointer (a video and its poster, a background under a photo), the popover has a list to pick one.
|
|
487
|
+
- Every replace is one undo step, and collaborators see it at once. Alt text saved on the media document is not part of the undo history.
|
|
488
|
+
|
|
489
|
+
**How the canvas finds the images.** It reads the URLs of `<img>` (also `srcset` and `<picture>` sources), `<video>` (the file and the poster), inline `background-image` styles and, for uploads still not found, CSS backgrounds from classes. It compares them with every URL of the block's media documents: the file, the thumbnail and each image size. `next/image` URLs (`/_next/image?url=…`) count as the image they wrap. Uploads in array rows (`photos.3.image`) and `hasMany` uploads (`gallery.2`) work too.
|
|
490
|
+
|
|
491
|
+
**Limits.** An image whose URL is not one of the block's uploads cannot be replaced on the canvas (an image from page data, a fixed file in `/public`). An empty upload field has no URL to match: mark its placeholder. Images inside rich text are edited in the inspector.
|
|
492
|
+
|
|
493
|
+
**Mark the element yourself** with `editableImage(mode, path)`. The default Image block marks its image and its empty placeholder this way:
|
|
494
|
+
|
|
495
|
+
```tsx
|
|
496
|
+
import { editableImage } from 'payload-canvas/react'
|
|
497
|
+
|
|
498
|
+
{photo ? <img {...editableImage(builder.mode, 'photo')} src={photo.url} alt="" /> : <div {...editableImage(builder.mode, 'photo')}>Add a photo</div>}
|
|
499
|
+
```
|
|
500
|
+
|
|
501
|
+
## Plugin options
|
|
502
|
+
|
|
503
|
+
```ts
|
|
504
|
+
websiteBuilder({
|
|
505
|
+
collections: {
|
|
506
|
+
pages: { field: 'layout', url: (doc) => `/${doc.slug}` },
|
|
507
|
+
posts: { templates: true, url: (doc) => `/blog/${doc.slug}` },
|
|
508
|
+
},
|
|
509
|
+
blocks, // default: defaultBlocks()
|
|
510
|
+
sections, // ready-made sections for the library and AI tools
|
|
511
|
+
savedSections: { slug: 'builder-sections' }, // sections people save; `false` turns it off
|
|
512
|
+
css: {
|
|
513
|
+
entry: 'src/app/(frontend)/globals.css',
|
|
514
|
+
plugins: { '@tailwindcss/typography': typography },
|
|
515
|
+
},
|
|
516
|
+
canvasPath: '/builder-canvas',
|
|
517
|
+
templates: { slug: 'builder-templates' },
|
|
518
|
+
live: { heartbeatMs: 15000 },
|
|
519
|
+
ai: { adapter: openRouterAdapter({ apiKey: process.env.OPENROUTER_API_KEY }) }, // the AI assistant
|
|
520
|
+
theme: { admin: { group: 'Settings' } }, // the Theme global; `false` leaves it out
|
|
521
|
+
editor: { dragMode: 'smooth' }, // the default drag and drop style; each user can change it
|
|
522
|
+
references: { usedIn: ['media'], protectDelete: ['media'] }, // "Used in" lists; `false` turns them off
|
|
523
|
+
})
|
|
524
|
+
```
|
|
525
|
+
|
|
526
|
+
| Option | Type | What it does |
|
|
527
|
+
|---|---|---|
|
|
528
|
+
| `collections` | `Record<slug, { field?, url?, templates? }>` | The collections that get the builder. Required. |
|
|
529
|
+
| `collections[slug].field` | `string` | Name of the layout JSON field. Default `layout`. The generated CSS goes in `<field>Css`. If a `json` field with this name exists (also inside rows, collapsibles or unnamed tabs), the plugin reuses it and moves it to the top level. |
|
|
530
|
+
| `collections[slug].url` | `(doc) => string` | The frontend path of a document. AI tools use it for preview links. The collection list block uses it for links. |
|
|
531
|
+
| `collections[slug].templates` | `boolean` | Documents render through templates. See [Templates](#templates-and-binding). |
|
|
532
|
+
| `collections[slug].legacyFields` | `string[]` | Top-level fields the builder replaced but the collection still has (the old `blocks` field after `migrateBlocksField`). **Publish** in the builder keeps their published value, so only the builder content goes live. See [Using existing Payload blocks](#using-existing-payload-blocks), step 7. |
|
|
533
|
+
| `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). |
|
|
534
|
+
| `blocks` | `BlockDefinition[]` | The blocks editors can use. Default `defaultBlocks()`. |
|
|
535
|
+
| `sections` | `SectionDefinition[]` | Ready-made sections. See [Sections](#sections). |
|
|
536
|
+
| `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). |
|
|
537
|
+
| `css.entry` | `string` | Your Tailwind entry CSS, absolute or relative to `process.cwd()`. Required. |
|
|
538
|
+
| `css.plugins` | `Record<id, plugin>` | Tailwind plugins by the id your CSS uses in `@plugin "<id>"`. Pass the imported module, so Next bundles it. |
|
|
539
|
+
| `canvasPath` | `string` | The canvas route. Default `/builder-canvas`. |
|
|
540
|
+
| `templates.slug` | `string` | Slug of the templates collection. Default `builder-templates`. |
|
|
541
|
+
| `templates.hooks` | `CollectionConfig['hooks']` | Hooks for the templates collection, for example to revalidate pages. |
|
|
542
|
+
| `live.heartbeatMs` | `number` | Interval of the keep-alive message on the live event stream. Default 10 s. |
|
|
543
|
+
| `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). |
|
|
544
|
+
| `ai` | `AiOptions` | Turns on the AI assistant in the editor. See [AI assistant](#ai-assistant). |
|
|
545
|
+
| `theme` | `ThemeOptions \| false` | The Theme global. On by default. `false` leaves it out. See [Theme](#theme). |
|
|
546
|
+
| `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). |
|
|
547
|
+
| `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. |
|
|
548
|
+
| `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). |
|
|
549
|
+
|
|
550
|
+
For each listed collection the plugin adds:
|
|
551
|
+
|
|
552
|
+
- the layout field (`json`) with the editor as its field component,
|
|
553
|
+
- a hidden `<field>Css` field that stores `{ hash, css }`,
|
|
554
|
+
- a hidden virtual rich text field, when a block has a rich text prop,
|
|
555
|
+
- a hidden `builderRefs` relationship field that lists the media and documents the layout uses (see [References and Used in](#references-and-used-in)),
|
|
556
|
+
- the **Builder** document tab, a link to the full-screen view (`/admin/builder/<slug>/<id>`; the plugin adds this root view once for all collections),
|
|
557
|
+
- a `beforeChange` hook that validates the layout and compiles its CSS, takes the layout from the live session while one is open, and rejects a save from an out-of-date form (see [Multiplayer editing](#multiplayer-editing)),
|
|
558
|
+
- a `beforeOperation` and an `afterChange` hook for the live session and Payload's document lock.
|
|
559
|
+
|
|
560
|
+
It also adds these endpoints (signed-in users only):
|
|
561
|
+
|
|
562
|
+
| Endpoint | Use |
|
|
563
|
+
|---|---|
|
|
564
|
+
| `GET /api/builder/canvas-css` | The stylesheets the canvas compiles from. |
|
|
565
|
+
| `GET /api/builder/style-tokens` | Theme tokens and class names for the Styles panel. |
|
|
566
|
+
| `GET /api/builder/live/:collection/:id/events` | Server-Sent Events stream of one document's live session. |
|
|
567
|
+
| `POST /api/builder/live/:collection/:id/commit` | Applies one batch of operations to the live session (editors). |
|
|
568
|
+
| `POST /api/builder/live/:collection/:id/awareness` | Sends your selection and pointer to the other editors. |
|
|
569
|
+
| `POST /api/builder/live/:collection/:id/operations` | Applies operations to the live session and returns the new layout (scripts and integrations). |
|
|
570
|
+
| `GET /api/builder/live/:collection/:id/meta` | What the builder's top bar shows: title, status, dates, versions count, preview links. |
|
|
571
|
+
| `POST /api/builder/live/:collection/:id/publish` | Saves the live session, then publishes the document. |
|
|
572
|
+
| `POST /api/builder/live/:collection/:id/unpublish` | Sets the document back to draft. |
|
|
573
|
+
| `POST /api/builder/live/:collection/:id/revert` | Drops the draft changes: the live session and the draft get the published version. |
|
|
574
|
+
| `POST /api/builder/live/:collection/:id/restore` | Body `{ versionId }`. Restores an older version: the live session and the draft get its layout. With drafts it becomes the draft. |
|
|
575
|
+
| `POST /api/builder/live/:collection/:id/validate` | Body `{ block }`. Runs the `validate` functions of the block's props and returns `{ problems: [{ propPath, message }] }`. The inspector calls it while someone edits. |
|
|
576
|
+
| `POST /api/builder/ai/chat` | The AI assistant (only with the `ai` option). Streams Server-Sent Events. |
|
|
577
|
+
| `GET /api/builder/theme` | The theme as `{ css, fontsHref }` (with the theme on). It uses the global's read access, so it is public by default. |
|
|
578
|
+
|
|
579
|
+
### Entry points
|
|
580
|
+
|
|
581
|
+
| Import | Use it in | Holds |
|
|
582
|
+
|---|---|---|
|
|
583
|
+
| `payload-canvas` | `payload.config.ts` (server) | `websiteBuilder`, `defineBlock`, `defaultBlocks`, `fromPayloadBlocks`, `migrateBlocksField`, types |
|
|
584
|
+
| `payload-canvas/blocks` | anywhere | `defaultBlocks`, `defineBlock`, `linkField`, `fromPayloadBlocks`, `BUILDER_CSS_CLASS`, `withBuilderCssClass` |
|
|
585
|
+
| `payload-canvas/core` | anywhere | layout types, `normalizeLayout`, `validateLayout`, `applyOperations`, tree helpers, `convertPayloadBlocksLayout`, `toPayloadBlock` |
|
|
586
|
+
| `payload-canvas/css` | server | `compileClasses`, `getStyleTokens`, `tracingIncludes` |
|
|
587
|
+
| `payload-canvas/theme` | anywhere | `themeCss`, `themeVariables`, `themeOutput`, `deriveColors`, `googleFontsHref`, `themeConfigOf`, theme types |
|
|
588
|
+
| `payload-canvas/theme-client` | Payload import map, or your own fields | `ThemeColorField`, `ThemeFontField`, `ThemeSliderField` |
|
|
589
|
+
| `payload-canvas/mcp` | server | `builderMcpTools` |
|
|
590
|
+
| `payload-canvas/ai` | server | the `AiAdapter` type and helpers for writing an adapter |
|
|
591
|
+
| `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). |
|
|
592
|
+
| `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). |
|
|
593
|
+
| `payload-canvas/live` | server | the live sessions and endpoints |
|
|
594
|
+
| `payload-canvas/client` | Payload import map only | admin client components (layout field, Builder tab) |
|
|
595
|
+
| `payload-canvas/rsc` | Payload import map only | admin server components (the builder view, the tab redirect) |
|
|
596
|
+
| `payload-canvas/react` | your site and the canvas (server and client) | `RenderLayout`, `defaultComponents`, `fromPayloadComponent(s)`, `withPageData`, `renderOnServer`, `editableText`, `editableImage`, link helpers, `ThemeLive`, types |
|
|
597
|
+
| `payload-canvas/react/server` | server only | `loadLayoutData`, `loadTemplate`, `loadTheme`, `ThemeStyle`, `createCanvasServer` (they call Payload's Local API) |
|
|
598
|
+
| `payload-canvas/react/canvas` | client only | `BuilderCanvas`, the runtime for the editor's iframe |
|
|
599
|
+
| `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. |
|
|
600
|
+
|
|
601
|
+
Every entry point is ESM with `.d.ts` types. Client components keep their `'use client'` directive in the build.
|
|
602
|
+
|
|
603
|
+
## Rendering the layout on your site
|
|
604
|
+
|
|
605
|
+
`RenderLayout` is a React Server Component. It walks the layout and renders each block with its component. It comes from `payload-canvas/react`. The helpers that call Payload (`loadLayoutData`, `loadTemplate`, `ThemeStyle`, `createCanvasServer`) come from `payload-canvas/react/server`, and the editor's canvas (`BuilderCanvas`) comes from `payload-canvas/react/canvas`. See [Entry points](#entry-points). The full page route is in [Install, step 7](#7-render-pages-on-the-site), the canvas route in [step 6](#6-add-the-canvas-route), and the theme in [Theme](#theme).
|
|
606
|
+
|
|
607
|
+
| Prop | Type | What it does |
|
|
608
|
+
|---|---|---|
|
|
609
|
+
| `layout` | `Layout` | The layout, usually after `loadLayoutData`. |
|
|
610
|
+
| `blocks` | `BlockDefinition[]` | The same list as the plugin. |
|
|
611
|
+
| `css` | `string \| null` | The generated CSS from `<field>Css`. Rendered in a `<style>` tag. |
|
|
612
|
+
| `components` | `Record<type, Component>` | Your components, merged over the defaults. |
|
|
613
|
+
| `resolveLink` | `(link) => string \| null` | Turns links into an `href`. Default: the URL, or `/<slug>` for a loaded document. |
|
|
614
|
+
| `context` | `{ collection, doc }` | The document a template renders. See [Templates](#templates-and-binding). |
|
|
615
|
+
| `pageData` | `Record<string, unknown>` | Data the page loads once for its blocks. See [Page data](#page-data-and--block-context--components). |
|
|
616
|
+
|
|
617
|
+
`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`.
|
|
618
|
+
|
|
619
|
+
Write a `resolveLink` when your collections have different routes. Pass the same function to `RenderLayout` and to `BuilderCanvas`:
|
|
620
|
+
|
|
621
|
+
```ts
|
|
622
|
+
import type { ResolveLink } from 'payload-canvas/react'
|
|
623
|
+
|
|
624
|
+
export const resolveLink: ResolveLink = (link) => {
|
|
625
|
+
if (link.type !== 'reference') return link.url?.trim() || null
|
|
626
|
+
// The loaded document after loadLayoutData, or still an ID.
|
|
627
|
+
const doc = link.reference?.value as { slug?: string } | null | undefined
|
|
628
|
+
if (!doc?.slug) return null
|
|
629
|
+
return link.reference?.relationTo === 'posts' ? `/blog/${doc.slug}` : `/${doc.slug}`
|
|
630
|
+
}
|
|
631
|
+
```
|
|
632
|
+
|
|
633
|
+
### Custom components
|
|
634
|
+
|
|
635
|
+
Every block component gets the same props:
|
|
636
|
+
|
|
637
|
+
```ts
|
|
638
|
+
type BlockComponentProps = {
|
|
639
|
+
block: Block // the stored block
|
|
640
|
+
props: Record<string, unknown> // props after data loading and link resolution
|
|
641
|
+
className?: string
|
|
642
|
+
slots: Record<string, ReactNode> // rendered children per slot
|
|
643
|
+
attributes: Record<string, string> // spread on the root element
|
|
644
|
+
slotAttributes: Record<string, Record<string, string>> // spread on each slot's container
|
|
645
|
+
mode: 'site' | 'canvas'
|
|
646
|
+
}
|
|
647
|
+
```
|
|
648
|
+
|
|
649
|
+
- Spread `attributes` on the root element. In the canvas it holds `data-block-id`, which the editor needs to select and measure the block.
|
|
650
|
+
- Props are plain data. A component can be a client component (`'use client'`).
|
|
651
|
+
- Use one components map for the site and the canvas, in a file without server code:
|
|
652
|
+
|
|
653
|
+
```tsx
|
|
654
|
+
// src/components/blocks.ts
|
|
655
|
+
import type { BlockComponents } from 'payload-canvas/react'
|
|
656
|
+
import { PricingTable } from './PricingTable'
|
|
657
|
+
|
|
658
|
+
export const components: BlockComponents = { pricingTable: PricingTable }
|
|
659
|
+
```
|
|
660
|
+
|
|
661
|
+
```tsx
|
|
662
|
+
<RenderLayout layout={layout} blocks={blocks} components={components} resolveLink={resolveLink} css={css} />
|
|
663
|
+
<BuilderCanvas blocks={blocks} components={components} resolveLink={resolveLink} />
|
|
664
|
+
```
|
|
665
|
+
|
|
666
|
+
`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)).
|
|
667
|
+
|
|
668
|
+
## Server components in the canvas
|
|
669
|
+
|
|
670
|
+
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 lightbox) work in the canvas as on the site. You do not change your components.
|
|
671
|
+
|
|
672
|
+
You keep two component maps:
|
|
673
|
+
|
|
674
|
+
- **The client-safe map** (`components`): for the canvas. It must not import server code.
|
|
675
|
+
- **The server map**: the client-safe map plus the server components. The site and the server action use it.
|
|
676
|
+
|
|
677
|
+
**1. Make the server map** in a file that only server code imports:
|
|
678
|
+
|
|
679
|
+
```ts
|
|
680
|
+
// src/components/blocks.server.ts
|
|
681
|
+
import { fromPayloadComponents } from 'payload-canvas/react'
|
|
682
|
+
import { blocks } from '@/builder'
|
|
683
|
+
import { ModelGridLeaf } from '@/blocks/leaves/modelGrid/component'
|
|
684
|
+
import { components } from './blocks'
|
|
685
|
+
|
|
686
|
+
export const serverComponents = {
|
|
687
|
+
...components,
|
|
688
|
+
...fromPayloadComponents({ modelGrid: ModelGridLeaf }, blocks),
|
|
689
|
+
}
|
|
690
|
+
```
|
|
691
|
+
|
|
692
|
+
**2. Give it to the server action** (see [step 6 of Install](#6-add-the-canvas-route)):
|
|
693
|
+
|
|
694
|
+
```ts
|
|
695
|
+
const canvas = createCanvasServer({ config, blocks, components: serverComponents, resolveLink })
|
|
696
|
+
```
|
|
697
|
+
|
|
698
|
+
**3. Render the site with it:** `<RenderLayout components={serverComponents} … />`.
|
|
699
|
+
|
|
700
|
+
The canvas renders a block on the server when:
|
|
701
|
+
|
|
702
|
+
- the block type has no component in the canvas's `components` (the default blocks always have one),
|
|
703
|
+
- its component is an `async` function, or
|
|
704
|
+
- its component is marked: `renderOnServer(Component)`, or `fromPayloadComponent(Component, { render: 'server' })`.
|
|
705
|
+
|
|
706
|
+
`createCanvasServer` options:
|
|
707
|
+
|
|
708
|
+
| Option | What it does |
|
|
709
|
+
|---|---|
|
|
710
|
+
| `config` | Your Payload config. Required. |
|
|
711
|
+
| `blocks` | The block definitions. Default: the plugin's `blocks`. |
|
|
712
|
+
| `components` | The server map. |
|
|
713
|
+
| `resolveLink` | The same link resolver as the site. |
|
|
714
|
+
| `pageData` | `({ payload, user, document, context, locale }) => data`: the page data. `locale` is the language the editor shows (null without localization); load your data in it. See below. |
|
|
715
|
+
|
|
716
|
+
How it works in the editor:
|
|
717
|
+
|
|
718
|
+
- The first render shows a gray box with the block's name. Then the server output shows.
|
|
719
|
+
- 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.
|
|
720
|
+
- 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.
|
|
721
|
+
- 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.
|
|
722
|
+
- Only signed-in users of the admin collection get an answer.
|
|
723
|
+
- When a component fails, that block shows "Name: the preview failed" with the error. The other blocks are not affected.
|
|
724
|
+
- Selecting, dragging, the outline and the inspector work as for every block. The editor puts the block id on the first element of the output.
|
|
725
|
+
- Text and images edit on the canvas as in other blocks ([Inline editing](#inline-editing)). When editing ends, the block renders on the server again with the new value.
|
|
726
|
+
|
|
727
|
+
### Slots in server-rendered blocks
|
|
728
|
+
|
|
729
|
+
The server renders each slot of the block as a small client component, a slot outlet. In the canvas, the outlet shows the children the canvas renders itself. So:
|
|
730
|
+
|
|
731
|
+
- Children that your component renders through the builder (`PayloadSlot`, or `slots` in a builder component) stay fully editable on the canvas: select, drag, drop, double-click to edit text. They update at once, without a request to the server. A child can be a server-rendered block too.
|
|
732
|
+
- Children that your component renders itself (`<RenderLeaves blocks={content} />`) render on the server with the block. They show correctly, but you cannot select them on the canvas. Edit them in the outline and the inspector. This is the same as for client components that render their own children.
|
|
733
|
+
- The server output can depend on the children's data, so a change to a child also asks for the parent again (after the same 250 ms). The parent keeps its output on the screen meanwhile, and children in outlets update at once.
|
|
734
|
+
|
|
735
|
+
Why not static HTML: the canvas would have to inject markup that React does not own. Client components inside it would not run, and the children in its slots could not stay live React elements.
|
|
736
|
+
|
|
737
|
+
### Page data and `{ block, context }` components
|
|
738
|
+
|
|
739
|
+
Some sites load data once per page and give it to every block, for example `<RenderBlocks blocks={blocks} context={{ services, reviewAggregate }} />`, with components written as `function Hero({ block, context })`. Use the adapter's `props` option for them:
|
|
740
|
+
|
|
741
|
+
```ts
|
|
742
|
+
export const components = fromPayloadComponents({ hero: HeroBlockRenderer, cta: CTABlockRenderer }, blocks, {
|
|
743
|
+
props: (block, context) => ({ block, context }),
|
|
744
|
+
})
|
|
745
|
+
```
|
|
746
|
+
|
|
747
|
+
`block` holds `{ id, blockType, blockName, ...fields }`, with each slot as a nested array. `context` is the page data. The third argument is the `builder` prop.
|
|
748
|
+
|
|
749
|
+
Give the page data with one function, on the site and in the canvas:
|
|
750
|
+
|
|
751
|
+
```ts
|
|
752
|
+
// src/lib/pageData.ts (server)
|
|
753
|
+
export async function loadPageData(payload: Payload) {
|
|
754
|
+
const services = await payload.find({ collection: 'services', depth: 1 })
|
|
755
|
+
return { services: services.docs }
|
|
756
|
+
}
|
|
757
|
+
```
|
|
758
|
+
|
|
759
|
+
```tsx
|
|
760
|
+
// The site
|
|
761
|
+
<RenderLayout layout={layout} components={serverComponents} pageData={await loadPageData(payload)} … />
|
|
762
|
+
```
|
|
763
|
+
|
|
764
|
+
```ts
|
|
765
|
+
// The canvas server action
|
|
766
|
+
createCanvasServer({ config, blocks, components: serverComponents, pageData: ({ payload }) => loadPageData(payload) })
|
|
767
|
+
```
|
|
768
|
+
|
|
769
|
+
The loader also gets `user`, `document` (the document open in the builder, `{ collection, id }`) and `context` (a template's sample document). The canvas loads the page data once, before its first render, and server-rendered blocks get it on every render. The page data must be plain data.
|
|
770
|
+
|
|
771
|
+
Only components that ask for the page data get it: every `fromPayloadComponent` component, and components marked with `withPageData(Component)` (they get it as `pageData`). So a client component does not carry the page data in the page's payload.
|
|
772
|
+
|
|
773
|
+
## Custom blocks
|
|
774
|
+
|
|
775
|
+
Declare a block with `defineBlock`. Props are Payload field configs. The editor builds its inputs from them, and the plugin builds a JSON Schema for validation and AI tools.
|
|
776
|
+
|
|
777
|
+
```ts
|
|
778
|
+
// src/builder.ts
|
|
779
|
+
import { defaultBlocks, defineBlock, linkField } from 'payload-canvas/blocks'
|
|
780
|
+
|
|
781
|
+
export const pricingTable = defineBlock({
|
|
782
|
+
type: 'pricingTable',
|
|
783
|
+
label: 'Pricing table',
|
|
784
|
+
icon: 'grid', // a name from the editor's icon set; unknown names get a generic icon
|
|
785
|
+
category: 'Marketing', // group in the block library
|
|
786
|
+
fields: [
|
|
787
|
+
{ name: 'plan', type: 'text', required: true },
|
|
788
|
+
{ name: 'price', type: 'number' },
|
|
789
|
+
linkField({ collections: ['pages'] }), // prop "link": URL or a page
|
|
790
|
+
],
|
|
791
|
+
slots: { features: { allow: ['text', 'list'] } }, // named child lists; omit for a leaf block
|
|
792
|
+
defaultClassName: 'flex flex-col gap-4 rounded-xl border p-6',
|
|
793
|
+
// classes: only for a component in a package your CSS does not scan (see below)
|
|
794
|
+
ai: {
|
|
795
|
+
description: 'A pricing card with a plan name, a price and a call to action.',
|
|
796
|
+
example: { props: { plan: 'Pro', price: 29 } },
|
|
797
|
+
},
|
|
798
|
+
})
|
|
799
|
+
|
|
800
|
+
export const blocks = [...defaultBlocks({ linkCollections: ['pages'] }), pricingTable]
|
|
801
|
+
```
|
|
802
|
+
|
|
803
|
+
- `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.
|
|
804
|
+
- `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 one child of it, so a new list starts with one item.
|
|
805
|
+
- `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.
|
|
806
|
+
- Block fields keep Payload's `validate`, `hooks` and `access`. See [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields).
|
|
807
|
+
- `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`).
|
|
808
|
+
- `linkField()` stores `{ type, url, reference, newTab }`. The component receives it resolved, with `href`, `target` and `rel`.
|
|
809
|
+
- The default blocks are `stack`, `grid`, `heading`, `text`, `richText`, `image`, `video`, `button`, `link`, `menu`, `list` with its `listItem` blocks, `quote`, `divider`, `spacer`, `collectionList` (documents from a collection) and `field` (a field of the document a template renders).
|
|
810
|
+
- 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.
|
|
811
|
+
- 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.
|
|
812
|
+
- 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.
|
|
813
|
+
|
|
814
|
+
### Validation, hooks and access on block fields
|
|
815
|
+
|
|
816
|
+
Block props live inside one JSON field, so Payload itself never runs the field logic of block fields. The plugin runs it, with the arguments Payload passes. It works the same for `defineBlock` fields and for blocks made with `fromPayloadBlocks()`, at any depth (groups, named tabs, rows, collapsibles, arrays and `blocks` fields inside props).
|
|
817
|
+
|
|
818
|
+
```ts
|
|
819
|
+
defineBlock({
|
|
820
|
+
type: 'product',
|
|
821
|
+
label: 'Product',
|
|
822
|
+
fields: [
|
|
823
|
+
{ name: 'sku', type: 'text', validate: (value) => !value || /^[A-Z]{3}-\d{3}$/.test(value) || 'Use a SKU like ABC-123' },
|
|
824
|
+
{ name: 'slug', type: 'text', hooks: { beforeChange: [({ value }) => slugify(value)] } },
|
|
825
|
+
{ name: 'note', type: 'text', access: { read: ({ req }) => Boolean(req.user?.isAdmin) } },
|
|
826
|
+
{ name: 'price', type: 'number', access: { update: ({ req }) => Boolean(req.user?.isAdmin) } },
|
|
827
|
+
],
|
|
828
|
+
})
|
|
829
|
+
```
|
|
830
|
+
|
|
831
|
+
What runs where:
|
|
832
|
+
|
|
833
|
+
| Field logic | Runs | Effect |
|
|
834
|
+
|---|---|---|
|
|
835
|
+
| `validate` | On **Publish** (the builder's button, REST, Local API): every block, after the hooks. In the inspector: the server checks the selected block about half a second after each change (`POST …/validate`). The MCP `validateLayout` tool lists the messages as warnings. | A message blocks **Publish** only, never a draft, autosave or a live session save. It shows under the field and in the problem list. |
|
|
836
|
+
| `hooks.beforeValidate`, `hooks.beforeChange` | On every save on the server: the live session's draft save (about 1 s after the last change, never per keystroke), Publish, Unpublish, Revert, Restore, REST, Local API, GraphQL. | The returned value is stored. Every open editor gets it at once (see below). |
|
|
837
|
+
| `hooks.afterChange` | After every save. | As in Payload: the returned value changes only the saved document that the API returns, not the stored data. |
|
|
838
|
+
| `hooks.afterRead` | On every read: REST, GraphQL, the Local API, versions, and when the builder loads the document into its live session. | The returned value is what the reader gets. |
|
|
839
|
+
| `access.read` | On every read, unless `overrideAccess`. In the builder: when it opens, and again after edits to blocks that have access rules. | The prop is left out of what the user gets. A REST save from that user that leaves it out keeps the stored value. The builder's inspector hides the prop from that user, and inline editing on the canvas refuses it. |
|
|
840
|
+
| `access.update` (`access.create` for a new document) | On every live edit (people, the operations endpoint, MCP agents, the AI assistant) and on other saves, unless `overrideAccess`. In the builder: as `access.read`. | A live edit that changes the prop is refused as a whole, with "You cannot change Price (Product). Nothing was applied." Other saves keep the stored value, as Payload does. A new block may hold the prop only empty, at its default value, or as a copy of a value already on the page (duplicate, paste). The builder's inspector shows the prop read-only, with a lock and a tooltip. Inline editing on the canvas refuses it with "You cannot change Price. You do not have permission to edit it." |
|
|
841
|
+
|
|
842
|
+
Arguments. `validate(value, options)` gets the field config spread in, plus `data` (the whole document), `siblingData` (the block's props, or the group or array row), `blockData` (the block in Payload's shape, `{ id, blockType, ...props }`), `req`, `id`, `operation`, `collectionSlug`, `path`, `previousValue`, `event` (`'submit'`, or `'onChange'` from the inspector), `overrideAccess` and `preferences`. Hooks get `value`, `data`, `siblingData`, `blockData`, `originalDoc`, `previousDoc` (afterChange), `previousValue`, `previousSiblingDoc`, `req`, `operation`, `field`, `path`, `schemaPath`, `context`, `collection`, `global` (null), `overrideAccess`, `siblingFields`, and in afterRead also `findMany`, `depth`, `currentDepth`, `draft` and `showHiddenFields`. `path` is the value's place in the document, for example `['layout', 'blocks', 0, 'props', 'items', 1, 'label']`. `schemaPath` is `['layout', '<block type>', 'items', 'label']`.
|
|
843
|
+
|
|
844
|
+
Access in the builder. When the builder opens, the server runs `access.read` and `access.update` of every block prop for the signed-in user and sends the answer with the document (`GET …/meta`, field `fieldAccess`). The functions get the same arguments as above, with the stored values of the default locale. The answer has one rule per block type (for new blocks) and one per block whose data changes the answer (for example `update: ({ siblingData }) => !siblingData.locked`). After someone adds, removes or changes a block that has access rules, the editor asks again about a second later (`GET …/access`). The server keeps each block's answer for 30 seconds per user, so it runs only the functions of blocks that changed. A function that throws counts as "no".
|
|
845
|
+
|
|
846
|
+
Skipped, as in Payload: `validate` of a field its condition hides. Also skipped: `validate` of a prop the block binds to document data.
|
|
847
|
+
|
|
848
|
+
Hook values and several editors. The live session saves its layout about a second after the last change. When a hook changes a value in that save, the session applies the stored value as one more change from "Field hooks", so every open editor shows it (for example "Red Shoe" becomes "red-shoe" in every inspector). When nobody changed anything during the save, that change counts as saved: no second save. A value someone changed again during the save keeps their newer value, and the next save runs the hook on it. Publish, REST and other saves while the builder is open work the same way.
|
|
849
|
+
|
|
850
|
+
Payload's own default validators are not called again for block fields: the builder's own check already covers types, required props, lengths, ranges, row counts and email addresses. The plugin reads `validate`, `hooks` and `access` once, when it starts, because Payload later adds its defaults to the same field objects.
|
|
851
|
+
|
|
852
|
+
Limits:
|
|
853
|
+
|
|
854
|
+
- `access.read` hides a prop in the builder's inspector, but it does not keep the value secret from editors. Everyone who edits the page shares one live session, and the session sends the whole layout to every editor's browser. The canvas renders what the site renders, so a component that shows the prop shows it on the canvas too. Keep real secrets out of blocks, or give the people who must not see them no update access to the document.
|
|
855
|
+
- In an array, a row that refuses a field locks that field in every row of the inspector. The server still checks each row.
|
|
856
|
+
- On a collection without drafts, nothing is "published", so `validate` messages never block a save. They show in the inspector.
|
|
857
|
+
- Saved sections (`builder-sections`) store blocks without running their field hooks.
|
|
858
|
+
- `migrateBlocksField` writes through the database adapter, so no hooks run. The values come from the old field, where Payload already ran the hooks.
|
|
859
|
+
|
|
860
|
+
## Using existing Payload blocks
|
|
861
|
+
|
|
862
|
+
A site that already has a Payload `blocks` field (for example `pages.layout` with sections and nested blocks) can keep its block configs and its components. The builder gets a field of its own, one script copies the content over, and the old field stays until you remove it.
|
|
863
|
+
|
|
864
|
+
What carries over:
|
|
865
|
+
|
|
866
|
+
- **Block configs.** `fromPayloadBlocks()` turns Payload `Block` configs into builder blocks. Every field stays a Payload field config, so the inspector shows it with Payload's own inputs: text, textarea, email, code, number, checkbox, select, radio, date, upload, relationship, rich text, JSON, point, group, array, row, collapsible and tabs (also `hasMany` text and number).
|
|
867
|
+
- **Nested blocks fields become slots.** A `blocks` field at the block's own level (also inside rows, collapsibles and unnamed tabs) becomes a slot with the same name. Its `blocks` and `blockReferences` become the slot's `allow`, and its `maxRows` and `minRows` become the slot's `max` and `min`.
|
|
868
|
+
- **Conditions.** An `admin.condition` that tests one sibling field, such as `(_, siblingData) => siblingData?.type === 'custom'`, becomes a JSON condition. The inspector hides the field, and an empty required field that is hidden does not block publishing.
|
|
869
|
+
- **Components.** `fromPayloadComponents()` renders components written for Payload's data (`{ blockType, ...fields }`) unchanged.
|
|
870
|
+
- **Field logic.** `validate`, field hooks and field `access` of the block fields run in the builder and the API, as in Payload. See [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields).
|
|
871
|
+
- **Content.** `migrateBlocksField()` converts every document, its drafts and its versions.
|
|
872
|
+
- **Canvas editing.** Text and images of your components edit in place on the canvas, with no marks in your code. See [Inline editing](#inline-editing).
|
|
873
|
+
|
|
874
|
+
### Step by step
|
|
875
|
+
|
|
876
|
+
These steps assume a site like this: `pages.layout` is a `blocks` field that references section blocks (`fullWidth`, `twoColumn`) from `config.blocks`, and the sections have nested `blocks` fields (`content`, `leftColumn`, `rightColumn`) with leaf blocks.
|
|
877
|
+
|
|
878
|
+
**1. Install** the package and add the canvas route, as in [Install](#install).
|
|
879
|
+
|
|
880
|
+
**2. Give the builder its own field.** Keep `layout` as it is.
|
|
881
|
+
|
|
882
|
+
```ts
|
|
883
|
+
websiteBuilder({
|
|
884
|
+
collections: { pages: { field: 'builderLayout', url: (doc) => `/${doc.slug}` } },
|
|
885
|
+
blocks,
|
|
886
|
+
css: { entry: 'src/app/(frontend)/globals.css' },
|
|
887
|
+
})
|
|
888
|
+
```
|
|
889
|
+
|
|
890
|
+
If you give the builder the name of the existing `blocks` field (`field: 'layout'`), the app does not start, and the error points here.
|
|
891
|
+
|
|
892
|
+
**3. Make builder blocks from your block configs.** Put them in the client-safe blocks file:
|
|
893
|
+
|
|
894
|
+
```ts
|
|
895
|
+
// src/builder.ts
|
|
896
|
+
import { defaultBlocks, fromPayloadBlocks } from 'payload-canvas/blocks'
|
|
897
|
+
import { allLeafBlocks, allSectionBlocks } from './blocks'
|
|
898
|
+
|
|
899
|
+
const siteBlocks = fromPayloadBlocks([...allSectionBlocks, ...allLeafBlocks], {
|
|
900
|
+
// The blocks the page's own blocks field allows. The others go only inside the sections that take them.
|
|
901
|
+
root: ['fullWidth', 'twoColumn'],
|
|
902
|
+
// Builder types become siteHeading, siteImage, …, so they do not clash with the default blocks.
|
|
903
|
+
prefix: 'site',
|
|
904
|
+
})
|
|
905
|
+
|
|
906
|
+
export const blocks = [...defaultBlocks({ linkCollections: ['pages'] }), ...siteBlocks]
|
|
907
|
+
```
|
|
908
|
+
|
|
909
|
+
| Option | What it does |
|
|
910
|
+
|---|---|
|
|
911
|
+
| `references` | Your `config.blocks`, when the list you pass does not hold every block that `blockReferences` names. |
|
|
912
|
+
| `root` | Slugs that may go in the page's root list. Every other block gets `parents`: the blocks whose nested blocks fields take it, as in Payload. Default: every block may go anywhere. |
|
|
913
|
+
| `prefix` | Prefix for the builder `type` (`prefix: 'site'` turns `heading` into `siteHeading`). You need it when a slug is also a default block (`heading`, `image`, `button`, `richText`, `list`, `link`, …). The plugin refuses two blocks with the same type. Payload data keeps its `blockType`. |
|
|
914
|
+
| `styles` | Adds `className` and the Styles panel. Default `false`: your components style themselves. |
|
|
915
|
+
| `category` | Library group for blocks without `admin.group`. Default "Site sections" (blocks with slots) or "Site blocks". |
|
|
916
|
+
| `overrides` | Per slug: `label`, `category`, `icon`, `styles`, `defaultClassName`, `classes`, `ai`, `parents`, and `slots` (merged into a slot, for example `{ content: { allow: ['*'] } }`). |
|
|
917
|
+
| `onWarning` | Gets the messages about things that do not carry over. Default: `console.warn` outside production. `false` turns them off. |
|
|
918
|
+
|
|
919
|
+
`labels.singular` becomes the label, and `admin.group` the library category. `interfaceName`, `dbName`, `imageURL` and the block's own admin components are not used.
|
|
920
|
+
|
|
921
|
+
**4. Wrap your components.** Use the same map as your `RenderBlocks`, keyed by Payload slug:
|
|
922
|
+
|
|
923
|
+
```ts
|
|
924
|
+
// src/components/blocks.ts (client-safe)
|
|
925
|
+
import { fromPayloadComponents } from 'payload-canvas/react'
|
|
926
|
+
import { blocks } from '@/builder'
|
|
927
|
+
import { FullWidthComponent } from '@/blocks/sections/fullWidth/component'
|
|
928
|
+
import { HeadingLeaf } from '@/blocks/leaves/heading/component'
|
|
929
|
+
|
|
930
|
+
export const components = fromPayloadComponents({ fullWidth: FullWidthComponent, heading: HeadingLeaf /* … */ }, blocks)
|
|
931
|
+
```
|
|
932
|
+
|
|
933
|
+
Each component gets the props it always got: `{ id, blockType, blockName, ...fields }`. `loadLayoutData` loads uploads and relationships (one level deep), and missing fields get their `defaultValue`. A field someone cleared (`null` or `''`) stays empty, as in Payload. Each slot arrives under its field name as an array of Payload-shaped blocks, so `<RenderLeaves blocks={content} />` keeps working. The component also gets a `builder` prop (see below).
|
|
934
|
+
|
|
935
|
+
- **Components that take `{ block, context }`** instead of the fields as props: add `{ props: (block, context) => ({ block, context }) }` as the third argument. `context` is the page data. See [Page data](#page-data-and--block-context--components).
|
|
936
|
+
- **Components that load data** (async server components, or components that import Payload): leave them out of this client-safe map and put them in the server map. The canvas renders them on the server. See [Server components in the canvas](#server-components-in-the-canvas). A section whose file imports such a component (through its own `RenderLeaves`) goes in the server map too.
|
|
937
|
+
|
|
938
|
+
**5. Convert the content.** Run a dry run first. It writes nothing and lists what it would do:
|
|
939
|
+
|
|
940
|
+
```ts
|
|
941
|
+
// scripts/migrate-blocks.ts
|
|
942
|
+
import config from '@payload-config'
|
|
943
|
+
import { formatMigrationReport, migrateBlocksField } from 'payload-canvas'
|
|
944
|
+
import { getPayload } from 'payload'
|
|
945
|
+
|
|
946
|
+
const payload = await getPayload({ config })
|
|
947
|
+
const report = await migrateBlocksField(payload, {
|
|
948
|
+
collection: 'pages',
|
|
949
|
+
from: 'layout',
|
|
950
|
+
to: 'builderLayout',
|
|
951
|
+
dryRun: !process.argv.includes('write'),
|
|
952
|
+
})
|
|
953
|
+
console.log(formatMigrationReport(report))
|
|
954
|
+
process.exit(0)
|
|
955
|
+
```
|
|
956
|
+
|
|
957
|
+
```bash
|
|
958
|
+
pnpm payload run scripts/migrate-blocks.ts # dry run
|
|
959
|
+
pnpm payload run scripts/migrate-blocks.ts write # convert
|
|
960
|
+
```
|
|
961
|
+
|
|
962
|
+
`payload run` drops `--flags`, so the script reads a plain word. The report gives:
|
|
963
|
+
|
|
964
|
+
- counts for documents and versions,
|
|
965
|
+
- the block types without a definition (left out),
|
|
966
|
+
- the fields with data that no definition has (left out),
|
|
967
|
+
- the layouts that need a fix in the builder (for example a select value that is no longer an option).
|
|
968
|
+
|
|
969
|
+
Close every builder tab while it runs. An open builder keeps its own copy of the layout and saves it again.
|
|
970
|
+
|
|
971
|
+
- Every document, every draft and every version is converted in place. No new versions are made, `updatedAt` and `createdAt` stay (the writes pass `updatedAt: null`, which every Payload adapter reads as "keep"), and the old field never changes.
|
|
972
|
+
- Field values: a stored `null` of a field with a `defaultValue` stays `null` (the field was cleared, so the default does not come back). A field with no key in the old data gets its default, as a new block does.
|
|
973
|
+
- A second run skips documents whose builder field has content. `overwrite: true` converts them again (unchanged results are skipped).
|
|
974
|
+
- After a real run it refreshes the documents' "Used in" records (`backfillReferences`), because its writes skip the save hook.
|
|
975
|
+
- It writes through the database adapter (`updateOne`, `updateVersion`), so no hooks run. It compiles the CSS itself. Tested on Postgres. On MongoDB it converts the documents but not the versions.
|
|
976
|
+
- Options: `where` (only some documents), `versions: false`, `overwrite`, `blocks` (default: the plugin's blocks), `log`.
|
|
977
|
+
|
|
978
|
+
**6. Render pages with the builder.** Change the page route to `RenderLayout` with `page.builderLayout` and `page.builderLayoutCss` (see [step 7 of Install](#7-render-pages-on-the-site)). Pass your wrapped `components` to `RenderLayout` and to `BuilderCanvas`.
|
|
979
|
+
|
|
980
|
+
**7. Keep the old field out of Publish, and remove it later.** Payload publishes the whole document. Without more setup, **Publish** in the builder would also publish the old field's latest draft (for example an edit someone made in the Edit view after the migration). List the old field in `legacyFields`:
|
|
981
|
+
|
|
982
|
+
```ts
|
|
983
|
+
websiteBuilder({
|
|
984
|
+
collections: { pages: { field: 'builderLayout', legacyFields: ['layout'], url: (doc) => `/${doc.slug}` } },
|
|
985
|
+
// …
|
|
986
|
+
})
|
|
987
|
+
```
|
|
988
|
+
|
|
989
|
+
Then **Publish** in the builder sends the old field's published value with the publish, so the site keeps it. The newer draft of the old field stays in the version history, but it is no longer the latest draft. A document that was never published has no published value to keep, so its old field goes live as it is. Publishing from the Edit view or the REST API is not changed. Remove the field and its name in `legacyFields` once every page renders from the builder. The migration report reminds you of this option.
|
|
990
|
+
|
|
991
|
+
### Slots and existing components: the trade-off
|
|
992
|
+
|
|
993
|
+
A component that renders its children itself (`<RenderLeaves blocks={content} />`) works as it is: the site shows the same HTML. In the editor you can select, move and edit the block, and you can edit and move its children in the outline and the inspector. On the canvas you cannot click or drag those children, because your renderer does not give their elements the builder's block ids.
|
|
994
|
+
|
|
995
|
+
To make the children editable on the canvas, render the slot with `PayloadSlot`. In the builder it renders the builder's children (each with its block id) in an element that takes the slot's drop attributes. Outside the builder it renders your old code:
|
|
996
|
+
|
|
997
|
+
```tsx
|
|
998
|
+
import { PayloadSlot, type PayloadBlockProps } from 'payload-canvas/react'
|
|
999
|
+
|
|
1000
|
+
export function TwoColumnComponent({ leftColumn, rightColumn, builder }: PayloadBlockProps<TwoColumnBlock>) {
|
|
1001
|
+
return (
|
|
1002
|
+
<div className="grid gap-10 md:grid-cols-2">
|
|
1003
|
+
<PayloadSlot builder={builder} name="leftColumn" className="space-y-8">
|
|
1004
|
+
<RenderLeaves blocks={leftColumn} />
|
|
1005
|
+
</PayloadSlot>
|
|
1006
|
+
<PayloadSlot builder={builder} name="rightColumn" className="space-y-8">
|
|
1007
|
+
<RenderLeaves blocks={rightColumn} />
|
|
1008
|
+
</PayloadSlot>
|
|
1009
|
+
</div>
|
|
1010
|
+
)
|
|
1011
|
+
}
|
|
1012
|
+
```
|
|
1013
|
+
|
|
1014
|
+
The `builder` prop holds `mode`, `className`, `slots` (rendered children by slot name) and `slotAttributes`. 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.
|
|
1015
|
+
|
|
1016
|
+
### Limitations
|
|
1017
|
+
|
|
1018
|
+
- **Classes in the editor.** Your components' own Tailwind classes come from your site's CSS, which the canvas layout imports ([step 6 of Install](#6-add-the-canvas-route)). A canvas route without that import has CSS only for the block elements' classes.
|
|
1019
|
+
- **Server components that load data** render on the server for the canvas, through the canvas server action ([Server components in the canvas](#server-components-in-the-canvas)). Without the action, the canvas shows "Name: no preview in the editor", and the block stays selectable. Their output updates after a short wait (250 ms after the last change, plus the request), not at once. Data that changes somewhere else shows when the editor opens again.
|
|
1020
|
+
- **Custom admin components** on fields (a custom `Field`) need Payload's form, so the inspector shows the default input for the field type. `fromPayloadBlocks` lists them in a warning.
|
|
1021
|
+
- **Conditions** that read the document, the user or several fields are not converted: the field always shows (also listed in a warning). Function `defaultValue`s of block fields do not run in the builder. `validate`, field hooks and field `access` do run: see [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields).
|
|
1022
|
+
- **Loaded data** is one level deep. A component that needs deeper data loads it itself.
|
|
1023
|
+
- **Blocks fields inside a group, a named tab or an array** stay props, edited as JSON. Localized block fields are not supported.
|
|
1024
|
+
- A Payload slug `list` with an `items` array is read as the old built-in list (`normalizeLayout`). Use `prefix` to avoid that.
|
|
1025
|
+
|
|
1026
|
+
## Sections
|
|
1027
|
+
|
|
1028
|
+
A section is a ready-made block tree: a hero, a feature grid, a footer. Editors insert it from the **Sections** tab. AI agents use sections as their main building unit.
|
|
1029
|
+
|
|
1030
|
+
```ts
|
|
1031
|
+
import type { SectionDefinition } from 'payload-canvas'
|
|
1032
|
+
|
|
1033
|
+
export const sections: SectionDefinition[] = [
|
|
1034
|
+
{
|
|
1035
|
+
id: 'hero',
|
|
1036
|
+
label: 'Hero',
|
|
1037
|
+
category: 'Heroes',
|
|
1038
|
+
description: 'A large heading with a short text and a button.',
|
|
1039
|
+
blocks: [
|
|
1040
|
+
{
|
|
1041
|
+
id: 'b_hero',
|
|
1042
|
+
type: 'stack',
|
|
1043
|
+
className: 'flex flex-col items-center gap-6 py-24 text-center',
|
|
1044
|
+
slots: {
|
|
1045
|
+
children: [
|
|
1046
|
+
{ id: 'b_title', type: 'heading', props: { text: 'Build faster', level: '1' }, className: 'text-5xl font-bold' },
|
|
1047
|
+
{ id: 'b_cta', type: 'button', props: { label: 'Start', link: { type: 'url', url: '/contact' } } },
|
|
1048
|
+
],
|
|
1049
|
+
},
|
|
1050
|
+
},
|
|
1051
|
+
],
|
|
1052
|
+
},
|
|
1053
|
+
]
|
|
1054
|
+
```
|
|
1055
|
+
|
|
1056
|
+
Pass them to `websiteBuilder({ sections })` and to `builderMcpTools({ sections })`. Block ids are regenerated on every insert.
|
|
1057
|
+
|
|
1058
|
+
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.
|
|
1059
|
+
|
|
1060
|
+
### Saved sections
|
|
1061
|
+
|
|
1062
|
+
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.
|
|
1063
|
+
|
|
1064
|
+
**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. A change applies only to later inserts; the top bar says so ("Pages keep their copy"). The section's **Builder** tab in the admin opens the same view.
|
|
1065
|
+
|
|
1066
|
+
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.
|
|
1067
|
+
|
|
1068
|
+
The plugin stores them in the `builder-sections` collection (next to Templates in the admin nav). The MCP tools and the AI assistant see them too: `listSections` lists them with `saved: true`, and `insertSection` takes `saved:<id>`, the document id or the section's name.
|
|
1069
|
+
|
|
1070
|
+
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.
|
|
1071
|
+
|
|
1072
|
+
## Styling
|
|
1073
|
+
|
|
1074
|
+
- **Classes.** Each block stores Tailwind v4 classes in `className`. Variants use normal Tailwind syntax: `md:flex-row`, `hover:bg-primary`, `dark:text-white`.
|
|
1075
|
+
- **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. The **Classes** box accepts any class.
|
|
1076
|
+
- **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.
|
|
1077
|
+
- **In the editor.** The canvas compiles the classes in the browser with Tailwind's own compiler. A new class shows at once.
|
|
1078
|
+
- **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.
|
|
1079
|
+
- **Block elements only.** Every generated rule matches only elements with the class `builder-css` (`.flex:where(.builder-css)`). `RenderLayout` adds it to each block's `className`, so a block component needs nothing. Your own components keep the order of your site's CSS, even when a layout on the page uses the same classes. If you render layouts with your own renderer, add `builder-css` to each element that gets a block's classes (`withBuilderCssClass` from `payload-canvas/blocks`).
|
|
1080
|
+
- **Tailwind plugins.** Pass them as a map on the server and in the canvas page. The canvas page must be a client component, because plugins are functions:
|
|
1081
|
+
|
|
1082
|
+
```ts
|
|
1083
|
+
// payload.config.ts
|
|
1084
|
+
import typography from '@tailwindcss/typography'
|
|
1085
|
+
websiteBuilder({ css: { entry: 'src/app/(frontend)/globals.css', plugins: { '@tailwindcss/typography': typography } } })
|
|
1086
|
+
```
|
|
1087
|
+
|
|
1088
|
+
```tsx
|
|
1089
|
+
// builder-canvas/page.tsx ('use client')
|
|
1090
|
+
import typography from '@tailwindcss/typography'
|
|
1091
|
+
const plugins = { '@tailwindcss/typography': typography }
|
|
1092
|
+
export default function CanvasPage() {
|
|
1093
|
+
return <BuilderCanvas blocks={blocks} plugins={plugins} />
|
|
1094
|
+
}
|
|
1095
|
+
```
|
|
1096
|
+
|
|
1097
|
+
- **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.
|
|
1098
|
+
- **Standalone output** needs `outputFileTracingIncludes`. See [step 8](#8-add-the-standalone-tracing-lines).
|
|
1099
|
+
|
|
1100
|
+
## Animations
|
|
1101
|
+
|
|
1102
|
+
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.
|
|
1103
|
+
|
|
1104
|
+
### In the editor
|
|
1105
|
+
|
|
1106
|
+
- Select a block and open the **Motion** tab in the inspector (next to Content and Styles). It has four sections: **Entrance**, **Hover and press**, **Scroll** and **Loop**. Pick a preset, then adjust its settings.
|
|
1107
|
+
- **Preview** plays the block's animation once on the canvas. Picking a preset also plays it.
|
|
1108
|
+
- The canvas shows every block at rest, so it never moves while you edit. **Play animations** (the icon button in the status bar under the canvas) plays the page as visitors see it: entrances on scroll, hover, parallax and loops.
|
|
1109
|
+
- Layers marks animated blocks with a small icon. Its tooltip names the animations.
|
|
1110
|
+
- **Copy styles** and **Paste styles** carry the animations with the classes. **Reset styles** removes classes only.
|
|
1111
|
+
- Changes go through the normal operations, so undo and multiplayer work as for any edit.
|
|
1112
|
+
|
|
1113
|
+
### Data
|
|
1114
|
+
|
|
1115
|
+
A block stores its animations in `motion`. Every kind is optional. Times are milliseconds, distances pixels. `motion` is left out when it holds nothing.
|
|
1116
|
+
|
|
1117
|
+
```json
|
|
1118
|
+
{
|
|
1119
|
+
"id": "b_cards",
|
|
1120
|
+
"type": "grid",
|
|
1121
|
+
"className": "grid grid-cols-3 gap-6",
|
|
1122
|
+
"motion": {
|
|
1123
|
+
"enter": { "preset": "fade-up", "stagger": 80 },
|
|
1124
|
+
"hover": { "preset": "lift" },
|
|
1125
|
+
"press": { "preset": "shrink" }
|
|
1126
|
+
}
|
|
1127
|
+
}
|
|
1128
|
+
```
|
|
1129
|
+
|
|
1130
|
+
| Kind | Presets | Settings (default) |
|
|
1131
|
+
|---|---|---|
|
|
1132
|
+
| `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` |
|
|
1133
|
+
| `hover` | `lift`, `grow`, `tilt` | `distance` (lift, 4), `scale` (grow, 1.03), `angle` (tilt, 6) |
|
|
1134
|
+
| `press` | `shrink` | `scale` (0.97) |
|
|
1135
|
+
| `scroll` | `parallax`, `fade`, `zoom` | `distance` (parallax, 60; negative moves with the scroll), `scale` (zoom start, 0.9) |
|
|
1136
|
+
| `loop` | `float`, `pulse` | `duration` (3000 float, 1500 pulse), `distance` (float, 8), `scale` (pulse, 1.04) |
|
|
1137
|
+
|
|
1138
|
+
- **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).
|
|
1139
|
+
- **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.
|
|
1140
|
+
- 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.
|
|
1141
|
+
|
|
1142
|
+
### On the site
|
|
1143
|
+
|
|
1144
|
+
- `RenderLayout` puts each animated block's settings on its root element: `data-motion` (JSON), plus `data-motion-item` on the children of a staggering block. Block components need nothing: the attributes come in `attributes`, which every component spreads on its root element.
|
|
1145
|
+
- When a layout has motion, `RenderLayout` also renders `<MotionStyle blocks={layout.blocks} />` (a small `<style>` in the head, once per page) and `<MotionRuntime />` (a client component that renders nothing). Pages without motion get neither, and load no motion code.
|
|
1146
|
+
- `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:
|
|
1147
|
+
- 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.
|
|
1148
|
+
- 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.
|
|
1149
|
+
- 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.
|
|
1150
|
+
- Loops pause while the block is out of view.
|
|
1151
|
+
- **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.
|
|
1152
|
+
- **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.
|
|
1153
|
+
- **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.
|
|
1154
|
+
- **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.
|
|
1155
|
+
|
|
1156
|
+
### Custom components and renderers
|
|
1157
|
+
|
|
1158
|
+
- A custom block component spreads `attributes` on its root element, as before. That is all it needs.
|
|
1159
|
+
- A component made with `fromPayloadComponent` gets the attributes on its class wrapper (`className: 'wrap'`, the default, for blocks with styles). Without a wrapper, they go on the component's first element after hydration, so an entrance above the fold can flash once on load. Keep the wrapper for animated blocks.
|
|
1160
|
+
- Your own renderer: put `motionAttributes(block.motion, isStaggerChild)` (from `payload-canvas/core`) on each block's root element, and render `<MotionStyle blocks={layout.blocks} />` and `<MotionRuntime />` from `payload-canvas/react` once on pages with motion. Without `blocks`, entrances on load wait for the runtime like entrances on scroll. `startMotion()` and `previewMotion(element)` are exported for other setups.
|
|
1161
|
+
- Parallax on an image inside a frame: give the frame `overflow-hidden` and a fixed height, and make the image taller than the frame (for example `h-[120%]`), so the moving image never shows an edge.
|
|
1162
|
+
|
|
1163
|
+
## Theme
|
|
1164
|
+
|
|
1165
|
+
The plugin adds a **Theme** global (slug `theme-settings`). Editors pick the site's colors, fonts, corner radius and spacing unit with Payload-native color, font and slider pickers. The site and the builder canvas get the theme as CSS variables. Your Tailwind `@theme` maps those variables to classes, so `bg-primary`, `font-heading` and `rounded-lg` follow the theme.
|
|
1166
|
+
|
|
1167
|
+
**What editors set, and the variables it writes:**
|
|
1168
|
+
|
|
1169
|
+
| Field | Variables |
|
|
1170
|
+
|---|---|
|
|
1171
|
+
| Colors: primary, secondary, accent, muted, destructive | `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--accent`, `--accent-foreground`, `--muted`, `--muted-foreground`, `--destructive`, `--destructive-foreground` |
|
|
1172
|
+
| Colors: background, foreground | `--background`, `--foreground`, `--card`, `--card-foreground`, `--popover`, `--popover-foreground`, `--border`, `--input` |
|
|
1173
|
+
| Derived from the colors | `--ring`, `--chart-1` … `--chart-5`, `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring` |
|
|
1174
|
+
| Fonts: body text, headings, code (any Google Font) | `--font-sans`, `--font-heading`, `--font-mono` |
|
|
1175
|
+
| Corner radius (rem) | `--radius` |
|
|
1176
|
+
| Spacing unit (px) | `--spacing` (Tailwind's spacing unit: `p-4` is 4 units) |
|
|
1177
|
+
|
|
1178
|
+
The names are the shadcn/ui names. Colors are stored as hex and written as `oklch(…)`. Each foreground color is dark or light, whichever reads on its color. Borders and secondary text are mixed from the background and the foreground. An empty field writes nothing, so your CSS default stays.
|
|
1179
|
+
|
|
1180
|
+
**1. Map the variables in your CSS entry.** Your `globals.css` stays yours. Set defaults on `:root` and map them in `@theme inline`:
|
|
1181
|
+
|
|
1182
|
+
```css
|
|
1183
|
+
:root {
|
|
1184
|
+
--background: oklch(1 0 0);
|
|
1185
|
+
--foreground: oklch(0.145 0 0);
|
|
1186
|
+
--primary: oklch(0.205 0 0);
|
|
1187
|
+
--primary-foreground: oklch(0.985 0 0);
|
|
1188
|
+
--radius: 0.625rem;
|
|
1189
|
+
/* …the other colors you use */
|
|
1190
|
+
}
|
|
1191
|
+
|
|
1192
|
+
@theme {
|
|
1193
|
+
--font-sans: ui-sans-serif, system-ui, sans-serif; /* the theme's body font replaces it */
|
|
1194
|
+
--font-heading: var(--font-sans); /* `font-heading`; the theme's heading font replaces it */
|
|
1195
|
+
}
|
|
1196
|
+
|
|
1197
|
+
@theme inline {
|
|
1198
|
+
--color-background: var(--background);
|
|
1199
|
+
--color-foreground: var(--foreground);
|
|
1200
|
+
--color-primary: var(--primary);
|
|
1201
|
+
--color-primary-foreground: var(--primary-foreground);
|
|
1202
|
+
--radius-sm: calc(var(--radius) - 4px);
|
|
1203
|
+
--radius-md: calc(var(--radius) - 2px);
|
|
1204
|
+
--radius-lg: var(--radius);
|
|
1205
|
+
--radius-xl: calc(var(--radius) + 4px);
|
|
1206
|
+
/* …one --color-* line per color you use */
|
|
1207
|
+
}
|
|
1208
|
+
```
|
|
1209
|
+
|
|
1210
|
+
A shadcn/ui project already has all of this. Font aliases work too: with `--font-display: var(--font-heading, var(--font-sans))`, `font-display` uses the heading font, or the body font when the theme has no heading font.
|
|
1211
|
+
|
|
1212
|
+
**2. Render the theme in the `<head>`** of the site's root layout, and in the `<body>` of the canvas layout with `live` ([step 6](#6-add-the-canvas-route); React moves its tags into the head):
|
|
1213
|
+
|
|
1214
|
+
```tsx
|
|
1215
|
+
// src/app/(frontend)/layout.tsx
|
|
1216
|
+
import { ThemeStyle } from 'payload-canvas/react/server'
|
|
1217
|
+
import config from '@payload-config'
|
|
1218
|
+
import { getPayload } from 'payload'
|
|
1219
|
+
import type { ReactNode } from 'react'
|
|
1220
|
+
import './globals.css'
|
|
1221
|
+
|
|
1222
|
+
export default async function RootLayout({ children }: { children: ReactNode }) {
|
|
1223
|
+
const payload = await getPayload({ config })
|
|
1224
|
+
return (
|
|
1225
|
+
<html lang="en">
|
|
1226
|
+
<head>
|
|
1227
|
+
<ThemeStyle payload={payload} />
|
|
1228
|
+
</head>
|
|
1229
|
+
<body>{children}</body>
|
|
1230
|
+
</html>
|
|
1231
|
+
)
|
|
1232
|
+
}
|
|
1233
|
+
```
|
|
1234
|
+
|
|
1235
|
+
`ThemeStyle` writes one `<style>` tag and one Google Fonts `<link>` for the chosen families. Both use React's `precedence`, so React places them in the `<head>` itself and they never cause a hydration mismatch. The rule uses `:root:root { … }`, so it wins over your `:root` defaults in any load order.
|
|
1236
|
+
|
|
1237
|
+
For about 90 popular families (Inter, Roboto, Newsreader, Hanken Grotesk and others in `theme/fallbacks.ts`) the `<style>` tag also holds a fallback `@font-face` (`'Inter Fallback'`: Arial or Times New Roman, scaled with `size-adjust` and the ascent, descent and line-gap overrides), and `--font-sans` lists it after the family. The text then keeps its size and line height when the web font loads, so the swap moves nothing (on the demo home page, CLS fell from 0.0007 to 0.00004). Other families keep the plain `sans-serif` or `serif` fallback.
|
|
1238
|
+
|
|
1239
|
+
| Prop | Default | What it does |
|
|
1240
|
+
|---|---|---|
|
|
1241
|
+
| `payload` | required | The Payload instance. |
|
|
1242
|
+
| `fonts` | `true` | `false` leaves the Google Fonts links out (for self-hosted fonts). |
|
|
1243
|
+
| `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. |
|
|
1244
|
+
|
|
1245
|
+
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.
|
|
1246
|
+
|
|
1247
|
+
**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.
|
|
1248
|
+
|
|
1249
|
+
**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)`).
|
|
1250
|
+
|
|
1251
|
+
**Options:**
|
|
1252
|
+
|
|
1253
|
+
```ts
|
|
1254
|
+
websiteBuilder({
|
|
1255
|
+
// …
|
|
1256
|
+
theme: {
|
|
1257
|
+
slug: 'theme-settings', // default
|
|
1258
|
+
label: 'Theme', // default
|
|
1259
|
+
access: { update: isAdmin }, // default: anyone reads, signed-in users update
|
|
1260
|
+
admin: { group: 'Settings' }, // merged into the global's admin config (group, livePreview, …)
|
|
1261
|
+
hooks: { afterChange: [log] }, // run after the plugin's own hooks
|
|
1262
|
+
cacheTag: 'theme-settings', // default: the slug
|
|
1263
|
+
},
|
|
1264
|
+
})
|
|
1265
|
+
```
|
|
1266
|
+
|
|
1267
|
+
`theme: false` leaves out the global, the endpoint and the theme fonts in the Styles panel. The plugin throws an error if a global with the same slug exists already.
|
|
1268
|
+
|
|
1269
|
+
**The pickers on other fields.** They work on any text field (the slider also on number fields):
|
|
1270
|
+
|
|
1271
|
+
```ts
|
|
1272
|
+
{ name: 'brandColor', type: 'text', admin: { components: { Field: 'payload-canvas/theme-client#ThemeColorField' } } }
|
|
1273
|
+
{ name: 'titleFont', type: 'text', admin: { components: { Field: 'payload-canvas/theme-client#ThemeFontField' } } }
|
|
1274
|
+
{ name: 'gap', type: 'number', admin: { components: { Field: 'payload-canvas/theme-client#ThemeSliderField' }, custom: { min: 0, max: 64, step: 4, unit: 'px' } } }
|
|
1275
|
+
```
|
|
1276
|
+
|
|
1277
|
+
## Templates and binding
|
|
1278
|
+
|
|
1279
|
+
Templates let one layout render many documents, for example every post. Turn them on per collection:
|
|
1280
|
+
|
|
1281
|
+
```ts
|
|
1282
|
+
websiteBuilder({
|
|
1283
|
+
collections: {
|
|
1284
|
+
pages: { url: (doc) => `/${doc.slug}` },
|
|
1285
|
+
posts: { templates: true, url: (doc) => `/blog/${doc.slug}` },
|
|
1286
|
+
},
|
|
1287
|
+
templates: { slug: 'builder-templates' }, // optional; this is the default
|
|
1288
|
+
// ...
|
|
1289
|
+
})
|
|
1290
|
+
```
|
|
1291
|
+
|
|
1292
|
+
What the plugin adds:
|
|
1293
|
+
|
|
1294
|
+
- 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`).
|
|
1295
|
+
- A `template` relationship in the sidebar of every document in a collection with `templates: true`.
|
|
1296
|
+
|
|
1297
|
+
Which template a document uses: its own `template`, else the newest default template of its collection, else none. Templates with an empty layout are skipped.
|
|
1298
|
+
|
|
1299
|
+
### Bindings and dynamic blocks
|
|
1300
|
+
|
|
1301
|
+
- 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.
|
|
1302
|
+
- 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.
|
|
1303
|
+
- 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 it 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 site shows published documents only. It works on normal pages too, not only in templates.
|
|
1304
|
+
|
|
1305
|
+
### Render a document through its template
|
|
1306
|
+
|
|
1307
|
+
```tsx
|
|
1308
|
+
import { RenderLayout } from 'payload-canvas/react'
|
|
1309
|
+
import { loadLayoutData, loadTemplate } from 'payload-canvas/react/server'
|
|
1310
|
+
|
|
1311
|
+
// depth: 1, so bound uploads and relationships are documents, not IDs
|
|
1312
|
+
const { docs } = await payload.find({ collection: 'posts', where: { slug: { equals: slug } }, limit: 1, depth: 1, draft })
|
|
1313
|
+
const post = docs[0]
|
|
1314
|
+
if (!post) notFound()
|
|
1315
|
+
|
|
1316
|
+
const found = await loadTemplate(payload, { collection: 'posts', doc: post, draft })
|
|
1317
|
+
if (!found) notFound() // or render a fallback
|
|
1318
|
+
|
|
1319
|
+
const context = { collection: 'posts', doc: post }
|
|
1320
|
+
const layout = await loadLayoutData(found.layout, blocks, payload, { draft, context, resolveLink })
|
|
1321
|
+
|
|
1322
|
+
return <RenderLayout layout={layout} css={found.css} context={context} blocks={blocks} resolveLink={resolveLink} />
|
|
1323
|
+
```
|
|
1324
|
+
|
|
1325
|
+
- `loadTemplate(payload, { collection, doc, templatesSlug?, draft? })` returns `{ template, layout, css }` or `null`. Without `draft` it uses published templates only.
|
|
1326
|
+
- `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`.
|
|
1327
|
+
- `getByPath(doc, path)` and `resolveBindings(layout, context, blocks)` from `payload-canvas/core` do the same work for a custom renderer.
|
|
1328
|
+
|
|
1329
|
+
## References and Used in
|
|
1330
|
+
|
|
1331
|
+
A layout is one JSON value, so Payload cannot see which images and documents a page uses. The plugin keeps a list of them in a hidden field. With it, Payload shows where a media file is used, refuses to delete a file that a page still uses, and gives search and sitemap code clean relation data.
|
|
1332
|
+
|
|
1333
|
+
What the plugin adds:
|
|
1334
|
+
|
|
1335
|
+
- **A hidden `builderRefs` field** on every builder collection, the templates collection and the saved sections collection. It is a polymorphic `relationship` field with `hasMany`. It points at every collection the blocks can reference: the `relationTo` of upload and relationship props, the collections of link fields, and the upload collections when a block has a rich text prop.
|
|
1336
|
+
- **A save hook** that fills the field from the layout on every save that sends the layout: the live session's draft saves, publish, the Edit view, the REST API and the Local API. The field is server-owned. The hook ignores values that clients send. A save without the layout keeps the stored list.
|
|
1337
|
+
- **"Used in"** on the media collection: a "Used in" section in the edit view lists the pages, posts, templates and sections that use the file, one Payload `join` field per builder collection (`usedInPages`, `usedInBuilderTemplates`, …). Empty lists are hidden. The REST and Local APIs return the same join fields.
|
|
1338
|
+
- **Delete protection** on the media collection: deleting a file that a builder document still uses fails with "This document is still used by Home (Pages), About (Pages) and 3 more. Remove it from those documents first." The edit view, the list view's bulk delete and the API all show this message.
|
|
1339
|
+
|
|
1340
|
+
What counts as a reference:
|
|
1341
|
+
|
|
1342
|
+
- Upload and relationship props, also inside groups, arrays, blocks fields and named tabs. Nested slots and hidden blocks count.
|
|
1343
|
+
- Link groups (`linkField()`) of type "Page or document". A URL link that still holds an old document choice does not count.
|
|
1344
|
+
- Upload, relationship and internal link nodes in rich text props.
|
|
1345
|
+
- Not bindings: a bound prop reads the rendered document at runtime, so it has no fixed ID. The prop's own value (its fallback) counts.
|
|
1346
|
+
- IDs of documents that do not exist are left out, so a save never fails on a deleted image.
|
|
1347
|
+
|
|
1348
|
+
Which version counts. Collections with drafts have two states. The delete protection checks both the published document and the latest draft. "Used in" in the admin shows the latest drafts. When a draft no longer uses a file but the published page still does, the delete is refused, but "Used in" does not list that page. Publish the page, then delete the file.
|
|
1349
|
+
|
|
1350
|
+
Options:
|
|
1351
|
+
|
|
1352
|
+
```ts
|
|
1353
|
+
websiteBuilder({
|
|
1354
|
+
// ...
|
|
1355
|
+
references: {
|
|
1356
|
+
field: 'builderRefs', // name of the hidden field
|
|
1357
|
+
usedIn: ['media', 'forms'], // collections that show "Used in"; default: the upload collections the blocks use
|
|
1358
|
+
protectDelete: ['media'], // collections that refuse to delete used documents; default: the same upload collections
|
|
1359
|
+
maxListed: 5, // how many documents the error message names
|
|
1360
|
+
},
|
|
1361
|
+
})
|
|
1362
|
+
```
|
|
1363
|
+
|
|
1364
|
+
- `references: false` turns all of this off.
|
|
1365
|
+
- To delete a used document anyway, pass the context flag: `payload.delete({ collection: 'media', id, context: { builderForceDelete: true } })` (`FORCE_DELETE_CONTEXT` from `payload-canvas`). Postgres removes the deleted document from every `builderRefs` list.
|
|
1366
|
+
- `findReferrers(payload, { relationTo: 'media', value: id })` from `payload-canvas` returns the builder documents that use a document (published and latest draft), for your own checks.
|
|
1367
|
+
- Search and sitemaps can query the field like any relationship: `where: { builderRefs: { equals: { relationTo: 'media', value: id } } }`.
|
|
1368
|
+
|
|
1369
|
+
**Existing documents.** Documents saved before this version have an empty list until their next save. To fill them now, run the backfill once:
|
|
1370
|
+
|
|
1371
|
+
```ts
|
|
1372
|
+
// scripts/backfill-references.ts — run with `pnpm payload run ./scripts/backfill-references.ts`
|
|
1373
|
+
import { getPayload } from 'payload'
|
|
1374
|
+
import config from '@payload-config'
|
|
1375
|
+
import { backfillReferences } from 'payload-canvas'
|
|
1376
|
+
|
|
1377
|
+
const payload = await getPayload({ config })
|
|
1378
|
+
console.log(await backfillReferences(payload))
|
|
1379
|
+
process.exit(0)
|
|
1380
|
+
```
|
|
1381
|
+
|
|
1382
|
+
It writes only the `builderRefs` field of each document and of each latest draft, through the database adapter: no hooks run, no new versions, and `updatedAt` does not change. It skips documents that are already right, so you can run it again.
|
|
1383
|
+
|
|
1384
|
+
**Database schema.** The field adds rows to the builder collections' `_rels` tables (and their version tables). In development, `pnpm dev` pushes the change. Before a production deploy, create a migration with `pnpm payload migrate:create`.
|
|
1385
|
+
|
|
1386
|
+
## Localization
|
|
1387
|
+
|
|
1388
|
+
Turn on Payload's `localization`, and builder pages translate. Every language shares one layout: the same blocks, order, classes and bindings. Only the text props differ per language. This is the Webflow model.
|
|
1389
|
+
|
|
1390
|
+
```ts
|
|
1391
|
+
buildConfig({
|
|
1392
|
+
localization: { locales: [{ code: 'en', label: 'English' }, { code: 'de', label: 'Deutsch' }], defaultLocale: 'en', fallback: true },
|
|
1393
|
+
plugins: [websiteBuilder({ … })],
|
|
1394
|
+
})
|
|
1395
|
+
```
|
|
1396
|
+
|
|
1397
|
+
**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, quote and source, 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.
|
|
1398
|
+
|
|
1399
|
+
**How it is stored.** The default language stays in `props`. Each other language keeps only its own values in `locales`:
|
|
1400
|
+
|
|
1401
|
+
```json
|
|
1402
|
+
{ "id": "b_1", "type": "heading", "props": { "text": "Hello", "level": "2" }, "locales": { "de": { "text": "Hallo" } } }
|
|
1403
|
+
```
|
|
1404
|
+
|
|
1405
|
+
A value a language does not have falls back, as Payload's `fallback` and `fallbackLocale` say (text and textarea also fall back when empty). Layouts saved before localization keep working: their values are the default language.
|
|
1406
|
+
|
|
1407
|
+
**The editor.**
|
|
1408
|
+
|
|
1409
|
+
- The top bar has a language switcher (the globe). The canvas shows the chosen language, and the inspector edits it. The address keeps it as `?locale=de`, Payload's convention, so a reload opens the same language.
|
|
1410
|
+
- In another language than the default, a translated field says **Translated** (with **Use English**, which removes the translation). An untranslated field says **Not translated · shows English**: text fields show the English text as a greyed placeholder, other fields show the English value greyed. **Copy English** copies the value, so you can change it. A note above the tabs has **Copy N fields from English** for the whole block.
|
|
1411
|
+
- The outline marks blocks with untranslated text with an orange dot.
|
|
1412
|
+
- Inline editing on the canvas writes the shown language.
|
|
1413
|
+
- Blocks, order, classes and fields that are not localized change every language. The inspector says so, and the first such edit in another language shows a notice.
|
|
1414
|
+
- A new block holds its text in the language you add it in. Add a heading in German, and its text is German only: English has no text for it yet. This covers blocks from the Blocks tab, the "+" between blocks, a new list item (Enter) and blocks the assistant adds. Pasted, duplicated and section content keeps its own languages.
|
|
1415
|
+
- A field that has text in another language but none in the default language says **Missing in English**. In English it has **Copy German**, and the note above the tabs copies every such field at once. The outline dot and the language switcher count these fields in the default language too.
|
|
1416
|
+
- Related documents load in the shown language: collection lists, images and relationships, the template's preview document and server-rendered blocks. Switching the language loads them again.
|
|
1417
|
+
- Collaborators see each other's language in the avatar (a small "DE") and in its tooltip. Structure changes reach everyone at once; each person sees the text of their own language. Undo stays per person.
|
|
1418
|
+
|
|
1419
|
+
**Saving and publishing.** Every save checks the translations too. The default language must fill every required prop. Another language needs its own value only when it has no fallback (`fallback: false`). The publish problem list names the language: "Heading: fill in text (DE)". A required prop that only another language has names the default language: "Heading: fill in text (EN)". So a block added in German blocks Publish until someone writes its English text. Field `validate`, `hooks` and `access` of localized props run for each language's values too, with `req.locale` set to that language.
|
|
1420
|
+
|
|
1421
|
+
**The site and the API.** Read a document with a locale and the layout comes back in that language, with fallback, without `locales`:
|
|
1422
|
+
|
|
1423
|
+
- REST: `GET /api/pages/1?locale=de` (add `&fallback-locale=none` for no fallback). `?locale=all` gives the stored form with `locales`.
|
|
1424
|
+
- Local API: `payload.find({ collection: 'pages', locale: 'de' })`.
|
|
1425
|
+
- A save with a locale (`PATCH /api/pages/1?locale=de`, the Edit view in German) writes the localized props to that language and keeps the others, as Payload does for localized fields. A value equal to the fallback the reader saw stays a fallback.
|
|
1426
|
+
|
|
1427
|
+
Render the site with the same locale everywhere:
|
|
1428
|
+
|
|
1429
|
+
```tsx
|
|
1430
|
+
const page = await payload.find({ collection: 'pages', where, locale })
|
|
1431
|
+
const template = await loadTemplate(payload, { collection: 'posts', doc: post, draft, locale })
|
|
1432
|
+
const layout = await loadLayoutData(page.layout, blocks, payload, { draft, locale }) // documents and lists in German too
|
|
1433
|
+
```
|
|
1434
|
+
|
|
1435
|
+
`loadLayoutData` also resolves a layout in the stored form (`localizeLayout` from `/server` does it alone). The generated CSS is the same for every language, because classes are shared. Bindings read the document you pass, so load it with the same `locale`.
|
|
1436
|
+
|
|
1437
|
+
**AI and MCP.** `getLayout` and `applyOperations` take `locale`. `getLayout` returns that language's view, the localized props of each block type and the untranslated props per block. `applyOperations` with a locale writes that language's text, also the text of blocks it inserts; other changes affect every language. `insertSection` keeps the section's own text. In the editor, the assistant works in the language you have open. Operations name their language as `update { id, props, locale }` and `insert { block, to, locale }` (the block's localized props are that language's).
|
|
1438
|
+
|
|
1439
|
+
**References.** Every language's values count: a German image is "used" too.
|
|
1440
|
+
|
|
1441
|
+
**Per collection.** `collections: { pages: { localization: false } }` keeps one set of values for every language. A separate layout per language (`localized: true` on the whole field, so the structure differs per language) is not supported yet.
|
|
1442
|
+
|
|
1443
|
+
**Limits.**
|
|
1444
|
+
|
|
1445
|
+
- Classes and structure are always shared.
|
|
1446
|
+
- `migrateBlocksField` keeps translations. When the old `blocks` field, or a field inside its blocks, is localized, it reads every language and stores each language's own values of localized props in `locales`. When the whole `blocks` field is localized, the default language gives the structure, and other languages' blocks match it by block id, then by position and type. The report lists blocks it could not match, and fields that differ per language but are not marked `localized: true` (add it to keep them).
|
|
1447
|
+
|
|
1448
|
+
## AI assistant
|
|
1449
|
+
|
|
1450
|
+
The editor gets an **Assistant** panel. The user types a request, for example "add a pricing section with three tiers", and the model edits the open page. Each change appears on the canvas as it happens. One reply is one undo step. The assistant never saves or publishes: the editor saves the page as usual.
|
|
1451
|
+
|
|
1452
|
+
An **adapter** connects the assistant to a model API, the same way Payload uses adapters for the database, storage and email. Each built-in adapter has its own import path, so your site loads only the one you use. Full guide: [docs/ai/providers.md](https://github.com/jon8800/payload-canvas/blob/main/docs/ai/providers.md).
|
|
1453
|
+
|
|
1454
|
+
No API key? Claude Code and Codex can edit pages with your Claude or ChatGPT plan over MCP: [docs/ai/connect-claude-code-and-codex.md](https://github.com/jon8800/payload-canvas/blob/main/docs/ai/connect-claude-code-and-codex.md). The panel shows the commands (link icon in its header).
|
|
1455
|
+
|
|
1456
|
+
### Turn it on
|
|
1457
|
+
|
|
1458
|
+
```ts
|
|
1459
|
+
import { openRouterAdapter } from 'payload-canvas/ai/openrouter'
|
|
1460
|
+
|
|
1461
|
+
websiteBuilder({
|
|
1462
|
+
collections,
|
|
1463
|
+
blocks,
|
|
1464
|
+
sections,
|
|
1465
|
+
css: { entry: 'src/app/(frontend)/globals.css' },
|
|
1466
|
+
ai: {
|
|
1467
|
+
adapter: openRouterAdapter({ apiKey: process.env.OPENROUTER_API_KEY }),
|
|
1468
|
+
},
|
|
1469
|
+
})
|
|
1470
|
+
```
|
|
1471
|
+
|
|
1472
|
+
Then put the key in `.env` and restart the server. Get a key at [openrouter.ai/keys](https://openrouter.ai/keys).
|
|
1473
|
+
|
|
1474
|
+
```bash
|
|
1475
|
+
OPENROUTER_API_KEY=sk-or-v1-...
|
|
1476
|
+
```
|
|
1477
|
+
|
|
1478
|
+
The default model is `openai/gpt-6-luna`: cheap and good at tool calls. Pick another one with `model`.
|
|
1479
|
+
|
|
1480
|
+
Without an adapter, or without a key, the panel shows a setup card. The card says what to set.
|
|
1481
|
+
|
|
1482
|
+
### Adapters
|
|
1483
|
+
|
|
1484
|
+
| Import | Adapter | Notes |
|
|
1485
|
+
|---|---|---|
|
|
1486
|
+
| `payload-canvas/ai/openrouter` | `openRouterAdapter({ apiKey, model?, siteUrl? })` | One key for hundreds of models. Easiest start. |
|
|
1487
|
+
| `payload-canvas/ai/cloudflare-gateway` | `cloudflareGatewayAdapter({ accountId, gatewayId, model, gatewayToken?, apiKey? })` | Cloudflare AI Gateway in front of OpenAI, Anthropic, Google and others. Supports stored keys and unified billing. |
|
|
1488
|
+
| `payload-canvas/ai/cloudflare-workers-ai` | `cloudflareWorkersAIAdapter({ accountId, apiToken, model?, gatewayId? })` | Models that run on Cloudflare (Workers AI). Only models with function calling work. |
|
|
1489
|
+
| `payload-canvas/ai/openai-compatible` | `openAICompatibleAdapter({ baseURL, model, apiKey? })` | OpenAI, Groq, Together, Ollama, LM Studio, vLLM and other Chat Completions servers. |
|
|
1490
|
+
| `payload-canvas/ai/anthropic` | `anthropicAdapter({ apiKey?, model? })` | The Anthropic Messages API with prompt caching, adaptive thinking and the refusal fallback. Needs `pnpm add @anthropic-ai/sdk`. |
|
|
1491
|
+
| `payload-canvas/ai/fake` | `fakeAdapter()` | A scripted model for tests and demos. No network, no cost. Never use it in production. |
|
|
1492
|
+
|
|
1493
|
+
Examples:
|
|
1494
|
+
|
|
1495
|
+
```ts
|
|
1496
|
+
ai: { adapter: openRouterAdapter({ apiKey: process.env.OPENROUTER_API_KEY, model: 'google/gemini-3.8-flash' }) }
|
|
1497
|
+
ai: { adapter: openAICompatibleAdapter({ baseURL: 'http://localhost:11434/v1', model: 'llama3.3' }) }
|
|
1498
|
+
ai: { adapter: anthropicAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }) }
|
|
1499
|
+
```
|
|
1500
|
+
|
|
1501
|
+
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 when `OPENROUTER_API_KEY` is set, else no adapter.
|
|
1502
|
+
|
|
1503
|
+
### Options
|
|
1504
|
+
|
|
1505
|
+
| Option | Default | What it does |
|
|
1506
|
+
|---|---|---|
|
|
1507
|
+
| `adapter` | none | The model API. See [Adapters](#adapters). Without it the panel shows the setup card. |
|
|
1508
|
+
| `effort` | the adapter's default (Anthropic: `medium`) | How much the model thinks: `low`, `medium`, `high`, `xhigh`, `max`. Anthropic and OpenRouter use it. `openAICompatibleAdapter` sends it as `reasoning_effort` with `reasoningEffort: true`. |
|
|
1509
|
+
| `instructions` | none | Extra rules for the assistant, for example your brand voice. Added to the end of the system prompt. |
|
|
1510
|
+
| `maxSteps` | `12` | Maximum tool rounds per user message. |
|
|
1511
|
+
| `mediaCollection` | `media` | The upload collection the assistant picks images from, and where generated images go. |
|
|
1512
|
+
| `images` | none | The image adapter. See [Image generation](#image-generation). |
|
|
1513
|
+
| `imageLimits` | `{ perRequest: 3, perHour: 20 }` | Images per assistant reply, and per user per hour. |
|
|
1514
|
+
| `imageMarkerField` | `generatedBy` | A media field that gets a note on generated images, when the collection has it. `false` turns it off. |
|
|
1515
|
+
|
|
1516
|
+
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.
|
|
1517
|
+
|
|
1518
|
+
### Write your own adapter
|
|
1519
|
+
|
|
1520
|
+
An adapter is a plain object of type `AiAdapter` from `payload-canvas/ai`. You do not need to change the plugin.
|
|
1521
|
+
|
|
1522
|
+
```ts
|
|
1523
|
+
type AiAdapter = {
|
|
1524
|
+
name: string // short id, e.g. "my-api". Part of the chat identity.
|
|
1525
|
+
label: string // shown in the panel
|
|
1526
|
+
model: string
|
|
1527
|
+
ready: boolean // false: the panel shows the setup card
|
|
1528
|
+
setupProblem?: string | null // one sentence for the developer, e.g. "Set MY_API_KEY."
|
|
1529
|
+
keyEnv?: string | null // shown in the setup card
|
|
1530
|
+
keyUrl?: string | null // "Get an API key" link
|
|
1531
|
+
stream(request: AiModelRequest): AsyncIterable<AiModelEvent>
|
|
1532
|
+
}
|
|
1533
|
+
```
|
|
1534
|
+
|
|
1535
|
+
`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:
|
|
1536
|
+
|
|
1537
|
+
- `{ type: 'text', text }`: assistant text as it arrives.
|
|
1538
|
+
- `{ type: 'toolStart', id, name }`: optional. The panel shows a running chip.
|
|
1539
|
+
- `{ type: 'toolCall', id, name, input }`: one complete tool call. Add `error` when the arguments could not be read: the tool does not run, and the model gets the error.
|
|
1540
|
+
- `{ type: 'usage', usage: { inputTokens, outputTokens } }`: optional.
|
|
1541
|
+
- `{ type: 'done', stopReason, content }`: `stopReason` is `end_turn`, `tool_use`, `max_tokens`, `refusal` or `pause_turn`. `content` is the assistant message the chat stores and sends back next time. Use the block types `text` and `tool_use` (add your own types for data you must send back, such as reasoning).
|
|
1542
|
+
- `{ type: 'error', code, message }`: `code` is `auth` (the panel shows the setup card), `aborted`, `api_error` or `invalid_output` (the loop calls the model again). Yield it instead of throwing.
|
|
1543
|
+
|
|
1544
|
+
Stored messages use the block types `text`, `tool_use` and `tool_result`. The agent loop runs the tools and adds the `tool_result` blocks.
|
|
1545
|
+
|
|
1546
|
+
This example wraps a Chat Completions endpoint without streaming, in about 40 lines:
|
|
1547
|
+
|
|
1548
|
+
```ts
|
|
1549
|
+
import { chatTools, parseArguments, toChatMessages, type AiAdapter, type AiContentBlock } from 'payload-canvas/ai'
|
|
1550
|
+
|
|
1551
|
+
export function myAdapter({ url, apiKey, model }: { url: string; apiKey?: string; model: string }): AiAdapter {
|
|
1552
|
+
return {
|
|
1553
|
+
name: 'my-api',
|
|
1554
|
+
label: 'My API',
|
|
1555
|
+
model,
|
|
1556
|
+
ready: Boolean(apiKey),
|
|
1557
|
+
setupProblem: apiKey ? null : 'Set MY_API_KEY in .env and restart the server.',
|
|
1558
|
+
keyEnv: 'MY_API_KEY',
|
|
1559
|
+
async *stream({ system, messages, tools, signal }) {
|
|
1560
|
+
const response = await fetch(url, {
|
|
1561
|
+
method: 'POST',
|
|
1562
|
+
headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
|
|
1563
|
+
body: JSON.stringify({ model, messages: toChatMessages(system, messages), tools: chatTools(tools) }),
|
|
1564
|
+
signal,
|
|
1565
|
+
}).catch((error: Error) => error)
|
|
1566
|
+
if (response instanceof Error) {
|
|
1567
|
+
yield { type: 'error', code: signal?.aborted ? 'aborted' : 'api_error', message: response.message }
|
|
1568
|
+
return
|
|
1569
|
+
}
|
|
1570
|
+
if (!response.ok) {
|
|
1571
|
+
yield { type: 'error', code: response.status === 401 ? 'auth' : 'api_error', message: `My API returned ${response.status}.` }
|
|
1572
|
+
return
|
|
1573
|
+
}
|
|
1574
|
+
const data = await response.json()
|
|
1575
|
+
const message = data.choices[0].message
|
|
1576
|
+
const content: AiContentBlock[] = []
|
|
1577
|
+
if (message.content) {
|
|
1578
|
+
yield { type: 'text', text: message.content }
|
|
1579
|
+
content.push({ type: 'text', text: message.content })
|
|
1580
|
+
}
|
|
1581
|
+
for (const call of message.tool_calls ?? []) {
|
|
1582
|
+
const parsed = parseArguments(call.function.arguments)
|
|
1583
|
+
const input = 'input' in parsed ? parsed.input : {}
|
|
1584
|
+
content.push({ type: 'tool_use', id: call.id, name: call.function.name, input })
|
|
1585
|
+
yield { type: 'toolCall', id: call.id, name: call.function.name, input, ...('error' in parsed ? { error: parsed.error } : {}) }
|
|
1586
|
+
}
|
|
1587
|
+
yield { type: 'done', stopReason: message.tool_calls?.length ? 'tool_use' : 'end_turn', content }
|
|
1588
|
+
},
|
|
1589
|
+
}
|
|
1590
|
+
}
|
|
1591
|
+
```
|
|
1592
|
+
|
|
1593
|
+
For a streaming OpenAI-format API, `createOpenAIFormatAdapter({ name, label, model, url, authHeaders, keyHint })` from the same import does all of this, with streaming, retries and timeouts. The built-in OpenRouter and Cloudflare adapters use it.
|
|
1594
|
+
|
|
1595
|
+
### Image generation
|
|
1596
|
+
|
|
1597
|
+
The assistant, the inspector (a **Generate image** button under every upload field) and MCP clients can make new images. The site saves each image in the media collection, with alt text. Image generation has its own adapter, so it works with any chat model, and also for Claude Code or Codex over MCP:
|
|
1598
|
+
|
|
1599
|
+
```ts
|
|
1600
|
+
import { openRouterImageAdapter } from 'payload-canvas/ai/images/openrouter'
|
|
1601
|
+
|
|
1602
|
+
ai: {
|
|
1603
|
+
adapter: openRouterAdapter({ apiKey: process.env.OPENROUTER_API_KEY }),
|
|
1604
|
+
images: openRouterImageAdapter({ apiKey: process.env.OPENROUTER_API_KEY }), // default model: black-forest-labs/flux.2-klein-4b
|
|
1605
|
+
}
|
|
1606
|
+
```
|
|
1607
|
+
|
|
1608
|
+
| Import | Adapter |
|
|
1609
|
+
|---|---|
|
|
1610
|
+
| `payload-canvas/ai/images/openrouter` | `openRouterImageAdapter({ apiKey, model? })`: every image model on OpenRouter. About 1.5 US cents per image with the default model. |
|
|
1611
|
+
| `payload-canvas/ai/images/openai` | `openAIImageAdapter({ apiKey, model?, baseURL?, quality? })`: the OpenAI Images API and compatible servers. |
|
|
1612
|
+
| `payload-canvas/ai/images/cloudflare-workers-ai` | `cloudflareWorkersAIImageAdapter({ accountId, apiToken, model? })`: FLUX and other models on Cloudflare. |
|
|
1613
|
+
| `payload-canvas/ai/images/fake` | `fakeImageAdapter()`: a local gradient PNG for tests. |
|
|
1614
|
+
|
|
1615
|
+
A chat model does not return images through the chat API, even when its app can make images. That is why the image adapter is a separate setting. Without it, the Generate button stays hidden and the `generateImage` tool says what to set up. Uploads run as the signed-in user, after a `create` access check. Limits, cost, the "generated by" note and writing your own `AiImageAdapter`: [docs/ai/images.md](https://github.com/jon8800/payload-canvas/blob/main/docs/ai/images.md).
|
|
1616
|
+
|
|
1617
|
+
### What it can do
|
|
1618
|
+
|
|
1619
|
+
- Insert ready-made sections and then change their text, images and classes. It prefers your sections over building from single blocks.
|
|
1620
|
+
- Add, move, duplicate, hide and remove blocks, and change props and Tailwind classes. It knows your theme colors, fonts and breakpoints, the selected block and the canvas width.
|
|
1621
|
+
- Pick images from the media library (it searches alt text and file names as the signed-in user), or generate new ones with `ai.images`.
|
|
1622
|
+
- In templates, bind block props to document fields.
|
|
1623
|
+
|
|
1624
|
+
Every change goes through the same operations as the editor and is checked against the block schemas. A change that would make the layout invalid is rolled back, and the model gets the error and tries again.
|
|
1625
|
+
|
|
1626
|
+
### Access
|
|
1627
|
+
|
|
1628
|
+
`POST /api/builder/ai/chat` needs a signed-in user who may update the document (Payload access control, `overrideAccess: false`). Media searches run as that user too.
|
|
1629
|
+
|
|
1630
|
+
### Cost
|
|
1631
|
+
|
|
1632
|
+
You pay the provider for each request. Each request sends the system prompt (blocks, sections, theme, tools; about 8,000 tokens in the starter), the conversation and the current layout. A typical request ("add a pricing section") takes two to four model calls.
|
|
1633
|
+
|
|
1634
|
+
- OpenRouter `openai/gpt-6-luna` ($0.10 / $0.50 per million tokens): well under one US cent per request.
|
|
1635
|
+
- Anthropic `claude-opus-5-5` at `medium` effort ($4 / $20 per million tokens): roughly 5 to 30 US cents per request. The fixed prompt is cached, so repeat requests within 5 minutes read it at a tenth of the price or less.
|
|
1636
|
+
|
|
1637
|
+
Long conversations and large pages cost more. Start a new conversation when the topic changes. Changing the adapter or the model starts a new chat.
|
|
1638
|
+
|
|
1639
|
+
### Privacy
|
|
1640
|
+
|
|
1641
|
+
The page content goes to the provider you pick (and through OpenRouter or Cloudflare when you use them): the layout JSON (all text, classes and media IDs), the conversation, media search results (alt text, file names, URLs), and for templates a summary of the sample document. Do not turn the assistant on for content that must not leave your servers. Check the provider's data policy.
|
|
1642
|
+
|
|
1643
|
+
### Testing without a key
|
|
1644
|
+
|
|
1645
|
+
`fakeAdapter()` from `payload-canvas/ai/fake` is a scripted model with no network calls. It lists the sections, inserts a hero section at the top of the page, changes its heading, and streams a few sentences. In the starter, set `BUILDER_AI_FAKE=1` in `.env` (ignored when `NODE_ENV=production`) and restart the server. For your own tests, pass `fakeAdapter({ steps: [...] })` with one scripted reply per model call.
|
|
1646
|
+
|
|
1647
|
+
## AI editing over MCP
|
|
1648
|
+
|
|
1649
|
+
The builder adds tools to [`payload-mcp-toolkit`](https://www.npmjs.com/package/payload-mcp-toolkit). An AI agent reads the blocks and sections, edits the draft layout, and every open editor shows the change at once.
|
|
1650
|
+
|
|
1651
|
+
```bash
|
|
1652
|
+
pnpm add payload-mcp-toolkit zod
|
|
1653
|
+
```
|
|
1654
|
+
|
|
1655
|
+
```ts
|
|
1656
|
+
import { mcpToolkitPlugin } from 'payload-mcp-toolkit'
|
|
1657
|
+
import { builderMcpTools } from 'payload-canvas/mcp'
|
|
1658
|
+
|
|
1659
|
+
const collections = { pages: { url: (doc) => `/${doc.slug}` } }
|
|
1660
|
+
|
|
1661
|
+
plugins: [
|
|
1662
|
+
mcpToolkitPlugin({
|
|
1663
|
+
customTools: builderMcpTools({ blocks, sections, collections }),
|
|
1664
|
+
}),
|
|
1665
|
+
websiteBuilder({ collections, blocks, sections, css: { entry: 'src/app/(frontend)/globals.css' } }),
|
|
1666
|
+
]
|
|
1667
|
+
```
|
|
1668
|
+
|
|
1669
|
+
- 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).
|
|
1670
|
+
- 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.
|
|
1671
|
+
- Tools (`listSections` and `insertSection` include [saved sections](#saved-sections)): `listBlocks`, `getBlockSchema`, `listSections`, `insertSection`, `getLayout`, `applyOperations`, `validateLayout`, `getPreviewUrl`, `generateImage`, plus `listTemplates` and `getBindingSources` for templates.
|
|
1672
|
+
- `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.
|
|
1673
|
+
- Every tool checks the key's access to the collection. Handlers run as the key's user with `overrideAccess: false`.
|
|
1674
|
+
- 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.
|
|
1675
|
+
- `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`).
|
|
1676
|
+
|
|
1677
|
+
## Multiplayer editing
|
|
1678
|
+
|
|
1679
|
+
Several people can have the same page open in the builder. Each change shows for the others at once, with their selections and pointers in their own color. AI agents over MCP join the same way.
|
|
1680
|
+
|
|
1681
|
+
How it works:
|
|
1682
|
+
|
|
1683
|
+
- The server keeps one live session per open document, in memory. The session holds the layout and a sequence number `seq`.
|
|
1684
|
+
- An editor applies its own change at once, then sends it to `commit`. The server applies changes in the order they arrive, raises `seq` by 1, and sends each change to every open editor. A change that no longer applies (for example, someone deleted its block) is rejected, and that editor drops it.
|
|
1685
|
+
- The server saves the session as a draft about 1 second after the last change (at the latest every 5 seconds). The save runs as the person who made the last change, with their access rules, and the normal save hook compiles the CSS.
|
|
1686
|
+
- While a session is open, the session owns the layout. Any other save of the document gets the session's layout: a stale autosave from another tab, a REST update, or **Publish**. Publish therefore publishes what everyone sees in the editor.
|
|
1687
|
+
- Every editor gets a `saved` event after each save and a `published` event after Publish, Unpublish or Revert, so the top bar shows the same status for everyone.
|
|
1688
|
+
- The session closes 60 seconds after the last editor leaves and its draft is saved.
|
|
1689
|
+
|
|
1690
|
+
The other fields (title, slug, SEO, …) are edited in Payload's Edit view or in the builder's **Page settings** drawer. They are protected in two ways:
|
|
1691
|
+
|
|
1692
|
+
- **Payload's document lock stays on.** The first person who changes a field in the Edit view or the settings drawer takes the lock. A second person who opens the form sees Payload's "locked by" dialog and can view it read-only or take over. The builder view itself never takes the lock, so layout editing, Publish, Unpublish, Revert and AI edits keep working while someone has the form open. These saves skip the lock and keep it.
|
|
1693
|
+
- **Out-of-date forms cannot undo newer changes.** Payload removes the lock after every save of the lock holder, autosave included, so on a collection with autosave the lock is often gone. The plugin therefore also checks each save from the Edit view or the drawer. If the form was loaded before someone else changed a field, and the save would put back the old value, the save fails with 409: "Not saved. Ana changed Title after you opened this form. Reload it to get their changes, then make your edit again." The record of who changed what lives in server memory, so it starts empty after a restart. Two tabs of the same person are not checked against each other.
|
|
1694
|
+
|
|
1695
|
+
To turn the lock off for a collection, set `lockDocuments: false` on it. The out-of-date check still runs.
|
|
1696
|
+
|
|
1697
|
+
Limits:
|
|
1698
|
+
|
|
1699
|
+
- Sessions live in the memory of one server process. With more than one app server, route all requests for a document to the same server (sticky routing), or keep one app server.
|
|
1700
|
+
- Two people who change the same prop at the same time: the later change wins.
|
|
1701
|
+
- 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.
|
|
1702
|
+
- Two people typing in the same text field at the same moment: the later value wins for the whole field.
|
|
1703
|
+
|
|
1704
|
+
## Production and Docker
|
|
1705
|
+
|
|
1706
|
+
- **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.
|
|
1707
|
+
- **Standalone output** needs `outputFileTracingIncludes`. See [step 8](#8-add-the-standalone-tracing-lines).
|
|
1708
|
+
- **Media.** Keep `public/media` (or your upload directory) on a volume.
|
|
1709
|
+
- **Secrets.** `PAYLOAD_SECRET` and `DATABASE_URL` are read at runtime.
|
|
1710
|
+
- The starter app in this repository has a working `Dockerfile` for a pnpm monorepo.
|
|
1711
|
+
|
|
1712
|
+
## Deploying
|
|
1713
|
+
|
|
1714
|
+
Run **one server process** for the app. Live sessions, the event streams and the record that protects the other fields live in that process's memory. Several app servers, a cluster or a serverless platform would split one document's editors across processes, and they would not see each other's edits.
|
|
1715
|
+
|
|
1716
|
+
Put a reverse proxy in front for TLS. This nginx config works:
|
|
1717
|
+
|
|
1718
|
+
```nginx
|
|
1719
|
+
server {
|
|
1720
|
+
listen 443 ssl;
|
|
1721
|
+
http2 on; # recommended, see below
|
|
1722
|
+
server_name example.com;
|
|
1723
|
+
# ssl_certificate …; ssl_certificate_key …;
|
|
1724
|
+
|
|
1725
|
+
client_max_body_size 50m; # media uploads
|
|
1726
|
+
|
|
1727
|
+
gzip on; # the app has compress: false, so nginx compresses
|
|
1728
|
+
gzip_proxied any;
|
|
1729
|
+
gzip_types text/css application/javascript application/json image/svg+xml text/x-component;
|
|
1730
|
+
# text/html is always compressed. text/event-stream is not in the list, so it stays uncompressed.
|
|
1731
|
+
|
|
1732
|
+
location / {
|
|
1733
|
+
proxy_pass http://127.0.0.1:3000;
|
|
1734
|
+
proxy_http_version 1.1;
|
|
1735
|
+
proxy_set_header Connection ''; # HTTP/1.1 to the app, without "Connection: close"
|
|
1736
|
+
proxy_set_header Host $host;
|
|
1737
|
+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
1738
|
+
proxy_set_header X-Forwarded-Proto $scheme;
|
|
1739
|
+
}
|
|
1740
|
+
}
|
|
1741
|
+
```
|
|
1742
|
+
|
|
1743
|
+
Notes:
|
|
1744
|
+
|
|
1745
|
+
- **The event stream must not be buffered.** The live endpoint (`/api/builder/live/…/events`) sends `X-Accel-Buffering: no` and `Cache-Control: no-cache, no-transform`, so nginx streams it and compression skips it. Next's own compression is off (`compress: false`, install step 9), so the stream is never compressed inside the app either. Behind nginx, an edit reaches the other editors in about 10 ms. With another proxy or a CDN, turn off response buffering and compression for `text/event-stream`.
|
|
1746
|
+
- **Idle streams stay open.** The server sends a heartbeat every 10 s (`live.heartbeatMs`). That is well inside nginx's default `proxy_read_timeout` of 60 s. If you raise the heartbeat interval, keep it below your proxy's read timeout.
|
|
1747
|
+
- **Use HTTP/2 to the browser.** Over HTTP/1.1 a browser opens at most 6 connections per site, and each open builder tab keeps one of them for its event stream. With several builder tabs open, the admin and the site in the same browser start to wait for connections. HTTP/2 sends everything over one connection.
|
|
1748
|
+
- **Database schema.** This version keeps Payload's document lock on for builder collections (earlier versions set `lockDocuments: false`). That adds one column per builder collection to `payload_locked_documents_rels`. Create a migration (`pnpm payload migrate:create`) and run it before you start the new version, or every save of a builder document fails with "column … does not exist".
|
|
1749
|
+
- **References need a migration too.** The `builderRefs` field (see [References and Used in](#references-and-used-in)) adds columns to the `_rels` tables of every builder collection and their version tables. Create a migration with `pnpm payload migrate:create` before you deploy, then run `backfillReferences(payload)` once.
|
|
1750
|
+
|
|
1751
|
+
## Troubleshooting
|
|
1752
|
+
|
|
1753
|
+
**The admin crashes with errors from `@payloadcms/ui` hooks (for example a missing provider), or fields render blank.** Your app has two copies of `@payloadcms/ui`. Check:
|
|
1754
|
+
|
|
1755
|
+
```bash
|
|
1756
|
+
pnpm why @payloadcms/ui
|
|
1757
|
+
```
|
|
1758
|
+
|
|
1759
|
+
All entries must show one version. Pin `payload`, `@payloadcms/*` and `next` to the same versions across your workspace, then run `pnpm install`. In a monorepo, check that the app and the builder resolve to the same folder: `readlink -f node_modules/@payloadcms/ui` (or `Get-Item node_modules\@payloadcms\ui | Select-Object Target` in PowerShell).
|
|
1760
|
+
|
|
1761
|
+
**The builder is empty, or the log says the layout field "is no longer a top-level field".** Another plugin moved the field into tabs after the builder added it (for example `seoPlugin({ tabbedUI: true })`). Put `websiteBuilder` last in `plugins`.
|
|
1762
|
+
|
|
1763
|
+
**"Collection "x" does not exist".** The plugin runs before the collection is added. Add the collection in `collections`, or put `websiteBuilder` after the plugin that adds it.
|
|
1764
|
+
|
|
1765
|
+
**The builder shows "Module not found", "not found" or no editor.** Run `pnpm payload generate:importmap` after you add or update the plugin.
|
|
1766
|
+
|
|
1767
|
+
**The canvas stays blank or shows "Canvas CSS failed to load".** Check that `/builder-canvas` (or your `canvasPath`) renders, that it uses a root layout with `<html>` and `<body>`, and that `css.entry` points to a file that exists.
|
|
1768
|
+
|
|
1769
|
+
**A class shows in the editor but not on the site.** The site must pass `css={page.<field>Css?.css}` to `RenderLayout` (or use `compilePageCss`). The element with the block's classes must also have the class `builder-css`: `RenderLayout` adds it to the `className` prop, so check that the component puts `className` on the element. Classes that a component in a package hardcodes must be listed in the block's `classes`, and the element needs `builder-css` too.
|
|
1770
|
+
|
|
1771
|
+
**The production log repeats `MaxListenersExceededWarning: 11 drain listeners added to [Gzip]`.** Next's built-in compression leaks one listener per backpressure event while it streams a large HTML page. The builder does not cause it. Set `compress: false` in `next.config.ts` and compress in your reverse proxy. See install step 9.
|
|
1772
|
+
|
|
1773
|
+
**Saving fails in production with "Cannot read stylesheet".** Standalone output is missing a CSS file. Add it to `outputFileTracingIncludes`.
|
|
1774
|
+
|
|
1775
|
+
**Saving fails with "Tailwind plugin "x" is used by @plugin in the CSS entry but is not in the plugins map".** Add the plugin to `css.plugins` and to the canvas page's `plugins`.
|
|
1776
|
+
|
|
1777
|
+
**"Collection "pages" already has a "blocks" field named "layout"".** The builder needs a `json` field. Give it its own name (`field: 'builderLayout'`) and convert the content: see [Using existing Payload blocks](#using-existing-payload-blocks).
|
|
1778
|
+
|
|
1779
|
+
**"Two blocks have the type "heading"".** A block made with `fromPayloadBlocks` has the same type as another block. Set `prefix` in `fromPayloadBlocks`.
|
|
1780
|
+
|
|
1781
|
+
**After adding `payload-mcp-toolkit`, `user.email` fails to typecheck.** The toolkit adds an API-key auth strategy, so `req.user` and `payload.auth()` can return an API key. Check `'email' in user` before you read user fields.
|
|
1782
|
+
|
|
1783
|
+
**Turbopack.** The package works with Turbopack (`next dev` and `next build`, the default in Next 16) and webpack. It ships `.scss` files for the admin, which Next compiles the same way it compiles Payload's own SCSS.
|
|
1784
|
+
|
|
1785
|
+
## Limits
|
|
1786
|
+
|
|
1787
|
+
This is version 0.1. Before 1.0, a minor version can change the API. Known limits:
|
|
1788
|
+
|
|
1789
|
+
- **Payload 3 only.** Payload 4 (canary today) changes the admin UI. The builder does not support it yet.
|
|
1790
|
+
- **Next.js and React only.** The admin editor and the canvas need a Next.js app (Payload's own requirement). Other frontends can render the stored JSON with their own code.
|
|
1791
|
+
- **`RenderLayout` needs React Server Components.** `RenderLayout` and the `payload-canvas/react/server` helpers need the Next.js App Router (or another RSC framework).
|
|
1792
|
+
- **The canvas runtime runs only in the editor's iframe.** `payload-canvas/react/canvas` belongs on the canvas route and nowhere else.
|
|
1793
|
+
- **Tailwind CSS v4 only.** Styles are Tailwind classes, compiled from your Tailwind v4 entry CSS.
|
|
1794
|
+
- **One server process.** Live sessions live in memory. See [Multiplayer editing](#multiplayer-editing) and [Deploying](#deploying). Serverless platforms are not supported.
|
|
1795
|
+
- **Tested databases.** Postgres is tested end to end. Other Payload adapters store the layout in a JSON field and should work, but are not tested.
|
|
1796
|
+
- **The editor's own labels are in English.** Payload's inputs inside it follow the admin language.
|
|
1797
|
+
|
|
1798
|
+
## License
|
|
1799
|
+
|
|
1800
|
+
MIT
|