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
@@ -0,0 +1,27 @@
1
+ import type { Block, BlockAttrs, BlockAttrsPatch, Layout } from './types.js';
2
+ /** Why the text cannot be an HTML id, or null when it can. */
3
+ export declare function htmlIdProblem(id: string): string | null;
4
+ /**
5
+ * Checks stored or inserted `attrs` and returns them in canonical form: no blank strings, no
6
+ * `ariaHidden: false`, `undefined` when nothing is left. A string is the error message.
7
+ */
8
+ export declare function checkAttrs(value: unknown): BlockAttrs | undefined | string;
9
+ /**
10
+ * `attrs` after an update patch: each key given replaces that key, `null` (or "" / false) removes
11
+ * it, keys left out stay. `patch: null` removes all. Returns the result and the patch that undoes it.
12
+ */
13
+ export declare function patchAttrs(before: BlockAttrs | undefined, patch: BlockAttrsPatch | null): {
14
+ attrs: BlockAttrs | undefined;
15
+ inverse: BlockAttrsPatch | null;
16
+ } | string;
17
+ /** The HTML attributes of `attrs`, for a block's root element. */
18
+ export declare function htmlAttributes(attrs: BlockAttrs | undefined): Record<string, string>;
19
+ /** The HTML ids the blocks use (at any depth), each with the id of the block that has it. */
20
+ export declare function htmlIdsOf(blocks: readonly Block[], out?: Map<string, string>): Map<string, string>;
21
+ /** Why the block's subtree cannot join the layout: an HTML id it uses is taken. Null when none is. */
22
+ export declare function htmlIdClash(layout: Layout, block: Block): string | null;
23
+ /**
24
+ * The block with every HTML id that `taken` holds removed (at any depth), so a paste, a duplicate
25
+ * or a second copy of a section never repeats an anchor. Unchanged blocks stay the same objects.
26
+ */
27
+ export declare function withoutTakenHtmlIds(block: Block, taken: ReadonlySet<string> | ReadonlyMap<string, unknown>): Block;
@@ -0,0 +1,132 @@
1
+ // HTML attributes of a block (`Block.attrs`): an id for anchors, an ARIA label and aria-hidden.
2
+ // Pure: no React, no Payload. The renderer spreads them through `attributes`.
3
+ // Local: tree.ts imports this module (normalizeLayout), so it cannot import tree.ts back.
4
+ const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
5
+ /** Letters, digits, "-" and "_", starting with a letter: safe in `#anchor` links and CSS selectors. */
6
+ const HTML_ID = /^[A-Za-z][\w-]*$/;
7
+ /** Why the text cannot be an HTML id, or null when it can. */
8
+ export function htmlIdProblem(id) {
9
+ if (HTML_ID.test(id))
10
+ return null;
11
+ return 'An id starts with a letter and holds only letters, digits, "-" and "_".';
12
+ }
13
+ /**
14
+ * Checks stored or inserted `attrs` and returns them in canonical form: no blank strings, no
15
+ * `ariaHidden: false`, `undefined` when nothing is left. A string is the error message.
16
+ */
17
+ export function checkAttrs(value) {
18
+ if (value === undefined || value === null)
19
+ return undefined;
20
+ if (!isPlainObject(value))
21
+ return 'attrs must be an object';
22
+ const attrs = {};
23
+ for (const [key, raw] of Object.entries(value)) {
24
+ if (raw === undefined || raw === null)
25
+ continue;
26
+ if (key === 'id' || key === 'ariaLabel') {
27
+ if (typeof raw !== 'string')
28
+ return `attrs.${key} must be a string`;
29
+ if (!raw.trim())
30
+ continue;
31
+ if (key === 'id') {
32
+ const problem = htmlIdProblem(raw);
33
+ if (problem)
34
+ return `attrs.id "${raw}": ${problem}`;
35
+ }
36
+ // The label keeps its text as typed: trimming it here would eat the space someone just typed.
37
+ attrs[key] = raw;
38
+ }
39
+ else if (key === 'ariaHidden') {
40
+ if (typeof raw !== 'boolean')
41
+ return 'attrs.ariaHidden must be a boolean';
42
+ if (raw)
43
+ attrs.ariaHidden = true;
44
+ }
45
+ else {
46
+ return `Unknown attrs key "${key}". Use id, ariaLabel or ariaHidden.`;
47
+ }
48
+ }
49
+ return Object.keys(attrs).length > 0 ? attrs : undefined;
50
+ }
51
+ /**
52
+ * `attrs` after an update patch: each key given replaces that key, `null` (or "" / false) removes
53
+ * it, keys left out stay. `patch: null` removes all. Returns the result and the patch that undoes it.
54
+ */
55
+ export function patchAttrs(before, patch) {
56
+ if (patch === null)
57
+ return { attrs: undefined, inverse: before ? { ...before } : {} };
58
+ if (!isPlainObject(patch))
59
+ return '`attrs` must be an object or null';
60
+ const merged = { ...before };
61
+ const inverse = {};
62
+ for (const [key, value] of Object.entries(patch)) {
63
+ if (value === undefined)
64
+ continue;
65
+ inverse[key] = before?.[key] ?? null;
66
+ merged[key] = value;
67
+ }
68
+ const attrs = checkAttrs(merged);
69
+ if (typeof attrs === 'string')
70
+ return attrs;
71
+ return { attrs, inverse: inverse };
72
+ }
73
+ /** The HTML attributes of `attrs`, for a block's root element. */
74
+ export function htmlAttributes(attrs) {
75
+ if (!attrs)
76
+ return {};
77
+ const out = {};
78
+ if (attrs.id)
79
+ out.id = attrs.id;
80
+ if (attrs.ariaLabel)
81
+ out['aria-label'] = attrs.ariaLabel;
82
+ if (attrs.ariaHidden)
83
+ out['aria-hidden'] = 'true';
84
+ return out;
85
+ }
86
+ /** The HTML ids the blocks use (at any depth), each with the id of the block that has it. */
87
+ export function htmlIdsOf(blocks, out = new Map()) {
88
+ for (const block of blocks) {
89
+ if (block.attrs?.id && !out.has(block.attrs.id))
90
+ out.set(block.attrs.id, block.id);
91
+ for (const children of Object.values(block.slots ?? {}))
92
+ htmlIdsOf(children, out);
93
+ }
94
+ return out;
95
+ }
96
+ /** Why the block's subtree cannot join the layout: an HTML id it uses is taken. Null when none is. */
97
+ export function htmlIdClash(layout, block) {
98
+ const taken = htmlIdsOf(layout.blocks);
99
+ for (const [id] of htmlIdsOf([block])) {
100
+ if (taken.has(id))
101
+ return `The HTML id "${id}" is already used by block "${taken.get(id)}". Every id is unique in a layout.`;
102
+ }
103
+ return null;
104
+ }
105
+ /**
106
+ * The block with every HTML id that `taken` holds removed (at any depth), so a paste, a duplicate
107
+ * or a second copy of a section never repeats an anchor. Unchanged blocks stay the same objects.
108
+ */
109
+ export function withoutTakenHtmlIds(block, taken) {
110
+ let next = block;
111
+ if (block.attrs?.id && taken.has(block.attrs.id)) {
112
+ const { id: _id, ...rest } = block.attrs;
113
+ next = { ...block };
114
+ if (Object.keys(rest).length > 0)
115
+ next.attrs = rest;
116
+ else
117
+ delete next.attrs;
118
+ }
119
+ if (!block.slots)
120
+ return next;
121
+ let changed = false;
122
+ const slots = {};
123
+ for (const [name, children] of Object.entries(block.slots)) {
124
+ slots[name] = children.map((child) => {
125
+ const copy = withoutTakenHtmlIds(child, taken);
126
+ if (copy !== child)
127
+ changed = true;
128
+ return copy;
129
+ });
130
+ }
131
+ return changed ? { ...next, slots } : next;
132
+ }
@@ -1,5 +1,5 @@
1
1
  import { type DataField } from './fields.js';
