payload-canvas 0.4.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +625 -153
- package/dist/admin/AiKeyField.d.ts +8 -0
- package/dist/admin/AiKeyField.js +54 -0
- package/dist/admin/BuilderTab.js +4 -1
- package/dist/admin/DocumentEditView.d.ts +9 -0
- package/dist/admin/DocumentEditView.js +45 -0
- package/dist/admin/LayoutField.d.ts +2 -2
- package/dist/admin/LayoutField.js +10 -7
- package/dist/admin/TemplateConditionsField.d.ts +9 -0
- package/dist/admin/TemplateConditionsField.js +22 -0
- package/dist/admin/aiKeyField.scss +58 -0
- package/dist/admin/client.d.ts +3 -0
- package/dist/admin/client.js +6 -0
- package/dist/admin/diff/changes.js +5 -0
- package/dist/admin/editor/Canvas.js +20 -5
- package/dist/admin/editor/Editor.d.ts +3 -1
- package/dist/admin/editor/Editor.js +6 -3
- package/dist/admin/editor/Inspector.js +75 -28
- package/dist/admin/editor/Library.js +40 -15
- package/dist/admin/editor/Outline.js +21 -16
- package/dist/admin/editor/Overlay.js +8 -3
- package/dist/admin/editor/actions.d.ts +10 -2
- package/dist/admin/editor/actions.js +18 -3
- package/dist/admin/editor/assistant/AssistantPanel.js +3 -1
- package/dist/admin/editor/classes/ClassManager.d.ts +4 -0
- package/dist/admin/editor/classes/ClassManager.js +56 -0
- package/dist/admin/editor/classes/controller.d.ts +112 -0
- package/dist/admin/editor/classes/controller.js +326 -0
- package/dist/admin/editor/classes/manager.scss +262 -0
- package/dist/admin/editor/classes/managerModel.d.ts +5 -0
- package/dist/admin/editor/classes/managerModel.js +27 -0
- package/dist/admin/editor/comments/CommentLayer.d.ts +2 -0
- package/dist/admin/editor/comments/CommentLayer.js +143 -0
- package/dist/admin/editor/comments/CommentsPanel.d.ts +8 -0
- package/dist/admin/editor/comments/CommentsPanel.js +73 -0
- package/dist/admin/editor/comments/Thread.d.ts +26 -0
- package/dist/admin/editor/comments/Thread.js +84 -0
- package/dist/admin/editor/comments/comments.scss +539 -0
- package/dist/admin/editor/comments/controller.d.ts +48 -0
- package/dist/admin/editor/comments/controller.js +142 -0
- package/dist/admin/editor/contentMode.d.ts +17 -0
- package/dist/admin/editor/contentMode.js +37 -0
- package/dist/admin/editor/dnd/DropOutlines.d.ts +1 -0
- package/dist/admin/editor/dnd/DropOutlines.js +73 -0
- package/dist/admin/editor/dnd/dnd.scss +43 -0
- package/dist/admin/editor/dnd/mode.d.ts +4 -0
- package/dist/admin/editor/dnd/mode.js +39 -0
- package/dist/admin/editor/editor.scss +13 -58
- package/dist/admin/editor/empty/EmptyStart.js +18 -66
- package/dist/admin/editor/fields/AddButton.d.ts +15 -0
- package/dist/admin/editor/fields/AddButton.js +14 -0
- package/dist/admin/editor/fields/ArrayField.js +3 -2
- package/dist/admin/editor/fields/CheckedInputs.d.ts +1 -0
- package/dist/admin/editor/fields/ConditionRows.d.ts +19 -0
- package/dist/admin/editor/fields/ConditionRows.js +137 -0
- package/dist/admin/editor/fields/ListWhereField.d.ts +8 -0
- package/dist/admin/editor/fields/ListWhereField.js +20 -0
- package/dist/admin/editor/fields/QueryFiltersField.d.ts +18 -0
- package/dist/admin/editor/fields/QueryFiltersField.js +41 -0
- package/dist/admin/editor/fields/RelatedField.d.ts +19 -0
- package/dist/admin/editor/fields/RelatedField.js +44 -0
- package/dist/admin/editor/fields/SortField.d.ts +13 -0
- package/dist/admin/editor/fields/SortField.js +37 -0
- package/dist/admin/editor/fields/WhereField.d.ts +12 -4
- package/dist/admin/editor/fields/WhereField.js +33 -53
- package/dist/admin/editor/fields/collectionFields.d.ts +6 -0
- package/dist/admin/editor/fields/collectionFields.js +15 -0
- package/dist/admin/editor/fields/conditions.d.ts +99 -0
- package/dist/admin/editor/fields/conditions.js +339 -0
- package/dist/admin/editor/fields/fields.scss +232 -9
- package/dist/admin/editor/fields/listOptions.d.ts +44 -0
- package/dist/admin/editor/fields/listOptions.js +111 -0
- package/dist/admin/editor/fields/queryFilterRows.d.ts +8 -0
- package/dist/admin/editor/fields/queryFilterRows.js +29 -0
- package/dist/admin/editor/fields/whereRows.d.ts +11 -12
- package/dist/admin/editor/fields/whereRows.js +83 -34
- package/dist/admin/editor/icons.d.ts +16 -1
- package/dist/admin/editor/icons.js +30 -1
- package/dist/admin/editor/inline.js +9 -0
- package/dist/admin/editor/insert/InsertHandle.js +4 -1
- package/dist/admin/editor/insert/picker.d.ts +3 -1
- package/dist/admin/editor/insert/picker.js +17 -10
- package/dist/admin/editor/insert/spots.d.ts +12 -1
- package/dist/admin/editor/insert/spots.js +49 -10
- package/dist/admin/editor/layout/LeftPanel.js +11 -6
- package/dist/admin/editor/live/useMultiplayer.js +9 -1
- package/dist/admin/editor/menu/blockMenu.js +27 -17
- package/dist/admin/editor/names.js +11 -3
- package/dist/admin/editor/renderField.d.ts +3 -1
- package/dist/admin/editor/renderField.js +63 -12
- package/dist/admin/editor/runtime.d.ts +14 -0
- package/dist/admin/editor/runtime.js +67 -6
- package/dist/admin/editor/sections/ComponentFields.d.ts +8 -0
- package/dist/admin/editor/sections/ComponentFields.js +116 -0
- package/dist/admin/editor/sections/PropertyControls.d.ts +18 -0
- package/dist/admin/editor/sections/PropertyControls.js +65 -0
- package/dist/admin/editor/sections/components.d.ts +29 -0
- package/dist/admin/editor/sections/components.js +112 -0
- package/dist/admin/editor/sections/components.scss +238 -0
- package/dist/admin/editor/sections/variants.d.ts +32 -0
- package/dist/admin/editor/sections/variants.js +59 -0
- package/dist/admin/editor/sections/variants.scss +90 -0
- package/dist/admin/editor/shortcuts.d.ts +4 -1
- package/dist/admin/editor/shortcuts.js +19 -3
- package/dist/admin/editor/store.d.ts +18 -0
- package/dist/admin/editor/store.js +46 -0
- package/dist/admin/editor/styles/ClassBar.d.ts +14 -0
- package/dist/admin/editor/styles/ClassBar.js +90 -0
- package/dist/admin/editor/styles/ClassCss.d.ts +4 -0
- package/dist/admin/editor/styles/ClassCss.js +28 -0
- package/dist/admin/editor/styles/ClassDialog.d.ts +2 -0
- package/dist/admin/editor/styles/ClassDialog.js +151 -0
- package/dist/admin/editor/styles/ColorPicker.js +5 -2
- package/dist/admin/editor/styles/RawClasses.d.ts +26 -1
- package/dist/admin/editor/styles/RawClasses.js +184 -32
- package/dist/admin/editor/styles/StylesPanel.d.ts +3 -3
- package/dist/admin/editor/styles/StylesPanel.js +53 -14
- package/dist/admin/editor/styles/VariantBar.js +2 -2
- package/dist/admin/editor/styles/classEdit.d.ts +4 -0
- package/dist/admin/editor/styles/classEdit.js +20 -0
- package/dist/admin/editor/styles/classes.scss +381 -0
- package/dist/admin/editor/styles/context.d.ts +19 -6
- package/dist/admin/editor/styles/context.js +24 -6
- package/dist/admin/editor/styles/controls.d.ts +3 -1
- package/dist/admin/editor/styles/controls.js +30 -12
- package/dist/admin/editor/styles/popover.d.ts +6 -0
- package/dist/admin/editor/styles/popover.js +5 -5
- package/dist/admin/editor/styles/styles.scss +26 -104
- package/dist/admin/editor/styles/suggestions.d.ts +22 -0
- package/dist/admin/editor/styles/suggestions.js +77 -0
- package/dist/admin/editor/styles/tokens.js +14 -0
- package/dist/admin/editor/templates/Bindable.js +86 -57
- package/dist/admin/editor/templates/SamplePicker.js +1 -1
- package/dist/admin/editor/templates/Visibility.d.ts +9 -0
- package/dist/admin/editor/templates/Visibility.js +54 -0
- package/dist/admin/editor/templates/binding.d.ts +2 -2
- package/dist/admin/editor/templates/binding.js +2 -2
- package/dist/admin/editor/templates/templates.scss +27 -0
- package/dist/admin/editor/templates/visibilityRows.d.ts +22 -0
- package/dist/admin/editor/templates/visibilityRows.js +83 -0
- package/dist/admin/editor/topbar/ContentModeToggle.d.ts +5 -0
- package/dist/admin/editor/topbar/ContentModeToggle.js +26 -0
- package/dist/admin/editor/topbar/DocumentActions.d.ts +1 -1
- package/dist/admin/editor/topbar/DocumentActions.js +5 -4
- package/dist/admin/editor/topbar/DocumentTitle.js +7 -2
- package/dist/admin/editor/topbar/TopBar.js +15 -3
- package/dist/admin/editor/topbar/contentMode.scss +35 -0
- package/dist/admin/editor/topbar/topbar.scss +3 -1
- package/dist/admin/formChoice.d.ts +3 -0
- package/dist/admin/formChoice.js +10 -0
- package/dist/admin/layoutField.scss +69 -0
- package/dist/admin/screen/BuilderScreen.d.ts +6 -1
- package/dist/admin/screen/BuilderScreen.js +4 -3
- package/dist/admin/server/BuilderView.js +10 -3
- package/dist/admin/templateConditions.scss +24 -0
- package/dist/ai/adapters/anthropic.js +17 -4
- package/dist/ai/adapters/cloudflare-gateway.js +7 -1
- package/dist/ai/adapters/cloudflare-workers-ai.js +2 -0
- package/dist/ai/adapters/openai-compatible.js +1 -0
- package/dist/ai/adapters/openrouter.js +2 -0
- package/dist/ai/config.d.ts +24 -4
- package/dist/ai/config.js +27 -8
- package/dist/ai/endpoint.d.ts +5 -2
- package/dist/ai/endpoint.js +31 -26
- package/dist/ai/images/cloudflare-workers-ai.js +6 -2
- package/dist/ai/images/openai.js +8 -3
- package/dist/ai/images/openrouter.js +6 -2
- package/dist/ai/images/service.d.ts +10 -4
- package/dist/ai/images/service.js +23 -7
- package/dist/ai/openai-format.d.ts +7 -0
- package/dist/ai/openai-format.js +17 -5
- package/dist/ai/prompt.d.ts +8 -0
- package/dist/ai/prompt.js +25 -5
- package/dist/ai/settings/index.d.ts +62 -0
- package/dist/ai/settings/index.js +264 -0
- package/dist/ai/settings/secret.d.ts +11 -0
- package/dist/ai/settings/secret.js +46 -0
- package/dist/ai/settings/shared.d.ts +22 -0
- package/dist/ai/settings/shared.js +3 -0
- package/dist/ai/tools.d.ts +3 -0
- package/dist/ai/tools.js +79 -15
- package/dist/ai/types.d.ts +43 -0
- package/dist/blocks/builtins/adjacentLinks.d.ts +5 -0
- package/dist/blocks/builtins/adjacentLinks.js +76 -0
- package/dist/blocks/builtins/carousel.d.ts +2 -29
- package/dist/blocks/builtins/carousel.js +44 -51
- package/dist/blocks/builtins/disclosure.d.ts +2 -1
- package/dist/blocks/builtins/disclosure.js +22 -32
- package/dist/blocks/builtins/embed.d.ts +15 -0
- package/dist/blocks/builtins/embed.js +47 -0
- package/dist/blocks/builtins/faq.d.ts +1 -1
- package/dist/blocks/builtins/faq.js +2 -2
- package/dist/blocks/builtins/filterLink.d.ts +1 -19
- package/dist/blocks/builtins/filterLink.js +9 -50
- package/dist/blocks/builtins/icon.d.ts +2 -0
- package/dist/blocks/builtins/icon.js +8 -8
- package/dist/blocks/builtins/index.d.ts +18 -13
- package/dist/blocks/builtins/index.js +43 -22
- package/dist/blocks/builtins/marquee.d.ts +5 -0
- package/dist/blocks/builtins/marquee.js +68 -0
- package/dist/blocks/builtins/popup.d.ts +5 -0
- package/dist/blocks/builtins/popup.js +83 -0
- package/dist/blocks/builtins/sectionRef.d.ts +16 -2
- package/dist/blocks/builtins/sectionRef.js +34 -12
- package/dist/blocks/builtins/shared.d.ts +18 -23
- package/dist/blocks/builtins/shared.js +34 -42
- package/dist/blocks/builtins/tableOfContents.d.ts +4 -0
- package/dist/blocks/builtins/tableOfContents.js +12 -18
- package/dist/blocks/builtins/tabs.d.ts +6 -0
- package/dist/blocks/builtins/tabs.js +87 -0
- package/dist/blocks/client/adjacentLinks.d.ts +4 -0
- package/dist/blocks/client/adjacentLinks.js +4 -0
- package/dist/blocks/client/carousel.d.ts +45 -0
- package/dist/blocks/client/carousel.js +53 -0
- package/dist/blocks/client/embed.d.ts +21 -0
- package/dist/blocks/client/embed.js +23 -0
- package/dist/blocks/client/field.d.ts +7 -0
- package/dist/blocks/client/field.js +8 -0
- package/dist/blocks/client/filterLink.d.ts +19 -0
- package/dist/blocks/client/filterLink.js +30 -0
- package/dist/blocks/client/helpers.d.ts +21 -0
- package/dist/blocks/client/helpers.js +24 -0
- package/dist/blocks/client/marquee.d.ts +14 -0
- package/dist/blocks/client/marquee.js +25 -0
- package/dist/blocks/client/menu.d.ts +46 -0
- package/dist/blocks/client/menu.js +49 -0
- package/dist/blocks/client/popup.d.ts +15 -0
- package/dist/blocks/client/popup.js +16 -0
- package/dist/blocks/client/tabs.d.ts +10 -0
- package/dist/blocks/client/tabs.js +11 -0
- package/dist/blocks/defaults.d.ts +15 -52
- package/dist/blocks/defaults.js +203 -437
- package/dist/blocks/index.d.ts +1 -2
- package/dist/blocks/index.js +1 -2
- package/dist/classes/actions.d.ts +97 -0
- package/dist/classes/actions.js +296 -0
- package/dist/classes/collection.d.ts +5 -0
- package/dist/classes/collection.js +189 -0
- package/dist/classes/config.d.ts +34 -0
- package/dist/classes/config.js +8 -0
- package/dist/classes/endpoints.d.ts +2 -0
- package/dist/classes/endpoints.js +120 -0
- package/dist/classes/index.d.ts +36 -0
- package/dist/classes/index.js +42 -0
- package/dist/classes/mcp.d.ts +6 -0
- package/dist/classes/mcp.js +161 -0
- package/dist/classes/shared.d.ts +131 -0
- package/dist/classes/shared.js +300 -0
- package/dist/classes/sheet.d.ts +34 -0
- package/dist/classes/sheet.js +126 -0
- package/dist/classes/usage.d.ts +57 -0
- package/dist/classes/usage.js +208 -0
- package/dist/comments/collection.d.ts +38 -0
- package/dist/comments/collection.js +226 -0
- package/dist/comments/config.d.ts +15 -0
- package/dist/comments/config.js +2 -0
- package/dist/comments/index.d.ts +20 -0
- package/dist/comments/index.js +22 -0
- package/dist/comments/shared.d.ts +54 -0
- package/dist/comments/shared.js +104 -0
- package/dist/core/bindings.d.ts +77 -32
- package/dist/core/bindings.js +319 -134
- package/dist/core/blockNames.d.ts +9 -0
- package/dist/core/blockNames.js +11 -0
- package/dist/core/blocks.d.ts +21 -8
- package/dist/core/blocks.js +37 -16
- package/dist/core/classes.d.ts +16 -8
- package/dist/core/classes.js +31 -27
- package/dist/core/components.d.ts +72 -0
- package/dist/core/components.js +294 -0
- package/dist/core/contentMode.d.ts +27 -0
- package/dist/core/contentMode.js +0 -0
- package/dist/core/dropTarget.d.ts +11 -0
- package/dist/core/dropTarget.js +24 -1
- package/dist/core/fields.d.ts +5 -0
- package/dist/core/fields.js +11 -0
- package/dist/core/headings.d.ts +5 -2
- package/dist/core/headings.js +14 -6
- package/dist/core/index.d.ts +8 -3
- package/dist/core/index.js +8 -3
- package/dist/core/layers.d.ts +9 -0
- package/dist/core/layers.js +29 -0
- package/dist/core/operations.d.ts +6 -0
- package/dist/core/operations.js +85 -24
- package/dist/core/payloadBlocks.js +5 -1
- package/dist/core/references.js +28 -0
- package/dist/core/schema.js +20 -6
- package/dist/core/sectionOrigin.d.ts +6 -0
- package/dist/core/sectionOrigin.js +21 -0
- package/dist/core/sections.d.ts +72 -0
- package/dist/core/sections.js +331 -0
- package/dist/core/templateChoice.d.ts +24 -0
- package/dist/core/templateChoice.js +43 -0
- package/dist/core/tree.js +18 -6
- package/dist/core/types.d.ts +148 -18
- package/dist/core/validate.d.ts +4 -1
- package/dist/core/validate.js +28 -11
- package/dist/core/visibility.d.ts +63 -0
- package/dist/core/visibility.js +214 -0
- package/dist/core/whereValues.d.ts +22 -0
- package/dist/core/whereValues.js +43 -0
- package/dist/css/classes.d.ts +16 -0
- package/dist/css/classes.js +172 -0
- package/dist/css/index.d.ts +32 -1
- package/dist/css/index.js +64 -5
- package/dist/css/tokens.d.ts +10 -0
- package/dist/css/tokens.js +23 -10
- package/dist/index.d.ts +5 -2
- package/dist/index.js +6 -1
- package/dist/live/contentMode.d.ts +24 -0
- package/dist/live/contentMode.js +39 -0
- package/dist/live/endpoints.js +3 -0
- package/dist/live/session.d.ts +5 -0
- package/dist/live/session.js +8 -0
- package/dist/live/types.d.ts +16 -1
- package/dist/mcp/index.d.ts +10 -1
- package/dist/mcp/index.js +146 -54
- package/dist/mcp/shared.d.ts +93 -3
- package/dist/mcp/shared.js +211 -15
- package/dist/plugin/hook.d.ts +7 -1
- package/dist/plugin/hook.js +30 -4
- package/dist/plugin/index.d.ts +19 -8
- package/dist/plugin/index.js +89 -20
- package/dist/plugin/links.d.ts +24 -0
- package/dist/plugin/links.js +27 -0
- package/dist/plugin/listCollections.d.ts +9 -7
- package/dist/plugin/listCollections.js +30 -21
- package/dist/plugin/sections.d.ts +14 -7
- package/dist/plugin/sections.js +69 -23
- package/dist/plugin/sectionsUsedIn.d.ts +6 -0
- package/dist/plugin/sectionsUsedIn.js +24 -0
- package/dist/plugin/templateEndpoint.d.ts +9 -0
- package/dist/plugin/templateEndpoint.js +49 -0
- package/dist/plugin/templates.js +23 -8
- package/dist/protocol/index.d.ts +16 -1
- package/dist/react/canvas/BuilderCanvas.js +144 -21
- package/dist/react/canvas/classes.d.ts +17 -0
- package/dist/react/canvas/classes.js +102 -0
- package/dist/react/canvas/controls.d.ts +31 -0
- package/dist/react/canvas/controls.js +75 -0
- package/dist/react/canvas/fetchDocs.d.ts +2 -2
- package/dist/react/canvas/fetchDocs.js +16 -8
- package/dist/react/canvas/measure.d.ts +9 -0
- package/dist/react/canvas/measure.js +106 -7
- package/dist/react/canvas/resolveLayout.d.ts +1 -1
- package/dist/react/canvas/resolveLayout.js +4 -3
- package/dist/react/canvas/thumbnail/ThumbnailCanvas.js +17 -4
- package/dist/react/classes/ClassesStyle.d.ts +27 -0
- package/dist/react/classes/ClassesStyle.js +27 -0
- package/dist/react/components/Button.d.ts +2 -11
- package/dist/react/components/Button.js +8 -43
- package/dist/react/components/CollectionList.d.ts +4 -1
- package/dist/react/components/CollectionList.js +10 -3
- package/dist/react/components/Container.d.ts +5 -2
- package/dist/react/components/Container.js +7 -4
- package/dist/react/components/Field.js +3 -14
- package/dist/react/components/Link.d.ts +1 -1
- package/dist/react/components/Link.js +5 -3
- package/dist/react/components/List.d.ts +1 -1
- package/dist/react/components/List.js +2 -2
- package/dist/react/components/Menu.d.ts +10 -1
- package/dist/react/components/Menu.js +39 -12
- package/dist/react/components/RichText.d.ts +3 -4
- package/dist/react/components/RichText.js +5 -5
- package/dist/react/components/builtins/Accordion.d.ts +4 -3
- package/dist/react/components/builtins/Accordion.js +6 -5
- package/dist/react/components/builtins/AdjacentLinks.d.ts +11 -0
- package/dist/react/components/builtins/AdjacentLinks.js +20 -0
- package/dist/react/components/builtins/Carousel.d.ts +21 -10
- package/dist/react/components/builtins/Carousel.js +175 -100
- package/dist/react/components/builtins/Disclosure.d.ts +4 -3
- package/dist/react/components/builtins/Disclosure.js +6 -5
- package/dist/react/components/builtins/Embed.d.ts +11 -0
- package/dist/react/components/builtins/Embed.js +23 -0
- package/dist/react/components/builtins/EmbedHtml.d.ts +15 -0
- package/dist/react/components/builtins/EmbedHtml.js +51 -0
- package/dist/react/components/builtins/EmbedPreview.d.ts +34 -0
- package/dist/react/components/builtins/EmbedPreview.js +105 -0
- package/dist/react/components/builtins/FilterLink.d.ts +1 -1
- package/dist/react/components/builtins/FilterLink.js +4 -4
- package/dist/react/components/builtins/Marquee.d.ts +8 -0
- package/dist/react/components/builtins/Marquee.js +15 -0
- package/dist/react/components/builtins/Popup.d.ts +26 -0
- package/dist/react/components/builtins/Popup.js +146 -0
- package/dist/react/components/builtins/SectionRef.d.ts +4 -3
- package/dist/react/components/builtins/SectionRef.js +9 -5
- package/dist/react/components/builtins/Tab.d.ts +7 -0
- package/dist/react/components/builtins/Tab.js +21 -0
- package/dist/react/components/builtins/TableOfContents.d.ts +17 -3
- package/dist/react/components/builtins/TableOfContents.js +22 -7
- package/dist/react/components/builtins/Tabs.d.ts +17 -0
- package/dist/react/components/builtins/Tabs.js +71 -0
- package/dist/react/components/builtins/index.d.ts +37 -20
- package/dist/react/components/builtins/index.js +54 -20
- package/dist/react/components/builtins/tabsContext.d.ts +12 -0
- package/dist/react/components/builtins/tabsContext.js +6 -0
- package/dist/react/components/index.js +11 -8
- package/dist/react/components/lazy.d.ts +32 -0
- package/dist/react/components/lazy.js +20 -0
- package/dist/react/components/lazyBlock.d.ts +17 -0
- package/dist/react/components/lazyBlock.js +23 -0
- package/dist/react/index.d.ts +6 -3
- package/dist/react/index.js +5 -2
- package/dist/react/render/RenderLayout.d.ts +9 -7
- package/dist/react/render/RenderLayout.js +96 -45
- package/dist/react/render/canvasMode.d.ts +13 -0
- package/dist/react/render/canvasMode.js +13 -0
- package/dist/react/render/canvasServer.js +4 -3
- package/dist/react/render/canvasServerTypes.d.ts +5 -0
- package/dist/react/render/lists.d.ts +36 -4
- package/dist/react/render/lists.js +132 -15
- package/dist/react/render/marks.d.ts +15 -0
- package/dist/react/render/marks.js +23 -0
- package/dist/react/render/payload.d.ts +8 -1
- package/dist/react/render/payload.js +12 -3
- package/dist/react/render/preview.d.ts +11 -0
- package/dist/react/render/preview.js +13 -0
- package/dist/react/render/relations.d.ts +10 -0
- package/dist/react/render/relations.js +39 -0
- package/dist/react/render/resolve.d.ts +8 -4
- package/dist/react/render/resolve.js +11 -5
- package/dist/react/render/reveal.d.ts +17 -0
- package/dist/react/render/reveal.js +39 -0
- package/dist/react/render/sections.d.ts +11 -5
- package/dist/react/render/sections.js +52 -24
- package/dist/react/render/templates.d.ts +47 -0
- package/dist/react/render/templates.js +139 -0
- package/dist/react/render/types.d.ts +62 -5
- package/dist/react/server.d.ts +2 -37
- package/dist/react/server.js +8 -133
- package/dist/react/theme/ThemeLiveLoader.d.ts +4 -0
- package/dist/react/theme/ThemeLiveLoader.js +5 -0
- package/dist/react/theme/ThemeStyle.js +1 -1
- package/dist/theme/admin/Variables.d.ts +11 -0
- package/dist/theme/admin/Variables.js +115 -0
- package/dist/theme/admin/fields.scss +113 -0
- package/dist/theme/client.d.ts +1 -0
- package/dist/theme/client.js +2 -0
- package/dist/theme/css.d.ts +6 -1
- package/dist/theme/css.js +12 -4
- package/dist/theme/global.js +83 -0
- package/dist/theme/index.d.ts +1 -0
- package/dist/theme/index.js +1 -0
- package/dist/theme/server.d.ts +15 -0
- package/dist/theme/server.js +43 -0
- package/dist/theme/usage.d.ts +23 -0
- package/dist/theme/usage.js +68 -0
- package/dist/theme/variables.d.ts +72 -0
- package/dist/theme/variables.js +231 -0
- package/package.json +4 -2
- package/dist/admin/editor/styles/SiteClasses.d.ts +0 -9
- package/dist/admin/editor/styles/SiteClasses.js +0 -31
- package/dist/blocks/builtins/headingId.d.ts +0 -15
- package/dist/blocks/builtins/headingId.js +0 -36
- package/dist/blocks/builtins/lightbox.d.ts +0 -43
- package/dist/blocks/builtins/lightbox.js +0 -93
- package/dist/blocks/builtins/mediaBackdrop.d.ts +0 -11
- package/dist/blocks/builtins/mediaBackdrop.js +0 -79
- package/dist/react/components/Quote.d.ts +0 -3
- package/dist/react/components/Quote.js +0 -12
- package/dist/react/components/Spacer.d.ts +0 -3
- package/dist/react/components/Spacer.js +0 -6
- package/dist/react/components/builtins/BackdropVideo.d.ts +0 -13
- package/dist/react/components/builtins/BackdropVideo.js +0 -16
- package/dist/react/components/builtins/Lightbox.d.ts +0 -45
- package/dist/react/components/builtins/Lightbox.js +0 -252
- package/dist/react/components/builtins/MediaBackdrop.d.ts +0 -14
- package/dist/react/components/builtins/MediaBackdrop.js +0 -61
package/README.md
CHANGED
|
@@ -33,11 +33,14 @@ One package holds everything: the Payload plugin and admin editor (`payload-canv
|
|
|
33
33
|
npx create-payload-canvas my-website
|
|
34
34
|
```
|
|
35
35
|
|
|
36
|
+
The starter also has a calmer Payload admin: a sidebar in groups with icons, a neutral look in light and dark mode, and a dashboard with quick actions, recent edits, drafts, form messages, site checks, scheduled publishes and optional Plausible or Umami numbers. Each part is plain code in `src/admin/` of the starter. The CLI asks which parts to keep (see [Features](../create-payload-canvas/README.md#features)).
|
|
37
|
+
|
|
36
38
|
## Contents
|
|
37
39
|
|
|
38
40
|
1. [Requirements](#requirements)
|
|
39
41
|
2. [Install](#install)
|
|
40
42
|
3. [The builder view](#the-builder-view)
|
|
43
|
+
- [Content mode for clients](#content-mode-for-clients)
|
|
41
44
|
4. [Inline editing](#inline-editing)
|
|
42
45
|
5. [Plugin options](#plugin-options)
|
|
43
46
|
6. [Rendering the layout on your site](#rendering-the-layout-on-your-site)
|
|
@@ -46,11 +49,13 @@ npx create-payload-canvas my-website
|
|
|
46
49
|
7. [Server components in the canvas](#server-components-in-the-canvas)
|
|
47
50
|
- [Whole-page editing: regions outside the layout](#whole-page-editing-regions-outside-the-layout)
|
|
48
51
|
8. [Custom blocks](#custom-blocks)
|
|
52
|
+
- [Interactive blocks on the canvas](#interactive-blocks-on-the-canvas)
|
|
49
53
|
- [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields)
|
|
50
54
|
- [Built-in blocks](#built-in-blocks)
|
|
51
55
|
9. [Using existing Payload blocks](#using-existing-payload-blocks)
|
|
52
56
|
10. [Sections](#sections)
|
|
53
57
|
11. [Styling](#styling)
|
|
58
|
+
- [Editable classes](#editable-classes)
|
|
54
59
|
12. [Animations](#animations)
|
|
55
60
|
13. [Theme](#theme)
|
|
56
61
|
14. [Templates and binding](#templates-and-binding)
|
|
@@ -59,6 +64,7 @@ npx create-payload-canvas my-website
|
|
|
59
64
|
17. [AI assistant](#ai-assistant)
|
|
60
65
|
18. [AI editing over MCP](#ai-editing-over-mcp)
|
|
61
66
|
19. [Multiplayer editing](#multiplayer-editing)
|
|
67
|
+
- [Comments on the canvas](#comments-on-the-canvas)
|
|
62
68
|
20. [Production and Docker](#production-and-docker)
|
|
63
69
|
21. [Deploying](#deploying)
|
|
64
70
|
22. [Troubleshooting](#troubleshooting)
|
|
@@ -427,18 +433,21 @@ The builder is a full-screen admin view at `/admin/builder/<collection>/<id>`. I
|
|
|
427
433
|
How editors open it:
|
|
428
434
|
|
|
429
435
|
- the document's **Builder** tab (a link to the view),
|
|
430
|
-
- the **Open builder** button on the layout field in the normal Edit view (a new document must be saved first),
|
|
431
|
-
- the old tab URL `/admin/collections/<collection>/<id>/builder`, which redirects to the view
|
|
436
|
+
- the **Open builder** button on the layout field in the normal Edit view (a new document must be saved first). The field also shows "3 sections · 24 blocks" and the list of sections,
|
|
437
|
+
- the old tab URL `/admin/collections/<collection>/<id>/builder`, which redirects to the view,
|
|
438
|
+
- with `editor.openInBuilder: true`, a click on a saved document in the collection list.
|
|
439
|
+
|
|
440
|
+
**Open documents in the builder.** `websiteBuilder({ editor: { openInBuilder: true } })` (default `false`) makes the builder the document's main view. Opening a saved document goes straight to `/admin/builder/<collection>/<id>`. Payload's form stays for new documents until their first save, in drawers, for users who cannot save, for documents in the trash, and with `?form=1` in the URL. The builder's **All fields** menu item opens the form with `?form=1`. The form then stays for that document until a full page load, or until you open the builder for it again. The builder's back arrow goes to the collection list. A collection that sets its own `admin.components.views.edit.default` keeps it. The option registers `payload-canvas/client#DocumentEditView`, so run `pnpm payload generate:importmap` after you turn it on.
|
|
432
441
|
|
|
433
442
|
The top bar, left to right:
|
|
434
443
|
|
|
435
|
-
- **Back** to the document's Edit view, the admin icon (to the dashboard), and `Collection › Title`. Click the title to rename the document: Enter or leaving the field saves it (as a draft when the collection has drafts). Escape cancels.
|
|
444
|
+
- **Back** to the document's Edit view (to the collection list with `openInBuilder`), the admin icon (to the dashboard), and `Collection › Title`. Click the title to rename the document: Enter or leaving the field saves it (as a draft when the collection has drafts). Escape cancels.
|
|
436
445
|
- The status: **Draft** (never published), **Published**, or **Changed** (published, with newer draft changes). Hover it for the last change, the creation date, the last publish and the number of versions (opens the Versions drawer).
|
|
437
446
|
- Undo and redo, the canvas width and the active breakpoint. **Fluid** (the default) fills the space between the sidebars, so the breakpoint follows the free width. Desktop (1280 px), tablet, mobile and a custom width are fixed widths. In a template: the sample document the canvas previews.
|
|
438
447
|
- The people on the page, and the save state: **Saving…** while changes are on their way, then **Saved · 12:04**.
|
|
439
448
|
- **Preview** opens the draft preview (the collection's `admin.livePreview.url`, else `admin.preview`), or the public page (the plugin's `url` option), in a new tab.
|
|
440
449
|
- **Page settings** opens the document's own edit form in a Payload drawer: title, slug, SEO, and for a template its collection and sample document. The top bar updates after each save.
|
|
441
|
-
- The AI assistant (with the `ai` option), the keyboard shortcuts, and **Publish changes**. Its menu has **Unpublish**, **Revert to published** (drops all draft changes, after a confirmation), **Versions** and **API** (Payload's own screens, in a drawer over the builder),
|
|
450
|
+
- The AI assistant (with the `ai` option), the keyboard shortcuts, and **Publish changes**. Its menu has **Unpublish**, **Revert to published** (drops all draft changes, after a confirmation), **Versions** and **API** (Payload's own screens, in a drawer over the builder), **All fields** (Payload's edit form) and a link to the live page. In the Versions drawer, open a version to compare it, then **Restore as draft**: every open editor gets the restored layout, and the site keeps the published version until you publish.
|
|
442
451
|
|
|
443
452
|
The left sidebar has three tabs: **Layers** (the block tree), **Blocks** and **Sections**. Each fills the sidebar. Alt+1, Alt+2 and Alt+3 (⌥1, ⌥2, ⌥3 on a Mac) open them, and the browser keeps the last tab. To drop a block or section into the tree, drag it onto the **Layers** tab and hold it there for a moment: the tab opens.
|
|
444
453
|
|
|
@@ -450,7 +459,9 @@ Publishing. All editors of a document share one live session (see [Multiplayer e
|
|
|
450
459
|
|
|
451
460
|
Save rules. Every save checks the layout. A broken layout (wrong shape, duplicate ids, unknown block types, wrong prop types) blocks every save. Unfinished blocks do not block drafts, autosave or live sessions: a missing required prop, a prop whose value does not match its `builderFormat` (for example a half-typed video URL), a value outside the field's limits (`minLength`, `maxLength`, `min`, `max`, `minRows`, `maxRows`, an email address without a valid form), a message from the field's own `validate` function, a block in a slot that refuses it, and a binding the prop cannot use. All of these can be true while someone is still typing. They block **Publish** only, and the problem list names the block ("Video: this YouTube link does not point to a video", "Product: SKU: use a SKU like ABC-123"). Click a problem to select the block. See [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields).
|
|
452
461
|
|
|
453
|
-
Adding blocks on the canvas. Hover the canvas: a small **+** shows on the edge between two blocks next to the pointer (above or below in a column, left or right in a row), and in the middle of an empty container. Click it to open a picker with the blocks and sections that fit there (slot rules apply). Type to search, use the arrow keys and Enter, or click. The new block goes in exactly that place and is selected. The **+** hides while you drag and while you edit text on the canvas.
|
|
462
|
+
Adding blocks on the canvas. Hover the canvas: a small **+** shows on the edge between two blocks next to the pointer (above or below in a column, left or right in a row), and in the middle of an empty container. Click it to open a picker with the blocks and sections that fit there (slot rules apply). Type to search, use the arrow keys and Enter, or click. The new block goes in exactly that place and is selected. The **+** hides while you drag and while you edit text on the canvas. It does not show next to a small block (under 48 px along the list and under 160 px across, at 100 % zoom), and it never covers more than a fifth of a block: the parent gets the **+** instead. It also hides over the controls of interactive blocks (a carousel's arrows, a tab).
|
|
463
|
+
|
|
464
|
+
Interactive blocks on the canvas. Select a block inside a closed accordion item, a hidden tab, another slide or a closed popup, on the canvas or in Layers: the canvas opens the item, the tab or the popup, or moves to the slide, and scrolls the block into view. Arrows, dots, tab buttons and popup triggers work as on the site: a click on them selects nothing. Outlines of blocks inside a container that hides its overflow (a carousel's viewport) are cut at the container's edge.
|
|
454
465
|
|
|
455
466
|
Drag and drop. Drag a block by its row in the outline, by the grip on the selected block's bar, or from the **Blocks** and **Sections** tabs. Slot rules apply: a slot that refuses the block is never a target. Escape cancels the drag. One drop is one undo step, and collaborators see the move at once. There are two styles:
|
|
456
467
|
|
|
@@ -459,8 +470,46 @@ Drag and drop. Drag a block by its row in the outline, by the grip on the select
|
|
|
459
470
|
|
|
460
471
|
Set the default with `websiteBuilder({ editor: { dragMode: 'smooth' } })`. Each user can change it with the grip button in the canvas status bar, next to the zoom. The choice stays in that browser. When the system asks for less motion (`prefers-reduced-motion: reduce`), the editor always uses the drop line. Both styles use the same drop rules, so the same drop gives the same result. Smooth mode moves blocks with CSS transforms only and never changes the layout before the drop.
|
|
461
472
|
|
|
473
|
+
Drop outlines. While you drag, a thin dashed line marks every container on the canvas that takes the block, by the same slot rules. The container the block would drop into gets a stronger line, and its name when a drop line shows. The lines are drawn over the canvas, so the page never moves. Turn them off in the same grip menu (**Outline where blocks can drop**), or set the default with `websiteBuilder({ editor: { dropOutlines: false } })`.
|
|
474
|
+
|
|
462
475
|
Access. The view sends signed-out visitors to the login page and back. Users without admin access go to Payload's "unauthorized" page. A document that does not exist, or a collection without the builder, shows "not found". A user who can read but not update the document gets the normal Edit view.
|
|
463
476
|
|
|
477
|
+
### Content mode for clients
|
|
478
|
+
|
|
479
|
+
Content mode lets a site owner's client change text, images and links without breaking the design. Webflow's Editor and Elementor's role manager work the same way.
|
|
480
|
+
|
|
481
|
+
```ts
|
|
482
|
+
websiteBuilder({
|
|
483
|
+
editor: {
|
|
484
|
+
// Users with the "editor" role get content mode. Everyone else keeps full rights.
|
|
485
|
+
canEditDesign: ({ user }) => user?.role !== 'editor',
|
|
486
|
+
},
|
|
487
|
+
})
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
The default is `true` for everyone, so nothing changes until you set it. A function that throws counts as `false`. The starter adds a **Role** field (Admin or Editor) to its users and uses it here.
|
|
491
|
+
|
|
492
|
+
In content mode, editors can:
|
|
493
|
+
|
|
494
|
+
- change text, textarea, rich text, upload (image and video), email and link props in the inspector,
|
|
495
|
+
- edit text on the canvas,
|
|
496
|
+
- in a block marked **Editors can add, remove and reorder its items**: duplicate, delete and reorder its direct children (FAQ items, team cards). They cannot restyle them.
|
|
497
|
+
|
|
498
|
+
They cannot add, move, duplicate or delete other blocks, and they see no Blocks or Sections tab, no **+** buttons, no drag and drop, no Styles, Motion or Advanced tab, no classes, section variants, visibility conditions, bindings or page regions. Design props (selects, checkboxes, numbers, relationships, heading levels) are hidden too. The top bar shows **Content mode**.
|
|
499
|
+
|
|
500
|
+
Users with design rights get **Preview as client** in the top bar. It shows the editor as clients see it. Turn it off to edit the design again.
|
|
501
|
+
|
|
502
|
+
Which props are content. The field type decides: `text`, `textarea`, `richText`, `upload`, `email` and link groups (`linkField()`) are content. A group, row or array is content when every field inside it is. Everything else is design. Override it per field with `admin.custom.builderContent`:
|
|
503
|
+
|
|
504
|
+
```ts
|
|
505
|
+
{ name: 'anchor', type: 'text', admin: { custom: { builderContent: false } } }, // a setting, not text
|
|
506
|
+
{ name: 'badge', type: 'select', options: ['New', 'Sale'], admin: { custom: { builderContent: true } } },
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
Mark a list. Select the block that holds the items, open the **Advanced** tab and turn on **Editors can add, remove and reorder its items**. It is stored as `editableItems: true` on the block. A new item must be a copy of an item already there.
|
|
510
|
+
|
|
511
|
+
The server enforces it. Every write checks the change against the layout before it: the live editor's commits, the operations endpoint, the MCP tools, the AI assistant, editable class renames, and saves through REST, GraphQL or the Edit view. A design change from a user in content mode is refused with a 403 and a message such as `In content mode you can change only text, images and links. "Hero" cannot be moved.` The editable classes collection and the theme global are design too: content mode cannot create, update or delete them. Payload's **Restore** of a version is checked the same way: a version with another design is refused with `This version has a different design, so only a designer can restore it.`, and a version that differs only in content restores. (Payload's Restore button shows its own generic error; the API response carries the message.) Publishing, unpublishing and **Revert to published** stay allowed: they never bring back a design that is not already published.
|
|
512
|
+
|
|
464
513
|
## Inline editing
|
|
465
514
|
|
|
466
515
|
Text and images edit in place on the canvas, in every block: the default blocks, your own components, and existing Payload components adopted with `fromPayloadComponents`. You do not need to change your components.
|
|
@@ -549,7 +598,7 @@ websiteBuilder({
|
|
|
549
598
|
live: { heartbeatMs: 15000 },
|
|
550
599
|
ai: { adapter: openRouterAdapter({ apiKey: process.env.OPENROUTER_API_KEY }) }, // the AI assistant
|
|
551
600
|
theme: { admin: { group: 'Settings' } }, // the Theme global; `false` leaves it out
|
|
552
|
-
editor: { dragMode: 'smooth' }, //
|
|
601
|
+
editor: { dragMode: 'smooth', openInBuilder: true }, // drag and drop style; open saved documents in the builder
|
|
553
602
|
references: { usedIn: ['media'], protectDelete: ['media'] }, // "Used in" lists; `false` turns them off
|
|
554
603
|
})
|
|
555
604
|
```
|
|
@@ -578,8 +627,12 @@ websiteBuilder({
|
|
|
578
627
|
| `ai` | `AiOptions` | Turns on the AI assistant in the editor. See [AI assistant](#ai-assistant). |
|
|
579
628
|
| `theme` | `ThemeOptions \| false` | The Theme global. On by default. `false` leaves it out. See [Theme](#theme). |
|
|
580
629
|
| `editor.dragMode` | `'indicator' \| 'smooth'` | The default drag and drop style. `indicator` (the default) shows a drop line; `smooth` lifts the block and moves the other blocks out of the way. Each user can change it in the editor. See [The builder view](#the-builder-view). |
|
|
630
|
+
| `editor.dropOutlines` | `boolean` | Thin outlines of every container that takes the dragged block, while you drag. Default `true`. Each user can change it in the editor. See [The builder view](#the-builder-view). |
|
|
631
|
+
| `editor.canEditDesign` | `({ req, user }) => boolean \| Promise<boolean>` | Who may change the design. Users for whom it returns `false` get content mode: text, images and links only. Default: everyone. See [Content mode for clients](#content-mode-for-clients). |
|
|
632
|
+
| `editor.openInBuilder` | `boolean` | Opening a saved document goes straight to the builder instead of Payload's form. Default `false`. Run `generate:importmap` after you turn it on. See [The builder view](#the-builder-view). |
|
|
581
633
|
| `css.fontFamilies` | `(payload) => Record<name, family>` | Font families set at runtime some other way than the Theme global, for the Styles panel's Font list. Its names win over the theme's. |
|
|
582
634
|
| `references` | `{ field?, usedIn?, protectDelete?, maxListed? } \| false` | Which media and documents each layout uses: "Used in" lists and delete protection. On by default. `false` turns it off. See [References and Used in](#references-and-used-in). |
|
|
635
|
+
| `comments` | `{ slug?, access?, admin?, hooks? } \| boolean` | Comments on blocks in the builder, stored in a `builder-comments` collection. On by default. `false` turns it off. See [Comments on the canvas](#comments-on-the-canvas). |
|
|
583
636
|
|
|
584
637
|
For each listed collection the plugin adds:
|
|
585
638
|
|
|
@@ -625,9 +678,9 @@ It also adds these endpoints (signed-in users only):
|
|
|
625
678
|
| `payload-canvas/ai/openrouter`, `/ai/cloudflare-gateway`, `/ai/cloudflare-workers-ai`, `/ai/openai-compatible`, `/ai/anthropic`, `/ai/fake` | `payload.config.ts` (server) | one AI adapter each. See [Adapters](#adapters). |
|
|
626
679
|
| `payload-canvas/ai/images/openrouter`, `/ai/images/openai`, `/ai/images/cloudflare-workers-ai`, `/ai/images/fake` | `payload.config.ts` (server) | one image adapter each. See [Image generation](#image-generation). |
|
|
627
680
|
| `payload-canvas/live` | server | the live sessions and endpoints |
|
|
628
|
-
| `payload-canvas/client` | Payload import map only | admin client components (layout field, Builder tab) |
|
|
681
|
+
| `payload-canvas/client` | Payload import map only | admin client components (layout field, Builder tab, `DocumentEditView` for `openInBuilder`) |
|
|
629
682
|
| `payload-canvas/rsc` | Payload import map only | admin server components (the builder view, the tab redirect) |
|
|
630
|
-
| `payload-canvas/react` | your site and the canvas (server and client) | `RenderLayout`, `defaultComponents`, `fromPayloadComponent(s)`, `withPageData`, `renderOnServer`, `editableText`, `editableImage`, link helpers, `ThemeLive`, types |
|
|
683
|
+
| `payload-canvas/react` | your site and the canvas (server and client) | `RenderLayout`, `defaultComponents`, `fromPayloadComponent(s)`, `withPageData`, `withLinkComponent`, `lazyBlock`, `renderOnServer`, `editableText`, `editableImage`, `useCanvasMode`, `useCanvasReveal`, `REVEAL_EVENT`, `CANVAS_CONTROL_ATTRIBUTE`, `builtinComponents`, link helpers, `ThemeLive`, types |
|
|
631
684
|
| `payload-canvas/react/server` | server only | `loadLayoutData`, `loadTemplate`, `loadTheme`, `ThemeStyle`, `createCanvasServer` (they call Payload's Local API) |
|
|
632
685
|
| `payload-canvas/react/canvas` | client only | `BuilderCanvas`, the runtime for the editor's iframe |
|
|
633
686
|
| `payload-canvas/protocol`, `/css-browser` | used by `payload-canvas/react` | the editor–canvas message types, the in-browser CSS compiler. You do not import them yourself. |
|
|
@@ -647,6 +700,26 @@ Every entry point is ESM with `.d.ts` types. Client components keep their `'use
|
|
|
647
700
|
| `resolveLink` | `(link) => string \| null` | Turns links into an `href`. Default: the URL, or `/<slug>` for a loaded document. |
|
|
648
701
|
| `context` | `{ collection, doc }` | The document a template renders. See [Templates](#templates-and-binding). |
|
|
649
702
|
| `pageData` | `Record<string, unknown>` | Data the page loads once for its blocks. See [Page data](#page-data-and--block-context--components). |
|
|
703
|
+
| `linkComponent` | client component | Renders the links of the button, link and menu blocks on the site. Default: a plain `<a>`. Pass `next/link` for client-side navigation and prefetching. It must be a client component (the menu is one and gets it as a prop). Your own components get it as `linkComponent` when you mark them with `withLinkComponent(Component)`. The canvas keeps plain links. |
|
|
704
|
+
| `priorityImages` | `number` | How many images of the first section load first (`fetchpriority="high"`, not lazy), in page order. Default `1`, usually the hero image. An image whose **Load first** is switched off keeps lazy loading. Give layouts further down the page (a footer) `0`. |
|
|
705
|
+
|
|
706
|
+
```tsx
|
|
707
|
+
import Link from 'next/link'
|
|
708
|
+
|
|
709
|
+
<RenderLayout layout={layout} blocks={blocks} components={components} linkComponent={Link} />
|
|
710
|
+
```
|
|
711
|
+
|
|
712
|
+
The interactive blocks (menu, carousel, popup, tabs, accordion, filter link) load their JavaScript only on pages that render them: their components load with `next/dynamic`. Do the same for a heavy client block of your own, in a `'use client'` module:
|
|
713
|
+
|
|
714
|
+
```tsx
|
|
715
|
+
'use client'
|
|
716
|
+
import dynamic from 'next/dynamic'
|
|
717
|
+
import { lazyBlock } from 'payload-canvas/react'
|
|
718
|
+
|
|
719
|
+
export const FormBlock = lazyBlock(dynamic(() => import('./Form').then((m) => m.FormBlock)))
|
|
720
|
+
```
|
|
721
|
+
|
|
722
|
+
`lazyBlock` gives the block its own Suspense boundary on the canvas, where it can mount after the page.
|
|
650
723
|
|
|
651
724
|
`loadLayoutData(layout, blocks, payload, options)` (from `payload-canvas/react/server`) loads the documents that upload and relationship props point to, in one `find` per collection. Options: `draft`, `context`, `resolveLink`.
|
|
652
725
|
|
|
@@ -675,13 +748,13 @@ type BlockComponentProps = {
|
|
|
675
748
|
className?: string
|
|
676
749
|
slots: Record<string, ReactNode> // rendered children per slot
|
|
677
750
|
attributes: Record<string, string> // spread on the root element
|
|
678
|
-
|
|
751
|
+
partAttributes: Record<string, Record<string, string>> // by slot or part name: spread on its element
|
|
679
752
|
mode: 'site' | 'canvas'
|
|
680
753
|
}
|
|
681
754
|
```
|
|
682
755
|
|
|
683
756
|
- Spread `attributes` on the root element. In the canvas it holds `data-block-id`, which the editor needs to select and measure the block.
|
|
684
|
-
- Spread `
|
|
757
|
+
- Spread `partAttributes[slot]` on the element that holds a slot's children. For a part (a slot with `styles: true`, or a name in `parts`) it also carries the part's `className` (see [Classes on inner elements](#classes-on-inner-elements)), so join it with any `className` you set on that element. Components written for 0.2 that read `slotAttributes` still work: it is the same object.
|
|
685
758
|
- Props are plain data. A component can be a client component (`'use client'`).
|
|
686
759
|
- Use one components map for the site and the canvas, in a file without server code:
|
|
687
760
|
|
|
@@ -729,7 +802,7 @@ With Next's Cache Components (`cacheComponents: true` in `next.config`), a route
|
|
|
729
802
|
|
|
730
803
|
## Server components in the canvas
|
|
731
804
|
|
|
732
|
-
Some block components load their own data: a model grid that calls `payload.find`, a review carousel, a blog listing, a FAQ from a collection. They are async server components, and they import Payload and your config. The canvas iframe is a client page, so it cannot import them. The canvas sends these blocks to a server action in the canvas route instead. The action renders them with your site's components and sends back the result as React Server Component output. Client components inside it (a carousel, a
|
|
805
|
+
Some block components load their own data: a model grid that calls `payload.find`, a review carousel, a blog listing, a FAQ from a collection. They are async server components, and they import Payload and your config. The canvas iframe is a client page, so it cannot import them. The canvas sends these blocks to a server action in the canvas route instead. The action renders them with your site's components and sends back the result as React Server Component output. Client components inside it (a carousel, a popup) work in the canvas as on the site. You do not change your components.
|
|
733
806
|
|
|
734
807
|
You keep two component maps:
|
|
735
808
|
|
|
@@ -951,6 +1024,7 @@ import { defaultBlocks, defineBlock, linkField } from 'payload-canvas/blocks'
|
|
|
951
1024
|
export const pricingTable = defineBlock({
|
|
952
1025
|
type: 'pricingTable',
|
|
953
1026
|
label: 'Pricing table',
|
|
1027
|
+
description: 'A price card with a button.', // the block library's tooltip, for editors
|
|
954
1028
|
icon: 'grid', // a name from the editor's icon set; unknown names get a generic icon
|
|
955
1029
|
category: 'Marketing', // group in the block library
|
|
956
1030
|
fields: [
|
|
@@ -970,31 +1044,104 @@ export const pricingTable = defineBlock({
|
|
|
970
1044
|
export const blocks = [...defaultBlocks({ linkCollections: ['pages'] }), pricingTable]
|
|
971
1045
|
```
|
|
972
1046
|
|
|
1047
|
+
- `description` is one short plain sentence for editors. The block library shows it as the tooltip. Without it, the tooltip shows only the label. The library search also reads `ai.description`. Keep code and syntax out of it: those go in `ai.description`.
|
|
973
1048
|
- `slots` declares where child blocks go. `allow` lists the accepted block types, or `['*']`. `max` caps the number of direct children: a full slot refuses insert, move, paste and duplicate (also from MCP and the assistant), and the canvas offers no drop target or "+" there. `min` is the fewest children: fewer block **Publish** but not draft saves.
|
|
974
|
-
- `inline: true` says the block renders no link, button or other control of its own (an icon, a badge, a rating). Such a block may go directly inside a `link` block, whose content slot sets `allowInline: true`. A slot of your own can set `allowInline: true` too. `websiteBuilder` and `builderMcpTools` add the inline types to those slots' `allow` lists (`withInlineBlocks`); a slot's `disallow` still wins. Blocks without `inline` stay out of links.
|
|
975
|
-
- `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
|
|
1049
|
+
- `inline: true` says the block renders no link, button or other control of its own (an icon, a badge, a rating). Such a block may go directly inside a `link` block, whose content slot sets `allowInline: true`. A slot of your own can set `allowInline: true` too. `websiteBuilder` and `builderMcpTools` add the inline types to those slots' `allow` lists (`withInlineBlocks`); a slot's `disallow` still wins. Blocks without `inline` stay out of links. `validateLayout` applies the same rule itself, so a seed or a test can check a layout against your own block list. To check a collection list's picked `ids` as a relationship, give that list `defaultBlocks({ listCollections })`, as the plugin does with the collections that have a `url`.
|
|
1050
|
+
- `parents` limits where a block may go: only directly inside the listed block types (never in the root list). The `listItem` block uses `parents: ['list']`. A new block whose slot accepts exactly one such type starts with children of it: the slot's `min`, or one. So a new list starts with one item, and new tabs start with two tabs.
|
|
976
1051
|
- `classes`: classes your component uses itself that your site's CSS does not have. Components in your app need no list: Tailwind finds their classes in your files, and the site's CSS has them on the site and on the canvas. List classes only for a component in a package that your CSS entry does not scan (no `@source` for it). The generated CSS styles only elements with the class `builder-css` (`BUILDER_CSS_CLASS` from `payload-canvas/blocks`), so add that class to each element that uses the listed classes. The built-in Menu block does this for its toggle, panel and links.
|
|
977
1052
|
- Block fields keep Payload's `validate`, `hooks` and `access`. See [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields).
|
|
978
|
-
- `
|
|
979
|
-
|
|
980
|
-
```ts
|
|
981
|
-
{ name: 'arrowClassName', type: 'text', defaultValue: 'size-10 rounded-full bg-white/80', admin: { custom: { builderClasses: true } } }
|
|
982
|
-
```
|
|
983
|
-
|
|
1053
|
+
- `parts` names inner elements that take classes of their own, for example a carousel's arrows. See [Classes on inner elements](#classes-on-inner-elements).
|
|
984
1054
|
- `admin.custom.builderFormat` on a `text` field names a value check, for example `custom: { builderFormat: 'videoUrl' }` (the Video block's URL). The inspector shows the message while the user types, and a bad value blocks **Publish** but not draft saves. `videoUrl` is the only built-in format. Formats live in a registry in `payload-canvas/core` (`FORMATS`, `formatProblem`). The renderer can use the same parser (`parseVideoUrl`).
|
|
985
1055
|
- `linkField()` stores `{ type, url, reference, newTab }`. The component receives it resolved, with `href`, `target` and `rel`.
|
|
986
|
-
- The default blocks are `stack`, `grid`, `heading`, `text`, `richText`, `image`, `video`, `button`, `link`, `menu`, `list` with its `listItem` blocks, `
|
|
1056
|
+
- The 15 default blocks are `stack`, `grid`, `heading`, `text`, `richText`, `image`, `video`, `button`, `link`, `menu`, `list` with its `listItem` blocks, `divider`, `collectionList` (documents from a collection), `field` (a field of the document a template renders) and `repeat` (the rows of an array or hasMany field of that document).
|
|
1057
|
+
- Field help in the inspector stays short. Put syntax and examples for agents in the field's `custom.ai.description`, and a hint inside an empty input in `admin.placeholder` (the inspector shows it).
|
|
987
1058
|
- Props worth knowing on the default blocks:
|
|
988
|
-
- `image`: `priority` (load first: `loading="eager"` and `fetchpriority="high"`, for the hero image) and `sizes` (the HTML `sizes` attribute, for example `(min-width: 768px) 50vw, 100vw`). The media's focal point (`focalX`, `focalY`) sets `object-position`, so a cropped image keeps its subject. Payload's default 50/50 counts as unset, so an `object-position` class (`object-top`) sets the crop of a photo whose focal point nobody moved. Limit: a focal point set to exactly 50/50 loses to such a class.
|
|
1059
|
+
- `image`: `priority` (load first: `loading="eager"` and `fetchpriority="high"`, for the hero image; the first image of the first section gets it unless switched off, see `priorityImages`) and `sizes` (the HTML `sizes` attribute, for example `(min-width: 768px) 50vw, 100vw`). The media's focal point (`focalX`, `focalY`) sets `object-position`, so a cropped image keeps its subject. Payload's default 50/50 counts as unset, so an `object-position` class (`object-top`) sets the crop of a photo whose focal point nobody moved. Limit: a focal point set to exactly 50/50 loses to such a class.
|
|
989
1060
|
- `heading`: `accent`, words of the text to highlight. They render as `<em>`. Style them with classes on the heading, for example `[&_em]:text-primary [&_em]:not-italic`.
|
|
990
|
-
- `stack`: `as` also takes `ol`, `ul`, `li`, `dl`, `dt`, `dd`, `figure
|
|
991
|
-
- The `menu` block folds its links into a "Menu" button and a panel on small screens. Set `ctaLabel` and `cta` (a link) to add a button as the last row of that panel, for example the header's call to action, which a header hides on phones. The inline links, and so the wide-screen header, do not change. `toggleLabel` is the text of the menu button (default "Menu").
|
|
1061
|
+
- `stack`: `as` (the inspector's **Tag**) also takes `ol`, `ul`, `li`, `dl`, `dt`, `dd`, `figure` and `figcaption`, for lists, term lists and captions. It takes no `p` or `span`: those cannot hold block children such as a heading.
|
|
1062
|
+
- The `menu` block folds its links into a "Menu" button and a panel on small screens. Set `ctaLabel` and `cta` (a link) to add a button as the last row of that panel, for example the header's call to action, which a header hides on phones. The inline links, and so the wide-screen header, do not change. `toggleLabel` is the text of the menu button (default "Menu"). The menu's labels (`label`, `toggleLabel`, `submenuLabel`) store nothing until someone types one: empty, they use the site's labels (`builtinComponents({ labels: { menu } })`, see [Labels](#labels)) or English. The panel and dropdown colours read the theme's CSS variables (`--color-background`, `--color-foreground`, `--color-border`, `--color-primary`) with the system colours as the fallback, so the menu needs no particular design system.
|
|
992
1063
|
- A `menu` item can have `children`: one level of links (`label`, `link`) in a dropdown. The item's own link is optional. With a link, the item shows the link and a small arrow toggle beside it, which screen readers hear as `submenuLabel` (default "{label} menu", localized). Without a link, the label is the toggle. The dropdown is a native `<details>`: Enter and Space open it, Escape closes it and returns the focus to the toggle, and it closes when the focus or a click leaves it. Opening one closes the others. A current child gets `aria-current="page"` and its parent `aria-current="true"`. In the small-screen panel the children show as a nested list. Its classes are in `MENU_CLASS_MAP` (`submenu`, `submenuToggle`, `submenuList`, `submenuLink`, `panelSubList`, `panelSubLink`); restyle them from the menu's `className`, for example `[&_li>details>ul]:rounded-lg`. Items without children render as before.
|
|
993
1064
|
- The `field` block renders rich text with the `prose` typography (and `max-w-none`) when its own `className` has no `prose` class. Add `prose prose-lg` or another `prose` class to take control.
|
|
994
|
-
- `field` `
|
|
995
|
-
- `field` and `richText`
|
|
1065
|
+
- `field` `path` takes a binding formatter after a `|` (see "Binding syntax"): `price|currency:EUR` gives `€1,200`, `publishedAt|date:en-GB` a date in that language, `content|readingTime` gives `5 min read`. The inspector edits it with the **Format** select under the field. `formatBindingValue(value, "currency:EUR")` in `payload-canvas/core` formats a value the same way.
|
|
1066
|
+
- `field` and `richText` give each rich-text heading an `id` from its text, for `#id` links and the [table of contents](#table-of-contents): `headingId('Über uns & Preise')` is `uber-uns-preise`. A repeated text gets `-2`, `-3`, and a heading without letters or digits gets `section`. `richTextHeadings(value)` in `payload-canvas/core` lists the headings with the same ids (`{ id, text, level, node }`). Two rich texts on one page with the same heading text give two elements the same id; the first one wins a `#id` link.
|
|
996
1067
|
- A list holds its items as `listItem` blocks in its `items` slot, so each item can be selected, dragged, styled and edited on the canvas. Enter at the end of an item adds the next one; Backspace at the start of an item joins it to the one before. Older layouts stored the items as a prop (`props.items: [{ text }]`). `normalizeLayout` turns them into `listItem` blocks when a layout loads, and the List component still renders the old prop until the layout is saved again. A list whose `items` prop is bound to document data keeps the old form. A `listItem` takes an optional `link` (the same link group as `button`): the item renders as `<li><a href>text</a></li>`, and the text stays editable in place. Do not set it on items of a list inside a `link` block, because a link cannot hold another link; the item's link is a prop, so the link block's type rules do not catch it.
|
|
997
1068
|
|
|
1069
|
+
### Where a block renders: `useCanvasMode()`
|
|
1070
|
+
|
|
1071
|
+
A block component can render differently in the editor. `useCanvasMode()` from `payload-canvas/react` tells a client component where it renders:
|
|
1072
|
+
|
|
1073
|
+
- `'site'`: the live website. This is the value on any page without the canvas.
|
|
1074
|
+
- `'canvas'`: the editor's canvas iframe.
|
|
1075
|
+
- `'thumbnail'`: the hidden canvas that takes the pictures of the section library.
|
|
1076
|
+
|
|
1077
|
+
Use it to keep heavy work out of the editor. This 3D block shows a still poster in a thumbnail, and pauses its animation loop on the canvas:
|
|
1078
|
+
|
|
1079
|
+
```tsx
|
|
1080
|
+
'use client'
|
|
1081
|
+
import { useEffect, useRef } from 'react'
|
|
1082
|
+
import { useCanvasMode, type BlockComponentProps } from 'payload-canvas/react'
|
|
1083
|
+
import { startScene } from '@/lib/scene' // your WebGL code: returns { pause(), resume(), dispose() }
|
|
1084
|
+
|
|
1085
|
+
export function ProductScene({ props, className, attributes }: BlockComponentProps) {
|
|
1086
|
+
const mode = useCanvasMode()
|
|
1087
|
+
const canvasRef = useRef<HTMLCanvasElement>(null)
|
|
1088
|
+
const poster = (props.poster as { url?: string } | undefined)?.url
|
|
1089
|
+
|
|
1090
|
+
useEffect(() => {
|
|
1091
|
+
if (mode === 'thumbnail' || !canvasRef.current) return
|
|
1092
|
+
const scene = startScene(canvasRef.current)
|
|
1093
|
+
// On the canvas the scene draws one frame and stops, so the editor stays fast.
|
|
1094
|
+
if (mode === 'canvas') scene.pause()
|
|
1095
|
+
return () => scene.dispose()
|
|
1096
|
+
}, [mode])
|
|
1097
|
+
|
|
1098
|
+
if (mode === 'thumbnail') return <img {...attributes} className={className} src={poster} alt="" />
|
|
1099
|
+
return <canvas {...attributes} ref={canvasRef} className={className} />
|
|
1100
|
+
}
|
|
1101
|
+
```
|
|
1102
|
+
|
|
1103
|
+
A server component cannot call hooks. When the canvas renders a block on the server (see [Server components in the canvas](#server-components-in-the-canvas)), the component gets the same value as its `canvasMode` prop: `'canvas'` or `'thumbnail'`. On the site the prop is missing. A component made with `fromPayloadComponent` gets it as `builder.canvasMode`, so a `{ block, context }` component can pass it on: `props: (block, context, builder) => ({ block, context: { ...context, mode: builder.canvasMode ?? 'site' } })`. Client components inside a server block call `useCanvasMode()` as usual.
|
|
1104
|
+
|
|
1105
|
+
### Interactive blocks on the canvas
|
|
1106
|
+
|
|
1107
|
+
A tab, a slide or a popup keeps some content out of view. On the canvas, an editor must still reach that content, and must still use the block's buttons. `payload-canvas/react` has three tools for this:
|
|
1108
|
+
|
|
1109
|
+
- `useCanvasReveal(ref, onReveal)`: calls `onReveal(target)` when the editor selects a block inside the element of `ref` (on the canvas or in Layers), or that element itself. Show the hidden part there: open the item, scroll to the slide, pick the tab. Only the canvas sends the event, so on the site it never fires.
|
|
1110
|
+
- `REVEAL_EVENT` (`'builder:reveal'`): the DOM event behind the hook. The canvas sends it from the selected block's element, and it bubbles. Listen for it yourself in code that is not a React component.
|
|
1111
|
+
- `CANVAS_CONTROL_ATTRIBUTE` (`'data-builder-control'`): put it on the block's controls (arrows, dots, tab buttons, a close button). On the canvas a click on such an element works as on the site and selects nothing. The hover outline and the "+" do not show over it.
|
|
1112
|
+
|
|
1113
|
+
What the canvas does when a block is selected: it opens every closed `<details>` around the block, sends the reveal event from the block's element, and after two animation frames scrolls the block into view. When the selection is cleared (Escape), it sends the reveal event from `<html>`, outside every block, so a box that closes when the editor selects something outside it closes then too. So a native `<details>` needs no code. A block that moves its content with CSS transforms (a slider) can send `element.dispatchEvent(new Event('scroll'))` after each move, so the canvas measures the block outlines again.
|
|
1114
|
+
|
|
1115
|
+
A "Read more" block that hides part of its content:
|
|
1116
|
+
|
|
1117
|
+
```tsx
|
|
1118
|
+
'use client'
|
|
1119
|
+
import { useRef, useState } from 'react'
|
|
1120
|
+
import { CANVAS_CONTROL_ATTRIBUTE, useCanvasReveal, type BlockComponentProps } from 'payload-canvas/react'
|
|
1121
|
+
|
|
1122
|
+
const CONTROL = { [CANVAS_CONTROL_ATTRIBUTE]: '' }
|
|
1123
|
+
|
|
1124
|
+
export function ReadMore({ attributes, className, partAttributes, slots }: BlockComponentProps) {
|
|
1125
|
+
const root = useRef<HTMLDivElement>(null)
|
|
1126
|
+
const [open, setOpen] = useState(false)
|
|
1127
|
+
// The editor selected the block or a block in its hidden part: show it.
|
|
1128
|
+
useCanvasReveal(root, () => setOpen(true))
|
|
1129
|
+
return (
|
|
1130
|
+
<div {...attributes} ref={root} className={className}>
|
|
1131
|
+
<div {...partAttributes.more} hidden={!open}>{slots.more}</div>
|
|
1132
|
+
{/* On the canvas the button opens and closes the part, as on the site. */}
|
|
1133
|
+
<button {...CONTROL} type="button" aria-expanded={open} onClick={() => setOpen(!open)}>
|
|
1134
|
+
{open ? 'Show less' : 'Read more'}
|
|
1135
|
+
</button>
|
|
1136
|
+
</div>
|
|
1137
|
+
)
|
|
1138
|
+
}
|
|
1139
|
+
```
|
|
1140
|
+
|
|
1141
|
+
The built-in carousel, popup and tabs use the hook and mark their controls. The disclosure and the accordion are native `<details>`, so the canvas opens them by itself.
|
|
1142
|
+
|
|
1143
|
+
A box that shows over the page on the canvas (an open popover, such as the built-in popup) is a layer. The canvas measures each one (`CanvasMeasurement.layers`) and marks the blocks inside it. Over a layer, the hover outline, selection, the "+" and drops reach only the layer's blocks, never the page under it. A click on the layer's padding selects its block. A click on its backdrop works as on the site and selects nothing. `reachableAt(measurement, point)` in `payload-canvas/core` gives the blocks and slots a point can reach.
|
|
1144
|
+
|
|
998
1145
|
### Validation, hooks and access on block fields
|
|
999
1146
|
|
|
1000
1147
|
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).
|
|
@@ -1043,7 +1190,7 @@ Limits:
|
|
|
1043
1190
|
|
|
1044
1191
|
### Built-in blocks
|
|
1045
1192
|
|
|
1046
|
-
Some blocks most sites need come with the plugin, but they are off until you add them: `icon`, `disclosure`, `accordion`, `
|
|
1193
|
+
Some blocks most sites need come with the plugin, but they are off until you add them: `icon`, `disclosure`, `accordion`, `popup`, `tabs` (with its `tab` blocks), `carousel`, `marquee`, `tableOfContents`, `filterLink`, `adjacentLinks` (previous / next) and `embed` (custom HTML). (The live saved section block, `sectionRef`, is not one of them: the plugin adds it, see [Live saved sections](#live-saved-sections-sectionref).) Add the definitions next to `defaultBlocks()`, and the components next to yours:
|
|
1047
1194
|
|
|
1048
1195
|
```ts
|
|
1049
1196
|
// src/builder.ts
|
|
@@ -1052,7 +1199,7 @@ import { ICON_NAMES } from './icons/names'
|
|
|
1052
1199
|
|
|
1053
1200
|
export const blocks = [
|
|
1054
1201
|
...defaultBlocks({ mediaCollection: 'media' }),
|
|
1055
|
-
...builtinBlocks({ include: ['icon', 'carousel', '
|
|
1202
|
+
...builtinBlocks({ include: ['icon', 'carousel', 'popup'], icons: ICON_NAMES }),
|
|
1056
1203
|
]
|
|
1057
1204
|
```
|
|
1058
1205
|
|
|
@@ -1061,14 +1208,36 @@ export const blocks = [
|
|
|
1061
1208
|
import { builtinComponents, type BlockComponents } from 'payload-canvas/react'
|
|
1062
1209
|
import { icons } from './icons'
|
|
1063
1210
|
|
|
1064
|
-
|
|
1211
|
+
// Call it once, at module level.
|
|
1212
|
+
export const components: BlockComponents = { ...builtinComponents({ icons, labels }), pricingTable: PricingTable }
|
|
1065
1213
|
```
|
|
1066
1214
|
|
|
1067
|
-
- Without `include`, `builtinBlocks()` adds all of them (`icon` only when you give `icons`).
|
|
1215
|
+
- Without `include`, `builtinBlocks()` adds all of them (`icon` only when you give `icons`, `embed` only when you give `embed`).
|
|
1068
1216
|
- The MCP tools and the AI assistant read the same `blocks` list, so they see each built-in you include, with its description and example.
|
|
1069
|
-
- Every built-in takes its look from `className`. The definitions have plain `defaultClassName`s without colours.
|
|
1217
|
+
- Every built-in takes its look from `className`. The definitions have plain `defaultClassName`s without colours. Inner elements that have their own entry in the **Style target** select are parts (see [Classes on inner elements](#classes-on-inner-elements)). The other inner elements have `data-*` attributes, so you style them from the block's `className` with variants such as `[&_[data-page-gap]]:opacity-50`.
|
|
1070
1218
|
- **Replace a built-in** with your own block of the same type: leave it out of `include` and add your block. Block types must be unique, so the plugin refuses both at once. In the components map, a key of yours with the same type wins over `builtinComponents()`.
|
|
1071
|
-
- `builtinComponents()` returns every built-in component.
|
|
1219
|
+
- `builtinComponents()` returns every built-in component. The interactive ones (carousel, popup, tabs, accordion, filter link) load their JavaScript only on pages that render them, so blocks you do not use cost nothing on the page. The marquee and previous / next are server components with no JavaScript.
|
|
1220
|
+
- For a photo that opens large, use a popup with a small image in its trigger and the large image in its content. For a background, put an `image` or `video` block first in a stack with `relative isolate`, and give the media `absolute inset-0 -z-10 size-full object-cover`.
|
|
1221
|
+
|
|
1222
|
+
#### Labels
|
|
1223
|
+
|
|
1224
|
+
The carousel, popup, tabs, table of contents, previous / next and menu have labels: the text of their controls and their names for screen readers ("Next slide", "Close", "Tab {n}", "On this page", "Previous and next", "Menu"). A new block stores none of them. An empty label uses the site's label, else the English one, which the empty input shows as its placeholder. Set the site's labels once, for example in its language:
|
|
1225
|
+
|
|
1226
|
+
```ts
|
|
1227
|
+
const labels = {
|
|
1228
|
+
carousel: { label: 'Karussell', previousLabel: 'Vorherige Folie', nextLabel: 'Nächste Folie', dotLabel: 'Folie {n}' },
|
|
1229
|
+
popup: { closeLabel: 'Schließen' },
|
|
1230
|
+
tabs: { tabLabel: 'Reiter {n}' },
|
|
1231
|
+
tableOfContents: { label: 'Auf dieser Seite' },
|
|
1232
|
+
adjacentLinks: { label: 'Vorheriger und nächster Beitrag' },
|
|
1233
|
+
menu: { label: 'Hauptmenü', toggleLabel: 'Menü', submenuLabel: 'Untermenü {label}' },
|
|
1234
|
+
} satisfies BuiltinLabels
|
|
1235
|
+
builtinComponents({ labels })
|
|
1236
|
+
```
|
|
1237
|
+
|
|
1238
|
+
- One block can still have its own label: type it in the block's props (under **Labels** for control labels). Label props are localized.
|
|
1239
|
+
- With `menu` labels, the map also holds a `menu` component (the default menu with those labels). A `menu` component of yours that comes after it in the map wins.
|
|
1240
|
+
- The English defaults are exported: `CAROUSEL_LABELS`, `POPUP_LABELS`, `TABS_LABELS`, `TABLE_OF_CONTENTS_LABELS`, `ADJACENT_LINKS_LABELS` and `MENU_LABELS` from `payload-canvas/blocks`.
|
|
1072
1241
|
|
|
1073
1242
|
#### Icon
|
|
1074
1243
|
|
|
@@ -1087,86 +1256,126 @@ export const icons = { arrowRight: ArrowRight, check: Check, close: Close } sati
|
|
|
1087
1256
|
- Each icon component gets `className`, the ARIA attributes and, on the canvas, the editor attributes. Spread its props on the `<svg>`.
|
|
1088
1257
|
- An unknown name renders nothing on the site and a note on the canvas.
|
|
1089
1258
|
|
|
1090
|
-
**
|
|
1259
|
+
**A button with an icon.** Put a `text` block and an `icon` block in a `link` block. An icon is an inline block, so it may go straight into a link. Give the link the button's classes (`inline-flex items-center gap-2 rounded-md bg-primary px-4 py-2`). The `button` block has no icon props.
|
|
1091
1260
|
|
|
1092
|
-
```ts
|
|
1093
|
-
...defaultBlocks({ mediaCollection: 'media', icons: ICON_NAMES }),
|
|
1094
|
-
```
|
|
1095
1261
|
|
|
1096
1262
|
#### Disclosure and accordion
|
|
1097
1263
|
|
|
1098
1264
|
`disclosure` is one show/hide item: a native `<details>` with a `summary` slot (always visible) and a `content` slot. It opens with the mouse and the keyboard without script, and the closed content stays in the HTML for search engines. `accordion` is a list of disclosures in its `items` slot (also a `repeat` or `collectionList` of disclosures). Include both: `include: ['disclosure', 'accordion']`.
|
|
1099
1265
|
|
|
1100
|
-
- `disclosure` props: `open` (open at first) and `animate` (the
|
|
1266
|
+
- `disclosure` props: `open` (open at first) and `animate` (the content grows and fades in, in 200 ms, in CSS only; off with reduced motion, and in browsers without `::details-content`).
|
|
1267
|
+
- On the canvas it starts open or closed as on the site. A click on the title opens or closes it, a double-click edits the title text, and selecting a block inside opens it.
|
|
1101
1268
|
- The summary slot refuses links, buttons and other controls: a `<summary>` is the button.
|
|
1102
1269
|
- Style the summary row with `[&>summary]:` classes and the content with `[&>div]:` classes on the disclosure. `open:` and `group-open:` classes style the open state, for example `group-open:rotate-45` on an icon in the summary.
|
|
1103
|
-
- `accordion` props: `multiple` (default on; off keeps one item open, with the browser's exclusive `<details name>`) and `faqSchema
|
|
1104
|
-
- FAQPage JSON-LD: `
|
|
1270
|
+
- `accordion` props: `multiple` (default on; off keeps one item open, with the browser's exclusive `<details name>`) and `faqSchema`, **Mark up as FAQ for search engines** (default off). Turn it on only for real questions and answers: search engines treat FAQ markup on other content as spam.
|
|
1271
|
+
- FAQPage JSON-LD: `RenderLayout` outputs it on the site by itself. When an accordion in the layout has `faqSchema` on, the layout renders one `<script type="application/ld+json">` with the questions (summary text) and answers (content text), with `<` escaped. Bound props, `field` blocks, repeats and collection lists give the document's values. Nothing is output on the canvas, or when no accordion opts in.
|
|
1272
|
+
- `<RenderLayout faqJsonLd={false} />` turns it off, for a site that writes its own. `faqItems(layout, blocks)` and `faqJsonLd(items)` from `payload-canvas/blocks` build the same data, for example to merge the FAQs of several layouts into one script:
|
|
1105
1273
|
|
|
1106
1274
|
```tsx
|
|
1107
1275
|
const items = [layout, templateLayout].flatMap((value) => faqItems(value, blocks))
|
|
1108
1276
|
const jsonLd = faqJsonLd(items)
|
|
1109
1277
|
// <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd).replace(/</g, '\\u003c') }} />
|
|
1278
|
+
// and <RenderLayout faqJsonLd={false} … /> for those layouts
|
|
1110
1279
|
```
|
|
1111
1280
|
|
|
1112
|
-
####
|
|
1281
|
+
#### Popup
|
|
1282
|
+
|
|
1283
|
+
`popup` is a button that opens a box over the page: a video, a large photo, a form. Its `trigger` slot is what the visitor clicks (a text, an icon, a small image). Its `content` slot is the box. The content stays in the HTML for search engines.
|
|
1284
|
+
|
|
1285
|
+
- The box is a native modal `<dialog>`. It keeps the focus inside and makes the page inert. Escape, the close button and a click beside the box close it, and the page does not scroll while it is open.
|
|
1286
|
+
- The trigger renders inside a `<button>`, so its slot refuses links, buttons, other controls, popups and tabs.
|
|
1287
|
+
- Props: `label` (the box's name for screen readers; empty: the first heading in the content) and `anchor`. With `anchor: 'newsletter'`, every link to `#newsletter` on the page opens the popup, and so does a page address that ends in `#newsletter`. With an anchor the trigger may stay empty: the site then renders no button.
|
|
1288
|
+
- Parts: the `trigger` and `content` slots, `panel` (the dialog box; `backdrop:` classes colour the backdrop, for example `backdrop:bg-black/60`) and `close` (the close button, placed absolutely in the panel). A new popup starts with a centred panel that fades and grows in (150 ms, `starting:opacity-0 starting:scale-95`; not with reduced motion) and a round close button.
|
|
1289
|
+
- **A photo that opens large.** Put a small image in the trigger and the large image in the content. Give the panel `max-w-5xl p-0` and the content `gap-0`.
|
|
1290
|
+
- On the canvas the box shows as on the site: centred over the page, with its backdrop. It opens when you click the trigger, or when you select the popup or a block inside it (on the canvas or in **Layers**). It is not modal: you select and edit the blocks in it as anywhere else, and a click on the box's padding selects the popup. Escape, the close button, a click on the backdrop and selecting a block outside it close it.
|
|
1291
|
+
- Control label, under **Labels** in the Content tab: `closeLabel` ("Close"). An empty label uses the site's label or the English one (see [Labels](#labels)).
|
|
1292
|
+
|
|
1293
|
+
#### Tabs
|
|
1294
|
+
|
|
1295
|
+
`tabs` shows one row of tab names and one panel at a time. Its `tabs` slot takes only `tab` blocks, at least two. A new tabs block starts with two. Each `tab` has a `label` (the tab name) and a `content` slot (its panel). Include `tabs`: it brings the `tab` block with it.
|
|
1296
|
+
|
|
1297
|
+
- The first tab is open at first. It follows the WAI-ARIA tabs pattern: the arrow keys move between tabs (and wrap), Home and End jump to the first and last tab, and only the open tab is in the Tab order. Hidden panels stay in the HTML with `hidden`.
|
|
1298
|
+
- Props: `label` (the tab row's name for screen readers) and `vertical` (the tabs stand in a column; the up and down arrows move). For a column, lay out the block with `flex flex-row gap-8` and give the `list` part `flex flex-col`.
|
|
1299
|
+
- Parts: `list` (the row of tabs), `tab` (each tab button) and `panel` (each panel). The open tab has `aria-selected="true"`, so `aria-selected:` classes style it: a new tabs block starts with `aria-selected:border-current aria-selected:opacity-100`. A `tab` block's own `className` styles its own panel.
|
|
1300
|
+
- The panel that becomes visible fades in: a new tabs block's `panel` part starts with `transition-opacity duration-150 ease-out starting:opacity-0 motion-reduce:transition-none`. Change or remove those classes in the Styles panel.
|
|
1301
|
+
- On the canvas a click on a tab opens it, and selecting a block opens the tab that holds it.
|
|
1302
|
+
- Control label: `tabLabel` ("Tab {n}"), the name of a tab without a label. `{n}` is the tab number.
|
|
1303
|
+
|
|
1304
|
+
#### Embed
|
|
1305
|
+
|
|
1306
|
+
`embed` holds custom HTML: a booking widget, a map, a newsletter form from another service. It is off until you turn it on, because its code runs on your site:
|
|
1307
|
+
|
|
1308
|
+
```ts
|
|
1309
|
+
builtinBlocks({ embed: {} }) // or include: [..., 'embed']
|
|
1310
|
+
// Only admins may change the code and the mode:
|
|
1311
|
+
builtinBlocks({ embed: { canEdit: ({ req }) => req.user?.role === 'admin' } })
|
|
1312
|
+
```
|
|
1113
1313
|
|
|
1114
|
-
|
|
1314
|
+
- Props: `code` (HTML, edited in Payload's code editor), `mode` and `title`.
|
|
1315
|
+
- `mode: 'inline'` (**In the page**, the default) puts the HTML in the page. Its `<script>` tags run once the page loads: the browser runs those of the server's HTML, and the block runs them again after a page change in the app (it copies each script, so external scripts keep their order). This JavaScript loads only on pages with an inline embed.
|
|
1316
|
+
- `mode: 'isolated'` (**In its own frame**) shows the HTML in a sandboxed `<iframe srcdoc>`. Scripts, forms and links to new tabs work, but the code cannot reach your page or the visitor's session (no `allow-same-origin`). A frame does not grow with its content: give the block a height, for example `h-96` or `aspect-video`. `title` is the frame's name for screen readers (empty: "Embedded content", or the site's label `builtinComponents({ labels: { embed: { title } } })`).
|
|
1317
|
+
- The editor never runs the code. The canvas shows it in a frame with scripts off, with the page's styles for inline code. Empty code, or code with nothing to see (only scripts), shows a "Custom code" box.
|
|
1318
|
+
- Access: `embed.canEdit` is a Payload field access function on `code` and `mode` (as `access.create` and `access.update`). Default: everyone who may edit the document may change them. Users without it see the code read-only. MCP agents and the AI assistant act as their user, so the same rule applies to them. See [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields).
|
|
1319
|
+
- `embed.maxLength`: the longest code, in characters. Default 50,000 (`EMBED_MAX_LENGTH`). Longer code blocks **Publish**.
|
|
1115
1320
|
|
|
1116
|
-
- A click on an image, or Enter or Space on a focused image, opens it in a native modal `<dialog>`. The dialog keeps the focus inside, makes the page inert, closes on Escape and gives the focus back. Arrow keys and the arrow buttons step through the images. On touch screens a sideways swipe steps too: left for the next photo, right for the previous one (pointer events, at least 50 px and more sideways than down; a mouse drag does not swipe). A click beside the photo closes it.
|
|
1117
|
-
- The images get `tabindex="0"`, `role="button"` and `aria-haspopup="dialog"`. Images inside a link or a button keep that element as the control.
|
|
1118
|
-
- Props: `label` (the dialog's name for screen readers, default "Photos"), `group` (lightboxes with the same group on a page open as one set) `captions` (shows the alt text under the photo; screen readers always hear "2 of 6") and `count` (default on: shows "2 of 6" at the top left when the set has more than one photo).
|
|
1119
|
-
- A set holds each photo once: two images with the same `src` attribute are one photo. An image with `data-lightbox-skip` (on the image or an element round it; `LIGHTBOX_SKIP_ATTRIBUTE`) is not in the set, but a click on it opens the set at the photo with the same `src`. Example: an image switcher puts its thumbnails and its large photo in one lightbox and skips the large photo, so the lightbox opens on the photo shown large and steps through the thumbnails.
|
|
1120
|
-
- When it closes, the lightbox sends a bubbling `lightbox-close` event (`LIGHTBOX_CLOSE_EVENT`) to the page image of the photo it showed last; `detail.index` is the photo's place in the set.
|
|
1121
|
-
- Motion: the dialog and its backdrop fade in (320 ms, ease-out) while the photo grows from 96%; a step slides the old photo out and the new one in (260 ms); closing fades out (200 ms), also on Escape. Under reduced motion only the fades stay. A photo that has not loaded after 150 ms shows a spinning ring.
|
|
1122
|
-
- The large photo is the image the page already loaded, with its `srcset` and `sizes="100vw"`, so the browser picks a larger file when it has one.
|
|
1123
|
-
- Style the dialog from the block's `className`: `[&_dialog]:` for its text colour and backdrop (`[&_dialog]:backdrop:bg-black/85`), `[&_[data-lightbox-button]]:` for the close, previous and next buttons (`data-lightbox-button` is `close`, `previous` or `next`) `[&_[data-lightbox-photo]]:` for the large photo (during a step the leaving photo has `data-lightbox-photo="leaving"`), `[&_[data-lightbox-count]]:` for the photo number and `[&_[data-lightbox-loading]]:` for the loading ring (its colour is the text colour). The component sets only position and size.
|
|
1124
|
-
- The canvas never opens it, so a click selects an image there.
|
|
1125
|
-
- Control labels, under **Labels** in the Content tab (localized, English defaults): `closeLabel` ("Close"), `previousLabel` ("Previous photo"), `nextLabel` ("Next photo") and `countLabel` ("{n} of {count}", the photo number). An empty label uses the default.
|
|
1126
1321
|
|
|
1127
1322
|
#### Carousel
|
|
1128
1323
|
|
|
1129
|
-
`carousel` shows the blocks of its `slides` slot as slides. Each direct child is one slide
|
|
1324
|
+
`carousel` shows the blocks of its `slides` slot as slides. It runs on [Embla Carousel](https://www.embla-carousel.com/). Each direct child is one slide. Set how many slides show at once with each slide's `className`: `basis-full md:basis-1/2` (or a width such as `w-[85%]`). A single `collectionList` or `repeat` child makes each of its items a slide: set the basis on the item. Any other single child is one slide.
|
|
1130
1325
|
|
|
1131
|
-
-
|
|
1326
|
+
- Visitors swipe or drag the slides, click the arrows or dots, or use the arrow keys when the carousel has the focus.
|
|
1327
|
+
- Props: `mode` (`scroll`: the slides slide sideways; `fade`: one slide fades into the next), `align` (**Slide position**: `start` or `center`, where the current slide sits when the slides are narrower than the carousel), `arrows` (default on), `dots`, `loop`, `autoplay` (milliseconds, 0 is off) and `label` (the region's name, default "Carousel").
|
|
1328
|
+
- Dots: one per stop, not one per slide. When two slides show at once, six slides have three dots.
|
|
1132
1329
|
- The optional `previous` and `next` slots hold the content of the arrow buttons, for example an `icon` block. Empty, they show a chevron.
|
|
1133
|
-
- Accessibility: the carousel is a `<section>` region with `aria-roledescription="carousel"` and its label. Each slide is a group labelled "2 of 6". The
|
|
1134
|
-
- Autoplay shows a Pause button (WCAG 2.2.2)
|
|
1135
|
-
- Style
|
|
1136
|
-
- Control labels, under **Labels** in the Content tab
|
|
1137
|
-
-
|
|
1330
|
+
- Accessibility: the carousel is a `<section>` region with `aria-roledescription="carousel"` and its label. Each slide is a group labelled "2 of 6". The viewport takes the keyboard focus. The track announces slide changes (`aria-live="polite"`) unless autoplay is running.
|
|
1331
|
+
- Autoplay shows a Pause button (WCAG 2.2.2). It pauses while the pointer is over the carousel and while it has the focus, stops when the visitor swipes, and never runs when the visitor asks for less motion.
|
|
1332
|
+
- Style the inner elements as parts (`partClassName`, the **Style target** select): `slides` for the track (the gap between slides), `arrow` for both arrows (`disabled:` at either end without `loop`), `dot` for each dot (the current dot has `aria-current="true"`; its visible mark is its `::after`), `controls` for the row of controls and `pause` for the pause button. A new carousel starts with round bordered arrows and small round dots, in the text colour.
|
|
1333
|
+
- Control labels, under **Labels** in the Content tab: `previousLabel` ("Previous slide"), `nextLabel` ("Next slide"), `pauseLabel` ("Pause"), `playLabel` ("Play"), `dotLabel` ("Slide {n}"), `slideLabel` ("{n} of {count}") and the `aria-roledescription` names `carouselRole` ("carousel") and `slideRole` ("slide"). `{n}` is the slide number and `{count}` the number of slides. An empty label uses the site's label or the English one (see [Labels](#labels)).
|
|
1334
|
+
- On the canvas the arrows and dots work, the slides do not drag (you drag blocks there), fade shows as sliding, and autoplay is off. Selecting a block in a slide moves the carousel to that slide.
|
|
1335
|
+
- Carousels saved before the move to Embla render as they are.
|
|
1336
|
+
|
|
1337
|
+
#### Marquee
|
|
1338
|
+
|
|
1339
|
+
`marquee` is a row of logos or words that scrolls sideways without end. It is CSS only: a server component with no JavaScript. Each direct child of its `children` slot is one item; give images a fixed height (`h-8 w-auto`).
|
|
1340
|
+
|
|
1341
|
+
- Props: `speed` (`slow`, `normal` or `fast`: 60, 35 or 20 seconds per round), `direction` (`left` or `right`) and `pauseOnHover` (default on; it also stops while a link in it has the focus).
|
|
1342
|
+
- The items render twice, so the row loops without a gap. The copy is hidden from screen readers and the keyboard. Keep the row wider than the screen: repeat a short list of items.
|
|
1343
|
+
- Space the items with margins in the `children` part (a new marquee has `*:mx-8`), not with a gap, so the loop does not jump.
|
|
1344
|
+
- The default `className` fades the edges with a mask, so it works on any background.
|
|
1345
|
+
- With reduced motion, and on the canvas, it stands still and the items wrap.
|
|
1138
1346
|
|
|
1139
1347
|
#### Table of contents
|
|
1140
1348
|
|
|
1141
1349
|
`tableOfContents` links to the H2 headings of a rich text field of the current document, for example the body of a post template. Bind its `content` prop to that field: `bindings: { content: 'content' }` (in the inspector, the bind button next to "Rich text"). It renders a `<nav>` of bare `<a href="#id">` links; style them with `[&>a]:` classes on the block.
|
|
1142
1350
|
|
|
1143
1351
|
- Props: `content` (the rich text, usually bound), `minHeadings` (default 3; with fewer headings the block renders nothing) and `label` (the nav's name, default "On this page").
|
|
1144
|
-
- The
|
|
1145
|
-
- Headings with the same text get their own ids: the second `
|
|
1352
|
+
- The `richText` and `field` blocks give each heading on the page an id from its text (`headingId(text)` in `payload-canvas/core`): lower case, accents dropped, other characters as hyphens, letters of every script kept ("Über uns?" becomes `uber-uns`). So the links find the headings with no setting. Only top-level H2 headings with letters or digits are listed.
|
|
1353
|
+
- Headings with the same text get their own ids: the second `pricing-2`, the third `pricing-3`, the same ids the rich text renders.
|
|
1146
1354
|
- On the canvas, with too few headings, it shows three sample links, so it can be selected and styled.
|
|
1147
1355
|
|
|
1148
1356
|
#### Filter link
|
|
1149
1357
|
|
|
1150
|
-
`filterLink` is a link to the current page with one URL query value set, toggled or cleared. It pairs with a collection list's `queryFilters`: a filter link with `param: '
|
|
1358
|
+
`filterLink` is a link to the current page with one URL query value set, toggled or cleared. It pairs with a collection list's `queryFilters`: a filter link with `param: 'category'` and `value: 'news'` goes to `?category=news`, and the list filters by it. Its `children` slot holds the label (a text, an icon); links and controls are refused there.
|
|
1151
1359
|
|
|
1152
|
-
- Props: `param`, `value` and `multiple`. An empty `param` clears every query value (the "All" link). An empty `value` clears its param. `multiple` adds or removes the value in a comma list (`?
|
|
1360
|
+
- Props: `param`, `value` and `multiple`. An empty `param` clears every query value (the "All" link). An empty `value` clears its param. `multiple` adds or removes the value in a comma list (`?tag=css,react`) instead of replacing it. The page's other query values stay.
|
|
1153
1361
|
- The current filter gets `aria-current="true"`. Style it with `aria-[current=true]:` classes.
|
|
1154
1362
|
- A new filter starts the lists at page 1: the link drops `page`, and the `pageParam` of every paginated list in the same layout (`loadLayoutData` and the canvas give each filter link these as the runtime `$pageParams` prop). Limit: a list in another layout (a page region) is not known, so its own page param stays.
|
|
1155
|
-
- It is a client component that reads the browser's URL. The server renders a relative href (`?
|
|
1363
|
+
- It is a client component that reads the browser's URL. The server renders a relative href (`?category=news`), so the link works before the script runs and search engines can follow it. The active state and the kept query values appear after hydration.
|
|
1156
1364
|
- `filterHref(path, query, { param, value, multiple, pageParams })` in `payload-canvas/blocks` is the same rule as a pure function, for a server component of your own.
|
|
1157
1365
|
- Send `noindex, follow` for filtered URLs.
|
|
1158
1366
|
|
|
1159
|
-
####
|
|
1367
|
+
#### Previous / next
|
|
1368
|
+
|
|
1369
|
+
`adjacentLinks` (**Previous / next**) links to the previous and the next document of the same collection, at the end of a template: blog posts, case studies. It is a `<nav>` with two slots, `previous` and `next`. Each slot holds one collection list that finds its document with a value of the page's own document:
|
|
1160
1370
|
|
|
1161
|
-
`
|
|
1371
|
+
- `previous`: `sort: '-publishedAt'`, `limit: 1`, `where: { publishedAt: { less_than: '$page.publishedAt' } }`.
|
|
1372
|
+
- `next`: `sort: 'publishedAt'`, `limit: 1`, `where: { publishedAt: { greater_than: '$page.publishedAt' } }`.
|
|
1162
1373
|
|
|
1163
|
-
|
|
1164
|
-
|
|
1165
|
-
-
|
|
1166
|
-
-
|
|
1167
|
-
-
|
|
1168
|
-
- Style the media with `[&>[data-backdrop-media]]:` classes (blur, opacity) and the overlay with `[&>[data-backdrop-overlay]]:` classes (`[&>[data-backdrop-overlay]]:bg-black/40`).
|
|
1169
|
-
- No WebGL effects.
|
|
1374
|
+
`createdAt`, or any date or number field, works the same way. The list's `item` slot is the link: a `link` bound to `$url` around a text ("← Previous") and a heading bound to `title`. The starter's post template shows the full pattern (`apps/starter/src/data/sections/postTemplate.ts`).
|
|
1375
|
+
|
|
1376
|
+
- On the site a side without a document renders nothing. With no document on either side, the whole block renders nothing. The canvas always shows both sides.
|
|
1377
|
+
- Parts: the `previous` and `next` slots. A new block puts the next link at the end (`ms-auto`).
|
|
1378
|
+
- Control label: `label` (the `<nav>`'s name, default "Previous and next").
|
|
1170
1379
|
|
|
1171
1380
|
## Using existing Payload blocks
|
|
1172
1381
|
|
|
@@ -1349,7 +1558,7 @@ export function TwoColumnComponent({ leftColumn, rightColumn, builder }: Payload
|
|
|
1349
1558
|
}
|
|
1350
1559
|
```
|
|
1351
1560
|
|
|
1352
|
-
The `builder` prop holds `mode`, `className`, `slots` (rendered children by slot name) and `
|
|
1561
|
+
The `builder` prop holds `mode`, `className`, `slots` (rendered children by slot name) and `partAttributes`. In the canvas, the adapter puts the block id on your component's first element. It adds no wrapper element, so the layout stays as on the site: container rules such as `space-y-8` and `divide-y` reach your elements. A component that renders nothing gets a small placeholder.
|
|
1353
1562
|
|
|
1354
1563
|
### Limitations
|
|
1355
1564
|
|
|
@@ -1438,7 +1647,15 @@ export const hero = defineSection({
|
|
|
1438
1647
|
})
|
|
1439
1648
|
```
|
|
1440
1649
|
|
|
1441
|
-
|
|
1650
|
+
How the versions show up:
|
|
1651
|
+
|
|
1652
|
+
- **Sections tab.** A section with variants is one card. The ‹ › arrows on its picture flip the card between the versions ("2 / 3"). A click or a drag inserts the version the card shows. Search also finds a section by a variant's label.
|
|
1653
|
+
- **Switch after the insert.** The root block of an inserted section remembers where it came from: `block.section = { id: 'hero', variant: 'split' }` (no `variant` for the section's own version). When you select that block, its action bar on the canvas shows ‹ Split ›. The arrows replace the section in place with the previous or next version, as one undo step. Text and images you changed come along: blocks pair by the same `id` in both versions first, then by type in order (the first heading with the first heading). Give a block the same `id` in each version to pair it exactly. The root block keeps its name and HTML id. Classes, animations and the structure come from the new version. Blocks you added inside the section are not carried over; undo brings them back. A translation stays only when the text it translates did not change.
|
|
1654
|
+
- **`variantLabel`** names the section's own version in the switch. Default "Default".
|
|
1655
|
+
- **MCP and the assistant.** `listSections` lists the variants under their section (`variants: [{ id, label, description?, outline }]`; `full: true` gives their `blocks`). `insertSection` takes `variant: "split"`. The old ids such as `hero/split` still work.
|
|
1656
|
+
- Only a section with one root block gets `block.section`: a section of several top-level blocks has nothing to switch. Saved sections have no variants, and "Save as section…" drops `block.section`.
|
|
1657
|
+
|
|
1658
|
+
`defineSection` fills a variant's missing block ids as `<section id>_<variant id>_1`, `_2`, …, and throws when a variant has no `id` or `label` or two variants share an id. Variant blocks get their `defaultClassName` like section blocks. `sectionVersion(section, variant?)` (from `payload-canvas`) returns one version ready to insert, with `block.section` set, for your own code such as a seed. `sectionsWithVariants(sections)` still returns the old flat list (`hero/split` as a section of its own), but the plugin no longer uses it.
|
|
1442
1659
|
|
|
1443
1660
|
The library shows each section as a real picture: the hidden canvas page (`?mode=thumbnail`) renders one section at a time with your components and theme, at a desktop width of 1280 px, and the editor keeps the picture in IndexedDB. A picture changes when the section, the theme or the block definitions change. Cards show a wireframe until their picture is ready, or when it fails.
|
|
1444
1661
|
|
|
@@ -1446,7 +1663,7 @@ The library shows each section as a real picture: the hidden canvas page (`?mode
|
|
|
1446
1663
|
|
|
1447
1664
|
Editors save their own sections: select a block (a whole section, or any block with its children), open **…** on the canvas or in the inspector, and choose **Save as section…**. Give it a name and, if you like, a category. It appears in **Add › Sections** under **Saved**, for everyone who edits pages. Insert it like any section; every insert gets new block ids. The card's **…** menu edits, renames or deletes it. A deleted section stays on the pages that use it.
|
|
1448
1665
|
|
|
1449
|
-
**Edit section** (in the card's **…** menu) opens the section in the full-screen builder, like a page, at `/admin/builder/builder-sections/<id>`. The top bar shows "Section: <name>" and its category; click either to change it. **Back** returns to the page you came from. Sections have no drafts: each change saves to the section at once, and the library pictures follow on their own. Pages that already inserted the section keep their own copy
|
|
1666
|
+
**Edit section** (in the card's **…** menu) opens the section in the full-screen builder, like a page, at `/admin/builder/builder-sections/<id>`. The top bar shows "Section: <name>" and its category; click either to change it. **Back** returns to the page you came from. Sections have no drafts: each change saves to the section at once, and the library pictures follow on their own. Pages that already inserted the section as plain blocks keep their own copy: a change applies only to later inserts. Copies of a component (see [Components](#components-sections-with-properties)) follow every change. The section's **Builder** tab in the admin opens the same view.
|
|
1450
1667
|
|
|
1451
1668
|
The collection stores the blocks in its `blocks` field. The builder edits a virtual `layout` field (no database column) that reads from `blocks`, and a save hook writes the layout back to `blocks`. While the section is open in the builder, the live session owns its blocks: a REST save of `blocks` gets the session's blocks, as on pages. Otherwise a REST or MCP save of `blocks` works as before.
|
|
1452
1669
|
|
|
@@ -1458,22 +1675,39 @@ A saved section runs the same field logic as a page save: the `beforeValidate` a
|
|
|
1458
1675
|
|
|
1459
1676
|
An inserted section is a copy: later edits of the saved section do not reach the page. A `sectionRef` block shows a saved section **live** instead: the page renders the section's current blocks, so one edit changes every page that uses it. Use it for blocks many pages share, such as a call to action or a footer band.
|
|
1460
1677
|
|
|
1461
|
-
|
|
1462
|
-
...builtinBlocks({ include: ['sectionRef'] }), // `sectionsCollection` if you set `savedSections.slug`
|
|
1463
|
-
```
|
|
1464
|
-
|
|
1465
|
-
- `builtinBlocks()` adds it only when `include` lists it, because it needs the plugin's saved sections. `builtinComponents()` has its component.
|
|
1678
|
+
- The plugin adds the block when saved sections are on (the default), pointed at their collection (`savedSections.slug`). Your own block list does not need it, and `defaultComponents` has its component. `loadLayoutData` reads the collection from the Payload config.
|
|
1466
1679
|
- Prop: `section`, a relationship to the saved sections collection. It has no classes and no slots. On the site it renders the section's blocks with no element of its own.
|
|
1467
|
-
- `loadLayoutData` loads the sections first, so their lists, images, bindings and translations load like the page's own. The canvas does the same. Copies of the section's blocks get ids prefixed with the ref's id (`<ref id>_<block id>`).
|
|
1680
|
+
- `loadLayoutData` loads the sections first, so their lists, images, bindings and translations load like the page's own. The canvas does the same. Copies of the section's blocks get ids prefixed with the ref's id (`<ref id>_<block id>`). A `sectionRef` inside a saved section loads too, up to 5 levels. A section never includes itself: saving one that would is refused, and such a ref renders nothing.
|
|
1468
1681
|
- CSS: the save hook compiles only the page's own classes. Output the page CSS with `compilePageCss(payload, [{ layout: loaded }])` (from `payload-canvas/react/server`), with the layout `loadLayoutData` returned, so the section's classes are in it.
|
|
1469
|
-
- On the canvas the section's blocks show but cannot be edited there: a click selects the `sectionRef`. **Detach section** in its **…** menu replaces it with a copy of the blocks (new ids), as one undo step.
|
|
1470
|
-
-
|
|
1682
|
+
- On the canvas the section's blocks show but cannot be edited there: a click selects the `sectionRef`. **Detach section** in its **…** menu replaces it with a copy of the blocks (new ids), as one undo step. A component's copy keeps its own values in the blocks.
|
|
1683
|
+
- A deleted section shows "Component not found" on the canvas and nothing on the site.
|
|
1684
|
+
- References: the saved section lists the pages that show it (**Used in**), and it cannot be deleted while a page uses it, as with media. With saved sections on, the references field also points at the saved sections collection: run `pnpm payload migrate:create` for production.
|
|
1685
|
+
|
|
1686
|
+
#### Components (sections with properties)
|
|
1687
|
+
|
|
1688
|
+
A component is a saved section with **properties**: the parts each copy may change, like a title, a text, an image, a link or whether a button shows. The design stays in one place: change the component, and every copy follows. This works like Webflow's components.
|
|
1689
|
+
|
|
1690
|
+
**Make one.** Save a section, then open it with **Edit section**. Select a block and open its **Content** tab. Next to a text, rich text, image or link field, click the ◆ button (**Make it a property**) and give the property a name. The field now shows a **Property** chip; its own value is the default every copy starts with. The **Visible** row under the fields makes a property that shows or hides the block. Use the same name on two fields to fill both with one value. The **×** on the chip makes it a normal field again. A banner on top of the inspector says how many places use the component.
|
|
1691
|
+
|
|
1692
|
+
**Use one.** Components are in **Add › Sections** under **Saved**, with a ◆ mark and "Component". A click or a drag adds a copy that stays in sync (a `sectionRef` block). Select it to see the component's properties as normal fields; an empty field shows the component's own content. **Edit component** opens the component; **Back** returns to the page. The card's **…** menu adds the component as plain blocks instead. A saved section without properties still goes in as plain blocks; its **…** menu adds a copy that stays in sync.
|
|
1693
|
+
|
|
1694
|
+
**Detach.** **Detach section** in the copy's **…** menu turns it into plain blocks with the copy's values in them.
|
|
1695
|
+
|
|
1696
|
+
How it is stored:
|
|
1697
|
+
|
|
1698
|
+
- A property is a binding inside the saved section that reads `$component.<name>`, for example `bindings: { text: '$component.title' }` on a heading. The bindings are the only record of the properties: no extra field, no migration. The type comes from the bound field (`text`, `richText`, `image` for an upload, `link` for a link group), the default is the prop's own value. A visible property uses the binding key `$visible`: `bindings: { $visible: '$component.showButton' }`.
|
|
1699
|
+
- A copy stores its values in `props.values` of the `sectionRef` block, by property name. Images are stored as `{ relationTo, value }`, so the page's references and **Used in** count them.
|
|
1700
|
+
- `attachSections` (used by `loadLayoutData` and the canvas) puts the values into the section's blocks before the rest of the data loading, so it works on the site, on the canvas and in server-rendered blocks. A template string may mix both: `{{$component.title}} for {{title}}`.
|
|
1701
|
+
- `core`: `componentProperties(blocks, definitions)`, `applyComponentValues(blocks, values, definitions)`, `checkComponentValues(properties, values)`.
|
|
1702
|
+
- MCP and the assistant: `listSections` shows `component: true` and the `properties` (name, type, default). `insertSection` takes `values` and inserts a copy that stays in sync; `linked: false` inserts plain blocks with the values in them.
|
|
1471
1703
|
|
|
1472
1704
|
## Styling
|
|
1473
1705
|
|
|
1474
1706
|
- **Classes.** Each block stores Tailwind v4 classes in `className`. Variants use normal Tailwind syntax: `md:flex-row`, `hover:bg-primary`, `dark:text-white`.
|
|
1475
|
-
- **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.
|
|
1476
|
-
- **
|
|
1707
|
+
- **Styles panel.** Visual controls for layout, spacing, size, position, typography, background, border and effects read and write classes. The breakpoint bar (`base`, `sm`, `md`, `lg`, `xl`, `2xl`) and the state bar (Default, Hover, Focus, Active) set the variant prefix. A line under them says what the controls change: "Editing this block at all screen sizes", or "Editing .card at md · 768 px and wider" while you edit a class.
|
|
1708
|
+
- **The Classes field** at the top of the Styles tab holds every class the controls do not show. [Editable classes](#editable-classes) are solid chips: click one to edit that class. Other classes (`dark:pt-4`, a code `@utility` class) are quiet chips in monospace: click one to change it, or × to remove it. Classes that a control shows (`p-4`, `md:flex`) have no chip. The input at the end adds any class, with suggestions. The "⋯" menu has **New class from these styles…**, **Import from the site's CSS** and **Edit as text** (the whole class list as one text box).
|
|
1709
|
+
- **Hide a block.** The inspector's **Advanced** tab has **Hide at all screen sizes** (`block.hidden`): the site does not render the block. To hide it at some sizes only, use Styles → Layout → **Display** → **Hidden** at a breakpoint. Hidden at `md` writes `md:hidden`: the block hides at `md` and wider. To hide it only on small screens, set Hidden at **All sizes** and a display at `md`: `hidden md:flex`.
|
|
1710
|
+
- **Site classes.** The **Classes** field in the Styles panel suggests your CSS entry's own static `@utility` classes (`type-h2`, `btn-primary`, `glass`) before Tailwind's classes. When the input gets the focus, it lists them by group, without the ones the block has. Typing filters them by class name or label. After a typed variant such as `md:`, the input lists them again, and the picked class gets the variant, as when you type it. A site class on the block shows its label next to the class name, and its tooltip shows the rule's CSS. A comment right above the rule sets a label and a group: `/* @canvas Buttons: Primary button */` (group "Buttons", label "Primary button") or `/* @canvas Primary button */` (a label only). Without a comment the class shows by its name. Classes from the files the entry imports count too, but not from packages in `node_modules`, and not functional utilities such as `tab-*`. `getStyleTokens()` returns them as `siteClasses` (`{ name, label?, group?, css }`). The MCP tool `listBlocks` and the assistant's prompt list them, so agents use the site's look.
|
|
1477
1711
|
|
|
1478
1712
|
```css
|
|
1479
1713
|
/* @canvas Buttons: Primary button */
|
|
@@ -1507,29 +1741,47 @@ export default function CanvasPage() {
|
|
|
1507
1741
|
- **Theme variables in the canvas.** The canvas gets the Theme global from `<ThemeStyle live />` in its layout. If you set other variables at runtime, render the same tag in the canvas layout too.
|
|
1508
1742
|
- **Standalone output** needs `outputFileTracingIncludes`. See [step 8](#8-add-the-standalone-tracing-lines).
|
|
1509
1743
|
|
|
1510
|
-
### Classes on
|
|
1744
|
+
### Classes on inner elements
|
|
1745
|
+
|
|
1746
|
+
A block can let the user style some of its inner elements, not only its root: a carousel's arrows, a collection list's page links, the `empty` slot of a collection list. These elements are the block's **parts**. Each part's classes live in `block.partClassName`, by part name.
|
|
1511
1747
|
|
|
1512
|
-
|
|
1748
|
+
There are two kinds of part:
|
|
1749
|
+
|
|
1750
|
+
- A slot with `styles: true`: the element that holds the slot's children, for example the `summary` and `content` of a disclosure.
|
|
1751
|
+
- An entry of `parts`: any other element, for example the carousel's `arrow`. A part name must not be a slot name.
|
|
1513
1752
|
|
|
1514
1753
|
```ts
|
|
1515
1754
|
defineBlock({
|
|
1516
|
-
type: '
|
|
1517
|
-
label: '
|
|
1755
|
+
type: 'gallery',
|
|
1756
|
+
label: 'Gallery',
|
|
1518
1757
|
fields: [],
|
|
1519
|
-
slots: {
|
|
1758
|
+
slots: { items: { label: 'Items', styles: true, defaultClassName: 'gap-4' } },
|
|
1759
|
+
parts: { caption: { label: 'Caption', defaultClassName: 'text-sm text-muted-foreground' } },
|
|
1520
1760
|
})
|
|
1521
1761
|
```
|
|
1522
1762
|
|
|
1763
|
+
```tsx
|
|
1764
|
+
function Gallery({ attributes, className, partAttributes, slots }: BlockComponentProps) {
|
|
1765
|
+
return (
|
|
1766
|
+
<figure {...attributes} className={className}>
|
|
1767
|
+
<div {...partAttributes.items} className={['grid', partAttributes.items?.className].filter(Boolean).join(' ')}>{slots.items}</div>
|
|
1768
|
+
<figcaption className={partAttributes.caption?.className}>A caption</figcaption>
|
|
1769
|
+
</figure>
|
|
1770
|
+
)
|
|
1771
|
+
}
|
|
1772
|
+
```
|
|
1773
|
+
|
|
1523
1774
|
```json
|
|
1524
|
-
{ "type": "collectionList", "className": "grid grid-cols-3 gap-6", "
|
|
1775
|
+
{ "type": "collectionList", "className": "grid grid-cols-3 gap-6", "partClassName": { "empty": "col-span-full text-center", "pager": "flex gap-2" } }
|
|
1525
1776
|
```
|
|
1526
1777
|
|
|
1527
|
-
- The component gets the classes in `
|
|
1778
|
+
- The component gets the classes in `partAttributes[name].className`, with the `builder-css` marker. Join them with the element's own classes.
|
|
1779
|
+
- `defaultClassName` on a part (or on a styled slot) gives a new block those classes, like the block's `defaultClassName`. Sections get them too (`withDefaultClassNames`).
|
|
1528
1780
|
- The save hook and the canvas compile them like `className`.
|
|
1529
|
-
- In the Styles tab, a block with
|
|
1530
|
-
- An update merges per
|
|
1531
|
-
- `validateLayout` refuses classes on a
|
|
1532
|
-
-
|
|
1781
|
+
- In the Styles tab, a block with parts shows a **Style target** select: **This block**, or one of its parts. The panel then edits that part's classes. A dot marks parts that have classes.
|
|
1782
|
+
- An update merges per part: `{ "type": "update", "id": "b_list01", "partClassName": { "empty": "p-8" } }`. `null` or `""` removes a part's classes.
|
|
1783
|
+
- `validateLayout` refuses classes on a name that is not a part. The MCP tools and the assistant list each block's `parts`.
|
|
1784
|
+
- Built-in parts: the collection list's `empty` slot, `pager` (the page links' `<nav>`) and `pageLink`; the carousel's `slides` slot (the track), `controls`, `arrow`, `dot` and `pause`; the menu's `link`, `submenu` (a dropdown box), `submenuLink` and `panel` (the small-screen panel); the disclosure's `summary` and `content`; the popup's `trigger` and `content` slots, `panel` and `close`; the tabs' `list`, `tab` and `panel`; the marquee's `children` slot; the previous / next block's `previous` and `next` slots.
|
|
1533
1785
|
|
|
1534
1786
|
### HTML attributes
|
|
1535
1787
|
|
|
@@ -1551,6 +1803,119 @@ Each block can carry three HTML attributes in `block.attrs`. Edit them in the in
|
|
|
1551
1803
|
- Inside a collection list item or a repeat row, only the first item keeps the `id`. The other items leave it out, so the id stays unique on the page.
|
|
1552
1804
|
- A Payload `blocks` field cannot store them, so the Advanced tab is hidden there.
|
|
1553
1805
|
|
|
1806
|
+
## Editable classes
|
|
1807
|
+
|
|
1808
|
+
An editor changes a class once in the Styles panel, and every block that uses it changes, on every page, without a deploy. A class is a document of the plugin's **Classes** collection (slug `builder-classes`): a name such as `card`, Tailwind classes, and optional custom CSS. Blocks use it by name in their classes, next to Tailwind classes: `card md:col-span-2`.
|
|
1809
|
+
|
|
1810
|
+
It is on by default. `websiteBuilder({ classes: false })` turns it off. Options: `classes: { slug?, sheetSlug?, access?, admin?, hooks? }`. Default access: signed-in users read, create, update and delete. The site never reads the collection; it loads the compiled stylesheet.
|
|
1811
|
+
|
|
1812
|
+
**A class holds:**
|
|
1813
|
+
|
|
1814
|
+
| Field | Holds |
|
|
1815
|
+
|---|---|
|
|
1816
|
+
| `name` | The class name, without the dot. Letters, digits, `-` and `_`, starting with a letter or `_`. It must not be a Tailwind class (`flex`, `shadow`, `prose`), and it is unique. A code `@utility` name of your site is allowed: the class replaces that rule. |
|
|
1817
|
+
| `label`, `group` | Shown in the Classes field's suggestions, as for code classes: "Buttons: Primary button". |
|
|
1818
|
+
| `styles` | Tailwind classes with variants, as in a block's classes: `rounded-xl p-6 md:p-8 hover:shadow-lg`. Another class's name applies that class (`btn bg-primary`). The Styles panel edits this field. |
|
|
1819
|
+
| `css` | Custom CSS inside the class rule, for what Tailwind cannot express: layered gradients, `&::before { … }`, `&:hover { … }`, `@keyframes`. `@import`, `@theme`, `@utility` and other rules that change the design system are refused. |
|
|
1820
|
+
| `previousNames` | Names the class had when it was published before (read-only). Published pages that still use an old name keep their look until they are published again. |
|
|
1821
|
+
|
|
1822
|
+
The collection has drafts and versions, so every class has a history, and Payload's Versions screen compares and restores it.
|
|
1823
|
+
|
|
1824
|
+
### In the Styles panel
|
|
1825
|
+
|
|
1826
|
+
- **Find a class.** The **Classes** field at the top of the Styles tab shows each editable class of the block as a solid chip. A small dot on a chip means the class has unpublished changes.
|
|
1827
|
+
- **Edit a class.** Click its chip. A banner says "Editing .card" and how far a change reaches ("Changes 12 blocks on 3 pages"). Every control now reads and writes the class's `styles`. The breakpoint and state bars work as for a block: `md:` and `hover:` go into the class. Under the controls, **More classes in .card** holds the class's classes that no control shows, and a **Custom CSS** box edits its `css`. Click the chip again, or the banner's back button, to edit the block again.
|
|
1828
|
+
- **New class from these styles…** In the Classes field's "⋯" menu. It moves the block's Tailwind classes into a new class and gives the block the class. Classes the block already had stay on it. Add the class to other blocks in their Classes field: it is suggested first, with its label.
|
|
1829
|
+
- **Drafts.** A change shows on the canvas at once. It saves as a draft 0.6 s after the last change (one autosave version for a run of changes). **Ctrl+Z** undoes class changes in order with the other edits.
|
|
1830
|
+
- **Publish.** The banner's **Publish class** makes the class live on every page that uses it. Publishing a page also publishes the classes it uses that have unpublished changes (as the same user), so the live page looks like the canvas. A class the user may not update stays a draft (the server logs it).
|
|
1831
|
+
- **Rename and delete** are in the banner's **…** menu. Both dialogs say where the class is used first. **Rename** changes the class and every block that uses it, in each page's draft, through the live sessions (open editors see it at once). The old published name stays in `previousNames`, so published pages keep their look. **Delete** removes the class from every block's draft, then deletes it. Published pages lose its styles at once.
|
|
1832
|
+
- In the Payload admin, deleting a class that blocks still use is refused with the list of pages (409). Use the Styles panel's **Delete**, which removes it from the blocks first.
|
|
1833
|
+
|
|
1834
|
+
### Manage classes
|
|
1835
|
+
|
|
1836
|
+
**Manage classes…** in the Classes field's "⋯" menu opens every shared class in one list, as Webflow's style manager.
|
|
1837
|
+
|
|
1838
|
+
- **Search** by name, label or group.
|
|
1839
|
+
- **Usage.** Each row shows how many blocks and pages use the class, or "Unused". A click on a used row lists the documents: pages, posts, templates, template parts, saved sections, every collection with a layout. Each link opens that document in the builder in a new tab. The counts include unsaved edits of open builder sessions.
|
|
1840
|
+
- **Rename**, **Duplicate** and **Delete** sit on each row. Rename and Delete use the same dialogs as the Styles panel: they change every layout's draft through its live session, so an open editor keeps its unsaved edits and sees the change at once. **Duplicate** makes a draft copy named `<name>-copy`.
|
|
1841
|
+
- **Remove unused classes** deletes every class that no layout uses. The server checks again before it deletes: the latest drafts, open builder sessions and published pages of every document, under the class's name and its former names. A class that only a published page still uses stays.
|
|
1842
|
+
- Endpoint: `POST /api/builder/classes/remove-unused` returns `{ deleted, failed }`. Server helpers: `unusedClasses(req)` and `removeUnusedClasses(req)` from `payload-canvas`.
|
|
1843
|
+
|
|
1844
|
+
### Import from the site's CSS
|
|
1845
|
+
|
|
1846
|
+
**Import from the site's CSS** (the Classes field's "⋯" menu, or `POST /api/builder/classes/import`) makes a published class from each static `@utility` rule of your CSS entry and the files it imports (not packages). The `/* @canvas Group: Label */` comment gives the label and the group. `@apply` lists become `styles`; declarations and nested rules become `css`. Names that are classes already are skipped.
|
|
1847
|
+
|
|
1848
|
+
After the import, the classes are the source. Delete the `@utility` rules from your CSS: until then, Tailwind may still put them in the site's CSS (when its scanner finds the name in your source files), and properties the class does not set still come from them.
|
|
1849
|
+
|
|
1850
|
+
### On the site
|
|
1851
|
+
|
|
1852
|
+
Render `ClassesStyle` in the root layout, after `ThemeStyle`:
|
|
1853
|
+
|
|
1854
|
+
```tsx
|
|
1855
|
+
import { ClassesStyle, ThemeStyle } from 'payload-canvas/react/server'
|
|
1856
|
+
|
|
1857
|
+
<head>
|
|
1858
|
+
<ThemeStyle payload={payload} />
|
|
1859
|
+
<ClassesStyle payload={payload} />
|
|
1860
|
+
</head>
|
|
1861
|
+
```
|
|
1862
|
+
|
|
1863
|
+
- **One stylesheet for all published classes.** The classes collection's hooks compile it after every publish, unpublish and delete, with the plugin's Tailwind compile against your CSS entry, so theme tokens and plugins work. It is stored with a hash of its CSS in a hidden global (`builder-classes-sheet`). Drafts never reach it.
|
|
1864
|
+
- **Cached by the browser.** `ClassesStyle` renders `<link rel="stylesheet" href="/api/builder/classes-sheet/<hash>.css">`, served with `Cache-Control: public, max-age=31536000, immutable`. A publish makes a new hash, and the plugin clears Next's page cache (`revalidatePath('/', 'layout')`). An old hash gets the current stylesheet, cached for 60 s.
|
|
1865
|
+
- **Size.** 15 typical classes (cards, buttons, type styles, a gradient and a keyframes animation) compile to 13.9 KB, 2.4 KB gzipped, in about 50 ms. The link loads at the same time as Next's own CSS file, which also blocks the first paint, and the browser keeps it for every later page. `mode="inline"` puts the CSS in a `<style>` tag in each page instead: no extra request, but no browser cache. `origin` puts a host before the path when the site and Payload run on different hosts.
|
|
1866
|
+
- **After a deploy** with a changed CSS entry, the first request compiles the stylesheet again.
|
|
1867
|
+
- **The page's CSS leaves the classes out.** `compilePageCss` and the stored `<field>Css` compile no rule for a class name, with or without a variant prefix, so a code `@utility` with the same name never comes back on the page.
|
|
1868
|
+
- `loadClassesSheet(payload)` (`payload-canvas/react/server`, read once per request) returns the stored stylesheet: `{ hash, css, names }`.
|
|
1869
|
+
|
|
1870
|
+
### Which rule wins
|
|
1871
|
+
|
|
1872
|
+
| Order on the page | Holds |
|
|
1873
|
+
|---|---|
|
|
1874
|
+
| 1. The site's CSS (`<link>` in the head) | Your Tailwind build, with code `@utility` rules |
|
|
1875
|
+
| 2. The theme (`ThemeStyle`) | CSS variables |
|
|
1876
|
+
| 3. The classes (`ClassesStyle`) | Every published class |
|
|
1877
|
+
| 4. The page's CSS (`<style>` in the body) | The block's own Tailwind classes |
|
|
1878
|
+
|
|
1879
|
+
All the rules are in `@layer utilities` with the specificity of one class, so the later stylesheet wins:
|
|
1880
|
+
|
|
1881
|
+
- A class beats a code `@utility` rule with the same name. The class's rules never include the code rule: the compile builds each class under an internal name and renames it after the build.
|
|
1882
|
+
- A block's own Tailwind classes beat its class: `card p-2` gets the class's look with `p-2` padding.
|
|
1883
|
+
- Class rules are not limited to block elements (no `builder-css` marker): your own components can use the classes too.
|
|
1884
|
+
- Use a class without a variant prefix. Put variants into the class's styles (`md:p-8`), not before its name (`md:card` styles nothing).
|
|
1885
|
+
|
|
1886
|
+
The canvas keeps the same order: the classes' stylesheet (compiled in the browser from the latest drafts) comes before the layout's CSS.
|
|
1887
|
+
|
|
1888
|
+
### MCP tools
|
|
1889
|
+
|
|
1890
|
+
`builderMcpTools()` adds `listClasses`, `getClass`, `upsertClass` and `deleteClass`. Each takes `collection: "builder-classes"` (the default, so agents may leave it out), and the API key needs access to the classes collection.
|
|
1891
|
+
|
|
1892
|
+
- `upsertClass` creates or changes a class (a draft; `publish: true` publishes it). `newName` renames it on every page, as the Styles panel does. Without `publish`, the result lists the published pages that still show the old version (`publishedPagesWithOldVersion`).
|
|
1893
|
+
- `deleteClass` refuses a class that blocks use and lists the pages, unless `removeFromBlocks: true`. The result lists the published pages that still use the class and need publishing again.
|
|
1894
|
+
- `listBlocks` lists the editable classes with the code classes (`siteClasses`), so agents use them in `className`.
|
|
1895
|
+
- `builderMcpTools({ classes: false })` leaves the tools out; `classes: { slug }` matches a custom slug.
|
|
1896
|
+
|
|
1897
|
+
### Endpoints
|
|
1898
|
+
|
|
1899
|
+
| Endpoint | Use |
|
|
1900
|
+
|---|---|
|
|
1901
|
+
| `GET /api/builder/classes` | The classes' latest drafts, as the user may read them. The editor and the canvas use it. |
|
|
1902
|
+
| `GET /api/builder/classes/usage` | Blocks and pages per class name (`?names=a,b` limits it). |
|
|
1903
|
+
| `POST /api/builder/classes/rename` | `{ id, name }`: renames the class everywhere. |
|
|
1904
|
+
| `POST /api/builder/classes/delete` | `{ id, removeFromBlocks }` |
|
|
1905
|
+
| `POST /api/builder/classes/import` | `{ names? }`: imports code `@utility` classes. |
|
|
1906
|
+
| `GET /api/builder/classes-sheet/<hash>.css` | The site's stylesheet. Public. |
|
|
1907
|
+
|
|
1908
|
+
Style edits use Payload's own REST API (`PATCH /api/builder-classes/:id?draft=true&autosave=true`), so access, hooks, validation and versions apply. The server actions are exported from `payload-canvas` for scripts: `upsertClass`, `publishClass`, `renameClass`, `deleteClass`, `importSiteClasses`, `classUsage`, `storeClassesSheet`, `loadClassesSheet`.
|
|
1909
|
+
|
|
1910
|
+
### Limits
|
|
1911
|
+
|
|
1912
|
+
- Other people's class changes reach your editor when its window gets the focus again. Canvases in your own browser follow your changes at once.
|
|
1913
|
+
- Section thumbnails keep their picture until the section, the theme or the blocks change.
|
|
1914
|
+
- Usage counts read every builder layout (one query per collection: latest drafts and open sessions). This is fine for hundreds of pages.
|
|
1915
|
+
- The in-editor AI assistant's style hints list the code classes only; the MCP tools list both.
|
|
1916
|
+
- Classes are the same in every locale.
|
|
1917
|
+
- The new collection and global need a migration in production: run `pnpm payload migrate:create` when you prepare the release.
|
|
1918
|
+
|
|
1554
1919
|
## Animations
|
|
1555
1920
|
|
|
1556
1921
|
Editors and the AI can add motion to any block without code: an entrance when the block scrolls into view, hover and press effects, a scroll effect such as parallax, and a loop. The site plays them with the [`motion`](https://motion.dev) package (its DOM API). Animations are data, not classes.
|
|
@@ -1703,6 +2068,25 @@ Other frontends: `loadTheme(payload)` from `payload-canvas/react/server` returns
|
|
|
1703
2068
|
|
|
1704
2069
|
**Styles panel.** The color swatches read the canvas, so they show the theme's colors. The Font list shows the theme's families ("Inter", not `var(--font-sans)`).
|
|
1705
2070
|
|
|
2071
|
+
### Design variables
|
|
2072
|
+
|
|
2073
|
+
Named colors, sizes and fonts that blocks and classes use by name, as Webflow's variables. Change a variable once in **Theme > Variables**, and every page that uses it changes.
|
|
2074
|
+
|
|
2075
|
+
| Type | Value | Classes | CSS variable |
|
|
2076
|
+
|---|---|---|---|
|
|
2077
|
+
| Color | a hex color or any CSS color | `bg-brand`, `text-brand/80`, `border-brand`, `from-brand` … | `--color-brand` |
|
|
2078
|
+
| Size | a CSS length: `24px`, `1.5rem`, `clamp(1rem, 4vw, 3rem)` | `p-gutter`, `mt-gutter`, `gap-gutter`, `w-gutter`, `-mx-gutter` … | `--spacing-gutter` |
|
|
2079
|
+
| Font | a Google Fonts family (the site loads it) | `font-display` | `--font-display` |
|
|
2080
|
+
|
|
2081
|
+
- **Names**: lower-case letters, digits and single dashes, unique across all types. Names the theme already uses (`primary`, `background`, `sans`, `full`, palette shades like `red-500`) are refused.
|
|
2082
|
+
- **Dark mode.** Colors and sizes can have a **Dark mode** value. The theme had no dark mode before, so the variables follow the `.dark` class (Tailwind's class strategy): the dark value applies on an element with `dark` and everything inside it. `ThemeStyle` writes `:root:root.dark, :root:root .dark { --color-brand: … }`. With the `@custom-variant dark (&:is(.dark *))` of the starter, `dark:` classes and the variables switch together.
|
|
2083
|
+
- **How it works.** `ThemeStyle` writes the values as CSS variables. Both Tailwind compiles (the save hook and the canvas) add a `@theme inline reference { --color-brand: var(--color-brand); … }` block after your CSS entry, so the classes exist and read the variable. The compiled CSS holds no values: a new value changes every page at once, without a new compile. Adding, renaming or deleting a variable changes which classes exist; the next save or render compiles again (the stored page CSS and the classes stylesheet carry a hash of the names).
|
|
2084
|
+
- **Classes.** Variables work in editable classes too: `bg-brand p-gutter` in a class's styles, `var(--color-brand)` in its custom CSS.
|
|
2085
|
+
- **Styles panel.** The color picker lists the color variables first, under **Variables**, with a swatch. The spacing, size and font suggestions list their variables first. After a theme save, open editors and canvases load the variables again.
|
|
2086
|
+
- **Renaming or deleting a variable in use** shows a warning in the theme form before you save: which blocks and classes still use the old name, with links to the pages. The old classes stop working after the save.
|
|
2087
|
+
- **AI and MCP.** The assistant's system prompt and the MCP `listBlocks` tool list the variables with their values and example classes. `GET /api/builder/style-tokens` returns them as `variables`. `GET /api/builder/theme/variables/usage` returns where each variable is used.
|
|
2088
|
+
- Helpers in `payload-canvas/theme`: `variableTokens`, `variablesThemeCss`, `variableNameProblem`, `variableValueProblem`, `textUsesVariable`.
|
|
2089
|
+
|
|
1706
2090
|
**Options:**
|
|
1707
2091
|
|
|
1708
2092
|
```ts
|
|
@@ -1746,38 +2130,40 @@ websiteBuilder({
|
|
|
1746
2130
|
|
|
1747
2131
|
What the plugin adds:
|
|
1748
2132
|
|
|
1749
|
-
- A templates collection (`builder-templates`) with drafts and the builder. Each template has a target collection (`targetCollection`), a "default for this collection" checkbox (`isDefault`), optional `conditions` and a sample document for the editor preview (`previewDocument`).
|
|
2133
|
+
- A templates collection (`builder-templates`) with drafts and the builder. Each template has a target collection (`targetCollection`), a "default for this collection" checkbox (`isDefault`), optional `conditions` with a `priority`, and a sample document for the editor preview (`previewDocument`).
|
|
1750
2134
|
- A `template` relationship in the sidebar of every document in a collection with `templates: true`.
|
|
1751
2135
|
|
|
1752
2136
|
Which template a document uses:
|
|
1753
2137
|
|
|
1754
2138
|
1. Its own `template`.
|
|
1755
|
-
2. Else the
|
|
1756
|
-
3. Else the
|
|
2139
|
+
2. Else the template with the highest `priority` whose `conditions` match the document. On equal priority the older template (by creation date) wins. The name never counts, so renaming a template does not change which one wins.
|
|
2140
|
+
3. Else the most recently updated default template of its collection.
|
|
1757
2141
|
4. Else none.
|
|
1758
2142
|
|
|
1759
2143
|
Only published templates count (all templates in draft mode). Templates with an empty layout are skipped.
|
|
1760
2144
|
|
|
1761
2145
|
#### Template conditions
|
|
1762
2146
|
|
|
1763
|
-
`conditions` is a Payload `where` query against the document,
|
|
2147
|
+
`conditions` is a Payload `where` query against the document. Use it to give some documents their own default layout, for example featured products or posts in one category. The template's edit form shows it as condition rows: a field of the target collection, an operator and a value, in "or" groups of AND-ed rows (the same rows as a collection list's `where`). A date value can be relative to now (`"$now-30d"`). **Edit as JSON** takes any query, for example:
|
|
1764
2148
|
|
|
1765
2149
|
```json
|
|
1766
|
-
{ "
|
|
1767
|
-
{ "
|
|
2150
|
+
{ "category": { "equals": "news" } }
|
|
2151
|
+
{ "or": [{ "featured": { "equals": true } }, { "price": { "greater_than": 100 } }] }
|
|
1768
2152
|
```
|
|
1769
2153
|
|
|
1770
|
-
- `loadTemplate` asks Payload whether the document matches
|
|
1771
|
-
-
|
|
2154
|
+
- `loadTemplate` reads the collection's templates once (without their layouts). When some have conditions, it asks Payload whether the document matches, one query per template with conditions, all at the same time, on the stored document (the latest draft in draft mode). Without conditions it runs no such query. Then it loads only the chosen template. Every operator and field path of a Payload query works, for example `equals`, `not_equals`, `in`, `not_in`, `exists`, `greater_than`, `less_than_equal`, `and`, `or` and relationship paths such as `category.slug`.
|
|
2155
|
+
- `priority` (a number in the sidebar, default 0, shown once the template has conditions) orders templates whose conditions match the same document: the highest wins. Equal priority: the older template wins.
|
|
1772
2156
|
- Empty conditions (`null` or `{}`) never match. A template with conditions can also be the default: then it is still the fallback for every document.
|
|
1773
2157
|
- A query that Payload refuses (an unknown field) counts as no match, and the error goes to the Payload log.
|
|
1774
|
-
- The editor's notice on an empty document ("This page uses a template")
|
|
2158
|
+
- The editor's notice on an empty document ("This page uses a template") runs the same code on the server (`GET /api/builder/live/:collection/:id/template`), with published templates and the document's latest draft.
|
|
2159
|
+
- The conditions field is a custom admin component (`payload-canvas/client#TemplateConditionsField`). After you add `templates: true` to a collection, run `payload generate:importmap`.
|
|
1775
2160
|
|
|
1776
2161
|
### Bindings and dynamic blocks
|
|
1777
2162
|
|
|
1778
2163
|
- A **binding** connects a block prop to a document field: `bindings: { "text": "title", "image": "author.avatar" }`. Paths are dot paths from the document root. At render time the prop takes the document's value. A missing value falls back to the prop's own value. In the editor, the binding picker lists only compatible fields of the target collection, including one relationship hop.
|
|
1779
2164
|
- The **Field** block (`field`) shows one field of the document by path, rendered by its type: rich text, an upload as an image, a date, a relationship's title, or text. Use it for the post body.
|
|
1780
|
-
- The **Collection list** block (`collectionList`) lists the latest documents of a collection (`collection`, `limit`, `sort`, `excludeCurrent`, `offset`, `depth`, and the filters `filterField`, `filterBy`, `where` and `queryFilters` below). Its `item` slot is the design of one item and repeats for every document. Its `empty` slot shows instead when no document matches, for example a text "
|
|
2165
|
+
- The **Collection list** block (`collectionList`) lists the latest documents of a collection (`collection`, `limit`, `sort`, `excludeCurrent`, `offset`, `depth`, and the filters `filterField`, `filterBy`, `where` and `queryFilters` below). Its `item` slot is the design of one item and repeats for every document. Its `empty` slot shows instead when no document matches, for example a text "No posts yet". Blocks in the item bind to the item's fields, for example a heading with `bindings: { "text": "title" }` and a link with `bindings: { "link": "$url" }` (the item's URL from the collection's `url` option). The block offers the collections with a `url`; add data collections without pages (testimonials, team members) with the plugin's `listCollections` option. The site shows published documents only. It works on normal pages too, not only in templates.
|
|
2166
|
+
- In the inspector, the fields show under the headings **Filter**, **Sort and count** and **Pages**. **Sort** is a select of the collection's fields with a direction ("Newest first", "A to Z") and **Random order**. It stores the same `sort` text (`-publishedAt`, `$random`). Your own blocks can use the same controls: `admin.custom.builderSort: { collectionField: 'collection' }` on a text field, and `admin.custom.builderHeading: 'Filter'` for a heading above a field.
|
|
1781
2167
|
- `offset` skips documents after the sort (at most 100).
|
|
1782
2168
|
- `depth` is `"1"` (default) or `"2"`: how deep the related documents of each item load. Use `"2"` to reach, for example, `categories.image`.
|
|
1783
2169
|
- The **Repeat** block (`repeat`) repeats its `item` slot per row of an array or hasMany field. See "Repeat the rows of a field" below.
|
|
@@ -1788,43 +2174,72 @@ Only published templates count (all templates in draft mode). Templates with an
|
|
|
1788
2174
|
| --- | --- | --- |
|
|
1789
2175
|
| A path | `"title"`, `"author.name"` | The field's value. |
|
|
1790
2176
|
| `$url` | `{ "link": "$url" }` | The document's page URL (the collection's `url` option). |
|
|
1791
|
-
| `<path>.$url` | `{ "link": "categories.0.$url" }` | The page URL of a related document: the first category of a
|
|
1792
|
-
| A fallback chain | `"
|
|
1793
|
-
| Formatters | `"publishedAt\|date:en-
|
|
1794
|
-
| A template string | `{ "text": "
|
|
1795
|
-
| `$visible` | `{ "$visible": "availableToday" }` | Not a prop: the block shows only when the condition holds. See below. |
|
|
2177
|
+
| `<path>.$url` | `{ "link": "categories.0.$url" }` | The page URL of a related document: the first category of a post, `venue.city.$url` through two relationships. See "URLs of related documents" below. |
|
|
2178
|
+
| A fallback chain | `"subtitle\|title"` | The first path that has a value. |
|
|
2179
|
+
| Formatters | `"publishedAt\|date:en-GB:Europe/London"`, `"price\|currency:EUR"`, `"summary\|truncate:160"` | Text. See the table below. Put them after the paths: `"subtitle\|title\|uppercase"`. |
|
|
2180
|
+
| A template string | `{ "text": "Read about {{title}}" }`, `"From {{price\|currency:EUR}}"` | Text with each `{{expression}}` filled in. A missing expression becomes empty. When every expression is missing, the prop keeps its own value. |
|
|
1796
2181
|
| `$item`, `$index` | `{ "image": "$item" }`, `"{{$index}}."` | Inside a repeat: the row value itself. Inside a list or repeat item: the item number, from 1. |
|
|
1797
2182
|
| `$parent.<path>` | `"$parent.name"` | Inside a list or repeat item: the enclosing document (the page's document, the listed document, or the outer row). |
|
|
1798
2183
|
| `$page.<path>` | `"$page.title"` | Anywhere: the page's own document, also inside list and repeat items. |
|
|
1799
2184
|
|
|
1800
|
-
|
|
2185
|
+
The syntax stops here: paths, `|` fallbacks, formatters and `{{ }}` templates. Nothing else will be added.
|
|
1801
2186
|
|
|
1802
|
-
|
|
1803
|
-
| --- | --- |
|
|
1804
|
-
| `"field"` | the field has a value. `false`, `""`, `null` and `[]` count as empty. |
|
|
1805
|
-
| `"!field"` | the field is empty. |
|
|
1806
|
-
| `"field=value"` | the field equals the value. For a list (hasMany), any item or document id matches. |
|
|
1807
|
-
| `"field!=value"` | the field does not equal the value. |
|
|
1808
|
-
| `"field>3"`, `"field>=3"`, `"field<3"`, `"field<=3"` | the field is a number (or a numeric text) and the comparison holds. Any other value fails. |
|
|
1809
|
-
| `"field#>=3"` | `field#` is the number of items: a list's length, `0` for an empty value, `1` for any other value. It works with every test above, for example `"galleryImages#>=3"` (at least 3 photos), `"services#=0"` or `"!galleryImages#"`. |
|
|
2187
|
+
Formatters. In the inspector, a bound text prop and the Field block have a **Format** select with an input per argument, so editors never type them.
|
|
1810
2188
|
|
|
1811
|
-
|
|
2189
|
+
| Formatter | Arguments | Example | Gives |
|
|
2190
|
+
| --- | --- | --- | --- |
|
|
2191
|
+
| `date` | language, time zone (default `en`, UTC) | `date:en-GB:Europe/London` | `11 Sept 2026` |
|
|
2192
|
+
| `number` | language | `number` | `1,200` |
|
|
2193
|
+
| `currency` | currency code (default `USD`), language | `currency:EUR` | `€1,200` (whole amounts have no cents) |
|
|
2194
|
+
| `uppercase`, `lowercase` | none | `uppercase` | `DESK LAMP` |
|
|
2195
|
+
| `truncate` | length, then `words` to count words | `truncate:160`, `truncate:25:words` | The plain text (rich text too) cut to 160 characters (on a whole word) or 25 words, with `…` |
|
|
2196
|
+
| `readingTime` | words per minute (default 200), text after the number (default `min read`) | `readingTime`, `readingTime:200:Min. Lesezeit` | `5 min read`: the time to read the text (rich text too), rounded up, at least 1 minute. Nothing for a text without words. |
|
|
2197
|
+
|
|
2198
|
+
After the first part of an expression, a name that is a formatter is always a formatter. So `"title|date"` formats `title`; it never falls back to a field called `date`. A field with a formatter's name works as the first path only: `"date|title"`.
|
|
1812
2199
|
|
|
1813
2200
|
URLs of related documents (`<path>.$url`):
|
|
1814
2201
|
|
|
1815
2202
|
- The URL comes from your `resolveLink`, called as for a link to that document: `{ type: 'reference', reference: { relationTo, value: doc } }`. So `resolveLink` is the site's "URL of a document" function, for pages and for `$url`.
|
|
1816
|
-
- The renderer must know the related collection. A `{ relationTo, value }` value (a relationship to several collections) names it. For a relationship to one collection,
|
|
1817
|
-
|
|
1818
|
-
```tsx
|
|
1819
|
-
const relations = bindingRelations(payload.config.collections)
|
|
1820
|
-
const loaded = await loadLayoutData(layout, blocks, payload, { context, relations, resolveLink })
|
|
1821
|
-
<RenderLayout layout={loaded} blocks={blocks} context={context} relations={relations} resolveLink={resolveLink} />
|
|
1822
|
-
```
|
|
1823
|
-
|
|
2203
|
+
- The renderer must know the related collection. A `{ relationTo, value }` value (a relationship to several collections) names it. For a relationship to one collection, `loadLayoutData` reads it from the Payload config (`bindingRelations` in `payload-canvas/core` maps each relationship and upload field to its collection, in groups, named tabs and arrays too) and gives it to the collection lists and repeats whose items need it. You pass nothing. The plugin sends the same map to the canvas.
|
|
1824
2204
|
- The related document must be loaded (list items load with `depth: 1`; use `depth: "2"` on the list for a relationship of a related document). An id alone gives no URL, and the prop keeps its own value.
|
|
1825
2205
|
- `$parent.` and `$page.` paths do not take `.$url`.
|
|
1826
2206
|
|
|
1827
|
-
|
|
2207
|
+
Expressions are not checked against the collection's fields when you publish. The inspector shows a fallback chain or a template string as text with a preview of its value. Add or change one in the layout JSON or through the MCP tools.
|
|
2208
|
+
|
|
2209
|
+
#### Show a block only when conditions match
|
|
2210
|
+
|
|
2211
|
+
A block in a template, a collection list item or a repeat row can show only when its document matches conditions. In the inspector, **Show only when** at the end of the Content tab has condition rows: a field, an operator and a value. The field select lists the fields of the block's document (the template's collection, the listed collection, or the row), else the collection's fields from the Payload config. The rows in a group must all match. **Add "or" group** adds another group, and one matching group is enough. The block stores them as `visibility`:
|
|
2212
|
+
|
|
2213
|
+
```json
|
|
2214
|
+
{
|
|
2215
|
+
"id": "b_sale01",
|
|
2216
|
+
"type": "text",
|
|
2217
|
+
"props": { "text": "On sale" },
|
|
2218
|
+
"visibility": {
|
|
2219
|
+
"match": "any",
|
|
2220
|
+
"conditions": [
|
|
2221
|
+
{ "field": "onSale", "operator": "equals", "value": true },
|
|
2222
|
+
{ "field": "price", "operator": "less_than", "value": 20 }
|
|
2223
|
+
]
|
|
2224
|
+
}
|
|
2225
|
+
}
|
|
2226
|
+
```
|
|
2227
|
+
|
|
2228
|
+
| Operator | Shows the block when |
|
|
2229
|
+
| --- | --- |
|
|
2230
|
+
| `is_set`, `is_empty` | the field has a value, or not. `false`, `""`, `null` and `[]` count as empty. No `value`. |
|
|
2231
|
+
| `equals`, `not_equals` | the field equals the value, or not. For a list (hasMany), any item or document id matches. A checkbox without a value counts as `false`. |
|
|
2232
|
+
| `in`, `not_in` | the field equals one of the values, or none (`value` is a list). |
|
|
2233
|
+
| `greater_than`, `greater_than_equal`, `less_than`, `less_than_equal` | the field and the value are numbers (or numeric texts) or dates, and the comparison holds. Any other value fails. |
|
|
2234
|
+
| `like`, `contains` | the field's text holds every word of the value, or the value, in any case. |
|
|
2235
|
+
|
|
2236
|
+
- `field` is a path of the document, or `$index`, `$item`, `$parent.<path>` and `$page.<path>`.
|
|
2237
|
+
- `"count": true` compares the number of items of the field instead of its value: a list's length, `0` for an empty value, `1` for any other value. For example `{ "field": "gallery", "operator": "greater_than_equal", "value": 3, "count": true }` (at least 3 photos). The inspector offers it under "Number of items" as "Gallery (count)", with operators such as "has at least".
|
|
2238
|
+
- `"valueField"` compares with another field of the same document instead of a fixed `value`: `{ "field": "salePrice", "operator": "less_than", "valueField": "price" }`. A condition has `value` or `valueField`, never both. In the inspector, pick **Other field** next to the value.
|
|
2239
|
+
- `match` is `"all"` (the default, left out) or `"any"`. With `"any"`, an entry can be a group `{ "all": [conditions] }` that matches when all its conditions match. So `{ "match": "any", "conditions": [{ "all": [a, b] }, c] }` means "(a and b) or c". This is how the inspector stores "or" groups.
|
|
2240
|
+
- The inspector offers the operators that fit the field's type ("is after" for dates, "contains" for text, "includes" for hasMany fields) and a value input of the same type: a select's options, checked or not checked, a number, a date, or a document picker for relationships and uploads.
|
|
2241
|
+
- A block that fails renders nothing on the site, and lists inside it load no documents. On the canvas it shows dimmed, like a hidden block. Without a current document (a normal page, outside list and repeat items) the conditions are not checked, and the block shows. The MCP tools return a `no-effect` warning for them there.
|
|
2242
|
+
- The outline marks a block whose condition reads a field the collection does not have.
|
|
1828
2243
|
|
|
1829
2244
|
#### Filter a collection list
|
|
1830
2245
|
|
|
@@ -1832,21 +2247,23 @@ A collection list can show only the documents related to the current document (t
|
|
|
1832
2247
|
|
|
1833
2248
|
| `filterBy` | The list shows | Payload query | Example |
|
|
1834
2249
|
| --- | --- | --- | --- |
|
|
1835
|
-
| `current` (default) | documents whose `filterField` holds the current document | `{ [filterField]: { in: [doc.id] } }` | On a
|
|
1836
|
-
| `shared` | documents whose `filterField` shares a value with the current document's own `filterField` | `{ [filterField]: { in: values } }` |
|
|
1837
|
-
| `linked` | the documents that the current document's `filterField` points to | `{ id: { in: values } }` | On a
|
|
2250
|
+
| `current` (default) | documents whose `filterField` holds the current document | `{ [filterField]: { in: [doc.id] } }` | On a category template: the posts whose `categories` include this category. |
|
|
2251
|
+
| `shared` | documents whose `filterField` shares a value with the current document's own `filterField` | `{ [filterField]: { in: values } }` | Related posts with a `category` in common. Products with the same `brand` text. |
|
|
2252
|
+
| `linked` | the documents that the current document's `filterField` points to | `{ id: { in: values } }` | On a post template: the post's `authors`. |
|
|
1838
2253
|
|
|
2254
|
+
- In the inspector this is one select, **Related to this page**, under the **Filter** heading. It lists the fields that relate the two collections in words ("Categories links to this page") and sets both props. It shows in templates, or when a filter is already set. Your own block gets it with `admin: { custom: { builderRelated: { collectionField: 'collection', modeField: 'filterBy' } } }` on the text field that stores the field name. `modeField` names the select that stores the mode.
|
|
1839
2255
|
- `values` are read from the current document with `getByPath`. Populated documents (`{ id }`), `{ relationTo, value }` pairs, strings and numbers all work, one value or many.
|
|
1840
2256
|
- With `shared` or `linked`, a current document without values shows an empty list. The plugin sends no query.
|
|
1841
|
-
- On a normal page (no current document), `filterField`
|
|
1842
|
-
- `where` is a static Payload `where` query, AND-ed with the filter. For example `{ "featured": { "equals": true } }` or `{ "
|
|
1843
|
-
- The inspector edits `where` as condition rows: a field of the chosen collection, an operator (
|
|
1844
|
-
-
|
|
2257
|
+
- On a normal page (no current document), a list with `filterField` shows nothing (its `empty` slot). The plugin sends no query. The same holds on the canvas for a template without a sample document; the editor still shows the item design once.
|
|
2258
|
+
- `where` is a static Payload `where` query, AND-ed with the filter. For example `{ "featured": { "equals": true } }` or `{ "category": { "equals": "news" } }`. Only a plain object counts; anything else is ignored.
|
|
2259
|
+
- The inspector edits `where` as condition rows: a field of the chosen collection, an operator in plain words ("is", "is any of", "is after", "has all the words", "is set") and a value. The operators and the value input follow the field's type: a select's options, checked or not checked, a number, a date, or a document picker (ids are stored). Rows in a group are AND-ed. **Add "or" group** stores `{ "or": [group, group] }`. `is set` and `is empty` store Payload's `exists`. **Edit as JSON** switches to the raw query. A query the rows cannot show (a group inside a group, an unknown operator) opens as JSON, so no part of it is lost. The stored value is the same Payload `where` object either way.
|
|
2260
|
+
- A row's value can also come from elsewhere (the select next to the value): **Relative date** (`"$now-30d"`, see below), **URL parameter** (`"$query.<param>"`), and in a template **Page field** (`"$page.<path>"`, a field of the document the template renders; "This page" is its id). `listQueries` reads them when the list loads, on the site and on the canvas alike. Example: `{ "category": { "equals": "$page.category" } }` on a post template lists the posts of the same category. A page field with several values (hasMany) turns `equals` into `in`. A page field without a value makes the list empty, except with `not_equals` and `not_in`, which are then left out. A URL parameter that is not in the URL leaves its condition out, as `queryFilters` do. The canvas has no URL, so it leaves URL conditions out. In an "or", a group that matches nothing or has nothing left does not count. A JSON field of your own block gets the rows with `admin: { custom: { builderWhere: { collectionField: 'collection' } } }`, where `collectionField` names the sibling prop that holds the collection slug.
|
|
2261
|
+
- Date values in `where`, `queryFilters` and a template's `conditions` can be tokens: `"$now"`, `"$now-30d"`, `"$now+12h"` (units `d` and `h`). They become ISO dates, rounded down to the minute. Example: `{ "createdAt": { "greater_than": "$now-30d" } }` lists documents from the last 30 days.
|
|
1845
2262
|
|
|
1846
2263
|
```json
|
|
1847
2264
|
{
|
|
1848
2265
|
"type": "collectionList",
|
|
1849
|
-
"props": { "collection": "
|
|
2266
|
+
"props": { "collection": "posts", "filterField": "categories", "filterBy": "current", "where": { "featured": { "equals": true } } }
|
|
1850
2267
|
}
|
|
1851
2268
|
```
|
|
1852
2269
|
|
|
@@ -1854,25 +2271,29 @@ Lists load with the visitor's access (`overrideAccess: false`). The site (`loadL
|
|
|
1854
2271
|
|
|
1855
2272
|
#### Filter by the URL query
|
|
1856
2273
|
|
|
1857
|
-
`queryFilters` filters a list by the page's URL query
|
|
2274
|
+
`queryFilters` filters a list by the page's URL query. Each URL parameter has one of two forms:
|
|
2275
|
+
|
|
2276
|
+
- A field path (the usual case): `{ "category": "category" }`. The field equals the URL value, so `?category=news` lists the documents whose `category` is `news`. The value goes to Payload as it is, so a relationship field takes a document id (`?author=12`), and `tags.slug` reaches into related documents.
|
|
2277
|
+
- Values to `where` queries (for anything else): `{ "<param>": { "<value>": where } }`. Each `param=value` in the URL adds its `where`; unknown values are ignored.
|
|
1858
2278
|
|
|
1859
2279
|
```json
|
|
1860
2280
|
{
|
|
1861
2281
|
"type": "collectionList",
|
|
1862
2282
|
"props": {
|
|
1863
|
-
"collection": "
|
|
2283
|
+
"collection": "posts",
|
|
1864
2284
|
"queryFilters": {
|
|
1865
|
-
"
|
|
1866
|
-
"
|
|
1867
|
-
"
|
|
2285
|
+
"category": "category",
|
|
2286
|
+
"tag": "tags.slug",
|
|
2287
|
+
"age": { "recent": { "publishedAt": { "greater_than": "$now-30d" } } }
|
|
1868
2288
|
}
|
|
1869
2289
|
}
|
|
1870
2290
|
}
|
|
1871
2291
|
```
|
|
1872
2292
|
|
|
1873
|
-
-
|
|
1874
|
-
- Several values of one param are OR-ed: `?
|
|
1875
|
-
- Params are AND-ed with each other and with the list's other filters. Unknown params
|
|
2293
|
+
- `?category=news&age=recent` lists the news posts of the last 30 days.
|
|
2294
|
+
- Several values of one param are OR-ed: `?tag=css,react` or `?tag=css&tag=react`.
|
|
2295
|
+
- Params are AND-ed with each other and with the list's other filters. Unknown params are ignored.
|
|
2296
|
+
- The inspector edits the field-path form as rows: a URL parameter and a field of the chosen collection. **Edit as JSON** switches to the raw value. A value with the full form opens as JSON. A JSON field of your own block gets the rows with `admin: { custom: { builderQueryFilters: { collectionField: 'collection' } } }`.
|
|
1876
2297
|
- Pass the query to `loadLayoutData`: `loadLayoutData(layout, blocks, payload, { query: await searchParams })`. It takes `URLSearchParams` or a Next.js `searchParams` object. Without `query`, the filters are off.
|
|
1877
2298
|
- The canvas has no URL query, so it shows the list without these filters.
|
|
1878
2299
|
- Filtered URLs show the same page with fewer items. Set `robots: { index: false, follow: true }` (`noindex, follow`) in the route's metadata when the URL has a filter param, so search engines index only the unfiltered page.
|
|
@@ -1886,12 +2307,13 @@ Lists load with the visitor's access (`overrideAccess: false`). The site (`loadL
|
|
|
1886
2307
|
| `paginate: "pages"` | Shows `limit` documents per page and page links under the items: `?page=2`, `?page=3` (`PAGE_PARAM`). The links keep the rest of the URL query (filters, other lists' pages), and page 1 has no page param. Seven pages or fewer: a link to each. More: the first, the last and the pages next to the current one, with a gap between (`1 … 4 5 6 … 20`; `pageWindow`). Pass the query to `loadLayoutData` (`query`), as for `queryFilters`, and the page's path (`path: '/guides'`): the links then start with the path, and page 1 is the bare path (`/guides`). Without `path` the links are relative, and page 1 with no other query values is `?`. `offset` does not apply. |
|
|
1887
2308
|
| `pageParam` | The URL parameter of the page number. Empty: `page`. Give each paginated list on one page its own (`reviewsPage`), so they page apart. Letters, digits, `_` and `-`; any other value counts as `page`. |
|
|
1888
2309
|
| `pagerLabel` | The name of the page links for screen readers (`aria-label` of the `<nav>`). Localized, default "Pages". |
|
|
1889
|
-
| `pagerClassName` | Classes of the `<nav>` around the links. Default `flex flex-wrap gap-2`. A gap is `<span data-page-gap aria-hidden="true">…</span>`: style it with `[&_[data-page-gap]]:` classes. |
|
|
1890
|
-
| `pageLinkClassName` | Classes of each page link. The current page has `aria-current="page"`, so `aria-[current=page]:font-bold` styles it. |
|
|
1891
2310
|
|
|
2311
|
+
- Style the links as parts (`partClassName`, the **Style target** select): `pager` is the `<nav>` around the links (a new list starts with `flex flex-wrap gap-2`), `pageLink` is each link. The current page has `aria-current="page"`, so `aria-[current=page]:font-bold` styles it. A gap is `<span data-page-gap aria-hidden="true">…</span>`: style it with `[&_[data-page-gap]]:` classes on `pager`.
|
|
2312
|
+
- With page links, the list renders a wrapper without classes that holds the items (with the block's classes) and then the `<nav>`, so a grid of items never takes the pager as a cell.
|
|
1892
2313
|
- The page links are plain `<a href>` links, so search engines can crawl every page. Give `?page=N` pages their own canonical URL (with the page), not the first page.
|
|
1893
2314
|
- Two paginated lists on one page share `page` unless one sets its own `pageParam`.
|
|
1894
2315
|
- On the canvas a paginated list shows page 1 with its links.
|
|
2316
|
+
- Lists inside hidden blocks (hidden by hand or by visibility conditions) send no query on the site. The canvas shows hidden blocks dimmed, so it loads their lists.
|
|
1895
2317
|
- After `loadLayoutData`, a paginated list carries its links as the runtime `$pages` prop (`LIST_PAGES_PROP`, type `ListPages`). A custom collection list component can render them its own way.
|
|
1896
2318
|
- Not built: a "Load more" button. Use the page links.
|
|
1897
2319
|
|
|
@@ -1910,11 +2332,11 @@ const itemLists = loadedLists(layout).map((list) => ({
|
|
|
1910
2332
|
|
|
1911
2333
|
#### Repeat the rows of a field
|
|
1912
2334
|
|
|
1913
|
-
The **Repeat** block (`repeat`) repeats its `item` slot once per row of a list field of the current document. Use it for an array field (FAQs `faqs: [{ question, answer }]`,
|
|
2335
|
+
The **Repeat** block (`repeat`) repeats its `item` slot once per row of a list field of the current document. Use it for an array field (FAQs `faqs: [{ question, answer }]`, plans `plans: [{ name, price }]`), a hasMany upload (a gallery), a hasMany relationship (the authors of a post) or a hasMany text or select field (tags).
|
|
1914
2336
|
|
|
1915
2337
|
| Prop | Type | What it does |
|
|
1916
2338
|
| --- | --- | --- |
|
|
1917
|
-
| `path` | text, required | The field, as a dot path in the current document, for example `faqs` or `
|
|
2339
|
+
| `path` | text, required | The field, as a dot path in the current document, for example `faqs` or `gallery`. `$parent.` and `$page.` paths work too. |
|
|
1918
2340
|
| `limit` | number | The most rows to show. Empty shows every row. |
|
|
1919
2341
|
| `offset` | number | Rows to skip at the start. `1` skips the first photo. |
|
|
1920
2342
|
| `collection` | text (a select of the collections with a `url` when the plugin knows them) | For a relationship field: the related collection, so `$url` links to each document. A `{ relationTo, value }` row names its own collection. |
|
|
@@ -1931,7 +2353,7 @@ Blocks in the `item` slot bind to the **row**:
|
|
|
1931
2353
|
```json
|
|
1932
2354
|
{
|
|
1933
2355
|
"type": "repeat",
|
|
1934
|
-
"props": { "path": "
|
|
2356
|
+
"props": { "path": "gallery", "offset": 1 },
|
|
1935
2357
|
"slots": { "item": [{ "type": "image", "bindings": { "image": "$item" } }] }
|
|
1936
2358
|
}
|
|
1937
2359
|
```
|
|
@@ -1963,7 +2385,7 @@ return <RenderLayout layout={layout} css={found.css} context={context} blocks={b
|
|
|
1963
2385
|
```
|
|
1964
2386
|
|
|
1965
2387
|
- `loadTemplate(payload, { collection, doc, templatesSlug?, draft? })` returns `{ template, layout, css }` or `null`. Without `draft` it uses published templates only. The document needs its `id` for template conditions.
|
|
1966
|
-
- `loadLayoutData(layout, blocks, payload, { draft, context, resolveLink, user, query })` resolves bindings and Field blocks against `context`, gives repeats their rows, loads collection lists, and loads upload and relationship props. `query` is the request's URL query for `queryFilters`. Pass the same `context` to `RenderLayout`.
|
|
2388
|
+
- `loadLayoutData(layout, blocks, payload, { draft, context, resolveLink, user, query })` resolves bindings, visibility conditions and Field blocks against `context`, gives repeats their rows, loads collection lists, and loads upload and relationship props. `query` is the request's URL query for `queryFilters`. Pass the same `context` to `RenderLayout`.
|
|
1967
2389
|
- `getByPath(doc, path)` and `resolveBindings(layout, context, blocks)` from `payload-canvas/core` do the same work for a custom renderer.
|
|
1968
2390
|
|
|
1969
2391
|
## References and Used in
|
|
@@ -2034,7 +2456,7 @@ buildConfig({
|
|
|
2034
2456
|
})
|
|
2035
2457
|
```
|
|
2036
2458
|
|
|
2037
|
-
**Which props translate.** A prop translates when its field config says `localized: true`, as in Payload. A group or array that holds a localized field translates as a whole. The default blocks mark their text as localized: heading, text, rich text, button label, image alt text, list items,
|
|
2459
|
+
**Which props translate.** A prop translates when its field config says `localized: true`, as in Payload. A group or array that holds a localized field translates as a whole. The default blocks mark their text as localized: heading, text, rich text, button label, image alt text, list items, menu links and name, and the field block's fallback. Images, links, numbers, selects and checkboxes are shared. Add `localized: true` to the fields of your own blocks. Without Payload localization, `localized` does nothing.
|
|
2038
2460
|
|
|
2039
2461
|
**How it is stored.** The default language stays in `props`. Each other language keeps only its own values in `locales`:
|
|
2040
2462
|
|
|
@@ -2119,6 +2541,20 @@ The default model is `openai/gpt-6-luna`: cheap and good at tool calls. Pick ano
|
|
|
2119
2541
|
|
|
2120
2542
|
Without an adapter, or without a key, the panel shows a setup card. The card says what to set.
|
|
2121
2543
|
|
|
2544
|
+
### API keys in the admin
|
|
2545
|
+
|
|
2546
|
+
An admin can also paste the API key in the admin, without a deploy. The plugin adds an **AI settings** global (slug `builder-ai-settings`) when `ai` is set.
|
|
2547
|
+
|
|
2548
|
+
- **Precedence.** A key set there wins over the key in the adapter options (your env). Not set, or cleared: the adapter uses its own key.
|
|
2549
|
+
- **One field per provider.** The global shows a key field for the chat adapter and one for the image adapter. When both read the same env var (for example both use `OPENROUTER_API_KEY`), they share one field.
|
|
2550
|
+
- **Never shown again.** The field shows only "Set, ends in …4f2a", with **Replace key** and **Clear key**. REST and Local API reads never return the key, and the global has no GraphQL schema.
|
|
2551
|
+
- **Encrypted.** The key is stored with AES-256-GCM. The encryption key comes from Payload's `secret`. If the secret changes, the stored key cannot be read: it counts as not set, the server logs a warning, and the field says to paste the key again.
|
|
2552
|
+
- **No restart.** The server reads the key for each AI request, so a new key works on the next request. The setup card in the editor links to the settings page.
|
|
2553
|
+
- **Access.** Default: signed-in users of the admin user collection (`admin.user`). Sites with roles should allow admins only: `ai: { settings: { access: ({ req }) => req.user?.role === 'admin' } }`.
|
|
2554
|
+
- **Database.** One new global table with two text columns (`chatApiKey`, `imageApiKey`). Dev creates it on `pnpm dev` (`push: true`). Make a migration for production.
|
|
2555
|
+
|
|
2556
|
+
`ai.settings: false` turns the global off. `ai.settings: { slug }` renames it. The model stays in code: changing it starts a new chat, so it is not an admin setting.
|
|
2557
|
+
|
|
2122
2558
|
### Adapters
|
|
2123
2559
|
|
|
2124
2560
|
| Import | Adapter | Notes |
|
|
@@ -2138,7 +2574,7 @@ ai: { adapter: openAICompatibleAdapter({ baseURL: 'http://localhost:11434/v1', m
|
|
|
2138
2574
|
ai: { adapter: anthropicAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }) }
|
|
2139
2575
|
```
|
|
2140
2576
|
|
|
2141
|
-
You choose the adapter in your own config code, so you decide which environment variables to read. The starter picks `fakeAdapter()` when `BUILDER_AI_FAKE=1` (development only), else OpenRouter
|
|
2577
|
+
You choose the adapter in your own config code, so you decide which environment variables to read. The starter picks `fakeAdapter()` when `BUILDER_AI_FAKE=1` (development only), else OpenRouter. OpenRouter takes `OPENROUTER_API_KEY`, or a key an admin pastes in AI settings.
|
|
2142
2578
|
|
|
2143
2579
|
### Options
|
|
2144
2580
|
|
|
@@ -2152,6 +2588,7 @@ You choose the adapter in your own config code, so you decide which environment
|
|
|
2152
2588
|
| `images` | none | The image adapter. See [Image generation](#image-generation). |
|
|
2153
2589
|
| `imageLimits` | `{ perRequest: 3, perHour: 20 }` | Images per assistant reply, and per user per hour. |
|
|
2154
2590
|
| `imageMarkerField` | `generatedBy` | A media field that gets a note on generated images, when the collection has it. `false` turns it off. |
|
|
2591
|
+
| `settings` | on | The AI settings global for API keys. `{ slug?, access? }`, or `false` to turn it off. See [API keys in the admin](#api-keys-in-the-admin). |
|
|
2155
2592
|
|
|
2156
2593
|
The model, the key, `maxTokens` and provider settings belong to the adapter. See [providers.md](https://github.com/jon8800/payload-canvas/blob/main/docs/ai/providers.md) for each adapter's options.
|
|
2157
2594
|
|
|
@@ -2168,10 +2605,14 @@ type AiAdapter = {
|
|
|
2168
2605
|
setupProblem?: string | null // one sentence for the developer, e.g. "Set MY_API_KEY."
|
|
2169
2606
|
keyEnv?: string | null // shown in the setup card
|
|
2170
2607
|
keyUrl?: string | null // "Get an API key" link
|
|
2608
|
+
acceptsApiKey?: boolean // reads request.apiKey: AI settings show a key field for it
|
|
2609
|
+
missingKey?: boolean // ready is false only because the key is missing
|
|
2171
2610
|
stream(request: AiModelRequest): AsyncIterable<AiModelEvent>
|
|
2172
2611
|
}
|
|
2173
2612
|
```
|
|
2174
2613
|
|
|
2614
|
+
With `acceptsApiKey: true`, the request has `apiKey` when an admin set a key in AI settings. Use it instead of your own key for that request. Set `missingKey: true` when the only problem is the missing key: a key in AI settings then makes the adapter ready. Image adapters take the same two fields, and `AiImageRequest.apiKey`.
|
|
2615
|
+
|
|
2175
2616
|
`stream` runs one model call. The request has `system` (parts; `cache: true` marks a stable prefix you may cache), `messages` (the conversation), `tools`, `effort` and `signal`. Yield these events, in order:
|
|
2176
2617
|
|
|
2177
2618
|
- `{ type: 'text', text }`: assistant text as it arrives.
|
|
@@ -2309,6 +2750,12 @@ plugins: [
|
|
|
2309
2750
|
- Agents connect to `POST <your site>/api/mcp` with an API key from **Admin > MCP > API Keys**. Claude Code and Codex setup: [docs/ai/connect-claude-code-and-codex.md](https://github.com/jon8800/payload-canvas/blob/main/docs/ai/connect-claude-code-and-codex.md).
|
|
2310
2751
|
- Sign-in with the website account (OAuth, no key to copy) is a `payload-mcp-toolkit` feature: pass `oauth: { canAuthorize, access: 'editor' }` to `mcpToolkitPlugin()` and add the discovery rewrites. The starter shows the setup, and the doc above has the Claude Code and Codex commands. API keys keep working next to it.
|
|
2311
2752
|
- Tools (`listSections` and `insertSection` include [saved sections](#saved-sections)): `listBlocks`, `getBlockSchema`, `listSections`, `insertSection`, `getLayout`, `applyOperations`, `validateLayout`, `getPreviewUrl`, `generateImage`, plus `listTemplates` and `getBindingSources` for templates.
|
|
2753
|
+
- Builder layouts change only through `applyOperations` and `insertSection`. The tool descriptions say so; agents must not write the layout field with `updateDocument` or `patchLayout`.
|
|
2754
|
+
- `listBlocks` returns the layout guide (`guide`: block keys, ids, positions, classes, motion presets, HTML attributes) and the bindings guide (`bindings`). The guides are in the result, not in the tool descriptions, so `tools/list` stays small.
|
|
2755
|
+
- `update` operations take `className` (replaces the list), `addClassName` and `removeClassName` (space-separated, the other classes stay).
|
|
2756
|
+
- `applyOperations` returns `changes` (id, type, changed keys, and the new class list after class changes) and the warnings of the blocks it touched. `insertSection` returns `needsContent`: blocks whose image, form or other upload or relationship is still empty.
|
|
2757
|
+
- `visibility` and `bindings` work only in templates and inside collection list or repeat items. On a normal page they do nothing, and `applyOperations`, `insertSection` and `validateLayout` return a `no-effect` warning.
|
|
2758
|
+
- When an argument has one possible value (`collection` of the class tools, `generateImage`, `listTemplates`, and every builder tool with one builder collection), agents may leave it out.
|
|
2312
2759
|
- `generateImage` makes an image with the site's image adapter (`ai.images` in `websiteBuilder`) and saves it in the media collection. Clients that cannot make images (Claude Code with a Claude plan) use the site's adapter this way. The key needs `create` on the media collection.
|
|
2313
2760
|
- Every tool checks the key's access to the collection. Handlers run as the key's user with `overrideAccess: false`.
|
|
2314
2761
|
- Writes are commits to the document's live session, like an editor's own changes. Open editors show them at once, and the agent appears in the collaborator list while it works. The draft is saved about a second later. `getLayout` returns the session's layout, unsaved changes included.
|
|
@@ -2349,6 +2796,31 @@ Limits:
|
|
|
2349
2796
|
- On SIGINT/SIGTERM the plugin saves unsaved session edits before the process exits. To make that possible, it holds back `process.exit` for at most 3 seconds, and only while unsaved edits exist. A hard kill (`SIGKILL`, a crash) can still lose the last 1–5 seconds of edits.
|
|
2350
2797
|
- Two people typing in the same text field at the same moment: the later value wins for the whole field.
|
|
2351
2798
|
|
|
2799
|
+
### Comments on the canvas
|
|
2800
|
+
|
|
2801
|
+
Team members leave comments on blocks, reply, and resolve them, as in Figma or Webflow. Everyone with the page open sees new comments, replies and changes at once.
|
|
2802
|
+
|
|
2803
|
+
In the builder:
|
|
2804
|
+
|
|
2805
|
+
- Click the speech bubble in the top bar, or press **C**, for comment mode. The comments panel takes the inspector's place. Press **C** or **Esc** to leave.
|
|
2806
|
+
- In comment mode, click a block on the canvas. A pin goes on that spot, and a box opens for the comment. **Enter** sends, **Shift+Enter** adds a line.
|
|
2807
|
+
- Pins stay on their spot of the block when the page scrolls, the layout changes or the canvas zooms. Comment mode shows the pins; normal editing shows none.
|
|
2808
|
+
- Click a pin to open its thread: reply, resolve or reopen. Authors edit and delete their own comments. Deleting a thread deletes its replies.
|
|
2809
|
+
- The panel lists the threads: open ones first, then resolved ones. **All**, **Open** and **Resolved** filter the list. Click a thread to select its block and scroll to it.
|
|
2810
|
+
- A thread whose block was deleted stays in the panel, marked **Block deleted**. It opens in the panel.
|
|
2811
|
+
- The top bar button shows the number of open threads.
|
|
2812
|
+
|
|
2813
|
+
Comments are not part of the layout. They never change the layout JSON, undo history, saves or publishing. The canvas does no comment work outside comment mode.
|
|
2814
|
+
|
|
2815
|
+
Data and access:
|
|
2816
|
+
|
|
2817
|
+
- Each comment is a document of the plugin's **Comments** collection (slug `builder-comments`): the page (`docCollection`, `docId`), the block (`blockId`), the pin (`x`, `y`, 0 to 1 inside the block's box), the text (`body`), the author, and for a thread its resolved state (`resolved`, `resolvedByName`, `resolvedAt`). A reply has `parent` set to its thread.
|
|
2818
|
+
- People who may change the page may comment on it, reply, resolve and reopen. A hook checks this on every save, also over REST. Only the author changes the text or deletes a comment. Signed-in users read comments; set `comments.access.read` to restrict that.
|
|
2819
|
+
- The editor reads and writes the collection over Payload's REST API. Each save or delete goes to the page's open editors as a `comments` event on the live channel (see [Multiplayer editing](#multiplayer-editing)). A reconnect loads the list again.
|
|
2820
|
+
- On by default. `websiteBuilder({ comments: false })` turns it off. Options: `comments: { slug?, access?, admin?, hooks? }`. The new collection needs a migration in production (`pnpm payload migrate:create`).
|
|
2821
|
+
|
|
2822
|
+
Not included yet: mentions and email notifications.
|
|
2823
|
+
|
|
2352
2824
|
## Production and Docker
|
|
2353
2825
|
|
|
2354
2826
|
- **Database schema.** In development, Payload's Postgres adapter pushes schema changes on `pnpm dev`. For production, create migrations with `pnpm payload migrate:create` and run them on start with `prodMigrations` in `postgresAdapter`, or run `pnpm payload migrate` in your deploy step. Never run `payload migrate` against a development database that uses push.
|