payload-canvas 0.6.3 → 0.6.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -21
- package/README.md +3237 -3236
- package/dist/admin/aiKeyField.scss +58 -58
- package/dist/admin/diff/layoutDiff.scss +181 -181
- package/dist/admin/editor/assistant/assistant.scss +944 -944
- package/dist/admin/editor/classes/manager.scss +262 -262
- package/dist/admin/editor/comments/comments.scss +539 -539
- package/dist/admin/editor/dnd/dnd.scss +261 -261
- package/dist/admin/editor/editor.scss +2629 -2629
- package/dist/admin/editor/empty/empty.scss +92 -92
- package/dist/admin/editor/fields/fields.scss +778 -778
- package/dist/admin/editor/generate/generate.scss +276 -276
- package/dist/admin/editor/layout/layout.scss +240 -240
- package/dist/admin/editor/live/presence.scss +24 -24
- package/dist/admin/editor/locale/locale.scss +154 -154
- package/dist/admin/editor/media/media.scss +233 -233
- package/dist/admin/editor/menu/menu.scss +132 -132
- package/dist/admin/editor/motion/motion.scss +84 -84
- package/dist/admin/editor/sections/components.scss +238 -238
- package/dist/admin/editor/sections/variants.scss +90 -90
- package/dist/admin/editor/styles/ClassCss.js +3 -3
- package/dist/admin/editor/styles/classes.scss +381 -381
- package/dist/admin/editor/styles/styles.scss +1123 -1123
- package/dist/admin/editor/styles/tokens.js +2 -1
- package/dist/admin/editor/templates/templates.scss +654 -654
- package/dist/admin/editor/tooltip/tooltip.scss +39 -39
- package/dist/admin/editor/topbar/DocumentActions.js +1 -1
- package/dist/admin/editor/topbar/TopBar.js +2 -1
- package/dist/admin/editor/topbar/contentMode.scss +26 -26
- package/dist/admin/editor/topbar/screens/screens.scss +134 -134
- package/dist/admin/editor/topbar/settingsDrawer.scss +32 -32
- package/dist/admin/editor/topbar/tabTitle.d.ts +6 -0
- package/dist/admin/editor/topbar/tabTitle.js +9 -0
- package/dist/admin/editor/topbar/topbar.scss +645 -645
- package/dist/admin/editor/ui/controls.scss +320 -320
- package/dist/admin/forms/submissions.scss +197 -197
- package/dist/admin/layoutField.scss +69 -69
- package/dist/admin/templateConditions.scss +24 -24
- package/dist/ai/prompt.js +40 -40
- package/dist/blocks/client/marquee.js +14 -14
- package/dist/blocks/payload.js +13 -3
- package/dist/core/payloadBlocks.js +10 -1
- package/dist/core/responseError.d.ts +5 -0
- package/dist/core/responseError.js +8 -0
- package/dist/core/sections.d.ts +2 -0
- package/dist/core/sections.js +8 -0
- package/dist/css/index.d.ts +6 -0
- package/dist/css/index.js +40 -1
- package/dist/css/shared.js +2 -2
- package/dist/live/session.js +18 -0
- package/dist/live/storage.d.ts +5 -0
- package/dist/live/storage.js +20 -0
- package/dist/mcp/index.js +46 -19
- package/dist/mcp/shared.js +16 -16
- package/dist/plugin/index.d.ts +21 -1
- package/dist/plugin/index.js +46 -15
- package/dist/react/canvas/BuilderCanvas.js +76 -75
- package/dist/react/canvas/thumbnail/ThumbnailCanvas.js +8 -7
- package/dist/theme/admin/fields.scss +363 -363
- package/package.json +1 -1
package/dist/ai/prompt.js
CHANGED
|
@@ -101,32 +101,32 @@ function sectionCatalog(sections, saved) {
|
|
|
101
101
|
/** The stable system prompt. Same input, same bytes: keep it free of request data. */
|
|
102
102
|
export function systemPrompt(catalog) {
|
|
103
103
|
const parts = [
|
|
104
|
-
`You are the AI assistant inside a visual website builder for Payload CMS. The user has one page open in the editor and asks you to change it: add sections, write or rewrite text, restyle blocks, reorder or remove them. You make those changes with your tools.
|
|
105
|
-
|
|
106
|
-
HOW YOUR EDITS WORK
|
|
107
|
-
- Your tools edit the page the user has open. Each successful change appears on the user's canvas at once. You never save or publish: the editor saves the page as usual, and the user can undo your whole reply in one step.
|
|
108
|
-
- Each user message comes with an <editor_context> block: the current layout JSON with every block id, the selected block, the canvas width and, for templates, the sample document. It shows the page when the user sent the message, including the user's own unsaved edits. The newest context block is the truth; older ones are history.
|
|
109
|
-
- "this", "it" and "the selected block" mean the selected block.
|
|
110
|
-
- Change only what the user asked for. Keep existing content unless the user asks you to replace it.
|
|
111
|
-
|
|
112
|
-
HOW TO WORK
|
|
113
|
-
1. Start with one short sentence that says what you are going to do.
|
|
114
|
-
2. To build page parts (hero, features, pricing, testimonials, FAQ, call to action, contact, footer), PREFER a ready-made section from the section catalog: insertSection, then adjust its text, images and classes with applyOperations "update". Build from single blocks only when no section fits, or for small additions.
|
|
115
|
-
3. Put related changes into one applyOperations call. Operations apply in order, all or nothing.
|
|
116
|
-
4. When a tool returns an error, read it, fix the input and try again. Do not repeat a call that failed.
|
|
117
|
-
5. When you are done, say in one or two plain sentences what you changed. Do not list block ids or JSON. If you could not do something, say so.
|
|
118
|
-
- If the request is unclear, or it would delete a lot of content, ask one short question instead of guessing.
|
|
119
|
-
|
|
120
|
-
WRITING COPY
|
|
121
|
-
- Keep copy short, concrete and on-brand: match the tone, names and facts already on the page.
|
|
122
|
-
- Headings: a few words. Body text: one to three sentences.
|
|
123
|
-
- Do not invent prices, statistics, customer names, quotes or contact details as if they were real. When the user wants example content, make it clearly a placeholder.
|
|
124
|
-
|
|
125
|
-
IMAGES
|
|
126
|
-
- Image and upload props hold the ID of a document in the media library. Find images with searchMedia. Never invent IDs or URLs.
|
|
127
|
-
- generateImage makes a new image and saves it in the media library (it costs money). Use it when the user asks for a new or generated image, or when nothing in the library fits and the user wants an image. With blockId it puts the image straight into that block. If it says image generation is not set up, keep the current image and tell the user.
|
|
128
|
-
|
|
129
|
-
RICH TEXT
|
|
104
|
+
`You are the AI assistant inside a visual website builder for Payload CMS. The user has one page open in the editor and asks you to change it: add sections, write or rewrite text, restyle blocks, reorder or remove them. You make those changes with your tools.
|
|
105
|
+
|
|
106
|
+
HOW YOUR EDITS WORK
|
|
107
|
+
- Your tools edit the page the user has open. Each successful change appears on the user's canvas at once. You never save or publish: the editor saves the page as usual, and the user can undo your whole reply in one step.
|
|
108
|
+
- Each user message comes with an <editor_context> block: the current layout JSON with every block id, the selected block, the canvas width and, for templates, the sample document. It shows the page when the user sent the message, including the user's own unsaved edits. The newest context block is the truth; older ones are history.
|
|
109
|
+
- "this", "it" and "the selected block" mean the selected block.
|
|
110
|
+
- Change only what the user asked for. Keep existing content unless the user asks you to replace it.
|
|
111
|
+
|
|
112
|
+
HOW TO WORK
|
|
113
|
+
1. Start with one short sentence that says what you are going to do.
|
|
114
|
+
2. To build page parts (hero, features, pricing, testimonials, FAQ, call to action, contact, footer), PREFER a ready-made section from the section catalog: insertSection, then adjust its text, images and classes with applyOperations "update". Build from single blocks only when no section fits, or for small additions.
|
|
115
|
+
3. Put related changes into one applyOperations call. Operations apply in order, all or nothing.
|
|
116
|
+
4. When a tool returns an error, read it, fix the input and try again. Do not repeat a call that failed.
|
|
117
|
+
5. When you are done, say in one or two plain sentences what you changed. Do not list block ids or JSON. If you could not do something, say so.
|
|
118
|
+
- If the request is unclear, or it would delete a lot of content, ask one short question instead of guessing.
|
|
119
|
+
|
|
120
|
+
WRITING COPY
|
|
121
|
+
- Keep copy short, concrete and on-brand: match the tone, names and facts already on the page.
|
|
122
|
+
- Headings: a few words. Body text: one to three sentences.
|
|
123
|
+
- Do not invent prices, statistics, customer names, quotes or contact details as if they were real. When the user wants example content, make it clearly a placeholder.
|
|
124
|
+
|
|
125
|
+
IMAGES
|
|
126
|
+
- Image and upload props hold the ID of a document in the media library. Find images with searchMedia. Never invent IDs or URLs.
|
|
127
|
+
- generateImage makes a new image and saves it in the media library (it costs money). Use it when the user asks for a new or generated image, or when nothing in the library fits and the user wants an image. With blockId it puts the image straight into that block. If it says image generation is not set up, keep the current image and tell the user.
|
|
128
|
+
|
|
129
|
+
RICH TEXT
|
|
130
130
|
- Rich text props hold Lexical JSON. Call getBlockSchema for the block before you write one.`,
|
|
131
131
|
stylingGuide(catalog.tokens),
|
|
132
132
|
layoutGuide('the block catalog'),
|
|
@@ -146,20 +146,20 @@ RICH TEXT
|
|
|
146
146
|
*/
|
|
147
147
|
export function formSystemPrompt(catalog) {
|
|
148
148
|
const parts = [
|
|
149
|
-
`You are the AI assistant inside a form builder for Payload CMS. The user has one form open (a contact form, a booking request, a survey) and asks you to change its fields: add, rename, reorder or remove questions, make them required, set their options, display conditions and classes (the width too). You make those changes with your tools.
|
|
150
|
-
|
|
151
|
-
HOW YOUR EDITS WORK
|
|
152
|
-
- editFormFields changes the open form. Each change appears in the form builder at once. You never save: the builder saves as usual, and the user can undo your whole reply in one step.
|
|
153
|
-
- Each user message comes with an <editor_context> block: the form's fields as a layout JSON (each block is one field; its type is "form" plus the field type, e.g. "formEmail"; its props are the field's values). The newest context block is the truth. getForm returns the fields in a simpler shape.
|
|
154
|
-
- "this" and "the selected field" mean the selected block.
|
|
155
|
-
- You cannot change the form's settings (title, submit button, confirmation message, emails, spam protection). When the user asks for one, tell them to click an empty spot of the canvas: the right panel then shows the form settings.
|
|
156
|
-
|
|
157
|
-
HOW TO WORK
|
|
158
|
-
1. Start with one short sentence that says what you are going to do.
|
|
159
|
-
2. Put related changes into one editFormFields call. Changes apply in order, all or nothing.
|
|
160
|
-
3. Ask people only for what you need: keep forms short, mark only the needed fields required, and use the field type that fits (email for addresses, textarea for messages, select or radio for a fixed list of choices, checkbox to accept terms).
|
|
161
|
-
4. Labels are short questions or nouns ("Your name", "Email", "How can we help?"). Names are short, lowercase, with _ ("company_size").
|
|
162
|
-
5. When a tool returns an error, read it, fix the input and try again. Do not repeat a call that failed.
|
|
149
|
+
`You are the AI assistant inside a form builder for Payload CMS. The user has one form open (a contact form, a booking request, a survey) and asks you to change its fields: add, rename, reorder or remove questions, make them required, set their options, display conditions and classes (the width too). You make those changes with your tools.
|
|
150
|
+
|
|
151
|
+
HOW YOUR EDITS WORK
|
|
152
|
+
- editFormFields changes the open form. Each change appears in the form builder at once. You never save: the builder saves as usual, and the user can undo your whole reply in one step.
|
|
153
|
+
- Each user message comes with an <editor_context> block: the form's fields as a layout JSON (each block is one field; its type is "form" plus the field type, e.g. "formEmail"; its props are the field's values). The newest context block is the truth. getForm returns the fields in a simpler shape.
|
|
154
|
+
- "this" and "the selected field" mean the selected block.
|
|
155
|
+
- You cannot change the form's settings (title, submit button, confirmation message, emails, spam protection). When the user asks for one, tell them to click an empty spot of the canvas: the right panel then shows the form settings.
|
|
156
|
+
|
|
157
|
+
HOW TO WORK
|
|
158
|
+
1. Start with one short sentence that says what you are going to do.
|
|
159
|
+
2. Put related changes into one editFormFields call. Changes apply in order, all or nothing.
|
|
160
|
+
3. Ask people only for what you need: keep forms short, mark only the needed fields required, and use the field type that fits (email for addresses, textarea for messages, select or radio for a fixed list of choices, checkbox to accept terms).
|
|
161
|
+
4. Labels are short questions or nouns ("Your name", "Email", "How can we help?"). Names are short, lowercase, with _ ("company_size").
|
|
162
|
+
5. When a tool returns an error, read it, fix the input and try again. Do not repeat a call that failed.
|
|
163
163
|
6. When you are done, say in one or two plain sentences what you changed. Do not list ids or JSON.`,
|
|
164
164
|
FORM_FIELDS_GUIDE,
|
|
165
165
|
`FIELD TYPES (JSON). The types this form offers, with their props.\n${JSON.stringify(formFieldTypes(catalog.blocks))}`,
|
|
@@ -8,18 +8,18 @@ export const MARQUEE_SECONDS = { slow: 60, normal: 35, fast: 20 };
|
|
|
8
8
|
* and moves by half its width, so the second copy takes the place of the first. Still on the
|
|
9
9
|
* canvas and with reduced motion: the items wrap and the copy is not shown.
|
|
10
10
|
*/
|
|
11
|
-
export const MARQUEE_CSS = `
|
|
12
|
-
@keyframes builder-marquee { from { transform: translate3d(0, 0, 0) } to { transform: translate3d(-50%, 0, 0) } }
|
|
13
|
-
[data-marquee] { overflow: hidden }
|
|
14
|
-
[data-marquee-track] { display: flex; width: max-content; animation: builder-marquee var(--marquee-duration, 35s) linear infinite }
|
|
15
|
-
[data-marquee-track] > * { flex-shrink: 0 }
|
|
16
|
-
[data-marquee="right"] [data-marquee-track] { animation-direction: reverse }
|
|
17
|
-
[data-marquee-pause]:hover [data-marquee-track], [data-marquee-pause]:focus-within [data-marquee-track] { animation-play-state: paused }
|
|
18
|
-
[data-marquee-still] [data-marquee-track] { width: auto; animation: none }
|
|
19
|
-
[data-marquee-still] [data-marquee-track] > * { flex-shrink: 1; flex-wrap: wrap }
|
|
20
|
-
@media (prefers-reduced-motion: reduce) {
|
|
21
|
-
[data-marquee-track] { width: auto; animation: none }
|
|
22
|
-
[data-marquee-track] > * { flex-shrink: 1; flex-wrap: wrap }
|
|
23
|
-
[data-marquee-copy] { display: none }
|
|
24
|
-
}
|
|
11
|
+
export const MARQUEE_CSS = `
|
|
12
|
+
@keyframes builder-marquee { from { transform: translate3d(0, 0, 0) } to { transform: translate3d(-50%, 0, 0) } }
|
|
13
|
+
[data-marquee] { overflow: hidden }
|
|
14
|
+
[data-marquee-track] { display: flex; width: max-content; animation: builder-marquee var(--marquee-duration, 35s) linear infinite }
|
|
15
|
+
[data-marquee-track] > * { flex-shrink: 0 }
|
|
16
|
+
[data-marquee="right"] [data-marquee-track] { animation-direction: reverse }
|
|
17
|
+
[data-marquee-pause]:hover [data-marquee-track], [data-marquee-pause]:focus-within [data-marquee-track] { animation-play-state: paused }
|
|
18
|
+
[data-marquee-still] [data-marquee-track] { width: auto; animation: none }
|
|
19
|
+
[data-marquee-still] [data-marquee-track] > * { flex-shrink: 1; flex-wrap: wrap }
|
|
20
|
+
@media (prefers-reduced-motion: reduce) {
|
|
21
|
+
[data-marquee-track] { width: auto; animation: none }
|
|
22
|
+
[data-marquee-track] > * { flex-shrink: 1; flex-wrap: wrap }
|
|
23
|
+
[data-marquee-copy] { display: none }
|
|
24
|
+
}
|
|
25
25
|
`;
|
package/dist/blocks/payload.js
CHANGED
|
@@ -24,13 +24,23 @@ const ICONS = [
|
|
|
24
24
|
[/spacer/i, 'spacer'],
|
|
25
25
|
[/rich|content|text|prose|copy|intro/i, 'richText'],
|
|
26
26
|
];
|
|
27
|
-
|
|
27
|
+
/**
|
|
28
|
+
* The warnings already printed, on `globalThis`: Next.js loads this module once per bundle (server
|
|
29
|
+
* components, SSR, route handlers, the admin) and again after each dev reload, so a module-level
|
|
30
|
+
* set would print the same warning on every render. One set per process, and per page load.
|
|
31
|
+
*/
|
|
32
|
+
const SEEN_WARNINGS_KEY = Symbol.for('payload-canvas.fromPayloadBlocks.warnings');
|
|
33
|
+
function seenWarnings() {
|
|
34
|
+
const store = globalThis;
|
|
35
|
+
return (store[SEEN_WARNINGS_KEY] ??= new Set());
|
|
36
|
+
}
|
|
28
37
|
function defaultWarn(message) {
|
|
29
38
|
if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production')
|
|
30
39
|
return;
|
|
31
|
-
|
|
40
|
+
const seen = seenWarnings();
|
|
41
|
+
if (seen.has(message))
|
|
32
42
|
return;
|
|
33
|
-
|
|
43
|
+
seen.add(message);
|
|
34
44
|
console.warn(message);
|
|
35
45
|
}
|
|
36
46
|
/** `{ max: 1 }` from `maxRows: 1`; nothing for a missing or invalid row count. */
|
|
@@ -302,7 +302,16 @@ export function payloadBlocksStorage(topSlugs, definitions, where) {
|
|
|
302
302
|
for (const child of slot.allow ?? [])
|
|
303
303
|
queue.push(child);
|
|
304
304
|
}
|
|
305
|
-
|
|
305
|
+
// A type the field holds only inside other blocks goes only there: the editor and the layout
|
|
306
|
+
// check read `parents`, and a type without them would be offered at the top level too.
|
|
307
|
+
const roots = new Set(rootTypes);
|
|
308
|
+
const list = [...found.values()].map((def) => {
|
|
309
|
+
if (def.parents || roots.has(def.type))
|
|
310
|
+
return def;
|
|
311
|
+
const parents = [...found.values()].filter((owner) => Object.values(owner.slots ?? {}).some((slot) => slot.allow?.includes(def.type))).map((owner) => owner.type);
|
|
312
|
+
return parents.length > 0 ? { ...def, parents } : def;
|
|
313
|
+
});
|
|
314
|
+
return { blocks: list, rootTypes };
|
|
306
315
|
}
|
|
307
316
|
/**
|
|
308
317
|
* Calls `visit` for every row of an array field and every block of a blocks field inside `data`,
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The message of a failed response: the endpoint's own `{ error }` text when it sent one (the CSS
|
|
3
|
+
* endpoints say what to change in the config), else the status. Client-safe.
|
|
4
|
+
*/
|
|
5
|
+
export async function responseErrorMessage(res) {
|
|
6
|
+
const body = (await res.json().catch(() => null));
|
|
7
|
+
return typeof body?.error === 'string' && body.error !== '' ? body.error : `${res.status} ${res.statusText}`;
|
|
8
|
+
}
|
package/dist/core/sections.d.ts
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
1
|
import type { Block, Layout, Operation, SectionDefinition, SectionOrigin } from './types.js';
|
|
2
|
+
/** The sections, and their variants, whose blocks `fits` accepts (a Payload blocks field stores only some). */
|
|
3
|
+
export declare function sectionsThatFit(sections: SectionDefinition[], fits: (blocks: Block[]) => boolean): SectionDefinition[];
|
|
2
4
|
/** The name of a section's own version when it sets no `variantLabel`. */
|
|
3
5
|
export declare const DEFAULT_VARIANT_LABEL = "Default";
|
|
4
6
|
/** One version of a section: the section itself (`variant` undefined) or one of its variants. */
|
package/dist/core/sections.js
CHANGED
|
@@ -8,6 +8,14 @@
|
|
|
8
8
|
import { htmlIdsOf, withoutTakenHtmlIds } from './attrs.js';
|
|
9
9
|
import { createId } from './ids.js';
|
|
10
10
|
import { findBlock, findLocation, walkBlocks } from './tree.js';
|
|
11
|
+
/** The sections, and their variants, whose blocks `fits` accepts (a Payload blocks field stores only some). */
|
|
12
|
+
export function sectionsThatFit(sections, fits) {
|
|
13
|
+
return sections.flatMap((section) => {
|
|
14
|
+
if (!fits(section.blocks))
|
|
15
|
+
return [];
|
|
16
|
+
return [section.variants ? { ...section, variants: section.variants.filter((v) => fits(v.blocks)) } : section];
|
|
17
|
+
});
|
|
18
|
+
}
|
|
11
19
|
/** The name of a section's own version when it sets no `variantLabel`. */
|
|
12
20
|
export const DEFAULT_VARIANT_LABEL = 'Default';
|
|
13
21
|
/**
|
package/dist/css/index.d.ts
CHANGED
|
@@ -25,6 +25,12 @@ export type CanvasCssInput = {
|
|
|
25
25
|
entry: string;
|
|
26
26
|
[key: string]: unknown;
|
|
27
27
|
};
|
|
28
|
+
/**
|
|
29
|
+
* What stops the app's CSS entry from compiling, as messages that say what to change: an entry
|
|
30
|
+
* file that cannot be read, `@plugin` ids missing from `plugins` (every one of them), or another
|
|
31
|
+
* compile error. Empty: the entry compiles. The plugin runs it at startup (`websiteBuilder`).
|
|
32
|
+
*/
|
|
33
|
+
export declare function cssEntryProblems(options: CssOptions): Promise<string[]>;
|
|
28
34
|
/**
|
|
29
35
|
* Compiles only the given classes against the app's CSS entry. Output: the utilities plus the
|
|
30
36
|
* @property / @keyframes rules they need. No Preflight, no base layer, never overrides theme vars.
|
package/dist/css/index.js
CHANGED
|
@@ -121,7 +121,11 @@ const hash = (...parts) => createHash('sha256').update(parts.join('\0')).digest(
|
|
|
121
121
|
const inputCache = new Lru(8);
|
|
122
122
|
/** countUtilityLayers() of an empty build, per recorded input. Server-side only. */
|
|
123
123
|
const staticUtilityLayers = new WeakMap();
|
|
124
|
-
|
|
124
|
+
/**
|
|
125
|
+
* `onMissing`: called for each `@plugin` id missing from `plugins`, which then loads as an empty
|
|
126
|
+
* plugin (the startup check lists every missing id). Left out: a missing id throws.
|
|
127
|
+
*/
|
|
128
|
+
async function recordInput(entryFile, entryCss, plugins, onMissing) {
|
|
125
129
|
const entryDir = path.dirname(entryFile);
|
|
126
130
|
const toVirtual = (real) => path.relative(entryDir, real).replaceAll('\\', '/') || ENTRY_BASE;
|
|
127
131
|
const data = { version: 1, entry: entryCss, stylesheets: {}, plugins: [] };
|
|
@@ -143,6 +147,10 @@ async function recordInput(entryFile, entryCss, plugins) {
|
|
|
143
147
|
loadModule: (id, base) => {
|
|
144
148
|
if (!data.plugins.includes(id))
|
|
145
149
|
data.plugins.push(id);
|
|
150
|
+
if (onMissing && !Object.hasOwn(plugins ?? {}, id)) {
|
|
151
|
+
onMissing(id);
|
|
152
|
+
return Promise.resolve({ path: id, base, module: (() => { }) });
|
|
153
|
+
}
|
|
146
154
|
return loadPlugin(id, base, plugins);
|
|
147
155
|
},
|
|
148
156
|
});
|
|
@@ -164,6 +172,37 @@ async function getInput(options) {
|
|
|
164
172
|
}
|
|
165
173
|
// ---------------------------------------------------------------------------------------------
|
|
166
174
|
// Public API
|
|
175
|
+
/**
|
|
176
|
+
* What stops the app's CSS entry from compiling, as messages that say what to change: an entry
|
|
177
|
+
* file that cannot be read, `@plugin` ids missing from `plugins` (every one of them), or another
|
|
178
|
+
* compile error. Empty: the entry compiles. The plugin runs it at startup (`websiteBuilder`).
|
|
179
|
+
*/
|
|
180
|
+
export async function cssEntryProblems(options) {
|
|
181
|
+
let entryCss;
|
|
182
|
+
try {
|
|
183
|
+
entryCss = await readCached(options.entry);
|
|
184
|
+
}
|
|
185
|
+
catch {
|
|
186
|
+
return [`The CSS entry "${options.entry}" cannot be read. Set \`css.entry\` of websiteBuilder() to the app's Tailwind entry CSS, absolute or relative to the folder the app starts in.`];
|
|
187
|
+
}
|
|
188
|
+
const missing = [];
|
|
189
|
+
try {
|
|
190
|
+
await recordInput(options.entry, entryCss, options.plugins, (id) => {
|
|
191
|
+
if (!missing.includes(id))
|
|
192
|
+
missing.push(id);
|
|
193
|
+
});
|
|
194
|
+
}
|
|
195
|
+
catch (error) {
|
|
196
|
+
return [...(missing.length > 0 ? [missingPluginsMessage(missing)] : []), `The CSS entry "${options.entry}" does not compile: ${error instanceof Error ? error.message : String(error)}`];
|
|
197
|
+
}
|
|
198
|
+
return missing.length > 0 ? [missingPluginsMessage(missing)] : [];
|
|
199
|
+
}
|
|
200
|
+
function missingPluginsMessage(ids) {
|
|
201
|
+
const list = ids.map((id) => `"${id}"`).join(', ');
|
|
202
|
+
const entries = ids.map((id) => `'${id}': plugin`).join(', ');
|
|
203
|
+
return (`The CSS entry uses @plugin ${list}, but \`css.plugins\` of websiteBuilder() does not have ${ids.length === 1 ? 'it' : 'them'}. ` +
|
|
204
|
+
`Import each plugin in the Payload config and pass it: css: { entry, plugins: { ${entries} } }.`);
|
|
205
|
+
}
|
|
167
206
|
const cssCache = new Lru(100);
|
|
168
207
|
/**
|
|
169
208
|
* Compiles only the given classes against the app's CSS entry. Output: the utilities plus the
|
package/dist/css/shared.js
CHANGED
|
@@ -5,8 +5,8 @@ import { BUILDER_CSS_CLASS } from './marker.js';
|
|
|
5
5
|
export const ENTRY_BASE = '.';
|
|
6
6
|
export const stylesheetKey = (id, base) => `${id}|${base}`;
|
|
7
7
|
export function missingPluginError(id) {
|
|
8
|
-
return new Error(`Tailwind plugin "${id}" is used by @plugin in the CSS entry but is not in the plugins map
|
|
9
|
-
`
|
|
8
|
+
return new Error(`Tailwind plugin "${id}" is used by @plugin in the CSS entry but is not in the plugins map ` +
|
|
9
|
+
`(\`css.plugins\` of websiteBuilder()). Import it and pass it as plugins: { '${id}': plugin }.`);
|
|
10
10
|
}
|
|
11
11
|
export function loadPlugin(id, base, plugins = {}) {
|
|
12
12
|
if (!Object.hasOwn(plugins, id))
|
package/dist/live/session.js
CHANGED
|
@@ -119,6 +119,8 @@ function rememberRows(session) {
|
|
|
119
119
|
}
|
|
120
120
|
/** The answer of a session save that found nothing left to write. */
|
|
121
121
|
const SKIPPED = Symbol('skipped');
|
|
122
|
+
/** The answer of a session save whose layout the field already stores: nothing written. */
|
|
123
|
+
const UNCHANGED = Symbol('unchanged');
|
|
122
124
|
/**
|
|
123
125
|
* The session save waits: a reset action owns the layout until its save or rollback finishes, or
|
|
124
126
|
* a committed save's hook changes are not in the layout yet (`session.adopting`).
|
|
@@ -423,6 +425,14 @@ export function createSessionManager(options = {}) {
|
|
|
423
425
|
const problems = codec.problems(layout);
|
|
424
426
|
if (problems.length > 0)
|
|
425
427
|
throw Object.assign(new Error(problems.join(' ')), { status: 422 });
|
|
428
|
+
// The layout as the field would store it equals the stored value (a commit set a value it
|
|
429
|
+
// already had, or later commits undid it): no write, so no new draft version. Read now,
|
|
430
|
+
// inside the gate: the session's copy can be older than a save outside the session.
|
|
431
|
+
const current = (await readStored(session))[target.field];
|
|
432
|
+
if (activeActions.has(session.key))
|
|
433
|
+
return PAUSED;
|
|
434
|
+
if (codec.isStored ? codec.isStored(layout, current) : sameJson(codec.encode(layout, current), current))
|
|
435
|
+
return UNCHANGED;
|
|
426
436
|
session.writing = true;
|
|
427
437
|
try {
|
|
428
438
|
return await write(layout, req);
|
|
@@ -477,6 +487,14 @@ export function createSessionManager(options = {}) {
|
|
|
477
487
|
clearFailure(session);
|
|
478
488
|
return;
|
|
479
489
|
}
|
|
490
|
+
if (saved === UNCHANGED) {
|
|
491
|
+
// Saved as far as anyone can tell: the stored value already is this layout.
|
|
492
|
+
session.persistedSeq = Math.max(session.persistedSeq, seq);
|
|
493
|
+
session.unsaved = session.unsaved.filter((entry) => entry.seq > session.persistedSeq);
|
|
494
|
+
clearFailure(session);
|
|
495
|
+
deliver(session, savedEvent(seq));
|
|
496
|
+
return;
|
|
497
|
+
}
|
|
480
498
|
session.persistedSeq = Math.max(session.persistedSeq, seq);
|
|
481
499
|
session.unsaved = session.unsaved.filter((entry) => entry.seq > session.persistedSeq);
|
|
482
500
|
clearFailure(session);
|
package/dist/live/storage.d.ts
CHANGED
|
@@ -12,6 +12,11 @@ export type LayoutCodec = {
|
|
|
12
12
|
encode(layout: Layout, previous?: unknown): unknown;
|
|
13
13
|
/** What in a layout the field cannot store. Empty: it can be stored as it is. */
|
|
14
14
|
problems(layout: Layout): string[];
|
|
15
|
+
/**
|
|
16
|
+
* True when saving `layout` over the stored `value` would store nothing new: the session then
|
|
17
|
+
* writes nothing, so no draft version. Left out: the encoded layout must deep-equal `value`.
|
|
18
|
+
*/
|
|
19
|
+
isStored?(layout: Layout, value: unknown): boolean;
|
|
15
20
|
/**
|
|
16
21
|
* The resolved operations of a commit as the field stores them (a Payload blocks field gives
|
|
17
22
|
* copied rows new ids; `owned`: the row ids the document's stored value has held). Returns `ops`
|
package/dist/live/storage.js
CHANGED
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
import { APIError, docAccessOperation } from 'payload';
|
|
11
11
|
import { decodePayloadBlocks, encodePayloadBlocks, payloadBlocksProblems, payloadRowIds, withUniqueRowIds } from '../core/payloadBlocks.js';
|
|
12
12
|
import { upgradeLayout } from '../core/blocks.js';
|
|
13
|
+
import { sameJson } from '../core/fieldSemantics.js';
|
|
13
14
|
import { normalizeLayout } from '../core/tree.js';
|
|
14
15
|
import { applyOperation } from '../core/operations.js';
|
|
15
16
|
export const JSON_CODEC = {
|
|
@@ -17,7 +18,25 @@ export const JSON_CODEC = {
|
|
|
17
18
|
decode: (value) => normalizeLayout(value),
|
|
18
19
|
encode: (layout) => layout,
|
|
19
20
|
problems: () => [],
|
|
21
|
+
// A JSON field stores the layout exactly: a `null` prop (cleared) differs from a missing one.
|
|
22
|
+
isStored: (layout, value) => sameJson(layout, value),
|
|
20
23
|
};
|
|
24
|
+
/**
|
|
25
|
+
* A value without its `null` and `undefined` object keys, at every depth. Payload keeps a block
|
|
26
|
+
* row's stored value for a key the saved row leaves out, and reads unset fields (`blockName` too)
|
|
27
|
+
* as `null`: for a blocks field, a missing key and a `null` one store the same thing.
|
|
28
|
+
*/
|
|
29
|
+
function withoutNulls(value) {
|
|
30
|
+
if (Array.isArray(value))
|
|
31
|
+
return value.map(withoutNulls);
|
|
32
|
+
if (value === null || typeof value !== 'object')
|
|
33
|
+
return value;
|
|
34
|
+
const out = {};
|
|
35
|
+
for (const [key, v] of Object.entries(value))
|
|
36
|
+
if (v !== null && v !== undefined)
|
|
37
|
+
out[key] = withoutNulls(v);
|
|
38
|
+
return out;
|
|
39
|
+
}
|
|
21
40
|
/** The codec of the builder's JSON layout that upgrades old blocks (`BlockDefinition.upgrade`) on read. */
|
|
22
41
|
export function jsonCodec(blocks) {
|
|
23
42
|
return { ...JSON_CODEC, decode: (value) => upgradeLayout(normalizeLayout(value), blocks) };
|
|
@@ -36,6 +55,7 @@ export function payloadBlocksCodec(storage) {
|
|
|
36
55
|
},
|
|
37
56
|
encode: (layout, previous) => encodePayloadBlocks(layout, storage, previous),
|
|
38
57
|
problems: (layout) => payloadBlocksProblems(layout, storage),
|
|
58
|
+
isStored: (layout, value) => sameJson(withoutNulls(encodePayloadBlocks(layout, storage, value)), withoutNulls(value ?? [])),
|
|
39
59
|
prepare: (layout, ops, owned) => withUniqueRowIds(layout, ops, storage, owned),
|
|
40
60
|
rowIds: (value) => payloadRowIds(value, storage),
|
|
41
61
|
};
|
package/dist/mcp/index.js
CHANGED
|
@@ -14,7 +14,8 @@ import { createId } from '../core/ids.js';
|
|
|
14
14
|
import { VISIBILITY_OPERATORS } from '../core/visibility.js';
|
|
15
15
|
import { blockJsonSchema } from '../core/schema.js';
|
|
16
16
|
import { checkSectionVariants, getBlockDefinition, sectionsWithDefaultClassNames } from '../core/blocks.js';
|
|
17
|
-
import { findSectionVersion } from '../core/sections.js';
|
|
17
|
+
import { findSectionVersion, sectionsThatFit } from '../core/sections.js';
|
|
18
|
+
import { payloadBlocksProblems } from '../core/payloadBlocks.js';
|
|
18
19
|
import { localeSettingsOf, localizedKeys, resolveLayoutLocale, stampLocale, untranslatedKeys } from '../core/locale.js';
|
|
19
20
|
import { normalizeLayout, subtreeIds, walkBlocks } from '../core/tree.js';
|
|
20
21
|
import { runPropValidators } from '../core/fieldValidate.js';
|
|
@@ -242,6 +243,19 @@ async function variablesOf(req) {
|
|
|
242
243
|
const list = variableTokens(await themeVariablesOf(req.payload));
|
|
243
244
|
return list.length > 0 ? { variables: describeVariables(list), variablesNote: VARIABLES_NOTE } : {};
|
|
244
245
|
}
|
|
246
|
+
/** The collection's own Payload blocks field (the block types it holds), or undefined for a JSON layout. */
|
|
247
|
+
function storageOf(req, collection) {
|
|
248
|
+
return req?.payload?.config ? builderConfigOf(req.payload)?.collections[collection]?.payloadBlocks : undefined;
|
|
249
|
+
}
|
|
250
|
+
/** Why a Payload blocks field cannot store `list` (the first problem), else null. JSON layouts store everything. */
|
|
251
|
+
function sectionProblem(req, collection, list) {
|
|
252
|
+
const storage = storageOf(req, collection);
|
|
253
|
+
return storage ? (payloadBlocksProblems({ version: 1, blocks: list }, storage)[0] ?? null) : null;
|
|
254
|
+
}
|
|
255
|
+
/** The sections, and their variants, the collection's layout can store. */
|
|
256
|
+
function sectionsFor(req, collection, list) {
|
|
257
|
+
return storageOf(req, collection) ? sectionsThatFit(list, (b) => sectionProblem(req, collection, b) === null) : list;
|
|
258
|
+
}
|
|
245
259
|
export function builderMcpTools(options) {
|
|
246
260
|
const templateTargets = Object.entries(options.collections).filter(([, c]) => c.templates).map(([slug]) => slug);
|
|
247
261
|
const templatesSlug = templateTargets.length > 0 ? (options.templates?.slug ?? DEFAULT_TEMPLATES_SLUG) : null;
|
|
@@ -254,6 +268,8 @@ export function builderMcpTools(options) {
|
|
|
254
268
|
* settings and the field blocks of the forms collection), else the app's list.
|
|
255
269
|
*/
|
|
256
270
|
const blocksOf = (req) => (req?.payload?.config ? builderConfigOf(req.payload)?.blocks : undefined) ?? appBlocks;
|
|
271
|
+
/** The block types a collection's layout can hold: a Payload blocks field's own, else the whole list. */
|
|
272
|
+
const blocksFor = (req, collection) => storageOf(req, collection)?.blocks ?? blocksOf(req);
|
|
257
273
|
// A section block without a className gets its type's default classes, as in the plugin.
|
|
258
274
|
// Variants stay under their section (core/sections.ts); insertSection takes `variant`.
|
|
259
275
|
checkSectionVariants(options.sections ?? []);
|
|
@@ -415,23 +431,30 @@ export function builderMcpTools(options) {
|
|
|
415
431
|
name: 'listBlocks',
|
|
416
432
|
routing: { kind: 'collection', action: 'read' },
|
|
417
433
|
description: [
|
|
418
|
-
'Lists every block type you can use in
|
|
434
|
+
'Lists every block type you can use in the layouts of `collection`: label, description, props, slots (which child types they accept), parts and an example, plus the site\'s own classes and design variables (named colors, sizes and fonts). Call it once before you build or edit a layout: its `guide` is the layout format (block keys, ids, positions, classes, motion presets, HTML attrs, canonical form) and `bindings` the binding and VISIBILITY format.',
|
|
419
435
|
'For whole page parts (hero, features, pricing, call to action, footer), PREFER ready-made sections: listSections, then insertSection. Use single blocks for small additions and edits.',
|
|
436
|
+
'A collection whose layout is its own Payload blocks field holds only the block types listed for it: `rootTypes` go at the page root, the others only in the slots that accept them. Other collections differ: call it again for each collection.',
|
|
420
437
|
`Dynamic blocks: "${FIELD_BLOCK}" shows one field of the current document (templates), "${COLLECTION_LIST_BLOCK}" lists documents of a collection and repeats its "item" slot per document, "${REPEAT_BLOCK}" repeats its "item" slot per row of an array or hasMany field of the current document.`,
|
|
421
438
|
`Forms on pages (when the list has a "${FORM_BLOCK}" block): build a form right on the page. A "${FORM_BLOCK}" block in mode "build" holds its own field blocks (formText, formEmail, formTextarea, formSelect, formRadio, formCheckbox, …), one "${FORM_SUBMIT_BLOCK}" block and layout blocks in its "${FORM_SLOT}" slot. Field blocks and "${FORM_SUBMIT_BLOCK}" go only inside a Form block (at any depth). Each field's \`name\` is unique in its form. The form's settings (title, submitButtonLabel, confirmationType, confirmationMessage, redirect, emails, spamProtection) are props of the Form block. Publishing the page saves the form to the forms collection. Mode "saved" shows an existing form instead (\`form\`: its id).`,
|
|
422
439
|
].join('\n\n'),
|
|
423
440
|
parameters: { collection: collectionArg },
|
|
424
|
-
handler: async (
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
(
|
|
434
|
-
|
|
441
|
+
handler: async (args, req) => {
|
|
442
|
+
const collection = String(args.collection);
|
|
443
|
+
const storage = storageOf(req, collection);
|
|
444
|
+
return text({
|
|
445
|
+
guide: LAYOUT_GUIDE,
|
|
446
|
+
// A Payload blocks field: only its own block types, and the ones it allows at the page root.
|
|
447
|
+
blocks: blocksFor(req, collection).map(describeBlock),
|
|
448
|
+
...(storage ? { rootTypes: [...storage.rootTypes] } : {}),
|
|
449
|
+
...(await siteClassesOf(req)),
|
|
450
|
+
...(await variablesOf(req)),
|
|
451
|
+
sections: sectionsFor(req, collection, sections).length,
|
|
452
|
+
bindings: BINDINGS_GUIDE,
|
|
453
|
+
...(templatesSlug ? { templates: { collection: templatesSlug, targets: templateTargets } } : {}),
|
|
454
|
+
next: 'getBlockSchema for exact prop shapes. listSections for ready-made sections. getLayout to read a page.' +
|
|
455
|
+
(templatesSlug ? ' listTemplates and getBindingSources for templates.' : ''),
|
|
456
|
+
});
|
|
457
|
+
},
|
|
435
458
|
};
|
|
436
459
|
const getBlockSchema = {
|
|
437
460
|
name: 'getBlockSchema',
|
|
@@ -439,7 +462,7 @@ export function builderMcpTools(options) {
|
|
|
439
462
|
description: 'Returns the JSON Schema (draft 2020-12) of one block type: its props, className, slots and motion (animations, under $defs.$motion), with nested child block schemas under $defs. Use it to write valid props.',
|
|
440
463
|
parameters: { collection: collectionArg, type: z.string().min(1).describe('Block type from listBlocks.') },
|
|
441
464
|
handler: async (args, req) => {
|
|
442
|
-
const blocks =
|
|
465
|
+
const blocks = blocksFor(req, String(args.collection));
|
|
443
466
|
const def = blocks.find((b) => b.type === args.type);
|
|
444
467
|
if (!def)
|
|
445
468
|
return fail(`Unknown block type "${String(args.type)}". Known types: ${blocks.map((b) => b.type).join(', ')}.`);
|
|
@@ -461,8 +484,8 @@ export function builderMcpTools(options) {
|
|
|
461
484
|
full: z.boolean().optional().describe('Include the full block JSON. Default false.'),
|
|
462
485
|
},
|
|
463
486
|
handler: async (args, req) => {
|
|
464
|
-
const blocks =
|
|
465
|
-
const all = await allSections(req);
|
|
487
|
+
const blocks = blocksFor(req, String(args.collection));
|
|
488
|
+
const all = sectionsFor(req, String(args.collection), await allSections(req));
|
|
466
489
|
const list = all.filter((s) => !args.category || s.category === args.category);
|
|
467
490
|
return text({
|
|
468
491
|
categories: [...new Set(all.map((s) => s.category).filter(Boolean))],
|
|
@@ -509,19 +532,23 @@ export function builderMcpTools(options) {
|
|
|
509
532
|
.describe('Saved sections only. true: a copy that stays in sync with the saved section (default for components). false: plain blocks.'),
|
|
510
533
|
},
|
|
511
534
|
handler: async (args, req) => {
|
|
512
|
-
const
|
|
535
|
+
const collection = String(args.collection);
|
|
536
|
+
const blocks = blocksFor(req, collection);
|
|
513
537
|
const all = await allSections(req);
|
|
514
538
|
const found = findSectionVersion(all, String(args.sectionId), typeof args.variant === 'string' ? args.variant : undefined);
|
|
515
539
|
if (typeof found === 'string')
|
|
516
540
|
return fail(found);
|
|
517
541
|
if (!found) {
|
|
518
|
-
const known = all.map((s) => (s.savedId !== undefined ? `${s.id} ("${s.label}")` : s.id));
|
|
542
|
+
const known = sectionsFor(req, collection, all).map((s) => (s.savedId !== undefined ? `${s.id} ("${s.label}")` : s.id));
|
|
519
543
|
return fail(`Unknown section "${String(args.sectionId)}". Known sections: ${known.join(', ') || 'none'}.`);
|
|
520
544
|
}
|
|
545
|
+
// A Payload blocks field: refused before the commit, with the reason (listSections leaves it out).
|
|
546
|
+
const unfit = sectionProblem(req, collection, found.blocks);
|
|
547
|
+
if (unfit)
|
|
548
|
+
return fail(`Section "${found.label}" cannot go in "${collection}": ${unfit} listSections lists the sections this collection can hold.`);
|
|
521
549
|
const section = sectionToInsert(found, blocks, { values: args.values, linked: typeof args.linked === 'boolean' ? args.linked : null });
|
|
522
550
|
if (typeof section === 'string')
|
|
523
551
|
return fail(section);
|
|
524
|
-
const collection = String(args.collection);
|
|
525
552
|
const result = await apply(req, collection, String(args.id), (layout) => sectionInsertOps(layout, section, {
|
|
526
553
|
parentId: args.parentId,
|
|
527
554
|
slot: args.slot,
|
package/dist/mcp/shared.js
CHANGED
|
@@ -42,22 +42,22 @@ export function motionGuide() {
|
|
|
42
42
|
* (a tool name, or "the block catalog").
|
|
43
43
|
*/
|
|
44
44
|
export function layoutGuide(blocksFrom) {
|
|
45
|
-
return `
|
|
46
|
-
LAYOUT MODEL. A layout is JSON: { "version": 1, "blocks": Block[] }. A Block is { id, type, props?, className?, slots?, bindings?, visibility?, hidden?, motion?, attrs?, partClassName? }.
|
|
47
|
-
- id: a string, unique in the whole layout. Operations target blocks by id, never by array index. New blocks need new ids: use "b_" plus 6 lowercase letters or digits (e.g. "b_k3x9qa").
|
|
48
|
-
- type: a block type from ${blocksFrom}.
|
|
49
|
-
- props: the block's own values. Get the exact shape with getBlockSchema. Upload and relationship props hold document IDs.
|
|
50
|
-
- className: Tailwind CSS v4 utility classes, with variants such as md:, lg:, hover:, dark:. Theme classes work (bg-primary, text-primary-foreground, text-muted-foreground, font-heading). CSS is generated on save, so any valid class works. In "update", className replaces the whole list; addClassName and removeClassName (space-separated) change single classes and keep the rest.
|
|
51
|
-
- slots: child blocks by slot name, e.g. { "children": [ ...blocks ] }. Only block types with slots take children. ${blocksFrom} shows which types each slot accepts. A type with "onlyInside" goes only directly inside those types (e.g. "listItem" only in a "list"). A slot with "maxBlocks" holds at most that many direct children: inserting into a full slot fails, so replace (update or remove) the block there instead. A slot with "minBlocks" needs that many before the page can be published.
|
|
52
|
-
- bindings: (templates, and blocks inside the "item" slot of a collection list or repeat, only) prop path -> document field path, e.g. { "text": "title" }, { "image": "featuredImage" }, { "link": "$url" }. At render time the prop takes the document's value; when the document has no value the literal prop stays. Get field paths from getBindingSources.
|
|
53
|
-
- visibility: (templates, and blocks inside the "item" slot of a collection list or repeat, only) conditions that show the block only when they match the document (see VISIBILITY in the bindings guide). Leave it out when the block always shows.
|
|
54
|
-
- On a normal page, outside list and repeat items, there is no current document: bindings and visibility do nothing (the block always shows), and the tools return a "no-effect" warning. Use "hidden": true to hide a block there.
|
|
55
|
-
- motion: animations of the block (see MOTION below). Leave it out when the block has none.
|
|
56
|
-
- partClassName: Tailwind classes of a block's inner elements, by part name, e.g. { "empty": "col-span-full text-center" } on a collection list or { "arrow": "size-12 rounded-full bg-white" } on a carousel. Only the "parts" listed in ${blocksFrom} take them. In "update" it merges per part; null removes a part's classes.
|
|
57
|
-
- attrs: HTML attributes of the block element: { id?, ariaLabel?, ariaHidden? }. "id" is an anchor for "#id" links (e.g. "contact"), unique in the layout, letters, digits, - and _, starting with a letter; never the block id. "ariaLabel" names the element for screen readers (e.g. a nav or an icon-only link). "ariaHidden": true hides decorative blocks from screen readers. Copies of a section or a block leave out an id the page already uses.
|
|
58
|
-
- section: { id, variant? } on the root block of a ready-made section, set by insertSection. Editors use it to switch the section to another variant. Keep it as it is; never write it yourself.
|
|
59
|
-
- Canonical form: leave out empty props, slots, bindings, visibility and motion objects and empty slot lists. Set hidden only when true.
|
|
60
|
-
POSITION = { parentId, slot?, index }. parentId null means the page root, whose only slot is "children". slot defaults to "children". index is the block's FINAL index in the target list (0 = first; the list length = append). For a move inside the same list, count positions after the block is taken out.
|
|
45
|
+
return `
|
|
46
|
+
LAYOUT MODEL. A layout is JSON: { "version": 1, "blocks": Block[] }. A Block is { id, type, props?, className?, slots?, bindings?, visibility?, hidden?, motion?, attrs?, partClassName? }.
|
|
47
|
+
- id: a string, unique in the whole layout. Operations target blocks by id, never by array index. New blocks need new ids: use "b_" plus 6 lowercase letters or digits (e.g. "b_k3x9qa").
|
|
48
|
+
- type: a block type from ${blocksFrom}.
|
|
49
|
+
- props: the block's own values. Get the exact shape with getBlockSchema. Upload and relationship props hold document IDs.
|
|
50
|
+
- className: Tailwind CSS v4 utility classes, with variants such as md:, lg:, hover:, dark:. Theme classes work (bg-primary, text-primary-foreground, text-muted-foreground, font-heading). CSS is generated on save, so any valid class works. In "update", className replaces the whole list; addClassName and removeClassName (space-separated) change single classes and keep the rest.
|
|
51
|
+
- slots: child blocks by slot name, e.g. { "children": [ ...blocks ] }. Only block types with slots take children. ${blocksFrom} shows which types each slot accepts. A type with "onlyInside" goes only directly inside those types (e.g. "listItem" only in a "list"). A slot with "maxBlocks" holds at most that many direct children: inserting into a full slot fails, so replace (update or remove) the block there instead. A slot with "minBlocks" needs that many before the page can be published.
|
|
52
|
+
- bindings: (templates, and blocks inside the "item" slot of a collection list or repeat, only) prop path -> document field path, e.g. { "text": "title" }, { "image": "featuredImage" }, { "link": "$url" }. At render time the prop takes the document's value; when the document has no value the literal prop stays. Get field paths from getBindingSources.
|
|
53
|
+
- visibility: (templates, and blocks inside the "item" slot of a collection list or repeat, only) conditions that show the block only when they match the document (see VISIBILITY in the bindings guide). Leave it out when the block always shows.
|
|
54
|
+
- On a normal page, outside list and repeat items, there is no current document: bindings and visibility do nothing (the block always shows), and the tools return a "no-effect" warning. Use "hidden": true to hide a block there.
|
|
55
|
+
- motion: animations of the block (see MOTION below). Leave it out when the block has none.
|
|
56
|
+
- partClassName: Tailwind classes of a block's inner elements, by part name, e.g. { "empty": "col-span-full text-center" } on a collection list or { "arrow": "size-12 rounded-full bg-white" } on a carousel. Only the "parts" listed in ${blocksFrom} take them. In "update" it merges per part; null removes a part's classes.
|
|
57
|
+
- attrs: HTML attributes of the block element: { id?, ariaLabel?, ariaHidden? }. "id" is an anchor for "#id" links (e.g. "contact"), unique in the layout, letters, digits, - and _, starting with a letter; never the block id. "ariaLabel" names the element for screen readers (e.g. a nav or an icon-only link). "ariaHidden": true hides decorative blocks from screen readers. Copies of a section or a block leave out an id the page already uses.
|
|
58
|
+
- section: { id, variant? } on the root block of a ready-made section, set by insertSection. Editors use it to switch the section to another variant. Keep it as it is; never write it yourself.
|
|
59
|
+
- Canonical form: leave out empty props, slots, bindings, visibility and motion objects and empty slot lists. Set hidden only when true.
|
|
60
|
+
POSITION = { parentId, slot?, index }. parentId null means the page root, whose only slot is "children". slot defaults to "children". index is the block's FINAL index in the target list (0 = first; the list length = append). For a move inside the same list, count positions after the block is taken out.
|
|
61
61
|
${motionGuide()}`.trim();
|
|
62
62
|
}
|
|
63
63
|
export const BINDINGS_GUIDE = [
|