2
- import type { Block, BindingField, BlockDefinition, Layout, TemplateContext } from './types.js';
2
+ import type { Block, BindingField, BlockDefinition, BlockProps, Layout, TemplateContext } from './types.js';
3
3
  import type { LayoutError } from './validate.js';
4
4
  /** Default slug of the templates collection. */
5
5
  export declare const DEFAULT_TEMPLATES_SLUG = "builder-templates";
@@ -11,8 +11,19 @@ export declare const TEMPLATE_DEFAULT_FIELD = "isDefault";
11
11
  export declare const TEMPLATE_PREVIEW_FIELD = "previewDocument";
12
12
  /** Templates collection: the layout field. */
13
13
  export declare const TEMPLATE_LAYOUT_FIELD = "layout";
14
+ /**
15
+ * Templates collection: an optional Payload `where` query against the document. A document
16
+ * without a template of its own uses the first published template (by name) whose conditions
17
+ * match it, before the default template.
18
+ */
19
+ export declare const TEMPLATE_CONDITIONS_FIELD = "conditions";
14
20
  /** Template-enabled collections: the relationship to the document's own template. */
15
21
  export declare const DOCUMENT_TEMPLATE_FIELD = "template";
22
+ /**
23
+ * A template's conditions as a `where` query, or `null` when it has none: only a plain object
24
+ * with at least one key counts (an empty object would match every document).
25
+ */
26
+ export declare function templateConditions(template: Record<string, unknown> | null | undefined): Record<string, unknown> | null;
16
27
  /** Virtual binding path: the frontend URL of the context document (from the link resolver). */
