payload-canvas 0.1.0 → 0.2.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 +202 -26
- package/dist/admin/editor/Canvas.js +30 -8
- package/dist/admin/editor/Editor.js +2 -0
- package/dist/admin/editor/Inspector.js +14 -7
- package/dist/admin/editor/Outline.js +15 -9
- package/dist/admin/editor/Overlay.js +2 -1
- package/dist/admin/editor/actions.d.ts +5 -0
- package/dist/admin/editor/actions.js +23 -1
- package/dist/admin/editor/counts.d.ts +6 -0
- package/dist/admin/editor/counts.js +10 -0
- package/dist/admin/editor/dnd/displace.js +3 -1
- package/dist/admin/editor/editor.scss +53 -0
- package/dist/admin/editor/inline.d.ts +12 -0
- package/dist/admin/editor/inline.js +48 -3
- package/dist/admin/editor/insert/spots.js +4 -2
- package/dist/admin/editor/live/useMultiplayer.js +8 -2
- package/dist/admin/editor/media/ImageEditor.js +21 -15
- package/dist/admin/editor/media/actions.d.ts +13 -9
- package/dist/admin/editor/media/actions.js +67 -28
- package/dist/admin/editor/media/model.d.ts +8 -0
- package/dist/admin/editor/media/model.js +14 -6
- package/dist/admin/editor/menu/blockMenu.js +13 -8
- package/dist/admin/editor/regions/RegionOverlay.d.ts +18 -0
- package/dist/admin/editor/regions/RegionOverlay.js +44 -0
- package/dist/admin/editor/regions/RegionPane.d.ts +5 -0
- package/dist/admin/editor/regions/RegionPane.js +26 -0
- package/dist/admin/editor/regions/RegionRows.d.ts +1 -0
- package/dist/admin/editor/regions/RegionRows.js +23 -0
- package/dist/admin/editor/regions/controller.d.ts +73 -0
- package/dist/admin/editor/regions/controller.js +231 -0
- package/dist/admin/editor/regions/select.d.ts +17 -0
- package/dist/admin/editor/regions/select.js +31 -0
- package/dist/admin/editor/runtime.d.ts +6 -0
- package/dist/admin/editor/runtime.js +49 -4
- package/dist/admin/editor/sections/controller.d.ts +6 -2
- package/dist/admin/editor/sections/controller.js +9 -3
- package/dist/admin/editor/shortcuts.js +11 -4
- package/dist/admin/editor/storage.d.ts +7 -0
- package/dist/admin/editor/storage.js +15 -0
- package/dist/admin/editor/store.d.ts +39 -0
- package/dist/admin/editor/store.js +106 -2
- package/dist/admin/editor/templates/Bindable.js +1 -1
- package/dist/admin/editor/templates/SamplePicker.js +1 -1
- package/dist/admin/editor/topbar/DocumentActions.js +38 -5
- package/dist/admin/editor/topbar/closeSave.d.ts +50 -0
- package/dist/admin/editor/topbar/closeSave.js +90 -0
- package/dist/admin/editor/topbar/document.d.ts +10 -2
- package/dist/admin/editor/topbar/document.js +9 -1
- package/dist/admin/editor/topbar/drawerLabels.d.ts +22 -0
- package/dist/admin/editor/topbar/drawerLabels.js +69 -0
- package/dist/admin/editor/topbar/problems.d.ts +9 -0
- package/dist/admin/editor/topbar/problems.js +15 -1
- package/dist/admin/editor/topbar/settingsDrawer.js +88 -4
- package/dist/admin/editor/topbar/settingsFocus.d.ts +11 -0
- package/dist/admin/editor/topbar/settingsFocus.js +46 -0
- package/dist/admin/editor/ui/payloadA11y.d.ts +17 -0
- package/dist/admin/editor/ui/payloadA11y.js +12 -5
- package/dist/admin/editor/valueStore.d.ts +2 -0
- package/dist/admin/editor/valueStore.js +6 -0
- package/dist/core/dropTarget.js +3 -1
- package/dist/core/index.d.ts +2 -0
- package/dist/core/index.js +2 -0
- package/dist/core/payloadBlocks.d.ts +53 -0
- package/dist/core/payloadBlocks.js +391 -0
- package/dist/core/regions.d.ts +63 -0
- package/dist/core/regions.js +239 -0
- package/dist/core/types.d.ts +53 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/live/document.d.ts +9 -1
- package/dist/live/document.js +57 -17
- package/dist/live/draftAccess.d.ts +36 -0
- package/dist/live/draftAccess.js +146 -0
- package/dist/live/endpoints.d.ts +11 -2
- package/dist/live/endpoints.js +120 -10
- package/dist/live/fieldChecks.d.ts +3 -3
- package/dist/live/fieldsGuard.d.ts +56 -2
- package/dist/live/fieldsGuard.js +107 -11
- package/dist/live/index.d.ts +2 -0
- package/dist/live/index.js +2 -0
- package/dist/live/regions.d.ts +89 -0
- package/dist/live/regions.js +401 -0
- package/dist/live/runtime.d.ts +1 -1
- package/dist/live/runtime.js +5 -2
- package/dist/live/session.d.ts +74 -9
- package/dist/live/session.js +655 -123
- package/dist/live/storage.d.ts +97 -0
- package/dist/live/storage.js +269 -0
- package/dist/live/types.d.ts +64 -0
- package/dist/live/writeGate.d.ts +72 -0
- package/dist/live/writeGate.js +478 -0
- package/dist/mcp/index.js +56 -12
- package/dist/plugin/hook.d.ts +44 -6
- package/dist/plugin/hook.js +176 -20
- package/dist/plugin/index.d.ts +23 -1
- package/dist/plugin/index.js +172 -10
- package/dist/plugin/references.d.ts +4 -2
- package/dist/plugin/references.js +2 -0
- package/dist/plugin/sectionsBuilder.js +3 -3
- package/dist/protocol/index.d.ts +28 -2
- package/dist/react/canvas/BuilderCanvas.js +198 -8
- package/dist/react/canvas/frame.d.ts +70 -0
- package/dist/react/canvas/frame.js +66 -0
- package/dist/react/canvas/inline/dom.d.ts +7 -1
- package/dist/react/canvas/inline/dom.js +19 -9
- package/dist/react/canvas/inline/mapper.d.ts +26 -0
- package/dist/react/canvas/inline/mapper.js +59 -32
- package/dist/react/canvas/inline/session.d.ts +7 -1
- package/dist/react/canvas/inline/session.js +6 -2
- package/dist/react/canvas/measure.js +26 -1
- package/dist/react/index.d.ts +2 -0
- package/dist/react/index.js +2 -0
- package/dist/react/render/LayoutOutlet.d.ts +11 -0
- package/dist/react/render/LayoutOutlet.js +16 -0
- package/dist/react/render/canvasFrame.d.ts +46 -0
- package/dist/react/render/canvasFrame.js +59 -0
- package/dist/react/render/canvasServer.d.ts +13 -0
- package/dist/react/render/canvasServer.js +3 -0
- package/dist/react/render/canvasServerTypes.d.ts +17 -0
- package/dist/react/render/regions.d.ts +13 -0
- package/dist/react/render/regions.js +8 -0
- package/dist/react/server.d.ts +2 -1
- package/dist/react/server.js +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,5 +1,20 @@
|
|
|
1
1
|
# Payload Canvas
|
|
2
2
|
|
|
3
|
+
<p align="center">
|
|
4
|
+
<a href="https://github.com/jon8800/payload-canvas/blob/main/docs/media/drag-and-drop.mp4"><img src="https://raw.githubusercontent.com/jon8800/payload-canvas/main/docs/media/drag-and-drop.gif" width="960" alt="Dragging a section on the canvas while the other sections slide out of the way, reordering it in the Layers tree, and dropping a ready-made section onto the page"></a>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<table>
|
|
8
|
+
<tr>
|
|
9
|
+
<td width="50%"><img src="https://raw.githubusercontent.com/jon8800/payload-canvas/main/docs/media/builder-dark.png" alt="The builder with a button selected and the Styles panel open"><br><sub>The full-screen builder: Layers, the live canvas, and the Styles panel.</sub></td>
|
|
10
|
+
<td width="50%"><img src="https://raw.githubusercontent.com/jon8800/payload-canvas/main/docs/media/ai-assistant.png" alt="The AI assistant after the request 'Make the hero headline punchier'"><br><sub>The AI assistant edits the page from a prompt.</sub></td>
|
|
11
|
+
</tr>
|
|
12
|
+
<tr>
|
|
13
|
+
<td><img src="https://raw.githubusercontent.com/jon8800/payload-canvas/main/docs/media/multiplayer.png" alt="Another editor's cursor and selection on the canvas"><br><sub>Multiplayer: another editor's cursor and selection show live.</sub></td>
|
|
14
|
+
<td><img src="https://raw.githubusercontent.com/jon8800/payload-canvas/main/docs/media/sections.png" alt="The Sections tab with section thumbnails"><br><sub>Ready-made sections with real thumbnails.</sub></td>
|
|
15
|
+
</tr>
|
|
16
|
+
</table>
|
|
17
|
+
|
|
3
18
|
A visual page builder for Payload CMS 3. It adds a full-screen builder to the collections you choose. Editors drag blocks onto a live canvas, nest them without limit, and style them with Tailwind classes. AI agents can build and edit the same pages over MCP, and an open editor shows each AI change as it happens.
|
|
4
19
|
|
|
5
20
|
The npm package is `payload-canvas`.
|
|
@@ -28,6 +43,7 @@ npx create-payload-canvas my-website
|
|
|
28
43
|
6. [Rendering the layout on your site](#rendering-the-layout-on-your-site)
|
|
29
44
|
- [Custom components](#custom-components)
|
|
30
45
|
7. [Server components in the canvas](#server-components-in-the-canvas)
|
|
46
|
+
- [Whole-page editing: regions outside the layout](#whole-page-editing-regions-outside-the-layout)
|
|
31
47
|
8. [Custom blocks](#custom-blocks)
|
|
32
48
|
- [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields)
|
|
33
49
|
9. [Using existing Payload blocks](#using-existing-payload-blocks)
|
|
@@ -239,19 +255,32 @@ export default async function CanvasLayout({ children }: { children: ReactNode }
|
|
|
239
255
|
}
|
|
240
256
|
```
|
|
241
257
|
|
|
258
|
+
The page is a server component that imports the server action, and passes it to a small client component that renders `BuilderCanvas`:
|
|
259
|
+
|
|
260
|
+
```tsx
|
|
261
|
+
// src/app/(builder-canvas)/builder-canvas/page.tsx (a server component: no 'use client')
|
|
262
|
+
import { builderCanvas } from './actions'
|
|
263
|
+
import { CanvasClient } from './CanvasClient'
|
|
264
|
+
|
|
265
|
+
export default function CanvasPage() {
|
|
266
|
+
return <CanvasClient server={builderCanvas} />
|
|
267
|
+
}
|
|
268
|
+
```
|
|
269
|
+
|
|
242
270
|
```tsx
|
|
243
|
-
// src/app/(builder-canvas)/builder-canvas/
|
|
271
|
+
// src/app/(builder-canvas)/builder-canvas/CanvasClient.tsx
|
|
244
272
|
'use client'
|
|
245
273
|
|
|
246
|
-
import { BuilderCanvas } from 'payload-canvas/react/canvas'
|
|
274
|
+
import { BuilderCanvas, type BuilderCanvasProps } from 'payload-canvas/react/canvas'
|
|
247
275
|
import { blocks } from '@/builder'
|
|
248
|
-
import { builderCanvas } from './actions'
|
|
249
276
|
|
|
250
|
-
export
|
|
251
|
-
return <BuilderCanvas blocks={blocks} server={
|
|
277
|
+
export function CanvasClient({ server }: { server: BuilderCanvasProps['server'] }) {
|
|
278
|
+
return <BuilderCanvas blocks={blocks} server={server} />
|
|
252
279
|
}
|
|
253
280
|
```
|
|
254
281
|
|
|
282
|
+
Keep the page a server component. The server action returns React Server Component output that holds client components: yours inside server-rendered blocks (an image, a carousel), and the builder's own (slot outlets, the page frame's layout). Next registers them in the route's client manifest only when a server component of the route imports the action. When a `'use client'` page imports it, they are missing, and the canvas shows "Could not find the module … in the React Client Manifest". Client-only props (`plugins`, `components`, `resolveLink`) belong in `CanvasClient`.
|
|
283
|
+
|
|
255
284
|
```ts
|
|
256
285
|
// src/app/(builder-canvas)/builder-canvas/actions.ts
|
|
257
286
|
'use server'
|
|
@@ -526,10 +555,11 @@ websiteBuilder({
|
|
|
526
555
|
| Option | Type | What it does |
|
|
527
556
|
|---|---|---|
|
|
528
557
|
| `collections` | `Record<slug, { field?, url?, templates? }>` | The collections that get the builder. Required. |
|
|
529
|
-
| `collections[slug].field` | `string` | Name of the
|
|
558
|
+
| `collections[slug].field` | `string` | Name of the builder's field. Default `layout`. Its type decides the storage. A Payload `blocks` field of the collection: the builder edits that field itself, the one source of truth (see [Using existing Payload blocks](#using-existing-payload-blocks)). Otherwise the builder's JSON layout: the generated CSS goes in `<field>Css`, and a `json` field with this name (also inside rows, collapsibles or unnamed tabs) is reused and moved to the top level. |
|
|
530
559
|
| `collections[slug].url` | `(doc) => string` | The frontend path of a document. AI tools use it for preview links. The collection list block uses it for links. |
|
|
531
560
|
| `collections[slug].templates` | `boolean` | Documents render through templates. See [Templates](#templates-and-binding). |
|
|
532
561
|
| `collections[slug].legacyFields` | `string[]` | Top-level fields the builder replaced but the collection still has (the old `blocks` field after `migrateBlocksField`). **Publish** in the builder keeps their published value, so only the builder content goes live. See [Using existing Payload blocks](#using-existing-payload-blocks), step 7. |
|
|
562
|
+
| `collections[slug].regions` | `{ name, label?, fields }[]` | Fixed parts of the page that show ordinary document fields outside the layout (a header made of the title and an image). The builder shows and edits the whole page. Left out: the layout alone. See [Whole-page editing](#whole-page-editing-regions-outside-the-layout). |
|
|
533
563
|
| `collections[slug].localization` | `'props' \| false` | With Payload `localization` on: `'props'` (the default) translates localized props in one shared layout; `false` keeps one set of values. See [Localization](#localization). |
|
|
534
564
|
| `blocks` | `BlockDefinition[]` | The blocks editors can use. Default `defaultBlocks()`. |
|
|
535
565
|
| `sections` | `SectionDefinition[]` | Ready-made sections. See [Sections](#sections). |
|
|
@@ -712,6 +742,8 @@ The canvas renders a block on the server when:
|
|
|
712
742
|
| `components` | The server map. |
|
|
713
743
|
| `resolveLink` | The same link resolver as the site. |
|
|
714
744
|
| `pageData` | `({ payload, user, document, context, locale }) => data`: the page data. `locale` is the language the editor shows (null without localization); load your data in it. See below. |
|
|
745
|
+
| `frame` | `({ doc, layout, region, … }) => ReactNode`: the page around the layout, for collections with `regions`. See [Whole-page editing](#whole-page-editing-regions-outside-the-layout). |
|
|
746
|
+
| `frameDepth` | The `depth` of the document `frame` gets. Default 1. |
|
|
715
747
|
|
|
716
748
|
How it works in the editor:
|
|
717
749
|
|
|
@@ -770,6 +802,112 @@ The loader also gets `user`, `document` (the document open in the builder, `{ co
|
|
|
770
802
|
|
|
771
803
|
Only components that ask for the page data get it: every `fromPayloadComponent` component, and components marked with `withPageData(Component)` (they get it as `pageData`). So a client component does not carry the page data in the page's payload.
|
|
772
804
|
|
|
805
|
+
## Whole-page editing: regions outside the layout
|
|
806
|
+
|
|
807
|
+
Many pages show more than their layout. A header shows the page's `title` and `coverImage` fields; a post shows its author above the body. These fields are ordinary Payload fields, rendered by your own component before or after the layout. Without regions, the canvas shows the layout alone, so these parts are missing in the editor.
|
|
808
|
+
|
|
809
|
+
Regions make the canvas show the whole page and let editors edit those fields in place. The fields stay where they are: the builder never copies them into the layout, and no sync runs. A region is fixed: it can be selected and edited, but never dragged, duplicated or deleted.
|
|
810
|
+
|
|
811
|
+
Regions are optional. A site that builds its pages from blocks alone needs none of this, and the editor does no extra work without them.
|
|
812
|
+
|
|
813
|
+
**1. Name the regions** of a collection. Each region lists the document fields it shows, by dot path. Fields in rows, collapsibles and unnamed tabs are named directly; a path goes through groups and named tabs (`header.title`). Name an array or upload field as a whole.
|
|
814
|
+
|
|
815
|
+
```ts
|
|
816
|
+
websiteBuilder({
|
|
817
|
+
collections: {
|
|
818
|
+
pages: {
|
|
819
|
+
field: 'layout',
|
|
820
|
+
regions: [{ name: 'header', label: 'Header', fields: ['title', 'subtitle', 'coverImage', 'links'] }],
|
|
821
|
+
},
|
|
822
|
+
},
|
|
823
|
+
// ...
|
|
824
|
+
})
|
|
825
|
+
```
|
|
826
|
+
|
|
827
|
+
The plugin checks the paths when it starts. It refuses the layout field and its own fields, Payload's `id`, `_status` and timestamps, `legacyFields`, join and virtual fields, paths through arrays, and a field in two regions.
|
|
828
|
+
|
|
829
|
+
**2. Put the page around the layout in one component**, used by the site and by the canvas. It gets the document, the layout to render, and `region`, which marks the part that shows a region:
|
|
830
|
+
|
|
831
|
+
```tsx
|
|
832
|
+
// src/components/PageFrame.tsx (a server component)
|
|
833
|
+
import type { ReactNode } from 'react'
|
|
834
|
+
import type { RegionMark } from 'payload-canvas/react'
|
|
835
|
+
import type { Page } from '@/payload-types'
|
|
836
|
+
import { PageHeader } from './PageHeader'
|
|
837
|
+
|
|
838
|
+
export function PageFrame({ page, layout, region }: { page: Page; layout: ReactNode; region: RegionMark }) {
|
|
839
|
+
return (
|
|
840
|
+
<>
|
|
841
|
+
{region('header', <PageHeader title={page.title} subtitle={page.subtitle} image={page.coverImage} links={page.links} />)}
|
|
842
|
+
<main>{layout}</main>
|
|
843
|
+
</>
|
|
844
|
+
)
|
|
845
|
+
}
|
|
846
|
+
```
|
|
847
|
+
|
|
848
|
+
`region(name, node)` adds no element. In the canvas it puts the region's mark on the first element of `node`. On the site you pass `siteRegion`, which returns `node` as it is. The frame's output holds client components (the layout outlet, the region mark), so the canvas page must be a server page that imports the action ([step 6 of Install](#6-add-the-canvas-route)).
|
|
849
|
+
|
|
850
|
+
**3. Render it on the site** with `siteRegion`:
|
|
851
|
+
|
|
852
|
+
```tsx
|
|
853
|
+
import { siteRegion } from 'payload-canvas/react'
|
|
854
|
+
|
|
855
|
+
<PageFrame page={page} region={siteRegion} layout={<RenderLayout layout={layout} css={css} components={serverComponents} />} />
|
|
856
|
+
```
|
|
857
|
+
|
|
858
|
+
**4. Render it in the canvas** with the `frame` option of `createCanvasServer`. The action file then holds JSX, so name it `actions.tsx`:
|
|
859
|
+
|
|
860
|
+
```tsx
|
|
861
|
+
// src/app/(builder-canvas)/builder-canvas/actions.tsx
|
|
862
|
+
'use server'
|
|
863
|
+
|
|
864
|
+
import config from '@payload-config'
|
|
865
|
+
import { createCanvasServer, type CanvasServerRequest } from 'payload-canvas/react/server'
|
|
866
|
+
import { blocks } from '@/builder'
|
|
867
|
+
import { serverComponents } from '@/components/blocks.server'
|
|
868
|
+
import { PageFrame } from '@/components/PageFrame'
|
|
869
|
+
import type { Page } from '@/payload-types'
|
|
870
|
+
|
|
871
|
+
const canvas = createCanvasServer({
|
|
872
|
+
config,
|
|
873
|
+
blocks,
|
|
874
|
+
components: serverComponents,
|
|
875
|
+
frame: ({ document, doc, layout, region }) =>
|
|
876
|
+
document.collection === 'pages' ? <PageFrame page={doc as Page} layout={layout} region={region} /> : layout,
|
|
877
|
+
})
|
|
878
|
+
|
|
879
|
+
export async function builderCanvas(request: CanvasServerRequest) {
|
|
880
|
+
return canvas(request)
|
|
881
|
+
}
|
|
882
|
+
```
|
|
883
|
+
|
|
884
|
+
`frame` gets the document's latest draft, read as the signed-in user, at `frameDepth` (default 1, so uploads and relationships arrive as documents), in the language the editor shows. It also gets `pageData`, `user`, `locale`, `context` and `mode`. Put `layout` where the page shows the layout: the canvas renders the live layout there, so every block stays selectable, draggable and editable at once. Return `layout` alone (or `null`) to show the layout without a frame.
|
|
885
|
+
|
|
886
|
+
**What editors can do with a region:**
|
|
887
|
+
|
|
888
|
+
- Hover or click it on the canvas, or click it in the **Layers** panel above the tree. The inspector shows its fields; **Edit fields** opens the page settings drawer at the region's first field. The drawer is Payload's own form, so every field type works with Payload's validation, hooks and access.
|
|
889
|
+
- Double-click its text to edit it in place: text, textarea and rich text fields, also inside array rows and groups. Double-click an image (or drop a file on it) to replace it, as in blocks. The automatic mapping finds the elements by their values, as for blocks. For elements it cannot find, `frame` gets `mode` (`'canvas'`): pass it on and mark them with `editableText(mode, path)` and `editableImage(mode, path)`, with the field's document path (`links.0.label`). On the site, pass `'site'`.
|
|
890
|
+
- Each change saves to the document when editing ends, as the user: a draft on collections with drafts, so **Publish** publishes it with the layout. One Ctrl+Z undoes it, and redo works too.
|
|
891
|
+
- Saves from anywhere show on every open canvas: a region edit, the settings drawer, REST, another editor. The `saved` event lists the fields a save changed, and the canvas asks for the frame again.
|
|
892
|
+
|
|
893
|
+
**What protects the fields:**
|
|
894
|
+
|
|
895
|
+
- The fields endpoint (`POST {api}/builder/live/:collection/:id/fields`) takes only paths inside the regions. It checks the user's update access to the document and to each field (Payload's own document access) and says no with 403, instead of dropping the change without a word.
|
|
896
|
+
- Each change carries the value the editor saw, also through a long inline edit. When someone else changed the field since, the save is refused (409) and the canvas shows their value. The answer never holds values the user may not read, also inside groups and array rows, and a save keeps those fields as they are.
|
|
897
|
+
- Undo and redo of a region change write the language the change was made in, and expect the value the server stored after the fields' hooks.
|
|
898
|
+
- Someone else's document lock (the Edit view or the settings drawer) refuses the save with 423. While your own settings drawer is open, canvas edits of region fields wait: the drawer's form holds its own copy of the fields.
|
|
899
|
+
- An open settings drawer renews its protection. If a close or renewal request is lost, protection expires after the configured document-lock duration (300 seconds by default).
|
|
900
|
+
- Saves of one document never overlap. Payload's update reads the newest version and writes the whole version back, so two overlapping saves (a layout save and a settings autosave) could lose one of the changes. The plugin lets one update of a builder document run at a time, from Payload's read to the commit of its transaction. This applies to every builder collection, with or without regions. A save that cannot get its turn (a wait that would never end) fails with a clear 409 instead. Editors hear of a save only after the database committed it: a rollback or a failed commit announces nothing.
|
|
901
|
+
|
|
902
|
+
**When the frame cannot show,** the canvas says so above the layout, and the layout stays editable: no `server` on `BuilderCanvas`, no `frame` option, a frame that throws, or a frame that never renders `layout`.
|
|
903
|
+
|
|
904
|
+
Limits:
|
|
905
|
+
|
|
906
|
+
- The canvas edits text, textarea, rich text and upload fields of a region. Edit other field types (selects, checkboxes, relationships, dates) in the settings drawer.
|
|
907
|
+
- Typing in a region reaches other editors when the editing ends, not letter by letter.
|
|
908
|
+
- AI tools (MCP and the assistant) edit the layout only.
|
|
909
|
+
- Templates show no frame: a template's regions would be its sample document's fields.
|
|
910
|
+
|
|
773
911
|
## Custom blocks
|
|
774
912
|
|
|
775
913
|
Declare a block with `defineBlock`. Props are Payload field configs. The editor builds its inputs from them, and the plugin builds a JSON Schema for validation and AI tools.
|
|
@@ -859,7 +997,17 @@ Limits:
|
|
|
859
997
|
|
|
860
998
|
## Using existing Payload blocks
|
|
861
999
|
|
|
862
|
-
A site that already has a Payload `blocks` field (for example `pages.layout` with sections and nested blocks)
|
|
1000
|
+
A site that already has a Payload `blocks` field (for example `pages.layout` with sections and nested blocks) keeps its field, its block configs, its components and its content. Point the builder at that field. The builder then edits the field itself: there is one source of truth, no second copy of the page, and nothing to migrate.
|
|
1001
|
+
|
|
1002
|
+
```ts
|
|
1003
|
+
websiteBuilder({
|
|
1004
|
+
collections: { pages: { field: 'layout', url: (doc) => `/${doc.slug}` } },
|
|
1005
|
+
blocks,
|
|
1006
|
+
css: { entry: 'src/app/(frontend)/globals.css' },
|
|
1007
|
+
})
|
|
1008
|
+
```
|
|
1009
|
+
|
|
1010
|
+
The type of the field decides how the builder stores the layout. A `blocks` field: the builder reads and writes that field. A `json` field, or no field with that name: the builder's own JSON layout, with every feature. There is no switch per document.
|
|
863
1011
|
|
|
864
1012
|
What carries over:
|
|
865
1013
|
|
|
@@ -868,7 +1016,7 @@ What carries over:
|
|
|
868
1016
|
- **Conditions.** An `admin.condition` that tests one sibling field, such as `(_, siblingData) => siblingData?.type === 'custom'`, becomes a JSON condition. The inspector hides the field, and an empty required field that is hidden does not block publishing.
|
|
869
1017
|
- **Components.** `fromPayloadComponents()` renders components written for Payload's data (`{ blockType, ...fields }`) unchanged.
|
|
870
1018
|
- **Field logic.** `validate`, field hooks and field `access` of the block fields run in the builder and the API, as in Payload. See [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields).
|
|
871
|
-
- **Content.**
|
|
1019
|
+
- **Content.** Nothing to convert: the builder edits the blocks field itself.
|
|
872
1020
|
- **Canvas editing.** Text and images of your components edit in place on the canvas, with no marks in your code. See [Inline editing](#inline-editing).
|
|
873
1021
|
|
|
874
1022
|
### Step by step
|
|
@@ -877,17 +1025,7 @@ These steps assume a site like this: `pages.layout` is a `blocks` field that ref
|
|
|
877
1025
|
|
|
878
1026
|
**1. Install** the package and add the canvas route, as in [Install](#install).
|
|
879
1027
|
|
|
880
|
-
**2.
|
|
881
|
-
|
|
882
|
-
```ts
|
|
883
|
-
websiteBuilder({
|
|
884
|
-
collections: { pages: { field: 'builderLayout', url: (doc) => `/${doc.slug}` } },
|
|
885
|
-
blocks,
|
|
886
|
-
css: { entry: 'src/app/(frontend)/globals.css' },
|
|
887
|
-
})
|
|
888
|
-
```
|
|
889
|
-
|
|
890
|
-
If you give the builder the name of the existing `blocks` field (`field: 'layout'`), the app does not start, and the error points here.
|
|
1028
|
+
**2. Point the builder at your blocks field** (`field: 'layout'`, as above). Keep the field as it is: its place, its admin options, its hooks, its access and its versions do not change. The plugin adds a Builder tab, and a hidden virtual field (`layoutBuilder`, no database column) that carries the editor's config.
|
|
891
1029
|
|
|
892
1030
|
**3. Make builder blocks from your block configs.** Put them in the client-safe blocks file:
|
|
893
1031
|
|
|
@@ -918,6 +1056,8 @@ export const blocks = [...defaultBlocks({ linkCollections: ['pages'] }), ...site
|
|
|
918
1056
|
|
|
919
1057
|
`labels.singular` becomes the label, and `admin.group` the library category. `interfaceName`, `dbName`, `imageURL` and the block's own admin components are not used.
|
|
920
1058
|
|
|
1059
|
+
Every block type the field holds, at any depth and through `blockReferences`, needs a builder block. The app does not start without one, and the error names the missing slugs.
|
|
1060
|
+
|
|
921
1061
|
**4. Wrap your components.** Use the same map as your `RenderBlocks`, keyed by Payload slug:
|
|
922
1062
|
|
|
923
1063
|
```ts
|
|
@@ -935,7 +1075,32 @@ Each component gets the props it always got: `{ id, blockType, blockName, ...fie
|
|
|
935
1075
|
- **Components that take `{ block, context }`** instead of the fields as props: add `{ props: (block, context) => ({ block, context }) }` as the third argument. `context` is the page data. See [Page data](#page-data-and--block-context--components).
|
|
936
1076
|
- **Components that load data** (async server components, or components that import Payload): leave them out of this client-safe map and put them in the server map. The canvas renders them on the server. See [Server components in the canvas](#server-components-in-the-canvas). A section whose file imports such a component (through its own `RenderLeaves`) goes in the server map too.
|
|
937
1077
|
|
|
938
|
-
**5.
|
|
1078
|
+
**5. Keep your page route.** The site renders `page.layout` with its own `RenderBlocks`, as before. Canvas edits are in that field right after each save.
|
|
1079
|
+
|
|
1080
|
+
### How the builder edits a Payload blocks field
|
|
1081
|
+
|
|
1082
|
+
- **One field.** When the builder opens a page, it reads the stored blocks (`depth: 0`) into the editor. Each save writes them back to the same field through Payload's Local API, as the editor's user (`overrideAccess: false`). Payload's field hooks, validation, access, versions and locales run once per save, as for a save in Payload's editor. Opening the builder saves nothing.
|
|
1083
|
+
- **Nothing lost.** A round trip keeps every stored value: fields the inspector does not show, unknown keys, `null` and empty values, block ids and order, `blockName` (the block's name in the builder), array rows with their ids, groups, nested blocks fields inside groups and arrays, and upload and relationship ids. No HTML is read back and no defaults are added. Data the builder cannot keep exactly (a block type without a builder block, two blocks with one id) is not changed: the builder refuses to open the page (422) and says why. Payload's editor still opens it.
|
|
1084
|
+
- **Saves from elsewhere win.** A save from Payload's editor, the REST API or the Local API is the stored truth. An open builder shows it at once and replays its own unsaved edits on top, after every such save until the builder saves.
|
|
1085
|
+
- **Copied rows.** Rows pasted from another page or inserted from a saved section get new ids. The page keeps its own row ids through remove, save, undo and save.
|
|
1086
|
+
- **Hooks.** After each save the builder reads the stored blocks again. What Payload's hooks stored becomes the builder's state at once: changed values and also added, removed or moved blocks. Edits made while the save ran stay on top. So a later edit or undo keeps what the hooks did.
|
|
1087
|
+
- **Old forms.** A form that loaded the page before its blocks last changed (the builder's settings drawer, a second tab) sends the blocks back as it loaded them. When the form did not change them, the save keeps the newer blocks. When it did, the save is refused (409, "Not saved. … changed Layout after you opened this form"), also when the same person made both changes.
|
|
1088
|
+
- **Publish, revert and restore** work on the same field. Publish stops if pending edits cannot be saved. Revert and restore require read access to every source value and update access to the blocks field. Payload's own version restore also updates an open builder after the transaction commits.
|
|
1089
|
+
|
|
1090
|
+
### Limits of a Payload blocks field
|
|
1091
|
+
|
|
1092
|
+
- **One language in the builder.** The builder edits the default locale. Translations stay in Payload's editor, and a canvas save keeps every other locale's values.
|
|
1093
|
+
- **No builder-only block data.** A Payload block has no place for Tailwind classes, animations, bindings or hidden blocks. The builder turns off the Styles and Motion tabs, Copy, Paste and Reset styles, and "Hide", also for blocks whose definition sets `styles: true` for JSON layouts. The editor refuses a change that carries such data before it shows it, and the server refuses it too (422): nothing of it is saved. The library lists only the sections and saved sections the field can store.
|
|
1094
|
+
- **No templates.** Templates hold builder JSON layouts. The plugin refuses `templates: true` on a collection whose builder field is a `blocks` field.
|
|
1095
|
+
- **Access.** The live session holds every value of the blocks, also values not saved yet. Payload's field `access.read` decides on those values themselves: stored ones and the open session's. A user who may not read one of them, or may not update the blocks field itself, cannot open, change or save the page in the builder or through MCP (403). The check runs on every request, and an open event stream checks each event before it goes out, against the values that event carried when it was sent: when the user may not read one, the stream ends instead. A reconnect gets the current state, never old changes. They edit in Payload's editor, which keeps the hidden values.
|
|
1096
|
+
|
|
1097
|
+
### Copying into a builder JSON field (opt-in)
|
|
1098
|
+
|
|
1099
|
+
Copy the content into a builder field of its own only when you want what a Payload block cannot hold: Tailwind classes, animations, bindings, hidden blocks, translations in the builder, or templates. The copy is one-way. After it, the builder field is the page's content, and the old field stays only until you remove it.
|
|
1100
|
+
|
|
1101
|
+
Give the builder a field of its own (`field: 'builderLayout'`), then convert the content:
|
|
1102
|
+
|
|
1103
|
+
**Convert the content.** Run a dry run first. It writes nothing and lists what it would do:
|
|
939
1104
|
|
|
940
1105
|
```ts
|
|
941
1106
|
// scripts/migrate-blocks.ts
|
|
@@ -975,9 +1140,9 @@ Close every builder tab while it runs. An open builder keeps its own copy of the
|
|
|
975
1140
|
- It writes through the database adapter (`updateOne`, `updateVersion`), so no hooks run. It compiles the CSS itself. Tested on Postgres. On MongoDB it converts the documents but not the versions.
|
|
976
1141
|
- Options: `where` (only some documents), `versions: false`, `overwrite`, `blocks` (default: the plugin's blocks), `log`.
|
|
977
1142
|
|
|
978
|
-
**
|
|
1143
|
+
**Render pages with the builder.** Change the page route to `RenderLayout` with `page.builderLayout` and `page.builderLayoutCss` (see [step 7 of Install](#7-render-pages-on-the-site)). Pass your wrapped `components` to `RenderLayout` and to `BuilderCanvas`.
|
|
979
1144
|
|
|
980
|
-
**
|
|
1145
|
+
**Keep the old field out of Publish, and remove it later.** Payload publishes the whole document. Without more setup, **Publish** in the builder would also publish the old field's latest draft (for example an edit someone made in the Edit view after the migration). List the old field in `legacyFields`:
|
|
981
1146
|
|
|
982
1147
|
```ts
|
|
983
1148
|
websiteBuilder({
|
|
@@ -1020,7 +1185,7 @@ The `builder` prop holds `mode`, `className`, `slots` (rendered children by slot
|
|
|
1020
1185
|
- **Custom admin components** on fields (a custom `Field`) need Payload's form, so the inspector shows the default input for the field type. `fromPayloadBlocks` lists them in a warning.
|
|
1021
1186
|
- **Conditions** that read the document, the user or several fields are not converted: the field always shows (also listed in a warning). Function `defaultValue`s of block fields do not run in the builder. `validate`, field hooks and field `access` do run: see [Validation, hooks and access on block fields](#validation-hooks-and-access-on-block-fields).
|
|
1022
1187
|
- **Loaded data** is one level deep. A component that needs deeper data loads it itself.
|
|
1023
|
-
- **Blocks fields inside a group, a named tab or an array** stay props, edited as JSON.
|
|
1188
|
+
- **Blocks fields inside a group, a named tab or an array** stay props, edited as JSON. With a Payload blocks field as the builder field, localized fields inside blocks keep every locale, and the builder edits the default locale. A copied JSON layout does not support localized block fields.
|
|
1024
1189
|
- A Payload slug `list` with an `items` array is read as the old built-in list (`normalizeLayout`). Use `prefix` to avoid that.
|
|
1025
1190
|
|
|
1026
1191
|
## Sections
|
|
@@ -1681,9 +1846,14 @@ Several people can have the same page open in the builder. Each change shows for
|
|
|
1681
1846
|
How it works:
|
|
1682
1847
|
|
|
1683
1848
|
- The server keeps one live session per open document, in memory. The session holds the layout and a sequence number `seq`.
|
|
1849
|
+
- Live editing requires access to the newest draft. Read access limited to published documents does not grant access to the live draft.
|
|
1850
|
+
- This also applies before the first draft save. The server checks collection read access on every streamed event and live edit. Query rules on the layout field cannot be checked against unsaved edits, so they refuse live editing. Other query rules use Payload's current stored document. A user role change applies after reconnecting.
|
|
1851
|
+
- After each committed save, the session reads the document's other fields again. Block access checks use those current fields, including for events still waiting to be sent. If the read fails, the check refuses access.
|
|
1684
1852
|
- An editor applies its own change at once, then sends it to `commit`. The server applies changes in the order they arrive, raises `seq` by 1, and sends each change to every open editor. A change that no longer applies (for example, someone deleted its block) is rejected, and that editor drops it.
|
|
1685
1853
|
- The server saves the session as a draft about 1 second after the last change (at the latest every 5 seconds). The save runs as the person who made the last change, with their access rules, and the normal save hook compiles the CSS.
|
|
1686
|
-
-
|
|
1854
|
+
- For native JSON layouts, an open session protects its unsaved layout from other document saves. Publish first saves pending edits and stops if that save fails. Payload's own version restore replaces the session from the restored version after commit. Existing Payload blocks fields follow the authoritative stored field, as described above.
|
|
1855
|
+
- Builder Restore and Revert pause background layout saves and outside layout sync until their save finishes. Concurrent actions run in order. Flush waits for an active action. Other JSON document saves during the action return 409; retry after it finishes. This includes Publish if the action starts after its flush. A failed action keeps earlier unsaved edits, and outside saves remain authoritative.
|
|
1856
|
+
- Flush also waits for a committed save's field-hook changes to reach the live session. Other guarded JSON saves return 409 while those changes wait. Retry after they apply. Background saves resume automatically.
|
|
1687
1857
|
- Every editor gets a `saved` event after each save and a `published` event after Publish, Unpublish or Revert, so the top bar shows the same status for everyone.
|
|
1688
1858
|
- The session closes 60 seconds after the last editor leaves and its draft is saved.
|
|
1689
1859
|
|
|
@@ -1694,9 +1864,12 @@ The other fields (title, slug, SEO, …) are edited in Payload's Edit view or in
|
|
|
1694
1864
|
|
|
1695
1865
|
To turn the lock off for a collection, set `lockDocuments: false` on it. The out-of-date check still runs.
|
|
1696
1866
|
|
|
1867
|
+
Saves of one document never overlap: Payload's update reads the newest version and writes the whole version back, so a session save and a settings autosave that overlap could put back the other one's old values. The plugin lets one update of a builder document run at a time, from Payload's read to the commit of its database transaction. Saves of different documents still run at the same time. Like the sessions, this works inside one server process.
|
|
1868
|
+
|
|
1697
1869
|
Limits:
|
|
1698
1870
|
|
|
1699
1871
|
- Sessions live in the memory of one server process. With more than one app server, route all requests for a document to the same server (sticky routing), or keep one app server.
|
|
1872
|
+
- Builder collections disable bulk editing. Bulk updates (`payload.update` with `where`) return 403 or 409. Update each document by ID. This keeps every update inside the write gate. Bulk publish, unpublish, trash changes and folder moves are unavailable; use the document's Edit view. Permanent bulk delete still works.
|
|
1700
1873
|
- Two people who change the same prop at the same time: the later change wins.
|
|
1701
1874
|
- On SIGINT/SIGTERM the plugin saves unsaved session edits before the process exits. To make that possible, it holds back `process.exit` for at most 3 seconds, and only while unsaved edits exist. A hard kill (`SIGKILL`, a crash) can still lose the last 1–5 seconds of edits.
|
|
1702
1875
|
- Two people typing in the same text field at the same moment: the later value wins for the whole field.
|
|
@@ -1774,7 +1947,9 @@ All entries must show one version. Pin `payload`, `@payloadcms/*` and `next` to
|
|
|
1774
1947
|
|
|
1775
1948
|
**Saving fails with "Tailwind plugin "x" is used by @plugin in the CSS entry but is not in the plugins map".** Add the plugin to `css.plugins` and to the canvas page's `plugins`.
|
|
1776
1949
|
|
|
1777
|
-
**"
|
|
1950
|
+
**""pages.layout" is a Payload blocks field, and the builder has no definition for its block "x"".** Every block type of the field needs a builder block. Add its config to `fromPayloadBlocks()` (with `references` for `blockReferences`): see [Using existing Payload blocks](#using-existing-payload-blocks).
|
|
1951
|
+
|
|
1952
|
+
**"The builder cannot open these blocks without changing them: …".** The stored blocks hold data the builder cannot keep exactly, for example a block type without a builder block. The message names it. Add the block, or fix the page in Payload's editor.
|
|
1778
1953
|
|
|
1779
1954
|
**"Two blocks have the type "heading"".** A block made with `fromPayloadBlocks` has the same type as another block. Set `prefix` in `fromPayloadBlocks`.
|
|
1780
1955
|
|
|
@@ -1784,7 +1959,7 @@ All entries must show one version. Pin `payload`, `@payloadcms/*` and `next` to
|
|
|
1784
1959
|
|
|
1785
1960
|
## Limits
|
|
1786
1961
|
|
|
1787
|
-
This is version 0.
|
|
1962
|
+
This is version 0.2. Before 1.0, a minor version can change the API. Known limits:
|
|
1788
1963
|
|
|
1789
1964
|
- **Payload 3 only.** Payload 4 (canary today) changes the admin UI. The builder does not support it yet.
|
|
1790
1965
|
- **Next.js and React only.** The admin editor and the canvas need a Next.js app (Payload's own requirement). Other frontends can render the stored JSON with their own code.
|
|
@@ -1792,6 +1967,7 @@ This is version 0.1. Before 1.0, a minor version can change the API. Known limit
|
|
|
1792
1967
|
- **The canvas runtime runs only in the editor's iframe.** `payload-canvas/react/canvas` belongs on the canvas route and nowhere else.
|
|
1793
1968
|
- **Tailwind CSS v4 only.** Styles are Tailwind classes, compiled from your Tailwind v4 entry CSS.
|
|
1794
1969
|
- **One server process.** Live sessions live in memory. See [Multiplayer editing](#multiplayer-editing) and [Deploying](#deploying). Serverless platforms are not supported.
|
|
1970
|
+
- **Updates by ID.** Builder collections disable bulk editing and refuse bulk updates with 403 or 409. Update each document by ID to preserve the order of saves.
|
|
1795
1971
|
- **Tested databases.** Postgres is tested end to end. Other Payload adapters store the layout in a JSON field and should work, but are not tested.
|
|
1796
1972
|
- **The editor's own labels are in English.** Payload's inputs inside it follow the admin language.
|
|
1797
1973
|
|
|
@@ -7,7 +7,8 @@ import { ancestors } from './actions.js';
|
|
|
7
7
|
import { dragModeChoice, prefersReducedMotion, useDragModeSetting } from './dnd/mode.js';
|
|
8
8
|
import { dropAt } from './dnd/smooth.js';
|
|
9
9
|
import { BlockIcon, Icon } from './icons.js';
|
|
10
|
-
import { applyInlineChange, applyInlineJoin, applyInlineSplit, boundHint, inlineEditing, noteInlineStart, refuseLockedInline, stopInlineEditing } from './inline.js';
|
|
10
|
+
import { applyInlineChange, applyInlineJoin, applyInlineSplit, boundHint, endRegionInline, inlineEditing, noteInlineStart, refuseLockedInline, stopInlineEditing, } from './inline.js';
|
|
11
|
+
import { regionAt, selectOwner } from './regions/select.js';
|
|
11
12
|
import { blockName } from './names.js';
|
|
12
13
|
import { MenuButton } from './menu/Menu.js';
|
|
13
14
|
import { playMotion } from './motion/play.js';
|
|
@@ -131,6 +132,7 @@ export function Canvas() {
|
|
|
131
132
|
}
|
|
132
133
|
if (message.kind === 'leave') {
|
|
133
134
|
store.hover(null);
|
|
135
|
+
runtime.regions?.hovered.set(null);
|
|
134
136
|
window.clearTimeout(spotTimer);
|
|
135
137
|
spotTimer = window.setTimeout(() => runtime.insertSpot.set(null), SPOT_LINGER_MS);
|
|
136
138
|
return;
|
|
@@ -140,6 +142,10 @@ export function Canvas() {
|
|
|
140
142
|
return;
|
|
141
143
|
const { layout } = store.getState();
|
|
142
144
|
const hit = deepestBlockAt(layout, m, message);
|
|
145
|
+
// Over no block: maybe over a fixed region of the page frame.
|
|
146
|
+
const region = !hit && runtime.regions ? regionAt(m, message) : null;
|
|
147
|
+
if (runtime.regions && runtime.regions.hovered.get() !== region)
|
|
148
|
+
runtime.regions.hovered.set(region);
|
|
143
149
|
if (message.kind === 'move') {
|
|
144
150
|
store.hover(hit);
|
|
145
151
|
const band = Math.max(EDGE_BAND, SPOT_BAND_PX / (runtime.frame.get().zoom || 1));
|
|
@@ -148,8 +154,14 @@ export function Canvas() {
|
|
|
148
154
|
const selected = selectedId ? { id: selectedId, tolerance: SELECTED_EDGE_PX / (runtime.frame.get().zoom || 1) } : undefined;
|
|
149
155
|
setSpot(inline.get() ? null : insertSpotAt(layout, runtime.config.blocks, m, message, { band, selected }));
|
|
150
156
|
}
|
|
151
|
-
if (message.kind === 'click')
|
|
152
|
-
|
|
157
|
+
if (message.kind === 'click') {
|
|
158
|
+
if (region && runtime.regions)
|
|
159
|
+
runtime.regions.selected.set(region);
|
|
160
|
+
else {
|
|
161
|
+
runtime.regions?.selected.set(null);
|
|
162
|
+
store.select(hit);
|
|
163
|
+
}
|
|
164
|
+
}
|
|
153
165
|
return;
|
|
154
166
|
}
|
|
155
167
|
case 'key':
|
|
@@ -164,11 +176,19 @@ export function Canvas() {
|
|
|
164
176
|
runtime.canvasError.set(message.message);
|
|
165
177
|
return;
|
|
166
178
|
case 'inlineStart':
|
|
167
|
-
|
|
179
|
+
selectOwner(runtime, message);
|
|
168
180
|
if (refuseLockedInline(runtime, message))
|
|
169
181
|
return;
|
|
170
182
|
noteInlineStart(runtime, message);
|
|
171
|
-
inline.set({
|
|
183
|
+
inline.set({
|
|
184
|
+
session: message.session,
|
|
185
|
+
id: message.id,
|
|
186
|
+
path: message.path,
|
|
187
|
+
kind: message.kind,
|
|
188
|
+
format: null,
|
|
189
|
+
linkRequest: 0,
|
|
190
|
+
...(message.region ? { region: message.region } : {}),
|
|
191
|
+
});
|
|
172
192
|
store.hover(null);
|
|
173
193
|
return;
|
|
174
194
|
case 'inlineChange':
|
|
@@ -177,6 +197,8 @@ export function Canvas() {
|
|
|
177
197
|
case 'inlineEnd':
|
|
178
198
|
if (inline.get()?.session === message.session)
|
|
179
199
|
inline.set(null);
|
|
200
|
+
if (message.region)
|
|
201
|
+
endRegionInline(runtime, message);
|
|
180
202
|
return;
|
|
181
203
|
case 'inlineSplit':
|
|
182
204
|
applyInlineSplit(runtime, message);
|
|
@@ -211,7 +233,7 @@ export function Canvas() {
|
|
|
211
233
|
return;
|
|
212
234
|
}
|
|
213
235
|
case 'imageEdit':
|
|
214
|
-
|
|
236
|
+
selectOwner(runtime, message.target);
|
|
215
237
|
updateImageEditor(runtime, { hover: message.target, open: { target: message.target, spot: 0, at: Date.now() } });
|
|
216
238
|
return;
|
|
217
239
|
case 'imageDrop': {
|
|
@@ -223,8 +245,8 @@ export function Canvas() {
|
|
|
223
245
|
runtime.warn(spot.kind === 'video' ? 'Drop a video file to replace this video.' : 'Drop an image file to replace this image.');
|
|
224
246
|
return;
|
|
225
247
|
}
|
|
226
|
-
|
|
227
|
-
void uploadImage(runtime, message.target
|
|
248
|
+
selectOwner(runtime, message.target);
|
|
249
|
+
void uploadImage(runtime, message.target, spot.path, message.file);
|
|
228
250
|
}
|
|
229
251
|
}
|
|
230
252
|
};
|
|
@@ -63,6 +63,8 @@ export function Editor({ config, meta, icon, locale }) {
|
|
|
63
63
|
useEffect(() => () => runtime.assistant?.stop(), [runtime]);
|
|
64
64
|
// The hidden thumbnail iframe goes with the editor.
|
|
65
65
|
useEffect(() => () => runtime.thumbnails.dispose(), [runtime]);
|
|
66
|
+
// The page's fixed regions: their values and the user's access, once the editor runs in the browser.
|
|
67
|
+
useEffect(() => void runtime.regions?.load(), [runtime]);
|
|
66
68
|
const stopAutoScroll = useRef(null);
|
|
67
69
|
const dndId = useId();
|
|
68
70
|
const sensors = useSensors(useSensor(PointerSensor, { activationConstraint: { distance: 4 } }));
|
|
@@ -16,11 +16,13 @@ import { AssistantPanel } from './assistant/AssistantPanel.js';
|
|
|
16
16
|
import { useAccessRefresh } from './fields/access.js';
|
|
17
17
|
import { BlockContentFields } from './renderField.js';
|
|
18
18
|
import { useRuntime } from './runtime.js';
|
|
19
|
+
import { storesBuilderData } from './actions.js';
|
|
19
20
|
import { shortcutList } from './shortcuts.js';
|
|
20
21
|
import { useEditor } from './store.js';
|
|
21
22
|
import { StylesPanel } from './styles/StylesPanel.js';
|
|
22
23
|
import { usePayloadControlNames } from './ui/payloadA11y.js';
|
|
23
|
-
import { useValue, useValueSelector } from './valueStore.js';
|
|
24
|
+
import { useOptionalValue, useValue, useValueSelector } from './valueStore.js';
|
|
25
|
+
import { RegionPane } from './regions/RegionPane.js';
|
|
24
26
|
function Tabs({ value, options, onChange, variant = 'underline' }) {
|
|
25
27
|
return (_jsx("div", { className: variant === 'segmented' ? 'builder-editor__segmented builder-editor__segmented--full' : 'builder-editor__tabs', role: "tablist", children: options.map((option) => (_jsxs("button", { type: "button", role: "tab", "aria-selected": value === option.id, className: variant === 'segmented' ? 'builder-editor__segment' : 'builder-editor__tab', onClick: () => onChange(option.id), children: [option.icon && _jsx(Icon, { name: option.icon, size: 13 }), option.label] }, option.id))) }));
|
|
26
28
|
}
|
|
@@ -65,6 +67,8 @@ function BlockPane() {
|
|
|
65
67
|
const [tab, setTab] = useState('content');
|
|
66
68
|
const [shownType, setShownType] = useState(null);
|
|
67
69
|
const focusRequest = useValue(runtime.focusRequest);
|
|
70
|
+
// A selected page region shows its own pane.
|
|
71
|
+
const region = useOptionalValue(runtime.regions?.selected ?? null);
|
|
68
72
|
// Styles and Motion stay open while the user edits blocks of one type. Another type opens its content,
|
|
69
73
|
// so its fields never seem to vanish.
|
|
70
74
|
if (block && block.type !== shownType) {
|
|
@@ -89,12 +93,15 @@ function BlockPane() {
|
|
|
89
93
|
return () => cancelAnimationFrame(frame);
|
|
90
94
|
}, [block, focusRequest, runtime]);
|
|
91
95
|
if (!block)
|
|
92
|
-
return _jsx(EmptyState, {});
|
|
93
|
-
return (_jsxs("div", { className: "builder-editor__block-pane", children: [_jsx(BlockHeader, { block: block }), _jsx(BlockProblems, { blockId: block.id }), _jsx(EditingBanner, { blockId: block.id }), _jsx(LocaleNote, { blockId: block.id, tab: tab }), _jsx(Tabs, { value: tab, onChange: setTab, options:
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
96
|
+
return region && runtime.regions ? _jsx(RegionPane, { regions: runtime.regions, name: region }, region) : _jsx(EmptyState, {});
|
|
97
|
+
return (_jsxs("div", { className: "builder-editor__block-pane", children: [_jsx(BlockHeader, { block: block }), _jsx(BlockProblems, { blockId: block.id }), _jsx(EditingBanner, { blockId: block.id }), _jsx(LocaleNote, { blockId: block.id, tab: tab }), _jsx(Tabs, { value: tab, onChange: setTab, options: storesBuilderData(runtime)
|
|
98
|
+
? [
|
|
99
|
+
{ id: 'content', label: 'Content' },
|
|
100
|
+
{ id: 'styles', label: 'Styles' },
|
|
101
|
+
{ id: 'motion', label: 'Motion' },
|
|
102
|
+
]
|
|
103
|
+
: // A Payload blocks field holds the blocks' own fields only.
|
|
104
|
+
[{ id: 'content', label: 'Content' }] }), tab === 'content' && _jsx(BlockContentFields, { block: block }), tab === 'styles' && storesBuilderData(runtime) && _jsx(StyleFields, { block: block }), tab === 'motion' && storesBuilderData(runtime) && _jsx(MotionPanel, { blockId: block.id, blockType: block.type, motion: block.motion })] }, block.id));
|
|
98
105
|
}
|
|
99
106
|
/** What stopped the last publish, for this block. */
|
|
100
107
|
function BlockProblems({ blockId }) {
|
|
@@ -3,7 +3,8 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
|
|
|
3
3
|
import { useDraggable } from '@dnd-kit/core';
|
|
4
4
|
import { memo, useCallback, useEffect, useMemo, useRef, useState, } from 'react';
|
|
5
5
|
import { describeMotion, findLocation, getBlockDefinition, slotNames, walkBlocks } from '../../core/index.js';
|
|
6
|
-
import { ancestors, renameBlock, toggleHidden } from './actions.js';
|
|
6
|
+
import { ancestors, renameBlock, storesBuilderData, toggleHidden } from './actions.js';
|
|
7
|
+
import { countText } from './counts.js';
|
|
7
8
|
import { BlockIcon, Icon } from './icons.js';
|
|
8
9
|
import { PeerDots } from './live/PresenceUI.js';
|
|
9
10
|
import { missingWords, useUntranslated } from './locale/locale.js';
|
|
@@ -11,6 +12,7 @@ import { BLOCK_KEYS, keyText } from './menu/keys.js';
|
|
|
11
12
|
import { openBlockMenu, renameRequest } from './menu/requests.js';
|
|
12
13
|
import { blockPreview, blockSummary, childrenOf, customLabel, typeName } from './names.js';
|
|
13
14
|
import { OUTLINE_INDENT, useRuntime } from './runtime.js';
|
|
15
|
+
import { RegionRows } from './regions/RegionRows.js';
|
|
14
16
|
import { useEditor } from './store.js';
|
|
15
17
|
import { findBindingField, listAncestor, URL_PATH } from './templates/binding.js';
|
|
16
18
|
import { useValue, useValueSelector } from './valueStore.js';
|
|
@@ -226,14 +228,14 @@ export function Outline() {
|
|
|
226
228
|
}
|
|
227
229
|
}
|
|
228
230
|
};
|
|
229
|
-
return (_jsxs("div", { className: "builder-editor__panel builder-editor__panel--grow builder-editor__outline-panel", children: [_jsxs("div", { className: "builder-editor__panel-head builder-left__tools", children: [_jsx("span", { className: "builder-left__note", children: total
|
|
231
|
+
return (_jsxs("div", { className: "builder-editor__panel builder-editor__panel--grow builder-editor__outline-panel", children: [_jsxs("div", { className: "builder-editor__panel-head builder-left__tools", children: [_jsx("span", { className: "builder-left__note", children: countText(total, { none: 'No blocks', one: 'block', many: 'blocks' }) }), _jsxs("span", { className: "builder-editor__panel-tools", children: [_jsx("button", { type: "button", className: "builder-editor__icon-button builder-editor__icon-button--small", "aria-label": "Collapse all", "data-tooltip": "Collapse all", onClick: () => {
|
|
230
232
|
const ids = new Set(runtime.collapsed.get());
|
|
231
233
|
walkBlocks(layout, (b) => {
|
|
232
234
|
if (childrenOf(b).length > 0)
|
|
233
235
|
ids.add(b.id);
|
|
234
236
|
});
|
|
235
237
|
runtime.collapsed.set(ids);
|
|
236
|
-
}, children: _jsx(Icon, { name: "chevronRight", size: 14 }) }), _jsx("button", { type: "button", className: "builder-editor__icon-button builder-editor__icon-button--small", "aria-label": "Expand all", "data-tooltip": "Expand all", onClick: () => runtime.collapsed.set(new Set()), children: _jsx(Icon, { name: "chevronDown", size: 14 }) })] })] }), rows.length === 0 ? (_jsx("div", { ref: outlineRef, className: "builder-editor__outline", children: _jsxs("div", { className: "builder-editor__empty", children: [_jsx(Icon, { name: "layers", size: 20 }), _jsx("p", { children: "The page is empty." }), _jsx("p", { className: "builder-editor__hint", children: "Add blocks from the Blocks or Sections tab: drag them onto the canvas, or click one." })] }) })) : (_jsx("div", { ref: outlineRef, className: "builder-editor__outline", role: "tree", "aria-label": "Layers", tabIndex: -1, onKeyDown: onKeyDown, children: rows.map((row) => (_jsx(OutlineRow, { block: row.block, depth: row.depth, container: row.container, open: row.open, childCount: row.childCount, text: row.text, issues: issues.get(row.block.id) ?? NO_ISSUES, untranslated: untranslated.get(row.block.id)?.length ?? 0, missing: missing, broken: broken.has(row.block.id), focusable: noSelectedRow && row.block.id === firstId, renaming: renaming === row.block.id, onRename: onRename }, row.block.id))) }))] }));
|
|
238
|
+
}, children: _jsx(Icon, { name: "chevronRight", size: 14 }) }), _jsx("button", { type: "button", className: "builder-editor__icon-button builder-editor__icon-button--small", "aria-label": "Expand all", "data-tooltip": "Expand all", onClick: () => runtime.collapsed.set(new Set()), children: _jsx(Icon, { name: "chevronDown", size: 14 }) })] })] }), _jsx(RegionRows, {}), rows.length === 0 ? (_jsx("div", { ref: outlineRef, className: "builder-editor__outline", children: _jsxs("div", { className: "builder-editor__empty", children: [_jsx(Icon, { name: "layers", size: 20 }), _jsx("p", { children: "The page is empty." }), _jsx("p", { className: "builder-editor__hint", children: "Add blocks from the Blocks or Sections tab: drag them onto the canvas, or click one." })] }) })) : (_jsx("div", { ref: outlineRef, className: "builder-editor__outline", role: "tree", "aria-label": "Layers", tabIndex: -1, onKeyDown: onKeyDown, children: rows.map((row) => (_jsx(OutlineRow, { block: row.block, depth: row.depth, container: row.container, open: row.open, childCount: row.childCount, text: row.text, issues: issues.get(row.block.id) ?? NO_ISSUES, untranslated: untranslated.get(row.block.id)?.length ?? 0, missing: missing, broken: broken.has(row.block.id), focusable: noSelectedRow && row.block.id === firstId, renaming: renaming === row.block.id, onRename: onRename }, row.block.id))) }))] }));
|
|
237
239
|
}
|
|
238
240
|
/** Inline actions must not start a drag or select the row. */
|
|
239
241
|
const stop = (e) => e.stopPropagation();
|
|
@@ -271,12 +273,16 @@ const OutlineRow = memo(function OutlineRow({ block, depth, container, open, chi
|
|
|
271
273
|
// Two hover actions, so the row keeps room for its name. Rename, duplicate and delete are in
|
|
272
274
|
// the menu and on their keys.
|
|
273
275
|
const actions = [
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
276
|
+
...(storesBuilderData(runtime)
|
|
277
|
+
? [
|
|
278
|
+
{
|
|
279
|
+
icon: (block.hidden ? 'eye' : 'eyeOff'),
|
|
280
|
+
label: block.hidden ? 'Show on the site' : 'Hide on the site',
|
|
281
|
+
tooltip: `${block.hidden ? 'Show on the site' : 'Hide on the site'} · ${keyText(BLOCK_KEYS.hide)}`,
|
|
282
|
+
run: () => toggleHidden(runtime, block.id),
|
|
283
|
+
},
|
|
284
|
+
]
|
|
285
|
+
: []),
|
|
280
286
|
{
|
|
281
287
|
icon: 'more',
|
|
282
288
|
label: 'More actions',
|