payload-canvas 0.2.0 → 0.4.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.
Files changed (170) hide show
  1. package/README.md +500 -25
  2. package/dist/admin/diff/changes.js +8 -0
  3. package/dist/admin/editor/Inspector.js +49 -4
  4. package/dist/admin/editor/Outline.js +12 -10
  5. package/dist/admin/editor/actions.d.ts +9 -1
  6. package/dist/admin/editor/actions.js +38 -3
  7. package/dist/admin/editor/empty/EmptyStart.js +29 -3
  8. package/dist/admin/editor/fields/GroupField.d.ts +5 -2
  9. package/dist/admin/editor/fields/GroupField.js +6 -2
  10. package/dist/admin/editor/fields/WhereField.d.ts +17 -0
  11. package/dist/admin/editor/fields/WhereField.js +67 -0
  12. package/dist/admin/editor/fields/fields.scss +89 -0
  13. package/dist/admin/editor/fields/whereRows.d.ts +28 -0
  14. package/dist/admin/editor/fields/whereRows.js +118 -0
  15. package/dist/admin/editor/icons.d.ts +1 -0
  16. package/dist/admin/editor/icons.js +2 -0
  17. package/dist/admin/editor/locale/LocaleField.d.ts +1 -1
  18. package/dist/admin/editor/locale/LocaleField.js +3 -1
  19. package/dist/admin/editor/menu/blockMenu.js +5 -1
  20. package/dist/admin/editor/motion/MotionPanel.js +1 -1
  21. package/dist/admin/editor/motion/model.js +2 -2
  22. package/dist/admin/editor/renderField.d.ts +3 -1
  23. package/dist/admin/editor/renderField.js +13 -4
  24. package/dist/admin/editor/runtime.js +1 -0
  25. package/dist/admin/editor/styles/SiteClasses.d.ts +9 -0
  26. package/dist/admin/editor/styles/SiteClasses.js +31 -0
  27. package/dist/admin/editor/styles/StylesPanel.d.ts +3 -1
  28. package/dist/admin/editor/styles/StylesPanel.js +9 -6
  29. package/dist/admin/editor/styles/context.d.ts +9 -2
  30. package/dist/admin/editor/styles/context.js +14 -9
  31. package/dist/admin/editor/styles/controls.js +2 -2
  32. package/dist/admin/editor/styles/sections.js +1 -1
  33. package/dist/admin/editor/styles/styles.scss +54 -0
  34. package/dist/admin/editor/templates/Bindable.d.ts +13 -5
  35. package/dist/admin/editor/templates/Bindable.js +73 -17
  36. package/dist/admin/editor/templates/binding.d.ts +11 -4
  37. package/dist/admin/editor/templates/binding.js +23 -3
  38. package/dist/ai/prompt.js +8 -2
  39. package/dist/ai/tools.js +11 -2
  40. package/dist/blocks/builtins/carousel.d.ts +32 -0
  41. package/dist/blocks/builtins/carousel.js +122 -0
  42. package/dist/blocks/builtins/disclosure.d.ts +13 -0
  43. package/dist/blocks/builtins/disclosure.js +107 -0
  44. package/dist/blocks/builtins/faq.d.ts +17 -0
  45. package/dist/blocks/builtins/faq.js +88 -0
  46. package/dist/blocks/builtins/filterLink.d.ts +22 -0
  47. package/dist/blocks/builtins/filterLink.js +76 -0
  48. package/dist/blocks/builtins/headingId.d.ts +15 -0
  49. package/dist/blocks/builtins/headingId.js +36 -0
  50. package/dist/blocks/builtins/icon.d.ts +8 -0
  51. package/dist/blocks/builtins/icon.js +45 -0
  52. package/dist/blocks/builtins/index.d.ts +35 -0
  53. package/dist/blocks/builtins/index.js +50 -0
  54. package/dist/blocks/builtins/lightbox.d.ts +43 -0
  55. package/dist/blocks/builtins/lightbox.js +93 -0
  56. package/dist/blocks/builtins/mediaBackdrop.d.ts +11 -0
  57. package/dist/blocks/builtins/mediaBackdrop.js +79 -0
  58. package/dist/blocks/builtins/sectionRef.d.ts +26 -0
  59. package/dist/blocks/builtins/sectionRef.js +78 -0
  60. package/dist/blocks/builtins/shared.d.ts +33 -0
  61. package/dist/blocks/builtins/shared.js +70 -0
  62. package/dist/blocks/builtins/tableOfContents.d.ts +3 -0
  63. package/dist/blocks/builtins/tableOfContents.js +44 -0
  64. package/dist/blocks/defaults.d.ts +19 -1
  65. package/dist/blocks/defaults.js +413 -20
  66. package/dist/blocks/index.d.ts +4 -2
  67. package/dist/blocks/index.js +3 -1
  68. package/dist/core/attrs.d.ts +27 -0
  69. package/dist/core/attrs.js +132 -0
  70. package/dist/core/bindings.d.ts +122 -11
  71. package/dist/core/bindings.js +504 -19
  72. package/dist/core/blocks.d.ts +46 -1
  73. package/dist/core/blocks.js +136 -0
  74. package/dist/core/classes.d.ts +10 -2
  75. package/dist/core/classes.js +34 -5
  76. package/dist/core/headings.d.ts +21 -0
  77. package/dist/core/headings.js +47 -0
  78. package/dist/core/index.d.ts +4 -2
  79. package/dist/core/index.js +4 -2
  80. package/dist/core/motion.d.ts +18 -9
  81. package/dist/core/motion.js +20 -12
  82. package/dist/core/operations.js +59 -2
  83. package/dist/core/payloadBlocks.js +3 -1
  84. package/dist/core/schema.js +20 -0
  85. package/dist/core/tree.js +24 -1
  86. package/dist/core/types.d.ts +87 -0
  87. package/dist/core/validate.js +29 -4
  88. package/dist/css/tokens.d.ts +6 -3
  89. package/dist/css/tokens.js +48 -2
  90. package/dist/index.d.ts +3 -3
  91. package/dist/index.js +2 -2
  92. package/dist/mcp/index.d.ts +2 -0
  93. package/dist/mcp/index.js +50 -13
  94. package/dist/mcp/shared.d.ts +3 -0
  95. package/dist/mcp/shared.js +23 -8
  96. package/dist/plugin/index.d.ts +8 -0
  97. package/dist/plugin/index.js +26 -8
  98. package/dist/plugin/listCollections.d.ts +17 -2
  99. package/dist/plugin/listCollections.js +44 -7
  100. package/dist/plugin/references.d.ts +5 -0
  101. package/dist/plugin/references.js +1 -1
  102. package/dist/plugin/templates.d.ts +4 -0
  103. package/dist/plugin/templates.js +23 -4
  104. package/dist/protocol/index.d.ts +2 -0
  105. package/dist/react/canvas/BuilderCanvas.js +5 -3
  106. package/dist/react/canvas/fetchDocs.d.ts +16 -2
  107. package/dist/react/canvas/fetchDocs.js +42 -9
  108. package/dist/react/canvas/measure.d.ts +3 -1
  109. package/dist/react/canvas/measure.js +26 -2
  110. package/dist/react/canvas/resolveLayout.d.ts +1 -1
  111. package/dist/react/canvas/resolveLayout.js +17 -6
  112. package/dist/react/canvas/serverBlocks.d.ts +11 -0
  113. package/dist/react/canvas/serverBlocks.js +28 -1
  114. package/dist/react/components/Button.d.ts +11 -2
  115. package/dist/react/components/Button.js +43 -6
  116. package/dist/react/components/CollectionList.d.ts +6 -3
  117. package/dist/react/components/CollectionList.js +21 -7
  118. package/dist/react/components/Container.js +4 -1
  119. package/dist/react/components/Field.js +13 -2
  120. package/dist/react/components/Heading.js +9 -2
  121. package/dist/react/components/Image.d.ts +9 -0
  122. package/dist/react/components/Image.js +16 -1
  123. package/dist/react/components/List.d.ts +1 -0
  124. package/dist/react/components/List.js +6 -0
  125. package/dist/react/components/Menu.d.ts +16 -0
  126. package/dist/react/components/Menu.js +83 -19
  127. package/dist/react/components/RichText.d.ts +8 -3
  128. package/dist/react/components/RichText.js +25 -4
  129. package/dist/react/components/builtins/Accordion.d.ts +9 -0
  130. package/dist/react/components/builtins/Accordion.js +37 -0
  131. package/dist/react/components/builtins/BackdropVideo.d.ts +13 -0
  132. package/dist/react/components/builtins/BackdropVideo.js +16 -0
  133. package/dist/react/components/builtins/Carousel.d.ts +13 -0
  134. package/dist/react/components/builtins/Carousel.js +134 -0
  135. package/dist/react/components/builtins/Disclosure.d.ts +7 -0
  136. package/dist/react/components/builtins/Disclosure.js +13 -0
  137. package/dist/react/components/builtins/FilterLink.d.ts +8 -0
  138. package/dist/react/components/builtins/FilterLink.js +30 -0
  139. package/dist/react/components/builtins/Icon.d.ts +14 -0
  140. package/dist/react/components/builtins/Icon.js +28 -0
  141. package/dist/react/components/builtins/Lightbox.d.ts +45 -0
  142. package/dist/react/components/builtins/Lightbox.js +252 -0
  143. package/dist/react/components/builtins/MediaBackdrop.d.ts +14 -0
  144. package/dist/react/components/builtins/MediaBackdrop.js +61 -0
  145. package/dist/react/components/builtins/SectionRef.d.ts +7 -0
  146. package/dist/react/components/builtins/SectionRef.js +17 -0
  147. package/dist/react/components/builtins/TableOfContents.d.ts +7 -0
  148. package/dist/react/components/builtins/TableOfContents.js +21 -0
  149. package/dist/react/components/builtins/glyphs.d.ts +8 -0
  150. package/dist/react/components/builtins/glyphs.js +7 -0
  151. package/dist/react/components/builtins/index.d.ts +32 -0
  152. package/dist/react/components/builtins/index.js +36 -0
  153. package/dist/react/components/index.js +2 -0
  154. package/dist/react/index.d.ts +3 -1
  155. package/dist/react/index.js +3 -1
  156. package/dist/react/motion/runtime.js +10 -6
  157. package/dist/react/render/RenderLayout.d.ts +1 -1
  158. package/dist/react/render/RenderLayout.js +76 -23
  159. package/dist/react/render/lists.d.ts +107 -5
  160. package/dist/react/render/lists.js +284 -9
  161. package/dist/react/render/resolve.d.ts +22 -2
  162. package/dist/react/render/resolve.js +45 -22
  163. package/dist/react/render/sections.d.ts +9 -0
  164. package/dist/react/render/sections.js +51 -0
  165. package/dist/react/render/types.d.ts +6 -1
  166. package/dist/react/server.d.ts +3 -1
  167. package/dist/react/server.js +53 -2
  168. package/dist/react/theme/ThemeStyle.d.ts +13 -2
  169. package/dist/react/theme/ThemeStyle.js +12 -2
  170. package/package.json +1 -1