17
28
  export declare const URL_PATH = "$url";
18
29
  /** The Field block: shows the context document's value at `props.path`. */
@@ -28,6 +39,30 @@ export declare const LIST_ITEM_SLOT = "item";
28
39
  export declare const LIST_ITEMS_PROP = "$items";
29
40
  /** Runtime-only prop of the Field block: the resolved value. It is never stored. */
30
41
  export declare const FIELD_VALUE_PROP = "value";
42
+ /**
43
+ * The repeat block: renders its `item` slot once per row of an array or hasMany field of the
44
+ * current document (`props.path`). The rows are its runtime-only `$items` prop.
45
+ */
46
+ export declare const REPEAT_BLOCK = "repeat";
47
+ /** Collection list slot shown when the list has no documents. */
48
+ export declare const LIST_EMPTY_SLOT = "empty";
49
+ /** The URL query parameter of a paginated list's page (`?page=3`). Filter links drop it. */
50
+ export declare const PAGE_PARAM = "page";
51
+ /** Virtual binding path inside a repeat item: the row value itself (a document, an upload, a text). */
52
+ export declare const ITEM_PATH = "$item";
53
+ /** Virtual binding path inside a collection list or repeat item: the item number, from 1. */
54
+ export declare const INDEX_PATH = "$index";
55
+ /** Virtual path prefix inside a collection list or repeat item: the enclosing document (`$parent.name`). */
56
+ export declare const PARENT_PATH = "$parent";
57
+ /** Virtual path prefix: the page's own document (`$page.title`), also inside list and repeat items. */
58
+ export declare const PAGE_PATH = "$page";
59
+ /**
60
+ * Binding key that shows or hides the block: `"field"` shows it when the field is filled,
61
+ * `"!field"` when it is empty, `"field=value"` when it equals the value, `"field!=value"` when not.
62
+ */
63
+ export declare const VISIBLE_BINDING = "$visible";
64
+ /** True for the slot that repeats per item: the `item` slot of a collection list or a repeat. */
65
+ export declare function isRepeatSlot(type: string, slot: string): boolean;
31
66
  type Doc = Record<string, unknown>;
32
67
  /**
33
68
  * The value at a dot path. Goes through objects, arrays (a non-numeric key collects the value of
@@ -35,6 +70,21 @@ type Doc = Record<string, unknown>;
35
70
  * relationship (an ID) ends the path with `undefined`.
36
71
  */
37
72
  export declare function getByPath(doc: unknown, path: string): unknown;
73
+ /**
74
+ * The rows of a repeat: the value at `props.path` in the context (an array field's rows, a hasMany
75
+ * field's documents, IDs or values; one value counts as one row), after `offset` and `limit`.
76
+ * The path may start with `$parent.` or `$page.`.
77
+ */
78
+ export declare function repeatRows(context: TemplateContext, props: BlockProps | undefined): unknown[];
79
+ /**
80
+ * The context one repeat row binds to: the row's own fields (an array row, or the related document
81
+ * of a relationship or upload), `$item` (the row value), `$index` (from 1), `$parent` (the
82
+ * enclosing document) and `$page`. `collection` is the related collection for `$url`; a
83
+ * `{ relationTo, value }` row names its own.
84
+ */
85
+ export declare function repeatRowContext(row: unknown, index: number, around: TemplateContext | null, collection?: string): TemplateContext;
86
+ /** The context of one collection list item (a listed document). */
87
+ export declare function listItemContext(doc: Doc, index: number, around: TemplateContext | null, collection: string): TemplateContext;
38
88
  /** True for values that count as "no value": the literal prop stays. */
39
89
  export declare function isMissing(value: unknown): boolean;
40
90
  /** Lexical editor state (rich text JSON). */
@@ -80,19 +130,62 @@ export type BindingOptions = {
80
130
  * resolver here. Without it, `$url` bindings stay unresolved.
81
131
  */
82
132
  url?: (context: TemplateContext) => string | null | undefined;
133
+ /**
134
+ * Which collection each relationship and upload field points to (`bindingRelations`), so
135
+ * `<path>.$url` (e.g. `categories.0.$url`) knows the related document's collection. A
136
+ * `{ relationTo, value }` value names its own collection without it.
137
+ */
138
+ relations?: BindingRelations;
83
139
  };
84
- /** The context document's value at a binding path (`$url` included). */
85
- export declare function bindingValue(context: TemplateContext, path: string, options?: BindingOptions): unknown;
140
+ /** Collection slug -> field path (no row numbers, e.g. "gallery.photo") -> the related collection. */
141
+ export type BindingRelations = Record<string, Record<string, string>>;
142
+ /**
143
+ * The related collection of every relationship and upload field with one `relationTo`, at any
144
+ * depth of groups, named tabs and arrays (blocks fields are left out). Plain JSON: pass it to
145
+ * `RenderLayout` and `loadLayoutData` as `relations`. The plugin sends it to the canvas itself.
146
+ */
147
+ export declare function bindingRelations(collections: ReadonlyArray<{
148
+ slug: string;
149
+ fields: readonly unknown[];
150
+ }>): BindingRelations;
151
+ /**
152
+ * Formatters for binding expressions (`price|currency:AUD`). Each takes a value that is not
153
+ * missing and returns text, or undefined when it cannot format the value.
154
+ */
155
+ export declare const BINDING_FORMATTERS: Record<string, (value: unknown, args: string[]) => string | undefined>;
156
+ /**
157
+ * A value through one formatter, written as in a binding: "currency:AUD", "date:en-AU:Australia/Brisbane",
158
+ * "number" or "firstSentence". Undefined for an unknown formatter, a missing value or a value the
159
+ * formatter cannot read. The field block's `format` prop uses it.
160
+ */
161
+ export declare function formatBindingValue(value: unknown, format: string): string | undefined;
162
+ /** True when a binding is more than one plain path: a template string, a fallback chain or a formatter. */
163
+ export declare function isBindingExpression(binding: string): boolean;
164
+ /**
165
+ * The value of a binding:
166
+ * - a path: `title`, `author.name`, or a virtual path (`$url`, `$item`, `$index`, `$parent.name`, `$page.title`);
167
+ * - a fallback chain: `heading|name` (the first value that is not missing);
168
+ * - formatters after the paths: `publishedAt|date:en-AU:Australia/Brisbane`, `price|currency:AUD`, `bio|firstSentence`;
169
+ * - a template string: `Enquire about {{name}}`. Each `{{expression}}` becomes text; a missing one
170
+ * becomes empty. When every one is missing, the value is missing (the literal prop stays).
171
+ */
172
+ export declare function bindingValue(context: TemplateContext, binding: string, options?: BindingOptions): unknown;
173
+ /** The plain field paths a binding reads (no formatters, no virtual `$url`, `$item`, `$index`). */
174
+ export declare function bindingPaths(key: string, binding: string): string[];
175
+ /** True when the `$visible` condition holds for the context. `false` counts as empty. */
176
+ export declare function isVisible(context: TemplateContext, condition: string, options?: BindingOptions): boolean;
86
177
  /**
87
178
  * Resolves one block's bindings (not its children). Bound props with a value take it; applied
88
- * bindings are removed from the result, unresolved ones stay. A Field block gets
89
- * `props.value`. Returns the same block when nothing changes.
179
+ * bindings are removed from the result, unresolved ones stay. A `$visible` binding that does not
180
+ * hold makes the block `hidden`. A Field block gets `props.value`, a repeat its rows (`$items`).
181
+ * Returns the same block when nothing changes.
90
182
  */