package/dist/core/tree.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { checkAttrs } from './attrs.js';
1
2
  import { createId } from './ids.js';
2
3
  import { normalizeMotion } from './motion.js';
3
4
  import { migrateTextList } from './textList.js';
@@ -71,10 +72,12 @@ export function subtreeIds(block, out = []) {
71
72
  // - `hidden` is stored only when true, `label` only when non-empty (trimmed)
72
73
  // - `locales` holds no empty locale objects, and is left out when empty
73
74
  // - `motion` holds only valid kinds and values (motion.ts), and is left out when empty
75
+ // - `attrs` holds only valid, non-empty values (attrs.ts), and is left out when empty
76
+ // - `slotClassName` holds only non-blank class strings, and is left out when empty
74
77
  // - every id is a non-empty string, unique in the layout
75
78
  // - old list blocks (`props.items` rows) hold `listItem` blocks in their `items` slot (textList.ts)
76
79
  // The operations module relies on this form for exact undo.
77
- const BLOCK_KEYS = new Set(['id', 'type', 'blockType', 'blockName', 'props', 'className', 'slots', 'children', 'bindings', 'hidden', 'label', 'locales', 'motion']);
80
+ const BLOCK_KEYS = new Set(['id', 'type', 'blockType', 'blockName', 'props', 'className', 'slots', 'children', 'bindings', 'hidden', 'label', 'locales', 'motion', 'attrs', 'slotClassName']);
78
81
  export function isPlainObject(value) {
79
82
  if (typeof value !== 'object' || value === null || Array.isArray(value))
80
83
  return false;
@@ -173,10 +176,30 @@ function normalizeBlock(value, seen) {
173
176
  const motion = normalizeMotion(value.motion);
174
177
  if (motion)
175
178
  block.motion = motion;
179
+ // A bad value is dropped key by key: a stored layout never fails to load.
180
+ const attrs = normalizeAttrs(value.attrs);
181
+ if (attrs)
182
+ block.attrs = attrs;
183
+ if (isPlainObject(value.slotClassName)) {
184
+ const kept = Object.fromEntries(Object.entries(value.slotClassName).filter(([, v]) => typeof v === 'string' && v.trim() !== ''));
185
+ if (Object.keys(kept).length > 0)
186
+ block.slotClassName = kept;
187
+ }
176
188
  // Old shapes of built-in blocks (see textList.ts).
177
189
  migrateTextList(block, (raw) => uniqueId(raw, seen));
178
190
  return block;
179
191
  }
192
+ function normalizeAttrs(value) {
193
+ if (!isPlainObject(value))
194
+ return undefined;
195
+ const kept = {};
196
+ for (const key of ['id', 'ariaLabel', 'ariaHidden']) {
197
+ const one = checkAttrs({ [key]: value[key] });
198
+ if (one && typeof one !== 'string')
199
+ Object.assign(kept, one);
200
+ }
201
+ return Object.keys(kept).length > 0 ? kept : undefined;
202
+ }
180
203
  function normalizeProps(value) {
181
204
  let source = null;
182
205
  if (isPlainObject(value.props)) {
@@ -34,6 +34,30 @@ export type Block = {
34
34
  * Stored only when it holds a kind.
35
35
  */
36
36
  motion?: BlockMotion;
37
+ /**
38
+ * HTML attributes of the block's root element (`core/attrs.ts`). Payload reserves `id` inside
39
+ * blocks, so they live here. Stored only when one is set.
40
+ */
41
+ attrs?: BlockAttrs;
42
+ /**
43
+ * Tailwind classes of a slot's own element, by slot name, for slots whose definition sets
44
+ * `styles: true` (e.g. the `empty` slot of a collection list). Compiled like `className`.
45
+ * Stored only when one is set.
46
+ */
47
+ slotClassName?: Record<string, string>;
48
+ };
49
+ /** A block's own HTML attributes. Empty values are left out. */
50
+ export type BlockAttrs = {
51
+ /** The element's `id`, for `#anchor` links. Unique in the layout. Letters, digits, "-" and "_", starting with a letter. */
52
+ id?: string;
53
+ /** `aria-label`: the element's name for screen readers. */
54
+ ariaLabel?: string;
55
+ /** `aria-hidden="true"`: screen readers skip the element (decorative shapes, repeated links). */
56
+ ariaHidden?: boolean;
57
+ };
58
+ /** An update of `attrs`: a key replaces that key, `null` removes it, keys left out stay. */
59
+ export type BlockAttrsPatch = {
60
+ [K in keyof BlockAttrs]?: BlockAttrs[K] | null;
37
61
  };
38
62
  export type Layout = {
39
63
  version: 1;
@@ -57,6 +81,17 @@ export type SlotDefinition = {
57
81
  max?: number;
58
82
  /** Fewest direct children the slot needs (Payload's `minRows`). Fewer blocks only publishing. */
59
83
  min?: number;
84
+ /**
85
+ * With `allow`: the slot also accepts every block type whose definition sets `inline: true`
86
+ * (`withInlineBlocks` adds them to `allow`). The link block's content slot sets it.
87
+ */
88
+ allowInline?: boolean;
89
+ /**
90
+ * The slot renders in an element of its own that takes classes (`block.slotClassName[slot]`).
91
+ * The Styles panel then offers the slot as a style target. The component spreads
92
+ * `slotAttributes[slot]` (which carries the `className`) on that element. Default false.
93
+ */
94
+ styles?: boolean;
60
95
  };
61
96
  export type BlockDefinition = {
62
97
  type: string;
@@ -71,6 +106,11 @@ export type BlockDefinition = {
71
106
  parents?: string[];
72
107
  /** Adds `className` and the style controls. Default true. */
73
108
  styles?: boolean;
109
+ /**
110
+ * The block renders no link, button or other control of its own, so it may sit inside a link
111
+ * (an icon, a badge, a rating). Slots with `allowInline` accept it. Default false.
112
+ */
113
+ inline?: boolean;
74
114
  /** Classes a newly inserted block starts with (e.g. "flex flex-col gap-4" for a stack). */
75
115
  defaultClassName?: string;
76
116
  /**
@@ -110,6 +150,22 @@ export type SectionDefinition = {
110
150
  * the saved sections collection. The section's own `id` is then `saved:<savedId>`.
111
151
  */
112
152
  savedId?: string | number;
153
+ /**
154
+ * Other versions of the section in the same file (a split hero next to a centred one). The
155
+ * plugin and `builderMcpTools` list each variant as a section of its own after this one
156
+ * (`sectionsWithVariants`): id `<id>/<variant id>`, label `<label> (<variant label>)`.
157
+ */
158
+ variants?: SectionVariant[];
159
+ /** Set on a variant after `sectionsWithVariants`: the id of the section it belongs to. */
160
+ variantOf?: string;
161
+ };
162
+ /** One version of a section (`SectionDefinition.variants`). It shares the section's category. */
163
+ export type SectionVariant = {
164
+ /** Unique in the section, e.g. "split". The variant's section id is `<section id>/<id>`. */
165
+ id: string;
166
+ label: string;
167
+ description?: string;
168
+ blocks: Block[];
113
169
  };
114
170
  /** The saved sections collection, for the editor. Null when `websiteBuilder({ savedSections: false })`. */
115
171
  export type SavedSectionsClientConfig = {
@@ -142,6 +198,14 @@ export type TemplatesClientConfig = {
142
198
  export type TemplateContext = {
143
199
  collection: string;
144
200
  doc: Record<string, any>;
201
+ /** Inside a repeat item: the row value itself (`$item`). */
202
+ item?: unknown;
203
+ /** Inside a collection list or repeat item: the item's number, from 1 (`$index`). */
204
+ index?: number;
205
+ /** Inside a collection list or repeat item: the enclosing document (`$parent.`). */
206
+ parent?: Record<string, any>;
207
+ /** Inside a collection list or repeat item: the page's own document (`$page.`). Else `doc` is the page. */
208
+ page?: Record<string, any>;
145
209
  };
146
210
  /**
147
211
  * Set by the plugin on the layout field as `admin.custom.builder` (field `admin.custom` reaches
@@ -202,6 +266,11 @@ export type BuilderClientConfig = {
202
266
  storage?: 'payload-blocks';
203
267
  /** With `storage: 'payload-blocks'`: the block types the field allows at its top level. */
204
268
  payloadRootTypes?: string[];
269
+ /**
270
+ * Collection -> relationship field path -> related collection (`bindingRelations`), so the
271
+ * canvas resolves `<path>.$url` bindings as the site does.
272
+ */
273
+ relations?: Record<string, Record<string, string>>;
205
274
  };
206
275
  /** One document field a region shows. */
207
276
  export type RegionField = {
@@ -298,6 +367,20 @@ export type StyleTokens = {
298
367
  containers: ThemeToken[];
299
368
  /** Every utility class name the design system knows (for autocomplete), without variants. */
300
369
  classList: string[];
370
+ /**
371
+ * The site's own static `@utility` classes (`type-h2`, `btn-primary`, `glass`), in CSS order, from
372
+ * the CSS entry and the files it imports (not from packages). The Styles panel lists them as
373
+ * presets. Left out by servers before this field existed.
374
+ */
375
+ siteClasses?: SiteClass[];
376
+ };
377
+ /** One `@utility` class of the site. A `/* @canvas Group: Label *\/` comment right above the rule sets `label` and `group`. */
378
+ export type SiteClass = {
379
+ name: string;
380
+ label?: string;
381
+ group?: string;
382
+ /** The rule's declarations, shortened, for a preview in the editor. */
383
+ css: string;
301
384
  };
302
385
  /**
303
386
  * Where a block goes. `parentId: null` means the root list (`layout.blocks`).
@@ -357,6 +440,10 @@ export type Operation = {
357
440
  * kinds left out stay. `motion: null` removes all motion.
358
441
  */
359
442
  motion?: MotionPatch | null;
443
+ /** HTML attributes. Each key given replaces that key, `null` removes it. `attrs: null` removes all. */
444
+ attrs?: BlockAttrsPatch | null;
445
+ /** Classes per slot. Each slot given replaces that slot's classes, `null` or "" removes them. */
446
+ slotClassName?: Record<string, string | null>;
360
447
  };
361
448
  /** `inverse` undoes this operation when applied in order to the resulting layout. */
362
449
  export type ApplyResult = {
@@ -1,6 +1,7 @@
1
1
  // Layout validation without external libraries. Mirrors the JSON Schema from schema.ts, plus
2
2
  // the rules a schema cannot express (unique ids). Optional props may be `null` (Payload's own
3
3
  // "empty" value); the schema leaves that out to keep it simple for AI tools.
4
+ import { checkAttrs } from './attrs.js';
4
5
  import { getBlockDefinition, slotLabel, slotLimitText } from './blocks.js';
5
6
  import { conditionMet, readCondition } from './conditions.js';
6
7
  import { formatProblem } from './formats.js';
@@ -20,7 +21,7 @@ export function isBlockingError(error, publishing) {
20
21
  return false;
21
22
  return publishing || !PUBLISH_ONLY_CODES.has(error.code);
22
23
  }
23
- const BLOCK_KEYS = new Set(['id', 'type', 'props', 'className', 'slots', 'bindings', 'hidden', 'label', 'locales', 'motion']);
24
+ const BLOCK_KEYS = new Set(['id', 'type', 'props', 'className', 'slots', 'bindings', 'hidden', 'label', 'locales', 'motion', 'attrs', 'slotClassName']);
24
25
  /** Checks structure, unique ids, known block types, slot rules and prop types. */
25
26
  export function validateLayout(layout, blocks, options = {}) {
26
27
  const errors = [];
@@ -34,11 +35,12 @@ export function validateLayout(layout, blocks, options = {}) {
34
35
  }
35
36
  const seen = new Set();
36
37
  const localization = options.localization ?? null;
37
- layout.blocks.forEach((block, i) => checkBlock(block, `blocks[${i}]`, null, [], blocks, seen, errors, localization));
38
+ const htmlIds = new Map();
39
+ layout.blocks.forEach((block, i) => checkBlock(block, `blocks[${i}]`, null, [], blocks, seen, errors, localization, htmlIds));
38
40
  return errors;
39
41
  }
40
42
  const nameOf = (value, def, type) => (typeof value.label === 'string' && value.label.trim()) || def?.label || type;
41
- function checkBlock(value, path, owner, banned, blocks, seen, errors, localization) {
43
+ function checkBlock(value, path, owner, banned, blocks, seen, errors, localization, htmlIds) {
42
44
  if (!isPlainObject(value)) {
43
45
  errors.push({ path, message: 'Block must be an object', code: 'invalid' });
44
46
  return;
@@ -97,12 +99,35 @@ function checkBlock(value, path, owner, banned, blocks, seen, errors, localizati
97
99
  else if (def?.styles === false)
98
100
  report(`${path}.className`, `Block type "${type}" does not take a className`);
99
101
  }
102
+ if (value.slotClassName !== undefined) {
103
+ if (!isPlainObject(value.slotClassName))
104
+ report(`${path}.slotClassName`, 'slotClassName must be an object of slot name -> classes');
105
+ else {
106
+ for (const [slot, classes] of Object.entries(value.slotClassName)) {
107
+ if (typeof classes !== 'string')
108
+ report(`${path}.slotClassName.${slot}`, 'Slot classes must be a string');
109
+ else if (def && !def.slots?.[slot]?.styles)
110
+ report(`${path}.slotClassName.${slot}`, `The "${slot}" slot of ${def.label} takes no classes`);
111
+ }
112
+ }
113
+ }
100
114
  if (value.hidden !== undefined && typeof value.hidden !== 'boolean') {
101
115
  report(`${path}.hidden`, 'hidden must be a boolean');
102
116
  }
103
117
  if (value.label !== undefined && typeof value.label !== 'string') {
104
118
  report(`${path}.label`, 'label must be a string');
105
119
  }
120
+ const attrs = checkAttrs(value.attrs);
121
+ if (typeof attrs === 'string')
122
+ report(`${path}.attrs`, attrs);
123
+ else if (attrs?.id) {
124
+ // Publish-only: a page with two equal anchors still saves as a draft.
125
+ const usedBy = htmlIds.get(attrs.id);
126
+ if (usedBy)
127
+ report(`${path}.attrs.id`, `The HTML id "${attrs.id}" is also used by block "${usedBy}". Every id is unique in a layout.`, 'constraint');
128
+ else
129
+ htmlIds.set(attrs.id, blockId ?? path);
130
+ }
106
131
  for (const problem of motionProblems(value.motion)) {
107
132
  report(`${path}.${problem.path}`, problem.message, problem.unknown ? 'unknown-key' : 'invalid');
108
133
  }
@@ -136,7 +161,7 @@ function checkBlock(value, path, owner, banned, blocks, seen, errors, localizati
136
161
  const label = nameOf(value, def, type ?? '');
137
162
  const childOwner = slotDef && type ? { type, label, slot: name, def: slotDef } : null;
138
163
  const childBanned = slotDef?.disallow?.length ? [...banned, ...slotDef.disallow.map((t) => ({ type: t, by: label }))] : banned;
139
- children.forEach((child, i) => checkBlock(child, `${slotPath}[${i}]`, childOwner, childBanned, blocks, seen, errors, localization));
164
+ children.forEach((child, i) => checkBlock(child, `${slotPath}[${i}]`, childOwner, childBanned, blocks, seen, errors, localization, htmlIds));
140
165
  }
141
166
  }
142
167
  /**
@@ -1,4 +1,4 @@
1
- import type { StyleTokens, ThemeToken } from '../core/types.js';
1
+ import type { SiteClass, StyleTokens, ThemeToken } from '../core/types.js';
2
2
  import type { TailwindPlugins } from './index.js';
3
3
  import { type CanvasCssData } from './shared.js';
4
4
  type ThemeEntry = {
@@ -24,9 +24,12 @@ export declare function resolveFontValue(value: string, families: FontFamilies,
24
24
  */
25
25
  export declare function applyFontFamilies(fonts: ThemeToken[], families: FontFamilies): ThemeToken[];
26
26
  /**
27
- * Builds StyleTokens from a recorded CSS input. Uses the design system API; if it is missing or
28
- * throws, logs a warning and parses the @theme blocks instead (no class list in that case).
27
+ * The site's own static `@utility` classes, in CSS order: the entry first, then the stylesheets it
28
+ * imports, without the ones from packages (`node_modules`). A comment right above a rule like
29
+ * `/* @canvas Buttons: Primary button *\/` gives its group and label; `/* @canvas Primary button *\/`
30
+ * a label only. A name defined twice is listed once.
29
31
  */
32
+ export declare function parseSiteClasses(data: CanvasCssData): SiteClass[];
30
33
  export declare function buildStyleTokens(data: CanvasCssData, plugins?: TailwindPlugins): Promise<{
31
34
  tokens: StyleTokens;
32
35
  source: TokensSource;
@@ -263,15 +263,61 @@ export function applyFontFamilies(fonts, families) {
263
263
  * Builds StyleTokens from a recorded CSS input. Uses the design system API; if it is missing or
264
264
  * throws, logs a warning and parses the @theme blocks instead (no class list in that case).
265
265
  */
266
+ /**
267
+ * `@utility name {` with an optional comment right above it. Only static names: `tab-*` (a
268
+ * functional utility) has no single class to offer. The comment may not hold `*\/`, so two
269
+ * comments in a row never merge: only the last one, right above the rule, counts.
270
+ */
271
+ const UTILITY_RULE = /(?:\/\*((?:(?!\*\/)[^])*)\*\/\s*)?@utility\s+([A-Za-z_][\w-]*)\s*\{/g;
272
+ const CANVAS_LABEL = /^\s*@canvas\s+(?:([^:]+?)\s*:\s*)?(.+?)\s*$/s;
273
+ const PREVIEW_LENGTH = 160;
274
+ /** The body of the rule whose `{` is at `open`: up to its matching `}`. */
275
+ function ruleBody(css, open) {
276
+ let depth = 0;
277
+ for (let i = open; i < css.length; i++) {
278
+ if (css[i] === '{')
279
+ depth++;
280
+ else if (css[i] === '}' && --depth === 0)
281
+ return css.slice(open + 1, i);
282
+ }
283
+ return css.slice(open + 1);
284
+ }
285
+ /**
286
+ * The site's own static `@utility` classes, in CSS order: the entry first, then the stylesheets it
287
+ * imports, without the ones from packages (`node_modules`). A comment right above a rule like
288
+ * `/* @canvas Buttons: Primary button *\/` gives its group and label; `/* @canvas Primary button *\/`
289
+ * a label only. A name defined twice is listed once.
290
+ */
291
+ export function parseSiteClasses(data) {
292
+ const sources = [data.entry, ...Object.values(data.stylesheets).filter((sheet) => !/(^|\/)node_modules\//.test(sheet.path)).map((sheet) => sheet.content)];
293
+ const out = new Map();
294
+ for (const css of sources) {
295
+ for (const match of css.matchAll(UTILITY_RULE)) {
296
+ const [whole, comment, name] = match;
297
+ if (!name || out.has(name))
298
+ continue;
299
+ const body = ruleBody(css, (match.index ?? 0) + whole.length - 1);
300
+ const preview = body.replace(/\/\*[^]*?\*\//g, '').replace(/\s+/g, ' ').trim();
301
+ const entry = { name, css: preview.length > PREVIEW_LENGTH ? `${preview.slice(0, PREVIEW_LENGTH - 1)}…` : preview };
302
+ const label = comment ? CANVAS_LABEL.exec(comment) : null;
303
+ if (label?.[2])
304
+ entry.label = label[2];
305
+ if (label?.[1])
306
+ entry.group = label[1];
307
+ out.set(name, entry);
308
+ }
309
+ }
310
+ return [...out.values()];
311
+ }
266
312
  export async function buildStyleTokens(data, plugins) {
267
313
  try {
268
314
  const ds = await loadDesignSystem(data, plugins);
269
315
  const classList = [...new Set(ds.getClassList().map((entry) => entry[0]))];
270
- return { tokens: tokensFromTheme(ds.theme.entries(), classList), source: 'design-system' };
316
+ return { tokens: { ...tokensFromTheme(ds.theme.entries(), classList), siteClasses: parseSiteClasses(data) }, source: 'design-system' };
271
317
  }
272
318
  catch (error) {
273
319
  console.warn(`[websiteBuilder] Tailwind's design system API failed, so style tokens come from parsing @theme ` +
274
320
  `(no class list for autocomplete). Cause: ${error instanceof Error ? error.message : String(error)}`);
275
- return { tokens: tokensFromTheme(parseThemeEntries(data), null), source: 'theme-parse' };
321
+ return { tokens: { ...tokensFromTheme(parseThemeEntries(data), null), siteClasses: parseSiteClasses(data) }, source: 'theme-parse' };
276
322
  }
277
323
  }
package/dist/index.d.ts CHANGED
@@ -2,14 +2,14 @@ export { websiteBuilder, cssFieldName, BUILDER_VIEW_KEY, BUILDER_VIEW_PATH, type
2
2
  export { bindingSources, templatesConfigOf, TEMPLATES_CONFIG_KEY } from './plugin/templates.js';
3
3
  export { backfillReferences, DEFAULT_REFERENCES_FIELD, findReferrers, FORCE_DELETE_CONTEXT, referencesConfigOf, REFERENCES_CONFIG_KEY, type BackfillResult, type ReferencesOptions, type ReferencesServerConfig, type Referrer, } from './plugin/references.js';
4
4
  export { builderViewPath } from './plugin/links.js';
5
- export { DEFAULT_TEMPLATES_SLUG, DOCUMENT_TEMPLATE_FIELD, TEMPLATE_DEFAULT_FIELD, TEMPLATE_LAYOUT_FIELD, TEMPLATE_PREVIEW_FIELD, TEMPLATE_TARGET_FIELD, } from './core/bindings.js';
5
+ export { DEFAULT_TEMPLATES_SLUG, DOCUMENT_TEMPLATE_FIELD, TEMPLATE_CONDITIONS_FIELD, TEMPLATE_DEFAULT_FIELD, TEMPLATE_LAYOUT_FIELD, TEMPLATE_PREVIEW_FIELD, TEMPLATE_TARGET_FIELD, } from './core/bindings.js';
6
6
  export { defaultBlocks, fromPayloadBlocks, type DefaultBlocksOptions, type FromPayloadBlocksOptions, type PayloadBlockOverride } from './blocks/index.js';
7
7
  export { convertPayloadBlocksLayout, type PayloadConversion, type PayloadConversionReport } from './core/convertPayload.js';
8
8
  export { decodePayloadBlocks, encodePayloadBlocks, payloadBlocksProblems, payloadBlocksStorage, type PayloadBlocksDecode, type PayloadBlocksStorage, } from './core/payloadBlocks.js';
9
9
  export { formatMigrationReport, migrateBlocksField, type MigrateBlocksOptions, type MigrateBlocksReport, type MigrateCounts, type MigrateIssue, } from './migrate/index.js';
10
10
  export type { AiAdapter, AiChatRequest, AiClientConfig, AiMessage, AiOptions, AiStreamEvent } from './ai/types.js';
11
- export { defineBlock } from './core/blocks.js';
11
+ export { defineBlock, defineSection, type SectionBlockInput, type SectionInput, sectionsWithVariants, withDefaultClassNames, withInlineBlocks } from './core/blocks.js';
12
12
  export { EMPTY_LAYOUT } from './core/types.js';
13
- export type { BindingField, Block, BlockDefinition, BuilderClientConfig, DragMode, EditorOptions, Layout, SectionDefinition, TemplateContext, TemplatesClientConfig, } from './core/types.js';
13
+ export type { BindingField, Block, BlockDefinition, BuilderClientConfig, DragMode, EditorOptions, Layout, SectionDefinition, SectionVariant, TemplateContext, TemplatesClientConfig, } from './core/types.js';
14
14
  export type { ThemeOptions } from './theme/config.js';
15
15
  export { DEFAULT_THEME_SLUG } from './theme/config.js';
package/dist/index.js CHANGED
@@ -3,11 +3,11 @@ export { websiteBuilder, cssFieldName, BUILDER_VIEW_KEY, BUILDER_VIEW_PATH, SITE
3
3
  export { bindingSources, templatesConfigOf, TEMPLATES_CONFIG_KEY } from './plugin/templates.js';
4
4
  export { backfillReferences, DEFAULT_REFERENCES_FIELD, findReferrers, FORCE_DELETE_CONTEXT, referencesConfigOf, REFERENCES_CONFIG_KEY, } from './plugin/references.js';
5
5
  export { builderViewPath } from './plugin/links.js';
6
- export { DEFAULT_TEMPLATES_SLUG, DOCUMENT_TEMPLATE_FIELD, TEMPLATE_DEFAULT_FIELD, TEMPLATE_LAYOUT_FIELD, TEMPLATE_PREVIEW_FIELD, TEMPLATE_TARGET_FIELD, } from './core/bindings.js';
6
+ export { DEFAULT_TEMPLATES_SLUG, DOCUMENT_TEMPLATE_FIELD, TEMPLATE_CONDITIONS_FIELD, TEMPLATE_DEFAULT_FIELD, TEMPLATE_LAYOUT_FIELD, TEMPLATE_PREVIEW_FIELD, TEMPLATE_TARGET_FIELD, } from './core/bindings.js';
7
7
  export { defaultBlocks, fromPayloadBlocks } from './blocks/index.js';
8
8
  export { convertPayloadBlocksLayout } from './core/convertPayload.js';
9
9
  export { decodePayloadBlocks, encodePayloadBlocks, payloadBlocksProblems, payloadBlocksStorage, } from './core/payloadBlocks.js';
10
10
  export { formatMigrationReport, migrateBlocksField, } from './migrate/index.js';
11
- export { defineBlock } from './core/blocks.js';
11
+ export { defineBlock, defineSection, sectionsWithVariants, withDefaultClassNames, withInlineBlocks } from './core/blocks.js';
12
12
  export { EMPTY_LAYOUT } from './core/types.js';
13
13
  export { DEFAULT_THEME_SLUG } from './theme/config.js';
@@ -33,6 +33,8 @@ export type BuilderMcpToolsOptions = {
33
33
  sections?: SectionDefinition[];
34
34
  /** The same collections map as `websiteBuilder({ collections })`. */
35
35
  collections: Record<string, BuilderMcpCollection>;
36
+ /** The same `listCollections` as `websiteBuilder`: more collections the collection list block can show. */
37
+ listCollections?: string[];
36
38
  /** Absolute site URL for `getPreviewUrl`. Default: Payload `serverURL`, then NEXT_PUBLIC_SERVER_URL, then the request origin. */
37
39
  siteUrl?: string;
38
40
  /** Slug of payload-mcp-toolkit's API-keys collection, used to show the key name in the editor. */
package/dist/mcp/index.js CHANGED
@@ -8,10 +8,10 @@
8
8
  // `overrideAccess: false`. Writes are commits to the document's live session, the same path as
9
9
  // the editor's own edits, so AI changes merge with people's edits as they happen.
10
10
  import { z } from 'zod';
11
- import { COLLECTION_LIST_BLOCK, DEFAULT_TEMPLATES_SLUG, FIELD_BLOCK, TEMPLATE_DEFAULT_FIELD, TEMPLATE_LAYOUT_FIELD, TEMPLATE_PREVIEW_FIELD, TEMPLATE_TARGET_FIELD, withoutBoundRequired, } from '../core/bindings.js';
11
+ import { COLLECTION_LIST_BLOCK, REPEAT_BLOCK, DEFAULT_TEMPLATES_SLUG, FIELD_BLOCK, TEMPLATE_CONDITIONS_FIELD, TEMPLATE_DEFAULT_FIELD, TEMPLATE_LAYOUT_FIELD, TEMPLATE_PREVIEW_FIELD, TEMPLATE_TARGET_FIELD, templateConditions, withoutBoundRequired, } from '../core/bindings.js';
12
12
  import { createId } from '../core/ids.js';
13
13
  import { blockJsonSchema } from '../core/schema.js';
14
- import { getBlockDefinition } from '../core/blocks.js';
14
+ import { getBlockDefinition, sectionsWithDefaultClassNames, sectionsWithVariants } from '../core/blocks.js';
15
15
  import { localeSettingsOf, localizedKeys, resolveLayoutLocale, stampLocale, untranslatedKeys } from '../core/locale.js';
16
16
  import { normalizeLayout, subtreeIds, walkBlocks } from '../core/tree.js';
17
17
  import { runPropValidators } from '../core/fieldValidate.js';
@@ -24,7 +24,9 @@ import { blocksAccessProblem, codecOf, withBlocksReadCheck } from '../live/stora
24
24
  import { liveRuntimeOf } from '../live/runtime.js';
25
25
  import { storedLayout } from '../plugin/hook.js';
26
26
  import { builderViewPath, documentPath, draftPreviewPath } from '../plugin/links.js';
27
- import { listCollectionsOf } from '../plugin/listCollections.js';
27
+ import { siteCssConfigOf } from '../plugin/index.js';
28
+ import { listableCollections, prepareBlocks } from '../plugin/listCollections.js';
29
+ import { getStyleTokens } from '../css/index.js';
28
30
  import { findSection, loadSavedSections, savedSectionsConfigOf } from '../plugin/sections.js';
29
31
  import { templatesConfigOf } from '../plugin/templates.js';
30
32
  import { generateImageToMedia, imageServiceOf } from '../ai/images/service.js';
@@ -44,6 +46,13 @@ const NO_DIRECT_EDIT = 'Do not change the layout field with updateDocument or pa
44
46
  */
45
47
  const motionArg = z.record(z.string(), z.unknown());
46
48
  const MOTION_HINT = 'Animations: { enter?, hover?, press?, scroll?, loop? }, each kind { preset, ...options }, e.g. { "enter": { "preset": "fade-up" } } (see MOTION in the layout guide).';
49
+ const attrsArg = z
50
+ .object({
51
+ id: z.string().nullable().optional().describe('The element id, for "#id" links. Unique in the layout. Letters, digits, - and _, starting with a letter.'),
52
+ ariaLabel: z.string().nullable().optional().describe('aria-label: the name screen readers read.'),
53
+ ariaHidden: z.boolean().nullable().optional().describe('true: aria-hidden, screen readers skip the block (decorative shapes, repeated links).'),
54
+ })
55
+ .describe('HTML attributes of the block element.');
47
56
  const positionSchema = z
48
57
  .object({
49
58
  parentId: z.string().nullable().describe('Id of the parent block, or null for the page root.'),
@@ -62,6 +71,8 @@ const blockSchema = z
62
71
  hidden: z.boolean().optional(),
63
72
  label: z.string().optional().describe('Name for editors, shown in the outline (e.g. "Hero"). Never rendered. Give each top-level section one.'),
64
73
  motion: motionArg.optional().describe(MOTION_HINT),
74
+ attrs: attrsArg.optional(),
75
+ slotClassName: z.record(z.string(), z.string()).optional().describe('Tailwind classes of a slot\'s own element, by slot name. Only slots marked "classes" in listBlocks take them.'),
65
76
  })
66
77
  .passthrough();
67
78
  const operationSchema = z.discriminatedUnion('type', [
@@ -92,6 +103,11 @@ const operationSchema = z.discriminatedUnion('type', [
92
103
  .nullable()
93
104
  .optional()
94
105
  .describe(`${MOTION_HINT} Merges per kind: a kind you send replaces that kind, null removes a kind, kinds you leave out stay. null removes all motion.`),
106
+ attrs: attrsArg.nullable().optional().describe('HTML attributes. A key replaces that key, null removes it. null removes all.'),
107
+ slotClassName: z
108
+ .record(z.string(), z.string().nullable())
109
+ .optional()
110
+ .describe('Classes of a slot\'s own element, by slot name. Each slot given replaces its classes; null removes them.'),
95
111
  locale: z
96
112
  .string()
97
113
  .optional()
@@ -171,13 +187,30 @@ async function loadDraft(req, collection, id) {
171
187
  // ---------------------------------------------------------------------------
172
188
  // Tools
173
189
  // ---------------------------------------------------------------------------
190
+ /** The site's own `@utility` classes for `listBlocks`, or nothing without the plugin's CSS config. */
191
+ async function siteClassesOf(req) {
192
+ const site = req?.payload?.config ? siteCssConfigOf(req.payload) : null;
193
+ if (!site)
194
+ return {};
195
+ const list = await getStyleTokens(site.css)
196
+ .then((tokens) => tokens.siteClasses ?? [])
197
+ .catch(() => []);
198
+ if (list.length === 0)
199
+ return {};
200
+ return {
201
+ siteClasses: list.map(({ name, label, group }) => ({ name, ...(label ? { label } : {}), ...(group ? { group } : {}) })),
202
+ siteClassesNote: "The site's own classes (its look: type styles, buttons, cards, surfaces). Prefer them in className over rebuilding the same look from utilities.",
203
+ };
204
+ }
174
205
  export function builderMcpTools(options) {
175
- const { sections = [] } = options;
176
206
  const templateTargets = Object.entries(options.collections).filter(([, c]) => c.templates).map(([slug]) => slug);
177
207
  const templatesSlug = templateTargets.length > 0 ? (options.templates?.slug ?? DEFAULT_TEMPLATES_SLUG) : null;
178
- const listable = Object.entries(options.collections).filter(([, c]) => c.url).map(([slug]) => slug);
179
- // The same block list the plugin validates against (collection list: only collections with a url).
180
- const blocks = listCollectionsOf(options.blocks, listable);
208
+ const listable = listableCollections(options.collections, options.listCollections);
209
+ // The same block list the plugin validates against (collection list: the collections with a url and `listCollections`).
210
+ const blocks = prepareBlocks(options.blocks, listable);
211
+ // A section block without a className gets its type's default classes, as in the plugin.
212
+ // Each variant is a section of its own (`<id>/<variant id>`).
213
+ const sections = sectionsWithDefaultClassNames(sectionsWithVariants(options.sections ?? []), blocks);
181
214
  const collections = templatesSlug
182
215
  ? { ...options.collections, [templatesSlug]: { field: TEMPLATE_LAYOUT_FIELD } }
183
216
  : options.collections;
@@ -306,12 +339,13 @@ export function builderMcpTools(options) {
306
339
  description: [
307
340
  'Lists every block type you can use in page layouts: label, description, props, slots (which child types they accept) and an example. Call this before you build or edit a layout.',
308
341
  'To build whole page parts (hero, features, pricing, call to action, footer), PREFER ready-made sections: listSections, then insertSection. They are designed and tested. Use single blocks for small additions and edits.',
309
- `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. Blocks inside a template or a list item can bind props to document fields with "bindings" (see getBindingSources).`,
342
+ `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. Blocks inside a template or a list item can bind props to document fields with "bindings" (see getBindingSources).`,
310
343
  LAYOUT_GUIDE,
311
344
  ].join('\n\n'),
312
345
  parameters: { collection: collectionArg },
313
- handler: async () => text({
346
+ handler: async (_args, req) => text({
314
347
  blocks: blocks.map(describeBlock),
348
+ ...(await siteClassesOf(req)),
315
349
  sections: sections.length,
316
350
  bindings: BINDINGS_GUIDE,
317
351
  ...(templatesSlug ? { templates: { collection: templatesSlug, targets: templateTargets } } : {}),
@@ -336,6 +370,7 @@ export function builderMcpTools(options) {
336
370
  routing: { kind: 'collection', action: 'read' },
337
371
  description: [
338
372
  'Lists ready-made sections (heroes, features, testimonials, calls to action, contact, footers, …) with an outline of their blocks. Sections are the best way to build a page: insert them with insertSection, then change their text, images and classes with applyOperations "update". Set `full: true` to get the complete block JSON of each section.',
373
+ 'A section can come in variants (other versions of the same section): they follow it in the list with an id like "hero/split" and `variantOf: "hero"`. Pick the version that fits the page.',
339
374
  'The list also has the sections people saved on this site. They have `saved: true` and an id like "saved:12".',
340
375
  ].join('\n'),
341
376
  parameters: {
@@ -352,6 +387,7 @@ export function builderMcpTools(options) {
352
387
  id: s.id,
353
388
  label: s.label,
354
389
  ...(s.savedId !== undefined ? { saved: true } : {}),
390
+ ...(s.variantOf ? { variantOf: s.variantOf } : {}),
355
391
  ...(s.category ? { category: s.category } : {}),
356
392
  ...(s.description ? { description: s.description } : {}),
357
393
  ...(args.full ? { blocks: s.blocks } : { outline: outline(s.blocks).join('\n') }),
@@ -373,7 +409,7 @@ export function builderMcpTools(options) {
373
409
  sectionId: z
374
410
  .string()
375
411
  .min(1)
376
- .describe('The section from listSections: its id (e.g. "hero" or "saved:12") or its exact name.'),
412
+ .describe('The section from listSections: its id (e.g. "hero", the variant "hero/split" or "saved:12") or its exact name.'),
377
413
  parentId: z.string().nullable().optional().describe('Parent block id. Default null (page root).'),
378
414
  slot: z.string().optional().describe('Slot of the parent. Default "children".'),
379
415
  index: z.number().int().min(0).optional().describe('Final index in the target list. Default: append.'),
@@ -468,7 +504,7 @@ export function builderMcpTools(options) {
468
504
  routing: { kind: 'collection', action: 'update' },
469
505
  description: [
470
506
  'Edits the layout of a document with a list of operations, applied in order, all or nothing. Saves a draft about a second later (never publishes). People with the page open in the editor see each change live.',
471
- 'Operations: insert { block, to }, move { id, to }, remove { id }, duplicate { id, newId? }, update { id, props?, unsetProps?, className?, hidden?, bindings?, label?, motion? }. "update" merges props and bindings; className REPLACES all classes, so send the full list. `motion` (animations, see MOTION below) merges per kind: a kind replaces that kind, null removes it, null alone removes all.',
507
+ 'Operations: insert { block, to }, move { id, to }, remove { id }, duplicate { id, newId? }, update { id, props?, unsetProps?, className?, hidden?, bindings?, label?, motion?, attrs?, slotClassName? }. "update" merges props and bindings; className REPLACES all classes, so send the full list. `motion` (animations, see MOTION below) merges per kind: a kind replaces that kind, null removes it, null alone removes all. `attrs` (HTML id, ariaLabel, ariaHidden) merges per key; null removes a key. `slotClassName` merges per slot; null removes the classes of a slot.',
472
508
  'Templates are edited the same way: collection = the templates collection, id = the template id from listTemplates.',
473
509
  'If any operation fails, nothing is saved and the error names the failing operation. Call getLayout for current ids first. The result is validated against the block schemas: missing required props are allowed in drafts (warnings), wrong types are errors. insert and move refuse a block that a slot does not accept, also deeper inside (for example no button or form anywhere inside a link). insert, move and duplicate refuse to add a block to a slot that already holds its maxBlocks (listBlocks).',
474
510
  'Localized sites: with `locale`, "update" props change that locale\'s values of localized props (a translation); other props and everything else (insert, move, remove, classes) change every locale. Blocks you insert with `locale` hold their localized props in that locale only: the default locale stays empty until someone writes it (required props then block publishing). Without `locale` they hold the default locale\'s values. Sections (insertSection) keep their own text.',
@@ -653,8 +689,8 @@ export function builderMcpTools(options) {
653
689
  name: 'listTemplates',
654
690
  routing: { kind: 'collection', action: 'read' },
655
691
  description: [
656
- `Lists the templates: layouts that render every document of a collection (${templateTargets.join(', ')}). A document uses its own template (its "template" field), else its collection's default template.`,
657
- `To edit a template, call getLayout and applyOperations with collection "${templatesSlug}" and the template id. Bind props to the document's fields with "bindings" (getBindingSources lists the fields). To create a template, use createDocument on "${templatesSlug}" with { name, ${TEMPLATE_TARGET_FIELD}, ${TEMPLATE_DEFAULT_FIELD} }.`,
692
+ `Lists the templates: layouts that render every document of a collection (${templateTargets.join(', ')}). A document uses its own template (its "template" field), else the first published template (by name) whose "${TEMPLATE_CONDITIONS_FIELD}" (a Payload where query against the document, e.g. { "tier": { "equals": "vip" } }) match it, else its collection's default template.`,
693
+ `To edit a template, call getLayout and applyOperations with collection "${templatesSlug}" and the template id. Bind props to the document's fields with "bindings" (getBindingSources lists the fields). To create a template, use createDocument on "${templatesSlug}" with { name, ${TEMPLATE_TARGET_FIELD}, ${TEMPLATE_DEFAULT_FIELD} } and optional ${TEMPLATE_CONDITIONS_FIELD}.`,
658
694
  ].join('\n'),
659
695
  parameters: {
660
696
  collection: z.enum([templatesSlug]).describe(`Always "${templatesSlug}".`),
@@ -680,6 +716,7 @@ export function builderMcpTools(options) {
680
716
  name: doc.name,
681
717
  target: doc[TEMPLATE_TARGET_FIELD],
682
718
  isDefault: doc[TEMPLATE_DEFAULT_FIELD] === true,
719
+ ...(templateConditions(doc) ? { conditions: templateConditions(doc) } : {}),
683
720
  ...(doc[TEMPLATE_PREVIEW_FIELD] ? { previewDocument: doc[TEMPLATE_PREVIEW_FIELD] } : {}),
684
721
  ...(doc._status ? { status: doc._status } : {}),
685
722
  blocks: normalizeLayout(doc[TEMPLATE_LAYOUT_FIELD]).blocks.length,
@@ -53,6 +53,7 @@ export declare function describeBlock(def: BlockDefinition): {
53
53
  hasMany?: boolean | undefined;
54
54
  options?: string[] | undefined;
55
55
  relationTo?: string | string[] | undefined;
56
+ holds?: string | undefined;
56
57
  }[];
57
58
  slots: {
58
59
  [k: string]: {
@@ -60,6 +61,7 @@ export declare function describeBlock(def: BlockDefinition): {
60
61
  accepts: string | string[];
61
62
  minBlocks?: number | undefined;
62
63
  maxBlocks?: number | undefined;
64
+ classes?: string | undefined;
63
65
  };
64
66
  };
65
67
  onlyInside?: string[] | undefined;
@@ -78,6 +80,7 @@ export declare function describeBlock(def: BlockDefinition): {
78
80
  hasMany?: boolean | undefined;
79
81
  options?: string[] | undefined;
80
82
  relationTo?: string | string[] | undefined;
83
+ holds?: string | undefined;
81
84
  }[];
82
85
  slots: string;
83
86
  onlyInside?: string[] | undefined;