91
183
  export declare function resolveBlockBindings(block: Block, context: TemplateContext, definition: BlockDefinition | undefined, options?: BindingOptions): Block;
92
184
  /**
93
- * Resolves every block's bindings against the context document. The `item` slot of a collection
94
- * list is left alone: its blocks bind to each listed document at render time. Applied bindings are
95
- * removed, so resolving twice is safe. Never mutates.
185
+ * Resolves every block's bindings against the context document. Repeats get their rows
186
+ * (`$items`). The `item` slot of a collection list or a repeat is left alone: its blocks bind to
187
+ * each listed document or row at render time. Applied bindings are removed, so resolving twice
188
+ * is safe. Never mutates.
96
189
  */
97
190
  export declare function resolveBindings(layout: Layout, context: TemplateContext, blocks: readonly BlockDefinition[], options?: BindingOptions): Layout;
98
191
  /**
@@ -111,11 +204,29 @@ export declare function isUrlSource(source: Pick<BindingField, 'path' | 'type' |
111
204
  * - a one-line text prop (`text`) cannot show rich text.
112
205
  */
113
206
  export declare function bindingProblem(fields: readonly unknown[], propPath: string, source: BindingField): string | null;
207
+ /**
208
+ * The bindable fields inside a list block's `item` slot. A collection list: its collection's
209
+ * sources. A repeat: `$item`, `$index`, the row's fields (the related collection's sources for a
210
+ * relationship or upload to one collection, with `$url` only when the repeat's `collection` names
211
+ * it; else the field's children, an array row) and `$parent` (the fields around it). Both get
212
+ * `$page` (the page document's `page` fields) when given. `fields` are the sources around the
213
+ * block. Undefined when unknown.
214
+ */
215
+ export declare function itemSources(block: Block, fields: readonly BindingField[] | undefined, sources: Record<string, readonly BindingField[]>, page?: readonly BindingField[]): BindingField[] | undefined;
216
+ /** The collection lists and repeats whose `item` slot holds the block, outermost first. */
217
+ export declare function repeatAncestors(layout: Layout, id: string): Block[];
218
+ /**
219
+ * The bindable fields a block reads: the template collection's sources, narrowed by every
220
+ * collection list and repeat around it. Undefined when unknown (no collection, or a repeat path
221
+ * missing from the sources).
222
+ */
223
+ export declare function scopeSources(layout: Layout, id: string, sources: Record<string, readonly BindingField[]>, collection: string | null): BindingField[] | undefined;
114
224
  /**
115
225
  * Checks every binding against the bindable fields of the document it reads: the template's
116
- * target collection, or inside a collection list's `item` slot, the listed collection. Problems
117
- * have the code `binding` (they block publishing only). Paths missing from `sources` are left
118
- * alone: the renderer keeps the literal value.
226
+ * target collection, inside a collection list's `item` slot the listed collection, and inside a
227
+ * repeat's `item` slot the row (`itemSources`). Problems have the code `binding` (they block
228
+ * publishing only). Paths missing from `sources` are left alone: the renderer keeps the literal
229
+ * value. `$item`, `$index`, `$visible` and expressions are always allowed.
119
230
  */
120
231
  export declare function validateBindings(layout: Layout, blocks: readonly BlockDefinition[], sources: Record<string, readonly BindingField[]>, collection: string | null): LayoutError[];
121
232
  export {};